diff options
Diffstat (limited to 'doc/proxsmtpd.8')
| -rw-r--r-- | doc/proxsmtpd.8 | 209 |
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 |