path: root/usr.sbin/smtpd/smtpd.conf.5

.\"	$OpenBSD: smtpd.conf.5,v 1.161 2016/05/19 08:21:23 gilles Exp $
.\"
.\" Copyright (c) 2008 Janne Johansson <jj@openbsd.org>
.\" Copyright (c) 2009 Jacek Masiulaniec <jacekm@dobremiasto.net>
.\" Copyright (c) 2012 Gilles Chehade <gilles@poolp.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\"
.Dd $Mdocdate: May 19 2016 $
.Dt SMTPD.CONF 5
.Os
.Sh NAME
.Nm smtpd.conf
.Nd Simple Mail Transfer Protocol daemon configuration file
.Sh DESCRIPTION
.Nm
is the configuration file for the mail daemon
.Xr smtpd 8 .
.Pp
The current line can be extended over multiple lines using a backslash
.Pq Sq \e .
Comments can be put anywhere in the file using a hash mark
.Pq Sq # ,
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.
.Pp
Argument names not beginning with a letter, digit, or underscore
must be quoted.
Arguments containing whitespace should be surrounded by double quotes
.Pq \&" .
.Pp
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
.Ar listen ,
.Ar accept ,
.Ar port ) .
Macros are not expanded inside quotes.
.Pp
For example:
.Bd -literal -offset indent
lan_addr = "192.168.0.1"
listen on $lan_addr
listen on $lan_addr tls auth
.Ed
.Pp
Additional configuration files can be included with the
.Ic include
keyword, for example:
.Bd -literal -offset indent
include "/etc/mail/smtpd.conf.local"
.Ed
.Pp
The syntax of
.Nm
is described below.
.Bl -tag -width Ds
.It Ic accept | reject
.Xr smtpd 8
accepts and rejects messages
based on information gathered during the SMTP session.
.Pp
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.
.Pp
Following the accept/reject
decision comes the optional tag matching:
.Bl -tag -width Ds
.It Xo
.Ic tagged
.Op Ic \&!
.Ar tag
.Xc
If specified, the rule will only be matched if the client session was tagged with
.Ar tag .
.El
.Pp
After that the client's IP address rule is specified:
.Bl -tag -width Ds
.It Ic from any
Make the rule match regardless of the IP of connecting client.
.It Xo
.Ic from
.Op Ic \&!
.Ic local
.Xc
The rule matches only locally originating connections.
This is the default,
and may be omitted.
.It Xo
.Ic from
.Op Ic \&!
.Ic source
.Pf < Ar table Ns >
.Xc
The rule matches if the connection is made from a client whose address
is declared in the table
.Ar table .
.El
.Pp
In addition, finer access control may be achieved on the sender if desired:
.Bl -tag -width Ds
.It Xo
.Ic sender
.Op Ic \&!
.Pf < Ar senders Ns >
.Xc
If specified, the rule will only be matched if the sender email address
is found in the table
.Ar senders .
The table may contain complete email addresses or apply to an entire
domain if prefixed with
.Sq @ .
.El
.Pp
Next comes the selection based on the domain the message is sent to:
.Bl -tag -width Ds
.It Ic for any Op Ic alias No < Ns Ar aliases Ns >
Make the rule match regardless of the domain it is sent to.
If specified, the table
.Ar aliases
is used for looking up alternative destinations for all addresses.
.It Ic for any virtual No < Ns Ar vmap Ns >
Make the rule match regardless of the domain it is sent to.
The
.Ar vmap
table will be used as the virtual domain mapping.
.It Xo
.Ic for
.Op Ic \&!
.Ic domain
.Ar domain
.Op Ic alias No < Ns Ar aliases Ns >
.Xc
This rule applies to mail destined for the specified
.Ar domain .
This parameter supports the
.Sq *
wildcard,
so that a single rule for all sub-domains can be used, for example:
.Bd -literal -offset indent
accept for domain "*.example.com" deliver to mbox
.Ed
.Pp
If specified, the table
.Ar aliases
is used for looking up alternative destinations for addresses in this
.Ar domain .
.It Xo
.Ic for
.Op Ic \&!
.Ic domain
.Pf < Ar domains Ns >
.Op Ic alias No < Ns Ar aliases Ns >
.Xc
This rule applies to mail destined to domains which are part of the table
.Ar domains .
.Pp
If specified, the table
.Ar aliases
is used for looking up alternative destinations for addresses in these
.Ar domains .
.It Xo
.Ic for
.Op Ic \&!
.Ic domain
.Ar domain
.Ic virtual No < Ns Ar users Ns >
.Xc
This rule applies to mail destined for the specified virtual
.Ar domain .
This parameter supports the
.Sq *
wildcard,
so that a single rule for all sub-domains can be used, for example:
.Bd -literal -offset indent
accept for domain "*.example.com" \e
       virtual <users> deliver to mbox
