smtpd.conf(5)
NAME
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
('\'). 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 "/etc/smtpd.conf.local"
The syntax of smtpd.conf is described below.
accept | reject
smtpd(8) accepts and rejects messages based on information
gathered during the SMTP session.
For each message processed by the daemon, the 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 rule 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 access control 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 table(5).
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 table(5).
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 access control 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] [rcpt-to] [as user]
Mail is delivered to host:port, or to the UNIX socket
over LMTP with the privileges of the specified user.
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.
deliver to maildir [path]
Mail is added to a maildir. Its location, path, may
contain 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 [as user]
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
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(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.
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 are 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 located in cafile with
hostname.
ciphers cipher-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.
When not specified, only ciphers considered safe are chosen.
expire n{s|m|h|d}
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
filter name 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).
filter name chain filter ...
Specify a filter chain with the given name and filters.
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 performance.
listen on socket [filter name] [mask-source] listen on interface [family]
[port port] [filter name]
[tls | tls-require | tls-require verify | smtps | secure]
[pki pkiname] [ca caname] [auth | auth-optional [<authtable>]]
[tag tag] [hostname hostname] [hostnames <names>]
[senders <users> [masquerade]] [mask-source] [received-auth]
[no-dsn]
Specify a 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.
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.
If a fallback certificate or SNI is wanted, the '*' wildcard may
be used as 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 dhe params
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) 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:
$ 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
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.
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
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"
FILES
/etc/smtpd.conf Default smtpd(8) configuration file.
/etc/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 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/secrets
# chmod 640 /etc/secrets
# chown root:_smtpd /etc/secrets
# echo "label username:password" > /etc/secrets
smtpd.conf would look like this:
table aliases file:/etc/aliases
table secrets file:/etc/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>
In this second example, the aim is to permit mail relaying for any user
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 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"
table aliases file:/etc/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
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.
table aliases file:/etc/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
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 table other-relays can be used to specify the
IP addresses of relays that may legitimately originate mail with your
domain as the sender.
table aliases file:/etc/aliases
table other-relays file:/etc/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.
Opportunity
Personal Opportunity - Free software gives you access to billions of dollars of software at no cost. Use this software for your business, personal use or to develop a profitable skill. Access to source code provides access to a level of capabilities/information that companies protect though copyrights. Open source is a core component of the Internet and it is available to you. Leverage the billions of dollars in resources and capabilities to build a career, establish a business or change the world. The potential is endless for those who understand the opportunity.
Business Opportunity - Goldman Sachs, IBM and countless large corporations are leveraging open source to reduce costs, develop products and increase their bottom lines. Learn what these companies know about open source and how open source can give you the advantage.
Free Software
Free Software provides computer programs and capabilities at no cost but more importantly, it provides the freedom to run, edit, contribute to, and share the software. The importance of free software is a matter of access, not price. Software at no cost is a benefit but ownership rights to the software and source code is far more significant.
Free Office Software - The Libre Office suite provides top desktop productivity tools for free. This includes, a word processor, spreadsheet, presentation engine, drawing and flowcharting, database and math applications. Libre Office is available for Linux or Windows.
Free Books
The Free Books Library is a collection of thousands of the most popular public domain books in an online readable format. The collection includes great classical literature and more recent works where the U.S. copyright has expired. These books are yours to read and use without restrictions.
Source Code - Want to change a program or know how it works? Open Source provides the source code for its programs so that anyone can use, modify or learn how to write those programs themselves. Visit the GNU source code repositories to download the source.
Education
Study at Harvard, Stanford or MIT - Open edX provides free online courses from Harvard, MIT, Columbia, UC Berkeley and other top Universities. Hundreds of courses for almost all major subjects and course levels. Open edx also offers some paid courses and selected certifications.
Linux Manual Pages - A man or manual page is a form of software documentation found on Linux/Unix operating systems. Topics covered include computer programs (including library and system calls), formal standards and conventions, and even abstract concepts.
