qmail-smtpd [ checkprogram subprogram ]
qmail-smtpd receives mail messages via the Simple Mail Transfer Proto-
col (SMTP) and invokes qmail-queue to deposit them into the outgoing
queue. qmail-smtpd must be supplied with several environment vari-
ables; see tcp-environ(5).
qmail-smtpd is responsible for counting hops. It rejects any message
with 100 or more Received or Delivered-To header fields.
qmail-smtpd supports ESMTP and offers 8BITMIME, DATA, PIPELINING, SIZE,
AUTH, STARTTLS, and SMTPTUF8 options. qmail-smtpd includes a "Mail From:"
parameter parser and obeys "Auth", "Size", and "SMTPUTF8" advertisements.
qmail-smtpd STARTTLS implementation requires the use of sslserver from
Authentication mode is facilitated in case the environment variable
SMTPAUTH is set which tells qmail-smtpd to accept LOGIN, PLAIN, and
eventually CRAM-MD5 AUTH types and if additionally a PAM 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. checkprogram invokes subprogram upon successful
authentication, which should return 0 to qmail-smtpd, effectively set-
ting the environment variables RELAYCLIENT and TCPREMOTEINFO or
TCP6REMOTEINFO (any supplied value replaced with the authenticated
username). qmail-smtpd will reject the authentication attempt if it
receives a nonzero return value from checkprogram or subprogram.
STARTTLS support is enabled setting the environment variable UCSPITLS.
In this case, qmail-smtpd communicates with the 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. qmail-smtpd provides mutual authentication based on
X.509 client certs and relaying with additional SMTP Return-Path vali-
qmail-smtpd may employ additional DNS look-ups for the "Mail From:"
envelope sender address and/or the HELO/EHLO greeting string from the
qmail-smtpd implements a SPF record check for the domain part of the
received Mail-From: <return-path> address or the HELO/EHLO statement in
case the domain information is missing. This behavior is triggered by
the environment variable SPF.
qmail-smtpd converts the SMTP newline convention into the UNIX newline
convention by converting CR LF into LF. Usually, it returns a tempo-
rary error and drops the connection on bare LFs.
qmail-smtpd accepts messages that contain long lines or non-ASCII char-
acters, even though such messages violate the SMTP protocol.
Unacceptable HELO/EHLO greeting strings. qmail-smtpd will reject
every connection attempt if the client MTA's HELO/EHLO greeting
compares with a wildmat pattern provided in badhelo in case the
environment variable HELOCHECK is set. badhelo checks have prece-
dence over DNS lookups. DNS lookups can be avoided, if the
announced HELO/EHLO greeting string is concatinated with a trail-
ing '!' and included in badhelo:
Unacceptable envelope sender addresses. qmail-smtpd will reject
every recipient address for a message if the envelope sender
address is listed in badmailfrom. A line in badmailfrom may be of
the form @host, meaning every address at host. Additionally, any
envelope sender address can be filtered with a wildmat check:
A badmailfrom file with this contents reject all mail from Earth-
link except from firstname.lastname@example.org. It also rejects all mail with
addresses like: email@example.com and firstname.lastname@example.org. Further,
any mail with a sender address containing a percent sign (%) is
This implementation recognises 'extended' addresss in badmailfrom
allowing to reject mails with particluar spoofed domain addresses:
(1) The address is appended with a '-'. Now, if TCP(6)REMOTEHOST
equals 'unknown', mails with the corresponding address are
(2) The address is appended with a '='. In case TCP(6)REMEOTEHOST
is set mails, whose domain part of the envelope addresses not
matching the corresponding entry are rejected (badmailfromwell-
(3) The address is appended with a '+'. If RELAYCLIENT is not set
and the sender address matches a corresponding entry (anti-spoof-
ing for internal addresses).
(4) The address is enhanced with a leading '~'. This requires a
Unacceptable base64 loader types in the message. qmail-smtpd will
reject every message if 5 significant characters (eg. Mi5kb) any-
ware in the base64 encoded attachment is identical to those com-
piled into badloadertypes.cdb. Use qmail-badloadertypes to derive
badloadertypes.cdb from badloadertypes. In order to make the
search efficient, all bad loader types have to start with the same
character (eg. "M"). The control file badloadertypes.cdb is eval-
uated if the environment variable BADLOADERTYPE is set to the
first character according to the contents of badloadertypes.
Unacceptable base64 encoded MIME types in message. qmail-smtpd
will reject every message if the first 9 significant characters
(eg. TVqQAAMAA) of any of it's embedded MIME types is identical
with one compiled into badmimetypes.cdb. Use qmail-badmimetypes
to derive badmimetypes.cdb from badmimetypes. The control file
badmimetypes.cdb is evaluated if the environment variable BADMIME-
TYPE is set. In addition, irregular BASE64 attachments carrying
whitespaces can be rejected defining BADMIMETYPE='!'.
Unacceptable envelope recipient addresses. qmail-smtpd will
reject every incoming message if the envelope recipient address is
listed in badrcptto. This control file is complementary to bad-
mailfrom. A line in badrcptto may be of the form @host, meaning
every address at host. badrcptto employes the same filtering
logic for the envelope recipient as badmailfrom. Effectively,
badrcptto allows a "whitelisting" of envelope recipient addresses:
Maximum number of bytes allowed in a message, or 0 for no limit.
Default: 0. If a message exceeds this limit, qmail-smtpd returns
a permanent error code to the client; in contrast, if the disk is
full or qmail-smtpd hits a resource limit, qmail-smtpd returns a
temporary error code.
databytes counts bytes as stored on disk, not as transmitted
through the network. It does not count the qmail-smtpd Received
line, the qmail-queue Received line, or the envelope.
Extra allowed RCPT domains. If rcpthosts and morercpthosts both
exist, morercpthosts is effectively appended to rcpthosts.
You must run qmail-newmrh whenever morercpthosts changes.
Rule of thumb for large sites: Put your 50 most commonly used
domains into rcpthosts, and the rest into morercpthosts.
Acceptable "Mail From:" addresses for RELAYCLIENTs are included
here. Use qmail-mfrules to derive
Allowed RCPT domains. If rcpthosts is supplied, qmail-smtpd will
reject any envelope recipient address with a domain not listed in
Exception: If the environment variable RELAYCLIENT is set, qmail-
smtpd will ignore rcpthosts, and will append the value of RELAY-
CLIENT to each incoming recipient address.
rcpthosts may include wildcards:
Envelope recipient addresses without @ signs are always allowed
List of external resources providing acceptable, full-qualified
envelope addresses ('RCPT to: <recip@domain>') to be used for
recipient verification during the SMTP session.
The external sources can be either fastforward compliant cdbs
including the envelope addresses, where the path to a cdb has to
be referenced relative to Qmail's home directory - or - checkpass-
word compatible Plugable Authentication Modules (PAM), receiving
the envelope address on FD 3 as 'recip@domain\0\0\0' and returning
'0' in a case of success and '1' in case of failure. The use of a
PAM is indicated with a delimiting '|' and it will be called with
up to five additional parameters; while a cdb follows a ':', which
can be omitted.
The list of external sources is consulted line-by-line for each
recipient envelope address until the first positive answer, or a
final negative response is encountered. Which external source to
be queried, depends on the domain part of the recipient envelope
address specified on the left side of the recipients file, while
the external resource is provided right from the delimitor.
The addresses' domain part is evaluated in lower-case. An exact
domain match can be encompassed by means of a leading '@'. The
'*' is a generic wildcard for all domains. Specific domains can
be excluded from the lookup by means of a leading '!'; thus all
recipient addresses are accepted for this domain. Additionally, a
'!*' can be used as wildcard for all domains not encountered
before in recipients (pass-thru).
A recipients file is always constructed like
domain:cdb','domain|pam', or simply 'cdb':
*|PATH/ldapam ldapserver host port DN passwd
Note: Excluded domains starting with a '!' should be placed in
the beginning of the recipients file for performance reasons,
while the pass-thru statement '!*' has to be on the last line.
The recipients check is applied after the rcpthosts evaluation.
qmail-recipients may be used to construct a users/recipients.cdb
The qmail-smtpd recipients mechanism supports Qmail's address
extension (VERP). Unqualified envelope recipients are appended
SMTP greeting message. Default: me, if that is supplied; other-
wise qmail-smtpd will refuse to run. The first word of smtpgreet-
ing should be the current host's name.
An additional SPF explanation can be given here to provide more
specific information for the sender in case of a reject. SPF
macro expansion is possible. It will override the default one,
See https://example.com/spfrules.html (#5.7.1)
As 'last resort', it is possible to include SPF local rules here
(on one line), that will be applied before other SPF rules would
fail. This can be used to allow certain MX to send mails anyway.
Number of seconds qmail-smtpd will wait for each new buffer of
data from the remote SMTP client. Default: 1200.
CONDITIONAL CONTROL FILES
The control files rcpthosts, morecpthosts, recipients, badhelo are
"conditional" control files and evaluated only if the environment vari-
Environment variables may be defined globally in the qmail-smtpd
startup script and/or individually as part of the tcpserver's cdb data-
base. The environment variables may be quoted ("variable", or 'vari-
able') and in case of global use, have to be exported. qmail-smtpd
supports the following legacy environment variables, typically provided
by tcpserver or sslserver: TCP(6)REMOTEIP, TCP(6)REMOTEHOST
TCP(6)REMOTEINFO and TCPLOCALPORT as well as RELAYCLIENT. Addition-
ally, qmail-smtpd may use several environment variables for different
Controlling the SMTP HELO/EHLO:
enables a check of the provided HELO/EHLO greeting against the
content of the control file badhelo. In case no HELO/EHLO greet-
ing is given, SMTP connections can be rejected, if HELOCHECK='!'
is set. Checks on the presence and the content of the HELO/EHLO
greeting string is facilitated, setting HELOCHECK='.'. To enforce
the match of the HELO/EHLO greeting with the remote host's FQDN (
TCP(6)REMOTEHOST), use HELOCHECK='='.
enable DNS A/MX lookup for the HELO/EHLO greeting string. In
addition, the HELO/EHLO string is checked against the content of
Controlling the SMTP Mail From:
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 rcpthosts or morercpthosts
control files, if not explicitly defined otherwise.
If LOCALMFCHECK='!' is set, the control file mailfromrules.cdb is
evaluated and the MAV is facilitated employing the environment
variables TCP(6)REMOTEINFO, TCP(6)REMOTIP, or TCP(6)REMOTEHOST as
a key. However, if LOCALMFCHECK='=' is provided, TCP(6)REMOTEINFO
(i.e. set by Auth) has to match the "Mail From:" envelope address
(case insensitive). Alternativley, using LOCALMFCHECK='?' the
email address embedded in the DN of a X.509 client is used and
compared against the "Mail From:" envelope address. Of course,
this requires sslserver to request a client cert for mutual
Note: Adding a qualifier to LOCALMFCHCEK, the entire "Mail From:"
address is verified; not only the domain part.
enable DNS MX lookup for the domain part of the "Mail From:" enve-
lope sender address.
SPF Records will be evaluated for the current SMTP session in case
SPF is defined. The value of SPF may be given between 1 and 6 to
enable SPF checks. 1 selects 'annotate-only' mode, where qmail-
smtpd will annotate incoming email with a Received-SPF header, but
will not reject any messages. 2 will produce temporary failures
on DNS lookup problems so you can be sure always to have meaning-
ful Received-SPF headers. 3 selects 'reject' mode, where incoming
mail will be rejected if the SPF record says 'fail'. 4 selects a
more stricter rejection mode, which is like 'reject' mode, except
that incoming mail will also be rejected, when the SPF record says
'softfail'. Further, 5 will reject when the SPF record says 'neu-
tral', and 6 rejects, if no SPF records are available at all (or a
syntax error was encountered). If SPF is given as 0, SPF checks
Note: Additional control files are spfexplain and spflocalrules.
Controlling the SMTP RCPT TO:
is the number of Rcpt To:'s qmail-smtpd will accept in a SMTP ses-
sion. If MAXRECIPIENTS ist not set, any number is allowed.
is the number of Rcpt To: qmail-smtpd accepts before it starts
tarpitting. Default: 0 which means no tarpitting.
tarpitdelay is the time in seconds of delay to be introduced after
each subsequent Rcpt To:.
Smart Rejection Notes: If TARPITCOUNT is set and TARPITDELAY = 0
(default) qmail-smtpd will issue after recognising TARPITCOUNT
invalid Rcpt To: a Recipient failure; thus additional Rcpt Tos
will not be accepted. If, however TARPITCOUNT is set and TARPIT-
DELAY = 999 qmail-smtpd will issue after TARPITCOUNT invalid Rcpt
To: a Recipient failure
tells to issue a SMTP reply '450' (temporary rejection) instead
the default '550' in case the recipient was not listed in any
allows the setting of customized SMTP reply messages in case of a
Controlling the email body:
tells qmail-smtpd to evaluate the control file badloadertypes.cdb
with the starting string 'c'. If BADLOADERTYPE='-' is set, the
check is disabled. In case BADLOADERTYPE='+' is defined, the
check is disabled for RELAYCLIENTS.
see control file badmimetypes.cdb. In case BADMIMETYPE='-' is
set; badmimetypes.cdb is not considered; thus the check is dis-
abled. Providing BADMIMTETYPE='+' the check is disabled if in
addition RELAYCLIENTS are recognized.
tells QHPSI to enable virus checking only if a base64 encoded
attachment was identified.
see control file databytes.
is used by qmail-smtpd to supply the name of the virus scanner and
Environment variables for SMTP authentication:
is used to enable SMTP Authentication for the qmail-smtpd Auth types
LOGIN and PLAIN. In case
is defined, qmail-smtpd honors LOGIN, PLAIN, and additionally
CRAM-MD5 authentication. Simply
restricts authentication just to CRAM-MD5. If however
starts with an exclamation mark Auth is required. You
can enforce 'Submission' using this option and binding qmail-smtpd
to the SUBMISSION port '587'. In particular,
may be useful. In opposite, if
starts with a dash, Auth is disabled for particular con-
nections. Note: The use of 'cram' requires a CRAM-MD5 enabled
Setting up the TLS/STARTTLS environment:
enables encrypted SMTP communication via STARTTLS in case
sslserver is provided. If UCSPITLS='!' is set, STARTTLS is
required; while setting UCSPITLS='-' disables STARTTLS. Further,
UCSPITLS='?' may be used to force the client to present a X.509
cert for authentication purpose which may be refined requesting
UCSPITLS='@' to additionally fetch the email address from the
client's cert to be perhaps subject of LOCALMFCHECK.
Other environment variables used:
mail address for special recipients.
feed from rblsmtpd including the information received from the
inquired RBL hosts and displayed as X-RBL-Info: message header.
ENVIRONMENT VARIABLES SET
By means of the following environment variables, the SMTP session can be
the HELO/EHLO greeting of the SMTP client.
the ESMTPA protocol used for authentication.
the supplied username for authentication.
containes the received "Mail From:" address.
containes all received "Rcpt To:" addresses separated by blanks.
in authentication mode set to the accepted username.
information from sslserver, if applicable.
tcp-environ(5), qmail-control(5), qmail-inject(8), qmail-newmrh(8),
qmail-newbmt(8), qmail-authuser(8), qmail-recipients(8), qmail-smt-
pam(8), qmail-mfrules(8), qmail-queue(8), qmail-remote(8), qmail-
send(8), qmail-log(8), tcpserver(8), sslserver(8).
Man(1) output converted with