1clamav-milter(8)                Clam AntiVirus                clamav-milter(8)
2
3
4

NAME

6       clamav-milter - milter compatible mail scanner
7

SYNOPSIS

9       clamav-milter [options] socket_address
10

DESCRIPTION

12       Clamav-milter  is a filter for sendmail(1) mail server.  It uses a mail
13       scanning engine built into clamd(8).
14
15       Clamav-milter can use load balancing and fault tolerant  techniques  to
16       connect  to  more  than  one clamd(8) server and seamlessly hot-swap to
17       even the load between different  machines  and  to  keep  scanning  for
18       viruses  even  when  a  server goes down.  When it is configured to use
19       clamd on the the localhost, when the --external flag (see below) is not
20       given  or  LocalSocket  in set in clamd.conf(5), clamav-milter verifies
21       that it can communicate with clamd; if it cannot, it terminates.
22
23       clamav-milter supports tcpwrappers, the value for daemon_list is  "cla‐
24       mav-milter".
25
26       The  socket_address  argument  is  the  socket used to communicate with
27       sendmail(8).  It must agree with the  entry  in  sendmail.cf  or  send‐
28       mail.mc.  The file associated with the socket must be creatable by cla‐
29       mav-milter, if the User option is set in  clamd.conf,  then  that  user
30       must have the rights to create the file.
31

OPTIONS

