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
74 distribution for more details.
75 Note: Although "spamd" will check per-user config files for every
77 message, any changes to the system-wide config files will require
78 either restarting spamd or forcing it to reload itself via SIGHUP for
79 the 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
84 directory). If you plan to use SIGHUP, you should always start "spamd"
85 with the -r switch to know its current pid.
86
88 Options of the long form can be shortened as long as they remain
89 unambiguous. (i.e. --dae can be used instead of --daemonize) Also,
90 boolean options (like --user-config) can be negated by adding no
91 (--nouser-config), however, this is usually unnecessary.
92 -l, --allow-tell
94 Allow learning and forgetting (to a local Bayes database),
95 reporting and revoking (to a remote database) by spamd. The client
96 issues a TELL command to tell what type of message is being
97 processed and whether local (learn/forget) or remote
98 (report/revoke) databases 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
113 "/usr/share/spamassassin" or similar).
114 --siteconfigpath=path
116 Use the specified path for locating site-specific configuration
117 files. Ignore the default directories (usually
118 "/etc/mail/spamassassin" or similar).
119 --cf='config line'
121 Add additional lines of configuration directly from the command-
122 line, parsed after the configuration files are read. Multiple
123 --cf arguments can be used, and each will be considered a separate
124 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
148 unencrypted connections. If the --ssl switch is used, and
149 --ssl-port is set, then unencrypted connections will be accepted on
150 the --port at the same time as encrypted connections are accepted
151 at --ssl-port.
152 -q, --sql-config
154 Turn on SQL lookups even when per-user config files have been
155 disabled 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
175 disabled with -x and also setuid to the user. This is useful for
176 spamd hosts which want to load user preferences from an SQL
177 database but also wish to support the use of -H (Helper home
178 directories.)
179 --setuid-with-ldap
181 Turn on LDAP lookups even when per-user config files have been
182 disabled with -x and also setuid to the user. This is again
183 completely 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
223 running 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
236 vpopmail 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
251 internally).
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 type can be
275 any of the socket types or logging mechanisms as accepted by the
276 subroutine Sys::Syslog::setlogsock(). Depending on a version of
277 Sys::Syslog and on the underlying operating system, one of the
278 following values (or their subset) can be used: "native",
279 "eventlog", "tcp", "udp", "inet", "unix", "stream", "pipe", or
280 "console". The value "eventlog" is specific to Win32 events logger
281 and requires a perl module Win32::EventLog to be installed. For
282 more information please consult the Sys::Syslog documentation.
283 A historical setting --syslog-socket=none is mapped to
285 --syslog=stderr.
286 A default for Windows platforms is "none", otherwise the default is
288 to try "unix" first, falling back to "inet" if perl detects errors
289 in its "unix" support.
290 Some platforms, or versions of perl, are shipped with old or
292 dysfunctional versions of the Sys::Syslog module which do not
293 support some socket types, so you may need to set this option
294 explicitly. If you get error messages regarding __PATH_LOG or
295 similar spamd, try changing this setting.
296 The socket types "file" is used internally and should not be
298 specified. Use the "-s" switch instead.
299 -u username, --username=username
301 Run as the named user. If this option is not set, the default
302 behaviour is to setuid() to the user running "spamc", if "spamd" is
303 running as root.
304 Note: "--username=root" is not a valid option. If specified,
306 "spamd" will exit with a fatal error on startup.
307 -g groupname, --groupname=groupname
309 Run as the named group if --username is being used. If this option
310 is not set when --username is used then the primary group for the
311 user given to --username is used.
312 -x, --nouser-config, --user-config
314 Turn off (on) reading of per-user configuration files (user_prefs)
315 from the user's home directory. The default behaviour is to read
316 per-user configuration from the user's home directory
317 (--user-config).
318 This option does not disable or otherwise influence the SQL, LDAP
320 or Virtual Config Dir settings.
321 --auth-ident
323 Verify the username provided by spamc using ident. This is only
324 useful if connections are only allowed from trusted hosts (because
325 an identd that lies is trivial to create) and if spamc REALLY
326 SHOULD be running as the user it represents. Connections are
327 terminated immediately if authentication fails. In this case,
328 spamc will pass the mail through unchecked. Failure to connect to
329 an ident server, and response timeouts are considered
330 authentication failures. This requires that Net::Ident be
331 installed.
332 --ident-timeout=timeout
334 Wait at most timeout seconds for a response to ident queries.
335 Authentication that takes long that timeout seconds will fail, and
336 mail will not be processed. Setting this to 0.0 or less results in
337 no timeout, which is STRONGLY discouraged. The default is 5
338 seconds.
339 -A host,..., --allowed-ips=host,...
341 Specify a list of authorized hosts or networks which can connect to
342 this spamd instance. Single IP addresses can be given, ranges of IP
343 addresses in address/masklength CIDR format, or ranges of IP
344 addresses by listing 3 or less octets with a trailing dot.
345 Hostnames are not supported, only IP addresses. This option can be
346 specified multiple times, or can take a list of addresses separated
347 by commas. Examples:
348 -A 10.11.12.13 -- only allow connections from 10.11.12.13.
350 -A 10.11.12.13,10.11.12.14 -- only allow connections from
352 10.11.12.13 and 10.11.12.14.
353 -A 10.200.300.0/24 -- allow connections from any machine in the
355 range "10.200.300.*".
356 -A 10. -- allow connections from any machine in the range
358 "10.*.*.*".
359 By default, connections are only accepted from localhost
361 [127.0.0.1].
362 -D [area,...], --debug [area,...]
364 Produce debugging output. If no areas are listed, all debugging
365 information is printed. Diagnostic output can also be enabled for
366 each area individually; area is the area of the code to instrument.
367 For example, to produce diagnostic output on bayes, learn, and dns,
368 use:
369 spamassassin -D bayes,learn,dns
371 Higher priority informational messages that are suitable for
373 logging in normal circumstances are available with an area of
374 "info".
375 For more information about which areas (also known as channels) are
377 available, please see the documentation at:
378 C<http://wiki.apache.org/spamassassin/DebugChannels>
380 --ipv4only, --ipv4-only, --ipv4
382 Do not use IPv6 for DNS tests. Use if the existing tests for IPv6
383 availability produce incorrect results or crashes.
384 -L, --local
386 Perform only local tests on all mail. In other words, skip DNS and
387 other network tests. Works the same as the "-L" flag to
388 spamassassin(1).
389 -P, --paranoid
391 Die on user errors (for the user passed from spamc) instead of
392 falling back to user nobody and using the default configuration.
393 -m number , --max-children=number
395 This option specifies the maximum number of children to spawn.
396 Spamd will spawn that number of children, then sleep in the
397 background until a child dies, wherein it will go and spawn a new
398 child.
399 Incoming connections can still occur if all of the children are
401 busy, however those connections will be queued waiting for a free
402 child. The minimum value is 1, the default value is 5.
403 Please note that there is a OS specific maximum of connections that
405 can be queued (Try "perl -MSocket -e'print SOMAXCONN'" to find this
406 maximum).
407 Note that if you run too many servers for the amount of free RAM
409 available, you run the danger of hurting performance by causing a
410 high swap load as server processes are swapped in and out
411 continually.
412 --min-children=number
414 The minimum number of children that will be kept running. The
415 minimum value is 1, the default value is 1. If you have lots of
416 free RAM, you may want to increase this.
417 --min-spare=number
419 The lower limit for the number of spare children allowed to run. A
420 spare, or idle, child is one that is not handling a scan request.
421 If there are too few spare children available, a new server will be
422 started every second or so. The default value is 1.
423 --max-spare=number
425 The upper limit for the number of spare children allowed to run.
426 If there are too many spare children, one will be killed every
427 second or so until the number of idle children is in the desired
428 range. The default value is 2.
429 --max-conn-per-child=number
431 This option specifies the maximum number of connections each child
432 should process before dying and letting the master spamd process
433 spawn a new child. The minimum value is 1, the default value is
434 200.
435 --round-robin
437 By default, "spamd" will attempt to keep a small number of "hot"
438 child processes as busy as possible, and keep any others as idle as
439 possible, using something similar to the Apache httpd server
440 scaling algorithm. This is accomplished by the master process
441 coordinating the activities of the children. This switch will
442 disable this scaling algorithm, and the behaviour seen in the 3.0.x
443 versions will be used instead, where all processes receive an equal
444 load and no scaling takes place.
445 --timeout-tcp=number
447 This option specifies the number of seconds to wait for headers
448 from a client (spamc) before closing the connection. The minimum
449 value is 1, the default value is 30, and a value of 0 will disable
450 socket timeouts completely.
451 --timeout-child=number
453 This option specifies the number of seconds to wait for a spamd
454 child to process or check a message. The minimum value is 1, the
455 default value is 300, and a value of 0 will disable child timeouts
456 completely.
457 -H directory, --helper-home-dir=directory
459 Specify that external programs such as Razor, DCC, and Pyzor should
460 have a HOME environment variable set to a specific directory. The
461 default is to use the HOME environment variable setting from the
462 shell running spamd. By specifying no argument, spamd will use the
463 spamc caller's home directory instead.
464 --ssl
466 Accept only SSL connections on the associated port. The
467 IO::Socket::SSL perl module must be installed.
468 If the --ssl switch is used, and --ssl-port is not supplied, then
470 --port port will be used to accept SSL connections instead of
471 unencrypted connections. If the --ssl switch is used, and
472 --ssl-port is set, then unencrypted connections will be accepted on
473 the --port, at the same time as encrypted connections are accepted
474 at --ssl-port.
475 --ssl-port=port
477 Optionally specifies the port number for the server to listen on
478 for SSL connections (default: whatever --port uses). See --ssl for
479 more details.
480 --ssl-version=sslversion
482 Specify the SSL protocol version to use, one of sslv2, sslv3,
483 tlsv1, or sslv23. The default, sslv23, is the most flexible,
484 accepting a SSLv2 or higher hello handshake, then negotiating use
485 of SSLv3 or TLSv1 protocol if the client can accept it. Specifying
486 --ssl-version implies --ssl.
487 --server-key keyfile
489 Specify the SSL key file to use for SSL connections.
490 --server-cert certfile
492 Specify the SSL certificate file to use for SSL connections.
493 --socketpath pathname
495 Listen on UNIX domain path pathname instead of a TCP socket.
496 Warning: the Perl support on BSD platforms for UNIX domain sockets
498 seems to have a bug regarding paths of over 100 bytes or so
499 (SpamAssassin bug 4380). If you see a 'could not find newly-
500 created UNIX socket' error message, and the path appears truncated,
501 this may be the cause. Try using a shorter path to the socket.
502 By default, use of --socketpath will inhibit SSL connections and
504 unencrypted TCP connections. To enable them, specify --port and/or
505 --ssl-port explicitly.
506 --socketowner name
508 Set UNIX domain socket to be owned by the user named name. Note
509 that this requires that spamd be started as "root", and if "-u" is
510 used, that user should have write permissions to unlink the file
511 later, for when the "spamd" server is killed.
512 --socketgroup name
514 Set UNIX domain socket to be owned by the group named name. See
515 "--socketowner" for notes on ownership and permissions.
516 --socketmode mode
518 Set UNIX domain socket to use the octal mode mode. Note that if
519 "-u" is used, that user should have write permissions to unlink the
520 file later, for when the "spamd" server is killed.
521
523 spamc(1) spamassassin(1) Mail::SpamAssassin::Conf(3)
524 Mail::SpamAssassin(3)
525
527 "Mail::SpamAssassin"
528
530 The SpamAssassin(tm) Project (http://spamassassin.apache.org/)
531
533 SpamAssassin is distributed under the Apache License, Version 2.0, as
534 described in the file "LICENSE" included with the distribution.
535perl v5.10.1 2013-12-05 SPAMD(1)