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 <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 virtual
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.
-
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 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 ‘@’.
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 file.
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 contain format specifiers that
are expanded before use.
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.
-
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(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 the verify parameter to
tls is specified, then
smtpd(8) 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(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.
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.
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.