.
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
). Macros are not expanded inside quotes.
- accept | reject
-
smtpd(8)
accepts and rejects messages
based on information gathered 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
Pf < 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
-
[ !]
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 @.
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
Sq *
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
Pf < 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 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
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
Pf < 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
/etc/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
-
[ !]
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 @.
If the method of delivery is local, a user database may be
specified 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 redirected to an
external address via an alias or a ~/.forward.
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
Ux
socket
over LMTP.
- 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 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 .B FORMAT SPECIFIERS .)
- Bk -words
-
relay
[ backup [mx]]
[ as address]
[ source < source >]
[ hostname name]
[ hostnames < names >]
[ pki pkiname]
[ tls [verify]]
Ek
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
Sq @,
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 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 OpenSMTPD 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, 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:
The communication channel may be secured using one of the secure
schemas.
For example:
In addition, credentials for authenticated relaying may be provided
when using a secure schema.
For example:
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
Sq @,
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 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, 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
-
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:
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 recommended 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
-
Sm off
n
{ s | m | h | d}
Sm on
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.
- Bk -words
-
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]
Ek
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 services.
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 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.
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.
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 Notification) 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 content of the original message.
- max-message-size n
-
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.
- pki hostname certificate
certfile
-
Associate the certificate located in
certfile
with
hostname.
A certificate chain may be created by appending one or many certificates,
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 specified, 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)
utilities.
- 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:
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 following:
- 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.
Some configuration directives support expansion of their parameters at runtime.
Such directives (for example
may use format specifiers which will be expanded before delivery or
relaying. The following formats are currently supported:
Expansion formats also support partial expansion using the optional bracket
notations with substring offset. For example, with recipient domain
``example.org :''
In addition, modifiers may be applied to the token. For example, with recipient
``User+Tag@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 :''
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:
first appeared in OpenBSD 4.6.