NAME

Clamd - Connect to a local clamd service and send commands

SYNOPSIS

my $clamd = Clamd->new();
if ($clamd->ping) {
  my %found = $clamd->scan('/tmp');
  foreach my $file (keys %found) {
    print "Found virus: $found{$file} in $file\n";
  }
}

DESCRIPTION

This module provides a simplified perl interface onto a local clamd scanner, allowing you to do fast virus scans on files on your local hard drive. It also simplifies and unifies the clamd interface.

API

new()

Create a new Clamd object. By default tries to connect to a local unix domain socket at /tmp/clamd. Options are passed in as key/value pairs.

Available Options:

• port

  A port or socket to connect to if you do not wish to use the unix domain socket at /tmp/clamd. If the socket has been setup as a TCP/IP socket (see the TCPSocket option in the clamav.conf file), then specifying in a number will cause Clamd to use a TCP socket.

  Examples:

  my $clamd = Clamd->new(); # Default - uses /tmp/clamd socket
  
  # Use the unix domain socket at /var/sock/clam
  my $clamd = Clamd->new(port => '/var/sock/clam');
  
  # Use tcp/ip at port 3310
  my $clamd = Clamd->new(port => 3310);

  Note: there is no way to connect to a clamd on another machine. The reason for this is that clamd can only scan local files, so there would not be much point in doing this (unless you had NFS shares). Plus if you are using TCP/IP clamd appears to bind to all adaptors, so it is probably insecure.

• find_all

  By default clamd will stop at the first virus it detects. This is useful for performance, but sometimes you want to find all possible viruses in all of the files. To do that, specify a true value for find_all.

  Examples:

  # Stop at first virus
  my $clamd = Clamd->new();
  my ($file, $virus) = $clamd->scan('/home/bob');
  
  # Return all viruses
  my $clamd = Clamd->new(find_all => 1);
  my %caught = $clamd->scan('/home/bob');

ping()

Pings the clamd to check it is alive. Returns true if it is alive, false if it is dead. Note that it is still possible for a race condition to occur between your test for ping() and any call to scan(). See below for more details.

scan($dir_or_file)

Scan a directory or a file. Note that the resource must be readable by the user clamd is running as.

Returns a hash of filename => virusname mappings.

If we cannot connect to the clamd backend for any reason, an exception will be thrown.

If clamd encounters an error (for example it cannot read a file) then it will throw an exception. If you wish to continue in the presence of errors, you will need to pass an option to scan() as follows:

$clamd->scan($dir, { RaiseError => 0 });

rawscan($dir_or_file)

Same as scan(), but does not scan inside of archives.

quit()

Sends the QUIT message to clamd, causing it to cleanly exit.

This may or may not work, I think due to bugs in clamd's C code (it does not waitpid after a child exit, so you get zombies). However it seems to be fine on BSD derived operating systems (i.e. it's just broken under Linux).

The test file t/03quit.t will currently wait 5 seconds before trying a kill -9 to get rid of the process. You may have to do something similar on Linux, or just don't use this method to kill Clamd - use kill `cat /path/to/clamd.pid` instead which seems to work fine.

reload()

Cause clamd to reload its virus database.

AUTHOR

Matt Sergeant, All Rights Reserved.

LICENSE

This is free software. You may use and distribute it under the same terms as perl itself.