You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@spamassassin.apache.org by pa...@apache.org on 2011/06/22 04:39:35 UTC
svn commit: r1138284 [15/15] - in /spamassassin/site/full/3.3.x: ./ doc/
Added: spamassassin/site/full/3.3.x/doc/spamc.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.3.x/doc/spamc.txt?rev=1138284&view=auto
==============================================================================
--- spamassassin/site/full/3.3.x/doc/spamc.txt (added)
+++ spamassassin/site/full/3.3.x/doc/spamc.txt Wed Jun 22 02:39:31 2011
@@ -0,0 +1,283 @@
+NAME
+ spamc - client for spamd
+
+SYNOPSIS
+ spamc [options] < message
+
+DESCRIPTION
+ Spamc is the client half of the spamc/spamd pair. It should be used in
+ place of "spamassassin" in scripts to process mail. It will read the
+ mail from STDIN, and spool it to its connection to spamd, then read the
+ result back and print it to STDOUT. Spamc has extremely low overhead in
+ loading, so it should be much faster to load than the whole spamassassin
+ program.
+
+ See the README file in the spamd directory of the SpamAssassin
+ distribution for more details.
+
+OPTIONS
+ All options detailed below can be passed as command line arguments, or
+ be contained in a configuration file, as described in the CONFIGURATION
+ FILE section below.
+
+ Note that the long options, a la "--long-options", are new as of
+ SpamAssassin 3.2.0, and were not available in earlier versions.
+
+ -B, --bsmtp
+ Assume input is a single BSMTP-formatted message. In other words,
+ spamc will pull out everything between the DATA line and the
+ lone-dot line to feed to spamd, and will place the spamd output back
+ in the same envelope (thus, any SIZE extension in your BSMTP file
+ will cause many problems).
+
+ -c, --check
+ Just check if the message is spam or not. Set process exitcode to 1
+ if message is spam, 0 if not spam or processing failure occurs. Will
+ print score/threshold to stdout (as ints) or 0/0 if there was an
+ error. Combining -c and -E is a no-op, since -c implies the
+ behaviour of -E.
+
+ -d *host[,host2]*, --dest=*host[,host2]*
+ In TCP/IP mode, connect to spamd server on given host (default:
+ localhost). Several hosts can be specified if separated by commas.
+
+ If *host* resolves to multiple addresses, then spamc will fail-over
+ to the other addresses, if the first one cannot be connected to. It
+ will first try all addresses of one host before it tries the next
+ one in the list. Note that this fail-over behaviour is incompatible
+ with -x; if that switch is used, fail-over will not occur.
+
+ -e *command* *[args]*, --pipe-to *command* *[args]*
+ Instead of writing to stdout, pipe the output to *command*'s
+ standard input. Note that there is a very slight chance mail will be
+ lost here, because if the fork-and-exec fails there's no place to
+ put the mail message.
+
+ Note that this must be the LAST command line option, as everything
+ after the -e is taken as arguments to the command (it's like *rxvt*
+ or *xterm*).
+
+ This option is not supported on Win32 platforms.
+
+ -E, --exitcode
+ Filter according to the other options, but set the process exitcode
+ to 1 if message is spam, 0 if not spam or processing failure occurs.
+
+ -F */path/to/file*, --config=*path*
+ Specify a configuration file to read additional command-line flags
+ from. See CONFIGURATION FILE below.
+
+ -h, --help
+ Print this help message and terminate without action.
+
+ -H, --randomize
+ For TCP/IP sockets, randomize the IP addresses returned for the
+ hosts given by the -d switch. This provides for a simple kind of
+ load balancing. It will try only three times though.
+
+ -l, --log-to-stderr
+ Send log messages to stderr, instead of to the syslog.
+
+ -L *learn type*, --learntype=*type*
+ Send message to spamd for learning. The "learn type" can be either
+ spam, ham or forget. The exitcode for spamc will be set to 5 if the
+ message was learned, or 6 if it was already learned, under a
+ condition that a --no-safe-fallback option is selected too.
+
+ Note that the "spamd" must run with the "--allow-tell" option for
+ this to work.
+
+ -C *report type*, --reporttype=*type*
+ Report or revoke a message to one of the configured collaborative
+ filtering databases. The "report type" can be either report or
+ revoke.
+
+ Note that the "spamd" must run with the "--allow-tell" option for
+ this to work.
+
+ -p *port*, --port=*port*
+ In TCP/IP mode, connect to spamd server listening on given port
+ (default: 783).
+
+ -r, --full-spam
+ Just output the SpamAssassin report text to stdout, if the message
+ is spam. If the message is ham (non-spam), nothing will be printed.
+ The first line of the output is the message score and the threshold,
+ in this format:
+
+ score/threshold
+
+ -R, --full
+ Just output the SpamAssassin report text to stdout, for all
+ messages. See -r for details of the output format used.
+
+ -s *max_size*, --max-size=*max_size*
+ Set the maximum message size which will be sent to spamd -- any
+ bigger than this threshold and the message will be returned
+ unprocessed (default: 500 KB). If spamc gets handed a message bigger
+ than this, it won't be passed to spamd. The maximum message size is
+ 256 MB.
+
+ The size is specified in bytes, as a positive integer greater than
+ 0. For example, -s 500000.
+
+ --connect-retries=*retries*
+ Retry connecting to spamd *retries* times. The default is 3 times.
+
+ --retry-sleep=*sleep*
+ Sleep for *sleep* seconds between attempts to connect to spamd. The
+ default is 1 second.
+
+ --filter-retries=*retries*
+ Retry filtering *retries* times if the spamd process fails (usually
+ times out). This differs from --connect-retries in that it times out
+ the transaction after the TCP connection has been established
+ successfully. The default is 1 time (ie. one attempt and no
+ retries).
+
+ --filter-retry-sleep=*sleep*
+ Sleep for *sleep* seconds between failed spamd filtering attempts.
+ The default is 1 second.
+
+ -S, --ssl, --ssl=*sslversion*
+ If spamc was built with support for SSL, encrypt data to and from
+ the spamd process with SSL; spamd must support SSL as well.
+ *sslversion* specifies the SSL protocol version to use, either
+ "sslv3", or "tlsv1". The default, is "sslv3".
+
+ -t *timeout*, --timeout=*timeout*
+ Set the timeout for spamc-to-spamd communications (default: 600, 0
+ disables). If spamd takes longer than this many seconds to reply to
+ a message, spamc will abort the connection and treat this as a
+ failure to connect; in other words the message will be returned
+ unprocessed.
+
+ -n *timeout*, --connect-timeout=*timeout*
+ Set the timeout for spamc-to-spamd connection establishment
+ (default: 600, 0 disables). If spamc takes longer than this many
+ seconds to establish a connection to spamd, spamc will abort the
+ connection and treat this as a failure to connect; in other words
+ the message will be returned unprocessed.
+
+ -u *username*, --username=*username*
+ To have spamd use per-user-config files, run spamc as the user whose
+ config files spamd should load; by default the effective user-ID is
+ sent to spamd. If you're running spamc as some other user, though,
+ (eg. root, mail, nobody, cyrus, etc.) then you may use this flag to
+ override the default.
+
+ -U *socketpath*, --socket=*path*
+ Connect to "spamd" via UNIX domain socket *socketpath* instead of a
+ TCP/IP connection.
+
+ This option is not supported on Win32 platforms.
+
+ -V, --version
+ Report the version of this "spamc" client. If built with SSL
+ support, an additional line will be included noting this, like so:
+
+ SpamAssassin Client version 3.0.0-rc4
+ compiled with SSL support (OpenSSL 0.9.7d 17 Mar 2004)
+
+ -x, --no-safe-fallback
+ Disables the 'safe fallback' error-recovery method, which passes
+ through the unaltered message if an error occurs. Instead, exit with
+ an error code, and let the MTA queue up the mails for a retry later.
+ See also "EXIT CODES".
+
+ This also disables the TCP fail-over behaviour from -d.
+
+ -y, --tests
+ Just output the names of the tests hit to stdout, on one line,
+ separated by commas.
+
+ -K Perform a keep-alive check of spamd, instead of a full message
+ check.
+
+ -z Use gzip compression to compress the mail message sent to "spamd".
+ This is useful for long-distance use of spamc over the internet.
+ Note that this relies on "zlib" being installed on the "spamc"
+ client side, and the "Compress::Zlib" perl module on the server
+ side; an error will be returned otherwise.
+
+ --headers
+ Perform a scan, but instead of allowing any part of the message
+ (header and body) to be rewritten, limit rewriting to only the
+ message headers. This is much more efficient in bandwidth usage,
+ since the response message transmitted back from the spamd server
+ will not include the body.
+
+ Note that this only makes sense if you are using "report_safe 0" in
+ the scanning configuration on the remote end; with "report_safe 1",
+ it is likely to result in corrupt messages.
+
+CONFIGURATION FILE
+ The above command-line switches can also be loaded from a configuration
+ file.
+
+ The format of the file is similar to the SpamAssassin rules files; blank
+ lines and lines beginning with "#" are ignored. Any space-separated
+ words are considered additions to the command line, and are prepended.
+ Newlines are treated as equivalent to spaces. Existing command line
+ switches will override any settings in the configuration file.
+
+ If the -F switch is specified, that file will be used. Otherwise,
+ "spamc" will attempt to load spamc.conf in "SYSCONFDIR" (default:
+ /etc/mail/spamassassin). If that file doesn't exist, and the -F switch
+ is not specified, no configuration file will be read.
+
+ Example:
+
+ # spamc global configuration file
+
+ # connect to "server.example.com", port 783
+ -d server.example.com
+ -p 783
+
+ # max message size for scanning = 350k
+ -s 350000
+
+EXIT CODES
+ By default, spamc will use the 'safe fallback' error recovery method.
+ That means, it will always exit with an exit code if 0, even if an error
+ was encountered. If any error occurrs, it will simply pass through the
+ unaltered message.
+
+ The -c and -E options modify this; instead, spamc will use an exit code
+ of 1 if the message is determined to be spam.
+
+ If one of the "-x", "-L" or "-C" options are specified, 'safe fallback'
+ will be disabled, and certain error conditions related to communication
+ between spamc and spamd will result in an error code. The exit codes
+ used are as follows:
+
+ EX_USAGE 64 command line usage error
+ EX_DATAERR 65 data format error
+ EX_NOINPUT 66 cannot open input
+ EX_NOUSER 67 addressee unknown
+ EX_NOHOST 68 host name unknown
+ EX_UNAVAILABLE 69 service unavailable
+ EX_SOFTWARE 70 internal software error
+ EX_OSERR 71 system error (e.g., can't fork)
+ EX_OSFILE 72 critical OS file missing
+ EX_CANTCREAT 73 can't create (user) output file
+ EX_IOERR 74 input/output error
+ EX_TEMPFAIL 75 temp failure; user is invited to retry
+ EX_PROTOCOL 76 remote error in protocol
+ EX_NOPERM 77 permission denied
+ EX_CONFIG 78 configuration error
+ EX_TOOBIG 98 message was too big to process (see --max-size)
+
+SEE ALSO
+ spamd(1) spamassassin(1) Mail::SpamAssassin(3)
+
+PREREQUISITES
+ "Mail::SpamAssassin"
+
+AUTHORS
+ The SpamAssassin(tm) Project <http://spamassassin.apache.org/>
+
+COPYRIGHT
+ SpamAssassin is distributed under the Apache License, Version 2.0, as
+ described in the file "LICENSE" included with the distribution.
+
Added: spamassassin/site/full/3.3.x/doc/spamd.html
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.3.x/doc/spamd.html?rev=1138284&view=auto
==============================================================================
--- spamassassin/site/full/3.3.x/doc/spamd.html (added)
+++ spamassassin/site/full/3.3.x/doc/spamd.html Wed Jun 22 02:39:31 2011
@@ -0,0 +1,626 @@
+<?xml version="1.0" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml">
+<head>
+<title>spamd - daemonized version of spamassassin</title>
+<meta http-equiv="content-type" content="text/html; charset=utf-8" />
+<link rev="made" href="mailto:parker@minotaur.apache.org" />
+</head>
+
+<body style="background-color: white">
+
+
+<!-- INDEX BEGIN -->
+<div name="index">
+<p><a name="__index__"></a></p>
+
+<ul>
+
+ <li><a href="#name">NAME</a></li>
+ <li><a href="#synopsis">SYNOPSIS</a></li>
+ <li><a href="#description">DESCRIPTION</a></li>
+ <li><a href="#options">OPTIONS</a></li>
+ <li><a href="#see_also">SEE ALSO</a></li>
+ <li><a href="#prerequisites">PREREQUISITES</a></li>
+ <li><a href="#authors">AUTHORS</a></li>
+ <li><a href="#license">LICENSE</a></li>
+</ul>
+
+<hr name="index" />
+</div>
+<!-- INDEX END -->
+
+<p>
+</p>
+<h1><a name="name">NAME</a></h1>
+<p>spamd - daemonized version of spamassassin</p>
+<p>
+</p>
+<hr />
+<h1><a name="synopsis">SYNOPSIS</a></h1>
+<p>spamd [options]</p>
+<p>Options:</p>
+<pre>
+ -l, --allow-tell Allow learning/reporting
+ -c, --create-prefs Create user preferences files
+ -C path, --configpath=path Path for default config files
+ --siteconfigpath=path Path for site configs
+ --cf='config line' Additional line of configuration
+ -d, --daemonize Daemonize
+ -h, --help Print usage message
+ -i [ipaddr], --listen-ip=ipaddr Listen on the IP ipaddr
+ --ipv4only, --ipv4-only, --ipv4 Disable attempted use of ipv6 for DNS
+ -p port, --port=port Listen on specified port
+ -m num, --max-children=num Allow maximum num children
+ --min-children=num Allow minimum num children
+ --min-spare=num Lower limit for number of spare children
+ --max-spare=num Upper limit for number of spare children
+ --max-conn-per-child=num Maximum connections accepted by child
+ before it is respawned
+ --round-robin Use traditional prefork algorithm
+ --timeout-tcp=secs Connection timeout for client headers
+ --timeout-child=secs Connection timeout for message checks
+ -q, --sql-config Enable SQL config (needs -x)
+ -Q, --setuid-with-sql Enable SQL config (needs -x,
+ enables use of -H)
+ --ldap-config Enable LDAP config (needs -x)
+ --setuid-with-ldap Enable LDAP config (needs -x,
+ enables use of -H)
+ --virtual-config-dir=dir Enable pattern based Virtual configs
+ (needs -x)
+ -r pidfile, --pidfile Write the process id to pidfile
+ -s facility, --syslog=facility Specify the syslog facility
+ --syslog-socket=type How to connect to syslogd
+ --log-timestamp-fmt=fmt strftime(3) format for timestamps, may be
+ empty to disable timestamps, or 'default'
+ -u username, --username=username Run as username
+ -g groupname, --groupname=groupname Run as groupname
+ -v, --vpopmail Enable vpopmail config
+ -x, --nouser-config Disable user config files
+ --auth-ident Use ident to authenticate spamc user
+ --ident-timeout=timeout Timeout for ident connections
+ -A host,..., --allowed-ips=..,.. Limit ip addresses which can connect
+ -D, --debug[=areas] Print debugging messages (for areas)
+ -L, --local Use local tests only (no DNS)
+ -P, --paranoid Die upon user errors
+ -H [dir], --helper-home-dir[=dir] Specify a different HOME directory
+ --ssl Run an SSL server
+ --ssl-port port Listen on port for SSL connections
+ --ssl-version sslversion Specify SSL protocol version to use
+ --server-key keyfile Specify an SSL keyfile
+ --server-cert certfile Specify an SSL certificate
+ --socketpath=path Listen on given UNIX domain socket
+ --socketowner=name Set UNIX domain socket file's owner
+ --socketgroup=name Set UNIX domain socket file's group
+ --socketmode=mode Set UNIX domain socket file's mode
+ -V, --version Print version and exit</pre>
+<p>
+</p>
+<hr />
+<h1><a name="description">DESCRIPTION</a></h1>
+<p>The purpose of this program is to provide a daemonized version of the
+spamassassin executable. The goal is improving throughput performance for
+automated mail checking.</p>
+<p>This is intended to be used alongside <code>spamc</code>, a fast, low-overhead C client
+program.</p>
+<p>See the README file in the <code>spamd</code> directory of the SpamAssassin distribution
+for more details.</p>
+<p>Note: Although <code>spamd</code> will check per-user config files for every message, any
+changes to the system-wide config files will require either restarting spamd
+or forcing it to reload itself via <strong>SIGHUP</strong> for the changes to take effect.</p>
+<p>Note: If <code>spamd</code> receives a <strong>SIGHUP</strong>, it internally reloads itself, which
+means that it will change its pid and might not restart at all if its
+environment changed (ie. if it can't change back into its own directory). If
+you plan to use <strong>SIGHUP</strong>, you should always start <code>spamd</code> with the <strong>-r</strong>
+switch to know its current pid.</p>
+<p>
+</p>
+<hr />
+<h1><a name="options">OPTIONS</a></h1>
+<p>Options of the long form can be shortened as long as they remain
+unambiguous. (i.e. <strong>--dae</strong> can be used instead of <strong>--daemonize</strong>)
+Also, boolean options (like <strong>--user-config</strong>) can be negated by
+adding <em>no</em> (<strong>--nouser-config</strong>), however, this is usually unnecessary.</p>
+<dl>
+<dt><strong><a name="l_allow_tell" class="item"><strong>-l</strong>, <strong>--allow-tell</strong></a></strong></dt>
+
+<dd>
+<p>Allow learning and forgetting (to a local Bayes database), reporting
+and revoking (to a remote database) by spamd. The client issues a TELL
+command to tell what type of message is being processed and whether
+local (learn/forget) or remote (report/revoke) databases should be
+updated.</p>
+<p>Note that spamd always trusts the username passed in (unless
+<strong>--auth-ident</strong> is used) so clients could maliciously learn messages
+for other users. (This is not ususally a concern with an SQL Bayes
+store as users will typically have read-write access directly to the
+database, and can also use <code>sa-learn</code> with the <strong>-u</strong> option to
+achieve the same result.)</p>
+</dd>
+<dt><strong><a name="c_create_prefs" class="item"><strong>-c</strong>, <strong>--create-prefs</strong></a></strong></dt>
+
+<dd>
+<p>Create user preferences files if they don't exist (default: don't).</p>
+</dd>
+<dt><strong><a name="c_path_configpath_path" class="item"><strong>-C</strong> <em>path</em>, <strong>--configpath</strong>=<em>path</em></a></strong></dt>
+
+<dd>
+<p>Use the specified path for locating the distributed configuration files.
+Ignore the default directories (usually <code>/usr/share/spamassassin</code> or similar).</p>
+</dd>
+<dt><strong><a name="siteconfigpath_path4" class="item"><strong>--siteconfigpath</strong>=<em>path</em></a></strong></dt>
+
+<dd>
+<p>Use the specified path for locating site-specific configuration files. Ignore
+the default directories (usually <code>/etc/mail/spamassassin</code> or similar).</p>
+</dd>
+<dt><strong><a name="cf_config_line4" class="item"><strong>--cf='config line'</strong></a></strong></dt>
+
+<dd>
+<p>Add additional lines of configuration directly from the command-line, parsed
+after the configuration files are read. Multiple <strong>--cf</strong> arguments can be
+used, and each will be considered a separate line of configuration.</p>
+</dd>
+<dt><strong><a name="d_daemonize" class="item"><strong>-d</strong>, <strong>--daemonize</strong></a></strong></dt>
+
+<dd>
+<p>Detach from starting process and run in background (daemonize).</p>
+</dd>
+<dt><strong><a name="h_help6" class="item"><strong>-h</strong>, <strong>--help</strong></a></strong></dt>
+
+<dd>
+<p>Print a brief help message, then exit without further action.</p>
+</dd>
+<dt><strong><a name="v_version5" class="item"><strong>-V</strong>, <strong>--version</strong></a></strong></dt>
+
+<dd>
+<p>Print version information, then exit without further action.</p>
+</dd>
+<dt><strong><a name="i_ipaddress_listen_ip_ipaddress_ip_address_ipaddress" class="item"><strong>-i</strong> [<em>ipaddress</em>], <strong>--listen-ip</strong>[=<em>ipaddress</em>], <strong>--ip-address</strong>[=<em>ipaddress</em>]</a></strong></dt>
+
+<dd>
+<p>Tells spamd to listen on the specified IP address (defaults to 127.0.0.1). If
+you specify no IP address after the switch, spamd will listen on all interfaces.
+(This is equal to the address 0.0.0.0). You can also use a valid hostname which
+will make spamd listen on the first address that name resolves to.</p>
+</dd>
+<dt><strong><a name="p_port_port_port2" class="item"><strong>-p</strong> <em>port</em>, <strong>--port</strong>=<em>port</em></a></strong></dt>
+
+<dd>
+<p>Optionally specifies the port number for the server to listen on (default: 783).</p>
+<p>If the <strong>--ssl</strong> switch is used, and <strong>--ssl-port</strong> is not supplied, then this
+port will be used to accept SSL connections instead of unencrypted connections.
+If the <strong>--ssl</strong> switch is used, and <strong>--ssl-port</strong> is set, then unencrypted
+connections will be accepted on the <strong>--port</strong> at the same time as encrypted
+connections are accepted at <strong>--ssl-port</strong>.</p>
+</dd>
+<dt><strong><a name="q_sql_config" class="item"><strong>-q</strong>, <strong>--sql-config</strong></a></strong></dt>
+
+<dd>
+<p>Turn on SQL lookups even when per-user config files have been disabled
+with <strong>-x</strong>. this is useful for spamd hosts which don't have user's
+home directories but do want to load user preferences from an SQL
+database.</p>
+<p>If your spamc client does not support sending the <code>User:</code> header,
+like <code>exiscan</code>, then the SQL username used will always be <strong>nobody</strong>.</p>
+<p>This inhibits the <code>setuid()</code> behavior, so the <code>-u</code> option is
+required. If you want the <code>setuid()</code> behaviour, use <code>-Q</code> or
+<code>--setuid-with-sql</code> instead.</p>
+</dd>
+<dt><strong><a name="ldap_config" class="item"><strong>--ldap-config</strong></a></strong></dt>
+
+<dd>
+<p>Turn on LDAP lookups. This is completely analog to <code>--sql-config</code>,
+only it is using an LDAP server.</p>
+<p>Like <code>--sql-config</code>, this disables the setuid behavior, and requires
+<code>-u</code>. If you want it, use <a href="#setuid_with_ldap"><code>--setuid-with-ldap</code></a> instead.</p>
+</dd>
+<dt><strong><a name="q_setuid_with_sql" class="item"><strong>-Q</strong>, <strong>--setuid-with-sql</strong></a></strong></dt>
+
+<dd>
+<p>Turn on SQL lookups even when per-user config files have been disabled
+with <strong>-x</strong> and also setuid to the user. This is useful for spamd hosts
+which want to load user preferences from an SQL database but also wish to
+support the use of <strong>-H</strong> (Helper home directories.)</p>
+</dd>
+<dt><strong><a name="setuid_with_ldap" class="item"><strong>--setuid-with-ldap</strong></a></strong></dt>
+
+<dd>
+<p>Turn on LDAP lookups even when per-user config files have been disabled
+with <strong>-x</strong> and also setuid to the user. This is again completely analog
+to <code>--setuid-with-sql</code>, only it is using an LDAP server.</p>
+</dd>
+<dt><strong><a name="virtual_config_dir_pattern" class="item"><strong>--virtual-config-dir</strong>=<em>pattern</em></a></strong></dt>
+
+<dd>
+<p>This option specifies where per-user preferences can be found for virtual
+users, for the <strong>-x</strong> switch. The <em>pattern</em> is used as a base pattern for the
+directory name. Any of the following escapes can be used:</p>
+<dl>
+<dt><strong><a name="_u" class="item">%u -- replaced with the full name of the current user, as sent by spamc.</a></strong></dt>
+
+<dt><strong><a name="_l" class="item">%l -- replaced with the 'local part' of the current username. In other
+words, if the username is an email address, this is the part before the <code>@</code>
+sign.</a></strong></dt>
+
+<dt><strong><a name="_d" class="item">%d -- replaced with the 'domain' of the current username. In other
+words, if the username is an email address, this is the part after the <code>@</code>
+sign.</a></strong></dt>
+
+<dt><strong><a name="sign" class="item">%% -- replaced with a single percent sign (%).</a></strong></dt>
+
+</dl>
+<p>So for example, if <code>/vhome/users/%u/spamassassin</code> is specified, and spamc
+sends a virtual username of <code>jm@example.com</code>, the directory
+<code>/vhome/users/jm@example.com/spamassassin</code> will be used.</p>
+<p>The set of characters allowed in the virtual username for this path are
+restricted to:</p>
+<pre>
+ A-Z a-z 0-9 - + _ . , @ =</pre>
+<p>All others will be replaced by underscores (<code>_</code>).</p>
+<p>This path must be a writable directory. It will be created if it does not
+already exist. If a file called <strong>user_prefs</strong> exists in this directory (note:
+<strong>not</strong> in a <code>.spamassassin</code> subdirectory!), it will be loaded as the user's
+preferences. The Bayes databases for that user will be stored in this directory.</p>
+<p>Note that this <strong>requires</strong> that <strong>-x</strong> is used, and cannot be combined with
+SQL- or LDAP-based configuration.</p>
+<p>The pattern <strong>must</strong> expand to an absolute directory when spamd is running
+daemonized (<strong>-d</strong>).</p>
+<p>Currently, use of this without <strong>-u</strong> is not supported. This inhibits setuid.</p>
+</dd>
+<dt><strong><a name="r_pidfile_pidfile_pidfile" class="item"><strong>-r</strong> <em>pidfile</em>, <strong>--pidfile</strong>=<em>pidfile</em></a></strong></dt>
+
+<dd>
+<p>Write the process ID of the spamd parent to the file specified by <em>pidfile</em>.
+The file will be unlinked when the parent exits. Note that when running
+with the <strong>-u</strong> option, the file must be writable by that user.</p>
+</dd>
+<dt><strong><a name="v_vpopmail" class="item"><strong>-v</strong>, <strong>--vpopmail</strong></a></strong></dt>
+
+<dd>
+<p>Enable vpopmail config. If specified with with <strong>-u</strong> set to the vpopmail user,
+this allows spamd to lookup/create user_prefs in the vpopmail user's own
+maildir. This option is useful for vpopmail virtual users who do not have an
+entry in the system /etc/passwd file.</p>
+<p>Currently, use of this without <strong>-u</strong> is not supported. This inhibits setuid.</p>
+</dd>
+<dt><strong><a name="s_facility_syslog_facility" class="item"><strong>-s</strong> <em>facility</em>, <strong>--syslog</strong>=<em>facility</em></a></strong></dt>
+
+<dd>
+<p>Specify the syslog facility to use (default: mail). If <code>stderr</code> is specified,
+output will be written to stderr. (This is useful if you're running <code>spamd</code>
+under the <code>daemontools</code> package.) With a <em>facility</em> of <code>file</code>, all output
+goes to spamd.log. <em>facility</em> is interpreted as a file name to log to if it
+contains any characters except a-z and 0-9. <code>null</code> disables logging completely
+(used internally).</p>
+<p><table cellspacing="0" cellpadding="0"><tr><td>Examples:
+<tr><td><td>spamd -s mail # use syslog, facility mail (default)
+<tr><td><td>spamd -s ./mail # log to file ./mail
+<tr><td><td>spamd -s stderr 2>/dev/null # log to stderr, throw messages away
+<tr><td><td>spamd -s null # the same as above
+<tr><td><td>spamd -s file # log to file ./spamd.log
+<tr><td><td>spamd -s /var/log/spamd.log # log to file /var/log/spamd.log</table></p>
+<p>If logging to a file is enabled and that log file is rotated, the spamd server
+must be restarted with a SIGHUP. (If the log file is just truncated, this is
+not needed but still recommended.)</p>
+<p>Note that logging to a file does not use locking, so you cannot intermix
+logging from spamd and other processes into the same file. If you want
+to mix logging like this, use syslog instead.</p>
+<p>If you use syslog logging, it is essential to send a SIGHUP to the spamd daemon
+when you restart the syslogd daemon. (This is due to a shortcoming in Perl's
+syslog handling, where the disappearance of the connection to the syslogd is
+considered a fatal error.)</p>
+</dd>
+<dt><strong><a name="syslog_socket_type" class="item"><strong>--syslog-socket</strong>=<em>type</em></a></strong></dt>
+
+<dd>
+<p>Specify how spamd should send messages to syslogd. The <em>type</em> can be any
+of the socket types or logging mechanisms as accepted by the subroutine
+Sys::Syslog::setlogsock(). Depending on a version of Sys::Syslog and on the
+underlying operating system, one of the following values (or their subset) can
+be used: <code>native</code>, <code>eventlog</code>, <code>tcp</code>, <code>udp</code>, <code>inet</code>, <code>unix</code>, <code>stream</code>,
+<code>pipe</code>, or <code>console</code>. The value <code>eventlog</code> is specific to Win32 events
+logger and requires a perl module Win32::EventLog to be installed.
+For more information please consult the Sys::Syslog documentation.</p>
+<p>A historical setting --syslog-socket=none is mapped to --syslog=stderr.</p>
+<p>A default for Windows platforms is <code>none</code>, otherwise the default is
+to try <code>unix</code> first, falling back to <code>inet</code> if perl detects errors
+in its <code>unix</code> support.</p>
+<p>Some platforms, or versions of perl, are shipped with old or dysfunctional
+versions of the <strong>Sys::Syslog</strong> module which do not support some socket types,
+so you may need to set this option explicitly. If you get error messages
+regarding <strong>__PATH_LOG</strong> or similar spamd, try changing this setting.</p>
+<p>The socket types <code>file</code> is used internally and should not be specified.
+Use the <code>-s</code> switch instead.</p>
+</dd>
+<dt><strong><a name="log_timestamp_fmt_format" class="item"><strong>--log-timestamp-fmt</strong>=<em>format</em></a></strong></dt>
+
+<dd>
+<p>The --log-timestamp-fmt option can provide a POSIX <code>strftime(3)</code> format for
+timestamps included in each logged message. Each logger (stderr, file,
+syslog) has its own default value for a timestamp format, which applies when
+--log-timestamp-fmt option is not given, or with --log-timestamp-fmt=default .
+Timestamps can be turned off by specifying an empty string with this
+option, e.g. --log-timestamp-fmt='' or just --log-timestamp-fmt= .
+Typical use: --log-timestamp-fmt='%a %b %e %H:%M:%S %Y' (provides
+localized weekday and month names in the <code>ctime(3)</code> style),
+or '%a, %e %b %Y %H:%M:%S %z (%Z)' for a <a href="http://www.ietf.org/rfc/rfc2822.txt" class="rfc">RFC 2822</a> format,
+or maybe '%Y-%m-%d %H:%M:%S%z' for an ISO 8601 (EN 28601) format,
+or just '%Y%m%dT%H%M%S' .</p>
+</dd>
+<dt><strong><a name="u_username_username_username3" class="item"><strong>-u</strong> <em>username</em>, <strong>--username</strong>=<em>username</em></a></strong></dt>
+
+<dd>
+<p>Run as the named user. If this option is not set, the default behaviour
+is to <code>setuid()</code> to the user running <code>spamc</code>, if <code>spamd</code> is running
+as root.</p>
+<p>Note: "--username=root" is not a valid option. If specified, <code>spamd</code> will
+exit with a fatal error on startup.</p>
+</dd>
+<dt><strong><a name="g_groupname_groupname_groupname" class="item"><strong>-g</strong> <em>groupname</em>, <strong>--groupname</strong>=<em>groupname</em></a></strong></dt>
+
+<dd>
+<p>Run as the named group if --username is being used. If this option is
+not set when --username is used then the primary group for the user
+given to --username is used.</p>
+</dd>
+<dt><strong><a name="x_nouser_config_user_config" class="item"><strong>-x</strong>, <strong>--nouser-config</strong>, <strong>--user-config</strong></a></strong></dt>
+
+<dd>
+<p>Turn off (on) reading of per-user configuration files (user_prefs) from the
+user's home directory. The default behaviour is to read per-user
+configuration from the user's home directory (<strong>--user-config</strong>).</p>
+<p>This option does not disable or otherwise influence the SQL, LDAP or
+Virtual Config Dir settings.</p>
+</dd>
+<dt><strong><a name="auth_ident" class="item"><strong>--auth-ident</strong></a></strong></dt>
+
+<dd>
+<p>Verify the username provided by spamc using ident. This is only
+useful if connections are only allowed from trusted hosts (because an
+identd that lies is trivial to create) and if spamc REALLY SHOULD be
+running as the user it represents. Connections are terminated
+immediately if authentication fails. In this case, spamc will pass
+the mail through unchecked. Failure to connect to an ident server,
+and response timeouts are considered authentication failures. This
+requires that Net::Ident be installed.</p>
+</dd>
+<dt><strong><a name="ident_timeout_timeout" class="item"><strong>--ident-timeout</strong>=<em>timeout</em></a></strong></dt>
+
+<dd>
+<p>Wait at most <em>timeout</em> seconds for a response to ident queries.
+Authentication that takes long that <em>timeout</em> seconds will fail, and
+mail will not be processed. Setting this to 0.0 or less results in no
+timeout, which is STRONGLY discouraged. The default is 5 seconds.</p>
+</dd>
+<dt><strong><a name="a_host_allowed_ips_host" class="item"><strong>-A</strong> <em>host,...</em>, <strong>--allowed-ips</strong>=<em>host,...</em></a></strong></dt>
+
+<dd>
+<p>Specify a list of authorized hosts or networks which can connect to this spamd
+instance. Single IP addresses can be given, ranges of IP addresses in
+address/masklength CIDR format, or ranges of IP addresses by listing 3 or less
+octets with a trailing dot. Hostnames are not supported, only IP addresses.
+This option can be specified multiple times, or can take a list of addresses
+separated by commas. Examples:</p>
+<p><strong>-A 10.11.12.13</strong> -- only allow connections from <code>10.11.12.13</code>.</p>
+<p><strong>-A 10.11.12.13,10.11.12.14</strong> -- only allow connections from <code>10.11.12.13</code> and
+<code>10.11.12.14</code>.</p>
+<p><strong>-A 10.200.300.0/24</strong> -- allow connections from any machine in the range
+<code>10.200.300.*</code>.</p>
+<p><strong>-A 10.</strong> -- allow connections from any machine in the range <code>10.*.*.*</code>.</p>
+<p>By default, connections are only accepted from localhost [127.0.0.1].</p>
+</dd>
+<dt><strong><a name="d_area_debug_area5" class="item"><strong>-D</strong> [<em>area,...</em>], <strong>--debug</strong> [<em>area,...</em>]</a></strong></dt>
+
+<dd>
+<p>Produce debugging output. If no areas are listed, all debugging information is
+printed. Diagnostic output can also be enabled for each area individually;
+<em>area</em> is the area of the code to instrument. For example, to produce
+diagnostic output on bayes, learn, and dns, use:</p>
+<pre>
+ spamassassin -D bayes,learn,dns</pre>
+<p>Higher priority informational messages that are suitable for logging in normal
+circumstances are available with an area of "info".</p>
+<p>For more information about which areas (also known as channels) are available,
+please see the documentation at:</p>
+<pre>
+ C<<a href="http://wiki.apache.org/spamassassin/DebugChannels>">http://wiki.apache.org/spamassassin/DebugChannels></a>;</pre>
+</dd>
+<dt><strong><a name="ipv4only_ipv4_only_ipv42" class="item"><strong> --ipv4only</strong>, <strong>--ipv4-only</strong>, <strong>--ipv4</strong></a></strong></dt>
+
+<dd>
+<p>Do not use IPv6 for DNS tests. Use if the existing tests
+for IPv6 availability produce incorrect results or crashes.</p>
+</dd>
+<dt><strong><a name="l_local3" class="item"><strong>-L</strong>, <strong>--local</strong></a></strong></dt>
+
+<dd>
+<p>Perform only local tests on all mail. In other words, skip DNS and other
+network tests. Works the same as the <code>-L</code> flag to <code>spamassassin(1)</code>.</p>
+</dd>
+<dt><strong><a name="p_paranoid" class="item"><strong>-P</strong>, <strong>--paranoid</strong></a></strong></dt>
+
+<dd>
+<p>Die on user errors (for the user passed from spamc) instead of falling back to
+user <em>nobody</em> and using the default configuration.</p>
+</dd>
+<dt><strong><a name="m_number_max_children_number" class="item"><strong>-m</strong> <em>number</em> , <strong>--max-children</strong>=<em>number</em></a></strong></dt>
+
+<dd>
+<p>This option specifies the maximum number of children to spawn.
+Spamd will spawn that number of children, then sleep in the background
+until a child dies, wherein it will go and spawn a new child.</p>
+<p>Incoming connections can still occur if all of the children are busy,
+however those connections will be queued waiting for a free child.
+The minimum value is <code>1</code>, the default value is <code>5</code>.</p>
+<p>Please note that there is a OS specific maximum of connections that can be
+queued (Try <code>perl -MSocket -e'print SOMAXCONN'</code> to find this maximum).</p>
+<p>Note that if you run too many servers for the amount of free RAM available, you
+run the danger of hurting performance by causing a high swap load as server
+processes are swapped in and out continually.</p>
+</dd>
+<dt><strong><a name="min_children_number" class="item"><strong>--min-children</strong>=<em>number</em></a></strong></dt>
+
+<dd>
+<p>The minimum number of children that will be kept running. The minimum value is
+<code>1</code>, the default value is <code>1</code>. If you have lots of free RAM, you may want to
+increase this.</p>
+</dd>
+<dt><strong><a name="min_spare_number" class="item"><strong>--min-spare</strong>=<em>number</em></a></strong></dt>
+
+<dd>
+<p>The lower limit for the number of spare children allowed to run. A
+spare, or idle, child is one that is not handling a scan request. If
+there are too few spare children available, a new server will be started
+every second or so. The default value is <code>1</code>.</p>
+</dd>
+<dt><strong><a name="max_spare_number" class="item"><strong>--max-spare</strong>=<em>number</em></a></strong></dt>
+
+<dd>
+<p>The upper limit for the number of spare children allowed to run. If there
+are too many spare children, one will be killed every second or so until
+the number of idle children is in the desired range. The default value
+is <code>2</code>.</p>
+</dd>
+<dt><strong><a name="max_conn_per_child_number" class="item"><strong>--max-conn-per-child</strong>=<em>number</em></a></strong></dt>
+
+<dd>
+<p>This option specifies the maximum number of connections each child
+should process before dying and letting the master spamd process spawn
+a new child. The minimum value is <code>1</code>, the default value is <code>200</code>.</p>
+</dd>
+<dt><strong><a name="round_robin" class="item"><strong>--round-robin</strong></a></strong></dt>
+
+<dd>
+<p>By default, <code>spamd</code> will attempt to keep a small number of "hot" child
+processes as busy as possible, and keep any others as idle as possible, using
+something similar to the Apache httpd server scaling algorithm. This is
+accomplished by the master process coordinating the activities of the children.
+This switch will disable this scaling algorithm, and the behaviour seen in
+the 3.0.x versions will be used instead, where all processes receive an
+equal load and no scaling takes place.</p>
+</dd>
+<dt><strong><a name="timeout_tcp_number" class="item"><strong>--timeout-tcp</strong>=<em>number</em></a></strong></dt>
+
+<dd>
+<p>This option specifies the number of seconds to wait for headers from a
+client (spamc) before closing the connection. The minimum value is <code>1</code>,
+the default value is <code>30</code>, and a value of <code>0</code> will disable socket
+timeouts completely.</p>
+</dd>
+<dt><strong><a name="timeout_child_number" class="item"><strong>--timeout-child</strong>=<em>number</em></a></strong></dt>
+
+<dd>
+<p>This option specifies the number of seconds to wait for a spamd child to
+process or check a message. The minimum value is <code>1</code>, the default
+value is <code>300</code>, and a value of <code>0</code> will disable child timeouts completely.</p>
+</dd>
+<dt><strong><a name="h_directory_helper_home_dir_directory" class="item"><strong>-H</strong> <em>directory</em>, <strong>--helper-home-dir</strong>=<em>directory</em></a></strong></dt>
+
+<dd>
+<p>Specify that external programs such as Razor, DCC, and Pyzor should have
+a HOME environment variable set to a specific directory. The default
+is to use the HOME environment variable setting from the shell running
+spamd. By specifying no argument, spamd will use the spamc caller's
+home directory instead.</p>
+</dd>
+<dt><strong><a name="ssl" class="item"><strong>--ssl</strong></a></strong></dt>
+
+<dd>
+<p>Accept only SSL connections on the associated port.
+The <strong>IO::Socket::SSL</strong> perl module must be installed.</p>
+<p>If the <strong>--ssl</strong> switch is used, and <strong>--ssl-port</strong> is not supplied, then
+<strong>--port</strong> port will be used to accept SSL connections instead of unencrypted
+connections. If the <strong>--ssl</strong> switch is used, and <strong>--ssl-port</strong> is set, then
+unencrypted connections will be accepted on the <strong>--port</strong>, at the same time as
+encrypted connections are accepted at <strong>--ssl-port</strong>.</p>
+</dd>
+<dt><strong><a name="ssl_port_port" class="item"><strong>--ssl-port</strong>=<em>port</em></a></strong></dt>
+
+<dd>
+<p>Optionally specifies the port number for the server to listen on for
+SSL connections (default: whatever --port uses). See <strong>--ssl</strong> for
+more details.</p>
+</dd>
+<dt><strong><a name="ssl_version_sslversion" class="item"><strong>--ssl-version</strong>=<em>sslversion</em></a></strong></dt>
+
+<dd>
+<p>Specify the SSL protocol version to use, one of <strong>sslv3</strong> or <strong>tlsv1</strong>.
+The default, <strong>sslv3</strong>, is the most flexible, accepting a SSLv3 or
+higher hello handshake, then negotiating use of SSLv3 or TLSv1
+protocol if the client can accept it. Specifying <strong>--ssl-version</strong>
+implies <strong>--ssl</strong>.</p>
+</dd>
+<dt><strong><a name="server_key_keyfile" class="item"><strong>--server-key</strong> <em>keyfile</em></a></strong></dt>
+
+<dd>
+<p>Specify the SSL key file to use for SSL connections.</p>
+</dd>
+<dt><strong><a name="server_cert_certfile" class="item"><strong>--server-cert</strong> <em>certfile</em></a></strong></dt>
+
+<dd>
+<p>Specify the SSL certificate file to use for SSL connections.</p>
+</dd>
+<dt><strong><a name="socketpath_pathname" class="item"><strong>--socketpath</strong> <em>pathname</em></a></strong></dt>
+
+<dd>
+<p>Listen on UNIX domain path <em>pathname</em> instead of a TCP socket.</p>
+<p>Warning: the Perl support on BSD platforms for UNIX domain sockets seems to
+have a bug regarding paths of over 100 bytes or so (SpamAssassin bug 4380). If
+you see a 'could not find newly-created UNIX socket' error message, and the
+path appears truncated, this may be the cause. Try using a shorter path
+to the socket.</p>
+<p>By default, use of <strong>--socketpath</strong> will inhibit SSL connections and unencrypted
+TCP connections. To enable them, specify <strong>--port</strong> and/or <strong>--ssl-port</strong>
+explicitly.</p>
+</dd>
+<dt><strong><a name="socketowner_name" class="item"><strong>--socketowner</strong> <em>name</em></a></strong></dt>
+
+<dd>
+<p>Set UNIX domain socket to be owned by the user named <em>name</em>. Note
+that this requires that spamd be started as <code>root</code>, and if <code>-u</code>
+is used, that user should have write permissions to unlink the file
+later, for when the <code>spamd</code> server is killed.</p>
+</dd>
+<dt><strong><a name="socketgroup_name" class="item"><strong>--socketgroup</strong> <em>name</em></a></strong></dt>
+
+<dd>
+<p>Set UNIX domain socket to be owned by the group named <em>name</em>. See
+<code>--socketowner</code> for notes on ownership and permissions.</p>
+</dd>
+<dt><strong><a name="socketmode_mode" class="item"><strong>--socketmode</strong> <em>mode</em></a></strong></dt>
+
+<dd>
+<p>Set UNIX domain socket to use the octal mode <em>mode</em>. Note that if <code>-u</code> is
+used, that user should have write permissions to unlink the file later, for
+when the <code>spamd</code> server is killed.</p>
+</dd>
+</dl>
+<p>
+</p>
+<hr />
+<h1><a name="see_also">SEE ALSO</a></h1>
+<p><code>spamc(1)</code>
+<code>spamassassin(1)</code>
+Mail::SpamAssassin::Conf(3)
+Mail::SpamAssassin(3)</p>
+<p>
+</p>
+<hr />
+<h1><a name="prerequisites">PREREQUISITES</a></h1>
+<p><code>Mail::SpamAssassin</code></p>
+<p>
+</p>
+<hr />
+<h1><a name="authors">AUTHORS</a></h1>
+<p>The SpamAssassin(tm) Project (http://spamassassin.apache.org/)</p>
+<p>
+</p>
+<hr />
+<h1><a name="license">LICENSE</a></h1>
+<p>SpamAssassin is distributed under the Apache License, Version 2.0, as
+described in the file <code>LICENSE</code> included with the distribution.</p>
+
+</body>
+
+</html>
Added: spamassassin/site/full/3.3.x/doc/spamd.txt
URL: http://svn.apache.org/viewvc/spamassassin/site/full/3.3.x/doc/spamd.txt?rev=1138284&view=auto
==============================================================================
--- spamassassin/site/full/3.3.x/doc/spamd.txt (added)
+++ spamassassin/site/full/3.3.x/doc/spamd.txt Wed Jun 22 02:39:31 2011
@@ -0,0 +1,539 @@
+NAME
+ spamd - daemonized version of spamassassin
+
+SYNOPSIS
+ spamd [options]
+
+ Options:
+
+ -l, --allow-tell Allow learning/reporting
+ -c, --create-prefs Create user preferences files
+ -C path, --configpath=path Path for default config files
+ --siteconfigpath=path Path for site configs
+ --cf='config line' Additional line of configuration
+ -d, --daemonize Daemonize
+ -h, --help Print usage message
+ -i [ipaddr], --listen-ip=ipaddr Listen on the IP ipaddr
+ --ipv4only, --ipv4-only, --ipv4 Disable attempted use of ipv6 for DNS
+ -p port, --port=port Listen on specified port
+ -m num, --max-children=num Allow maximum num children
+ --min-children=num Allow minimum num children
+ --min-spare=num Lower limit for number of spare children
+ --max-spare=num Upper limit for number of spare children
+ --max-conn-per-child=num Maximum connections accepted by child
+ before it is respawned
+ --round-robin Use traditional prefork algorithm
+ --timeout-tcp=secs Connection timeout for client headers
+ --timeout-child=secs Connection timeout for message checks
+ -q, --sql-config Enable SQL config (needs -x)
+ -Q, --setuid-with-sql Enable SQL config (needs -x,
+ enables use of -H)
+ --ldap-config Enable LDAP config (needs -x)
+ --setuid-with-ldap Enable LDAP config (needs -x,
+ enables use of -H)
+ --virtual-config-dir=dir Enable pattern based Virtual configs
+ (needs -x)
+ -r pidfile, --pidfile Write the process id to pidfile
+ -s facility, --syslog=facility Specify the syslog facility
+ --syslog-socket=type How to connect to syslogd
+ --log-timestamp-fmt=fmt strftime(3) format for timestamps, may be
+ empty to disable timestamps, or 'default'
+ -u username, --username=username Run as username
+ -g groupname, --groupname=groupname Run as groupname
+ -v, --vpopmail Enable vpopmail config
+ -x, --nouser-config Disable user config files
+ --auth-ident Use ident to authenticate spamc user
+ --ident-timeout=timeout Timeout for ident connections
+ -A host,..., --allowed-ips=..,.. Limit ip addresses which can connect
+ -D, --debug[=areas] Print debugging messages (for areas)
+ -L, --local Use local tests only (no DNS)
+ -P, --paranoid Die upon user errors
+ -H [dir], --helper-home-dir[=dir] Specify a different HOME directory
+ --ssl Run an SSL server
+ --ssl-port port Listen on port for SSL connections
+ --ssl-version sslversion Specify SSL protocol version to use
+ --server-key keyfile Specify an SSL keyfile
+ --server-cert certfile Specify an SSL certificate
+ --socketpath=path Listen on given UNIX domain socket
+ --socketowner=name Set UNIX domain socket file's owner
+ --socketgroup=name Set UNIX domain socket file's group
+ --socketmode=mode Set UNIX domain socket file's mode
+ -V, --version Print version and exit
+
+DESCRIPTION
+ The purpose of this program is to provide a daemonized version of the
+ spamassassin executable. The goal is improving throughput performance
+ for automated mail checking.
+
+ This is intended to be used alongside "spamc", a fast, low-overhead C
+ client program.
+
+ See the README file in the "spamd" directory of the SpamAssassin
+ distribution for more details.
+
+ Note: Although "spamd" will check per-user config files for every
+ message, any changes to the system-wide config files will require either
+ restarting spamd or forcing it to reload itself via SIGHUP for the
+ changes to take effect.
+
+ Note: If "spamd" receives a SIGHUP, it internally reloads itself, which
+ means that it will change its pid and might not restart at all if its
+ environment changed (ie. if it can't change back into its own
+ directory). If you plan to use SIGHUP, you should always start "spamd"
+ with the -r switch to know its current pid.
+
+OPTIONS
+ Options of the long form can be shortened as long as they remain
+ unambiguous. (i.e. --dae can be used instead of --daemonize) Also,
+ boolean options (like --user-config) can be negated by adding *no*
+ (--nouser-config), however, this is usually unnecessary.
+
+ -l, --allow-tell
+ Allow learning and forgetting (to a local Bayes database), reporting
+ and revoking (to a remote database) by spamd. The client issues a
+ TELL command to tell what type of message is being processed and
+ whether local (learn/forget) or remote (report/revoke) databases
+ should be updated.
+
+ Note that spamd always trusts the username passed in (unless
+ --auth-ident is used) so clients could maliciously learn messages
+ for other users. (This is not ususally a concern with an SQL Bayes
+ store as users will typically have read-write access directly to the
+ database, and can also use "sa-learn" with the -u option to achieve
+ the same result.)
+
+ -c, --create-prefs
+ Create user preferences files if they don't exist (default: don't).
+
+ -C *path*, --configpath=*path*
+ Use the specified path for locating the distributed configuration
+ files. Ignore the default directories (usually
+ "/usr/share/spamassassin" or similar).
+
+ --siteconfigpath=*path*
+ Use the specified path for locating site-specific configuration
+ files. Ignore the default directories (usually
+ "/etc/mail/spamassassin" or similar).
+
+ --cf='config line'
+ Add additional lines of configuration directly from the
+ command-line, parsed after the configuration files are read.
+ Multiple --cf arguments can be used, and each will be considered a
+ separate line of configuration.
+
+ -d, --daemonize
+ Detach from starting process and run in background (daemonize).
+
+ -h, --help
+ Print a brief help message, then exit without further action.
+
+ -V, --version
+ Print version information, then exit without further action.
+
+ -i [*ipaddress*], --listen-ip[=*ipaddress*], --ip-address[=*ipaddress*]
+ Tells spamd to listen on the specified IP address (defaults to
+ 127.0.0.1). If you specify no IP address after the switch, spamd
+ will listen on all interfaces. (This is equal to the address
+ 0.0.0.0). You can also use a valid hostname which will make spamd
+ listen on the first address that name resolves to.
+
+ -p *port*, --port=*port*
+ Optionally specifies the port number for the server to listen on
+ (default: 783).
+
+ If the --ssl switch is used, and --ssl-port is not supplied, then
+ this port will be used to accept SSL connections instead of
+ unencrypted connections. If the --ssl switch is used, and --ssl-port
+ is set, then unencrypted connections will be accepted on the --port
+ at the same time as encrypted connections are accepted at
+ --ssl-port.
+
+ -q, --sql-config
+ Turn on SQL lookups even when per-user config files have been
+ disabled with -x. this is useful for spamd hosts which don't have
+ user's home directories but do want to load user preferences from an
+ SQL database.
+
+ If your spamc client does not support sending the "User:" header,
+ like "exiscan", then the SQL username used will always be nobody.
+
+ This inhibits the setuid() behavior, so the "-u" option is required.
+ If you want the setuid() behaviour, use "-Q" or "--setuid-with-sql"
+ instead.
+
+ --ldap-config
+ Turn on LDAP lookups. This is completely analog to "--sql-config",
+ only it is using an LDAP server.
+
+ Like "--sql-config", this disables the setuid behavior, and requires
+ "-u". If you want it, use "--setuid-with-ldap" instead.
+
+ -Q, --setuid-with-sql
+ Turn on SQL lookups even when per-user config files have been
+ disabled with -x and also setuid to the user. This is useful for
+ spamd hosts which want to load user preferences from an SQL database
+ but also wish to support the use of -H (Helper home directories.)
+
+ --setuid-with-ldap
+ Turn on LDAP lookups even when per-user config files have been
+ disabled with -x and also setuid to the user. This is again
+ completely analog to "--setuid-with-sql", only it is using an LDAP
+ server.
+
+ --virtual-config-dir=*pattern*
+ This option specifies where per-user preferences can be found for
+ virtual users, for the -x switch. The *pattern* is used as a base
+ pattern for the directory name. Any of the following escapes can be
+ used:
+
+ %u -- replaced with the full name of the current user, as sent by
+ spamc.
+ %l -- replaced with the 'local part' of the current username. In
+ other words, if the username is an email address, this is the part
+ before the "@" sign.
+ %d -- replaced with the 'domain' of the current username. In other
+ words, if the username is an email address, this is the part after
+ the "@" sign.
+ %% -- replaced with a single percent sign (%).
+
+ So for example, if "/vhome/users/%u/spamassassin" is specified, and
+ spamc sends a virtual username of "jm@example.com", the directory
+ "/vhome/users/jm@example.com/spamassassin" will be used.
+
+ The set of characters allowed in the virtual username for this path
+ are restricted to:
+
+ A-Z a-z 0-9 - + _ . , @ =
+
+ All others will be replaced by underscores ("_").
+
+ This path must be a writable directory. It will be created if it
+ does not already exist. If a file called user_prefs exists in this
+ directory (note: not in a ".spamassassin" subdirectory!), it will be
+ loaded as the user's preferences. The Bayes databases for that user
+ will be stored in this directory.
+
+ Note that this requires that -x is used, and cannot be combined with
+ SQL- or LDAP-based configuration.
+
+ The pattern must expand to an absolute directory when spamd is
+ running daemonized (-d).
+
+ Currently, use of this without -u is not supported. This inhibits
+ setuid.
+
+ -r *pidfile*, --pidfile=*pidfile*
+ Write the process ID of the spamd parent to the file specified by
+ *pidfile*. The file will be unlinked when the parent exits. Note
+ that when running with the -u option, the file must be writable by
+ that user.
+
+ -v, --vpopmail
+ Enable vpopmail config. If specified with with -u set to the
+ vpopmail user, this allows spamd to lookup/create user_prefs in the
+ vpopmail user's own maildir. This option is useful for vpopmail
+ virtual users who do not have an entry in the system /etc/passwd
+ file.
+
+ Currently, use of this without -u is not supported. This inhibits
+ setuid.
+
+ -s *facility*, --syslog=*facility*
+ Specify the syslog facility to use (default: mail). If "stderr" is
+ specified, output will be written to stderr. (This is useful if
+ you're running "spamd" under the "daemontools" package.) With a
+ *facility* of "file", all output goes to spamd.log. *facility* is
+ interpreted as a file name to log to if it contains any characters
+ except a-z and 0-9. "null" disables logging completely (used
+ internally).
+
+ Examples: spamd -s mail # use syslog, facility mail (default) spamd
+ -s ./mail # log to file ./mail spamd -s stderr 2>/dev/null # log to
+ stderr, throw messages away spamd -s null # the same as above spamd
+ -s file # log to file ./spamd.log spamd -s /var/log/spamd.log # log
+ to file /var/log/spamd.log
+
+ If logging to a file is enabled and that log file is rotated, the
+ spamd server must be restarted with a SIGHUP. (If the log file is
+ just truncated, this is not needed but still recommended.)
+
+ Note that logging to a file does not use locking, so you cannot
+ intermix logging from spamd and other processes into the same file.
+ If you want to mix logging like this, use syslog instead.
+
+ If you use syslog logging, it is essential to send a SIGHUP to the
+ spamd daemon when you restart the syslogd daemon. (This is due to a
+ shortcoming in Perl's syslog handling, where the disappearance of
+ the connection to the syslogd is considered a fatal error.)
+
+ --syslog-socket=*type*
+ Specify how spamd should send messages to syslogd. The *type* can be
+ any of the socket types or logging mechanisms as accepted by the
+ subroutine Sys::Syslog::setlogsock(). Depending on a version of
+ Sys::Syslog and on the underlying operating system, one of the
+ following values (or their subset) can be used: "native",
+ "eventlog", "tcp", "udp", "inet", "unix", "stream", "pipe", or
+ "console". The value "eventlog" is specific to Win32 events logger
+ and requires a perl module Win32::EventLog to be installed. For more
+ information please consult the Sys::Syslog documentation.
+
+ A historical setting --syslog-socket=none is mapped to
+ --syslog=stderr.
+
+ A default for Windows platforms is "none", otherwise the default is
+ to try "unix" first, falling back to "inet" if perl detects errors
+ in its "unix" support.
+
+ Some platforms, or versions of perl, are shipped with old or
+ dysfunctional versions of the Sys::Syslog module which do not
+ support some socket types, so you may need to set this option
+ explicitly. If you get error messages regarding __PATH_LOG or
+ similar spamd, try changing this setting.
+
+ The socket types "file" is used internally and should not be
+ specified. Use the "-s" switch instead.
+
+ --log-timestamp-fmt=*format*
+ The --log-timestamp-fmt option can provide a POSIX strftime(3)
+ format for timestamps included in each logged message. Each logger
+ (stderr, file, syslog) has its own default value for a timestamp
+ format, which applies when --log-timestamp-fmt option is not given,
+ or with --log-timestamp-fmt=default . Timestamps can be turned off
+ by specifying an empty string with this option, e.g.
+ --log-timestamp-fmt='' or just --log-timestamp-fmt= . Typical use:
+ --log-timestamp-fmt='%a %b %e %H:%M:%S %Y' (provides localized
+ weekday and month names in the ctime(3) style), or '%a, %e %b %Y
+ %H:%M:%S %z (%Z)' for a RFC 2822 format, or maybe '%Y-%m-%d
+ %H:%M:%S%z' for an ISO 8601 (EN 28601) format, or just
+ '%Y%m%dT%H%M%S' .
+
+ -u *username*, --username=*username*
+ Run as the named user. If this option is not set, the default
+ behaviour is to setuid() to the user running "spamc", if "spamd" is
+ running as root.
+
+ Note: "--username=root" is not a valid option. If specified, "spamd"
+ will exit with a fatal error on startup.
+
+ -g *groupname*, --groupname=*groupname*
+ Run as the named group if --username is being used. If this option
+ is not set when --username is used then the primary group for the
+ user given to --username is used.
+
+ -x, --nouser-config, --user-config
+ Turn off (on) reading of per-user configuration files (user_prefs)
+ from the user's home directory. The default behaviour is to read
+ per-user configuration from the user's home directory
+ (--user-config).
+
+ This option does not disable or otherwise influence the SQL, LDAP or
+ Virtual Config Dir settings.
+
+ --auth-ident
+ Verify the username provided by spamc using ident. This is only
+ useful if connections are only allowed from trusted hosts (because
+ an identd that lies is trivial to create) and if spamc REALLY SHOULD
+ be running as the user it represents. Connections are terminated
+ immediately if authentication fails. In this case, spamc will pass
+ the mail through unchecked. Failure to connect to an ident server,
+ and response timeouts are considered authentication failures. This
+ requires that Net::Ident be installed.
+
+ --ident-timeout=*timeout*
+ Wait at most *timeout* seconds for a response to ident queries.
+ Authentication that takes long that *timeout* seconds will fail, and
+ mail will not be processed. Setting this to 0.0 or less results in
+ no timeout, which is STRONGLY discouraged. The default is 5 seconds.
+
+ -A *host,...*, --allowed-ips=*host,...*
+ Specify a list of authorized hosts or networks which can connect to
+ this spamd instance. Single IP addresses can be given, ranges of IP
+ addresses in address/masklength CIDR format, or ranges of IP
+ addresses by listing 3 or less octets with a trailing dot. Hostnames
+ are not supported, only IP addresses. This option can be specified
+ multiple times, or can take a list of addresses separated by commas.
+ Examples:
+
+ -A 10.11.12.13 -- only allow connections from 10.11.12.13.
+
+ -A 10.11.12.13,10.11.12.14 -- only allow connections from
+ 10.11.12.13 and 10.11.12.14.
+
+ -A 10.200.300.0/24 -- allow connections from any machine in the
+ range "10.200.300.*".
+
+ -A 10. -- allow connections from any machine in the range
+ "10.*.*.*".
+
+ By default, connections are only accepted from localhost
+ [127.0.0.1].
+
+ -D [*area,...*], --debug [*area,...*]
+ Produce debugging output. If no areas are listed, all debugging
+ information is printed. Diagnostic output can also be enabled for
+ each area individually; *area* is the area of the code to
+ instrument. For example, to produce diagnostic output on bayes,
+ learn, and dns, use:
+
+ spamassassin -D bayes,learn,dns
+
+ Higher priority informational messages that are suitable for logging
+ in normal circumstances are available with an area of "info".
+
+ For more information about which areas (also known as channels) are
+ available, please see the documentation at:
+
+ C<http://wiki.apache.org/spamassassin/DebugChannels>
+
+ --ipv4only, --ipv4-only, --ipv4
+ Do not use IPv6 for DNS tests. Use if the existing tests for IPv6
+ availability produce incorrect results or crashes.
+
+ -L, --local
+ Perform only local tests on all mail. In other words, skip DNS and
+ other network tests. Works the same as the "-L" flag to
+ spamassassin(1).
+
+ -P, --paranoid
+ Die on user errors (for the user passed from spamc) instead of
+ falling back to user *nobody* and using the default configuration.
+
+ -m *number* , --max-children=*number*
+ This option specifies the maximum number of children to spawn. Spamd
+ will spawn that number of children, then sleep in the background
+ until a child dies, wherein it will go and spawn a new child.
+
+ Incoming connections can still occur if all of the children are
+ busy, however those connections will be queued waiting for a free
+ child. The minimum value is 1, the default value is 5.
+
+ Please note that there is a OS specific maximum of connections that
+ can be queued (Try "perl -MSocket -e'print SOMAXCONN'" to find this
+ maximum).
+
+ Note that if you run too many servers for the amount of free RAM
+ available, you run the danger of hurting performance by causing a
+ high swap load as server processes are swapped in and out
+ continually.
+
+ --min-children=*number*
+ The minimum number of children that will be kept running. The
+ minimum value is 1, the default value is 1. If you have lots of free
+ RAM, you may want to increase this.
+
+ --min-spare=*number*
+ The lower limit for the number of spare children allowed to run. A
+ spare, or idle, child is one that is not handling a scan request. If
+ there are too few spare children available, a new server will be
+ started every second or so. The default value is 1.
+
+ --max-spare=*number*
+ The upper limit for the number of spare children allowed to run. If
+ there are too many spare children, one will be killed every second
+ or so until the number of idle children is in the desired range. The
+ default value is 2.
+
+ --max-conn-per-child=*number*
+ This option specifies the maximum number of connections each child
+ should process before dying and letting the master spamd process
+ spawn a new child. The minimum value is 1, the default value is 200.
+
+ --round-robin
+ By default, "spamd" will attempt to keep a small number of "hot"
+ child processes as busy as possible, and keep any others as idle as
+ possible, using something similar to the Apache httpd server scaling
+ algorithm. This is accomplished by the master process coordinating
+ the activities of the children. This switch will disable this
+ scaling algorithm, and the behaviour seen in the 3.0.x versions will
+ be used instead, where all processes receive an equal load and no
+ scaling takes place.
+
+ --timeout-tcp=*number*
+ This option specifies the number of seconds to wait for headers from
+ a client (spamc) before closing the connection. The minimum value is
+ 1, the default value is 30, and a value of 0 will disable socket
+ timeouts completely.
+
+ --timeout-child=*number*
+ This option specifies the number of seconds to wait for a spamd
+ child to process or check a message. The minimum value is 1, the
+ default value is 300, and a value of 0 will disable child timeouts
+ completely.
+
+ -H *directory*, --helper-home-dir=*directory*
+ Specify that external programs such as Razor, DCC, and Pyzor should
+ have a HOME environment variable set to a specific directory. The
+ default is to use the HOME environment variable setting from the
+ shell running spamd. By specifying no argument, spamd will use the
+ spamc caller's home directory instead.
+
+ --ssl
+ Accept only SSL connections on the associated port. The
+ IO::Socket::SSL perl module must be installed.
+
+ If the --ssl switch is used, and --ssl-port is not supplied, then
+ --port port will be used to accept SSL connections instead of
+ unencrypted connections. If the --ssl switch is used, and --ssl-port
+ is set, then unencrypted connections will be accepted on the --port,
+ at the same time as encrypted connections are accepted at
+ --ssl-port.
+
+ --ssl-port=*port*
+ Optionally specifies the port number for the server to listen on for
+ SSL connections (default: whatever --port uses). See --ssl for more
+ details.
+
+ --ssl-version=*sslversion*
+ Specify the SSL protocol version to use, one of sslv3 or tlsv1. The
+ default, sslv3, is the most flexible, accepting a SSLv3 or higher
+ hello handshake, then negotiating use of SSLv3 or TLSv1 protocol if
+ the client can accept it. Specifying --ssl-version implies --ssl.
+
+ --server-key *keyfile*
+ Specify the SSL key file to use for SSL connections.
+
+ --server-cert *certfile*
+ Specify the SSL certificate file to use for SSL connections.
+
+ --socketpath *pathname*
+ Listen on UNIX domain path *pathname* instead of a TCP socket.
+
+ Warning: the Perl support on BSD platforms for UNIX domain sockets
+ seems to have a bug regarding paths of over 100 bytes or so
+ (SpamAssassin bug 4380). If you see a 'could not find newly-created
+ UNIX socket' error message, and the path appears truncated, this may
+ be the cause. Try using a shorter path to the socket.
+
+ By default, use of --socketpath will inhibit SSL connections and
+ unencrypted TCP connections. To enable them, specify --port and/or
+ --ssl-port explicitly.
+
+ --socketowner *name*
+ Set UNIX domain socket to be owned by the user named *name*. Note
+ that this requires that spamd be started as "root", and if "-u" is
+ used, that user should have write permissions to unlink the file
+ later, for when the "spamd" server is killed.
+
+ --socketgroup *name*
+ Set UNIX domain socket to be owned by the group named *name*. See
+ "--socketowner" for notes on ownership and permissions.
+
+ --socketmode *mode*
+ Set UNIX domain socket to use the octal mode *mode*. Note that if
+ "-u" is used, that user should have write permissions to unlink the
+ file later, for when the "spamd" server is killed.
+
+SEE ALSO
+ spamc(1) spamassassin(1) Mail::SpamAssassin::Conf(3)
+ Mail::SpamAssassin(3)
+
+PREREQUISITES
+ "Mail::SpamAssassin"
+
+AUTHORS
+ The SpamAssassin(tm) Project (http://spamassassin.apache.org/)
+
+LICENSE
+ SpamAssassin is distributed under the Apache License, Version 2.0, as
+ described in the file "LICENSE" included with the distribution.
+