Man pages and sample config file.

1 files changed, 209 insertions, 0 deletions

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