SYNOPSIS

       qmail-smtpd [ checkprogram subprogram ]


DESCRIPTION

       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.



TRANSPARENCY

       qmail-smtpd converts the SMTP newline convention into the UNIX newline
            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
              *
              !
              !*@*.*
              *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
            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 -
            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
            '!*' 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
               example.com|bin/qmail-smtpam mx.example.com
               *:etc/fastforward.cdb
               *|PATH/ldapam ldapserver host port DN passwd
               !*

            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

       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 READ

       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
            UTF8(E)SMTP.

       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

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

       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.

       REPLYMAV
            allows the setting of customized SMTP reply messages in case of a
            MAV mismatch.

       Controlling the email body:

       BADLOADERTYPE='c'
            attachment was identified.

       DATABYTES
            see control file databytes.

       QHPSI
            is used by qmail-smtpd to supply the name of the virus scanner and
            it's 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.

       RBLSMTPD
            feed from rblsmtpd including the information received from the
            the supplied username for authentication.

       MAILFROM
            containes the received 'Mail From:' address.

       RCPTTO
            containes all received 'Rcpt To:' addresses separated by blanks.

       TCP(6)REMOTEINFO
            in authentication mode set to the accepted username.

       SSL_*
            information from sslserver, if applicable.



SEE ALSO

       tcp-environ(5), qmail-control(5), qmail-inject(8), qmail-newmrh(8),
       qmail-newbmt(8), qmail-authuser(8), qmail-recipients(8), qmail-
       smtpam(8), qmail-mfrules(8), qmail-queue(8), qmail-remote(8), qmail-
       send(8), qmail-log(8), tcpserver(8), sslserver(8).




                                       8                 s/qmail:(qmail-smtpd)

Man(1) output converted with man2html