SMTP.PROXY(1) SMTP.PROXY(1)
NAME
smtp.proxy - SMTP proxy server
SYNOPSIS
smtp.proxy [options] [server ...]
smtp.proxy [options] [/path/to/cmd ...]
DESCRIPTION
smtp.proxy is a proxy server for the SMTP protocol. It forwards traf‐
fic between a client and a server watching that the client fullfills
the protocol specification.
smtp.proxy is usually started from a TCP superserver like inetd(1) or
tcpproxy(1) but can also run in standalone mode or under control of a
supervise process.
server can be either a list of SMTP servers or th full path a local
mail server binary followed by required options to start the program in
SMTP mode. The server argument may be omited if smtp.proxy is config‐
ured to use a configuration file.
Protocol Support
smtp.proxy supports the following SMTP commands:
HELO, EHLO
[MAIL|SEND|SOML|SAML] FROM, RCPT TO, DATA,
NOOP, RSET, HELP, ETRN, QUIT
Unsupported SMTP commands result in a syslog message without forwarding
the command to the server. ETRN is only supported if the -e option is
given on the command line.
Email addresses are checked againt some simple tests:
- they must be enclosed in angle brackets ‘<’, ‘>’,
- they must contain exactly one ‘@’,
- they must not contain a ‘!’,
- ‘:’ and ‘,’ characters are also not allowed.
While these checks block some valid email addresses they are almost
what you want these days in an Internet with DNS.
The special envelop address ‘<>’ is always allowed.
Server Argument
smtp.proxy supports a list of servernames (or IP-numbers). It will try
the servers on the list until it can connect to one of them. If more
than one server is given, smtp.proxy tries to apply simple round-robin
scheme to it: it uses the value from the file /var/tmp/smtp.last to
determine on which server on the list to start of its pid if the file
does not provide a useable value. The mode (and filename) filename can
be set with the server-type option, possible values are:
round-robin
which sets round-robin as explained above. This option value
may be followed by the named of the last-server file.
prim-sec
which tries the servers always in the listed order.
Configuration File
A lot smtp.proxy features can be turned on with command line options
but no all. The use of a configuration file, -f option, is strongly
recommended.
POP3 before SMTP
smtp.proxy can be configured to do "POP3 before SMTP" checking. This
is done by configuring a directory with the clientip-dir option where
smtp.proxy looks files named after the client’s IP-number. If such a
file exists and the file is not older than 10 minutes than the client
is allowed to send e-mail and rejected with a 421 otherwise. The
client IP-number files are usually created from a POP3 server.
pop3.proxy(1) supports this feature also.
Early Talker Rejection
After smtp.proxy accepted a new connection it waits one second to see
if the clients starts immediately to send to the server. If it does
(not waiting for the server’s client greeting) the e-mail is rejected
with a 421 response.
Message-ID Adding
If smtp.proxy receives e-mails without message-ids it creates its own
and adds it to the mail.
pidfile
If smtp.proxy runs in standalone mode is can be configured to create a
pidfile with it’s process id in. smtp.proxy tries to remove this file
automatically removed when it terminates but usually fails because of a
permission problem. The pidfile is created with root permissions but
attempting to remove the file is done under another user (e.g. nobody,
clamav etc.). If this happens smtp.proxy tries to erase the file, that
is to leave it empty.
Received: Path Dropping
smtp.proxy may drop the Received: path from each mail is forwards to
hide network internal details. To enable this option, droppath must be
set to yes.
Session Status Files
smtp.proxy can create and update status files for each active proxy
session. Session status files are enabled by configuring a directory
where the files should be created with the statdir option. Each file
contains the following data: proxy name (always smtp.proxy),
- the proxy’s program filename,
- pid of the process,
- time when the session started as seconds from 1970,
- proxy’s interface IP-number and port,
- client IP-number,
- client name
- server IP-number and port,
- unused
- current session status
Session status files are automatically removed when the session termi‐
nates.
CPU Load Monitoring
smtp.proxy checks the CPU load before accepting new SMTP sessions.
This feature is automatically enabled and can be configured by giving
three numeric values to the maxloadavg option, the default values are
"10 0 0". Each of the three numbers is compared againt it’s counter‐
part from /proc/loadavg if it is not zero, it it’s zero no comparison
is done on this value. If all compared values from /proc/loadavg are
above the configured treshholds, the session is rejected with a 421
response.
To disable CPU load checking set all three treshholds to 0. This fea‐
ture requires /proc/loadavg to exist and to be formatted as smtp.proxy
expects it.
VIRUS SCANNING
Virus scanning is enabled by setting the clamav-scan option to yes. In
this case smtp.proxy expects clamd to run on the localhost on port
3310. By default virulent e-mails are dropped and a 250 status code in
response is sent to the client. Virus quarantining can be enabled by
configuring a quarantine directory with the clamav-qdir option.
Other options are clamav-passonerror which controls if e-mails are for‐
warded if a clamav protocol error occurs and clamav-passonvirus which
enables forwarding of viruses. These two options make only sense if
smtp.proxy and clamav are only the first line of defence.
For more information regarding mail quarantining see below.
SPAM SCANNING
smtp.proxy may use spamassassin for spam scanning. To enable this, the
spamc-scan option must be set to yes. The spamc-cmd option can be used
to modify the invocation of the spamassassin client if it is not
"/usr/bin/spamc -c".
By default recognized spam is tagged with the word ‘[SPAM]’ in the e-
mail subject and forwarded to the server. The tag can be changed with
the spamc-tag option. Spam can also be quarantined which requires that
the spam quarantine area is configured (see below), that the spamc-
quarantine option is set to yes and that the spamc-treshhold option
sets a spam score (set by spamassassin) above which spam goes into the
quarantine.
Only e-mails with a size less than 250 kByte are scanned for spam.
MAIL QUARANTINING
This section explains quaratining for spam virulent e-mails. Both sub‐
systems are configured with the same options using different prefixes
(clamav and spamc). Replace the xx found here with the correct prefix.
To successfully quarantine e-mails, first the quarantine directory must
be configured with the xx-qdir and smtp.proxy’s directory for temporary
files (see the tmpdir option) must be configured to be on the same
harddisk partition (smtp.proxy moves files into quarantine).
smtp.proxy creates automatically subdirectories for quarantine e-mails,
one for each day on which it receives an e-mail to quarantine, and
names them after the current date, YYYY-MM-DD format. This behaviour
can be changed with the xx-dirmode options. Possible values are
autosubdir
the default described above.
plain do not create subdirectories, store all files in the quarantine
directory.
A second option is th eindex style which is set with the xx-index
option. By default smtp.proxy creates a .info file for each quaran‐
tined e-mail which holds the SMTP protocol information the the mail.
Possible options are
info create .info files for each mail, this is the default.
table write the information into the file .index.tab.
none do not store any additional information.
DNS BLACKLISTING
smtp.proxy can query DNS blacklists to reject e-mails. To active RBL
checking one or more DNS blacklist servers must be configured with the
rbl-server option. The exact behaviour can then be controlled with the
rbl-mode option. Possible values are
reject reject blacklisted clients immediately after they connect. This
is the default.
quarantine
quarantine blacklisted mails in the spam quarantine directory
(which must be configured of course).
log-only
log blacklisted clients but forward the mails.
delayed
reject blacklisted clients as response to the MAIL command.
The reject code is in any case 451.
CONTROL PROGRAMS
smtp.proxy supports two kinds of external control programs, access and
command control programs.
The control programs are external programs (e.g. shell scripts) that
are called by the proxy in a defined context (see below) and may permit
or reject the current e-mail.
Access Control
If given the acp is called after the client’s DATA command before the
DATA’s SMTP response is send to the client. The acp can then decide,
e.g. based on the sender’s and recipient’s e-mail addresses if the e-
mail should be processed or not. See below for a listing of environ‐
ment variables that are set for the acp.
Command Control
If a ccp is given the e-mail from the client is first read into a tem‐
porary file without sending anything to the SMTP server. The ccp can
then also inspect the e-mail’s content and/or size to decide if the e-
mail should be further processed or not.
Notice that smtp.proxy does not prevent timeouts occuring on the SMTP
server while receiving the e-mail.
Environment Variables
Both types of control programs are called with the following variables
set.
SMTP_PID
the pid of the calling smtp.proxy.
SMTP_LOGLABEL
a label suitable for syslog logging.
SMTP_SERVER
the name of the server that is the proxy connected to.
SMTP_CLIENT, SMTP_CLIENTNAME
IP number and name of the client.
SMTP_SENDER
the sender’s e-mail address enclosed in angle brackets.
SMTP_NRCPT
the number of recipients.
SMTP_RCPT
the space separated list of all recipients. The addresses are
not enclosed in angle brackets.
SMTP_RCPTV
same as above but this time as rc(1)/akanga(1) compatible list.
Additionally the ccp receives the following settings:
SMTP_MAIL
a temporary file which contains the e-mail from the client.
SMTP_SIZE
the e-mail’s size.
Response Codes
smtp.proxy reads the first line of the program’s standard output and
standard error. If a line is found on stdout it’s written to the sys‐
log. This is meant to be a diagnostic message for the proxy adminis‐
trator.
The output on the program’s stderr should contain a valid SMTP response
(including the diagnostic message for the client) and is used in con‐
junction with the program’s exit code to decide how to continue with
the e-mail.
The control program’s response is interpreted as follows:
250, 354
positive response, the e-mail is further processed. Notice that
the program’s exit code must be 0. If not the positive response
is ignored and replaced by a "421 server error".
status codes 4xx and 5xx
they are passed on an as-is basis to the client and e-mail pro‐
cessing is terminated at this point.
Any other response code is replaced by a 421.
If smtp.proxy receives nothing on the control program’s stderr e-mail
processing is determined only on the program’s exit code:
0 positive response, e-mail is further processed.
1 send a 451 transient error resonse and terminate e-mail process‐
ing.
any other
send a 554 permanent error response and terminate e-mail pro‐
cessing.
If e-mail processing is terminated by a control program the connection
to the SMTP server is resetted with the RSET command. Furthermore 4xx
and 5xx status code messages are also written to syslog.
Notice that if the SMTP status code is 421 (for any reason) smtp.proxy
terminates the connection to the client.
CONFIGURATION FILE
smtp.proxy can read it’s configuration options from a configuration
file (-f option). Each line which is neither empty nor a UNIX-style
‘#’ comment is expected to specifiy a valid option and the option’s
value. The list below uses the data types
boolean
can be ‘yes’ or ‘no’.
list a comma/space separated list of words.
num is a numeric value.
string the characters till the end of the line.
word character sequence without blanks.
If an option has an incompatible parameter smtp.proxy terminates with
an error message. The following options are supported:
acp string
sets the full path to the access control program.
ccp string
sets the full path to the command control program.
clientip-dir string
sets the directory where smtp.proxy looks for the POP3 before
SMTP files.
daemonmode boolean
turns standalone mode on or off.
debug boolean
turns debugging on or off.
droppath boolean
defines if the mailpath should be removed from or not.
etrn boolean
turns support for the ETRN command on or off.
maxloadavg num num num
sets maximum load average values for mail processing. If the
system’s load average values as found in __/proc/loadavg__ are
greater than the configued values, smtp.proxy refuses mail pro‐
cessing with a 412 code.
pidfile filename
sets the name to smtp.proxy’s pid file, only created in daemon
mode.
port word
port number on which to bind. The port parameter might be pre‐
fixed with an interface on which smtp.proxy should bind.
rcptlist string
gives the list of allowed recipients as comma separated list.
srcip ipnum
sets the IP number for smtp.proxy’s outgoing connections.
senderlist list
gives the list of allowed senders as comma separated list.
server word-list
defines the SMTP server. If more that one server is given, the
servers are tried in the listed order. Each server may be fol‐
lowed by a slash and an IP number which defines then the IP num‐
ber for smtp.proxy’s outgoing connection.
server-type word [filename]
sets the server mode in case that more than one server is con‐
figured. Valid options are prim-sec or round-robin. If the
mode is round-robin the optional filename configures where
smtp.proxy stores which server to try first.
source-ip ipnumber
sets the local IP-number with which smtp.proxy connects to it’s
upstream server.
statdir word
defines the directory for smtp.proxy’s session status files.
supervised boolean
must be set to yes if smtp.proxy is controlled by a qmail super‐
vise process.
timeout num
sets the connection timeout in seconds (default is 300).
tmpdir dir
sets the directory for smtp.proxy’s temporary files, used for
virus and spam scanning.
username string
user under which the daemon will run.
varname string
defines the common prefix for the control program’s environment
variables (default is ‘SMTP_’).
clamav Configuration
clamav-dirmode word
sets the virus quarantine directory mode, possible options are
autosubdir, flat and plain.
clamav-index word
sets the virus quarantine directory index mode, possible options
are info, table and none.
clamav-passonerror boolean
if set to yes smtp.proxy will forward e-mails if a virus scan‐
ning error appears.
clamav-passonvirus boolean
enables e-mail forwaring if virulent mails are found.
clamav-qdir dir
set the virus quarantine directory.
clamav-scan boolean
turns virus scanning on or off.
spamassassin Configuration
spamc-cmd string
defines the spamassassin command line, "/usr/bin/spamc -c" is
the default.
spamc-dirmode word
sets the spam quarantine directory mode, possible options are
autosubdir, flat and plain.
spamc-index word
sets the spam quarantine directory index mode, possible options
are info, table and none.
spamc-qdir dir
sets the spam quarantine directory.
spamc-quarantine boolean
turns spam quarantining on or off.
spamc-scan boolean
turns spam scanning on or off.
spamc-tag word
defines a string that is used to label the subject of identified
spam.
spamc-trashhold num
set the value above which spam is quarantined.
RBL Configuration
rbl-firstmatch boolean
defines if blacklist querying stops after the first match, the
default if yes.
rbl-mode word
sets the RBL mode, valid options are reject, quarantine, logonly
and delayed.
rbl-server list
sets a list RBL servers. Setting one or more RBL servers turns
automatically blacklisting on.
Interface Sections
smtp.proxy’s configuration file may contain interface specific configu‐
rations after the normal, global, configuration. These sections start
with a line of the form ‘[ipnum]’ where ipnum is the interface’s IP-
number. smtp.proxy checks for such sections as soon as it has the con‐
nection to the client. If it does not have a section for that inter‐
face but for other interfaces smtp.proxy will drop the connection. In
other words, if you run smtp.proxy with interface specific configura‐
tions, the configuration file must have a section for every valid
interface, even if it does not have a different configuration.
Notice furthermore that smtp.proxy reads the global configuration on
startup and the interface specific sections on an incoming connection.
This makes two main differences: First, for changes to the global con‐
figuration smtp.proxy has to be restarted to activate it. Second, con‐
figuration errors in the global configuration are detected on startup,
in interface specific sections only on an incoming connection. If
smtp.proxy is started from inetd the differences are not visible.
Command Line Arguments
Notice that if smtp.proxy is started with a configuration file the com‐
mand line parameter interpretation changes a little bit. Of course,
the proxy servers can be specified in the configuration file, the don’t
have to be given on the command line. If the server parameter is miss‐
ing smtp.proxy does not assume that it should use the local sendmail
for it’s upstream. It will stop with an error message instead.
OPTIONS
The following options are available:
-a acp set the access control program.
-c ccp set the command control program.
-d switch to debug mode: the dialog between server and client is
written to stderr.
-e enable proxying of the ETRN command.
-f filename
read configuration options from filename.
-l dir if set smtp.proxy looks if the file clientip exists in the
directory dir and if it’s not older than 600 seconds. If so the
client is accepted, otherwise not.
-m domain
rewrite all senders to be from the given e-mail domain.
-o dir set the session-status-file directory.
-p filename
set the name of the pidfile.
-q ipnum
set the local IP-number to use when connecting to the server.
-r rcptlist
specify a comma separated list of valid recipients. If this
option is set smtp.proxy checks each recipient from the RCPT
command against the patterns (use ‘*’ and ‘?’ as wildcards) from
that list and rejects it if it doesn’t match any pattern without
forwarding the request to the server.
If a pattern from rcptlist starts with an ‘@’-sign only the
domain part of the email address is matched against it, not the
whole email address.
-s senderlist
the same as the above rcptlist but for senders in the MAIL com‐
mand.
-t timeout
specify a different SMTP timeout in seconds than the default of
300 (5 minutes).
-u remove the mailpath from the received mail. Specifing -u twice
supresses also the proxy’s own ‘received from’ line.
-y | -yy cmd
scans all e-mails for spam using spamassassin, the default spam
client command is /usr/bin/spamc which can be changed by giving
-y twice.
-z | -zz dir
scans all mail for for viruses using clamav. Specifying -z
twice sets a quarantine folder which receives all virulent e-
mails. If no quarantine folder is given the e-mails are simply
dropped. Notice that smtp.proxy’s temporary directory must be
on the same disk partition as the quarantine directory, see -T
below.
-D | -DD [interface:]port
standalone mode: bind to the SMTP service port and handle incom‐
ing connections by forking proxy child. If -D is given twice
smtp.proxy expects the port number on which to bind. The port
parameter might be prefixed with an interface on which
smtp.proxy should bind.
The functions of the -l, -r and -s options can be easyly done with
access control programs. These options are however currently continued
for compatibility with earlier versions of the proxy.
-S sets supervised mode: enter daemon mode but don’t fork into
background.
-T dir defines the directory for temporary files.
-U username
user under which the daemon will run.
-V print version and exit.
There are some other command line options recognized by smtp.proxy but
these may be discontinued in a future release without further notice
and should be therefore not be used.
NOTES
If your running smtp.proxy with a local sendmail make sure the user
running the proxy is on the Tuser list in sendmail.cf. Otherwise
you’ll get authentication warnings in your syslog and the emails.
SEE ALSO
inetd(1), sendmail(1), tcpproxy(1).
03 April 2007 SMTP.PROXY(1)
