NAME

spamd - daemonized version of spamassassin


SYNOPSIS

spamd [options]

Options:

 -a, --auto-whitelist, --whitelist  Use auto-whitelists
 -c, --create-prefs                 Create user preferences files
 -C path, --configpath=path         Path for default config files
 --siteconfigpath=path              Path for site configs (def: /etc/mail/spamassassin)
 -d, --daemonize                    Daemonize
 -h, --help                         Print usage message.
 -i ipaddr, --listen-ip=ipaddr,...  Listen on the IP ipaddr (default: 127.0.0.1)
 -m num, --max-children num         Allow maximum num children
 -p port, --port                    Listen on specified port (default: 783)
 -q, --sql-config                   Enable SQL config (only useful with -x)
 -Q, --setuid-with-sql              Enable SQL config (only useful with -x,
                                    enables use of -a and -H)
 -V, --virtual-config=dir           Enable Virtual configs (needs -x)
 --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 (default: mail)
 --syslog-socket=type               How to connect to syslogd (default: unix)
 -u username, --username=username   Run as username
 -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                        Print debugging messages
 -L, --local                        Use local tests only (no DNS)
 -P, --paranoid                     Die upon user errors
 -H dir                             Specify a different HOME directory, path optional
 --ssl                              Run an SSL server
 --server-key keyfile               Specify an SSL keyfile
 --server-cert certfile             Specify an SSL certificate
 --socketpath=path                  Listen on given UNIX domain socket


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 --auto-whitelist) can be negated by adding --no (--noauto-whitelist), however, this is usually unnecessary.

-a, --auto-whitelist, --whitelist
Use auto-whitelists. Auto-whitelists track the long-term average score for each sender and then shift the score of new messages toward that long-term average. This can increase or decrease the score for messages, depending on the long-term behavior of the particular correspondent. See the README file for more details.

-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).

-d, --daemonize
Detach from starting process and run in background (daemonize).

-h, --help
Print a brief help message, 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]. Use 0.0.0.0 to listen on all interfaces.

-p port, --port=port
Optionally specifies the port number for the server to listen on.

-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.

-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 -a (AWL) and -H (Helper home directories.)

--virtual-config-dir=pattern
This option specifies where per-user preferences can be found for virtual users, for the -x switch. If this and the --virtual-config switch are both used, this will take precedence.

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.

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, it will be loaded as the user's preferences. The auto-whitelist and/or 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-based configuration.

The pattern must expand to an absolute directory when spamd is running daemonized (-d).

-V=directory, --virtual-config=directory
This option specifies where per-user preferences can be found for virtual users, for the -x switch.

The files are in the format of username.prefs. A default.prefs file will be used if an individual user config is not found.

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 (_).

Note that this requires that -x is used, and cannot be combined with SQL-based configuration.

If a subdirectory is found in that directory, called username, and it is writable, it will be used to store auto-whitelist and/or Bayes databases for that user.

-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.

If specified without -u, then it allows every mail account on a vpopmail virtual domain setup to have their own user-customizable spamassassin preferences, assuming they have their own home directory set.

-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.

--syslog-socket=type
Specify how spamd should send messages to syslogd. The options are unix, inet or none. 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 dysfunctional versions of the Sys::Syslog package which do not support some socket types, so you may need to set this. If you get error messages regarding __PATH_LOG or similar from spamd, try changing this setting.

-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'' disables the setuid() functionality and leaves spamd running as root.

-x, --nouser-config, --user-config
Turn off(on) per-user config files. All users will just get the default configuration. The default behaviour is for per-user configuration to be off.

--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, --debug
Print debugging messages

-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
Specify a maximum number of children to spawn. Spamd will wait until another child finishes before forking again. Meanwhile, incoming connections will be queued.

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). Also, this option causes spamd to create an extra pipe for each child.

-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. The IO::Socket::SSL perl module must be installed.

--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.


BUGS

Perl 5.005_03 seems to have a bug, which spamd triggers, causing messages to pass through unscanned. Upgrading to Perl 5.6 seems to fix the problem, so that's the current workaround. More information can be found at http://bugzilla.spamassassin.org/show_bug.cgi?id=497

The module IO::Socket::INET from Perl 5.005 needs too much time to shut down the port, so when spamd receives the HUP signal to reload itself, it will die because it can't open that port. Updating IO::Socket or (better) to Perl 5.6 or later should help.

The -m switch seems to trigger signal-handling bugs in many versions of Perl.


SEE ALSO

spamc(1) spamassassin(1) Mail::SpamAssassin(3) Mail::SpamAssassin::Conf(3)


AUTHOR

Craig R Hughes <craig@hughes-family.org>


PREREQUISITES

Mail::SpamAssassin