path: root/usr.sbin/smtpd/smtpd.conf.5

.\"	$OpenBSD: smtpd.conf.5,v 1.80 2013/02/04 05:55:58 gilles Exp $
.\"
.\" Copyright (c) 2008 Janne Johansson <jj@openbsd.org>
.\" Copyright (c) 2009 Jacek Masiulaniec <jacekm@dobremiasto.net>
.\" Copyright (c) 2012 Gilles Chehade <gilles@poolp.org>
.\"
.\" Permission to use, copy, modify, and distribute this software for any
.\" purpose with or without fee is hereby granted, provided that the above
.\" copyright notice and this permission notice appear in all copies.
.\"
.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.\"
.Dd $Mdocdate: February 4 2013 $
.Dt SMTPD.CONF 5
.Os
.Sh NAME
.Nm smtpd.conf
.Nd Simple Mail Transfer Protocol daemon configuration file
.Sh DESCRIPTION
.Nm
is the configuration file for the mail daemon
.Xr smtpd 8 .
.Pp
The current line can be extended over multiple lines using a backslash
.Pq Sq \e .
Comments can be put anywhere in the file using a hash mark
.Pq 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.
.Pp
Argument names not beginning with a letter, digit, or underscore
must be quoted.
Arguments containing whitespace should be surrounded by double quotes
.Pq \&" .
.Pp
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
.Ar listen ,
.Ar accept ,
.Ar port ) .
Macros are not expanded inside quotes.
.Pp
For example:
.Bd -literal -offset indent
lan_addr = "192.168.0.1"
listen on $lan_addr
listen on $lan_addr tls auth
.Ed
.Pp
Some configuration directives support expansion of their parameters at runtime.
Such directives (for example
.Ar deliver to maildir ,
.Ar deliver to mda )
may use format specifiers which will be expanded before delivery or
relaying.
The following formats are currently supported:
.Bd -literal -offset indent
%{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
.Ed
.Pp
Expansion formats also support partial expansion using the optional
bracket notations with substring offset.
For example, with recipient domain "example.org":
.Bd -literal -offset indent
%{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"
.Ed
.Pp
Additional configuration files can be included with the
.Ic include
keyword, for example:
.Bd -literal -offset indent
include "/etc/mail/smtpd.conf.local"
.Ed
.Pp
The syntax of
.Nm
is described below.
.Bl -tag -width Ds
.It Ic expire Ar n {s|m|h|d}
Specify how long a message can stay in the queue.
The default value is 4 days.
For example:
.Bd -literal -offset indent
expire 4d	# expire after 4 days
expire 10h	# expire after 10 hours
.Ed
.It Xo
.Ic listen on Ar interface
.Op Ic port Ar port
.Op Ic tls | tls-require | smtps
.Op Ic certificate Ar name
.Op Ic auth | auth-optional
.Op Ic tag Ar tag
.Op Ic hostname Ar hostname
.Xc
Specify an
.Ar interface
and
.Ar port
to listen on.
An interface group, an IP address or a domain name may
be used in place of
.Ar interface .
.Pp
Secured connections are provided either using STARTTLS
.Pq Ic tls ,
by default on port 25,
or SMTPS
.Pq Ic smtps ,
by default on port 465.
.Ic 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
.Pa /etc/mail/certs
directory.
If
.Ic certificate
is specified,
a certificate
.Ao Ar name Ac Ns .crt ,
a key
.Ao Ar name Ac Ns .key
and Diffie-Hellman parameters
.Ao Ar name Ac Ns .dh
are searched for.
A certificate authority may be appended to the .crt
file to create a certificate chain.
If no
.Ic certificate
is specified,
the default interface name is instead used,
for example
.Pa fxp0.crt ,
.Pa fxp0.key ,
.Pa fxp0.ca ,
and
.Pa fxp0.dh .
If no DH parameters are provided, smtpd will use
built-in parameters.
Creation of certificates is documented in
.Xr starttls 8 .
.Pp
If the
.Ic 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
.Ic 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.
.Pp
If the
.Ic tag
parameter is used, then clients connecting to the listener will be
tagged
.Ar tag .
.Pp
If the
.Ic hostname
parameter is used, then it will be used in the greeting banner.
.It Xo
.Ic table Ar name
.Ar [type:]config
.Xc
Tables are used to provide additional configuration information for
.Xr smtpd 8
in the form of lists or key-value mappings.
.Pp
The table is identified using table name
.Ar name ;
the name itself is arbitrarily chosen.
.Pp
.Ar type
specifies the table backend,
and should be one of the following:
.Pp
.Bl -tag -width "fileXXX" -compact
.It db
Information is stored in a file created using
.Xr makemap 8 .
.It file
Information is stored in a plain text file using the
same format as used to generate
.Xr makemap 8
mappings.
This is the default.
.El
.Pp
.Ar config
specifies a configuration file for the table data.
It must be an absolute path to a file for the
.Dq file
and
.Dq db
table types.
.It Xo
.Ic table Ar name
.Ic { Ar value
.Op , Ar value_n
.Ic }
.Xc
Tables containing list of static values may be declared
using an inlined notation.
.Pp
The table is identified using table name
.Ar name ;
the name itself is arbitrarily chosen.
.Pp
The table must contain at least one value and may declare many values as a
list of comma separated strings.
.It Xo
.Ic table Ar name
.Ic { Ar key => value
.Op , key_n => value_n
.Ic }
.Xc
Tables containing static key-value mappings may be declared
using an inlined notation.
.Pp
The table is identified using table name
.Ar name ;
the name itself is arbitrarily chosen.
.Pp
The table must contain at least one key-value mapping and may declare
many mappings as a list of comma separated
.Ar key => value
descriptions.
.It Ic max-message-size Ar n
Specify a maximum message size of
.Ar n
bytes.
The argument may contain a multiplier, as documented in
.Xr scan_scaled 3 .
The default maximum message size is 35MB if none is specified.
.It Xo
.Ic queue
.Ic compression Op Ar gzip
.Xc
Enable transparent deflating and inflating of all envelopes
and messages.
The only supported algorithm at the moment is gzip.
Envelopes and messages may be inspected using
.Xr gzcat 1 .
.It Ic accept | reject
.Xr smtpd 8
accepts and rejects messages
based on information gathered during the SMTP session.
.Pp
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.
.Pp
Following the accept/reject
decision comes the client's IP address filter:
.Bl -tag -width Ds
.It Ic tagged Ar tag
If specified, the rule will only be matched if the client session was tagged
.Ar tag .
.It Ic from any
Make the rule match regardless of the IP of connecting client.
.It Ic from local
The rule matches only locally originating connections.
This is the default,
and may be omitted.
.It Ic from Ar network
The rule matches if the connection is made from the specified
.Ar network ,
specified in CIDR notation.
.It Ic from Ar <table>
The rule matches if the connection is made from a client whose address
is declared in the table
.Ar table .
.El
.Pp
In addition, finer filtering may be achieved on the sender if desired:
.Bl -tag -width Ds
.It Ic sender Ar senders
If specified, the rule will only be matched if the sender email address
is found in the table
.Ar senders .
The table may contain complete email addresses or apply to an entire
domain if prefixed with @.
.El
.Pp
Next comes the selection based on the domain the message is sent to:
.Bl -tag -width Ds
.It Xo
.Ic for any
.Op Ic alias Ar <aliases>
.Xc
Make the rule match regardless of the domain it is sent to.
If specified, the table
.Ar aliases
is used for looking up alternative destinations for all addresses.
.It Xo
.Ic for any
.Ic virtual Ar <vmap>
.Xc
Make the rule match regardless of the domain it is sent to.
The
.Ar vmap
table will be used as the virtual domain mapping.
.It Xo
.Ic for domain Ar domain
.Op Ic alias Ar <aliases>
.Xc
This rule applies to mail destined for the specified
.Ar domain .
This parameter supports the
.Sq *
wildcard,
so that a single rule for all sub-domains can be used, for example:
.Bd -literal -offset indent
accept for domain "*.example.com" deliver to mbox
.Ed
.Pp
If specified, the table
.Ar aliases
is used for looking up alternative destinations for addresses in this
.Ar domain .
.It Xo
.Ic for domain Ar <domains>
.Op Ic alias Ar <aliases>
.Xc
This rule applies to mail destined to domains which are part of the table
.Ar domains .
.Pp
If specified, the table
.Ar aliases
is used for looking up alternative destinations for addresses in these
.Ar domains .
.It Xo
.Ic for domain Ar domain Ic virtual Ar <users>
.Xc
This rule applies to mail destined for the specified virtual
.Ar domain .
This parameter supports the
.Sq *
wildcard,
so that a single rule for all sub-domains can be used, for example:
.Bd -literal -offset indent
accept for domain "*.example.com" \e
       virtual <users> deliver to mbox
.Ed
.Pp
The table
.Ar users
holds a key-value mapping of virtual to system users.
For an example of how to configure the
.Ar users
table, see
.Xr makemap 8 .
.It Ic for domain Ar <domains> Ic virtual Ar <users>
This rule applies to mail destined for the virtual domains specified
in the table
.Ar domains .
.Pp
The table
.Ar users
holds a key-value mapping of virtual to system users.
For an example of how to configure the
.Ar users
table, see
.Xr makemap 8 .
.It Xo
.Ic for local
.Op Ic alias Ar <aliases>
.Xc
This rule applies to mail destined to
.Dq localhost
and to the server's fully qualified domain name,
as returned by
.Xr hostname 1 .
.It Xo
.Ic for local
.Ic virtual Ar <vmap>
.Xc
This rule applies to mail destined to
.Dq localhost
and to the server's fully qualified domain name,
as returned by
.Xr hostname 1 .
The
.Ar vmap
table will be used as the virtual domain mapping.
.El
.Pp
If the method of delivery is local, a user database may be
specified to override the system database:
.Bl -tag -width Ds
.It Xo
.Op Ic users Ar <table>
.Xc
Look up users in the table
.Ar table
instead of performing system lookups using the
.Xr getpwnam 3
function.
.El
.Pp
Finally, the method of delivery is specified:
.Bl -tag -width Ds
.It Ic deliver to maildir Ar path
Mail is added to a maildir.
Its location,
.Ar path ,
may contain format specifiers that are expanded before use
(see above).
If
.Ar path
is not provided, then
.Pa ~/Maildir
is assumed.
.It Ic deliver to mbox
Mail is delivered to the local user's system mailbox in
.Pa /var/mail .
.It Ic deliver to mda Ar program
Mail is piped to the specified
.Ar 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).
.It Xo
.Ic relay
.Op Ic backup Op Ar mx
.Op Ic as Ar address
.Op Ic source Ar source
.Xc
Mail is relayed.
The routing decision is based on the DNS system.
.Pp
If the
.Ic 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
.Ar mx .
If
.Ar mx
is not specified, local hostname will be assumed.
.Pp
If the
.Ic as
parameter is specified,
.Xr smtpd 8
will rewrite the sender advertised
in the SMTP session.
.Ar 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.
.Pp
If the
.Ic source
parameter is specified,
.Xr smtpd 8
will explicitly bind to an address found in the table referenced by
.Ar 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.
.It Xo
.Ic relay via
.Ar host
.Op Ic certificate Ar name
.Op Ic auth Ar <auth>
.Op Ic as Ar address
.Op Ic source Ar source
.Xc
Mail is relayed through the specified
.Ar host
expressed as a URL.
For example:
.Bd -literal -offset indent
smtp://mx1.example.org		# use SMTP
smtp://mx1.example.org:4321	# use SMTP \e
				# with port 4321
.Ed
.Pp
The communication channel may be secured using one of the secure
schemas.
For example:
.Bd -literal -offset indent
tls://mx1.example.org		# use TLS
smtps://mx1.example.org		# use SMTPS
ssl://mx1.example.org		# try SMTPS and \e
				# fallback to TLS
.Ed
.Pp
In addition, credentials for authenticated relaying may be provided
when using a secure schema.
For example:
.Bd -literal -offset indent
tls+auth://label@mx.example.org	  # over TLS
smtps+auth://label@mx.example.org # over SMTPS
ssl+auth://label@mx.example.org	  # over either \e
				  # SMTPS or TLS
.Ed
.Pp
If a certificate
.Ar name
is specified and exists in the
.Pa /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
.Xr starttls 8 .
.Pp
If an SMTPAUTH session with
.Ar host
is desired, the
.Ic auth
parameter is used to specify the
.Ar auth
table that holds the credentials.
Credentials will be looked up using the label provided in the URL.
.Pp
If the
.Ic as
parameter is specified,
.Xr smtpd 8
will rewrite the sender advertised
in the SMTP session.
.Ar 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.
.Pp
If the
.Ic source
parameter is specified,
.Xr smtpd 8
will explicitly bind to an address found in the table referenced by
.Ar 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.
.El
.It Ic expire Ar n {s|m|h|d}
Specify how long a message that matched this rule can stay in the queue.
.It Ic bounce-warn Ar 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:
.Bd -literal -offset indent
bounce-warn	1h, 6h, 2d
.Ed
.Pp
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.
.El
.Sh FILES
.Bl -tag -width "/etc/mail/smtpd.confXXX" -compact
.It Pa /etc/mail/smtpd.conf
Default
.Xr smtpd 8
configuration file.
.It Pa /var/spool/smtpd/
Spool directories for mail during processing.
.El
.Sh EXAMPLES
The default
.Nm
file which ships with
.Ox
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.
.Pp
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:
.Bd -literal -offset indent
# touch /etc/mail/secrets
# chmod 640 /etc/mail/secrets
# chown root:_smtpd /etc/mail/secrets
# echo "label username:password" \*(Gt /etc/mail/secrets
# makemap /etc/mail/secrets
.Ed
.Pp
.Nm
would look like this:
.Bd -literal -offset indent
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>
.Ed
.Pp
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 has an external interface bnx0.
Mail with a local destination should be sent to an external mda.
First, the RSA certificate is created:
.Bd -literal -offset indent
# openssl genrsa -out /etc/mail/certs/mail.example.com.key 4096
# openssl req -new -x509 -key /etc/mail/certs/mail.example.com.key \e
	-out /etc/mail/certs/mail.example.com.crt -days 365
# chmod 600 /etc/mail/certs/mail.example.com.*
.Ed
.Pp
In the example above,
a certificate valid for one year was created.
The configuration file would look like this:
.Bd -literal -offset indent
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 \e
	deliver to mda "/path/to/mda -f -"
accept for any relay
.Ed
.Sh SEE ALSO
.Xr mailer.conf 5 ,
.Xr makemap 8 ,
.Xr smtpd 8
.Sh HISTORY
.Xr smtpd 8
first appeared in
.Ox 4.6 .