.TH qmail-smtpd 8
.SH NAME
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)
and invokes
.B qmail-queue
to deposit them into the outgoing queue.
.B qmail-smtpd
must be supplied with several environment variables;
see
.BR tcp-environ(5) .

.B qmail-smtpd
is responsible for counting hops.
It rejects any message with 100 or more 
.B Received
or
.B Delivered-To
header fields.

.B qmail-smtpd
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.
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.
.B qmail-smtpd
will reject every recipient address for a message
if the envelope sender address is listed in
.IR badmailfrom .
A line in
.I badmailfrom
may be of the form
.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,
or 0 for no limit.
Default: 0.
If a message exceeds this limit,
.B qmail-smtpd
returns a permanent error code to the client;
in contrast, if
the disk is full or
.B qmail-smtpd
hits a resource limit,
.B qmail-smtpd
returns a temporary error code.

.I databytes
counts bytes as stored on disk, not as transmitted through the network.
It does not count the
.B qmail-smtpd
Received line, the
.B qmail-queue
Received line, or the envelope.

If the environment variable DATABYTES
is set, it overrides
.IR databytes .
.TP 5
.I localiphost
Replacement host name for local IP addresses.
Default:
.IR me ,
if that is supplied.
.B qmail-smtpd
is responsible for recognizing dotted-decimal addresses for the
current host.
When it sees a recipient address of the form
.IR box@[d.d.d.d] ,
where
.I d.d.d.d
is a local IP address,
it replaces
.IR [d.d.d.d]
with
.IR localiphost .
This is done before
.IR rcpthosts .
.TP 5
.I morercpthosts
Extra allowed RCPT domains.
If
.I rcpthosts
and
.I morercpthosts
both exist,
.I morercpthosts
is effectively appended to
.IR rcpthosts .

You must run
.B qmail-newmrh
whenever
.I morercpthosts
changes.

Rule of thumb for large sites:
Put your 50 most commonly used domains into
.IR rcpthosts ,
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
.I rcpthosts
is supplied,
.B qmail-smtpd
will reject
any envelope recipient address with a domain not listed in
.IR rcpthosts .

Exception:
If the environment variable RELAYCLIENT is set,
.B qmail-smtpd
will ignore
.IR rcpthosts ,
and will append the value of RELAYCLIENT
to each incoming recipient address.

.I rcpthosts
may include wildcards:

.EX
   heaven.af.mil
   .heaven.af.mil
.EE

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:
.IR me ,
if that is supplied;
otherwise
.B qmail-smtpd
will refuse to run.
The first word of
.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-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.