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 -u username, --username=username Run as username
44 -g groupname, --groupname=groupname Run as groupname
45 -v, --vpopmail Enable vpopmail config
46 -x, --nouser-config Disable user config files
47 --auth-ident Use ident to authenticate spamc user
48 --ident-timeout=timeout Timeout for ident connections
49 -A host,..., --allowed-ips=..,.. Limit ip addresses which can connect
50 -D, --debug[=areas] Print debugging messages (for areas)
51 -L, --local Use local tests only (no DNS)
52 -P, --paranoid Die upon user errors
53 -H [dir], --helper-home-dir[=dir] Specify a different HOME directory
54 --ssl Run an SSL server
55 --ssl-port port Listen on port for SSL connections
56 --ssl-version sslversion Specify SSL protocol version to use
57 --server-key keyfile Specify an SSL keyfile
58 --server-cert certfile Specify an SSL certificate
59 --socketpath=path Listen on given UNIX domain socket
60 --socketowner=name Set UNIX domain socket file's owner
61 --socketgroup=name Set UNIX domain socket file's group
62 --socketmode=mode Set UNIX domain socket file's mode
63 -V, --version Print version and exit
64
66 The purpose of this program is to provide a daemonized version of the
67 spamassassin executable. The goal is improving throughput performance
68 for automated mail checking.
69 This is intended to be used alongside "spamc", a fast, low-overhead C
71 client program.
72 See the README file in the "spamd" directory of the SpamAssassin dis‐
74 tribution for more details.
75 Note: Although "spamd" will check per-user config files for every mes‐
77 sage, any changes to the system-wide config files will require either
78 restarting spamd or forcing it to reload itself via SIGHUP for the
79 changes to take effect.
80 Note: If "spamd" receives a SIGHUP, it internally reloads itself, which
82 means that it will change its pid and might not restart at all if its
83 environment changed (ie. if it can't change back into its own direc‐
84 tory). If you plan to use SIGHUP, you should always start "spamd" with
85 the -r switch to know its current pid.
86
88 Options of the long form can be shortened as long as they remain unam‐
89 biguous. (i.e. --dae can be used instead of --daemonize) Also, boolean
90 options (like --user-config) can be negated by adding no (--nouser-con‐
91 fig), however, this is usually unnecessary.
92 -l, --allow-tell
94 Allow learning and forgetting (to a local Bayes database), report‐
95 ing and revoking (to a remote database) by spamd. The client issues
96 a TELL command to tell what type of message is being processed and
97 whether local (learn/forget) or remote (report/revoke) databases
98 should be updated.
99 Note that spamd always trusts the username passed in (unless
101 --auth-ident is used) so clients could maliciously learn messages
102 for other users. (This is not ususally a concern with an SQL Bayes
103 store as users will typically have read-write access directly to
104 the database, and can also use "sa-learn" with the -u option to
105 achieve the same result.)
106 -c, --create-prefs
108 Create user preferences files if they don't exist (default: don't).
109 -C path, --configpath=path
111 Use the specified path for locating the distributed configuration
112 files. Ignore the default directories (usually "/usr/share/spamas‐
113 sassin" or similar).
114 --siteconfigpath=path
116 Use the specified path for locating site-specific configuration
117 files. Ignore the default directories (usually "/etc/mail/spamas‐
118 sassin" or similar).
119 --cf='config line'
121 Add additional lines of configuration directly from the com‐
122 mand-line, parsed after the configuration files are read. Multi‐
123 ple --cf arguments can be used, and each will be considered a sepa‐
124 rate line of configuration.
125 -d, --daemonize
127 Detach from starting process and run in background (daemonize).
128 -h, --help
130 Print a brief help message, then exit without further action.
131 -V, --version
133 Print version information, then exit without further action.
134 -i [ipaddress], --listen-ip[=ipaddress], --ip-address[=ipaddress]
136 Tells spamd to listen on the specified IP address (defaults to
137 127.0.0.1). If you specify no IP address after the switch, spamd
138 will listen on all interfaces. (This is equal to the address
139 0.0.0.0). You can also use a valid hostname which will make spamd
140 listen on the first address that name resolves to.
141 -p port, --port=port
143 Optionally specifies the port number for the server to listen on
144 (default: 783).
145 If the --ssl switch is used, and --ssl-port is not supplied, then
147 this port will be used to accept SSL connections instead of unen‐
148 crypted connections. If the --ssl switch is used, and --ssl-port
149 is set, then unencrypted connections will be accepted on the --port
150 at the same time as encrypted connections are accepted at
151 --ssl-port.
152 -q, --sql-config
154 Turn on SQL lookups even when per-user config files have been dis‐
155 abled with -x. this is useful for spamd hosts which don't have
156 user's home directories but do want to load user preferences from
157 an SQL database.
158 If your spamc client does not support sending the "User:" header,
160 like "exiscan", then the SQL username used will always be nobody.
161 This inhibits the setuid() behavior, so the "-u" option is
163 required. If you want the setuid() behaviour, use "-Q" or
164 "--setuid-with-sql" instead.
165 --ldap-config
167 Turn on LDAP lookups. This is completely analog to "--sql-config",
168 only it is using an LDAP server.
169 Like "--sql-config", this disables the setuid behavior, and
171 requires "-u". If you want it, use "--setuid-with-ldap" instead.
172 -Q, --setuid-with-sql
174 Turn on SQL lookups even when per-user config files have been dis‐
175 abled with -x and also setuid to the user. This is useful for
176 spamd hosts which want to load user preferences from an SQL data‐
177 base but also wish to support the use of -H (Helper home directo‐
178 ries.)
179 --setuid-with-ldap
181 Turn on LDAP lookups even when per-user config files have been dis‐
182 abled with -x and also setuid to the user. This is again com‐
183 pletely analog to "--setuid-with-sql", only it is using an LDAP
184 server.
185 --virtual-config-dir=pattern
187 This option specifies where per-user preferences can be found for
188 virtual users, for the -x switch. The pattern is used as a base
189 pattern for the directory name. Any of the following escapes can
190 be used:
191 %u -- replaced with the full name of the current user, as sent by
193 spamc.
194 %l -- replaced with the 'local part' of the current username. In
195 other words, if the username is an email address, this is the part
196 before the "@" sign.
197 %d -- replaced with the 'domain' of the current username. In other
198 words, if the username is an email address, this is the part after
199 the "@" sign.
200 %% -- replaced with a single percent sign (%).
201 So for example, if "/vhome/users/%u/spamassassin" is specified, and
203 spamc sends a virtual username of "jm@example.com", the directory
204 "/vhome/users/jm@example.com/spamassassin" will be used.
205 The set of characters allowed in the virtual username for this path
207 are restricted to:
208 A-Z a-z 0-9 - + _ . , @ =
210 All others will be replaced by underscores ("_").
212 This path must be a writable directory. It will be created if it
214 does not already exist. If a file called user_prefs exists in this
215 directory (note: not in a ".spamassassin" subdirectory!), it will
216 be loaded as the user's preferences. The Bayes databases for that
217 user will be stored in this directory.
218 Note that this requires that -x is used, and cannot be combined
220 with SQL- or LDAP-based configuration.
221 The pattern must expand to an absolute directory when spamd is run‐
223 ning daemonized (-d).
224 Currently, use of this without -u is not supported. This inhibits
226 setuid.
227 -r pidfile, --pidfile=pidfile
229 Write the process ID of the spamd parent to the file specified by
230 pidfile. The file will be unlinked when the parent exits. Note
231 that when running with the -u option, the file must be writable by
232 that user.
233 -v, --vpopmail
235 Enable vpopmail config. If specified with with -u set to the vpop‐
236 mail user, this allows spamd to lookup/create user_prefs in the
237 vpopmail user's own maildir. This option is useful for vpopmail
238 virtual users who do not have an entry in the system /etc/passwd
239 file.
240 Currently, use of this without -u is not supported. This inhibits
242 setuid.
243 -s facility, --syslog=facility
245 Specify the syslog facility to use (default: mail). If "stderr" is
246 specified, output will be written to stderr. (This is useful if
247 you're running "spamd" under the "daemontools" package.) With a
248 facility of "file", all output goes to spamd.log. facility is
249 interpreted as a file name to log to if it contains any characters
250 except a-z and 0-9. "null" disables logging completely (used inter‐
251 nally).
252 Examples: spamd -s mail # use syslog, facility
254 mail (default) spamd -s ./mail # log to file
255 ./mail spamd -s stderr 2>/dev/null # log to stderr, throw
256 messages away spamd -s null # the same as
257 above spamd -s file # log to file ./spamd.log
258 spamd -s /var/log/spamd.log # log to file /var/log/spamd.log
259 If logging to a file is enabled and that log file is rotated, the
261 spamd server must be restarted with a SIGHUP. (If the log file is
262 just truncated, this is not needed but still recommended.)
263 Note that logging to a file does not use locking, so you cannot
265 intermix logging from spamd and other processes into the same file.
266 If you want to mix logging like this, use syslog instead.
267 If you use syslog logging, it is essential to send a SIGHUP to the
269 spamd daemon when you restart the syslogd daemon. (This is due to
270 a shortcoming in Perl's syslog handling, where the disappearance of
271 the connection to the syslogd is considered a fatal error.)
272 --syslog-socket=type
274 Specify how spamd should send messages to syslogd. The options are
275 "unix", "inet" or "none". The default is to try "unix" first,
276 falling back to "inet" if perl detects errors in its "unix" sup‐
277 port.
278 Some platforms, or versions of perl, are shipped with dysfunctional
280 versions of the Sys::Syslog package which do not support some
281 socket types, so you may need to set this. If you get error mes‐
282 sages regarding __PATH_LOG or similar from spamd, try changing this
283 setting.
284 The socket type "file" is used internally and should not be speci‐
286 fied. Use the "-s" switch instead.
287 -u username, --username=username
289 Run as the named user. If this option is not set, the default be‐
290 haviour is to setuid() to the user running "spamc", if "spamd" is
291 running as root.
292 Note: "--username=root" is not a valid option. If specified,
294 "spamd" will exit with a fatal error on startup.
295 -g groupname, --groupname=groupname
297 Run as the named group if --username is being used. If this option
298 is not set when --username is used then the primary group for the
299 user given to --username is used.
300 -x, --nouser-config, --user-config
302 Turn off (on) reading of per-user configuration files (user_prefs)
303 from the user's home directory. The default behaviour is to read
304 per-user configuration from the user's home directory (--user-con‐
305 fig).
306 This option does not disable or otherwise influence the SQL, LDAP
308 or Virtual Config Dir settings.
309 --auth-ident
311 Verify the username provided by spamc using ident. This is only
312 useful if connections are only allowed from trusted hosts (because
313 an identd that lies is trivial to create) and if spamc REALLY
314 SHOULD be running as the user it represents. Connections are ter‐
315 minated immediately if authentication fails. In this case, spamc
316 will pass the mail through unchecked. Failure to connect to an
317 ident server, and response timeouts are considered authentication
318 failures. This requires that Net::Ident be installed.
319 --ident-timeout=timeout
321 Wait at most timeout seconds for a response to ident queries.
322 Authentication that takes long that timeout seconds will fail, and
323 mail will not be processed. Setting this to 0.0 or less results in
324 no timeout, which is STRONGLY discouraged. The default is 5 sec‐
325 onds.
326 -A host,..., --allowed-ips=host,...
328 Specify a list of authorized hosts or networks which can connect to
329 this spamd instance. Single IP addresses can be given, ranges of IP
330 addresses in address/masklength CIDR format, or ranges of IP
331 addresses by listing 3 or less octets with a trailing dot. Host‐
332 names are not supported, only IP addresses. This option can be
333 specified multiple times, or can take a list of addresses separated
334 by commas. Examples:
335 -A 10.11.12.13 -- only allow connections from 10.11.12.13.
337 -A 10.11.12.13,10.11.12.14 -- only allow connections from
339 10.11.12.13 and 10.11.12.14.
340 -A 10.200.300.0/24 -- allow connections from any machine in the
342 range "10.200.300.*".
343 -A 10. -- allow connections from any machine in the range
345 "10.*.*.*".
346 By default, connections are only accepted from localhost
348 [127.0.0.1].
349 -D [area,...], --debug [area,...]
351 Produce debugging output. If no areas are listed, all debugging
352 information is printed. Diagnostic output can also be enabled for
353 each area individually; area is the area of the code to instrument.
354 For example, to produce diagnostic output on bayes, learn, and dns,
355 use:
356 spamassassin -D bayes,learn,dns
358 Higher priority informational messages that are suitable for log‐
360 ging in normal circumstances are available with an area of "info".
361 For more information about which areas (also known as channels) are
363 available, please see the documentation at:
364 C<http://wiki.apache.org/spamassassin/DebugChannels>
366 --ipv4only, --ipv4-only, --ipv4
368 Do not use IPv6 for DNS tests. Use if the existing tests for IPv6
369 availablity produce incorrect results or crashes.
370 -L, --local
372 Perform only local tests on all mail. In other words, skip DNS and
373 other network tests. Works the same as the "-L" flag to spamassas‐
374 sin(1).
375 -P, --paranoid
377 Die on user errors (for the user passed from spamc) instead of
378 falling back to user nobody and using the default configuration.
379 -m number , --max-children=number
381 This option specifies the maximum number of children to spawn.
382 Spamd will spawn that number of children, then sleep in the back‐
383 ground until a child dies, wherein it will go and spawn a new
384 child.
385 Incoming connections can still occur if all of the children are
387 busy, however those connections will be queued waiting for a free
388 child. The minimum value is 1, the default value is 5.
389 Please note that there is a OS specific maximum of connections that
391 can be queued (Try "perl -MSocket -e'print SOMAXCONN'" to find this
392 maximum).
393 Note that if you run too many servers for the amount of free RAM
395 available, you run the danger of hurting performance by causing a
396 high swap load as server processes are swapped in and out continu‐
397 ally.
398 --min-children=number
400 The minimum number of children that will be kept running. The min‐
401 imum value is 1, the default value is 1. If you have lots of free
402 RAM, you may want to increase this.
403 --min-spare=number
405 The lower limit for the number of spare children allowed to run. A
406 spare, or idle, child is one that is not handling a scan request.
407 If there are too few spare children available, a new server will be
408 started every second or so. The default value is 1.
409 --max-spare=number
411 The upper limit for the number of spare children allowed to run.
412 If there are too many spare children, one will be killed every sec‐
413 ond or so until the number of idle children is in the desired
414 range. The default value is 2.
415 --max-conn-per-child=number
417 This option specifies the maximum number of connections each child
418 should process before dying and letting the master spamd process
419 spawn a new child. The minimum value is 1, the default value is
420 200.
421 --round-robin
423 By default, "spamd" will attempt to keep a small number of "hot"
424 child processes as busy as possible, and keep any others as idle as
425 possible, using something similar to the Apache httpd server scal‐
426 ing algorithm. This is accomplished by the master process coordi‐
427 nating the activities of the children. This switch will disable
428 this scaling algorithm, and the behaviour seen in the 3.0.x ver‐
429 sions will be used instead, where all processes receive an equal
430 load and no scaling takes place.
431 --timeout-tcp=number
433 This option specifies the number of seconds to wait for headers
434 from a client (spamc) before closing the connection. The minimum
435 value is 1, the default value is 30, and a value of 0 will disable
436 socket timeouts completely.
437 --timeout-child=number
439 This option specifies the number of seconds to wait for a spamd
440 child to to process or check a message. The minimum value is 1,
441 the default value is 300, and a value of 0 will disable child time‐
442 outs completely.
443 -H directory, --helper-home-dir=directory
445 Specify that external programs such as Razor, DCC, and Pyzor should
446 have a HOME environment variable set to a specific directory. The
447 default is to use the HOME environment variable setting from the
448 shell running spamd. By specifying no argument, spamd will use the
449 spamc caller's home directory instead.
450 --ssl
452 Accept only SSL connections on the associated port. The
453 IO::Socket::SSL perl module must be installed.
454 If the --ssl switch is used, and --ssl-port is not supplied, then
456 --port port will be used to accept SSL connections instead of unen‐
457 crypted connections. If the --ssl switch is used, and --ssl-port
458 is set, then unencrypted connections will be accepted on the
459 --port, at the same time as encrypted connections are accepted at
460 --ssl-port.
461 --ssl-port=port
463 Optionally specifies the port number for the server to listen on
464 for SSL connections (default: whatever --port uses). See --ssl for
465 more details.
466 --ssl-version=sslversion
468 Specify the SSL protocol version to use, one of sslv2, sslv3,
469 tlsv1, or sslv23. The default, sslv23, is the most flexible,
470 accepting a SSLv2 or higher hello handshake, then negotiating use
471 of SSLv3 or TLSv1 protocol if the client can accept it. Specifying
472 --ssl-version implies --ssl.
473 --server-key keyfile
475 Specify the SSL key file to use for SSL connections.
476 --server-cert certfile
478 Specify the SSL certificate file to use for SSL connections.
479 --socketpath pathname
481 Listen on UNIX domain path pathname instead of a TCP socket.
482 Warning: the Perl support on BSD platforms for UNIX domain sockets
484 seems to have a bug regarding paths of over 100 bytes or so (Spa‐
485 mAssassin bug 4380). If you see a 'could not find newly-created
486 UNIX socket' error message, and the path appears truncated, this
487 may be the cause. Try using a shorter path to the socket.
488 By default, use of --socketpath will inhibit SSL connections and
490 unencrypted TCP connections. To enable them, specify --port and/or
491 --ssl-port explicitly.
492 --socketowner name
494 Set UNIX domain socket to be owned by the user named name. Note
495 that this requires that spamd be started as "root", and if "-u" is
496 used, that user should have write permissions to unlink the file
497 later, for when the "spamd" server is killed.
498 --socketgroup name
500 Set UNIX domain socket to be owned by the group named name. See
501 "--socketowner" for notes on ownership and permissions.
502 --socketmode mode
504 Set UNIX domain socket to use the octal mode mode. Note that if
505 "-u" is used, that user should have write permissions to unlink the
506 file later, for when the "spamd" server is killed.
507
509 spamc(1) spamassassin(1) Mail::SpamAssassin::Conf(3) Mail::SpamAssas‐
510 sin(3)
511
513 "Mail::SpamAssassin"
514
516 The SpamAssassin(tm) Project (http://spamassassin.apache.org/)
517
519 SpamAssassin is distributed under the Apache License, Version 2.0, as
520 described in the file "LICENSE" included with the distribution.
521perl v5.8.8 2008-01-29 SPAMD(1)