smtpd.conf



SMTPD.CONF(5)                 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).

     When mail arrives, each "RCPT TO:" command generates a mail envelope.  If
     an envelope matches any of a pre-designated set of criteria (using the
     match directive), the message is accepted for delivery.  A copy of the
     message, as well as its associated envelopes, is saved in the mail queue
     and later dispatched according to an associated set of actions (using the
     action directive).  If an envelope does not match any options, it is
     rejected.  The match rules are evaluated sequentially, with the first
     match winning.

     The format of the configuration file is fairly flexible.  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, as well as reserved words (such as listen, match, and port),
     must be quoted.  Arguments containing whitespace should be surrounded by
     double quotes (").

     Macros can be defined that are later expanded in context.  Macro names
     must start with a letter, digit, or underscore, and may contain any of
     those characters, but may not be reserved words.  Macros are not expanded
     inside quotes.  For example:

           lan_addr = "192.168.0.1"
           listen on $lan_addr
           listen on $lan_addr tls auth

     The syntax of smtpd.conf is described below.

     action name method [options]
             When the queue runner processes an envelope from the mail queue,
             it carries out the action name, selected by the match ... action
             directive when the message was received.  The action directive
             provides configuration data for delivery attempts.  Required
             lookups are performed at the time of each delivery attempt.
             Consequently, changing an action directive or the files it
             references and restarting the smtpd(8) daemon causes the changes
             to take effect for subsequent delivery attempts for the
             respective dispatcher name, even for messages that were already
             stuck in the queue prior to the configuration changes.

             The delivery method parameter may be one of the following:

             expand-only
                     Only accept the message if a delivery method was
                     specified in an aliases or .forward file.

             forward-only
                     Only accept the message if the recipient results in a
                     remote address after the processing of aliases or forward
                     file.

             lmtp destination [rcpt-to]
                     Deliver the message to an LMTP server at destination.
                     The location may be expressed as host:port or as a UNIX
                     socket.

                     Optionally, rcpt-to might be specified to use the
                     recipient email address (after expansion) instead of the
                     local user in the LMTP session as RCPT TO.

             maildir [pathname [junk]]
                     Deliver the message to the maildir in pathname if
                     specified, or by default to ~/Maildir.

                     The pathname may contain format specifiers that are
                     expanded before use (see FORMAT SPECIFIERS).

                     If the junk argument is provided, the message will be
                     moved to the Junk folder if it contains a positive X-Spam
                     header.

             mbox    Deliver the message to the user's mbox with
                     mail.local(8).

             mda command
                     Delegate the delivery to a command that receives the
                     message on its standard input.

                     The command may contain format specifiers that are
                     expanded before use (see FORMAT SPECIFIERS).

             relay   Relay the message to another SMTP server.

             The local delivery methods support additional options:

             alias <table>
                     Use the mapping table for aliases(5) expansion.

             ttl n{s|m|h|d}
                     Specify how long a message may remain in the queue.

             user username
                     Specify the username for performing the delivery, to be
                     looked up with getpwnam(3).

                     This is used for virtual hosting where a single username
                     is in charge of handling delivery for all virtual users.

                     This option is not usable with the mbox delivery method.

             userbase <table>
                     Use the mapping table for user lookups instead of the
                     getpwnam(3) function.

                     The userbase does not apply for the user option.

             virtual <table>
                     Use the mapping table for virtual expansion.  The
                     aliasing table format is described in table(5).

             wrapper name
                     Use the wrapper specified in mda wrapper.

             The relay delivery methods also support additional options:

             backup  Operate as a backup mail exchanger delivering messages to
                     any mail exchanger with higher priority.

             backup mx name
                     Operate as a backup mail exchanger delivering messages to
                     any mail exchanger with higher priority than mail
                     exchanger identified as name.

             helo heloname
                     Advertise heloname as the hostname to other mail
                     exchangers during the HELO phase.

             helo-src <table>
                     Use the mapping table to look up a hostname matching the
                     source address, to advertise during the HELO phase.

             host relay-url
                     Do not perform MX lookups but relay messages to the relay
                     host described by relay-url.  The format for relay-url is
                     [proto://[label@]]host[:port].  The following protocols
                     are available:

                     smtp        Normal SMTP session with opportunistic
                                 STARTTLS (the default).
                     smtp+tls    Normal SMTP session with mandatory STARTTLS.
                     smtp+notls  Plain text SMTP session without TLS.
                     lmtp        LMTP session.
                     smtps       SMTP session with forced TLS on connection.

                     The label corresponds to an entry in a credentials table,
                     as documented in table(5).  It is used with the
                     "smtp+tls" and "smtps" protocols for authentication.
                     Server certificates for those protocols are verified by
                     default.

             tls [no-verify]
                     Require TLS to be used when relaying, using mandatory
                     STARTTLS by default.  When used with a smarthost, the
                     protocol must not be "smtp+notls://".  If [no-verify] is
                     specified, do not require a valid certificate.

             auth <table>
                     Use the mapping table for connecting to relay-url using
                     credentials.  This option is usable only with host
                     option.  The credential table format is described in
                     table(5).

             mail-from mailaddr
                     Use mailaddr as the MAIL FROM address within the SMTP
                     transaction.

             src address | <address>
                     Use the string or list table address for the source IP
                     address.  If the list contains more than one address, all
                     of them are used in such a way that traffic is routed as
                     efficiently as possible.

     bounce warn-interval delay [, delay ...]
             Send warning messages to the envelope sender when temporary
             delivery failures cause a message to remain on the queue for
             longer than delay.  Each delay parameter consists of a positive
             decimal integer and a unit s, m, h, or d.  At most four delay
             parameters can be specified.  The default is "bounce
             warn-interval 4h", sending a single warning after four hours.

     ca caname cert cafile
             Associate the Certificate Authority (CA) certificate file cafile
             with host caname, and use that file as the CA certificate for
             that host.  caname is the server's name, derived from the default
             hostname or set using either /etc/mail/mailname or using the
             hostname directive.

     include "pathname"
             Replace this directive with the content of the additional
             configuration file at the absolute pathname.

     listen on interface [family] [options]
             Listen on the interface for incoming connections, using the same
             syntax as for ifconfig(8).  The interface parameter may also be
             an interface group, an IP address, or a domain name.  Listening
             can optionally be restricted to a specific address family, which
             can be either inet4 or inet6.

             The options are as follows:

             auth [<authtable>]
                     Support SMTPAUTH: clients may only start SMTP
                     transactions after successful authentication.  Users are
                     authenticated against either their own normal login
                     credentials or a credentials table authtable, the format
                     of which is described in table(5).

             auth-optional [<authtable>]
                     Support SMTPAUTH optionally: clients need not
                     authenticate, but may do so.  This allows a listen on
                     directive to both accept incoming mail from untrusted
                     senders and permit outgoing mail from authenticated users
                     (using match auth).  It can be used in situations where
                     it is not possible to listen on a separate port (usually
                     the submission port, 587) for users to authenticate.

             ca caname
                     For secure connections, use the CA certificate associated
                     with caname (declared in a ca directive) as the CA
                     certificate when verifying client certificates.

             hostname hostname
                     Use hostname in the greeting banner instead of the
                     default server name.

             hostnames <names>
                     Override the server name for specific addresses.  The
                     names table contains a mapping of IP addresses to
                     hostnames.  If the address on which the connection
                     arrives appears in the mapping, the associated hostname
                     is used.

             mask-src
                     Omit the from part when prepending "Received" headers.

             no-dsn  Disable the DSN (Delivery Status Notification) extension.

             pki pkiname
                     For secure connections, use the certificate associated
                     with pkiname (declared in a pki directive) to prove a
                     mail server's identity.

             port [port]
                     Listen on the given port instead of the default port 25.

             received-auth
                     In "Received" headers, report whether the session was
                     authenticated and by which local user.

             senders <users> [masquerade]
                     Look up the authenticated user in the users mapping table
                     to find the email addresses that user is allowed to
                     submit mail as.  In addition, if the masquerade option is
                     provided, the From header is rewritten to match the
                     sender provided in the SMTP session.

             smtps   Support SMTPS, by default on port 465.  Mutually
                     exclusive with tls.

             tag tag
                     Clients connecting to the listener are tagged with the
                     given tag.

             tls     Support STARTTLS, by default on port 25.  Mutually
                     exclusive with smtps.

             tls-require [verify]
                     Like tls, but force clients to establish a secure
                     connection before being allowed to start an SMTP
                     transaction.  With the verify option, clients must also
                     provide a valid certificate to establish an SMTP session.

     listen on socket [mask-src]
             Listen for incoming SMTP connections on the Unix domain socket
             /var/run/smtpd.sock.  This is done by default, even if the
             directive is absent.  If the mask-src option is specified,
             printing of the HELO name, hostname, and IP address of the
             originating host is suppressed in Received: header lines.

     match options action name
             If at least one mail envelope matches the options of one match
             action directive, receive the incoming message, put a copy into
             each matching envelope, and atomically save the envelopes to the
             mail spool for later processing by the respective dispatcher
             name.

             The following matching options are supported and can all be
             negated:

             [!] for any
                     Specify that session may address any destination.

             [!] for local
                     Specify that session may address any local domain.  This
                     is the default, and may be omitted.

             [!] for domain domain | <domain>
                     Specify that session may address the string or list table
                     domain.

             [!] from any
                     Specify that session may originate from any source.

             [!] from local
                     Specify that session may only originate from a local IP
                     address, or from the local enqueuer.  This is the
                     default, and may be omitted.

             [!] from socket
                     Specify that session may only originate from the local
                     enqueuer.

             [!] from src address | <address>
                     Specify that session may only originate from string or
                     list table address which can be a specific address or a
                     subnet expressed in CIDR-notation.

             In addition, the following transaction options:

             [!] auth
                     Matches transactions which have been authenticated.

             [!] helo helo-name | <helo-name>
                     Specify that session's HELO / EHLO should match the
                     string or list table helo-name.

             [!] mail-from sender | <sender>
                     Specify that transactions's MAIL FROM should match the
                     string or list table sender.

             [!] rcpt-to recipient | <recipient>
                     Specify that transaction's RCPT TO should match the
                     string or list table recipient.

             [!] tag tag
                     Matches transactions tagged with the given tag.

             [!] tls
                     Specify that transaction should take place in a TLS
                     channel.

     match options reject
             Reject the incoming message during the SMTP dialogue.  The same
             options are supported as for the match action directive.

     mda wrapper name command
             Associate command with the mail delivery agent wrapper named
             name.  When a local delivery specifies a wrapper, the command
             associated with the wrapper will be executed instead.  The
             command may contain format specifiers (see FORMAT SPECIFIERS).

     mta max-deferred number
             When delivery to a given host is suspended due to temporary
             failures, cache at most number envelopes for that host such that
             they can be delivered as soon as another delivery succeeds to
             that host.  The default is 100.

     pki pkiname cert certfile
             Associate certificate file certfile with host pkiname, and use
             that file to prove the identity of the mail server to clients.
             pkiname is the server's name, derived from the default hostname
             or set using either /etc/mail/mailname or using the hostname
             directive.  If a fallback certificate or SNI is wanted, the `*'
             wildcard may be used as pkiname.

             A certificate chain may be created by appending one or many
             certificates, including a Certificate Authority certificate, to
             certfile.  The creation of certificates is documented in
             starttls(8).

     pki pkiname key keyfile
             Associate the key located in keyfile with host pkiname.

     pki pkiname dhe params
             Specify the DHE parameters to use for DHE cipher suites with host
             pkiname.  Valid parameter values are none, legacy, and auto.  For
             legacy, a fixed key length of 1024 bits is used, whereas for
             auto, the key length is determined automatically.  The default is
             none, which disables DHE cipher suites.

     queue compression
             Store queue files in a compressed format.  This may be useful to
             save disk space.

     queue encryption [key]
             Encrypt queue files with EVP_aes_256_gcm(3).  If no key is
             specified, it is read with getpass(3).  If the string stdin or a
             single dash (`-') is given instead of a key, the key is read from
             the standard input.

     queue ttl delay
             Set the default expiration time for temporarily undeliverable
             messages, given as a positive decimal integer followed by a unit
             s, m, h, or d.  The default is four days (4d).

     smtp ciphers control
             Set the control string for SSL_CTX_set_cipher_list(3).  The
             default is "HIGH:!aNULL:!MD5".

     smtp max-message-size size
             Reject messages larger than size, given as a positive number of
             bytes or as a string to be parsed with scan_scaled(3).  The
             default is "35M".

     smtp sub-addr-delim character
             When resolving the local part of a local email address, ignore
             the ASCII character and all characters following it.  The default
             is `+'.

     table name [type:]pathname
             Tables 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.

             Each table is identified by an arbitrary, unique name.

             If the type is db, information is stored in a file created with
             makemap(8); if it is file or omitted, information is stored in a
             plain text file using the format described in table(5).  The
             pathname to the file must be absolute.

     table name {value [, ...]}
             Instead of using a separate file, declare a list table containing
             the given static values.  The table must contain at least one
             value and may declare multiple values as a comma-separated
             (whitespace optional) list.

     table name {key=value [, ...]}
             Instead of using a separate file, declare a mapping table
             containing the given static key-value pairs.  The table must
             contain at least one key-value pair and may declare multiple
             pairs as a comma-separated (whitespace optional) list.

   FORMAT SPECIFIERS
     Some configuration directives support expansion of their parameters at
     runtime.  Such directives (for example action maildir, action mda) may
     use format specifiers which are expanded before delivery or relaying.
     The following formats are currently supported:

           %{sender}            sender email address, may be empty string
           %{sender.user}       user part of the sender email address, may be
                                empty
           %{sender.domain}     domain part of the sender email address, may
                                be empty
           %{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
           %{mbox.from}         name used in mbox From separator lines
           %{mda}               mda command, only available for mda wrappers

     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/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/run/smtpd.sock      Unix domain socket for incoming SMTP
                              connections.
     /var/spool/smtpd/        Spool directories for mail during processing.


EXAMPLES

     The default smtpd.conf file which ships with OpenBSD 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/mail/secrets
           # chmod 640 /etc/mail/secrets
           # chown root:_smtpd /etc/mail/secrets
           # echo "bob username:password" > /etc/mail/secrets

     smtpd.conf would look like this:

           table aliases file:/etc/mail/aliases
           table secrets file:/etc/mail/secrets

           listen on lo0

           action "local" mbox alias <aliases>
           action "relay" relay host smtp+tls://bob@smtp.example.com \
                   auth <secrets>

           match for local action "local"
           match for any action "relay"

     In this second example, the aim is to permit mail delivery and relaying
     only for users 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 routes
     point to.  Mail with a local destination is 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 cert "/etc/ssl/mail.example.com.crt"
           pki mail.example.com key "/etc/ssl/private/mail.example.com.key"

           table aliases file:/etc/mail/aliases

           listen on lo0
           listen on egress tls pki mail.example.com auth

           action mda_with_aliases mda "/path/to/mda -f -" alias <aliases>
           action mda_without_aliases mda "/path/to/mda -f -"
           action "relay" relay

           match for local action mda_with_aliases
           match from any for domain example.com action mda_without_aliases
           match for any action "relay"
           match auth from any for any action "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.

           table aliases file:/etc/mail/aliases

           listen on lo0
           listen on lo0 port 10028 tag DKIM

           action "mbox" mbox alias <aliases>
           action "relay" relay
           action relay_dkim relay host smtp://127.0.0.1:10027

           match for local action "mbox"
           match tag DKIM for any action "relay"
           match for any action relay_dkim

     Sites that accept non-local messages may be able to cut down on the
     volume of spam received by rejecting forged messages that claim to be
     from the local domain.  The following example uses a list table
     other-relays to specify the IP addresses of relays that may legitimately
     originate mail with the owner's domain as the sender.

           table aliases file:/etc/mail/aliases
           table other-relays file:/etc/mail/other-relays

           listen on lo0
           listen on egress

           action "mbox" mbox alias <aliases>
           action "relay" relay

           match for local action "mbox"
           match for any action "relay"
           match !from src <other-relays> mail-from "@example.com" for any \
                 reject
           match from any for domain example.com action "mbox"


SEE ALSO

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


HISTORY

     smtpd(8) first appeared in OpenBSD 4.6.

OpenBSD 6.4                     October 8, 2018                    OpenBSD 6.4

[Unix Hosting | Open-Source | Contact Us]
[Engineering & Automation | Software Development | Server Applications]