@@ -1,3 +1,7 @@

+Wed Feb 25 14:08:14 CET 2009 (acab)

+-----------------------------------

+ * docs/man/clamav-milter.8.in: update documentation

+

 Wed Feb 25 00:00:25 EET 2009 (edwin)

 ------------------------------------

  * unit_tests/duma_tests.sh: fix duma timeouts (thanks Nigel!).

@@ -1,10 +1,10 @@

-.TH "clamav\-milter" "8" "March 23, 2004" "ClamAV @VERSION@" "Clam AntiVirus"

+.TH "clamav\-milter" "8" "Feb 25, 2009" "ClamAV @VERSION@" "Clam AntiVirus"

 .SH "NAME"

 .LP

 clamav\-milter \- milter compatible mail scanner

 .SH "SYNOPSIS"

 .LP

-clamav\-milter [options] socket_address

+clamav\-milter [options]

 .SH "DESCRIPTION"

 .LP

 Clamav\-milter is a filter for \fBsendmail(1)\fR mail server.

@@ -14,319 +14,23 @@ 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 \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 creatable 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

+Output help information and exit.

+.TP 

 \fB\-V, \-\-version\fR

 Print the version number and exit.

-.TP

-\fB\-C DIR, \-\-chroot=DIR\fR

-Run in chroot jail DIR.

-.IP

-You will have to do a lot of fiddling if you want notifications to work,

-since clamav\-milter calls \fBsendmail(8)\fR to handle the notifications and

-sendmail will run of out the same jail.

-.TP

+.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 compatibility 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, and needs

-to be enabled at compile\-time ].

-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 operating 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\-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, wherever 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.

-.TP

-\fB\-k, \-\-blacklist\-time=time\fR

-Tells the number of seconds to black list an IP address (IPv4 only). This

-is especially useful with phishing which often send a number of emails one

-after the other.

-.IP

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

-.IP

-Machines on the LAN, the local host, and machines that are our MX peers are

-never blacklisted.

-.TP

-\fB\f\-K, \-\-dont\-blacklist=IP[,IP...]\fR

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

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

-.IP

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

-.TP

-\fB\-M, \-\-freshclam\-monitor\fR

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

-The checking cannot be disabled, a value less than or equal to zero will be

-rejected.

-.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 creatable 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 that receives notifications of viruses caught,

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

-.TP

-\fB\-q, \-\-quiet\fR

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

-.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\-r, \-\-report\-phish=EMAILADDRESS\fR

-Report caught phishing to an anti\-phish organisation's email address such

-as pirt_clamav@castlecops.com and reportphishing@antiphishing.org.

-.TP

-\fB\-R, \-\-report\-phish\-false\-positives=EMAILADDRESS\fR

-Report phish false positves to an email address, such as bugs@clamav.net.

-.TP

-\fB\-U, \-\-quarantine\-dir=DIR\fR

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

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

-.TP

-\fB\-\-sign, \-S\fR

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

-.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\-\-dont\-sanitise\fR

-Allow semicolon and pipe characters in email addresses.

-.TP

-\fB\-\-ignore net, \-I net\fR

-\fInet\fR 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.

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

-Occurrences of %v within the file is replaced with the message

-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 appropriate

-sendmail\-variable, e.g. ${if_addr}$.

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

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

-sendmail.

-.TP

-\fB\-\-template\-headers=file\fR

-File points to a file whose contents are added to the headers of the

-warning message given to the \fB\-\-template\-file\fR option.

-For example, to state the character set of the message,

-put "Content\-Type: text/plain; charset=koi8\-r" into the file.

-.TP

-\fB\-\-timeout=n \-T n\fR

-Used in conjunction with max\-children. If clamav\-milter waits for more than

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

-will turn off the timeout and clamav\-milter will wait indefinitely 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\fR

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

-.IP

-The file consists of a list of addresses, each address on a line enclosed

-in angle brackets (e.g. <foo@bar.com>).

-Optionally each line can start with the string \fITo:\fR or \fIFrom:\fR

-indicating if it is the sender or recipient that is to be whitelisted. If the

-field is missing, the default is \fITo\fR.

-Lines starting with #, : or ! are ignored.

-.TP

-\fB\-\-sendmail\-cf=FILE\fR

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

-.TP

-\fB\-\-black\-hole\-mode\fR

-Since \fIsendmail\fR 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.

-.IP

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

-.IP

-To enable this mode clamav\-milter must have certain sendmail rights:

-it needs to run as a TrustedUser as defined by \fIsendmail\fR

-(see http://www.sendmail.org/m4/tweaking_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 AllowSupplementaryGroups must be enabled in clamd.conf.

-Some operating systems set \fI/var/spool/mqueue\fR 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 \fI/var/spool/mqueue\fR as

-mode 750.

-.SH "BUGS"

-There is no support for IPv6.

-.SH "EXAMPLES"

-.LP

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

+Read configuration from FILE.

+.SH "FILES"

+.LP 

+@CFGDIR@/clamd.conf

 .SH "AUTHOR"

-.LP

-Nigel Horne <njh@bandsman.co.uk>

+.LP 

+aCaB <acab@clamav.net>

 .SH "SEE ALSO"

 .LP

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

+sendmail(8), clamd(8), clamd.conf(5)