summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--doc/Makefile.am4
-rw-r--r--doc/proxsmtpd.8209
-rw-r--r--doc/proxsmtpd.conf43
-rw-r--r--doc/proxsmtpd.conf.5135
4 files changed, 389 insertions, 2 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index e548c86..9bc2bb3 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -1,3 +1,3 @@
-#man_MANS = proxsmtpd.8 proxsmtpd.conf.5
-#EXTRA_DIST = $(man_MANS) proxsmtpd.conf
+man_MANS = proxsmtpd.8 proxsmtpd.conf.5
+EXTRA_DIST = $(man_MANS) proxsmtpd.conf
diff --git a/doc/proxsmtpd.8 b/doc/proxsmtpd.8
new file mode 100644
index 0000000..fc10eec
--- /dev/null
+++ b/doc/proxsmtpd.8
@@ -0,0 +1,209 @@
+.\"
+.\" 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 proxsmtpd 8
+.Os proxsmtp
+.Sh NAME
+.Nm proxsmtpd
+.Nd an SMTP server for performing filtering
+.Sh SYNOPSIS
+.Nm
+.Op Fl d Ar level
+.Op Fl f Ar configfile
+.Op Fl p Ar pidfile
+.Nm
+.Fl v
+.Sh DESCRIPTION
+.Nm
+is an SMTP filter that allows you to perform arbitrary filtering on email. 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. Email can be
+altered, bounced, or silently dropped.
+.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 proxsmtpd.conf 5
+file. See the man page for
+.Xr proxsmtpd.conf 5
+for more info on the default location of the configuration file.
+.Sh OPTIONS
+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 proxsmtpd.conf 5
+for more details on where the configuration file is located by default.
+.It Fl p
+.Ar pidfile
+specifies a location for the a process id file to be written to. This file
+contains the process id of
+.Nm
+and can be used to stop the daemon.
+.It Fl v
+Prints the proxsmtp version number and exits.
+.El
+.Sh FILTER SCRIPTS
+The filter script is specified using the
+.Ar FilterCommand
+option. By default the email is piped through the script on standard input.
+Standard output is read for the filtered email. Standard error is also read
+for error messages.
+.Pp
+If the
+.Ar FilterType
+option is set to 'file', your filter will operate on a file rather than processing
+standard in and standard out. The file name will be passed to your filter
+command using the
+.Ar EMAIL
+environment variable. Your script can change the file as needed. Standard error
+is still processed as outlined below.
+.Pp
+If the filter command returns a successful exit code (ie: 0), then the filtered
+email is sent to the destination mail server as usual. When a error exit code
+(ie: anything but 0) a failure message is sent back to the sending server. In
+this case the email is not sent.
+.Pp
+You can customize the error message sent back. The last line of output printed
+to standard error will be used in this case. If you specify a full SMTP error
+code then it will be used (ie: '550 Bad Email'). If it's just a text message
+then a 550 SMTP error code will be used.
+.Pp
+You can silently drop messages by using an error message with a 250 SMTP code.
+This gives the illusion to the sending server that the email was accepted.
+.Pp
+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.
+.Bl -tag -width Fl
+.It Ar EMAIL
+When the
+.Ar FilterType
+option is set to 'file', this specifies the file that the email was saved to.
+.It Ar RECIPIENTS
+The email addresses of the email recipients. These are specified one per
+line, in standard address format.
+.It Ar SENDER
+The email address for the sender of the email.
+.It Ar TMPDIR
+The path to the temp directory in use. This is the same as the
+.Ar TempDirectory
+option.
+.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 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 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.
+.Nm
+has support for transparent proxying of SMTP traffic by enabling the
+.Ar TransparentProxy
+setting. This type of setup usually involves firewall rules which redirect traffic to
+.Nm
+and the setup varies from OS to OS. The SMTP traffic will be forwarded to it's
+original destination after being scanned.
+.Pp
+Note that some features (such as SSL/TLS) will not be available
+when going through the transparent proxy.
+.Pp
+Make sure that the
+.Ar MaxConnections
+setting is set high enough for your transparent proxying. Because
+.Nm
+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.
+.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.
+.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
+Make sure you understand the issues involved with escaping external data. The
+environment variables such as
+.Ar SENDER
+or
+.Ar RECIPIENTS
+need to be treated with care.
+.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 proxsmtpd.conf 5
+.Sh AUTHOR
+.An Nate Nielsen Aq nielsen@memberwebs.com
diff --git a/doc/proxsmtpd.conf b/doc/proxsmtpd.conf
new file mode 100644
index 0000000..0138e94
--- /dev/null
+++ b/doc/proxsmtpd.conf
@@ -0,0 +1,43 @@
+# ------------------------------------------------------------------------------
+# SAMPLE PROXSMTPD CONFIG FILE
+# ------------------------------------------------------------------------------
+#
+# - Comments are a line that starts with a #
+# - All the options are found below with sample settings
+
+
+# The address to send scanned mail to.
+# This option is required unless TransparentProxy is enabled
+OutAddress: 10026
+
+# The Filter Command run for each email. See 'man proxsmtpd' for details
+# The following command is a simple which just creates temp files.
+#FilterCommand: tee `mktemp -t sample-filter.XXXXXX`
+
+# The amount of time to wait for data from FilterCommand
+#FilterTimeout: 10
+
+# The type of filter ('pipe' to pipe data through filter,
+# or 'file' to pass a file to the filter)
+#FilterType: pipe
+
+# The maximum number of connection allowed at once.
+# Be sure that clamd can also handle this many connections
+#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
+
+# Directory for temporary files
+#TempDirectory: /tmp
+
+# Enable transparent proxy support
+#TransparentProxy: off
+
+# User to switch to
+#User: nobody
+
+
diff --git a/doc/proxsmtpd.conf.5 b/doc/proxsmtpd.conf.5
new file mode 100644
index 0000000..75495e4
--- /dev/null
+++ b/doc/proxsmtpd.conf.5
@@ -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 proxsmtpd.conf 5
+.Os proxsmtp
+.Sh NAME
+.Nm proxsmtpd.conf
+.Nd the configuration file for
+.Xr proxsmtpd 8
+.Sh DESCRIPTION
+.Xr proxsmtpd 8
+reads a configuration file when starting up. The location of the file is dependent
+on how you compiled proxsmtp but it should usually be in either the
+.Pa /usr/local/etc/
+or
+.Pa /etc/
+directories. If
+.Xr proxsmtpd 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 proxsmtpd 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 proxsmtp distribution.
+.Sh SETTINGS
+The various settings are as follows:
+.Bl -tag -width Fl
+.It Ar FilterCommand
+This is the command used to filter email through. If not specified then no
+filtering will be done. Specify all the arguments the command needs as you
+would on a command-line.
+[ Default: no filtering ]
+.It Ar FilterTimeout
+The amount of time in seconds to wait for the
+.Ar FilterCommand
+to process email data.
+[ Default: 30 seconds ]
+.It Ar FilterType
+When set to 'pipe' the email data is piped through the
+.Ar FilterCommand
+using standard in and standard out. When set to 'file' the email data is saved
+to a file and the file name is passed to the
+.Ar FilterCommand
+using the
+.Ar EMAIL
+environment variable.
+.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 MaxConnections
+Specifies the maximum number of connections to accept at once.
+[ Default: 64 ]
+.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 Ar TempDirectory
+The directory to write temp files too.
+[ Default:
+.Pa /tmp
+]
+.It Ar TimeOut
+The number of seconds to wait while reading data from network connections.
+[ Default: 180 seconds ]
+.It Ar TransparentProxy
+This option enables transparent proxy support, which allows you to route all
+SMTP traffic that's going through a gateway through proxsmtp which will then
+send it on to its final destination. This setup usually involves firewall
+rules which redirect traffic to proxsmtp, and the setup varies from OS to OS.
+.It Ar User
+The user to run as. If this option is specified then
+.Xr proxsmtpd 8
+must be started as root. It will then drop root privileges and run as the
+specified user. The user can either be a name or a numerical user id.
+.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/socket').
+.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 are implemented but disabled. The code needs testing.
+.El
+.Sh SEE ALSO
+.Xr proxsmtpd 8
+.Sh AUTHOR
+.An Nate Nielsen Aq nielsen@memberwebs.com