diff options
| -rw-r--r-- | doc/Makefile.am | 4 | ||||
| -rw-r--r-- | doc/proxsmtpd.8 | 209 | ||||
| -rw-r--r-- | doc/proxsmtpd.conf | 43 | ||||
| -rw-r--r-- | doc/proxsmtpd.conf.5 | 135 |
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 |