Provided by: opensmtpd_5.4.1p1-1_amd64 bug

NAME

       smtpd.conf - Simple Mail Transfer Protocol daemon configuration file

DESCRIPTION

       smtpd.conf is the configuration file for the mail daemon smtpd(8).

       The current line can be extended over multiple lines using a backslash (Sq \.)  Comments
       can be put anywhere in the file using a hash mark (Sq #,) and extend to the end of the
       current line.  Care should be taken when commenting out multi-line text: the comment is
       effective until the end of the entire block.

       Argument names not beginning with a letter, digit, or underscore must be quoted.
       Arguments containing whitespace should be surrounded by double quotes (".)

       Macros can be defined that will later be expanded in context.  Macro names must start with
       a letter, digit, or underscore, and may contain any of those characters.  Macro names may
       not be reserved words (for example listen, accept, port).  Macros are not expanded inside
       quotes.

       For example:
           lan_addr = "192.168.0.1"
           listen on $lan_addr
           listen on $lan_addr tls auth

       Additional configuration files can be included with the
        include
       keyword, for example:
           include "/etc/smtpd.conf.local"

       The syntax of
       smtpd.conf
       is described below.

             accept | reject
                   smtpd(8)
                   accepts and rejects messages
                   based on information gathered during the SMTP session.

            For each message processed by the daemon,
            the filter rules are evaluated in sequential order,
            from first to last.
            The first matching rule decides what action is taken.
            If no rule matches the message,
            the default action is to reject the message.
            An exclamation mark may be specified to perform a reverse match.

            Following the accept/reject
            decision comes the optional tag matching:

                  tagged
                        [ ]
                         tag
                        If specified, the rule will only be matched if the client session was tagged with
                        tag.

            After that the client's IP address filter is specified:

                  from any
                        Make the rule match regardless of the IP of connecting client.

                  from  [ ]
                         local
                        The rule matches only locally originating connections.
                        This is the default,
                        and may be omitted.

                  from  [ ]
                         source
                         table
                        The rule matches if the connection is made from a client whose address
                        is declared in the table
                        table.

            In addition, finer filtering may be achieved on the sender if desired:

                  sender
                        [ ]
                         senders
                        If specified, the rule will only be matched if the sender email address
                        is found in the table
                        senders.
                        The table may contain complete email addresses or apply to an entire
                        domain if prefixed with @.

            Next comes the selection based on the domain the message is sent to:

                  for any [ alias <aliases>]
                        Make the rule match regardless of the domain it is sent to.
                        If specified, the table
                        aliases
                        is used for looking up alternative destinations for all addresses.

                  for any virtual <vmap>
                        Make the rule match regardless of the domain it is sent to.
                        The
                        vmap
                        table will be used as the virtual domain mapping.

                  for   [ ]
                         domain
                        domain
                        [ alias <aliases>]
                        This rule applies to mail destined for the specified
                        domain.
                        This parameter supports the
                        Sq *
                        wildcard,
                        so that a single rule for all sub-domains can be used, for example:
                     accept for domain "*.example.com" deliver to mbox

                 If specified, the table
                 aliases
                 is used for looking up alternative destinations for addresses in this
                 domain.

                  for   [ ]
                         domain
                        <domains>
                        [ alias <aliases>]
                        This rule applies to mail destined to domains which are part of the table
                        domains.

                 If specified, the table
                 aliases
                 is used for looking up alternative destinations for addresses in these
                 domains.

                  for   [ ]
                         domain
                        domain
                         virtual <users>
                        This rule applies to mail destined for the specified virtual
                        domain.
                        This parameter supports the
                        Sq *
                        wildcard,
                        so that a single rule for all sub-domains can be used, for example:
                     accept for domain "*.example.com" \
                            virtual <users> deliver to mbox

                 The table
                 users
                 holds a key-value mapping of virtual to system users.
                 For an example of how to configure the
                 users
                 table, see
                 makemap(8).

                  for   [ ]
                         domain
                        <domains
                        >  virtual <users>
                        This rule applies to mail destined for the virtual domains specified
                        in the table
                        domains.

                 The table
                 users
                 holds a key-value mapping of virtual to system users.
                 For an example of how to configure the
                 users
                 table, see
                 makemap(8).

                  for   [ ]
                         local
                        [ alias <aliases>]
                        This rule applies to mail destined to
                        ``localhost''
                        and to the default server name.
                        See the
                        FILES
                        entry for
                        /etc/mailname
                        below for details of how the server name is determined.

                  for   [ ]
                         local
                         virtual <vmap>
                        This rule applies to mail destined to
                        ``localhost''
                        and to the default server name.
                        The
                        vmap
                        table will be used as the virtual domain mapping.

            Further filtering may be achieved on specific recipients if desired:

                  recipient
                        [ !]
                        recipients
                        If specified, the rule will only be matched if the recipient email address
                        is found in the table
                        recipients.
                        The table may contain complete email addresses or apply to an entire
                        domain if prefixed with
                        Sq @.

            If the method of delivery is local, a user database may be
            specified to override the system database:

                 [ userbase <table>]
                        Look up users in the table
                        table
                        instead of performing system lookups using the
                        getpwnam(3)
                        function.

            Finally, the method of delivery is specified:

                  deliver to lmtp [host: port | socket]
                        Mail is delivered to
                        host: port,
                        or to the
                        Ux
                        socket
                        over LMTP.

                  deliver to maildir path
                        Mail is added to a maildir.
                        Its location,
                        path,
                        may contain format specifiers that are expanded before use
                        (see above).
                        If
                        path
                        is not provided, then
                        ~/Maildir
                        is assumed.

                  deliver to mbox
                        Mail is delivered to the local user's system mailbox in
                        /var/mail.

                  deliver to mda program
                        Mail is piped to the specified
                        program,
                        which is run with the privileges of the user the message is destined to.
                        This parameter may use conversion specifiers that are expanded before use
                        (see above).

                  relay [ backup [mx]]
                        [ as address]
                        [ source source]
                        Bk -words
                        [ hostname name]
                        [ hostnames names]
                        Ek
                        [ pki pkiname]
                        [ tls | verify]
                        Mail is relayed.
                        The routing decision is based on the DNS system.

                 If the
                  backup
                 parameter is specified, the current server will act as a backup server
                 for the target domain.
                 Accepted mails are only relayed through servers with a lower preference
                 value in the MX record for the domain than the one specified in
                 mx.
                 If
                 mx
                 is not specified, the default server name will be assumed.

                 If the
                  as
                 parameter is specified,
                 smtpd(8)
                 will rewrite the sender advertised
                 in the SMTP session.
                 address
                 may be a user, a domain prefixed with
                 Sq @,
                 or an email address, causing
                 smtpd to rewrite the user-part, the domain-part, or the entire address,
                 respectively.

                 If the
                  source
                 parameter is specified,
                 smtpd(8)
                 will explicitly bind to an address found in the table referenced by
                 source
                 when connecting to the relay.
                 If the table contains more than one address, they are picked in turn each
                 time a new connection is opened.

                 By default, when connecting to a remote server,
                 smtpd(8)
                 advertises its default server name.
                 A
                  hostname
                 parameter may be specified to advertise the alternate hostname
                 name.
                 If the
                  source
                 parameter is used, the
                  hostnames
                 parameter may be specified to advertise a hostname based on
                 the source address.
                 Table
                 names
                 contains a mapping of IP addresses to hostnames and
                 smtpd(8)
                 will automatically select the name that matches its source address
                 when connected to the remote server.
                 The
                  hostname
                 and
                  hostnames
                 parameters are mutually exclusive.

                 When relaying, STARTTLS is always attempted if available on remote host
                 and OpenSMTPD will try to present a certificate matching the outgoing
                 hostname if one is registered in the pki.
                 If
                  pki
                 is specified, the certificate registered for
                 pkiname
                 is used instead.

                 If
                  tls
                 is specified, OpenSMTPD will refuse to relay unless the remote host provides
                 STARTTLS.

                 If
                  verify
                 is specified, OpenSMTPD will refuse to relay unless the remote host provides
                 STARTTLS and the certificate it presented has been verified.

                 Note that the
                  tls
                 and
                  verify
                 options are mutually exclusive and should only be used in private networks
                 as they will prevent proper relaying on the Internet.

                  relay via
                        host
                        [ auth <auth>]
                        [ as address]
                        [ source source]
                        [ hostname name]
                        [ hostnames names]
                        [ pki pkiname]
                        [ verify]
                        Mail is relayed through the specified
                        host
                        expressed as a URL.
                        For example:
                     smtp://mx1.example.org        # use SMTP
                     smtp://mx1.example.org:4321   # use SMTP \
                                         # with port 4321
                     lmtp://localhost:2026         # use LMTP \
                                         # with port 2026

                 The communication channel may be secured using one of the secure
                 schemas.
                 For example:
                     tls://mx1.example.org         # use TLS
                     smtps://mx1.example.org       # use SMTPS
                     secure://mx1.example.org # try SMTPS and \
                                         # fallback to TLS

                 In addition, credentials for authenticated relaying may be provided
                 when using a secure schema.
                 For example:
                     tls+auth://label@mx.example.org         # over TLS
                     smtps+auth://label@mx.example.org  # over SMTPS
                     secure+auth://label@mx.example.org # over either \
                                              # SMTPS or TLS

                 If a pki entry exists for the outgoing hostname, or one is provided
                 with
                 pkiname,
                 the associated certificate will be sent to the remote server.

                 If an SMTPAUTH session with
                 host
                 is desired, the
                  auth
                 parameter is used to specify the
                 auth
                 table that holds the credentials.
                 Credentials will be looked up using the label provided in the URL.

                 If the
                  as
                 parameter is specified,
                 smtpd(8)
                 will rewrite the sender advertised
                 in the SMTP session.
                 address
                 may be a user, a domain prefixed with
                 Sq @,
                 or an email address, causing
                 smtpd to rewrite the user-part, the domain-part, or the entire address,
                 respectively.

                 If the
                  source
                 parameter is specified,
                 smtpd(8)
                 will explicitly bind to an address found in the table referenced by
                 table
                 when connecting to the relay.
                 If the table contains more than one address, they are picked in turn each
                 time a new connection is opened.

                 By default, when connecting to a remote server,
                 smtpd(8)
                 advertises its default server name.
                 A
                  hostname
                 parameter may be specified to advertise the alternate hostname
                 name.
                 If the
                  source
                 parameter is used, the
                  hostnames
                 parameter may be specified to advertise a hostname based on
                 the source address.
                 Table
                 names
                 contains a mapping of IP addresses to hostnames and
                 smtpd(8)
                 will automatically select the name that matches its source address
                 when connected to the remote server.
                 The
                  hostname
                 and
                  hostnames
                 parameters are mutually exclusive.

            If
             verify
            is specified, OpenSMTPD will refuse to relay unless the remote host provides
            STARTTLS and the certificate it presented has been verified.
            The relay URL must specify TLS for this option to be valid.

            Additional per-rule adjustments available:

                  expire n {s|m|h|d}
                        Specify how long a message that matched this rule can stay in the queue.

             bounce-warn n Bro s|m|h|d Brc Bq, ...
                   Specify the delays for which temporary failure reports must be generated
                   when messages are stuck in the queue.
                   For example:
                bounce-warn    1h, 6h, 2d

            will generate a failure report when an envelope is in the queue for more
            than one hour, six hours and two days.
            The default is 4h.

             expire n {s|m|h|d}
                   Specify how long a message can stay in the queue.
                   The default value is 4 days.
                   For example:
                expire 4d # expire after 4 days
                expire 10h     # expire after 10 hours

             limit mta
                   [ for  domain domain]
                   family
                   Instruct
                   smtpd(8)
                   to only use the specified address
                   family
                   for outgoing connections.
                   Accepted values are
                    inet4
                   and
                    inet6.
                   If a
                   domain
                   is specified, the restriction only applies when connecting
                   to MXs for this domain.

             limit scheduler max-inflight
                   num
                   Suspend the scheduling of envelopes for deliver/relay until the number
                   of inflight envelopes falls below
                   num.
                   Changing the default value might degrade performances.

            Bk -words
                    listen on interface
                   [family]
                   [ port port]
                   [ tls | tls-require | tls-require verify | smtps | secure]
                   [ pki pkiname]
                   [ auth | auth-optional | auth authtable |  auth-optional authtable]
                   [ tag tag]
                   [ hostname hostname]
                   [ hostnames names]
                   [ mask-source]
                   Ek
                   Specify an
                   interface
                   and
                   port
                   to listen on.
                   An interface group, an IP address or a domain name may
                   be used in place of
                   interface.
                   The
                   family
                   parameter can be used to listen only on specific address family.
                   Accepted values are
                    inet4
                   and
                    inet6.

            Secured connections are provided either using STARTTLS
            ( tls,)
            by default on port 25,
            or SMTPS
            ( smtps,)
            by default on port 465.
             tls-require
            may be used to force clients to establish a secure connection
            before being allowed to start an SMTP transaction.

            If
             tls-require verify
            is specified, the client must provide a valid certificate to be
            able to establish an SMTP session.

             secure
            may be specified to provide both STARTTLS and SMTPS services.
            Host certificates may be used for these connections,
            and must be priorly declared using the pki directive.
            If
             pki
            is specified,
            a certificate matching
             name
            is searched for.

            If the
             auth
            parameter is used,
            then a client may only start an SMTP transaction after a
            successful authentication.
            Any remote sender that passed SMTPAUTH is treated as if
            it was the server's local user that was sending the mail.
            This means that filter rules using "from local" will be matched.
            If
             auth-optional
            is specified, then SMTPAUTH is not required to establish an
            SMTP transaction.
            This is only useful to let a listener accept incoming mail from
            untrusted senders and outgoing mail from authenticated users in
            situations where it is not possible to listen on the submission
            port.

            Both
             auth
            and
             auth-optional
            accept a table as parameter.
            When provided, credentials are looked up in this table.
            Credentials format is described in
            table(5).

            If the
             tag
            parameter is used, then clients connecting to the listener will be
            tagged
            tag.

            If the
             hostname
            parameter is used, then it will be used in the greeting banner
            instead of the default server name.

            The
             hostnames
            parameter overrides the server name for specific addresses.
            Table
            names
            contains a mapping of IP addresses to hostnames and
            smtpd(8)
            will use the hostname that matches the address on which the connection arrives
            if it is found in the mapping.

            If the
             mask-source
            parameter is used, then the listener will skip the "from" part
            when prepending the "Received" header.

             max-message-size n
                   Specify a maximum message size of
                   n
                   bytes.
                   The argument may contain a multiplier, as documented in
                   scan_scaled(3).
                   The default maximum message size is 35MB if none is specified.

             pki hostname  certificate certfile
                   Associate the certificate located in
                   certfile
                   with
                   hostname.

            A certificate chain may be created by appending one or many certificates,
            including a Certificate Authority certificate,
            to
            certfile.

            Creation of certificates is documented in
            starttls(8).

             pki hostname  key keyfile
                   Associate the key located in
                   keyfile
                   with
                   hostname.

             pki hostname  ca cafile
                   Associate a custom CA certificate
                   cafile
                   with
                   hostname.

             pki hostname  dhparams dhfile
                   Associate the Diffie-Hellman parameters located in
                   dhfile
                   with
                   hostname.

            The parameters are used for ephemeral key exchange.
            If not specified, OpenSMTPD will use safely generated builtin parameters.

            Creation of Diffie-Hellman parameters is documented in
            openssl(1).

             queue compression
                   Enable transparent compression of envelopes and messages.
                   The only supported algorithm at the moment is gzip.
                   Envelopes and messages may be inspected using the
                   smtpctl(8)
                   or
                   gzcat(1)
                   utilities.

             queue encryption [key key]
                   Enable transparent encryption of envelopes and messages.
                   key
                   must be a 16-byte random key in hexadecimal representation.
                   It can be obtained using the
                   openssl(1)
                   utility as follow:
                $ openssl rand -hex 16

            If the
            key
            parameter is not specified, it is read with
            getpass(3)
            at startup.
            If
            key
            is "stdin", then it is read from the standard input at startup.

            The only supported algorithm is AES-256 in GCM mode.
            Envelopes and messages may be inspected using the
            smtpctl(8)
            utility.

            Queue encryption can be used with queue compression and will always
            perform compression before encryption.

             table name [type:] config
                   Tables are used to provide additional configuration information for
                   smtpd(8)
                   in the form of lists or key-value mappings.
                   The format of the entries depends on what the table is used for.
                   Refer to
                   table(5)
                   for the exhaustive documentation.

            The table is identified using table name
            name;
            the name itself is arbitrarily chosen.

            type
            specifies the table backend,
            and should be one of the following:

                 db     Information is stored in a file created using
                        makemap(8).

                 file   Information is stored in a plain text file using the
                        same format as used to generate
                        makemap(8)
                        mappings.
                        This is the default.

            config
            specifies a configuration file for the table data.
            It must be an absolute path to a file for the
            ``file''
            and
            ``db''
            table types.

             table name {value [, ...]}
                   Tables containing list of static values may be declared
                   using an inlined notation.

            The table is identified using table name
            name;
            the name itself is arbitrarily chosen.

            The table must contain at least one value and may declare many values as a
            list of comma separated strings.

             table name {key=value [, ...]}
                   Tables containing static key-value mappings may be declared
                   using an inlined notation.

            The table is identified using table name
            name;
            the name itself is arbitrarily chosen.

            The table must contain at least one key-value mapping and may declare
            many mappings as a list of comma separated
            key=value
            descriptions.

       Some configuration directives support expansion of their parameters at runtime.
       Such directives (for example
       deliver to maildir,
       deliver to mda)
       may use format specifiers which will be expanded before delivery or
       relaying.
       The following formats are currently supported:
           %{sender}      sender email address
           %{sender.user}      user part of the sender email address
           %{sender.domain}     domain part of the sender email address
           %{rcpt}              recipient email address
           %{rcpt.user}        user part of the recipient email address
           %{rcpt.domain}      domain part of the recipient email address
           %{dest}              recipient email address after expansion
           %{dest.user}        user part after expansion
           %{dest.domain}      domain part after expansion
           %{user.username}     local user
           %{user.directory}    home directory of the local user

       Expansion formats also support partial expansion using the optional
       bracket notations with substring offset.
       For example, with recipient domain "example.org":
           %{rcpt.domain[0]}   expands to "e"
           %{rcpt.domain[1]}   expands to "x"
           %{rcpt.domain[8:]}  expands to "org"
           %{rcpt.domain[-3:]} expands to "org"
           %{rcpt.domain[0:6]} expands to "example"
           %{rcpt.domain[0:-4]}     expands to "example"

       In addition, modifiers may be applied to the token.
       For example, with recipient "User+Tag@Example.org":
           %{rcpt:lowercase}   expands to "user+tag@example.org"
           %{rcpt:uppercase}   expands to "USER+TAG@EXAMPLE.ORG"
           %{rcpt:strip}       expands to "User@Example.org"
           %{rcpt:lowercase|strip}  expands to "user@example.org"

       For security concerns, expanded values are sanitized and potentially
       dangerous characters are replaced with ":".
       In situations where they are desirable, the "raw" modifier may be applied.
       For example, with recipient "user+t?g@example.org":
           %{rcpt}        expands to "user+t:g@example.org"
           %{rcpt:raw}    expands to "user+t?g@example.org"

FILES

            /etc/smtpd.conf
                   Default smtpd(8) configuration file.

            /etc/mailname
                   If this file exists, the first line is used as the server name.  Otherwise,
                   the server name is derived from the local hostname returned by gethostname(3),
                   either directly if it is a fully qualified domain name, or by retreiving the
                   associated canonical name through getaddrinfo(3).

            /var/spool/smtpd/
                   Spool directories for mail during processing.

EXAMPLES

       The default smtpd.conf file listens on the loopback network interface (lo0), and allows
       for mail from users and daemons on the local machine, as well as permitting email to
       remote servers.  Some more complex configurations are given below.

       This first example is the same as the default configuration, but all outgoing mail is
       forwarded to a remote SMTP server.  A secrets file is needed to specify a username and
       password:
           # touch /etc/secrets
           # chmod 640 /etc/secrets
           # chown root:_smtpd /etc/secrets
           # echo "label username:password" > /etc/secrets
           # makemap /etc/secrets

       smtpd.conf
       would look like this:
           listen on lo0
           table aliases db:/etc/aliases.db
           table secrets db:/etc/secrets.db
           accept for local alias <aliases> deliver to mbox
           accept for any relay via tls+auth://label@smtp.example.com \
                auth <secrets>

       In this second example,
       the aim is to permit mail relaying for any user that can authenticate
       using their normal login credentials.
       An RSA certificate must be provided to prove the server's identity.
       The mail server listens on all interfaces the default route(s) point to.
       Mail with a local destination should be sent to an external mda.
       First, the RSA certificate is created:
           # openssl genrsa -out /etc/ssl/private/mail.example.com.key 4096
           # openssl req -new -x509 -key /etc/ssl/private/mail.example.com.key \
                -out /etc/ssl/mail.example.com.crt -days 365
           # chmod 600 /etc/ssl/mail.example.com.crt
           # chmod 600 /etc/ssl/private/mail.example.com.key

       In the example above,
       a certificate valid for one year was created.
       The configuration file would look like this:
           pki mail.example.com certificate "/etc/ssl/mail.example.com.crt"
           pki mail.example.com key "/etc/ssl/private/mail.example.com.key"
           listen on lo0
           listen on egress tls pki mail.example.com auth
           table aliases db:/etc/aliases.db
           accept for local alias <aliases> deliver to mda "/path/to/mda -f -"
           accept from any for domain example.org \
                deliver to mda "/path/to/mda -f -"
           accept for any relay

SEE ALSO

       mailer.conf(5), table(5), makemap(8), smtpd(8)

HISTORY

       smtpd(8) first appeared in OpenBSD 4.6.

                                   $Mdocdate: December 5 2013 $                     SMTPD.CONF(5)