1SPAMD(1) User Contributed Perl Documentation SPAMD(1)
2
6 spamd - daemonized version of spamassassin
7
9 spamd [options]
10 Options:
12 -l, --allow-tell Allow learning/reporting
14 -c, --create-prefs Create user preferences files
15 -C path, --configpath=path Path for default config files
16 --siteconfigpath=path Path for site configs
17 --cf='config line' Additional line of configuration
18 -d, --daemonize Daemonize
19 -h, --help Print usage message
20 -i [ipaddr], --listen-ip=ipaddr Listen on the IP ipaddr
21 --ipv4only, --ipv4-only, --ipv4 Disable attempted use of ipv6 for DNS
22 -p port, --port=port Listen on specified port
23 -m num, --max-children=num Allow maximum num children
24 --min-children=num Allow minimum num children
25 --min-spare=num Lower limit for number of spare children
26 --max-spare=num Upper limit for number of spare children
27 --max-conn-per-child=num Maximum connections accepted by child
28 before it is respawned
29 --round-robin Use traditional prefork algorithm
30 --timeout-tcp=secs Connection timeout for client headers
31 --timeout-child=secs Connection timeout for message checks
32 -q, --sql-config Enable SQL config (needs -x)
33 -Q, --setuid-with-sql Enable SQL config (needs -x,
34 enables use of -H)
35 --ldap-config Enable LDAP config (needs -x)
36 --setuid-with-ldap Enable LDAP config (needs -x,
37 enables use of -H)
38 --virtual-config-dir=dir Enable pattern based Virtual configs
39 (needs -x)
40 -r pidfile, --pidfile Write the process id to pidfile
41 -s facility, --syslog=facility Specify the syslog facility
42 --syslog-socket=type How to connect to syslogd
43 --log-timestamp-fmt=fmt strftime(3) format for timestamps, may be
44 empty to disable timestamps, or 'default'
45 -u username, --username=username Run as username
46 -g groupname, --groupname=groupname Run as groupname
47 -v, --vpopmail Enable vpopmail config
48 -x, --nouser-config Disable user config files
49 --auth-ident Use ident to authenticate spamc user
50 --ident-timeout=timeout Timeout for ident connections
51 -A host,..., --allowed-ips=..,.. Limit ip addresses which can connect
52 -D, --debug[=areas] Print debugging messages (for areas)
53 -L, --local Use local tests only (no DNS)
54 -P, --paranoid Die upon user errors
55 -H [dir], --helper-home-dir[=dir] Specify a different HOME directory
56 --ssl Run an SSL server
57 --ssl-port port Listen on port for SSL connections
58 --ssl-version sslversion Specify SSL protocol version to use
59 --server-key keyfile Specify an SSL keyfile
60 --server-cert certfile Specify an SSL certificate
61 --socketpath=path Listen on given UNIX domain socket
62 --socketowner=name Set UNIX domain socket file's owner
63 --socketgroup=name Set UNIX domain socket file's group
64 --socketmode=mode Set UNIX domain socket file's mode
65 -V, --version Print version and exit
66
68 The purpose of this program is to provide a daemonized version of the
69 spamassassin executable. The goal is improving throughput performance
70 for automated mail checking.
71 This is intended to be used alongside "spamc", a fast, low-overhead C
73 client program.
74 See the README file in the "spamd" directory of the SpamAssassin
76 distribution for more details.
77 Note: Although "spamd" will check per-user config files for every
79 message, any changes to the system-wide config files will require
80 either restarting spamd or forcing it to reload itself via SIGHUP for
81 the changes to take effect.
82 Note: If "spamd" receives a SIGHUP, it internally reloads itself, which
84 means that it will change its pid and might not restart at all if its
85 environment changed (ie. if it can't change back into its own
86 directory). If you plan to use SIGHUP, you should always start "spamd"
87 with the -r switch to know its current pid.
88
90 Options of the long form can be shortened as long as they remain
91 unambiguous. (i.e. --dae can be used instead of --daemonize) Also,
92 boolean options (like --user-config) can be negated by adding no
93 (--nouser-config), however, this is usually unnecessary.
94 -l, --allow-tell
96 Allow learning and forgetting (to a local Bayes database),
97 reporting and revoking (to a remote database) by spamd. The client
98 issues a TELL command to tell what type of message is being
99 processed and whether local (learn/forget) or remote
100 (report/revoke) databases should be updated.
101 Note that spamd always trusts the username passed in (unless
103 --auth-ident is used) so clients could maliciously learn messages
104 for other users. (This is not ususally a concern with an SQL Bayes
105 store as users will typically have read-write access directly to
106 the database, and can also use "sa-learn" with the -u option to
107 achieve the same result.)
108 -c, --create-prefs
110 Create user preferences files if they don't exist (default: don't).
111 -C path, --configpath=path
113 Use the specified path for locating the distributed configuration
114 files. Ignore the default directories (usually
115 "/usr/share/spamassassin" or similar).
116 --siteconfigpath=path
118 Use the specified path for locating site-specific configuration
119 files. Ignore the default directories (usually
120 "/etc/mail/spamassassin" or similar).
121 --cf='config line'
123 Add additional lines of configuration directly from the command-
124 line, parsed after the configuration files are read. Multiple
125 --cf arguments can be used, and each will be considered a separate
126 line of configuration.
127 -d, --daemonize
129 Detach from starting process and run in background (daemonize).
130 -h, --help
132 Print a brief help message, then exit without further action.
133 -V, --version
135 Print version information, then exit without further action.
136 -i [ipaddress], --listen-ip[=ipaddress], --ip-address[=ipaddress]
138 Tells spamd to listen on the specified IP address (defaults to
139 127.0.0.1). If you specify no IP address after the switch, spamd
140 will listen on all interfaces. (This is equal to the address
141 0.0.0.0). You can also use a valid hostname which will make spamd
142 listen on the first address that name resolves to.
143 -p port, --port=port
145 Optionally specifies the port number for the server to listen on
146 (default: 783).
147 If the --ssl switch is used, and --ssl-port is not supplied, then
149 this port will be used to accept SSL connections instead of
150 unencrypted connections. If the --ssl switch is used, and
151 --ssl-port is set, then unencrypted connections will be accepted on
152 the --port at the same time as encrypted connections are accepted
153 at --ssl-port.
154 -q, --sql-config
156 Turn on SQL lookups even when per-user config files have been
157 disabled with -x. this is useful for spamd hosts which don't have
158 user's home directories but do want to load user preferences from
159 an SQL database.
160 If your spamc client does not support sending the "User:" header,
162 like "exiscan", then the SQL username used will always be nobody.
163 This inhibits the setuid() behavior, so the "-u" option is
165 required. If you want the setuid() behaviour, use "-Q" or
166 "--setuid-with-sql" instead.
167 --ldap-config
169 Turn on LDAP lookups. This is completely analog to "--sql-config",
170 only it is using an LDAP server.
171 Like "--sql-config", this disables the setuid behavior, and
173 requires "-u". If you want it, use "--setuid-with-ldap" instead.
174 -Q, --setuid-with-sql
176 Turn on SQL lookups even when per-user config files have been
177 disabled with -x and also setuid to the user. This is useful for
178 spamd hosts which want to load user preferences from an SQL
179 database but also wish to support the use of -H (Helper home
180 directories.)
181 --setuid-with-ldap
183 Turn on LDAP lookups even when per-user config files have been
184 disabled with -x and also setuid to the user. This is again
185 completely analog to "--setuid-with-sql", only it is using an LDAP
186 server.
187 --virtual-config-dir=pattern
189 This option specifies where per-user preferences can be found for
190 virtual users, for the -x switch. The pattern is used as a base
191 pattern for the directory name. Any of the following escapes can
192 be used:
193 %u -- replaced with the full name of the current user, as sent by
195 spamc.
196 %l -- replaced with the 'local part' of the current username. In
197 other words, if the username is an email address, this is the part
198 before the "@" sign.
199 %d -- replaced with the 'domain' of the current username. In other
200 words, if the username is an email address, this is the part after
201 the "@" sign.
202 %% -- replaced with a single percent sign (%).
203 So for example, if "/vhome/users/%u/spamassassin" is specified, and
205 spamc sends a virtual username of "jm@example.com", the directory
206 "/vhome/users/jm@example.com/spamassassin" will be used.
207 The set of characters allowed in the virtual username for this path
209 are restricted to:
210 A-Z a-z 0-9 - + _ . , @ =
212 All others will be replaced by underscores ("_").
214 This path must be a writable directory. It will be created if it
216 does not already exist. If a file called user_prefs exists in this
217 directory (note: not in a ".spamassassin" subdirectory!), it will
218 be loaded as the user's preferences. The Bayes databases for that
219 user will be stored in this directory.
220 Note that this requires that -x is used, and cannot be combined
222 with SQL- or LDAP-based configuration.
223 The pattern must expand to an absolute directory when spamd is
225 running daemonized (-d).
226 Currently, use of this without -u is not supported. This inhibits
228 setuid.
229 -r pidfile, --pidfile=pidfile
231 Write the process ID of the spamd parent to the file specified by
232 pidfile. The file will be unlinked when the parent exits. Note
233 that when running with the -u option, the file must be writable by
234 that user.
235 -v, --vpopmail
237 Enable vpopmail config. If specified with with -u set to the
238 vpopmail user, this allows spamd to lookup/create user_prefs in the
239 vpopmail user's own maildir. This option is useful for vpopmail
240 virtual users who do not have an entry in the system /etc/passwd
241 file.
242 Currently, use of this without -u is not supported. This inhibits
244 setuid.
245 -s facility, --syslog=facility
247 Specify the syslog facility to use (default: mail). If "stderr" is
248 specified, output will be written to stderr. (This is useful if
249 you're running "spamd" under the "daemontools" package.) With a
250 facility of "file", all output goes to spamd.log. facility is
251 interpreted as a file name to log to if it contains any characters
252 except a-z and 0-9. "null" disables logging completely (used
253 internally).
254 Examples: spamd -s mail # use syslog, facility
256 mail (default) spamd -s ./mail # log to file
257 ./mail spamd -s stderr 2>/dev/null # log to stderr, throw
258 messages away spamd -s null # the same as
259 above spamd -s file # log to file ./spamd.log
260 spamd -s /var/log/spamd.log # log to file /var/log/spamd.log
261 If logging to a file is enabled and that log file is rotated, the
263 spamd server must be restarted with a SIGHUP. (If the log file is
264 just truncated, this is not needed but still recommended.)
265 Note that logging to a file does not use locking, so you cannot
267 intermix logging from spamd and other processes into the same file.
268 If you want to mix logging like this, use syslog instead.
269 If you use syslog logging, it is essential to send a SIGHUP to the
271 spamd daemon when you restart the syslogd daemon. (This is due to
272 a shortcoming in Perl's syslog handling, where the disappearance of
273 the connection to the syslogd is considered a fatal error.)
274 --syslog-socket=type
276 Specify how spamd should send messages to syslogd. The type can be
277 any of the socket types or logging mechanisms as accepted by the
278 subroutine Sys::Syslog::setlogsock(). Depending on a version of
279 Sys::Syslog and on the underlying operating system, one of the
280 following values (or their subset) can be used: "native",
281 "eventlog", "tcp", "udp", "inet", "unix", "stream", "pipe", or
282 "console". The value "eventlog" is specific to Win32 events logger
283 and requires a perl module Win32::EventLog to be installed. For
284 more information please consult the Sys::Syslog documentation.
285 A historical setting --syslog-socket=none is mapped to
287 --syslog=stderr.
288 A default for Windows platforms is "none", otherwise the default is
290 to try "unix" first, falling back to "inet" if perl detects errors
291 in its "unix" support.
292 Some platforms, or versions of perl, are shipped with old or
294 dysfunctional versions of the Sys::Syslog module which do not
295 support some socket types, so you may need to set this option
296 explicitly. If you get error messages regarding __PATH_LOG or
297 similar spamd, try changing this setting.
298 The socket types "file" is used internally and should not be
300 specified. Use the "-s" switch instead.
301 --log-timestamp-fmt=format
303 The --log-timestamp-fmt option can provide a POSIX strftime(3)
304 format for timestamps included in each logged message. Each logger
305 (stderr, file, syslog) has its own default value for a timestamp
306 format, which applies when --log-timestamp-fmt option is not given,
307 or with --log-timestamp-fmt=default . Timestamps can be turned off
308 by specifying an empty string with this option, e.g.
309 --log-timestamp-fmt='' or just --log-timestamp-fmt= . Typical use:
310 --log-timestamp-fmt='%a %b %e %H:%M:%S %Y' (provides localized
311 weekday and month names in the ctime(3) style), or '%a, %e %b %Y
312 %H:%M:%S %z (%Z)' for a RFC 2822 format, or maybe '%Y-%m-%d
313 %H:%M:%S%z' for an ISO 8601 (EN 28601) format, or just
314 '%Y%m%dT%H%M%S' .
315 -u username, --username=username
317 Run as the named user. If this option is not set, the default
318 behaviour is to setuid() to the user running "spamc", if "spamd" is
319 running as root.
320 Note: "--username=root" is not a valid option. If specified,
322 "spamd" will exit with a fatal error on startup.
323 -g groupname, --groupname=groupname
325 Run as the named group if --username is being used. If this option
326 is not set when --username is used then the primary group for the
327 user given to --username is used.
328 -x, --nouser-config, --user-config
330 Turn off (on) reading of per-user configuration files (user_prefs)
331 from the user's home directory. The default behaviour is to read
332 per-user configuration from the user's home directory
333 (--user-config).
334 This option does not disable or otherwise influence the SQL, LDAP
336 or Virtual Config Dir settings.
337 --auth-ident
339 Verify the username provided by spamc using ident. This is only
340 useful if connections are only allowed from trusted hosts (because
341 an identd that lies is trivial to create) and if spamc REALLY
342 SHOULD be running as the user it represents. Connections are
343 terminated immediately if authentication fails. In this case,
344 spamc will pass the mail through unchecked. Failure to connect to
345 an ident server, and response timeouts are considered
346 authentication failures. This requires that Net::Ident be
347 installed.
348 --ident-timeout=timeout
350 Wait at most timeout seconds for a response to ident queries.
351 Authentication that takes long that timeout seconds will fail, and
352 mail will not be processed. Setting this to 0.0 or less results in
353 no timeout, which is STRONGLY discouraged. The default is 5
354 seconds.
355 -A host,..., --allowed-ips=host,...
357 Specify a list of authorized hosts or networks which can connect to
358 this spamd instance. Single IP addresses can be given, ranges of IP
359 addresses in address/masklength CIDR format, or ranges of IP
360 addresses by listing 3 or less octets with a trailing dot.
361 Hostnames are not supported, only IP addresses. This option can be
362 specified multiple times, or can take a list of addresses separated
363 by commas. Examples:
364 -A 10.11.12.13 -- only allow connections from 10.11.12.13.
366 -A 10.11.12.13,10.11.12.14 -- only allow connections from
368 10.11.12.13 and 10.11.12.14.
369 -A 10.200.300.0/24 -- allow connections from any machine in the
371 range "10.200.300.*".
372 -A 10. -- allow connections from any machine in the range
374 "10.*.*.*".
375 By default, connections are only accepted from localhost
377 [127.0.0.1].
378 -D [area,...], --debug [area,...]
380 Produce debugging output. If no areas are listed, all debugging
381 information is printed. Diagnostic output can also be enabled for
382 each area individually; area is the area of the code to instrument.
383 For example, to produce diagnostic output on bayes, learn, and dns,
384 use:
385 spamassassin -D bayes,learn,dns
387 Higher priority informational messages that are suitable for
389 logging in normal circumstances are available with an area of
390 "info".
391 For more information about which areas (also known as channels) are
393 available, please see the documentation at:
394 C<http://wiki.apache.org/spamassassin/DebugChannels>
396 --ipv4only, --ipv4-only, --ipv4
398 Do not use IPv6 for DNS tests. Use if the existing tests for IPv6
399 availability produce incorrect results or crashes.
400 -L, --local
402 Perform only local tests on all mail. In other words, skip DNS and
403 other network tests. Works the same as the "-L" flag to
404 spamassassin(1).
405 -P, --paranoid
407 Die on user errors (for the user passed from spamc) instead of
408 falling back to user nobody and using the default configuration.
409 -m number , --max-children=number
411 This option specifies the maximum number of children to spawn.
412 Spamd will spawn that number of children, then sleep in the
413 background until a child dies, wherein it will go and spawn a new
414 child.
415 Incoming connections can still occur if all of the children are
417 busy, however those connections will be queued waiting for a free
418 child. The minimum value is 1, the default value is 5.
419 Please note that there is a OS specific maximum of connections that
421 can be queued (Try "perl -MSocket -e'print SOMAXCONN'" to find this
422 maximum).
423 Note that if you run too many servers for the amount of free RAM
425 available, you run the danger of hurting performance by causing a
426 high swap load as server processes are swapped in and out
427 continually.
428 --min-children=number
430 The minimum number of children that will be kept running. The
431 minimum value is 1, the default value is 1. If you have lots of
432 free RAM, you may want to increase this.
433 --min-spare=number
435 The lower limit for the number of spare children allowed to run. A
436 spare, or idle, child is one that is not handling a scan request.
437 If there are too few spare children available, a new server will be
438 started every second or so. The default value is 1.
439 --max-spare=number
441 The upper limit for the number of spare children allowed to run.
442 If there are too many spare children, one will be killed every
443 second or so until the number of idle children is in the desired
444 range. The default value is 2.
445 --max-conn-per-child=number
447 This option specifies the maximum number of connections each child
448 should process before dying and letting the master spamd process
449 spawn a new child. The minimum value is 1, the default value is
450 200.
451 --round-robin
453 By default, "spamd" will attempt to keep a small number of "hot"
454 child processes as busy as possible, and keep any others as idle as
455 possible, using something similar to the Apache httpd server
456 scaling algorithm. This is accomplished by the master process
457 coordinating the activities of the children. This switch will
458 disable this scaling algorithm, and the behaviour seen in the 3.0.x
459 versions will be used instead, where all processes receive an equal
460 load and no scaling takes place.
461 --timeout-tcp=number
463 This option specifies the number of seconds to wait for headers
464 from a client (spamc) before closing the connection. The minimum
465 value is 1, the default value is 30, and a value of 0 will disable
466 socket timeouts completely.
467 --timeout-child=number
469 This option specifies the number of seconds to wait for a spamd
470 child to process or check a message. The minimum value is 1, the
471 default value is 300, and a value of 0 will disable child timeouts
472 completely.
473 -H directory, --helper-home-dir=directory
475 Specify that external programs such as Razor, DCC, and Pyzor should
476 have a HOME environment variable set to a specific directory. The
477 default is to use the HOME environment variable setting from the
478 shell running spamd. By specifying no argument, spamd will use the
479 spamc caller's home directory instead.
480 --ssl
482 Accept only SSL connections on the associated port. The
483 IO::Socket::SSL perl module must be installed.
484 If the --ssl switch is used, and --ssl-port is not supplied, then
486 --port port will be used to accept SSL connections instead of
487 unencrypted connections. If the --ssl switch is used, and
488 --ssl-port is set, then unencrypted connections will be accepted on
489 the --port, at the same time as encrypted connections are accepted
490 at --ssl-port.
491 --ssl-port=port
493 Optionally specifies the port number for the server to listen on
494 for SSL connections (default: whatever --port uses). See --ssl for
495 more details.
496 --ssl-version=sslversion
498 Specify the SSL protocol version to use, one of sslv2, sslv3,
499 tlsv1, or sslv23. The default, sslv23, is the most flexible,
500 accepting a SSLv2 or higher hello handshake, then negotiating use
501 of SSLv3 or TLSv1 protocol if the client can accept it. Specifying
502 --ssl-version implies --ssl.
503 --server-key keyfile
505 Specify the SSL key file to use for SSL connections.
506 --server-cert certfile
508 Specify the SSL certificate file to use for SSL connections.
509 --socketpath pathname
511 Listen on UNIX domain path pathname instead of a TCP socket.
512 Warning: the Perl support on BSD platforms for UNIX domain sockets
514 seems to have a bug regarding paths of over 100 bytes or so
515 (SpamAssassin bug 4380). If you see a 'could not find newly-
516 created UNIX socket' error message, and the path appears truncated,
517 this may be the cause. Try using a shorter path to the socket.
518 By default, use of --socketpath will inhibit SSL connections and
520 unencrypted TCP connections. To enable them, specify --port and/or
521 --ssl-port explicitly.
522 --socketowner name
524 Set UNIX domain socket to be owned by the user named name. Note
525 that this requires that spamd be started as "root", and if "-u" is
526 used, that user should have write permissions to unlink the file
527 later, for when the "spamd" server is killed.
528 --socketgroup name
530 Set UNIX domain socket to be owned by the group named name. See
531 "--socketowner" for notes on ownership and permissions.
532 --socketmode mode
534 Set UNIX domain socket to use the octal mode mode. Note that if
535 "-u" is used, that user should have write permissions to unlink the
536 file later, for when the "spamd" server is killed.
537
539 spamc(1) spamassassin(1) Mail::SpamAssassin::Conf(3)
540 Mail::SpamAssassin(3)
541
543 "Mail::SpamAssassin"
544
546 The SpamAssassin(tm) Project (http://spamassassin.apache.org/)
547
549 SpamAssassin is distributed under the Apache License, Version 2.0, as
550 described in the file "LICENSE" included with the distribution.
551perl v5.12.4 2011-09-13 SPAMD(1)