clamav-milter(8) Clam AntiVirus clamav-milter(8)
NAME
clamav-milter - milter compatible mail scanner
SYNOPSIS
clamav-milter [options] socket_address
DESCRIPTION
Clamav-milter is a filter for sendmail(1) mail server. It uses a mail scanning engine
built into clamd(8).
Clamav-milter can use load balancing and fault tolerant techniques to connect to more than
one clamd(8) server and seamlessly hot-swap to even the load between different machines
and to keep scanning for viruses even when a server goes down. When it is configured to
use clamd on the the localhost, when the --external flag (see below) is not given or
LocalSocket in set in clamd.conf(5), clamav-milter verifies that it can communicate with
clamd; if it cannot, it terminates.
clamav-milter supports tcpwrappers, the value for daemon_list is "clamav-milter".
The socket_address argument is the socket used to communicate with sendmail(8). It must
agree with the entry in sendmail.cf or sendmail.mc. The file associated with the socket
must be creatable by clamav-milter, if the User option is set in clamd.conf, then that
user must have the rights to create the file.
OPTIONS
-a FROM, --from<=EMAIL>
Source email address of notices. The default is MAILER-DAEMON. If =EMAIL is not
given, thus --from, then the from address is set to the originating email address,
however since it is likely that address is forged it must not be relied upon. -h,
--help Output the help information and exit.
-H, --headers
Include all headers in the content of emails generated by clamav-milter. This is
useful for system administrators who may want to look at headers to check if any of
their machines are infected.
-V, --version
Print the version number and exit.
-C DIR, --chroot=DIR
Run in chroot jail DIR.
You will have to do a lot of fiddling if you want notifications to work, since cla-
mav-milter calls sendmail(8) to handle the notifications and sendmail will run of
out the same jail.
-c FILE, --config-file=FILE
By default clamav-milter uses a default configuration file, this option allows you
to specify another one.
-D, --debug
Enables debugging.
-x n, --debug-level=n
Set the debug level to n (where n from [0..9]) if clamav-milter was configured and
compiled with --clamav-debug enabled. Will be replaced by --debug for compatibil-
ity with other programs in the suite.
-A, --advisory
When in advisory mode, clamav-milter flags emails with viruses but still forwards
them. The default option is to stop viruses. This mode is incompatible with
--quarantine and --quarantine-dir.
-b, --bounce
Send a failure message to the sender, and to the postmaster. [ Warning: most
viruses and worms fake their source address, so this option is not recommended, and
needs to be enabled at compile-time ]. See also --noreject.
-B, --broadcast[=]
When a virus is intercepted, broadcast a UDP message to the TCPSocket port set in
clamd.conf. If the optional iface option is given, broadcasts will be sent on that
interface. The default is set by the operating system, usually to the first NIC. A
future network management program (yet to be written) will intercept these broad-
casts to raise a warning on the operator's desk.
-d, --dont-scan-on-error
If a system error occurs pass messages through unscanned, usually when a system
error occurs the milter raises a temporary failure which generally causes the mes-
sage to remain in the queue.
-f, --force-scan
Always scan, wherever the message came from (see also --local and --outgoing). You
probably don't want this.
-e, --external
Usually clamav-milter scans the emails itself without the use of an external pro-
gram. The --external option informs clamav-milter to use an external program such
as clamd(8) running either on the local server or other server(s) to perform the
scanning.
-k, --blacklist-time=time
Tells the number of seconds to black list an IP address (IPv4 only). This is espe-
cially useful with phishing which often send a number of emails one after the
other.
Blacklisting speeds up scanning significantly, however it does have drawbacks since
it is possible for a site to be incorrectly blacklisted because of DHCP or an
unsafe smart-host. To avoid this, clamav-milter's blacklist does not last for
ever. The recommended value is 60.
Machines on the LAN, the local host, and machines that are our MX peers are never
blacklisted.
K, --dont-blacklist=IP[,IP...]
Instructs clamav-milter to refrain from blacklisting IP the given addresses. This
is useful for sites that receive email from upstream servers that are either
untrusted or have no virus. Without this option many false positives could occur.
This scenario often happens when the upstream server belongs to an ISP that may not
have AV software.
-l, --local
Also scan messages sent from LAN. You probably want this especially if your LAN is
populated by machines running Windows or DOS.
Machines with IP addresses within the ranges 192.168.0.0/16, 10.0.0.0/8,
172.16.0.0/12 and 169.254.0.0/16 are defined as 'local'. Messages from other
machines are always scanned. Up to 8 extra ranges may be added with the --ignore
option.
-M, --freshclam-monitor
When not running in external mode, this option tells clamav-milter how often to
check that the virus database has been updated, probably by freshclam(1). The
option takes one parameter, which is a number in seconds. The default is 300 sec-
onds. The checking cannot be disabled, a value less than or equal to zero will be
rejected.
-n, --noxheader
Usually clamav-milter adds headings to messages that are scanned. The headers are
of the form "X-Virus-Scanned: version", and "X-Virus-Status:
clean/infected/not-scanned". This option instructs clamav-milter to refrain from
adding this heading.
-N, --noreject
When clamav-milter processes an e-mail which contains a virus it rejects the e-mail
by using the SMTP code 550 or 554 depending on the state machine. This option
causes clamav-milter to silently discard such messages. It is recommended that
system administrators use this option when NOT using the --bounce option.
-o, --outgoing
Scan messages generated from this machine. You probably don't need this.
-i, --pidfile=FILE
Notifies clamav-milter to store its process ID in FILE. The file must be creatable
by clamav-milter, if the User option is set in clamd.conf(5), then that user must
have the rights to create the file.
-p, --postmaster=EMAILADDRESS
Sets the e-mail address that receives notifications of viruses caught, when the
--quiet option is not given.
-P, --postmaster-only
When the --quiet option is not given, send a notification to the postmaster. Set-
ting this flag will include the ID of the message in the email's body which can
ease searching through system logs if the administrator believes it is a locally
sourced virus. Without this option, the intended recipient of the email will also
receive a copy of the notification of the interception.
-q, --quiet
Don't send any notification messages when a virus or worm is detected. This option
overrides the --bounce and --postmaster-only options, and is the way to turn off
notification to the postmaster.
-Q, --quarantine=EMAILADDRESS
If this e-mail address is given, messages containing a virus or worm are redirected
to it.
-r, --report-phish=EMAILADDRESS
Report caught phishing to an anti-phish organisation's email address such as
and .
-R, --report-phish-false-positives=EMAILADDRESS
Report phish false positves to an email address, such as .
-U, --quarantine-dir=DIR
If this option is given, infected files are left in this directory. The directory
must not be publicly readable or writable, if it is, clamav-milter will issue an
error and fail to start. Note - this option only works when using LocalSocket.
--server=HOSTNAME/ADDRESS, -s HOSTNAME/ADDRESS
IP address or hostname of server(s) running clamd (when using TCPsocket and
--external). More than one server may be specified, separating the server's names
by colons. If more than one server is specified, clamav-milter will load balance
between the available servers. All the servers must be up when clamav-milter
starts, however afterwards it is fault tolerant to a server becoming unavailable,
and will only raise an error if all of the servers cannot be reached. The default
value for ADDRESS is 127.0.0.1 (localhost).
--sign, -S
Add a hard-coded signature to each scanned file. It is likely that this signature
will only display on the end user's terminal if the message is plain/text or not
encoded.
--signature-file, -F
Location of file to be appended to each scanned message. Overrides -S.
--max-children=n, -m n
Set a hint of the maximum number of children. If the number is hit the maximum time
a pending thread will be held up is set by --timeout, so the number of threads can
exceed this number for short periods of time. There is no default, if this argu-
ment is not clamav-milter will spawn as many children as is necessary up to the
MaxThreads limit set in clamd.conf. When clamav-milter has been built with SESSION
mode this argument is mandatory since it tells clamav-milter the number of sessions
to keep open to clamd servers. When not built with in SESSION mode it is unlikely
that you will need this unless your system is under great load. Note, however,
that the default build is for SESSION to be disabled.
--dont-wait
Tells clamav-milter what do to if the max-children number is exceeded. Usually
clamav-milter waits until a child dies or the timeout value has been exceeded,
which ever comes first, however with dont-wait enabled, clamav-milter will inform
the remote SMTP client to retry later.
--dont-sanitise
Allow semicolon and pipe characters in email addresses.
--ignore net, -I net
net is taken to be an extra IPv4 or IPv6 network in prefix/length notation (for
example 192.0.2.0/24 or 2001:db8::/32) which is treated as being on the LAN for the
purposes of the --local argument. Up to eight nets can be specified.
--template-file=file -t file
File points to a file whose contents is sent as the warning message whenever a
virus is intercepted. Occurrences of %v within the file is replaced with the mes-
sage returned from clamd, which includes the name of the virus. Occurrences of %h
are replaced with the message's headers. The %v string can be escaped thus, \%v,
to send the string %v. The % character can be escaped thus, %%, to send the %
character. Any occurrence of strings in dollar signs are replaced with the appro-
priate sendmail-variable, e.g. ${if_addr}$. If the -t option is not given, cla-
mav-milter defaults to a hard-coded message. Note that to send warning messages,
clamav-milter must be able to execute sendmail.
--template-headers=file
File points to a file whose contents are added to the headers of the warning mes-
sage given to the --template-file option. For example, to state the character set
of the message, put "Content-Type: text/plain; charset=koi8-r" into the file.
--timeout=n -T n
Used in conjunction with max-children. If clamav-milter waits for more than n sec-
onds (default 300) it proceeds with scanning. Setting n to zero will turn off the
timeout and clamav-milter will wait indefinitely for the scanning to quit. In prac-
tice the timeout set by sendmail will then take over.
--detect-forged-local-address -L
When neither --force, --local nor --outgoing is given, this option intercepts
incoming mails that incorrectly claim to be from the local domain.
--whitelist-file=FILE, -W file
This option specifies a file which contains a list of e-mail addresses. E-mails
sent to or from these addresses will NOT be checked. While this is not an
Anti-Virus function, it is quite useful for some systems. The address given to the
--quarantine directive is always whitelisted.
The file consists of a list of addresses, each address on a line enclosed in angle
brackets (e.g. <>). Optionally each line can start with the string To:
or From: indicating if it is the sender or recipient that is to be whitelisted. If
the field is missing, the default is To. Lines starting with #, : or ! are
ignored.
--sendmail-cf=FILE
When starting, clamav-milter runs some sanity checks against the sendmail.cf file,
usually in /etc/sendmail.cf or /etc/mail/sendmail.cf. This directive tells cla-
mav-milter where to find the sendmail.cf file.
--black-hole-mode
Since sendmail calls its milters before it looks in its alias and virtuser tables,
clamav-milter can spend time looking for malware that's going to be thrown away
even if the message is clean.
Enabling this stops these messages from being scanned (in practice clamav-milter
will discard these messages so the message doesn't go further down the milter call
chain). Only enable this if your site has many addresses aliased to /dev/null.
To enable this mode clamav-milter must have certain sendmail rights: it needs to
run as a TrustedUser as defined by sendmail (see http://www.sendmail.org/m4/tweak-
ing_config.html) by the use of the User directive in clamd.conf, the clamav user
must be able read the mail queue (often /var/spool/mqueue), and AllowSupplementary-
Groups must be enabled in clamd.conf. Some operating systems set /var/spool/mqueue
to be mode 700 forcing you to run clamav-milter as root for black-hole-mode. This
is always unadvisable, it is better to have /var/spool/mqueue as mode 750.
BUGS
There is no support for IPv6.
EXAMPLES
clamav-milter -o local:/var/run/clamav/clmilter.sock
AUTHOR
Nigel Horne <>
SEE ALSO
clamd(8), clamscan(1), freshclam(1), sigtool(1), clamd.conf(5), hosts_access(5), send-
mail(8)
ClamAV 0.94.2 March 23, 2004 clamav-milter(8)
|