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:

    wan_if = "fxp0"
    listen on $wan_if
    listen on $wan_if tls enable auth

Some configuration directives expect expansion of their parameters at runtime. Such directives (for example deliver to maildir, deliver to mda, relay via) may use format specifiers which will be expanded before delivery or relaying. The following formats are currently supported: %a expands to the user part of the email address prior to the resolution of aliases; %u expands to the user part after aliases resolution and will typically be the system account; %d expands to the domain part of the email address; %U expands to the user part of the sender email address; %D expands to the domain part of the sender email address.

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.

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

hostname name
    Specify the fully qualified domain name (FQDN) of the server. By default the current host name is used, as returned by hostname(1).

    listen on interface [port port] [tls | smtps] [certificate name] [enable auth] 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.

    Secured connections are provided either using STARTTLS (tls), by default on port 25, or SMTPS (smtps), by default on port 465. Host certificates may be used for these connections, and are searched for in the /etc/mail/certs directory. If certificate is specified, a certificate <name>.crt, a key <name>.key, a certificate authority <name>.ca and Diffie-Hellman parameters <name>.dh are searched for. If no certificate is specified, the default interface name is instead used, for example fxp0.crt, fxp0.key, fxp0.ca, and fxp0.dh. If no DH parameters are provided, smtpd will use built-in parameters. Creation of certificates is documented in starttls(8).

    If the enable auth parameter is used, 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.

    map map source type source Maps are used to provide additional configuration information for smtpd(8).

    map may be named freely.

    type may be one of the following:

    db  Mappings are stored in a file created using makemap(8). This is the default type if none is specified.
    plain
        Mappings are stored in a plain text file using the same format as used to generate makemap(8) mappings.

    source specifies the source of the map data. It must be an absolute path to a file for the “plain” and “db” map types.

size n
    Specify a maximum message size of n bytes. The argument may contain a multiplier, as documented in scan_scaled(3).

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.

    Following the accept/reject decision comes the client's IP address filter:

    from all
        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 network
        The rule matches if the connection is made from the specified network, specified in CIDR notation.

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

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

        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, aliases is used for looking up alternative destinations for addresses in this domain.

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

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

        for local [alias map] This rule applies to mail destined to “localhost” and to the server's fully qualified domain name, as returned by hostname(1).

    for virtual map vmap
        This rule applies to mail destined for the virtual domains specified in the map vmap. For an example of how to configure a virtual map, see makemap(8).

    Finally, the method of delivery is specified:

    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 [as address] Mail is relayed. The routing decision is based on the DNS system.

        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.

        relay via host [certificate name] [auth map] [as address] 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

        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
            ssl://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://mx1.example.org	# AUTH over TLS
            smtps+auth://mx1.example.org	# AUTH over SMTPS
            ssl+auth://mx1.example.org	# AUTH over either \
            				# SMTPS or TLS

        If a certificate name is specified and exists in the /etc/mail/certs directory with a .crt extension, it will be used if the remote server requests a client certificate. Creation of certificates is documented in starttls(8).

        If an SMTPAUTH session with host is desired, the auth parameter is used to specify the map that holds the credentials.

        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.

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

FILES
/etc/mail/smtpd.conf
    Default smtpd(8) configuration file.
/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 "smtp.example.com  username:password"  /etc/mail/secrets
    # makemap /etc/mail/secrets

smtpd.conf would look like this:

    listen on lo0
    map aliases source db "/etc/mail/aliases.db"
    map secrets source db "/etc/mail/secrets.db"
    accept for local alias aliases deliver to mbox
    accept for all relay via tls+auth://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 has an external interface bnx0. Mail with a local destination should be sent to an external mda. First, the RSA certificate is created:

    # openssl genrsa -out /etc/mail/certs/mail.example.com.key 4096
    # openssl req -new -x509 -key /etc/mail/certs/mail.example.com.key \
    	-out /etc/mail/certs/mail.example.com.crt -days 365
    # chmod 600 /etc/mail/certs/mail.example.com.*

In the example above, a certificate valid for one year was created. The configuration file would look like this:

    listen on lo0
    listen on bnx0 tls certificate mail.example.com enable auth
    map aliases source db "/etc/mail/aliases.db"
    accept for local deliver to mda "/path/to/mda -f -"
    accept from all for domain example.org \
    	deliver to mda "/path/to/mda -f -"
    accept for all relay

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

HISTORY
smtpd(8) first appeared in OpenBSD 4.6.