--- 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.