.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "Razor2::Client::Agent 3"
.TH Razor2::Client::Agent 3 2026-04-06 "perl v5.42.2" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
Razor2::Client::Agent \- Command\-line interface for Vipul\*(Aqs Razor spam detection
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\&    use Razor2::Client::Agent;
\&
\&    my $agent = Razor2::Client::Agent\->new(\*(Aqrazor\-check\*(Aq);
\&    $agent\->read_options() or $agent\->raise_error;
\&    $agent\->do_conf()      or $agent\->raise_error;
\&    my $rc = $agent\->doit({});
\&    exit $rc;
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
Razor2::Client::Agent provides the user interface layer for Vipul\*(Aqs Razor,
a distributed, collaborative spam detection and filtering network.  It
implements the command\-line tools \fBrazor\-check\fR, \fBrazor\-report\fR,
\&\fBrazor\-revoke\fR, and \fBrazor\-admin\fR.
.PP
This module inherits from Razor2::Client::Core (network protocol),
Razor2::Client::Config (configuration management), Razor2::Logger
(logging), and Razor2::String (utility functions).
.PP
Typical usage is through the command\-line programs rather than calling
this module directly.  See \fBrazor\-check\fR\|(1), \fBrazor\-report\fR\|(1),
\&\fBrazor\-revoke\fR\|(1), and \fBrazor\-admin\fR\|(1).
.SH METHODS
.IX Header "METHODS"
.IP \fBnew($breed)\fR 4
.IX Item "new($breed)"
Constructor.  \f(CW$breed\fR is the full program name, which must end with one
of \f(CW\*(C`razor\-check\*(C'\fR, \f(CW\*(C`razor\-report\*(C'\fR, \f(CW\*(C`razor\-revoke\*(C'\fR, or \f(CW\*(C`razor\-admin\*(C'\fR.
The breed determines which operations are available.
.Sp
Deletes \f(CW$ENV{PATH}\fR and \f(CW$ENV{BASH_ENV}\fR for taint safety.
.IP \fBread_options($agent)\fR 4
.IX Item "read_options($agent)"
Parses command\-line options via Getopt::Long.  Returns true on success,
false on error (error message available via \f(CWerrstr()\fR).
.IP \fBdo_conf()\fR 4
.IX Item "do_conf()"
Processes configuration: resolves razorhome, reads the config file, sets up
logging, and creates the home directory if \f(CW\*(C`\-create\*(C'\fR was specified.
Must be called after \f(CWread_options()\fR.
.IP \fBdoit($args)\fR 4
.IX Item "doit($args)"
Main dispatcher.  Calls the appropriate handler based on the breed:
\&\f(CWcheckit()\fR for check, \f(CWadminit()\fR for admin, \f(CWreportit()\fR for report
and revoke.
.Sp
Returns 0 for match (spam), 1 for no match (not spam), or 2 for error.
.IP \fBcheckit($args)\fR 4
.IX Item "checkit($args)"
Checks mail against the Razor catalogue servers.  Accepts input as
filenames, mbox files, signatures on the command line, or a filehandle
in \f(CW$args\fR.
.Sp
Return values: 0 = spam detected, 1 = not spam, 2 = error.
.IP \fBreportit($args)\fR 4
.IX Item "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(CW\*(C`\-f\*(C'\fR (foreground) is specified.
.Sp
Return values: 0 = success, 2 = error.
.IP \fBadminit($args)\fR 4
.IX Item "adminit($args)"
Handles administrative tasks: creating razorhome (\f(CW\*(C`\-create\*(C'\fR), server
discovery (\f(CW\*(C`\-discover\*(C'\fR), and identity registration (\f(CW\*(C`\-register\*(C'\fR).
.Sp
Return values: 0 = success, 2 = error.
.IP \fBparse_mbox($args)\fR 4
.IX Item "parse_mbox($args)"
Parses input into individual mail messages.  Supports mbox format
(splitting on \f(CW\*(C`^From \*(C'\fR lines), single RFC 822 messages, filehandle
input (via \f(CW\*(C`$args\->{fh}\*(C'\fR), and array reference input (via
\&\f(CW\*(C`$args\->{aref}\*(C'\fR).
.Sp
Returns an array reference of scalar references to mail content.
.IP \fBlocal_check($obj)\fR 4
.IX Item "local_check($obj)"
Performs local whitelist and mailing\-list checks.  Returns true if the
mail should be skipped (not checked against the server).
.IP \fBread_whitelist()\fR 4
.IX Item "read_whitelist()"
Loads the whitelist file specified in the configuration.  The whitelist
maps header names to patterns; matching mail is skipped.
.IP \fBget_server_info()\fR 4
.IX Item "get_server_info()"
Reads server lists, loads cached server configurations, and resolves the
next server to connect to.  Called before network operations.
.IP \fBraise_error($errstr)\fR 4
.IX Item "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.
.ie n .IP "\fBlog($level, \fR\fB$msg\fR\fB)\fR" 4
.el .IP "\fBlog($level, \fR\f(CB$msg\fR\fB)\fR" 4
.IX Item "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.
.IP \fBlogll($loglevel)\fR 4
.IX Item "logll($loglevel)"
Returns true if the current debug level is at or above \f(CW$loglevel\fR.
Use this to guard expensive log message construction.
.SH CONFIGURATION
.IX Header "CONFIGURATION"
See \fBrazor\-agent.conf\fR\|(5) for configuration file format and options.
.PP
The razorhome directory (default \fI~/.razor/\fR, system\-wide \fI/etc/razor/\fR)
stores configuration files, server lists, identity files, and logs.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBrazor\-check\fR\|(1), \fBrazor\-report\fR\|(1), \fBrazor\-revoke\fR\|(1),
\&\fBrazor\-admin\fR\|(1), \fBrazor\-agent.conf\fR\|(5), \fBrazor\-whitelist\fR\|(5),
Razor2::Client::Core, Razor2::Client::Config
.SH AUTHORS
.IX Header "AUTHORS"
Vipul Ved Prakash, <mail@vipul.net>
.SH LICENSE
.IX Header "LICENSE"
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.