diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 3 | ||||
| -rw-r--r-- | doc/clamsmtpd.8 | 135 | ||||
| -rw-r--r-- | doc/clamsmtpd.conf | 40 | ||||
| -rw-r--r-- | doc/clamsmtpd.conf.5 | 142 |
4 files changed, 320 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..44dfc12 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,3 @@ + +man_MANS = clamsmtpd.8 clamsmtpd.conf.5 +EXTRA_DIST = $(man_MANS) clamsmtpd.conf diff --git a/doc/clamsmtpd.8 b/doc/clamsmtpd.8 new file mode 100644 index 0000000..8ee3d80 --- /dev/null +++ b/doc/clamsmtpd.8 @@ -0,0 +1,135 @@ +.\" +.\" 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 September, 2004 +.Dt clamsmtpd 8 +.Os clamsmtp +.Sh NAME +.Nm clamsmtpd +.Nd an SMTP server for scanning viruses via clamd +.Sh SYNOPSIS +.Nm +.Op Fl d Ar level +.Op Fl f Ar configfile +.Nm +.Fl v +.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. The options +it does have are configured by editing the +.Xr clamsmtpd.conf 5 +file. See the man page for +.Xr clamsmtpd.conf 5 +for more info on the default location of the configuration file. +.Sh OPTIONS +Previous versions had more options. These still work for now but have equivalents in +.Xr clamsmtpd.conf 5 +and are not documented here. The options are as follows. +.Bl -tag -width Fl +.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 f +.Ar configfile +specifies an alternate location for the +.Nm +configuration file. See +.Xr clamsmtpd.conf 5 +for more details on where the configuration file is located by default. +.It Fl v +Prints the clamsmtp version number and exits. +.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 OutAddress +setting in the configuration file. This will cause +.Nm +to pass the email back to the said port on the incoming IP address. +.Pp +Make sure the +.Ar MaxConnections +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 +.Ar TempDirectory +setting. +.Pp +If running +.Nm +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). +.Sh SEE ALSO +.Xr clamsmtpd.conf 5 +.Xr clamd 8 , +.Xr clamdscan 1 +.Sh AUTHOR +.An Nate Nielsen Aq nielsen@memberwebs.com diff --git a/doc/clamsmtpd.conf b/doc/clamsmtpd.conf new file mode 100644 index 0000000..979103c --- /dev/null +++ b/doc/clamsmtpd.conf @@ -0,0 +1,40 @@ +# ------------------------------------------------------------------------------ +# SAMPLE CLAMSMTPD CONFIG FILE +# ------------------------------------------------------------------------------ +# +# - Comments are a line that starts with a # +# - All the options are found below with their defaults commented out + + +# The address to send scanned mail to. Required +OutAddress: 10026 + + + +# The maximum number of connection allowed at once +#MaxConnections: 64 + +# Amount of time (in seconds) to wait on network IO +#TimeOut: 180 + +# Address to listen on (defaults to all local addresses on port 10025) +#Listen: 0.0.0.0:10025 + +# The address clamd is listening on +#ClamAddress: /var/run/clamav/clamd + +# A header to add to all scanned email +#ScanHeader: X-AV-Checked: ClamAV using ClamSMTP + +# Directory for temporary files +#TempDirectory: /tmp + +# Whether or not to bounce email (default is to silently drop) +#Bounce: off + +# Whether or not to keep virus files +#Quarantine: off + +# The location for a pid file for stopping clamsmtpd +#PidFile: (none) + diff --git a/doc/clamsmtpd.conf.5 b/doc/clamsmtpd.conf.5 new file mode 100644 index 0000000..ffbd204 --- /dev/null +++ b/doc/clamsmtpd.conf.5 @@ -0,0 +1,142 @@ +.\" +.\" 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 September, 2004 +.Dt clamsmtpd.conf 5 +.Os clamsmtp +.Sh NAME +.Nm clamsmtpd.conf +.Nd the configuration file for +.Xr clamsmtpd 8 +.Sh DESCRIPTION +.Xr clamsmtpd 8 +reads a configuration file when starting up. The location of the file is dependent +on how you compiled clamsmtp but it should usually be in either the +.Pa /usr/local/etc/ +or +.Pa /etc/ +directories. If +.Xr clamsmtpd 8 +does not find it's configuration file it'll print a warning when it starts up along +with the location it's expecting to find it in. You can also specify a different +location for a config file by passing the +.Fl f +argument to +.Xr clamsmtpd 8 +.Pp +The settings are specified one per line. The setting names comes first, followed +by a colon and then the value. Comments start with the '#' character on a line +of their own. Whitespace is ignored at the beginning of line, end of line and +around the colons. +.Pp +A sample configuration file can be found in the +.Pa doc/ +directory of the clamsmtp distribution. +.Sh SETTINGS +The various settings are as follows: +.Bl -tag -width Fl +.It Ar Bounce +When this flag is set +.Xr clamsmtpd 8 +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. +[ Default: off ] +.It Ar ClamAddress +Specifies the address to connect to +.Xr clamd 8 +on. See syntax of addresses below. +[ Default: +.Pa /var/run/clamav/clamd +] +.It Ar Listen +The address and port to listen for SMTP connections on. See syntax of +addresses below. +[ Default: port 10025 on all local IP addresses ] +.It Ar Quarantine +Quarantine files that contain viruses by leaving them in the +.Ar TempDirectory +directory. The file names look like this (where X is a random +character or number): +.Pa virus.XXXXXX +[ Default: off ] +.It Ar MaxConnections +Specifies the maximum number of connections to accept at once. +[ Default: 64 ] +.It Ar PidFile +This option causes +.Xr clamsmtpd 8 +to write a file with the daemon's process id, which can be used to stop the +daemon. +[ Optional ] +.It Ar ScanHeader +A header to add to scanned messages. Put an empty value to supress adding +a header. +[ Default: 'X-AV-Checked: ClamAV using ClamSMTP' ] +.It Ar OutAddress +The address of the SMTP server to send email to once it's been scanned. See +syntax of addreses below. +[ Required ] +.It TempDirectory +The directory to write temp files too. This directory needs to be +accessible to both +.Xr clamd 8 +and +.Xr clamsmtpd 8 +[ Default: +.Pa /tmp +] +.It Ar TimeOut +The number of seconds to wait while reading data from network connections. +[ Default: 180 seconds ] +.El +.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 clamsmtpd 8 +.Sh AUTHOR +.An Nate Nielsen Aq nielsen@memberwebs.com |