NAME

       clamsmtpd — an SMTP server for scanning viruses via clamd

SYNOPSIS

       clamsmtpd [-d level] [-f configfile] [-p pidfile]
       clamsmtpd -v

DESCRIPTION

       clamsmtpd is an SMTP filter that allows you to check for viruses using the ClamAV anti-virus software. It
       accepts SMTP connections and forwards the SMTP commands and responses to another SMTP server.

       The  DATA  email  body  is  intercepted  and scanned before forwarding. By default email with viruses are
       dropped silently and logged without any additional action taken.

       clamsmtpd aims to be lightweight and simple rather than have a myriad of options.  The  options  it  does
       have  are  configured  by  editing the clamsmtpd.conf(5) file. See the man page for clamsmtpd.conf(5) for
       more info on the default location of the configuration file.

OPTIONS

       Previous versions had more options. These still work for now but have  equivalents  in  clamsmtpd.conf(5)
       and are not documented here. The options are as follows.

       -d          Don't  detach  from the console and run as a daemon. In addition the level argument specifies
                   what level of error messages to display. 0 being the least, 4 the most.

       -f          configfile specifies  an  alternate  location  for  the  clamsmtpd  configuration  file.  See
                   clamsmtpd.conf(5) for more details on where the configuration file is located by default.

       -p          pidfile  specifies  a location for the a process id file to be written to. This file contains
                   the process id of clamsmtpd and can be used to stop the daemon.

       -v          Prints the clamsmtp version number and exits.

LOGGING

       clamsmtpd logs to syslogd by default under the 'mail' facility. You can also output logs to  the  console
       using the -d option.

LOOPBACK FEATURE

       In  some cases it's advantageous to consolidate the virus scanning and filtering for several mail servers
       on one machine.  clamsmtpd allows this by providing a loopback feature to connect back to the IP that  an
       SMTP connection comes in from.

       To  use  this  feature  specify  only  a  port  number  (no IP address) for the OutAddress setting in the
       configuration file. This will cause clamsmtpd to pass the email back to the said port on the incoming  IP
       address.

       Make  sure  the MaxConnections setting is set high enough to handle the mail from all the servers without
       refusing connections.

TRANSPARENT PROXY FEATURE

       A transparent proxy is a configuration on a gateway that routes certain types of traffic through a  proxy
       server  without  any  changes on the client computers.  clamsmtpd has support for transparent proxying of
       SMTP traffic by enabling the TransparentProxy setting. This type of setup usually involves firewall rules
       which redirect traffic to clamsmtpd and the setup varies  from  OS  to  OS.  The  SMTP  traffic  will  be
       forwarded to it's original destination after being scanned.

       When  doing  transparent  proxying  for  outgoing  email  it's  probably  a  good  idea to turn on bounce
       notifications using the Action: bounce setting. Also note that some features (such as SSL/TLS)  will  not
       be available when going through the transparent proxy.

       Make  sure  that  the  MaxConnections  setting  is set high enough for your transparent proxying. Because
       clamsmtpd is not being used as a filter inside a queue, which usually throttles the amount of email going
       through, this setting may need to be higher than usual.

VIRUS ACTIONS

       Using the VirusAction option you can run a script or program whenever a virus is found. This may be handy
       in certain circumstances but it has several drawbacks. For one, the performance of  the  virus  filtering
       will  take  a  hit,  perhaps  DOS'ing your machine under heavy load. Secondly as with running any program
       there are security implications to be considered.

       Please consider the above carefully before implementing a virus action.

       The script is run without its output being logged, or return value being checked.  Because  of  this  you
       should  test  it thoroughly. Make sure it runs without problems under the user that clamsmtpd(8) is being
       run as.

       Various environment variables will be present when your script is  run.  You  may  need  to  escape  them
       properly  before  use  in  your  favorite  scripting  language. Failure to do this could lead to a REMOTE
       COMPROMISE of your machine.

       CLIENT      The network address of the SMTP client connected.

       EMAIL       When the Quarantine option is enabled, this specifies the file that the virus was saved to.

       RECIPIENTS  The email addresses of the email recipients. These are specified one per  line,  in  standard
                   address format.

       REMOTE      If  clamsmtpd is being used to filter email between SMTP servers, then this is the IP address
                   of the original client. In order for this information to  be  present  (a)  the  SMTP  client
                   (sending  server) must an send an XFORWARD command and (b) the SMTP server (receiving server)
                   must accept that XFORWARD command without error.

       REMOTE_HELO
                   If clamsmtpd is being used to filter email between SMTP servers, then this is  the  HELO/EHLO
                   banner  of  the  original  client.  In  order for this information to be present (a) the SMTP
                   client (sending server) must an send an XFORWARD command and (b) the SMTP  server  (receiving
                   server) must accept that XFORWARD command without error.

       SENDER      The email address for the sender of the email.

       SERVER      The network address of the SMTP server we're connected to.

       TMPDIR      The path to the temp directory in use. This is the same as the TempDirectory option.

       VIRUS       The name of the virus found.

SECURITY

       There's  no  reason  to  run this daemon as root. It is meant as a filter and should listen on a high TCP
       port. It's probably a good idea to run it using the same user  as  the  clamd(8)  daemon.  This  way  the
       temporary files it writes are accessible to clamd(8)

       Care  should  be  taken  with  the directory that clamsmtpd writes its temporary files to. In order to be
       secure, it should not be a world writeable  location.  Specify  the  directory  using  the  TempDirectory
       setting.

       When  using  the  VirusAction  option  make  sure  you understand the security issues involved. Unescaped
       environment variables can lead to execution of arbitrary shell commands on your machine.

       If running clamsmtpd on a publicly accessible IP  address  or  without  a  firewall  please  be  sure  to
       understand all the possible security issues. This is especially true if the loopback feature is used (see
       above).

SEE ALSO

       clamsmtpd.conf(5) clamd(8), clamdscan(1)

AUTHOR

       Stef Walter <stef@memberwebs.com>

clamsmtp                                         September, 2004                                    clamsmtpd(8)