1. BUILD INSTRUCTIONS A makefile was supplied with this which should have built the program. If it fails please let us know, and here are some hints for building on different platforms. You will need to set --enable-milter when running configure for the automatic build to work. Tested OK on Linux/x86 with gcc3.2. cc -O3 -pedantic -Wuninitialized -Wall -pipe -mcpu=pentium -march=pentium -fomit-frame-pointer -ffast-math -finline-functions -funroll-loops clamav-milter.c -pthread -lmilter ../libclamav/.libs/libclamav.a ../clamd/cfgfile.o ../clamd/others.o Compiles OK on Linux/x86 with tcc 0.9.16, but fails to link errors with 'atexit' tcc -g -b -lmilter -lpthread clamav-milter.c... Fails to compile on Linux/x86 with icc6.0 (complains about stdio.h...) icc -O3 -tpp7 -xiMKW -ipo -parallel -i_dynamic -w2 clamav-milter.c... Fails to build on Linux/x86 with icc7.1 with -ipo (fails on libclamav.a - keeps saying run ranlib). Otherwise it builds and runs OK. icc -O2 -tpp7 -xiMKW -parallel -i_dynamic -w2 -march=pentium4 -mcpu=pentium4 clamav-milter.c... Tested with Electric Fence 2.2.2, and the bounds checking C compiler from http://sourceforge.net/projects/boundschecking/ Compiles OK on Linux/ppc (YDL2.3) with gcc2.95.4. Needs -lsmutil to link. cc -O3 -pedantic -Wuninitialized -Wall -pipe -fomit-frame-pointer -ffast-math -finline-functions -funroll-loop -pthread -lmilter ../libclamav/.libs/libclamav.a ../clamd/cfgfile.o ../clamd/others.o -lsmutil I haven't tested it further on this platform yet. YDL3.0 should compile out of the box Linux/sparc (Gentoo 2004.2) comes with a sendmail that doesn't support MILTER, so *before* running "configure --enable-milter", download from http://www.sendmail.org/ftp, then: cd .../sendmail-source-directory sh Build make install cd libmilter make install Sendmail on MacOS/X (10.1) is provided without a development package so this can't be run "out of the box" Solaris 8 doesn't have milter support so clamav-milter won't work unless you rebuild sendmail from source. FreeBSD4.7 use /usr/local/bin/gcc30. GCC3.0 is an optional extra on FreeBSD. It comes with getopt.h which is handy. To link you need -lgnugetopt gcc30 -O3 -DCONFDIR=\"/usr/local/etc\" -I. -I.. -I../clamd -I../libclamav -pedantic -Wuninitialized -Wall -pipe -mcpu=pentium -march=pentium -fomit-frame-pointer -ffast-math -finline-functions -funroll-loops clamav-milter.c -pthread -lmilter ../libclamav/.libs/libclamav.a ../clamd/cfgfile.o ../clamd/others.o -lgnugetopt FreeBSD4.8: compiles out of the box with either gcc2.95 or gcc3 NetBSD2.0: compiles out of the box OpenBSD3.4: the supplied sendmail does not come with Milter support. Do this *before* running configure (thanks for Per-Olov Sjöhol for these instructions). echo WANT_LIBMILTER=1 > /etc/mk.conf cd /usr/src/gnu/usr.sbin/sendmail make depend make make install kill -HUP `sed q /var/run/sendmail.pid` Then do this to make the milter headers available to clamav... (the libmilter.a file is already in the right place after the sendmail recompiles above) cd /usr/include ln -s ../src/gnu/usr.sbin/sendmail/include/libmilter libmilter Solaris 9 and FreeBSD5 have milter support in the supplied sendmail, but doesn't include libmilter so you can't develop milter applications on it. Go to sendmail.org, download the latest sendmail, cd to libmilter and "make install" there. Needs -lresolv on Solaris, for res_close(). If, when building clamav-milter, you see the error "undefined reference to smfi_opensocket", it means that your sendmail installation is broken. More specifically it means that your installed version of libmilter does not agree with your installed version of Sendmail. Naturally they must be the same. Check to see if you have more than one mfapi.h on your system; if you installed sendmail from source, did you remember to install libmilter at the same time? You can ensure that your Sendmail is correctly installed if you follow these instructions: cd .../sendmail-source-directory sh Build make install cd libmilter make install 2. INSTALLATION Install into /usr/local/sbin/clamav-milter. Ensure that your sendmail supports milters by running /usr/lib/sendmail -d0 < /dev/null | fgrep MILTER or /usr/sbin/sendmail -d0 < /dev/null | fgrep MILTER You should see something like: MATCHGECOS MILTER MIME7TO8 MIME8TO7 NAMED_BIND NETINET NETINET6 It doesn't matter exactly what you see, as long as the word MILTER is printed. If you see no output you MUST upgrade your sendmail. See http://www.nmt.edu/~wcolburn/sendmail-8.12.5/libmilter/docs/sample.html 2.1 LINUX (RedHat, Fedora, YellowDog etc) Installations for RedHat Linux and it's derivatives such as YellowDog: Ensure that you have the sendmail-devel RPM installed Add to /etc/mail/sendmail.mc before the MAILER statement: INPUT_MAIL_FILTER(`clamav', `S=local:/var/run/clamav/clmilter.sock, F=, T=S:4m;R:4m;C:30s;E:10m')dnl define(`confINPUT_MAIL_FILTERS', `clamav') Note that the INPUT_MAIL_FILTER line must come before the confINPUT_MAIL_FILTERS line. Don't worry that the file /var/run/clamav/clmilter.sock doesn't exist, clamav-milter will create it for you. However you will need to create the directory /var/run/clamav (usually owned by user clamav, mode 700). Check entry in /usr/local/etc/clamd.conf of the form: LocalSocket /var/run/clamav/clamd.sock If you already have a filter (such as spamassassin-milter from http://savannah.nongnu.org/projects/spamass-milt) add it thus: INPUT_MAIL_FILTER(`clamav', `S=local:/var/run/clamav/clmilter.sock, F=, T=S:4m;R:4m')dnl INPUT_MAIL_FILTER(`spamassassin', `S=local:/var/run/spamass.sock, F=, T=C:15m;S:4m;R:4m;E:10m') define(`confINPUT_MAIL_FILTERS', `spamassassin,clamav')dnl mkdir /var/run/clamav chown clamav /var/run/clamav (if you use User clamav in clamd.conf) chmod 700 /var/run/clamav Where /var/run/spamass.sock is the location of the spamass-milt socket file (on some systems it is in /var/run/sendmail/spamass.sock). 2.2 LINUX (Debian) Installations for Debian Linux: As above for RedHat, except that you need the libmilter-dev package: apt-get install libmilter-dev To use TCPwrappers you need to: apt-get install libwrap0-dev 2.3 FreeBSD Installations for FreeBSD5 (may be true for other BSDs) Add to /etc/mail/freebsd.mc: INPUT_MAIL_FILTER(`clamav', `S=local:/var/run/clamav/clmilter.sock, F=, T=S:4m;R:4m')dnl define(`confINPUT_MAIL_FILTERS', `clamav') Check entry in /usr/local/etc/clamd.conf of the form: LocalSocket /var/run/clamav/clamd.sock If you already have a filter (such as spamassassin-milter from http://savannah.nongnu.org/projects/spamass-milt) add it thus: INPUT_MAIL_FILTER(`clamav', `S=local:/var/run/clamav/clmilter.sock, F=, T=S:4m;R:4m')dnl INPUT_MAIL_FILTER(`spamassassin', `S=local:/var/run/spamass.sock, F=, T=C:15m;S:4m;R:4m;E:10m') define(`confINPUT_MAIL_FILTERS', `spamassassin,clamav')dnl mkdir /var/run/clamav chown clamav /var/run/clamav (if you use User clamav in clamd.conf) chmod 700 /var/run/clamav Where /var/run/spamass.sock is the location of the spamass-milt socket file (on some systems it is in /var/run/sendmail/spamass.sock). FreeBSD5.3 sendmail comes without libmilter support. You can upgrade by cd /usr/ports/mail/sendmail make install This may overwrite your existing sendmail configuration, so ensure that you back up first. You should have received a script to install into /etc/rc.d as /etc/rc.d/clamav with this software. Add to /etc/rc.conf: clamd_enable="YES" clamav_milter_enable="YES" clamav_milter_flags="--max-children=2 --dont-wait --timeout=0 -P local:/var/run/clamav/clmilter.sock --pidfile=/var/run/clamav/clamav-milter.pid --quarantine-dir=/var/run/clamav/quarantine" 2.4 Solaris 10 Solaris 10 should install out of the box. Edit /etc/mail/cf/cf/main.mc adding the line: INPUT_MAIL_FILTER(`clamav', `S=local:/var/run/clamav/clamav-milter, F=, T=S:4m;R:4m')dnl Then: cp /etc/mail/cf/cf/main.cf /etc/mail/main.cf /usr/local/sbin/clamav-milter local:/var/run/clamav/clamav-milter mkdir /var/run/clamav chown clamav /var/run/clamav (if you use User clamav in clamd.conf) chmod 700 /var/run/clamav You should have received a script to install into /etc/init.d as /etc/init.d/clamav-milter. Then: chmod 755 /etc/init.d/clamav-milter cd /etc ln init.d/clamav-milter rc2.d/S90clamav-milter ln init.d/clamav-milter rc0.d/K90clamav-milter /etc/init.d/clamav-milter start /etc/init.d/sendmail restart 2.5 OpenBSD4.1: OpenBSD4.1 should install out of the box. Edit , or if you have none: cd into /usr/share/sendmail/cf, copy openbsd-proto.mc custom.mc, edit custom.mc adding: INPUT_MAIL_FILTER(`clamav', `S=local:/var/run/clamav/clamav-milter, F=, T=S:4m;R:4m')dnl Then run m4 ../m4/cf.m4 custom.mc >/etc/mail/localhost.cf and finally restart sendmail by sending it a SIGHUP 2.6 General Installation Issues You may find INPUT_MAIL_FILTERS is not needed on your machine, however it is recommended by the Sendmail documentation and I recommend going along with that. If you see an unsafe socket error from sendmail, it means that the permissions of the /var/run/clamav directory are too open; check you have correctly run chown and chmod. It may also mean that clamav-milter hasn't started, run ps and check your logs. The above example shows clamav-milter, clamd and sendmail all on the same machine, however using TCP they may reside on different machines, indeed clamav-milter is capable of talking to multiple clamds for redundancy and load balancing. An alternative load balancer is PEN (http://siag.nu/pen/). I suggest putting SpamAssassin first since you're more likely to get spam than a virus/worm sent to you. Add to /etc/sysconfig/clamav-milter CLAMAV_FLAGS="local:/var/run/clamav/clmilter.sock" or if clamd is on a different machine CLAMAV_FLAGS="--server=192.168.1.9 local:/var/run/clamav/clmilter.sock" If you want clamav-milter to listen on TCP for communication with sendmail, for example if they are on different machines use inet:. On machine A (running sendmail) you would have in sendmail.mc: INPUT_MAIL_FILTER(`clamav', `S=inet:3311@machineb, F=T, T=S:4m;R:4m')dnl On machine B (running clamav-milter) you would start up clamav-milter thus: clamav-milter inet:3311 You should have received a script to put into /etc/init.d with this software. You should always start clamd before clamav-milter. You may also think about the F= entry in sendmail.mc, since it tells sendmail what to do with emails if clamav-milter is not running. Setting F=T will tell the remote end to resend later (temporary failure), setting F=R will reject the email (permanent failure) and setting F= will pass the email through as though clamav-milter were not installed, in this case you should warn your users that emails are not being scanned. We recommend setting F=T. You may wish to experiment with the T= entry which governs timeout options. You MUST set some type of timeout or a malicious client could cause a Denial of Service attack by keeping your clamav-milter threads alive. The types of timeout are C (time for clamav-milter to acknowledge to sendmail that it has accepted a new connection), S (timeout for sending information from sendmail to clamav-milter), R (timeout for sendmail reading a reply from clamav-milter when it has been sent some information) and E (timeout for clamav-milter to handle the end-of-message request, this needs to be high enough to scan the largest file that you will receive since it is at this stage that the file is scanned, but short enough to ensure that a DoS can't occur when lots of scans are requested). The important entries for clamav-milter are C and E (both default to 5 minutes). WARNING: When running on internal mode (--external is NOT used), clamav-milter will need to wait for all connections to stop before it can reload the database after running freshclam. It is therefore important that NO timeouts in sendmail.cf are set too high or worse still turned off, otherwise clamav-milter can wait a long time, perhaps indefinately, while waiting for the system to quieten down. The same goes for disabling StreamMaxLength, since receiving a very large email to be scanned may take a long time. We advise setting StreamMaxLength to 1M. Don't forget to rebuild sendmail.cf after modifying sendmail.mc. You will need to restart sendmail after rebuilding sendmail.cf and starting clamd and clamav-milter. As with all software it is wise to ensure that clamav-milter has the least privileges it needs to run. So don't run it as root and don't store the sockets in a directory that can be written by everyone. For example ensure that /var/run is owned and writeable only by root and add entries for 'User' and 'FixStaleSocket' in clamd.conf. When using UNIX domain sockets via the LocalSocket option of clamd.conf, we recommend that you use the --quarantine-dir option since that may improve performance. If you wish to send a warning when a message is blocked, clamav-milter MUST be able to call sendmail, for example on a Fedora Linux system: # ls -lL /usr/lib/sendmail -rwxr-sr-x 1 root smmsp 732356 Sep 1 11:16 /usr/lib/sendmail To test that your clamAV system is now intercepting viruses, visit http://www.testvirus.org If, under heavy strain on Linux, you see the message thread_create() failed: 12, abort appearing in a log file, you will need to increase the number of threads on your system (/proc/sys/kernel/threads-max), or decrease the value of --max-children. Clamav-milter performs DNS look ups, if you wish to tweak its timeouts see resolv.conf(5). 2.7 Postfix Clamav-milter has only been designed to work with Sendmail. I understand that modern versions of Postfix have milter support, and I've heard that Clamav-milter runs with these versions of Postfix, however it is not supported with that software and I do not know how much functionality works. To start clamav-milter: # clamav-milter --sendmail-cf= --max-children=2 \ --timeout=0 --pidfile=/var/run/clamav/clamav-milter \ local:/var/spool/postfix/clamav/clamav-milter # chown clamav:postfix /var/spool/postfix/clamav/clamav-milter # chmod g+w /var/spool/postfix/clamav/clmilter In /etc/postfix/main.cf set: smtpd_milters = unix:clamav/clamav-milter non_smtpd_milters = unix:clamav/clamav-milter 3. CHANGE HISTORY See ../ChangeLog 4. INTERNATIONALISATION The .po file was created with the command xgettext --msgid-bugs-address=bugs@clamav.net --copyright-holder=njh@bandsman.co.uk -L c -d clamav-milter -k_ clamav-milter.c If you're interested in helping to translate this program please drop the author an e-mail. 5. BUG REPORTS Please send bug reports and/or comments to Nigel Horne or bugs@clamav.net. Various tips will go here, for example define(`confMILTER_LOG_LEVEL',`22') Running in the foreground, valgrind, LogSyslog, LogVerbose, LogFile etc. 5.1. Patches Patches are welcome, but they must be against the latest CVS version and adhere to the coding style of clamav-milter. Coding style is religious, everyone believes theirs is great and all others are rubbish. This is my coding style, live with it. You don't want me in a bad mood because I can't read your code when I'm deciding if your code should be incorporated. Most of this style is based on K&R. Use the tab key, not space key, to indent. Except for functions, braces always go on the same line as the condition. Don't leave to chance, or your knowledge of precedence, use brackets to highten the readability. Choose variable names sensibly, don't use Hungarian style. The code is ANSI C, not C++, remember that when thinking of comment formats, location of declarations, etc. Patches which use 'goto' will never, ever, be accepted. Use the design of your code as comments. Test your patches and document the tests when submitting, e.g. different hardware, operating systems, test tools such as valgrind, compilers (gcc, icc, Sun's cc). Function names appear at the start of lines (I use ctags). Document your changes. If you add, remove, or change functionality you will need to update the manual page and possibly the usage message as well. 6. CHROOT JAIL The instructions will differ for you, but these will give you an idea. You will have to do a lot of fiddling if you want notifications to work, since clamav-milter calls sendmail to handle the notifications and sendmail will run of out the same jail. I've not disabled the notifications, but I may in the future - for the moment handling notifications in the jail is an excercise for the reader. I've put in a symbolic link to sendmail, but I suspect it should be a real copy. mkdir /var/run/clamav-root chown clamav:clamav /var/run/clamav-root chmod 750 /var/run/clamav-root cd /var/run/clamav-root mkdir var mkdir var/tmp ln -s var/tmp . mkdir var/log cd var/log ln -s ../../../../../var/log/clamav . cd .. mkdir run mkdir run/clamav chown clamav:clamav run/clamav cd .. mkdir usr mkdir usr/local mkdir usr/local/share ln -s ../../../../../../usr/local/share/clamav . mkdir usr/lib cd usr/lib ln -s ../../../../../usr/lib/sendmail . cd ../.. mkdir dev cd dev mknod null c 1 3 chown clamav:clamav null In sendmail.mc: INPUT_MAIL_FILTER(`clamav', `S=local:/var/run/clamav-root/var/run/clamav/clmilter.sock, F=T, T=S:4m;R:4m;C:30s;E:10m')dnl When starting clamav-milter use options such as (notice that the location of clmilter.sock is different in sendmail.mc than the location clamav-milter expects to see it) --chroot=/var/run/clamav-root --max-children=3 -P --pidfile=/var/run/clamav/clamav-milter.pid --blacklist=60 --black-hole-mode local:/var/run/clamav/clmilter.sock You may need to modify your shutdown script to look for clamav-milter.pid in /var/run/clamav-root/var/run/clamav/clamav-milter.pid 7. TODO There are several ideas marked as TODO in the source code. If anyone has any other suggestions please feel free to contact me. To avoid disappointment always contact me before undertaking any work.