Razor2::Client::Agent(3pm)

NAME

Razor2::Client::Agent - Command-line interface for Vipul's Razor spam detection

SYNOPSIS

    use Razor2::Client::Agent;
    my $agent = Razor2::Client::Agent->new('razor-check');
    $agent->read_options() or $agent->raise_error;
    $agent->do_conf()      or $agent->raise_error;
    my $rc = $agent->doit({});
    exit $rc;

DESCRIPTION

Razor2::Client::Agent provides the user interface layer for Vipul's Razor, a distributed, collaborative spam detection and filtering network. It implements the command-line tools razor-check, razor-report, razor-revoke, and razor-admin.

This module inherits from Razor2::Client::Core (network protocol), Razor2::Client::Config (configuration management), Razor2::Logger (logging), and Razor2::String (utility functions).

Typical usage is through the command-line programs rather than calling this module directly. See razor-check(1), razor-report(1), razor-revoke(1), and razor-admin(1).

METHODS

new($breed)

Constructor. $breed is the full program name, which must end with one of "razor-check", "razor-report", "razor-revoke", or "razor-admin". The breed determines which operations are available.

Deletes $ENV{PATH} and $ENV{BASH_ENV} for taint safety.

read_options($agent): Parses command-line options via Getopt::Long. Returns true on success, false on error (error message available via errstr()).

do_conf(): Processes configuration: resolves razorhome, reads the config file, sets up logging, and creates the home directory if "-create" was specified. Must be called after read_options().

doit($args)

Main dispatcher. Calls the appropriate handler based on the breed: checkit() for check, adminit() for admin, reportit() for report and revoke.

Returns 0 for match (spam), 1 for no match (not spam), or 2 for error.

checkit($args)

Checks mail against the Razor catalogue servers. Accepts input as filenames, mbox files, signatures on the command line, or a filehandle in $args.

Return values: 0 = spam detected, 1 = not spam, 2 = error.

reportit($args)

Reports mail as spam (or revokes a previous report). Requires a valid Razor identity; attempts automatic registration if none is found. Backgrounds itself unless "-f" (foreground) is specified.

Return values: 0 = success, 2 = error.

adminit($args)

Handles administrative tasks: creating razorhome ("-create"), server discovery ("-discover"), and identity registration ("-register").

Return values: 0 = success, 2 = error.

parse_mbox($args)

Parses input into individual mail messages. Supports mbox format (splitting on "^From " lines), single RFC 822 messages, filehandle input (via "$args->{fh}"), and array reference input (via "$args->{aref}").

Returns an array reference of scalar references to mail content.

local_check($obj): Performs local whitelist and mailing-list checks. Returns true if the mail should be skipped (not checked against the server).

read_whitelist(): Loads the whitelist file specified in the configuration. The whitelist maps header names to patterns; matching mail is skipped.

get_server_info(): Reads server lists, loads cached server configurations, and resolves the next server to connect to. Called before network operations.

raise_error($errstr): Prints a fatal error message and exits with the Razor error code extracted from the message, or 255 if no code is found.

log($level, $msg): Logs a message at the given debug level. Uses the Razor2::Logger instance if available, otherwise prints to STDOUT in debug mode.

logll($loglevel): Returns true if the current debug level is at or above $loglevel. Use this to guard expensive log message construction.

CONFIGURATION

See razor-agent.conf(5) for configuration file format and options.

The razorhome directory (default ~/.razor/, system-wide /etc/razor/) stores configuration files, server lists, identity files, and logs.

AUTHORS

Vipul Ved Prakash, <[email protected]>

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.