.de ES
.sp
.in +0.5i
..
.de EE
.in -0.5i
.sp
..
.de EX
.sp
.in +0.5i
\\$1
.in -0.5i
.sp
..
.TH SMTP.PROXY 1 "28 August 1999"
.SH NAME
smtp.proxy \- SMTP proxy server
.SH SYNOPSIS
\fBsmtp.proxy\fR [\fIoptions\fR] [\fIserver\fR]
.SH DESCRIPTION
.I smtp.proxy
is a proxy server for the SMTP protocol.
It forwards traffic between a client and a server watching that the client
fullfills the protocol specification.
.PP
.I smtp.proxy
is usually started from a TCP superserver like
.IR inetd (1)
or
.IR tcpproxy (1).
It can be used from the command line to but does not support binding to a
service port like
.IR sendmail (1).
.PP
\fIserver\fR can be either an SMTP server on a different machine which is then
contacted via TCP/IP or a local \fIsendmail\fR binary.
If \fIserver\fR is omitted the latter is assumed with \fIsendmail\fR
in \fI/usr/sbin\fR.
.SS Protocol Support
.I smtp.proxy
supports the following SMTP commands:
.PP
.RS
HELO, EHLO
.br
[MAIL|SEND|SOML|SAML] FROM, RCPT TO, DATA,
.br
NOOP, RSET, HELP, ETRN, QUIT
.br
.PP
.RE
Unsupported SMTP commands result in a syslog message without forwarding the
command to the server.
ETRN is only supported if the \fB-e\fR option is given on the command line.
.PP
Email addresses are checked againt some simple tests:
.PP
.RS
- they must be enclosed in angle brackets `<', `>',
.br
- they must contain exactly one `@',
.br
- they must not contain a `%' or a `!',
.br
- `:' and `,' characters are also not allowed.
.br
.PP
.RE
While these checks block some valid email addresses they are almost
what you want these days in an Internet with DNS.
.br
The special envelop address `<>' is always allowed.
.SH CONTROL PROGRAMS
\fIsmtp.proxy\fR supports two kinds of external control programs, access
and command control programs.
Note: the term "command control program" is not correct for \fIsmtp.proxy\fR
but it was chosen to use a term compatible to the other proxies.
.sp
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.
.SS 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 variables that are set for the acp.
.SS Command Control
If a ccp is given the e-mail from the client is first read into a temporary
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.
.br
Notice that \fIsmtp.proxy\fR does not prevent timeouts occuring on the
SMTP server while receiving the e-mail.
.SS Environment Variables
Both types of control programs are called with the following variables
set.
.TP
\fBSMTP_SERVER\fR
the name of the server that is the proxy connected to.
.TP
\fBSMTP_CLIENT\fR, \fBSMTP_CLIENTNAME\fR
IP number and name of the client.
.TP
\fBSMTP_SENDER\fR
the sender's e-mail address enclosed in angle brackets.
.TP
\fBSMTP_NRCPT\fR
the number of recipients.
.TP
\fBSMTP_RCPT\fR
the space separated list of all recipients.
The addresses are \fBnot\fR enclosed in angle brackets.
.TP
\fBSMTP_RCPTV\fR
same as above but this time as \fIrc\fR(1)/\fIakanga\fR(1) compatible
list.
.PP
Additionally the ccp receives the following settings:
.TP
\fBSMTP_MAIL\fR
a temporary file which contains the e-mail from the client.
.TP
\fBSMTP_SIZE\fR
the e-mail's size.
.PP
.SS Response Codes
\fIsmtp.proxy\fR 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 syslog.
This is meant to be a diagnostic message for the proxy administrator.
.P
The output on the program's stderr should contain a valid SMTP response
(including the diagnostic message for the client)
and is used in conjunction with the program's exit code to decide how to
continue with the e-mail.
.br
The control program's response is interpreted as follows:
.TP
\fB250\fR, \fB354\fR
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".
.TP
status codes \fB4xx\fR and \fB5xx\fR
they are passed on an as-is basis to the client and e-mail processing
is terminated at this point.
.PP
Any other response code is replaced by a 421.
.P
If \fIsmtp.proxy\fR receives nothing on the control program's stderr
e-mail processing is determined only on the program's exit code:
.TP
\fB0\fR
positive response, e-mail is further processed.
.TP
\fB1\fR
send a 451 transient error resonse and terminate e-mail
processing.
.TP
any other
send a 554 permanent error response and terminate e-mail processing.
.PP
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.
.P
Notice that if the SMTP status code is 421 (for any reason) \fIsmtp.proxy\fR
terminates the connection to the client.
.SH OPTIONS
The following options are available:
.TP
\fB-a\fR \fIacp\fR
set the access control program.
.TP
\fB-c\fR \fIccp\fR
set the command control program.
.TP
.B -d
switch to debug mode: the dialog between server and client is written to
stderr.
.TP
.B -e
enable proxying of the ETRN command.
.TP
\fB-l\fR \fIdir\fR
if set \fIsmtp.proxy\fR looks if the file \fIclientip\fR exists in
the directory \fIdir\fR and if it's not older than 600 seconds.
If so the client is accepted otherwise not.
.TP
.B -q
remove the mailpath from the received mail.
Specifing \fb-q\fR twice supresses also the proxy's own `received from' line.
.TP
\fB-r\fR \fIrcptlist\fR
specify a comma separated list of valid recipients.
If this option is set \fIsmtp.proxy\fR 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.
.br
If a pattern from \fIrcptlist\fR starts with an `@'-sign only the domain part
of the email address is matched against it, not the whole email address.
.TP
\fB-s\fR \fIsenderlist\fR
the same as the above \fIrcptlist\fR but for senders in the MAIL command.
.TP
\fB-t\fR \fItimeout\fR
specify a different SMTP timeout in seconds than the default of 300 (5 minutes).
.PP
The functions of the \fB-l\fR, \fB-r\fR and \fB-s\fR options can be easyly
done with access control programs.
These options are however currently continued for compatibility with
earlier versions of the proxy.
.SH NOTES
If your running \fIsmtp.proxy\fR with a local \fIsendmail\fR make sure the
user running the proxy is on the \fBT\fIuser\fR list in \fIsendmail.cf\fR.
Otherwise you'll get authentication warnings in your syslog and the emails.
.SH "SEE ALSO"
.IR inetd (1),
.IR sendmail (1),
.IR tcpproxy (1).