qmail-smtpd - receive mail via SMTP
qmail-smtpd [ checkprogram subprogram ]
qmail-smtpd receives mail messages via the Simple Mail Transfer Protocol (SMTP) and invokes qmail-queue to deposit them into the outgoing queue. qmail-smtpd must be supplied with several environment variables; 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 SMTPUTF8 options. qmail-smtpd includes a ’Mail From:’ parameter parser and obeys ’Auth’, ’Size’, and ’SMTPUTF8’ advertisements. qmail-smtpd supports SMTPUTF8 SMTP envelope addresses and provides 8 bit clean message transmission. qmail-smtpd STARTTLS and SMTPS implementation requires the use of sslserver from ucspi-ssl.
Authentication 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 setting 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 validation.
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.
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 can be advised to communicate with a Greylisting server prior of acceptance, like postgrey, submitting the connection information Mail From:, Rcpt To:, TCPREMOTEIP and TCPREMOTEHOST given its IPv4/IPv6 address as environment variable POSTGREY and potentially including the port number (60000 is default) following the IP address separated by a semi-colon. For IPv6 LLU addresses the interface name followwing a percent sign can be included: fe80::1%eth0;60000. A return value of 10 will advise qmail-smtpd to defer the SMTP connection providing a 450 greylisted (#4.3.0) response to the connecting MTA, which can be tailored (see below). This mechanism shall not be used for SMTP connections on the Submission port. Setting POSTGREY=’-’ disables the lookup.
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 LF, if not adviced otherwise.
qmail-smtpd accepts messages that contain long lines or non-ASCII characters and thus is initially capable for SMTPUTF8 support.
badhelo
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 precedence over DNS lookups. DNS lookups can be avoided, if the announced HELO/EHLO greeting string is concatinated with a trailing ’!’ and included in badhelo:
localhost
localhost.localdomain
127.0.0.1
mygreetingstring
[192.168.1.2]!
badmailfrom
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:
*@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-
@hotmail.com=
@mydomain.tld+
~yahoo.com
?nobody@example.com
A 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 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 rejected (badmailfromunknown).
(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 (badmailfromwellknown).
(3) The address is appended with a ’+’. If RELAYCLIENT is not set and the sender address matches a corresponding entry (anti-spoofing for internal addresses).
(4) The address is enhanced with a leading ’~’. This requires a (left to right partial) matching of TCP(6)REMOTEHOST with the domain part of the envelope address. Thus, this specific entry in badmailfrom uses TCP(6)REMOTEHOST in the first place (badmailfrommismachteddomains).
(5) The address is enhanced with a leading ’?’. Emails with the corresponding sender address pass by all further badmailfrom tests including the MFDNSCHECK check.
Note: The ’enhanced’ addresses are not subject of the wildmat check and are evaluated in lower-case.
The wildmat check is done in the order: Least significant to most significant. Example:
*
!
!*@*.*
*viagra*
badloadertypes.cdb
Unacceptable base64 loader types in the message. qmail-smtpd will reject every message if 5 significant characters (eg. Mi5kb) anyware in the base64 encoded attachment is identical to those compiled 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 evaluated if the environment variable BADLOADERTYPE is set to the first character according to the contents of badloadertypes.
badmimetypes.cdb
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 BADMIMETYPE is set. In addition, irregular BASE64 attachments carrying whitespaces can be rejected defining BADMIMETYPE=’!’.
badrcptto
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 badmailfrom. 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:
*
!user1@mydomain.com
!user2@mydomain.com
!*@anotherdomain.com
badrcptto allows to tag recipient addresses to be reachable from authorized clients only (aka relayclients), prepending it in badrcptto with +.
+localaddress@mydomain.com
databytes
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.
If the environment variable DATABYTES is set, it overrides databytes.
localiphost
Replacement host name for local IP addresses. Default: me, if that is supplied. qmail-smtpd is responsible for recognizing native IPv4/IPv6 addresses for the current host. When it sees a recipient address of the form box@[d.d.d.d] or box@[a:b:c:d:e:f:g:h], where d.d.d.d or a:b:c:d:e:f:g:h is a local IPv4/IPv6 address, it replaces [d.d.d.d] or [a:b:c:d:e:f:g:h] with localiphost. This is done before rcpthosts.
morercpthosts
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.
mailfromrules
Acceptable ’Mail From:’ addresses for RELAYCLIENTs are included here. Use qmail-mfrules to derive
mailfromrules.cdb
from mailfromrules.
rcpthosts
Allowed RCPT domains. If rcpthosts is supplied, qmail-smtpd will reject any envelope recipient address with a domain not listed in rcpthosts.
Exception: If the environment variable RELAYCLIENT is set, qmail-smtpd will ignore rcpthosts, and will append the value of RELAYCLIENT to each incoming recipient address.
rcpthosts may include wildcards:
heaven.af.mil
.heaven.af.mil
Envelope recipient addresses without @ signs are always allowed through.
recipients
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 a qmail-users build cdb available as users/assign.cdb, or a checkpassword 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’:
!nocheck.com
mydomain.com:users/recipients.cdb
@mx.mydomain.com:=
example.com|bin/qmail-smtpam mx.example.com
*:etc/fastforward.cdb
*|PATH/ldapam ldapserver host port DN passwd
!*
qmail-smtpd will semi-automatically consult users/assign.cdb generated by qmail-newu in case the domain name is followed by a colon and the equal sign ’=’. Now, the received ´Rcpt to:´ address is compared against each local part address (starting with a ’=’) in users/assign.cdb. However, no VERP addresses are considered, which are indicated therein via a ’+’.
Lagacy format:
users/recipients.cdb
etc/fastforward.cdb
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 from users/recipients.
The qmail-smtpd recipients mechanism supports Qmail’s address extension (VERP). Unqualified envelope recipients are appended with ´@localhost´.
smtpgreeting
SMTP greeting message. Default: me, if that is supplied; otherwise qmail-smtpd will refuse to run. The first word of smtpgreeting should be the current host’s name.
spfexplain
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, e.g.:
See https://example.com/spfrules.html (#5.7.1)
spflocalrules
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.
Example:
include:spf.trusted-forwarder.org
timeoutsmtpd
Number of seconds
qmail-smtpd
will wait for each new buffer of data from the remote SMTP
client.
Default: 1200.
The control files rcpthosts, morecpthosts, recipients, badhelo are ’conditional’ control files and evaluated only if the environment variable RELAYCLIENT is not set. On the other hand, mailfromrules.cdb is only taken into account, if RELAYCLIENT is set. This allows 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 badloadertypes, badmimetypes which depend on the setting of the corresponding environment variables.
Further, the control files spfexplain and spflocalrules are only evaluated if the environment variable SPF is defined and greater than 0 and RELAYCLIENT is not set.
Environment variables may be defined globally in the qmail-smtpd startup script and/or individually as part of the sslserver’s cdb database. The environment variables may be quoted ("variable", or ’variable’) and in case of global use, have to be exported. qmail-smtpd supports the following legacy environment variables, typically provided by sslserver or tcpserver: TCP(6)REMOTEIP, TCP(6)REMOTEHOST TCP(6)REMOTEINFO and TCPLOCALPORT as well as RELAYCLIENT. Additionally, qmail-smtpd may use several environment variables for different purposes.
Controlling the
SMTP HELO/EHLO:
HELOCHECK=’’
enables a check of the provided HELO/EHLO greeting against the content of the control file badhelo. In case no HELO/EHLO greeting 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=’=’.
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 badhelo.
|
UTF8 |
display the SMTPUTF8 greeting string. This is off by default. |
Since qmail-smtpd is 8 bit clean, setting of UTF8 has no real consequences except for displaying this setting in the log as ESMTP[SA]UTF8.
Controlling the
SMTP Mail From:
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 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 authentication.
Note: Adding a qualifier to LOCALMFCHCEK, the domain part of the ’Mail From:’ address is compared against the provided string.
MFDNSCHECK
enable DNS MX lookup for the domain part of the ’Mail From:’ envelope sender address.
SPF=’0’|’1’|’2’|’3’|’4’|’5’|’6’
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 a meaningful Received-SPF header. 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 ’neutral’, 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 are disabled.
Note: Additional control files are spfexplain and spflocalrules.
Controlling the
SMTP RCPT TO:
MAXRECIPIENTS
is the number of Rcpt To:’s qmail-smtpd will accept in a SMTP session. If MAXRECIPIENTS ist not set, any number is allowed.
TARPITCOUNT
is the number of Rcpt To: qmail-smtpd accepts before it starts tarpitting. Default: 0 which means no tarpitting.
TARPITDELAY
tarpitdelay is the time in seconds of delay to be introduced after each subsequent Rcpt To:.
Smart Rejection Notes:
RECIPIENTS450
tells to issue a SMTP reply ’450’ (temporary rejection) instead the default ’550’ in case the recipient was not listed in any recipients cdb. 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 TARPITDELAY = 999 qmail-smtpd will issue after TARPITCOUNT invalid Rcpt To: a Recipient failure
Controlling the
email body:
BADLOADERTYPE=’c’
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.
BADMIMETYPE
see control file badmimetypes.cdb. In case BADMIMETYPE=’-’ is set; badmimetypes.cdb is not considered; thus the check is disabled. Setting BADMIMTETYPE=’!’ the mime type is rejected if it includes whitespaces; even without the control file badmimetypes.cdb. Providing BADMIMTETYPE=’+’ the check is disabled if in addition RELAYCLIENTS are recognized.
BARELF
If set, qmail-smtpd will not strictly require the ending delimiter CRLF for lines in the message header/body, but rather will accept those with LF only. If however, BARELF=’-’ is set, mails with bare line feeds (LF) are rejected. Use this option to potentially inverse a global BARELF environment variable per connection.
BASE64
tells QHPSI to enable virus checking only if a base64 encoded attachment was identified.
DATABYTES
see control file databytes.
QHPSI
is used by qmail-smtpd to supply the name of the virus scanner and its path.
Environment
variables for SMTP authentication:
SMTPAUTH
is used to enable SMTP Authentication for the Auth types LOGIN and PLAIN. In case
SMTPAUTH=’+cram’
is defined, qmail-smtpd honors LOGIN, PLAIN, and additionally CRAM-MD5 authentication. Simply
SMTPAUTH=’cram’
restricts authentication just to CRAM-MD5. If however
SMTPAUTH=’!’
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,
SMTPAUTH=’!cram’
may be useful. In opposite, if
SMTPAUTH=’-’
starts with a dash, Auth disabled for particular connections. Note: The use of ’cram’ requires a CRAM-MD5 enabled PAM.
Setting up the
TLS/STARTTLS environment:
UCSPITLS
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:
DELIVERTO
mail address for special recipients.
POSTGREY
triggering the call of qmail-postgrey and feeding it with the IP address and port of the greylisting server. If POSTGREY is set to - no lookup is performed.
RBLSMTPD
feed from rblsmtpd including the information received from the inquired RBL hosts and displayed as X-RBL-Info: message header.
In case of
rejected or defered SMTP connections qmail-smtpd can
provide additional informations in the SMTP reply message
which are sandwiched between the reply code and the EMMSC.
qmail-smtpd recognizes these environment variables:
REPLY_BADMAILFROM
following 553 badmail from
REPLY_BADRCPTTO
following 553 badrcpt to
REPLY_GREYLISTED
following 450 greylisting
REPLY_CONTENT
following 554 Message content invalid
REPLY_HELO
following 550 Bad Helo
REPLY_MAILBOX
following 550 mailbox not existing
REPLY_MAXSIZE
following 552 message size to large
REPLY_NOGATEWAY
following 553 No gateway
REPLY_SENDEREXIST
following 553 SMTP sender DNS
REPLY_SENDERINVALID
following 553 SMTP sender invalid
By means of the
following environment variables, the SMTP session can be
interrogated:
AUTHPROTOCOL
the ESMTPA protocol used for authentication.
AUTHUSER
the supplied username for authentication.
HELOHOST
the HELO/EHLO greeting of the SMTP client.
MAILFROM
containes the received ’Mail From:’ address.
RCPTTO
containes all received ’Rcpt To:’ addresses separated by blanks.
SSL_*
information from sslserver, if applicable.
TCP(6)REMOTEINFO
in authentication mode set to the accepted username.
tcp-environ(5), qmail-control(5), qmail-inject(8), qmail-newmrh(8), qmail-newbmt(8), qmail-authuser(8), qmail-recipients(8), qmail-postgrey(8), qmail-smtpam(8), qmail-mfrules(8), qmail-queue(8), qmail-remote(8), qmail-send(8), qmail-log(8), tcpserver(8), sslserver(8).