SMTPD.CONF(5) BSD File Formats Manual SMTPD.CONF(5)NAMEsmtpd.conf — Simple Mail Transfer Protocol daemon configuration file
DESCRIPTIONsmtpd.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 "/usr/local/etc/mail/smtpd.conf.local"
The syntax of smtpd.conf is described below.
accept | reject
smtpd(8) accepts and rejects messages based on information gath‐
ered 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. An
exclamation mark may be specified to perform a reverse match.
Following the accept/reject decision comes the optional tag
matching:
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 filter 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 filtering 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 vir‐
tual 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 makemap(8).
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 makemap(8).
for [!] local [alias <aliases>]
This rule applies to mail destined to “localhost” and to
the default server name. See the FILES entry for
/usr/local/etc/mail/mailname below for details of how the
server name is determined.
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 filtering may be achieved on specific recipients if
desired:
recipient [!] <recipients>
If specified, the rule will only be matched if the recip‐
ient 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 speci‐
fied 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 redi‐
rected to an external address via an alias or a ~/.for‐
ward.
Example:
accept for domain opensmtpd.org forward-only
Finally, the method of delivery is specified:
deliver to lmtp [host:port | socket]
Mail is delivered to host:port, or to the UNIX socket
over LMTP.
deliver to maildir path
Mail is added to a maildir. Its location, path, may con‐
tain 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
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 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 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 refer‐
enced by source when connecting to the relay. If the ta‐
ble 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 con‐
nected to the remote server. The hostname and hostnames
parameters are mutually exclusive.
When relaying, STARTTLS is always attempted if available
on remote host and OpenSMTPD will try to present a cer‐
tificate matching the outgoing hostname if one is regis‐
tered in the pki. If pki is specified, the certificate
registered for pkiname is used instead.
If tls is specified, OpenSMTPD will refuse to relay
unless the remote host provides STARTTLS.
If the verify parameter to tls is specified, then
OpenSMTPD will refuse to relay unless the certificate
presented by the remote host has been verified.
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 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 refer‐
enced 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 con‐
nected to the remote server. The hostname and hostnames
parameters are mutually exclusive.
If verify is specified, OpenSMTPD 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 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 cafile with hostname.
ciphers cipher-list
Specify an alternate ciphers list to use when establishing TLS
sessions. It is highly recommanded 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.
curve curve-name
Specify an alternate curve for ECDHE-based cipher suites. If no
curve is specified, the default curve prime256v1 will be used.
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
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 performances.
listen on interface [family] [port port]
[tls | tls-require | tls-require verify | smtps | secure]
[pki pkiname] [auth | auth-optional [<authtable>]] [tag tag]
[hostname hostname] [hostnames <names>]
[senders <users> [masquerade]] [mask-source] [no-dsn]
[dsn-notify disable] [dsn-ret headers]
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.
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.
secure may be specified to provide both STARTTLS and SMTPS ser‐
vices. Host certificates may be used for these connections, and
must be priorly declared using the pki directive. If pki is
specified, a certificate matching name is searched for.
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 incom‐
ing mail from untrusted senders and outgoing mail from authenti‐
cated 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 parame‐
ter. When provided, credentials are looked up in this table.
Credentials format is described in table(5).
If the tag parameter is used, then clients connecting to the lis‐
tener 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.
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 lookup in a
mapping of username to email addresses if 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 no-dsn parameter is used, DSN (Delivery Status Notifica‐
tion) extension will not be enabled. If the dsn-notify parameter
is used with the disable argument, the listener will not generate
DSN upon delivery failures. If the dsn-ret parameter is used
with the headers argument, DSN will be generated without the con‐
tent of the original message.
max-message-size n
Specify a maximum message size of n bytes. The argument may con‐
tain 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.
A certificate chain may be created by appending one or many cer‐
tificates, 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 dhparams dhfile
Associate the Diffie-Hellman parameters located in dhfile with
hostname.
The parameters are used for ephemeral key exchange. If not spec‐
ified, OpenSMTPD will use safely generated builtin parameters.
Creation of Diffie-Hellman parameters is documented in
openssl(1).
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) utili‐
ties.
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.
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 fol‐
lowing:
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 dan‐
gerous characters are replaced with ‘:’. In situations where they are
desirable, the “raw” modifier may be applied. For example, with recipi‐
ent “user+t?g@example.org”:
%{rcpt} expands to “user+t:g@example.org”
%{rcpt:raw} expands to “user+t?g@example.org”
FILES
/usr/local/etc/mail/smtpd.conf Default smtpd(8) configuration file.
/usr/local/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/spool/smtpd/ Spool directories for mail during pro‐
cessing.
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 config‐
urations are given below.
This first example is the same as the default configuration, but all out‐
going mail is forwarded to a remote SMTP server. A secrets file is
needed to specify a username and password:
# touch /usr/local/etc/mail/secrets
# chmod 640 /usr/local/etc/mail/secrets
# chown root:_smtpd /usr/local/etc/mail/secrets
# echo "label username:password" > /usr/local/etc/mail/secrets
# makemap /usr/local/etc/mail/secrets
smtpd.conf would look like this:
listen on lo0
table aliases db:/usr/local/etc/mail/aliases.db
table secrets db:/usr/local/etc/mail/secrets.db
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 cer‐
tificate 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"
listen on lo0
listen on egress tls pki mail.example.com auth
table aliases db:/usr/local/etc/mail/aliases.db
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.
listen on lo0
listen on lo0 port 10028 tag DKIM
table aliases db:/usr/local/etc/mail/aliases.db
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 vol‐
ume 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.
listen on lo0
listen on egress
table aliases db:/usr/local/etc/mail/aliases.db
table other-relays "/usr/local/etc/mail/other-relays"
accept for local alias <aliases> deliver to mbox
accept for 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 ALSOmailer.conf(5), table(5), makemap(8), smtpd(8)HISTORYsmtpd(8) first appeared in OpenBSD 4.6.
BSD April 29, 2024 BSD
