.\" 
.\" Copyright (c) 2004, Nate Nielsen
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without 
.\" modification, are permitted provided that the following conditions 
.\" are met:
.\" 
.\"     * Redistributions of source code must retain the above 
.\"       copyright notice, this list of conditions and the 
.\"       following disclaimer.
.\"     * Redistributions in binary form must reproduce the 
.\"       above copyright notice, this list of conditions and 
.\"       the following disclaimer in the documentation and/or 
.\"       other materials provided with the distribution.
.\"     * The names of contributors to this software may not be 
.\"       used to endorse or promote products derived from this 
.\"       software without specific prior written permission.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
.\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
.\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
.\" FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 
.\" COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 
.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 
.\" OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED 
.\" AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, 
.\" OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF 
.\" THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH 
.\" DAMAGE.
.\" 
.\"
.\" CONTRIBUTORS
.\"  Nate Nielsen <nielsen@memberwebs.com>
.\"
.Dd July, 2004
.Dt clamsmtpd 8
.Os clamsmtp 
.Sh NAME
.Nm clamsmtpd
.Nd an SMTP server for scanning viruses via clamd
.Sh SYNOPSIS
.Nm
.Op Fl bq
.Op Fl c Ar clamaddr
.Op Fl d Ar level
.Op Fl D Ar tmpdir
.Op Fl h Ar header
.Op Fl l Ar listenaddr
.Op Fl m Ar maxconn
.Op Fl p Ar pidfile
.Op Fl r 
.Op Fl t Ar timeout
.Ar serveraddr
.Sh DESCRIPTION
.Nm
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. 
.Pp
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.
.Pp
.Nm
aims to be lightweight and simple rather than have a myriad of options. Your
basic usage would look like the following (Be sure to see the SECURITY section
below):
.Pp
.Dl clamsmtpd -c /path/to/clam.sock mysmtp.com:25
.Pp
The above command would start 
.Nm
listening on port 10025 (the default) and forward email to mysmtp.com on port 25. 
It also specifies the socket where 
.Xr clamd 8
is listening for connections.
.Sh OPTIONS
The options are as follows:
.Bl -tag -width Fl
.It Fl b
When this flag is set 
.Nm 
actively rejects messages with viruses. This may cause the sender to receive
a message back notifying them of the virus. In most cases this is not a good
idea since many viruses spoof sender addresses. 
.It Fl c 
.Ar clamaddr 
specifies the address to connect to 
.XR clamd 8
on. See syntax of addresses below. 
[Default:  
.Pa /var/run/clamav/clamd
]
.It Fl d 
Don't detach from the console and run as a daemon. In addition the 
.Ar level
argument specifies what level of error messages to display. 0 being 
the least, 4 the most.
.It Fl D
.Ar tmpdir 
is the directory to write temp files too. This directory needs to be 
accessible to both 
.Xr clamd 8
and 
.Nm
[Default:
.Pa /tmp
]
.It Fl h
.Ar header
is a header to add to scanned messages. Add a blank argument to not add 
a header. [Default: 'X-AV-Checked: ClamAV using ClamSMTP']
.It Fl l
.Ar listenaddr
is the address and port to listen for SMTP connections on. See syntax of 
addresses below. [Default: port 25 on all local IP addresses] 
.It Fl m
.Ar maxconn 
specifies the maximum number of connections to accept at once. 
[Default: 64]
.It Fl p
This option causes 
.Nm
to write a file with the daemon's process id, which can be used to stop the 
daemon.
.Ar pidfile 
is the location of the file.
.It Fl q
Quarantine files that contain viruses by leaving them in the
.Ar tmpdir 
directory. The file names look like this (where X is a random 
character or number):
.Pa virus.XXXXXX
.It Fl t
.Ar timeout
is the number of seconds to wait while reading data from network connections.
[Default: 180 seconds]
.It serveraddr
The address of the SMTP server to send email to once it's been scanned. This
option must be specified. See syntax of addreses below. 
.El
.Sh LOGGING
.Nm
logs to 
.Xr syslogd 
by default under the 'mail' facility. You can also output logs to the console
using the 
.Fl d 
option.
.Sh LOOPBACK FEATURE
In some cases it's advantagous to consolidate the virus scanning and filtering 
for several mail servers on one machine. 
.Nm
allows this by providing a loopback feature to connect back to the IP that an 
SMTP connection comes in from. 
.Pp
To use this feature specify only a port number (no IP address) for the 
.Ar serveraddr
in which case
.Nm
will pass the email back to the said port on the incoming IP address.
.Pp
Make sure the 
.Ar maxconn
setting is set high enough to handle the mail from all the servers without refusing
connections. 
.Sh 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 
.Xr clamd 8
daemon. This way the temporary files it writes are accessible to 
.Xr clamd 8
.Pp
Care should be taken with the directory that 
.Nm
writes its temporary files to. In order to be secure, it should not be a world
writeable location. Specify the directory using the 
.Fl t
option.
.Pp
.Nm
should probably not be run on a publicly accessible IP address or without a 
firewall. This is especially true if the loopback feature is used (see above).
.Sh ADDRESSES
Addresses can be specified in multiple formats:
.Bl -bullet
.It 
Unix local addresses can be specified by specifying their full path. 
(ie: '/var/run/clamav/clamd').
.It 
IP addresses can be specified using dotted notation with a colon before
the port number (ie: '127.0.0.1:3310').
.It 
IPv6 addresses can be specified using bracketted notation with a colon 
before the port number (ie: '[::1]:3310')
.El
.Sh SEE ALSO
.Xr clamd 8 ,
.Xr clamdscan 1 
.Sh AUTHOR
.An Nate Nielsen Aq nielsen@memberwebs.com