Configuration file for clamsmtp

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