Provided by: opensmtpd_6.0.3p1-6_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 (‘\’).  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/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 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 matching of optional session related
             properties:

             [!] authenticated
                     If specified, the rule will only be matched if the client session was
                     authenticated either by requesting authentication over the network or
                     because the message was submitted over the local enqueuer.

             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 rule 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 access control 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 virtual 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 table(5).

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

             for [!] local [alias <aliases>]
                     This rule applies to mail destined to “localhost” and to the default server
                     name (the FILES entry for /etc/mailname details how the server name is
                     determined).  This is the default, and may be omitted.

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

             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 access control 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 ‘@’.

             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.

             You can also accept mail just to have it forwarded elsewhere:

             forward-only
                     Mail is accepted for local recipients ONLY if it is redirected to an
                     external address via an alias or a ~/.forward file.

                     Example:

                           accept for domain opensmtpd.org forward-only

             Finally, the method of delivery is specified:

             deliver to lmtp [host:port | socket] [rcpt-to] [as user]
                     Mail is delivered to host:port, or to the UNIX socket over LMTP with the
                     privileges of the specified user.

                     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.

             deliver to maildir [path]
                     Mail is added to a maildir.  Its location, path, may contain 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 [as user]
                     Mail is piped to the specified program, which is run with the privileges of
                     the specified user or 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(8) 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
                     smtpd(8) 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, smtpd(8) will refuse to relay unless the remote host
                     provides STARTTLS.  If tls verify is specified, smtpd(8) will refuse to
                     relay unless the remote host provides STARTTLS and the certificate it
                     presented has been verified.

                     Note that the tls and tls verify options 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 ‘@’, or an email address, causing smtpd(8) 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.

                     If verify is specified, smtpd(8) 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 are 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.

     ca hostname certificate cafile
             Associate a custom CA certificate located in cafile with hostname.

     ciphers cipher-list
             Specify an alternate list of ciphers to use when establishing TLS sessions.  It is
             highly recommended to avoid making use of this option unless there is a good
             understanding of the implications.

             When not specified, only ciphers considered safe are chosen.

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

                   expire 4d       # expire after 4 days
                   expire 10h      # expire after 10 hours

     limit session {max-rcpt | max-mails} num
             Instruct smtpd(8) to accept a maximum number of recipients or emails at once in the
             receiving queue.  Defaults are 100 for max-mails and 1000 for max-rcpt.

     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 performance.

     listen on interface [family] [port port] [tls | tls-require | tls-require verify | smtps]
             [pki pkiname] [ca caname] [auth | auth-optional [<authtable>]] [tag tag]
             [hostname hostname] [hostnames <names>] [senders <users> [masquerade]] [mask-source]
             [received-auth] [no-dsn]
             Specify an interface and optional port to listen on for incoming connections.  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.

             Host certificates may be used for these connections, and must be previously declared
             using the pki directive.  If pki is specified, a certificate matching name is
             searched for.  Moreover, a previously declared ca directive may be specified to use
             a custom CA certificate.

             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 an optional table as a parameter.  When provided,
             credentials are looked up in this table.  The 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 senders parameter is used, then smtpd(8) will look up a mapping of username
             to email addresses to see whether the authenticated user is allowed to submit mail
             as the sender that was provided in the SMTP session.  In addition, if the masquerade
             option is provided, the From header will be rewritten to match the sender provided
             in the SMTP session.

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

             If the received-auth parameter is used, the “Received” header will display if the
             session was authenticated and by which local user.

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

     listen on socket [mask-source]
             Modify behaviour for the listener which handles messages submitted through the local
             enqueuer, such as the mail(1) utility.  Clients connecting in this manner are tagged
             with the "local" tag.

             Parameters available are:

             mask-source  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.

             If a fallback certificate or SNI is wanted, the ‘*’ wildcard may be used as
             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 dhe params
             Specify the DHE parameters to use for DHE cipher suites with hostname.  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
             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.

     subaddressing-delimiter delimiter
             Redefine the subaddressing delimiter from the default ‘+’ to delimiter.

             Any printable character valid in an email address is allowed, except spaces and ‘@’.

             The first character in the user-part of an email address that matches delimiter is
             considered to be the subaddressing delimiter.

     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.

   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+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 retrieving 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

     smtpd.conf would look like this:

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

           listen on lo0

           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"

           table aliases file:/etc/aliases

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

           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.

           table aliases file:/etc/aliases

           listen on lo0
           listen on lo0 port 10028 tag DKIM

           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 volume 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.

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

           listen on lo0
           listen on egress

           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.