.Ed
.Pp
The table
.Ar users
holds a key-value mapping of virtual to system users.
For an example of how to configure the
.Ar users
table, see
.Xr table 5 .
.It Xo
.Ic for
.Op Ic \&!
.Ic domain
.Pf < Ar domains Ns > Ic virtual No < Ns Ar users Ns >
.Xc
This rule applies to mail destined for the virtual domains specified
in the table
.Ar domains .
.Pp
The table
.Ar users
holds a key-value mapping of virtual to system users.
For an example of how to configure the
.Ar users
table, see
.Xr table 5 .
.It Xo
.Ic for
.Op Ic \&!
.Ic local
.Op Ic alias No < Ns Ar aliases Ns >
.Xc
This rule applies to mail destined to
.Dq localhost
and to the default server name.
See the
.Sx FILES
entry for
.Pa /etc/mail/mailname
below for details of how the server name is determined.
.It Xo
.Ic for
.Op Ic \&!
.Ic local
.Ic virtual No < Ns Ar vmap Ns >
.Xc
This rule applies to mail destined to
.Dq localhost
and to the default server name.
The
.Ar vmap
table will be used as the virtual domain mapping.
.El
.Pp
Further access control may be achieved on specific recipients if desired:
.Bl -tag -width Ds
.It Xo
.Ic recipient
.Op Ic \&!
.Pf < Ar recipients Ns >
.Xc
If specified, the rule will only be matched if the recipient email address
is found in the table
.Ar recipients .
The table may contain complete email addresses or apply to an entire
domain if prefixed with
.Sq @ .
.El
.Pp
If the method of delivery is local, a user database may be
specified to override the system database:
.Bl -tag -width Ds
.It Op Ic userbase No < Ns Ar table Ns >
Look up users in the table
.Ar table
instead of performing system lookups using the
.Xr getpwnam 3
function.
.El
.Pp
You can also accept mail just to have it forwarded elsewhere:
.Bl -tag -width Ds
.It Ic forward-only
Mail is accepted for local recipients ONLY if it is redirected to an
external address via an alias or a ~/.forward file.
.Pp
Example:
.Bd -literal -offset indent
accept for domain opensmtpd.org forward-only
.Ed
.El
.Pp
Finally, the method of delivery is specified:
.Bl -tag -width Ds
.It Xo
.Ic deliver to lmtp
.Op Ar host : Ns Ar port | socket
.Op Ic rcpt-to
.Op Ic as Ar user
.Xc
Mail is delivered to
.Ar host : Ns Ar port ,
or to the
.Ux
.Ar socket
over LMTP with the privileges of the specified
.Ar user .
.Pp
Optionally,
.Ic 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.
.It Ic deliver to maildir Op Ar path
Mail is added to a maildir.
Its location,
.Ar path ,
may contain format specifiers that are expanded before use
.Pq see Sx FORMAT SPECIFIERS .
If
.Ar path
is not provided, then
.Pa ~/Maildir
is assumed.
.It Ic deliver to mbox
Mail is delivered to the local user's system mailbox in
.Pa /var/mail .
.It Ic deliver to mda Ar program Op Ic as Ar user
Mail is piped to the specified
.Ar program ,
which is run with the privileges of the specified
.Ar user
or the user the message is destined to.
This parameter may use conversion specifiers that are expanded before use
.Pq see Sx FORMAT SPECIFIERS .
.It Xo
.Bk -words
.Ic relay
.Op Ic backup Op Ar mx
.Op Ic as Ar address
.Op Ic source No < Ns Ar source Ns >
.Op Ic hostname Ar name
.Op Ic hostnames No < Ns Ar names Ns >
.Op Ic pki Ar pkiname
.Op Ic tls Op Ic verify
.Ek
.Xc
.Pp
Mail is relayed.
The routing decision is based on the DNS system.
.Pp
If the
.Ic 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
.Ar mx .
If
.Ar mx
is not specified, the default server name will be assumed.
.Pp
If the
.Ic as
parameter is specified,
.Xr smtpd 8
will rewrite the sender advertised
in the SMTP session.
.Ar address
may be a user, a domain prefixed with
.Sq @ ,
or an email address, causing
.Xr smtpd 8
to rewrite the user-part, the domain-part, or the entire address, respectively.
.Pp
If the
.Ic source
parameter is specified,
.Xr smtpd 8
will explicitly bind to an address found in the table referenced by
.Ar 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.
.Pp
By default, when connecting to a remote server,
.Xr smtpd 8
advertises its default server name.
A
.Ic hostname
parameter may be specified to advertise the alternate hostname
.Ar name .
If the
.Ic source
parameter is used, the
.Ic hostnames
parameter may be specified to advertise a hostname based on
the source address.
Table
.Ar names
contains a mapping of IP addresses to hostnames and
.Xr smtpd 8
will automatically select the name that matches its source address
when connected to the remote server.
The
.Ic hostname
and
.Ic hostnames
parameters are mutually exclusive.
.Pp
When relaying, STARTTLS is always attempted if available on remote host and
.Xr smtpd 8
will try to present a certificate matching the outgoing hostname if one is
registered in the pki.
If
.Ic pki
is specified, the certificate registered for
.Ar pkiname
is used instead.
.Pp
If
.Ic tls
is specified,
.Xr smtpd 8
will refuse to relay unless the remote host provides STARTTLS.
If
.Ic tls verify
is specified,
.Xr smtpd 8
will refuse to relay unless the remote host provides STARTTLS and the
certificate it presented has been verified.
.Pp
Note that the
.Ic tls
and
.Ic tls verify
options should only be used in private networks
as they will prevent proper relaying on the Internet.
.It Xo
.Ic relay via
.Ar host
.Op Ic auth No < Ns Ar auth Ns >
.Op Ic as Ar address
.Op Ic source No < Ns Ar source Ns >
.Op Ic hostname Ar name
.Op Ic hostnames No < Ns Ar names Ns >
.Op Ic pki Ar pkiname
.Op Ic verify
.Xc
.Pp
Mail is relayed through the specified
.Ar host
expressed as a URL.
For example:
.Bd -literal -offset indent
smtp://mx1.example.org		# use SMTP
smtp://mx1.example.org:4321	# use SMTP \e
				# with port 4321
