SMTPD.CONF(5)             OpenBSD Programmer's 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).

SECTIONS
     smtpd.conf is divided into four main sections:

     Macros
          User-defined variables may be defined and used later, simplifying
          the configuration file.

     Global Configuration
          Global settings for smtpd(8).

     Maps
          Mail aliases, virtual domains, and authentication secrets are stored
          in maps defined in this section.

     Filter Rules
          Mail filter provides rule-based accepting, relaying, or refusing of
          messages.

     Comments can be put anywhere in the file using a hash mark (`#'), and ex-
     tend to the end of the current line.

     Additional configuration files can be included with the include keyword,
     for example:

           include "/etc/mail/smtpd.conf.local"

MACROS
     Macros can be defined that will later be expanded in context.  Macro
     names must start with a letter, and may contain letters, digits and un-
     derscores.  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

GLOBAL CONFIGURATION
     Here are the settings that can be set globally:

     hostname name
             Specify primary domain name of the server.  By default, 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.  Address or domain
             name may be used in place of interface.

             Secured connections are provided either with STARTTLS, by default
             on port 25, or SMTPS, by default on port 465.  If no certificate
             name is specified, the /etc/mail/certs directory is searched for
             a file named by joining interface name with a .crt extension, eg.
             `/etc/mail/certs/fxp0.crt'.  Creation of certificates is docu-
             mented 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" source specification will be matched.

MAPS
     Maps provide generic interface for associating textual key to a value.
     Such associations may be accessed through a flat file, database, or DNS.
     There are three maps known to smtpd:

     alias   Map queried when resolving mail aliases.  Query key is the user
             part of mail address.

     virtual
             Map used for creating virtual domains.  See the VIRTUAL DOMAINS
             section below.

     secrets
             Map queried for credentials when relaying mail via server that
             requires SMTPAUTH before accepting mail for relaying.  Query key
             is the domain name of the server acting as relay.

     The configuration directives that are valid in the map context are de-
     scribed below:

     type maptype
             Specifies method of accessing data.  The following map types are
             supported:

             db      Mappings are stored in a file created using makemap(8).
                     This is the default type if none is specified.

             dns     Not implemented yet.

             file    Not implemented yet.

     source mapsource
             Specifies the source of mapping data.  It must be absolute path
             to a file in case of ``file'' and ``db'' maptype, and a domain
             name in case of ``dns''.

FILTER RULES
     smtpd(8) has the ability to accept and reject messages based on informa-
     tion gathered during 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 client's IP address filter:

     from network
             The rule will match if connection is made from the specified
             network.  If missing, rule will apply to locally originated con-
             nections only.

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

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

     for domain domain
             This rule applies to mail destined for specified domain.  This
             parameter supports `*' wildcard, so that one can have single rule
             for all sub-domains, for example:

                   accept for domain "*.example.com" deliver to mbox

     for local
             This rule applies to mail destined to ``localhost'' and to the
             server's fully qualified domain name, as returned by hostname(1).

     for all
             Make the rule match regardless of the domain it is sent to.

     Finally, method of delivery is specified:

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

     deliver to maildir path
             Message is added to a maildir.  Its location, path, may contain
             format specifiers that are expanded before use, see the EXPANSION
             section below.  If path is not provided, then ~/Maildir is as-
             sumed.

     deliver to mda program
             Message is piped to the specified program, which is run with
             privileges of the user the message is destined to.  This parame-
             ter may use conversion specifiers that are expanded before use,
             see the EXPANSION section below.

     relay   Message is relayed.  The routing decision is based on the DNS
             system.

     relay via host [port port] [tls | smtps | ssl] [certificate name] [enable
             auth]
             Message is relayed through the specified host and port.

             Security of the communication channel may be enforced using the
             tls or smtps option.  Special keyword, ssl, means any of the two
             is acceptable: SMTPS is tried first, STARTTLS second.  If a cer-
             tificate name is specified and exists in the /etc/mail/certs di-
             rectory 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 SMTPAUTH session with host is desired, use the enable auth pa-
             rameter.

VIRTUAL DOMAINS
     Virtual domains are kept in the virtual map.  To create single virtual
     address, add ``user@example.com'' to the virtual map.  To handle all mail
     destined to any user at example.com, add ``@example.com'' to the virtual
     map.

     In addition to adding an entry to the virtual map, one must add a filter
     rule that accepts mail for the virtual domain, for example:

           accept for domain "example.com" deliver to mbox

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

FILES
     /etc/mail/smtpd.conf     Default smtpd(8) configuration file.
     /var/spool/smtpd/        Spool directories for mail during processing.

EXAMPLES
     The following example configures a machine to accept local delivery for
     both localhost and example.com, as well as the relaying of mail destined
     for example.org through the mx1.example.org server and mail destined for
     example.net through regular MX record lookup:

           listen on lo0
           accept for local deliver to mbox
           accept for domain "example.com" deliver to mbox
           accept for domain "example.org" relay via "mx1.example.org"
           accept for domain "example.net" relay

SEE ALSO
     smtpctl(8), smtpd(8)

HISTORY
     smtpd(8) first appeared in OpenBSD 4.6.

OpenBSD 4.6                      June 5, 2009                                4