33       -a FROM, --from<=EMAIL>
34              Source  email  address of notices. The default is MAILER-DAEMON.
35              If =EMAIL is not given, thus --from, then the  from  address  is
36              set to the originating email address, however since it is likely
37              that address is forged it must not be relied upon.   -h,  --help
38              Output the help information and exit.
39
40       -H, --headers
41              Include  all  headers in the content of emails generated by cla‐
42              mav-milter.  This is useful for system  administrators  who  may
43              want  to  look  at headers to check if any of their machines are
44              infected.
45
46       -V, --version
47              Print the version number and exit.
48
49       -C DIR, --chroot=DIR
50              Run in chroot jail DIR.
51
52              You will have to do a lot of fiddling if you want  notifications
53              to  work,  since  clamav-milter  calls sendmail(8) to handle the
54              notifications and sendmail will run of out the same jail.
55
56       -c FILE, --config-file=FILE
57              By default clamav-milter uses a default configuration file, this
58              option allows you to specify another one.
59
60       -D, --debug
61              Enables debugging.
62
63       -x n, --debug-level=n
64              Set  the debug level to n (where n from [0..9]) if clamav-milter
65              was configured and compiled with --clamav-debug  enabled.   Will
66              be  replaced by --debug for compatibility with other programs in
67              the suite.
68
69       -A, --advisory
70              When in advisory mode, clamav-milter flags emails  with  viruses
71              but  still forwards them. The default option is to stop viruses.
72              This mode is incompatible with  --quarantine  and  --quarantine-
73              dir.
74
75       -b, --bounce
76              Send  a failure message to the sender, and to the postmaster.  [
77              Warning: most viruses and worms fake their  source  address,  so
78              this  option is not recommended, and needs to be enabled at com‐
79              pile-time ].  See also --noreject.
80
81       -B, --broadcast[=<iface>]
82              When a virus is intercepted, broadcast a UDP message to the TCP‐
83              Socket  port set in clamd.conf.  If the optional iface option is
84              given, broadcasts will be sent on that interface. The default is
85              set by the operating system, usually to the first NIC.  A future
86              network management program (yet to be  written)  will  intercept
87              these broadcasts to raise a warning on the operator's desk.
88
89       -d, --dont-scan-on-error
90              If  a  system error occurs pass messages through unscanned, usu‐
91              ally when a system error occurs the milter  raises  a  temporary
92              failure  which  generally  causes  the  message to remain in the
93              queue.
94
95       -f, --force-scan
96              Always scan, wherever the message came from  (see  also  --local
97              and --outgoing).  You probably don't want this.
98
99       -e, --external
100              Usually clamav-milter scans the emails itself without the use of
101              an external program.  The --external option informs  clamav-mil‐
102              ter  to  use an external program such as clamd(8) running either
103              on the local server or other server(s) to perform the scanning.
104
105       -k, --blacklist-time=time
106              Tells the number of seconds to black list an  IP  address  (IPv4
107              only).  This is especially useful with phishing which often send
108              a number of emails one after the other.
109
110              Blacklisting speeds up scanning significantly, however  it  does
111              have drawbacks since it is possible for a site to be incorrectly
112              blacklisted because of DHCP or an unsafe smart-host.   To  avoid
113              this,  clamav-milter's  blacklist  does  not last for ever.  The
114              recommended value is 60.
115
116              Machines on the LAN, the local host, and machines that  are  our
117              MX peers are never blacklisted.
118
119       K, --dont-blacklist=IP[,IP...]
120              Instructs  clamav-milter  to  refrain  from  blacklisting IP the
121              given addresses.  This is useful for sites  that  receive  email
122              from  upstream  servers  that  are  either  untrusted or have no
123              virus.  Without this option many false  positives  could  occur.
124              This  scenario often happens when the upstream server belongs to
125              an ISP that may not have AV software.
126
127       -l, --local
128              Also scan messages sent from LAN. You probably want  this  espe‐
129              cially  if  your LAN is populated by machines running Windows or
130              DOS.
131
132              Machines with IP addresses  within  the  ranges  192.168.0.0/16,
133              10.0.0.0/8,  172.16.0.0/12  and  169.254.0.0/16  are  defined as
134              'local'. Messages from other machines are always scanned.  Up to
135              8 extra ranges may be added with the --ignore option.
136
137       -M, --freshclam-monitor
138              When not running in external mode, this option tells clamav-mil‐
139              ter how often to check that the virus database has been updated,
140              probably by freshclam(1).  The option takes one parameter, which
141              is a number in seconds.  The default is 300 seconds.  The check‐
142              ing  cannot be disabled, a value less than or equal to zero will
143              be rejected.
144
145       -n, --noxheader
146              Usually  clamav-milter  adds  headings  to  messages  that   are
147              scanned.   The  headers  are  of the form "X-Virus-Scanned: ver‐
148              sion", and "X-Virus-Status:  clean/infected/not-scanned".   This
149              option instructs clamav-milter to refrain from adding this head‐
150              ing.
151
152       -N, --noreject
153              When clamav-milter processes an e-mail which contains a virus it
154              rejects  the  e-mail by using the SMTP code 550 or 554 depending
155              on the state  machine.   This  option  causes  clamav-milter  to
156              silently  discard  such messages.  It is recommended that system
157              administrators use this  option  when  NOT  using  the  --bounce
158              option.
159
160       -o, --outgoing
161              Scan  messages  generated  from this machine. You probably don't
162              need this.
163
164       -i, --pidfile=FILE
165              Notifies clamav-milter to store its process  ID  in  FILE.   The
166              file  must  be creatable by clamav-milter, if the User option is
167              set in clamd.conf(5), then that user must  have  the  rights  to
168              create the file.
169
170       -p, --postmaster=EMAILADDRESS
171              Sets  the  e-mail address that receives notifications of viruses
172              caught, when the --quiet option is not given.
173
174       -P, --postmaster-only
175              When the --quiet option is not given, send a notification to the
176              postmaster.   Setting  this flag will include the ID of the mes‐
177              sage in the email's body which can ease searching through system
178              logs  if  the  administrator  believes  it  is a locally sourced
179              virus.  Without this option, the intended recipient of the email
180              will  also  receive  a copy of the notification of the intercep‐
181              tion.
182
183       -q, --quiet
184              Don't send any notification messages when a  virus  or  worm  is
185              detected.   This option overrides the --bounce and --postmaster-
186              only options, and is the way to turn  off  notification  to  the
187              postmaster.
188
189       -Q, --quarantine=EMAILADDRESS
190              If  this e-mail address is given, messages containing a virus or
191              worm are redirected to it.
192
193       -r, --report-phish=EMAILADDRESS
194              Report caught phishing to  an  anti-phish  organisation's  email
195              address  such  as  pirt_clamav@castlecops.com  and  reportphish‐
196              ing@antiphishing.org.
197
198       -R, --report-phish-false-positives=EMAILADDRESS
199              Report phish  false  positves  to  an  email  address,  such  as
200              bugs@clamav.net.
201
202       -U, --quarantine-dir=DIR
203              If  this option is given, infected files are left in this direc‐
204              tory.  The directory must not be publicly readable or  writable,
205              if  it  is, clamav-milter will issue an error and fail to start.
206              Note - this option only works when using LocalSocket.
207
208       --server=HOSTNAME/ADDRESS, -s HOSTNAME/ADDRESS
209              IP address or hostname of server(s) running  clamd  (when  using
210              TCPsocket  and  --external).  More than one server may be speci‐
211              fied, separating the server's names by colons.  If more than one
212              server is specified, clamav-milter will load balance between the
213              available servers. All the servers must be up when clamav-milter
214              starts,  however  afterwards  it  is  fault tolerant to a server
215              becoming unavailable, and will only raise an error if all of the
216              servers  cannot  be  reached.   The default value for ADDRESS is
217              127.0.0.1 (localhost).
218
219       --sign, -S
220              Add a hard-coded signature to each scanned file.  It  is  likely
221              that this signature will only display on the end user's terminal
222              if the message is plain/text or not encoded.
223
224       --signature-file, -F
225              Location of file to be appended to each scanned  message.  Over‐
226              rides -S.
227
228       --max-children=n, -m n
229              Set  a  hint of the maximum number of children. If the number is
230              hit the maximum time a pending thread will be held up is set  by
231              --timeout,  so  the number of threads can exceed this number for
232              short periods of time.  There is no default, if this argument is
233              not clamav-milter will spawn as many children as is necessary up
234              to the MaxThreads limit set in clamd.conf.   When  clamav-milter
235              has  been  built  with  SESSION  mode this argument is mandatory
236              since it tells clamav-milter the number of sessions to keep open
237              to  clamd  servers.   When  not built with in SESSION mode it is
238              unlikely that you will need this unless  your  system  is  under
239              great  load.   Note, however, that the default build is for SES‐
240              SION to be disabled.
241
242       --dont-wait
243              Tells clamav-milter what do to if  the  max-children  number  is
244              exceeded.  Usually clamav-milter waits until a child dies or the
245              timeout value has been exceeded, which ever comes first, however
246              with  dont-wait  enabled,  clamav-milter  will inform the remote
247              SMTP client to retry later.
248
249       --ignore net, -I net
250              net is taken to be  an  extra  IPv4  or  IPv6  network  in  pre‐
251              fix/length  notation (for example 192.0.2.0/24 or 2001:db8::/32)
252              which is treated as being on the LAN for  the  purposes  of  the
253              --local argument. Up to eight nets can be specified.
254
255       --template-file=file -t file
256              File points to a file whose contents is sent as the warning mes‐
257              sage whenever a virus is intercepted.  Occurrences of %v  within
258              the file is replaced with the message returned from clamd, which
259              includes the name of the virus.  Occurrences of %h are  replaced
260              with  the message's headers.  The %v string can be escaped thus,
261              \%v, to send the string %v.  The  %  character  can  be  escaped
262              thus, %%, to send the % character.  Any occurrence of strings in
263              dollar signs are replaced with  the  appropriate  sendmail-vari‐
264              able,  e.g.  ${if_addr}$.   If  the -t option is not given, cla‐
265              mav-milter defaults to a hard-coded message.  Note that to  send
266              warning  messages,  clamav-milter  must be able to execute send‐
267              mail.
268
269       --template-headers=file
270              File points to a file whose contents are added to the headers of
271              the  warning  message  given to the --template-file option.  For
272              example, to state the character set of the  message,  put  "Con‐
273              tent-Type: text/plain; charset=koi8-r" into the file.
274
275       --timeout=n -T n
276              Used  in  conjunction  with max-children. If clamav-milter waits
277              for more than n seconds (default 300) it proceeds with scanning.
278              Setting  n  to  zero will turn off the timeout and clamav-milter
279              will wait indefinitely for the scanning to quit. In practice the
280              timeout set by sendmail will then take over.
281
282       --detect-forged-local-address -L
283              When  neither  --force,  --local  nor  --outgoing is given, this
284              option intercepts incoming mails that incorrectly  claim  to  be
285              from the local domain.
286
287       --whitelist-file=FILE, -W file
288              This  option  specifies  a  file which contains a list of e-mail
289              addresses.  E-mails sent to or from these addresses will NOT  be
290              checked.   While this is not an Anti-Virus function, it is quite
291              useful for some systems.  The address given to the  --quarantine
292              directive is always whitelisted.
293
294              The file consists of a list of addresses, each address on a line
295              enclosed in angle  brackets  (e.g.  <foo@bar.com>).   Optionally
296              each  line  can start with the string To: or From: indicating if
297              it is the sender or recipient that is to be whitelisted. If  the
298              field  is  missing, the default is To.  Lines starting with #, :
299              or ! are ignored.
300
301       --sendmail-cf=FILE
302              When starting, clamav-milter runs some sanity checks against the
303              sendmail.cf file, usually in /etc/sendmail.cf or /etc/mail/send‐
304              mail.cf. This directive tells clamav-milter where  to  find  the
305              sendmail.cf file.
306
307       --black-hole-mode
308              Since  sendmail  calls  its milters before it looks in its alias
309              and virtuser tables, clamav-milter can spend  time  looking  for
310              malware  that's  going  to be thrown away even if the message is
311              clean.
312
313              Enabling this stops these messages from being scanned (in  prac‐
314              tice  clamav-milter  will  discard these messages so the message
315              doesn't go further down the milter  call  chain).   Only  enable
316              this if your site has many addresses aliased to /dev/null.
317
318              To  enable  this  mode  clamav-milter must have certain sendmail
319              rights: it needs to run as a TrustedUser as defined by  sendmail
320              (see http://www.sendmail.org/m4/tweaking_config.html) by the use
321              of the User directive in clamd.conf, the  clamav  user  must  be
322              able  read  the mail queue (often /var/spool/mqueue), and Allow‐
323              SupplementaryGroups must be enabled in clamd.conf.  Some operat‐
324              ing  systems set /var/spool/mqueue to be mode 700 forcing you to
325              run clamav-milter as root for black-hole-mode.  This  is  always
326              unadvisable, it is better to have /var/spool/mqueue as mode 750.
327

BUGS

329       There is no support for IPv6.
330

EXAMPLES

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

AUTHOR

335       Nigel Horne <njh@bandsman.co.uk>
336

SEE ALSO

338       clamd(8),   clamscan(1),   freshclam(1),   sigtool(1),   clamd.conf(5),
339       hosts_access(5), sendmail(8)
340
341
342
343ClamAV 0.92.1                   March 23, 2004                clamav-milter(8)
Impressum