unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OpenBSD-5.7)
Page:
Section:
Apropos / Subsearch:
optional field

SMTPD.CONF(5)               BSD File Formats Manual              SMTPD.CONF(5)

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
     ('\').  Comments can be put anywhere in the file using a hash mark ('#'),
     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/mail/smtpd.conf.local"

     The syntax of smtpd.conf is described below.

     accept | reject
             smtpd(8) accepts and rejects messages based on information gath-
             ered 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 '*' 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 vir-
                     tual domain.  This parameter supports the '*' 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/mail/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 recip-
                     ient email address is found in the table recipients.  The
                     table may contain complete email addresses or apply to an
                     entire domain if prefixed with '@'.

             If the method of delivery is local, a user database may be speci-
             fied 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 UNIX socket
                     over LMTP.

             deliver to maildir [path]
                     Mail is added to a maildir.  Its location, path, may con-
                     tain format specifiers that are expanded before use (see
                     FORMAT SPECIFIERS).  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 FORMAT SPECIFIERS).

             relay [backup [mx]] [as address] [source <source>]
                     [hostname name] [hostnames <names>] [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 '@', 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 refer-
                     enced by source when connecting to the relay.  If the ta-
                     ble 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 con-
                     nected 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 cer-
                     tificate matching the outgoing hostname if one is regis-
                     tered 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 certifi-
                     cate it presented has been verified.

                     Note that the tls and verify options are mutually exclu-
                     sive 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://labelATmx.org         # over TLS
                           smtps+auth://labelATmx.org       # over SMTPS
                           secure+auth://labelATmx.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 '@', 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 refer-
                     enced 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 con-
                     nected 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{s|m|h|d}[, ...]
             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.

     listen on interface [family] [port port]
             [tls | tls-require | tls-require verify | smtps | secure]
             [pki pkiname] [auth | auth-optional [<authtable>]] [tag tag]
             [hostname hostname] [hostnames <names>] [mask-source] [no-dsn]

             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 ser-
             vices.  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 incom-
             ing mail from untrusted senders and outgoing mail from authenti-
             cated users in situations where it is not possible to listen on
             the submission port.

             Both auth and auth-optional accept an optional table as a parame-
             ter.  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 lis-
             tener 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.

             If the no-dsn parameter is used, DSN (Delivery Status Notifica-
             tion) extension will not be enabled.

     max-message-size n
             Specify a maximum message size of n bytes.  The argument may con-
             tain 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 cer-
             tificates, 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 spec-
             ified, 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) utili-
             ties.

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

             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.

   FORMAT SPECIFIERS
     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+TagATExample.org'':

           %{rcpt:lowercase}          expands to ``user+tagATexample.org''
           %{rcpt:uppercase}          expands to ``USER+TAGATEXAMPLE.ORG''
           %{rcpt:strip}              expands to ``UserATExample.org''
           %{rcpt:lowercase|strip}    expands to ``userATexample.org''

     For security concerns, expanded values are sanitized and potentially dan-
     gerous characters are replaced with ':'.  In situations where they are
     desirable, the ``raw'' modifier may be applied.  For example, with recip-
     ient ``user+t?gATexample.org'':

           %{rcpt}        expands to ``user+t:gATexample.org''
           %{rcpt:raw}    expands to ``user+t?gATexample.org''

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

     /etc/mail/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 retrieving the
                              associated canonical name through
                              getaddrinfo(3).

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

EXAMPLES
     The default smtpd.conf file which ships with OpenBSD listens on the loop-
     back 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 out-
     going mail is forwarded to a remote SMTP server.  A secrets file is
     needed to specify a username and password:

           # touch /etc/mail/secrets
           # chmod 640 /etc/mail/secrets
           # chown root:_smtpd /etc/mail/secrets
           # echo "label username:password" > /etc/mail/secrets
           # makemap /etc/mail/secrets

     smtpd.conf would look like this:

           listen on lo0
           table aliases db:/etc/mail/aliases.db
           table secrets db:/etc/mail/secrets.db
           accept for local alias <aliases> deliver to mbox
           accept for any relay via tls+auth://labelATsmtp.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 cer-
     tificate 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/mail/aliases.db

           accept for local alias <aliases> deliver to mda "/path/to/mda -f -"
           accept from any for domain example.com \
                   deliver to mda "/path/to/mda -f -"
           accept for any relay

     For sites that wish to sign messages using DKIM, the dkimproxy package
     may be used as a filter.  The following example is the same as the
     default configuration, but all outgoing mail is passed to dkimproxy_out
     on port 10027 for signing.  The signed messages are received on port
     10028 and tagged for relaying.

           listen on lo0
           listen on lo0 port 10028 tag DKIM

           table aliases db:/etc/mail/aliases.db

           accept for local alias <aliases> deliver to mbox
           accept tagged DKIM for any relay
           accept from local for any relay via smtp://127.0.0.1:10027

     Sites that accept non-local messages may be able to cut down on the vol-
     ume of spam received by rejecting forged messages that claim to be from
     the local domain.  The table other-relays can be used to specify the IP
     addresses of relays that may legitimately originate mail with your domain
     as the sender.

           listen on lo0
           listen on egress

           table aliases   db:/etc/mail/aliases.db
           table other-relays "/etc/mail/other-relays"

           accept for local alias <aliases> deliver to mbox
           accept from local for any relay
           reject from ! source <other-relays> sender "@example.com" for any
           accept from any for domain example.com \
                   alias <aliases> deliver to mbox

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

HISTORY
     smtpd(8) first appeared in OpenBSD 4.6.

BSD                             March 23, 2017                             BSD