lmtp://localhost:2026		# use LMTP \e
				# with port 2026
.Ed
.Pp
The communication channel may be secured using one of the secure
schemas.
For example:
.Bd -literal -offset indent
tls://mx1.example.org		# use TLS
smtps://mx1.example.org		# use SMTPS
secure://mx1.example.org	# try SMTPS and \e
				# fallback to TLS
.Ed
.Pp
In addition, credentials for authenticated relaying may be provided
when using a secure schema.
For example:
.Bd -literal -offset indent
tls+auth://label@mx.example.org	    # over TLS
smtps+auth://label@mx.example.org   # over SMTPS
secure+auth://label@mx.example.org  # over either \e
				    # SMTPS or TLS
.Ed
.Pp
If a pki entry exists for the outgoing hostname, or one is provided
with
.Ar pkiname ,
the associated certificate will be sent to the remote server.
.Pp
If an SMTPAUTH session with
.Ar host
is desired, the
.Ic auth
parameter is used to specify the
.Ar auth
table that holds the credentials.
Credentials will be looked up using the label provided in the URL.
.Pp
If the
.Ic as
parameter is specified,
.Xr smtpd 8
will rewrite the sender advertised
in the SMTP session.
.Ar address
may be a user, a domain prefixed with
.Sq @ ,
or an email address, causing
.Xr smtpd 8
to rewrite the user-part, the domain-part, or the entire address, respectively.
.Pp
If the
.Ic source
parameter is specified,
.Xr smtpd 8
will explicitly bind to an address found in the table referenced by
.Pf < Ar source Ns >
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.
.Pp
By default, when connecting to a remote server,
.Xr smtpd 8
advertises its default server name.
A
.Ic hostname
parameter may be specified to advertise the alternate hostname
.Ar name .
If the
.Ic source
parameter is used, the
.Ic hostnames
parameter may be specified to advertise a hostname based on
the source address.
Table
.Ar names
contains a mapping of IP addresses to hostnames and
.Xr smtpd 8
will automatically select the name that matches its source address
when connected to the remote server.
The
.Ic hostname
and
.Ic hostnames
parameters are mutually exclusive.
.Pp
If
.Ic verify
is specified,
.Xr 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.
.El
.Pp
Additional per-rule adjustments are available:
.Bl -tag -width Ds
.It Xo
.Ic expire
.Sm off
.Ar n
.Brq Cm s | m | h | d
.Sm on
.Xc
Specify how long a message that matched this rule can stay in the queue.
.El
.It Xo
.Ic bounce-warn
.Sm off
.Ar n
.Brq Cm s | m | h | d
.Oo ,
.Sm on
.Ar ...
.Oc
.Xc
Specify the delays for which temporary failure reports must be generated
when messages are stuck in the queue.
For example:
.Bd -literal -offset indent
bounce-warn	1h, 6h, 2d
.Ed
.Pp
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.
.It Ic ca Ar hostname Ic certificate Ar cafile
Associate a custom CA certificate located in
.Ar cafile
with
.Ar hostname .
.It Ic ciphers Ar 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.
.Pp
When not specified, only ciphers considered safe are chosen.
.It Xo
.Ic expire
.Sm off
.Ar n
.Brq Cm s | m | h | d
.Sm on
.Xc
Specify how long a message can stay in the queue.
The default value is 4d.
For example:
.Bd -literal -offset indent
expire 4d	# expire after 4 days
expire 10h	# expire after 10 hours
.Ed
.It Ic filter Ar name filter Op Ar arguments
Specify a filter with the given
.Ar name
and the program
.Ar filter
using the given filter
.Ar arguments .
Filters are used to hook into the SMTP dialog and provide additional filtering
options for
.Xr smtpd 8 .
.It Ic filter Ar name Ic chain Ar filter Ar ...
Specify a filter chain with the given
.Ar name
and filters.
.It Xo
.Ic limit session
.Brq Cm max-rcpt | max-mails
.Ar num
.Xc
Instruct
.Xr smtpd 8
to accept a maximum number of recipients or emails at once
in the receiving queue.
Defaults are 100 for
.Ic max-mails
and 1000 for
.Ic max-rcpt .
.It Xo
.Ic limit mta
.Op Ic for Ic domain Ar domain
.Ar family
.Xc
Instruct
.Xr smtpd 8
to only use the specified address
.Ar family
for outgoing connections.
Accepted values are
.Ic inet4
and
.Ic inet6 .
If a
.Ar domain
is specified, the restriction only applies when connecting
to MXs for this domain.
.It Ic limit scheduler max-inflight Ar num
Suspend the scheduling of envelopes for deliver/relay until the number
of inflight envelopes falls below
.Ar num .
Changing the default value might degrade performance.
.It Xo
.Ic listen on socket
.Op Ic filter Ar name
.Op Ic mask-source
.br
.Bk -words
.Ic listen on Ar interface
.Op Ar family
.Op Ic port Ar port
.Op Ic filter Ar name
.Op Ic tls | tls-require | tls-require verify | smtps | secure
.Op Ic pki Ar pkiname
.Op Ic ca Ar caname
.Op Ic auth | auth-optional Op < Ns Ar authtable Ns >
.Op Ic tag Ar tag
.Op Ic hostname Ar hostname
.Op Ic hostnames No < Ns Ar names Ns >
.Op Ic senders No < Ns Ar users Ns > Op masquerade
.Op Ic mask-source
.Op Ic received-auth
.Op Ic no-dsn
.Ek
.Xc
.Pp
Specify a
.Ic socket
or an
.Ar interface
to listen on for incoming connections.
The
.Ic listen on socket
directive is used to modify the behavior of the listener handling
messages submitted through the local enqueuer, for example via the
.Xr mail 1
utility.
This is an optional directive: if unspecified then
.Xr smtpd 8
will simply listen for connections on the
.Ic socket
as if it was configured with no option.
Clients connecting through the
.Ic socket
will always be tagged with the 'local'
.Ic tag .
.Pp
To listen on a specific network interface, specify an
.Ar interface
and an optional
.Ar port .
An interface group, an IP address or a domain name may
be used in place of
.Ar interface .
The
.Ar family
parameter can be used to listen only on specific address family.
Accepted values are
.Ic inet4
and
.Ic inet6 .
.Pp
A
.Ic filter
may be specified to use a filter or filter chain with the given
.Ar name
on SMTP transactions.
.Pp
Secured connections are provided either using STARTTLS
.Pq Ic tls ,
by default on port 25,
or SMTPS
.Pq Ic smtps ,
by default on port 465.
.Ic tls-require
may be used to force clients to establish a secure connection
before being allowed to start an SMTP transaction.
.Pp
If
.Ic tls-require verify
is specified, the client must provide a valid certificate to be
able to establish an SMTP session.
.Pp
.Ic secure
may be specified to provide both STARTTLS and SMTPS services.
Host certificates may be used for these connections,
and must be previously declared using the pki directive.
If
.Ic pki
is specified,
a certificate matching
.Ic name
is searched for.
Moreover, a previously declared
.Ic ca
directive may be specified to use a custom CA certificate.
.Pp
If the
.Ic 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
.Ic from local
will be matched.
If
.Ic 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.
.Pp
Both
.Ic auth
and
.Ic auth-optional
accept an optional table as a parameter.
When provided, credentials are looked up in this table.
The credentials format is described in
.Xr table 5 .
.Pp
If the
.Ic tag
parameter is used, then clients connecting to the listener will be
tagged
.Ar tag .
.Pp
If the
.Ic hostname
parameter is used, then it will be used in the greeting banner
instead of the default server name.
.Pp
The
.Ic hostnames
parameter overrides the server name for specific addresses.
Table
.Ar names
contains a mapping of IP addresses to hostnames and
.Xr smtpd 8
will use the hostname that matches the address on which the connection arrives
if it is found in the mapping.
.Pp
If the
.Ic senders
parameter is used, then
.Xr 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.
.Pp
If the
.Ic mask-source
parameter is used, then the listener will skip the
.Ic from
part when prepending the
.Dq Received
header.
.Pp
If the
.Ic received-auth
parameter is used, the
.Dq Received
header will display if the session was authenticated and by which local user.
.Pp
If the
.Ic no-dsn
parameter is used, DSN (Delivery Status Notification) extension will not
be enabled.
.It Ic max-message-size Ar n
Specify a maximum message size of
.Ar n
bytes.
The argument may contain a multiplier, as documented in
.Xr scan_scaled 3 .
The default maximum message size is 35MB if none is specified.
.It Ic pki Ar hostname Ic certificate Ar certfile
Associate the certificate located in
.Ar certfile
with
.Ar hostname .
.Pp
If a fallback certificate or SNI is wanted, the
.Sq *
wildcard may be used as
.Ar hostname .
.Pp
A certificate chain may be created by appending one or many certificates,
including a Certificate Authority certificate,
to
.Ar certfile .
.Pp
Creation of certificates is documented in
.Xr starttls 8 .
.It Ic pki Ar hostname Ic key Ar keyfile
Associate the key located in
.Ar keyfile
with
.Ar hostname .
.It Ic pki Ar hostname Ic dhe Ar params
Specify the DHE parameters to use for DHE cipher suites with
.Ar 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.
.It Ic 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
.Xr smtpctl 8
or
.Xr gzcat 1
utilities.
.It Ic queue encryption Op key Ar key
Enable transparent encryption of envelopes and messages.
.Ar key
must be a 16-byte random key in hexadecimal representation.
It can be obtained using the
.Xr openssl 1
utility as follow:
.Bd -literal -offset indent
$ openssl rand \-hex 16
.Ed
.Pp
If the
.Ar key
parameter is not specified, it is read with
.Xr getpass 3
at startup.
If
.Ar key
is
.Ic stdin ,
then it is read from the standard input at startup.
.Pp
The only supported algorithm is AES-256 in GCM mode.
Envelopes and messages may be inspected using the
.Xr smtpctl 8
utility.
.Pp
Queue encryption can be used with queue compression and will always
perform compression before encryption.
.It Ic table Ar name Oo Ar type : Oc Ns Ar config
Tables are used to provide additional configuration information for
.Xr 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
.Xr table 5
for the exhaustive documentation.
.Pp
The table is identified using table name
.Ar name ;
the name itself is arbitrarily chosen.
.Pp
.Ar type
specifies the table backend,
and should be one of the following:
.Pp
.Bl -tag -width "fileXXX" -compact
.It db
Information is stored in a file created using
.Xr makemap 8 .
.It file
Information is stored in a plain text file using the
same format as used to generate
.Xr makemap 8
mappings.
This is the default.
.El
.Pp
.Ar config
specifies a configuration file for the table data.
It must be an absolute path to a file for the
.Dq file
and
.Dq db
table types.
.It Ic table Ar name Brq Ar value Op , Ar ...
Tables containing list of static values may be declared
using an inlined notation.
.Pp
The table is identified using table name
.Ar name ;
the name itself is arbitrarily chosen.
.Pp
The table must contain at least one value and may declare many values as a
list of comma-separated strings.
.It Ic table Ar name Brq Ar key Ns = Ns Ar value Op , Ar ...
Tables containing static key-value mappings may be declared
using an inlined notation.
.Pp
The table is identified using table name
.Ar name ;
the name itself is arbitrarily chosen.
.Pp
The table must contain at least one key-value mapping and may declare
many mappings as a list of comma-separated
.Ar key Ns = Ns Ar value
descriptions.
.El
.Ss FORMAT SPECIFIERS
Some configuration directives support expansion of their parameters at runtime.
Such directives (for example
.Ic deliver to maildir ,
.Ic deliver to mda )
may use format specifiers which will be expanded before delivery or
relaying.
The following formats are currently supported:
.Bl -column %{user.directory} -offset indent
.It %{sender}         Ta sender email address
.It %{sender.user}    Ta user part of the sender email address
.It %{sender.domain}  Ta domain part of the sender email address
.It %{rcpt}           Ta recipient email address
.It %{rcpt.user}      Ta user part of the recipient email address
.It %{rcpt.domain}    Ta domain part of the recipient email address
.It %{dest}           Ta recipient email address after expansion
.It %{dest.user}      Ta user part after expansion
.It %{dest.domain}    Ta domain part after expansion
.It %{user.username}  Ta local user
.It %{user.directory} Ta home directory of the local user
.El
.Pp
Expansion formats also support partial expansion using the optional
bracket notations with substring offset.
For example, with recipient domain
.Dq example.org :
.Bl -column %{rcpt.domain[0:-4]} -offset indent
.It %{rcpt.domain[0]}    Ta expands to Dq e
.It %{rcpt.domain[1]}    Ta expands to Dq x
.It %{rcpt.domain[8:]}   Ta expands to Dq org
.It %{rcpt.domain[-3:]}  Ta expands to Dq org
.It %{rcpt.domain[0:6]}  Ta expands to Dq example
.It %{rcpt.domain[0:-4]} Ta expands to Dq example
.El
.Pp
In addition, modifiers may be applied to the token.
For example, with recipient
.Dq User+Tag@Example.org :
.Bl -column %{rcpt:lowercase|strip} -offset indent
.It %{rcpt:lowercase}       Ta expands to Dq user+tag@example.org
.It %{rcpt:uppercase}       Ta expands to Dq USER+TAG@EXAMPLE.ORG
.It %{rcpt:strip}           Ta expands to Dq User@Example.org
.It %{rcpt:lowercase|strip} Ta expands to Dq user@example.org
.El
.Pp
For security concerns, expanded values are sanitized and potentially
dangerous characters are replaced with
.Sq \&: .
In situations where they are desirable, the
.Dq raw
modifier may be applied.
For example, with recipient
.Dq user+t?g@example.org :
.Bl -column %{rcpt:raw} -offset indent
.It %{rcpt}     Ta expands to Dq user+t:g@example.org
.It %{rcpt:raw} Ta expands to Dq user+t?g@example.org
.El
.Sh FILES
.Bl -tag -width "/etc/mail/smtpd.confXXX" -compact
.It Pa /etc/mail/smtpd.conf
Default
.Xr smtpd 8
configuration file.
.It Pa /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
.Xr gethostname 3 ,
either directly if it is a fully qualified domain name,
or by retrieving the associated canonical name through
.Xr getaddrinfo 3 .
.It Pa /var/spool/smtpd/
Spool directories for mail during processing.
.El
.Sh EXAMPLES
The default
.Nm
file which ships with
.Ox
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.
.Pp
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:
.Bd -literal -offset indent
# touch /etc/mail/secrets
# chmod 640 /etc/mail/secrets
# chown root:_smtpd /etc/mail/secrets
# echo "label username:password" > /etc/mail/secrets
.Ed
.Pp
.Nm
would look like this:
.Bd -literal -offset indent
table aliases file:/etc/mail/aliases
table secrets file:/etc/mail/secrets

