OpenBSD manual page server

Manual Page Search Parameters
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).

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

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"

Additional configuration files can be included with the include keyword, for example:

include "/etc/mail/smtpd.conf.local"

The syntax of smtpd.conf is described below.

|
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.

Following the accept/reject decision comes the client's IP address filter:

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.
network
The rule matches if the connection is made from the specified network, specified in CIDR notation.
⟨table⟩
The rule matches if the connection is made from a client whose address is declared in the table table.
tag
If specified, the rule will only be matched if the client session was tagged tag.

In addition, finer filtering may be achieved on the sender if desired:

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:

[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.
⟨vmap⟩
Make the rule match regardless of the domain it is sent to. The vmap table will be used as the virtual domain mapping.
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.

⟨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.

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).

⟨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).

[alias ⟨aliases⟩]
This rule applies to mail destined to “localhost” and to the default server name (see below).
⟨vmap⟩
This rule applies to mail destined to “localhost” and to the default server name (see below). The vmap table will be used as the virtual domain mapping.

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.

Finally, the method of delivery is specified:

[host:port | socket]
Mail is delivered to host:port, or to the UNIX socket over LMTP.
path
Mail is added to a maildir. Its location, path, may contain format specifiers that are expanded before use (see above). If path is not provided, then ~/Maildir is assumed.
Mail is delivered to the local user's system mailbox in /var/mail.
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 above).
[backup [mx]] [as address] [source source] [helo names]
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, default server name (see below) 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 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 table 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 (see below). A helo parameter may be specified to advertise an alternate hostname. 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.

relay via host [certificate name] [auth ⟨auth⟩] [as address] [source source] [helo names]
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
ssl://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
ssl+auth://label@mx.example.org	  # over either \
				  # SMTPS or TLS

If a certificate name is specified and exists in the /etc/mail/certs directory with a .crt extension, it will be used if the remote server requests a client certificate. Creation of certificates is documented in starttls(8).

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 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 table 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 (see below). A helo parameter may be specified to advertise an alternate hostname. 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.

Additional per-rule adjustments available:

n {s|m|h|d}
Specify how long a message that matched this rule can stay in the queue.
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.

n {s|m|h|d}
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
[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.
listen on interface [family] [port port] [tls | tls-require | smtps] [certificate name] [auth | auth-optional] [tag tag] [hostname hostname]
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. Host certificates may be used for these connections, and are searched for in the /etc/mail/certs directory. If certificate is specified, a certificate ⟨name⟩.crt, a key ⟨name⟩.key and Diffie-Hellman parameters ⟨name⟩.dh are searched for. A certificate authority may be appended to the .crt file to create a certificate chain. If no certificate is specified, the default interface name is instead used, for example fxp0.crt, fxp0.key, fxp0.ca, and fxp0.dh. If no DH parameters are provided, smtpd will use built-in parameters. Creation of certificates is documented in starttls(8).

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.

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 (see below).

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.
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.
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

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.

name [type:]config
Tables are used to provide additional configuration information for smtpd(8) in the form of lists or key-value mappings.

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.

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.

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.

The default server name is the hostname that smtpd(8) operates as, which is used at various places. It is determined at startup as follows.

If a /etc/mailname file exists, then the first line is read and 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 retreiving the associated canonical name through getaddrinfo(3).

/etc/mail/smtpd.conf
Default smtpd(8) configuration file.
/etc/mailname
Alternate server name to use.
/var/spool/smtpd/
Spool directories for mail during processing.

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/mail/secrets
# chmod 640 /etc/mail/secrets
# chown root:_smtpd /etc/mail/secrets
# echo "label username:password" > /etc/mail/secrets
# makemap /etc/mail/secrets

smtpd.conf would look like this:

listen on lo0
table aliases db:/etc/mail/aliases.db
table secrets db:/etc/mail/secrets.db
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/mail/certs/mail.example.com.key 4096
# openssl req -new -x509 -key /etc/mail/certs/mail.example.com.key \
	-out /etc/mail/certs/mail.example.com.crt -days 365
# chmod 600 /etc/mail/certs/mail.example.com.*

In the example above, a certificate valid for one year was created. The configuration file would look like this:

listen on lo0
listen on egress tls certificate mail.example.com auth
table aliases db:/etc/mail/aliases.db
accept for local alias <aliases> deliver to mda "/path/to/mda -f -"
accept from any for domain example.org \
	deliver to mda "/path/to/mda -f -"
accept for any relay

mailer.conf(5), makemap(8), smtpd(8)

smtpd(8) first appeared in OpenBSD 4.6.

July 20, 2013 OpenBSD-5.4