| SMTPD.CONF(5) | File Formats Manual | SMTPD.CONF(5) |
smtpd.conf —
Simple Mail Transfer Protocol daemon configuration
file
smtpd.conf is the configuration file for
the mail daemon smtpd(8).
When mail arrives, each “RCPT TO:” command generates
a mail envelope. If an envelope matches any of a pre-designated set of
criteria (using the match directive), the message is
accepted for delivery. A copy of the message, as well as its associated
envelopes, is saved in the mail queue and later dispatched according to an
associated set of actions (using the action
directive). If an envelope does not match any options, it is rejected. The
match rules are evaluated sequentially, with the first match winning.
The format of the configuration file is fairly flexible. 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, as well as reserved words (such as
listen, match, and
port), must be quoted. Arguments containing
whitespace should be surrounded by double quotes (").
Macros can be defined that are later expanded in context. Macro names must start with a letter, digit, or underscore, and may contain any of those characters, but may not be reserved words. Macros are not expanded inside quotes. For example:
lan_addr = "192.168.0.1" listen on $lan_addr listen on $lan_addr tls auth
The syntax of smtpd.conf is described
below.
action
name method [options]action name,
selected by the match ...
action directive when the message was received.
The action directive provides configuration data
for delivery attempts. Required lookups are performed at the time of each
delivery attempt. Consequently, changing an action
directive or the files it references and restarting the
smtpd(8) daemon causes the changes to take effect for
subsequent delivery attempts for the respective dispatcher
name, even for messages that were already stuck in
the queue prior to the configuration changes.
The delivery method parameter may be one of the following:
expand-onlyforward-onlylmtp
destination [rcpt-to]Optionally, 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.
maildir
[pathname [junk]]The pathname may contain format specifiers that are expanded before use (see FORMAT SPECIFIERS).
If the junk argument is provided,
the message will be moved to the
‘Junk’ folder if it contains a
positive ‘X-Spam’ header. This
folder will be created under pathname if it
does not yet exist.
mboxmda
commandThe command may contain format specifiers that are expanded before use (see FORMAT SPECIFIERS).
relayThe local delivery methods support additional options:
alias
<table>ttl
n{s|m|h|d}user
usernameThis is used for virtual hosting where a single username is in charge of handling delivery for all virtual users.
This option is not usable with the
mbox delivery method.
userbase
<table>The userbase does not apply for
the user option.
virtual
<table>wrapper
namemda wrapper.The relay delivery methods also support additional options:
backupbackup
mx namehelo
helonamehelo-src
<table>domain
<domains>host
relay-urlThe label corresponds to an entry in a credentials table, as documented in table(5). It is used with the “smtp+tls” and “smtps” protocols for authentication. Server certificates for those protocols are verified by default.
pki
pkinamepki directive) to prove the client's identity
to the remote mail server.srstls
[no-verify]no-verify is
specified, do not require a valid certificate.auth
<table>host option. The credential
table format is described in table(5).mail-from
mailaddrsrc
sourceaddr |
<sourceaddr>admd
authservidbounce
warn-interval delay [,
delay ...]s, m,
h, or d. At most four
delay parameters can be specified. The default is
"bounce warn-interval
4h", sending a single warning after four
hours.ca
caname cert
cafilehostname directive.filter
chain-name chain
{filter-name [, ...]}filter
filter-name phase
phase-name match
conditions decisionfilter
filter-name proc
proc-namefilter
filter-name proc-exec
commandinclude
"pathname"listen
on interface [family]
[options]inet4 or inet6.
The options are as follows:
auth
[<authtable>]auth-optional
[<authtable>]listen on directive to both
accept incoming mail from untrusted senders and permit outgoing mail
from authenticated users (using match auth).
It can be used in situations where it is not possible to listen on a
separate port (usually the submission port, 587) for users to
authenticate.ca
canameca
directive) as the CA certificate when verifying client
certificates.filter
namehostname
hostnamehostnames
<names>mask-srcno-dsnpki
pkinamepki directive) to prove a mail server's
identity.port
[port]proxy-v2received-authsenders
<users>
[masquerade]masquerade
option is provided, the From header is rewritten to match the sender
provided in the SMTP session.smtpstls.tag
tagtlssmtps.tls-require
[verify]tls, but force clients to establish a
secure connection before being allowed to start an SMTP transaction.
With the verify option, clients must also
provide a valid certificate to establish an SMTP session.listen
on socket
[options]The options are as follows:
match
options action
namematch action
directive, receive the incoming message, put a copy into each matching
envelope, and atomically save the envelopes to the mail spool for later
processing by the respective dispatcher name.
The following matching options are supported and can all be negated:
!] for any!] for local!] for domain
domain | <domain>!] for domain regex
domain | <domain>!] for rcpt-to
recipient |
<recipient>!] for rcpt-to regex
recipient |
<recipient>!] from any!] from auth!] from auth
user | <user>!] from auth regex
user | <user>!] from local!] from mail-from
sender | <sender>!] from mail-from
regex sender |
<sender>!] from rdns!] from rdns
hostname |
<hostname>!] from rdns regex
hostname |
<hostname>!] from socket!] from src
address |
<address>!] from src regex
address |
<address>In addition, the following transaction options:
!] auth!] auth
username |
<username>!] auth regex
username |
<username>!] helo
helo-name |
<helo-name>!] helo regex
helo-name |
<helo-name>!] mail-from
sender | <sender>!] mail-from regex
sender | <sender>!] rcpt-to
recipient |
<recipient>!] rcpt-to regex
recipient |
<recipient>!] tag
tag!] tag regex
tag!] tlsmatch
options rejectmatch action
directive.mda
wrapper name commandmta
max-deferred numberpki
pkiname cert
certfilehostname directive. If a fallback certificate or
SNI is wanted, the ‘*’ wildcard may be used as
pkiname.
A certificate chain may be created by appending one or many certificates, including a Certificate Authority certificate, to certfile. The creation of certificates is documented in starttls(8).
pki
pkiname key
keyfilepki
pkiname dhe
paramsnone, 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.proc
proc-name commandqueue
compressionqueue
encryption [key]stdin
or a single dash (‘-’) is given
instead of a key, the key is read from the standard
input.queue
ttl delays, m,
h, or d. The default is
four days (4d).smtp
ciphers controlsmtp limit max-mails
countsmtp limit max-rcpt
countsmtp
max-message-size sizesmtp
sub-addr-delim character+’.srs
key secretsrs
key backup secretsrs
ttl delaytable
name
[type:]pathnameEach table is identified by an arbitrary, unique name.
If the type is
db, information is stored in a file created with
makemap(8); if it is file or
omitted, information is stored in a plain text file using the format
described in table(5). The
pathname to the file must be absolute.
table
name {value [,
...]}table
name
{key=value [,
...]}In a regular workflow, smtpd(8) may accept or reject a message based only on the content of envelopes. Its decisions are about the handling of the message, not about the handling of an active session.
Filtering extends the decision making process by allowing smtpd(8) to stop at each phase of an SMTP session, check that conditions are met, then decide if a session is allowed to move forward.
With filtering, a session may be interrupted at any phase before an envelope is complete. A message may also be rejected after being submitted, regardless of whether the envelope was accepted or not.
The following phases are currently supported:
| connect | upon connection, before a banner is displayed |
| helo | after HELO command is submitted |
| ehlo | after EHLO command is submitted |
| mail-from | after MAIL FROM command is submitted |
| rcpt-to | after RCPT TO command is submitted |
| data | after DATA command is submitted |
| commit | after message is fully is submitted |
At each phase, various conditions may be matched. The fcrdns, rdns, and src data are available in all phases, but other data must have been already submitted before they are available.
| fcrdns | forward-confirmed reverse DNS is valid |
| rdns | session has a reverse DNS |
| rdns <table> | session has a reverse DNS in table |
| src <table> | source address is in table |
| helo <table> | helo name is in table |
| auth | session is authenticated |
| auth <table> | session username is in table |
| mail-from <table> | sender address is in table |
| rcpt-to <table> | recipient address is in table |
These conditions may all be negated by prefixing them with an exclamation mark:
| !fcrdns | forward-confirmed reverse DNS is invalid |
Any conditions using a table may indicate that tables hold regex by prefixing the table name with the keyword regex.
| helo regex <table> | helo name matches a regex in table |
Finally, a number of decisions may be taken:
| bypass | the session or transaction bypasses filters |
| disconnect message | the session is disconnected with message |
| junk | the session or transaction is junked, i.e., an
‘X-Spam: yes’ header is added to any
messages |
| reject message | the command is rejected with message |
| rewrite value | the command parameter is rewritten with value |
Decisions that involve a message require that the message be RFC valid, meaning that they should either start with a 4xx or 5xx status code. Descisions can be taken at any phase, though junking can only happen before a message is committed.
Some configuration directives support expansion of their
parameters at runtime. Such directives (for example
action maildir,
action mda) may use format
specifiers which are expanded before delivery or relaying. The following
formats are currently supported:
| %{sender} | sender email address, may be empty string |
| %{sender.user} | user part of the sender email address, may be empty |
| %{sender.domain} | domain part of the sender email address, may be empty |
| %{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 |
| %{mbox.from} | name used in mbox From separator lines |
| %{mda} | mda command, only available for mda wrappers |
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 dangerous characters are replaced with ‘:’. In situations where they are desirable, the “raw” modifier may be applied. For example, with recipient “user+t?g@example.org”:
| %{rcpt} | expands to “user+t:g@example.org” |
| %{rcpt:raw} | expands to “user+t?g@example.org” |
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/secrets # chmod 640 /etc/secrets # chown root:_smtpd /etc/secrets # echo "bob username:password" > /etc/secrets
smtpd.conf would look like this:
table aliases file:/etc/aliases table secrets file:/etc/secrets listen on lo0 action "local_mail" mbox alias <aliases> action "outbound" relay host smtp+tls://bob@smtp.example.com \ auth <secrets> match from local for local action "local_mail" match from local for any action "outbound"
In this second example, the aim is to permit mail delivery and relaying only for users 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 routes point to. Mail with a local destination is 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 cert "/etc/ssl/mail.example.com.crt" pki mail.example.com key "/etc/ssl/private/mail.example.com.key" table aliases file:/etc/aliases listen on lo0 listen on egress tls pki mail.example.com auth action mda_with_aliases mda "/path/to/mda -f -" alias <aliases> action mda_without_aliases mda "/path/to/mda -f -" action "outbound" relay match for local action mda_with_aliases match from any for domain example.com action mda_without_aliases match for any action "outbound" match auth from any for any action "outbound"
For sites that wish to sign messages using DKIM, the following example uses opensmtpd-filter-dkimsign for DKIM signing:
table aliases file:/etc/aliases filter "dkimsign" proc-exec "filter-dkimsign -d <domain> -s <selector> \ -k /etc/dkim/private.key" user _dkimsign group _dkimsign listen on socket filter "dkimsign" listen on lo0 filter "dkimsign" action "local_mail" mbox alias <aliases> action "outbound" relay match for local action "local_mail" match for any action "outbound"
Alternatively, the
opensmtpd-filter-rspamd
package may be used to provide integration with rspamd, a
third-party daemon which provides multiple antispam features as well as DKIM
signing. As well as configuring rspamd itself, it requires
use of the proc-exec keyword:
filter "rspamd" proc-exec "filter-rspamd"
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 following example uses a list table other-relays to specify the IP addresses of relays that may legitimately originate mail with the owner's domain as the sender.
table aliases file:/etc/aliases
table other-relays file:/etc/other-relays
listen on lo0
listen on egress
action "local_mail" mbox alias <aliases>
action "outbound" relay
match for local action "local_mail"
match for any action "outbound"
match !from src <other-relays> mail-from "@example.com" for any \
reject
match from any for domain example.com action "local_mail"
smtpd(8) first appeared in OpenBSD 4.6.
| September 23, 2020 | Debian |