--- qmail-smtpd.8.orig 1998-06-15
+++ qmail-smtpd.8 2007-03-21
--- .././qmail-1.03/qmail-smtpd.8 Mon Jun 15 12:53:16 1998
+++ ../qmail-1.03.2418/qmail-smtpd.8 Sat Jan 6 21:38:04 2007
@@ -3,6 +3,10 @@
qmail-smtpd \- receive mail via SMTP
.SH SYNOPSIS
.B qmail-smtpd
+[
+.I checkprogram
+.I subprogram
+]
.SH DESCRIPTION
.B qmail-smtpd
receives mail messages via the Simple Mail Transfer Protocol (SMTP)
@@ -10,7 +14,7 @@
.B qmail-queue
to deposit them into the outgoing queue.
.B qmail-smtpd
-must be supplied several environment variables;
+must be supplied with several environment variables;
see
.BR tcp-environ(5) .
@@ -23,19 +27,90 @@
header fields.
.B qmail-smtpd
-supports ESMTP, including the 8BITMIME and PIPELINING options.
+supports ESMTP and offers 8BITMIME, DATA, PIPELINING, SIZE, AUTH, and STARTTLS options.
+.B qmail-smtpd
+includes a "MAIL FROM:" parameter parser and obeys "Auth" and "Size" advertisements.
+.B qmail-smtpd
+STARTTLS implementation requires the use of a patched version of
+.B sslserver
+and of course the OpenSSL library.
+
+Authentication mode is facilitated in case the environment variable SMTPAUTH is set
+which tells
+.B qmail-smtpd
+to accept LOGIN, PLAIN, and eventually CRAM-MD5 AUTH types
+and if additionally a PAM
+.I checkprogram
+is available which reads on file descriptor 3 the username, a 0 byte,
+the password or CRAM-MD5 digest/response derived from the SMTP client,
+another 0 byte, a CRAM-MD5 challenge (if applicable to the AUTH type),
+and a final 0 byte.
+.I checkprogram
+invokes
+.I subprogram
+upon successful authentication, which should return 0 to
+.BR qmail-smtpd ,
+effectively setting the environment variables RELAYCLIENT and TCPREMOTEINFO
+(any supplied value replaced with the authenticated username).
+.B qmail-smtpd
+will reject the authentication attempt if it receives a nonzero return
+value from
+.I checkprogram
+or
+.IR subprogram .
+
+STARTTLS support is enabled setting the environment variable UCSPITLS.
+In this case,
+.B qmail-smtpd
+communicates with the
+.B sslserver
+program interface through a control socket, a reading and a writing pipe, dynamically
+defined during the session start to be used for transport layer encryption.
+
+.B qmail-smtpd
+may employ additional DNS look-ups for the "MAIL FROM:" envelope sender
+address and/or the HELO/EHLO greeting string from the MTA client.
+
.SH TRANSPARENCY
.B qmail-smtpd
converts the SMTP newline convention into the UNIX newline convention
by converting CR LF into LF.
-It returns a temporary error and drops the connection on bare LFs;
+Usually, it returns a temporary error and drops the connection on bare LFs;
see
.BR http://pobox.com/~djb/docs/smtplf.html .
.B qmail-smtpd
accepts messages that contain long lines or non-ASCII characters,
even though such messages violate the SMTP protocol.
+
.SH "CONTROL FILES"
+.TP 5
+.IR badhelo
+Unacceptable HELO/EHLO greeting strings.
+.B qmail-smtpd
+will reject every connection attempt
+if the client MTA's HELO/EHLO greeting compares with
+a wildmat pattern provided in
+.IR badhelo
+in case the environment variable
+.B HELOCHECK
+is set.
+.IR badhelo
+checks have precedence over DNS lookups.
+DNS lookups can be avoided, if the announced
+HELO/ELO greeting string is concatinated
+with a trailing '!' and included in
+.IR badhelo :
+
+.EX
+ localhost
+ localhost.localdomain
+ 127.0.0.1
+ mygreetingstring
+ [192.168.1.2]!
+.EE
+
+
.TP 5
.I badmailfrom
Unacceptable envelope sender addresses.
@@ -49,6 +124,124 @@
.BR @\fIhost ,
meaning every address at
.IR host .
+Additionally, any envelope sender address can be filtered
+with a wildmat check:
+
+.EX
+ *@earthlink.net
+ !fred@earthlink.net
+ [0-9][0-9][0-9][0-9][0-9]@[0-9][0-9][0-9].com
+ answerme@save*
+ *%*
+ @yahoo.com-
+ @mydomain.tld+
+.EE
+
+A
+.I badmailfrom
+file with this contents reject all mail from Earthlink except from
+fred@earthlink.net. It also rejects all mail with addresses like:
+12345@123.com and answerme@savetrees.com. Further, any mail with
+a sender address containing a percent sign (%) is rejected.
+
+This
+.I badmailfrom
+implementation allows to reject addresses where
+particularly
+.I TCPREMOTEHOST
+equals 'unknown' (badmailfromunknown).
+In the case, the corresponding address in
+.I badmailfrom
+has to be appended with a '-'.
+Reversely, mails will be rejected in case
+.I RELAYCLIENT
+is not set if the sender address matches an entry
+appended with a '+' (anti-spoofing).
+
+Note: The 'appended' addresses are not subject of the wildmat check.
+
+The wildmat check is done in the order:
+Least significant to most significant.
+Example:
+
+.EX
+ *
+ !
+ !*@*.*
+ *viagra*
+.EE
+
+.TP
+.I badloadertypes.cdb
+Unacceptable base64 loader types in the message.
+.B qmail-smtpd
+will reject every message if 5 significant
+characters (eg.
+.BR Mi5kb)
+anyware in the base64 encoded attachment is identical
+to those compiled into
+.IR badloadertypes.cdb .
+Use
+.B qmail-badloadertypes
+to derive
+.I badloadertypes.cdb
+from
+.IR badloadertypes .
+In order to make the search efficient, all bad loader
+types have to start with the same character (eg. "M").
+The control file
+.I badloadertypes.cdb
+is evaluated if the environment variable BADLOADERTYPE
+is set to the first character according to the contents of
+.IR badloadertypes .
+.TP
+.I badmimetypes.cdb
+Unacceptable base64 encoded MIME types in message.
+.B qmail-smtpd
+will reject every message if the first 9 significant
+characters (eg.
+.BR TVqQAAMAA )
+of any of it's embedded MIME types is identical with one
+compiled into
+.IR badmimetypes.cdb .
+Use
+.B qmail-badmimetypes
+to derive
+.I badmimetypes.cdb
+from
+.IR badmimetypes .
+The control file
+.I badmimetypes.cdb
+is evaluated if the environment variable BADMIMETYPE
+is set but empty.
+.TP 5
+.I badrcptto
+Unacceptable envelope recipient addresses.
+.B qmail-smtpd
+will reject every incoming message
+if the envelope recipient address is listed in
+.IR badrcptto .
+This control file is complementary to
+.IR badmailfrom .
+A line in
+.I badrcptto
+may be of the form
+.BR @\fIhost ,
+meaning every address at
+.IR host .
+.I badrcptto
+employes the same filtering logic for the envelope recipient as
+.IR badmailfrom .
+Effectively,
+.IR badrcptto
+allows a "whitelisting" of envelope recipient addresses:
+
+.EX
+ *
+ !user1@mydomain.com
+ !user2@mydomain.com
+ !*@anotherdomain.com
+.EE
.TP 5
.I databytes
Maximum number of bytes allowed in a message,
@@ -72,8 +265,7 @@
.B qmail-queue
Received line, or the envelope.
-If the environment variable
-.B DATABYTES
+If the environment variable DATABYTES
is set, it overrides
.IR databytes .
.TP 5
@@ -120,6 +312,30 @@
and the rest into
.IR morercpthosts .
.TP 5
+.I mailfromrules
+Acceptable 'Mail From:' addresses for
+RELAYCLIENTs are included here. Use
+.B qmail-mfrules
+to derive
+.TP 5
+.I mailfromrules.cdb
+from
+.IR mailfromrules .
+.TP 5
+.IR moreipme (c)
+.B qmail-smtpd
+will treat all addresses in this file exactly as if they were local,
+though not identified initially by the OS; eg. in a NAT environment.
+Local IP addresses can be displayed by means of the program
+.BR ipmeprint .
+.TP 5
+.IR notipme (c)
+.B qmail-smtpd
+will ignore detected local IP addresses included in
+.IR notipme .
+This has precedence over
+.IR moreipme .
+.TP 5
.I rcpthosts
Allowed RCPT domains.
If
@@ -131,14 +347,11 @@
.IR rcpthosts .
Exception:
-If the environment variable
-.B RELAYCLIENT
-is set,
+If the environment variable RELAYCLIENT is set,
.B qmail-smtpd
will ignore
.IR rcpthosts ,
-and will append the value of
-.B RELAYCLIENT
+and will append the value of RELAYCLIENT
to each incoming recipient address.
.I rcpthosts
@@ -152,6 +365,63 @@
Envelope recipient addresses without @ signs are
always allowed through.
.TP 5
+.I recipients
+List of
+.B fastforward
+compatible cdbs with full-qualified SMTP
+addresses to be allowed for SMTP reception
+("RCPT TO: <recip@domain>").
+The path to a cdb has to be referenced relative to
+Qmail's home directory.
+.B qmail-recipients
+may be used to construct a
+.I users/recipients.cdb
+from
+.IR users/recipients .
+A typical
+.I recipients
+file looks like:
+
+.EX
+ users/recipients.cdb
+ etc/fastforward.cdb
+.EE
+
+.B qmail-smtpd
+will reject a message
+for
+.I recip@domain
+if the full-qualified recipient address
+is not included in any of
+.I recipients
+cdb's.
+In order to allow the unrestricted reception for a complete
+domain, the wildcard format
+.I !@domain
+can be used. For performance reasons it is adviceable,
+to place this information at the beginning of the first cdb.
+The
+.B qmail-smtpd
+recipients mechanism supports Qmail's address extension (VERP).
+Unqualified envelope recipients are appended with "@localhost".
+
+Note: The recipients check is applied after the
+.I rcpthosts
+evaluation and thus only if the environment variable
+RELAYCLIENT is not set.
+.TP 5
+.IR relaymailfrom (c)
+envelope senders ("MAIL FROM:") listed in this file will be allowed to relay
+independently of the RELAYCLIENT environment variable. Entries in
+.I relaymailfrom
+have to be a qualified envelope sender addresses.
+Examples:
+
+.EX
+ joeblow@domain1.com
+ foo@domain2.com
+.EE
+.TP 5
.I smtpgreeting
SMTP greeting message.
Default:
@@ -164,16 +434,230 @@
.I smtpgreeting
should be the current host's name.
.TP 5
+.IR tarpitcount
+tarpitcount is the number of RCPT TO:
+.B qmail-smtpd
+accepts before it starts tarpitting.
+Default: 0 which means no tarpitting.
+The environment variable TARPITCOUNT
+can be used instead.
+
+Note: After receiving TARPITCOUNT
+invalid RCPT TO:
+.B qmail-smtpd
+will issue a Recipient failure.
+.TP 5
+.IR tarpitdelay
+tarpitdelay is the time in seconds of delay
+to be introduced after each subsequent RCPT TO:.
+Default: 5.
+The environment variable TARPITDELAY can be used instead.
+.TP 5
.I timeoutsmtpd
Number of seconds
.B qmail-smtpd
will wait for each new buffer of data from the remote SMTP client.
Default: 1200.
+
+.SH "CONDITIONAL CONTROL FILES"
+The control files \fIrcpthosts\fR, \fImorecpthosts\fR,
+\fIrecipients\fR, \fIbadhelo\fR,
+\fItarpitcount\fR, and \fItarpitdelay\fR
+are "conditional" control files and evaluated
+only if the environment variable RELAYCLIENT is not set.
+On the other hand,
+\fImailfromrules.cdb\fR is only taken into account, if
+RELAYCLIENT is set.
+This allows
+.B qmail-smtpd
+to relay mail messages from local clients and to filter
+mails with certain SMTP envelope conditions
+originating from particular clients ("Split Horizon").
+Other conditional control files are
+\fIbadloadertypes\fR,
+\fIbadmimetypes\fR
+which depend on the setting of the corresponding
+environment variables.
+
+.SH "ENVIRONMENT VARIABLES READ"
+Environment variables may be defined globally in the
+.B qmail-smtpd
+startup script and/or individually as part of the
+.B tcpserver's
+cdb database.
+The environment variables may be quoted ("variable", or 'variable') and
+in case of global use, have to be exported.
+.B qmail-smtpd
+supports the following legacy environment variables, typically
+provided by
+.B tcpserver
+or
+.BR tcp-env :
+.IR TCPREMOTEIP ,
+.IR TCPREMOTEHOST
+and
+.IR TCPREMOTEINFO
+as well as
+.IR RELAYCLIENT .
+Additionally, with SPAMCONTROL
+.B qmail-smtpd
+may use the following environment variables:
+.TP 5
+.IR GREETDELAY
+if provided,
+.B qmail-smtpd
+will wait the provided number in seconds
+before issueing it's SMTP greeting to the client.
+.TP 5
+.I HELOCHECK=''
+enables a check of the provided HELO/EHLO greeting against
+the content of the control file
+.IR badhelo .
+In case no HELO/EHLO greeting is given, SMTP
+connections can be rejected, if
+.I HELOCHECK='!'
+is set. Checks on the presence and the content of
+the HELO/EHLO greeting string is facilitated, setting
+.IR HELOCHECK='.' .
+To enforce the match of the HELO/EHLO greeting with
+the remote host's FQDN (
+.IR TCPREMOTEHOST ),
+use
+.IR HELOCHECK='=' .
+.TP 5
+.IR HELOCHECK='A' | HELOCHECK='M'
+enable DNS A/MX lookup for the HELO/EHLO greeting string.
+In addition, the HELO/EHLO string is checked against
+the content of
+.IR badhelo .
+.TP 5
+.I BADLOADERTYPE='c'
+tells
+.B qmail-smtpd
+to evalute the control file
+.I badloadertypes.cdb
+with the starting string "c".
+.TP 5
+.I BADMIMETYPE
+see control file
+.IR badmimetypes.cdb .
+.TP 5
+.I DATABYTES
+see control file
+.IR databytes .
+.TP 5
+.I LOCALMFCHECK
+is used to enable a 'Mail From:' address Verification (MAV) for RELAYCLIENTs.
+Thus, the domain part of the 'Mail From:' envelope sender address
+has to match an entry in
+.IR rcpthosts
+or
+.IR morercpthosts
+control files, if not explicitly defined otherwise.
+
+If in particular LOCALMFCHECK='!', the control file
+.I mailfromrules.cdb
+is evaluated and the MAV is facilitated employing the environment variables
+.IR TCPREMOTEINFO ,
+.IR TCPREMOTIP ,
+or
+.I TCPREMOTEHOST
+as a key.
+
+Note: In this case the whole 'Mail From:' address may be verified;
+not only the domain part.
+.TP 5
+.I MAXRECIPIENTS
+is the number of RCPT TO:'s
+.B qmail-smtpd
+will accept in a SMTP session.
+If MAXRECIPIENTS ist not set, any number is allowed.
+.TP 5
+.IR MFDNSCHECK
+enable DNS MX lookup for the domain part of the "MAIL FROM:" envelope sender address.
+.TP 5
+.I QHPSI
+is used by
+.B qmail-smtpd
+to supply the name of the virus scanner
+in it's logs.
+.TP 5
+.I BASE64
+tells QHPSI to enable virus checking only if a base64 encoded
+attachment was identified.
+.TP 5
+.I RECIPIENTS450
+tells
+.b qmail-smtpd
+to issue a SMTP reply '450' (temporary rejection)
+instead the default '550'
+in case the recipient was not listed in any
+.I recipients
+cdb.
+.TP 5
+.I REPLYMAV
+allows the setting of customized SMTP reply messages in case
+of a MAV mismatch.
+.TP 5
+.IR REQUIREAUTH
+The REQUIREAUTH environment variable advices
+.B qmail-smtpd
+to accept only SMTP authenticated sessions
+in a none-RELAYLCIENT case.
+.TP 5
+.IR REQUIRETLS
+enforces
+.B qmail-smtpd
+to accept only TLS encrypted SMTP sessions.
+.TP 5
+.IR SMTPAUTH
+is used to enable SMTP Authentication for the Auth types
+LOGIN and PLAIN.
+If however
+.IR SMTPAUTH='cram'
+is defined
+.B qmail-smtpd
+honors LOGIN, PLAIN, and CRAM-MD5 authentication.
+
+Note: This requires a CRAM-MD5 enabled PAM.
+.TP 5
+.IR UCSPITLS
+enables in addition encryption of the SMTP communication
+via STARTTLS in case
+.B sslserver
+is provided.
+.TP 5
+.IR TARPITCOUNT
+see control file
+.IR tarpitcount .
+.TP 5
+.IR TARPITDELAY
+see control file
+.IR tarpitdelay .
+
+.SH "ENVIRONMENT VARIABLES SET"
+.TP 5
+.IR TCPREMOTEINFO
+in authentication mode set to the provided username.
+
.SH "SEE ALSO"
tcp-env(1),
tcp-environ(5),
qmail-control(5),
qmail-inject(8),
qmail-newmrh(8),
+qmail-newbmt(8),
+qmail-recipients(8),
+qmail-mfrules(8),
qmail-queue(8),
-qmail-remote(8)
+qmail-remote(8),
+qmail-send(8)
+
+.SH "HISTORY"
+The patch enabling the ESMTP AUTH and STARTTLS option is not part of the standard
+.B qmail-1.03
+distribution. This man-page describes the options of
+.B qmail-1.03
+in addition with the
+.B SPAMCONTROL 2.4
+patch.
syntax highlighted by Code2HTML, v. 0.9.1