smtpd-conf(5)
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 (Sq \.) Comments can be put anywhere in the file using a hash mark (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.
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
include
keyword, for example:
- include "/etc/opensmtpd/smtpd.conf.local"
smtpd.conf
is described below.
accept | rejectsmtpd(8) accepts and rejects messages based on information gathered during the SMTP session.tagged- [
!] tag If specified, the rule will only be matched if the client session was tagged with tag. from any- Make the rule match regardless of the IP of connecting client.
from- [
!]localThe rule matches only locally originating connections. This is the default, and may be omitted. from- [
!]sourcePf < table > The rule matches if the connection is made from a client whose address is declared in the table table. sender- [
!] Pf < 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 Sq @. 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- [
!]domaindomain [alias <aliases >] This rule applies to mail destined for the specified domain. This parameter supports the Sq * wildcard, so that a single rule for all sub-domains can be used, for example: - accept for domain "*.example.com" deliver to mbox
for- [
!]domainPf < domains > [alias <aliases >] This rule applies to mail destined to domains which are part of the table domains. for- [
!]domaindomainvirtual <users > This rule applies to mail destined for the specified virtual domain. This parameter supports the Sq * 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
for- [
!]domainPf < domains >virtual <users > This rule applies to mail destined for the virtual domains specified in the table domains. for- [
!]local[alias <aliases >] This rule applies to mail destined to ``localhost'' and to the default server name. See theFILESentry for /etc/opensmtpd/mailname below for details of how the server name is determined. for- [
!]localvirtual <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. recipient- [
!] Pf < 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 Sq @. - [
userbase <table >] - Look up users in the table
table
instead of performing system lookups using the
getpwnam(3) function. forward-only- Mail is accepted for local recipients ONLY if it is redirected to an external address via an alias or a ~/.forward file.
- accept for domain opensmtpd.org forward-only
deliver to lmtp- [host: port | socket]
[
rcpt-to] [asuser] Mail is delivered to host: port, or to the Ux socket over LMTP with the privileges of the specified user. deliver to maildir [path]- Mail is added to a maildir. Its location, path, may contain format specifiers that are expanded before use (see .B 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 mdaprogram [asuser]- 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 .B FORMAT SPECIFIERS .)
- Bk -words
relay[backup [mx]] [asaddress] [source <source >] [hostnamename] [hostnames <names >] [pkipkiname] [tls [ verify]] Ekrelay via- host
[
auth <auth >] [asaddress] [source <source >] [hostnamename] [hostnames <names >] [pkipkiname] [verify] - smtp://mx1.example.org # use SMTP smtp://mx1.example.org:4321 # use SMTP \ # with port 4321 lmtp://localhost:2026 # use LMTP \ # with port 2026
- tls://mx1.example.org # use TLS smtps://mx1.example.org # use SMTPS secure://mx1.example.org # try SMTPS and \ # fallback to TLS
- 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
expire- Sm off
n
{
s| m | h | d} Sm on Specify how long a message that matched this rule can stay in the queue. bounce-warn- Sm off
n
{
s| m | h | d} [, Sm on ... ] 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
cahostnamecertificatecafile- Associate a custom CA certificate located in cafile with hostname.
cipherscipher-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.
expire- Sm off
n
{
s| m | h | d} Sm on 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
filtername filter [arguments]- Specify a filter with the given
name
and the program
filter
using the given filter
arguments.
Filters are used to hook into the SMTP dialog and provide additional filtering
options for
smtpd(8). filternamechainfilter ...- Specify a filter chain with the given name and filters.
limit session- {
max-rcpt| max-mails} num Instructsmtpd(8) to accept a maximum number of recipients or emails at once in the receiving queue. Defaults are 100 formax-mailsand 1000 formax-rcpt. limit mta- [
for domaindomain] family Instructsmtpd(8) to only use the specified address family for outgoing connections. Accepted values areinet4andinet6.If a domain is specified, the restriction only applies when connecting to MXs for this domain. limit scheduler max-inflightnum- 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 socket- [
filtername] [mask-source] br Bk -wordslisten oninterface [family] [portport] [filtername] [tls | tls-require | tls-require verify | smtps | secure] [pkipkiname] [cacaname] [auth | auth-optional [<authtable >]] [tagtag] [hostnamehostname] [hostnames <names >] [senders <users >[masquerade]] [mask-source] [received-auth] [no-dsn] Ek max-message-sizen- 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. pkihostnamecertificatecertfile- Associate the certificate located in certfile with hostname.
pkihostnamekeykeyfile- Associate the key located in keyfile with hostname.
pkihostnamedheparams- 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) orgzcat(1) utilities. queue encryption [keykey]- 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
tablename [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 totable(5) for the exhaustive documentation. - 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. tablename {value [, ...]}- Tables containing list of static values may be declared using an inlined notation.
tablename {key=value [, ...]}- Tables containing static key-value mappings may be declared using an inlined notation.
table(5).
table(5).
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.
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
Sq @,
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.
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
Sq @,
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
Pf < 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.
socket
or an
interface
to listen on for incoming connections.
The
listen on socket
directive is used to modify the behavior of the listener handling
messages submitted through the local enqueuer, for example via the
mail(1)
utility.
This is an optional directive: if unspecified then
smtpd(8)
will simply listen for connections on the
socket
as if it was configured with no option.
Clients connecting through the
socket
will always be tagged with the 'local'
tag.
To listen on a specific network interface, specify an
interface
and an optional
port.
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.
A
filter
may be specified to use a filter or filter chain with the given
name
on SMTP transactions.
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 services.
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.
starttls(8).
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.
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} Ta sender email address
- %{sender.user} Ta user part of the sender email address
- %{sender.domain} Ta domain part of the sender email address
- %{rcpt} Ta recipient email address
- %{rcpt.user} Ta user part of the recipient email address
- %{rcpt.domain} Ta domain part of the recipient email address
- %{dest} Ta recipient email address after expansion
- %{dest.user} Ta user part after expansion
- %{dest.domain} Ta domain part after expansion
- %{user.username} Ta local user
- %{user.directory} Ta 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]} Ta expands to “e”
- %{rcpt.domain[1]} Ta expands to “x”
- %{rcpt.domain[8:]} Ta expands to “org”
- %{rcpt.domain[-3:]} Ta expands to “org”
- %{rcpt.domain[0:6]} Ta expands to “example”
- %{rcpt.domain[0:-4]} Ta expands to “example”
In addition, modifiers may be applied to the token. For example, with recipient “User+Tag [at] Example.org :”
- %{rcpt:lowercase} Ta expands to “user+tag [at] example.org”
- %{rcpt:uppercase} Ta expands to “USER+TAG [at] EXAMPLE.ORG”
- %{rcpt:strip} Ta expands to “User [at] Example.org”
- %{rcpt:lowercase|strip} Ta expands to “user [at] example.org”
For security concerns, expanded values are sanitized and potentially dangerous characters are replaced with Sq :. In situations where they are desirable, the “raw” modifier may be applied. For example, with recipient “user+t?g@example.org :”
- %{rcpt} Ta expands to “user+t:g@example.org”
- %{rcpt:raw} Ta expands to “user+t?g@example.org”
Files
/etc/opensmtpd/smtpd.conf- Default
smtpd(8) configuration file. /etc/opensmtpd/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 throughgetaddrinfo(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/opensmtpd/secrets # chmod 640 /etc/opensmtpd/secrets # chown root:_smtpd /etc/opensmtpd/secrets # echo "label username:password" > /etc/opensmtpd/secrets
smtpd.conf
would look like this:
- table aliases file:/etc/opensmtpd/aliases table secrets file:/etc/opensmtpd/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>
- # 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
- 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/opensmtpd/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
- table aliases file:/etc/opensmtpd/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
- table aliases file:/etc/opensmtpd/aliases table other-relays file:/etc/opensmtpd/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.