.TH "clamav-milter" "8" "March 23, 2004" "" "Clam AntiVirus"

 .SH "NAME"

 .LP

 clamav\-milter \- milter compatible mail scanner

 .SH "SYNOPSIS"

 .LP

 clamav\-milter [options] socket_address
 .SH "DESCRIPTION"

 .LP

 Clamav\-milter is a filter for \fBsendmail(1)\fR mail server.
 It uses a mail scanning engine built into \fBclamd(8)\fR.

 .LP

 Clamav\-milter can, when configured to use communicate to clamd on other
 machines, use load balancing and fault tolerant techniques to connect to
 more than one clamd and seemlessly hot swap to even the load between different
 servers 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 \fBclamd.conf(5)\fR,

 clamav\-milter verifies that it can communicate with clamd; if it cannot, it
 terminates.

 .LP
 clamav\-milter supports tcpwrappers, the value for \fIdaemon_list\fR
 is "clamav\-milter".

 .LP
 The socket_address argument is the socket used to communicate with
 \fBsendmail(8)\fR.
 It must agree with the entry in sendmail.cf or sendmail.mc.
 The file associated with the socket must be createable by clamav\-milter,

 if the User option is set in clamd.conf,

 then that user must have the rights to create the file.

 .SH "OPTIONS"

 .LP

 .TP

 \fB-a FROM, \-\-from<=EMAIL>\fR

 Source email address of notices. The default is MAILER-DAEMON.

 If \fI=EMAIL\fR 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.

 \fB\-h, \-\-help\fR
 Output the help information and exit.

 .TP
 \fB\-H, \-\-headers\fR
 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.

 .TP

 \fB\-V, \-\-version\fR
 Print the version number and exit.

 .TP

 \fB\-c FILE, \-\-config\-file=FILE\fR

 By default clamav\-milter uses a default configuration file, this option allows you to specify another one.

 .TP

 \fB\-D, \-\-debug\fR

 Enables debugging.

 .TP

 \fB\-x n, \-\-debug\-level=n\fR

 Set the debug level to n (where n from [0..9]) if \fBclamav\-milter\fR was

 configured and compiled with \-\-clamav-debug enabled.

 Will be replaced by \-\-debug for compatability with other programs in the
 suite.

 .TP

 \fB-A, \-\-advisory\fR
 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.

 .TP

 \fB\-b, \-\-bounce\fR

 Send a failure message to the sender, and to the postmaster.
 [ \fBWarning\fR: most viruses and worms

 fake their source address, so this option is not recommended ].
 See also \-\-noreject.

 .TP

 \fB\-B, \-\-broadcast[=<iface>]\fR

 When a virus is intercepted, broadcast a UDP message to the TCPSocket port set
 in \fBclamd.conf\fR.

 If the optional \fIiface\fR option is given, broadcasts will be sent on
 that interface. The default is set by the opertating system, usually to the
 first NIC.

 A future network management program (yet to be written) will intercept these
 broadcasts to raise a warning on the operator's desk.
 .TP

 \fB-C, \-\-dont-log-clean\fR
 Messages without viruses are usually logged if SysLog is set in

 \fBclamd.conf\fR since it gives a feel-good factor.

 This option turns that off.
 .TP

 \fB-d, \-\-dont-scan-on-error\fR
 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 message to remain in the queue.
 .TP
 \fB-f, \-\-force-scan\fR

 Always scan, whereever the message came from (see also --local and --outgoing).

 You probably don't want this.

 .TP

 \fB-e, \-\-external\fR

 Usually clamav\-milter scans the emails itself without the use of an

 external program.

 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.

 The setting in clamd.conf for LocalSocket or TCPSocket is ignored.

 .TP

 \fB-l, \-\-local\fR

 Also scan messages sent from LAN. You probably want this especially if
 your LAN is populated by machines running Windows or DOS.

 .TP
 \fB-n, \-\-noxheader\fR

 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.

 .TP

 \fB-N, \-\-noreject\fR

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

 \fB-o, \-\-outgoing\fR

 Scan messages generated from this machine. You probably don't need this.

 .TP

 \fB-i, \-\-pidfile=FILE\fR
 Notifies clamav\-milter to store its process ID in FILE.
 The file must be createable by clamav\-milter,
 if the User option is set in

 \fBclamd.conf(5)\fR,

 then that user must have the rights to create the file.
 .TP

 \fB-p, \-\-postmaster=EMAILADDRESS\fR

 Sets the e-mail address to send notifications to when the \-\-quiet option
 is not given.

 .TP
 \fB-P, \-\-postmaster-only\fR

 When the \-\-quiet option is not given, send a notification to the postmaster.

 Setting this flag will include the ID of the message which can ease searching
 through system logs if the administrator believes it is a locally sourced
 virus.

 .TP
 \fB-q, \-\-quiet\fR
 Don't send any warning messages when a virus or worm or is detected.
 This option overrides the \-\-bounce and \-\-postmaster-only options, and is
 the way to turn off notification to the postmaster.
 .TP
 \fB-Q, \-\-quarantine=EMAILADDRESS\fR
 If this e-mail address is given, messages containing a virus or worm are
 redirected to it.
 .TP
 \fB-U, \-\-quarantine-dir=DIR\fR
 If this option is given, infected files are left in this directory.

 The directory must not be publically readable or writeable, if it is,
 clamav\-milter will issue an error and fail to start.
 \fBNote\fR - this option only works when using LocalSocket.

 .TP

 \fB\-\-server=HOSTNAME/ADDRESS, \-s HOSTNAME/ADDRESS\fR
 IP address or hostname of server(s) running clamd (when using TCPsocket).

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

 .TP
 \fB\-\-sign, \-S\fR
 Add a hard\-coded signature to each scanned file.
 .TP
 \fB\-\-signature-file, \-F\fR
 Location of file to be appended to each scanned message. Overrides \-S.

 .TP

 \fB\-\-max\-children=n, \-m n\fR

 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 argument is not \fBclamav\-milter\fR will

 spawn as many children as is necessary up to the MaxThreads limit set

 in \fBclamd.conf\fR.

 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.

 .TP

 \fB\-\-dont\-wait\fR
 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.
 .TP

 \fB\-\-template\-file=file \-t file\fR

 File points to a file whose contents is sent as the warning message whenever a
 virus is intercepted.

 Occurances of %v within the file is replaced with the message

 returned from clamd, which includes the name of the virus.

 Occurances 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 occurance of strings in dollar signs are replaced with the appropriate
 sendmail-variable, e.g. ${if_addr}$.

 If the \-t option is not given, clamav\-milter defaults to a hardcoded message.

 Note that to send warning messages, clamav\-milter must be able to execute
 sendmail.

 .TP
 \fB\-\-timeout=n \-T n\fR
 Used in conjuction with max\-children. If clamav\-milter waits for more than

 \fIn\fR seconds (default 0) it proceeds with scanning. Setting \fIn\fR to zero

 will turn off the timeout and clamav\-milter will wait indefinately for the
 scanning to quit. In practice the timeout set by sendmail will then take over.

 .TP
 \fB\-\-detect-forged-local-address \-L\fR
 When neither \-\-force, \-\-local nor \-\-outgoing is given,
 this option intercepts incoming mails that incorrectly claim to be from the
 local domain.

 .TP
 \fB\-\-whitelist-file=FILE, \-W file
 This option specifies a file which contains a list of e-mail addresses.
 E-mails sent to 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.
 .TP
 \fB\-\-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 clamav\-milter where to find the sendmail.cf file.

 .SH "BUGS"
 There is no support for IPv6.

 .SH "EXAMPLES"

 .LP

 clamav\-milter \-o local:/var/run/clamav/clmilter.sock

 .SH "AUTHOR"

 .LP

 Nigel Horne <njh@bandsman.co.uk>

 .SH "SEE ALSO"

 .LP

 sendmail(1), clamd(8), clamscan(1), freshclam(1), sigtool(1), clamd.conf(5), hosts_access(5)