diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/.cvsignore | 3 | ||||
| -rw-r--r-- | doc/Makefile.am | 3 | ||||
| -rw-r--r-- | doc/proxsmtpd.8 | 213 | ||||
| -rw-r--r-- | doc/proxsmtpd.conf | 52 | ||||
| -rw-r--r-- | doc/proxsmtpd.conf.5 | 177 |
5 files changed, 0 insertions, 448 deletions
diff --git a/doc/.cvsignore b/doc/.cvsignore deleted file mode 100644 index 9ad01f5..0000000 --- a/doc/.cvsignore +++ /dev/null @@ -1,3 +0,0 @@ -Makefile -Makefile.in -test.conf diff --git a/doc/Makefile.am b/doc/Makefile.am deleted file mode 100644 index 9bc2bb3..0000000 --- a/doc/Makefile.am +++ /dev/null @@ -1,3 +0,0 @@ - -man_MANS = proxsmtpd.8 proxsmtpd.conf.5 -EXTRA_DIST = $(man_MANS) proxsmtpd.conf diff --git a/doc/proxsmtpd.8 b/doc/proxsmtpd.8 deleted file mode 100644 index 9f9f9d0..0000000 --- a/doc/proxsmtpd.8 +++ /dev/null @@ -1,213 +0,0 @@ -.\" -.\" 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 CLIENT -The network address of the SMTP client connected. -.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 SERVER -The network address of the SMTP server we're connected to. -.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 advantageous 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 deleted file mode 100644 index 2b87e84..0000000 --- a/doc/proxsmtpd.conf +++ /dev/null @@ -1,52 +0,0 @@ -# ------------------------------------------------------------------------------ -# 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 - -# A header to add to all scanned email -#Header: X-Filtered: By ProxSMTP - -# Keep Alives (ie: NOOP's to server) -#KeepAlives: 0 - -# Send XCLIENT commands to receiving server -#XClient: off - -# 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 deleted file mode 100644 index 916bc7b..0000000 --- a/doc/proxsmtpd.conf.5 +++ /dev/null @@ -1,177 +0,0 @@ -.\" -.\" 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 its 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 come 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. -.Pp -[ Default: no filtering ] -.It Ar FilterTimeout -The amount of time in seconds to wait for the -.Ar FilterCommand -to process email data. -.Pp -[ 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. -.Pp -[ Default: pipe ] -.It Ar Header -A header to add to scanned messages. Put an empty value to suppress adding -a header. You can include the following special formatting characters in the -string to include special values: -.Bl -inset -.It Ar %i -Client IP Address -.It Ar %l -Local IP Address -.It Ar %d -Current Date -.El -.Pp -You can also include the standard \\r or \\n escapes. -.Pp -[ Optional ] -.It Ar KeepAlives -On slow connections the server will sometimes timeout before -.Xr proxsmtpd 8 -is finished filtering the file. This option sends NOOP's to the server -to keep the connection alive. Specify the number of seconds, or 0 -to disable. -.Pp -[ Default: 0 ] -.It Ar Listen -The address and port to listen for SMTP connections on. See syntax of -addresses below. -.Pp -[ Default: port 10025 on all local IP addresses ] -.It Ar MaxConnections -Specifies the maximum number of connections to accept at once. -.Pp -[ 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. -.Pp -[ Required ] -.It Ar TempDirectory -The directory to write temp files to. -.Pp -[ Default: -.Pa /tmp -] -.It Ar TimeOut -The number of seconds to wait while reading data from network connections. -.Pp -[ 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. -.Pp -[ Default: off ] -.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. -.Pp -[ Optional ] -.It Ar XClient -Send an XCLIENT command to the receiving server. This is useful for forwarding -client addresses and connection info to servers that support this feature. -.Pp -[ Default: off ] -.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 |