listen on lo0

accept for local alias <aliases> deliver to mbox
accept for any relay via tls+auth://label@smtp.example.com \e
	auth <secrets>
.Ed
.Pp
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:
.Bd -literal -offset indent
# openssl genrsa \-out /etc/ssl/private/mail.example.com.key 4096
# openssl req \-new \-x509 \-key /etc/ssl/private/mail.example.com.key \e
	\-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
.Ed
.Pp
In the example above,
a certificate valid for one year was created.
The configuration file would look like this:
.Bd -literal -offset indent
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/mail/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 \e
	deliver to mda "/path/to/mda \-f \-"
accept for any relay
.Ed
.Pp
For sites that wish to sign messages using DKIM, the
.Em 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.
.Bd -literal -offset indent
table aliases file:/etc/mail/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
.Ed
.Pp
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
.Em other-relays
can be used to specify the IP addresses of relays that may legitimately
originate mail with your domain as the sender.
.Bd -literal -offset indent
table aliases file:/etc/mail/aliases
table other-relays file:/etc/mail/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 \e
	alias <aliases> deliver to mbox
.Ed
.Sh SEE ALSO
.Xr mailer.conf 5 ,
.Xr table 5 ,
.Xr makemap 8 ,
.Xr smtpd 8
.Sh HISTORY
.Xr smtpd 8
first appeared in
.Ox 4.6 .