ClamAV::Client: A client class for the clamav "clamd" virus scanner daemon

VERSION

0.11

SYNOPSIS

Creating a scanner client

    use ClamAV::Client;

    # Try using socket options from clamd.conf, or use default socket:
    my $scanner = ClamAV::Client->new();

    # Use a local Unix domain socket:
    my $scanner = ClamAV::Client->new(
        socket_name     => '/var/run/clamav/clamd.ctl'
    );

    # Use a TCP socket:
    my $scanner = ClamAV::Client->new(
        socket_host     => '127.0.0.1',
        socket_port     => 3310
    );

    die("ClamAV daemon not alive")
        if not defined($scanner) or not $scanner->ping();

Daemon maintenance

my $version = $scanner->version; # Retrieve the ClamAV version string.

$scanner->reload(); # Reload the malware pattern database.

$scanner->quit(); # Terminates the ClamAV daemon. $scanner->shutdown(); # Likewise.

Path scanning (lazy)

# Scan a single file or a whole directory structure, # and stop at the first infected file: my ($path, $result) = $scanner->scan_path($path); my ($path, $result) = $scanner->scan_path( $path, ClamAV::Client::SCAN_MODE_NORMAL ); my ($path, $result) = $scanner->scan_path( $path, ClamAV::Client::SCAN_MODE_RAW );

Path scanning (complete)

# Scan a single file or a whole directory structure, # and scan all files without stopping at the first infected one: my %results = $scanner->scan_path_complete($path); while (my ($path, $result) = each %results) { ... }

Other scanning methods

# Scan a stream, i.e. read from an I/O handle: my $result = $scanner->scan_stream($handle);

# Scan a scalar value: my $result = $scanner->scan_scalar(\$value);

DESCRIPTION

ClamAV::Client is a class acting as a client for a ClamAV \*(C`clamd\*(C' virus scanner daemon. The daemon may run locally or on a remote system as ClamAV::Client can use both Unix domain sockets and \s-1TCP/IP\s0 sockets. The full functionality of the \*(C`clamd\*(C' client/server protocol is supported.

Constructor

The following constructor is provided:

new(%options): \s-1RETURNS\s0 ClamAV::Client

Creates a new \*(C`ClamAV::Client\*(C' object. If no socket options are specified, first the socket options from the local \*(C`clamd.conf\*(C' configuration file are tried, then the Unix domain socket \*(C`/var/run/clamav/clamd.ctl\*(C' is tried, then finally the \s-1TCP/IP\s0 socket at 127.0.0.1 on port 3310 is tried. If either Unix domain or \s-1TCP/IP\s0 socket options are explicitly specified, only these are used. %options is a list of key/value pairs representing any of the following options:

socket_name: A scalar containing the absolute name of the local Unix domain socket. Defaults to '/var/run/clamav/clamd.ctl'.
socket_host: A scalar containing the name or \s-1IP\s0 address of the \s-1TCP/IP\s0 socket. Defaults to '127.0.0.1'.
socket_port: A scalar containing the port number of the \s-1TCP/IP\s0 socket. Defaults to 3310.

Instance methods

The following instance methods are provided:

Daemon maintenance

ping: \s-1RETURNS\s0 \s-1SCALAR\s0; \s-1THROWS\s0 ClamAV::Client::Error: Returns true ('\s-1PONG\s0') if the ClamAV daemon is alive. Throws a ClamAV::Client::Error exception otherwise.
version: \s-1RETURNS\s0 \s-1SCALAR\s0; \s-1THROWS\s0 ClamAV::Client::Error: Returns the version string of the ClamAV daemon.
reload: \s-1RETURNS\s0 \s-1SCALAR\s0; \s-1THROWS\s0 ClamAV::Client::Error: Instructs the ClamAV daemon to reload its malware database. Returns true if the reloading succeeds, or throws a ClamAV::Client::Error exception otherwise.
quit: \s-1RETURNS\s0 \s-1SCALAR\s0; \s-1THROWS\s0 ClamAV::Client::Error
shutdown: \s-1RETURNS\s0 \s-1SCALAR\s0; \s-1THROWS\s0 ClamAV::Client::Error: Terminates the ClamAV daemon. Returns true if the termination succeeds, or throws a ClamAV::Client::Error exception otherwise.
scan_path($path): \s-1RETURNS\s0 \s-1SCALAR\s0, \s-1SCALAR\s0; \s-1THROWS\s0 ClamAV::Client::Error: Scans a single file or a whole directory structure, and stops at the first infected file found. The specified path must be absolute. A scan mode may be specified: a mode of ClamAV::Client::SCAN_MODE_NORMAL (which is the default) causes a normal scan (\*(C`SCAN\*(C') with archive support enabled, a mode of ClamAV::Client::SCAN_MODE_RAW causes a raw scan with archive support disabled. If an infected file is found, returns a list consisting of the path of the file and the name of the malware signature that matched the file. Otherwise, returns the originally specified path and undef.
scan_path_complete($path): \s-1RETURNS\s0 \s-1HASH\s0; \s-1THROWS\s0 ClamAV::Client::Error: Scans a single file or a whole directory structure completely, not stopping at the first infected file found. The specified path must be absolute. Only the normal, non-raw mode is supported for complete scans by ClamAV. Returns a hash with a list of infected files found, with the file paths as the keys and the matched malware signature names as the values.
scan_stream($handle): \s-1RETURNS\s0 \s-1SCALAR\s0; \s-1THROWS\s0 ClamAV::Client::Error: Scans a stream, that is, reads from an I/O handle. If the stream is found to be infected, returns the name of the matching malware signature, undef otherwise.
scan_scalar(\$value): \s-1RETURNS\s0 \s-1SCALAR\s0; \s-1THROWS\s0 ClamAV::Client::Error: Scans the value referenced by the given scalarref. If the value is found to be infected, returns the name of the matching malware signature, undef otherwise.

RELATED TO ClamAV::Client…

The clamd and clamav man-pages.

AVAILABILITY and SUPPORT

The latest version of ClamAV::Client is available on \s-1CPAN\s0 and at http://www.mehnle.net/software/clamav-client <http://www.mehnle.net/software/clamav-client>.

Support is usually (but not guaranteed to be) given by the author, Julian Mehnle <[email protected]>.

AUTHOR and LICENSE

ClamAV::Client is free software. You may use, modify, and distribute it under the same terms as Perl itself, i.e. under the \s-1GNU\s0 \s-1GPL\s0 or the Artistic License.

ClamAV::Client (3pm)