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

.\"	$OpenBSD: smtpd.conf.5,v 1.13 2009/06/05 23:04:51 jacekm Exp $
.\"
.\" Copyright (c) 2008 Janne Johansson <jj@openbsd.org>
.\" Copyright (c) 2009 Jacek Masiulaniec <jacekm@dobremiasto.net>
.\"
.\" 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: June 5 2009 $
.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 .
.Sh SECTIONS
.Nm
is divided into four main sections:
.Bl -tag -width xxx
.It Sy Macros
User-defined variables may be defined and used later,
simplifying the configuration file.
.It Sy Global Configuration
Global settings for
.Xr smtpd 8 .
.It Sy Maps
Mail aliases,
virtual domains,
and authentication secrets
are stored in maps defined in this section.
.It Sy Filter Rules
Mail filter provides rule-based accepting, relaying, or refusing of messages.
.El
.Pp
Comments can be put anywhere in the file using a hash mark
.Pq Sq # ,
and extend to the end of the current line.
.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
.Sh MACROS
Macros can be defined that will later be expanded in context.
Macro names must start with a letter, and may contain letters, digits
and underscores.
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
wan_if = "fxp0"
listen on $wan_if
listen on $wan_if tls enable auth
.Ed
.Sh GLOBAL CONFIGURATION
Here are the settings that can be set globally:
.Bl -tag -width Ds
.It Ic hostname Ar name
Specify primary domain name of the server.
By default, current host name is used,
as returned by
.Xr hostname 1 .
.It Xo
.Ic listen on Ar interface
.Op Ic port Ar port
.Op Ic tls | smtps
.Op Ic certificate Ar name
.Op Ic enable auth
.Xc
Specify an
.Ar interface
and
.Ar port
to listen on.
Address or domain name may be used in place of
.Ar interface .
.Pp
Secured connections are provided either with STARTTLS,
by default on port 25,
or SMTPS,
by default on port 465.
If no certificate
.Ar name
is specified, the
.Pa /etc/mail/certs
directory is searched for a file named by joining
.Ar interface
name with a .crt extension, eg.
.Sq /etc/mail/certs/fxp0.crt .
Creation of certificates is documented in
.Xr starttls 8 .
.Pp
If the
.Ic enable auth
parameter is used,
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" source specification
will be matched.
.El
.Sh MAPS
Maps provide generic interface for associating textual key to a value.
Such associations may be accessed through a flat file, database, or DNS.
There are three maps known to smtpd:
.Bl -tag -width Ds
.It alias
Map queried when resolving mail aliases.
Query key is the user part of mail address.
.It virtual
Map used for creating virtual domains.
See the
.Sx VIRTUAL DOMAINS
section below.
.It secrets
Map queried for credentials
when relaying mail via server that requires SMTPAUTH
before accepting mail for relaying.
Query key is the domain name of the server acting as relay.
.El
.Pp
The configuration directives that are valid in the
.Ic map
context are described below:
.Bl -tag -width Ds
.It Ic type Ar maptype
Specifies method of accessing data.
The following map types are supported:
.Bl -tag -width Ds
.It db
Mappings are stored in a file created using
.Xr makemap 8 .
This is the default type if none is specified.
.It dns
Not implemented yet.
.It file
Not implemented yet.
.El
.It Ic source Ar mapsource
Specifies the source of mapping data.
It must be absolute path to a file in case of
.Dq file
and
.Dq db
.Ar maptype ,
and a domain name in case of
.Dq dns .
.El
.Sh FILTER RULES
.Xr smtpd 8
has the ability to
.Ar accept
and
.Ar reject
messages based on information gathered during 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
.Ic accept
/
.Ic reject
decision comes client's IP address filter:
.Bl -tag -width Ds
.It Ic from Ar network
The rule will match if connection is made from the specified
.Ar network .
If missing,
rule will apply to locally originated connections only.
.It Ic from all
Make the rule match regardless of the IP of connecting client.
.El
.Pp
Next comes the selection based on the domain the message is sent to:
.Bl -tag -width Ds
.It Ic for domain Ar domain
This rule applies to mail destined for specified
.Ar domain .
This parameter supports
.Sq *
wildcard,
so that one can have single rule for all sub-domains, for example:
.Bd -literal -offset indent
accept for domain "*.example.com" deliver to mbox
.Ed
.It Ic for local
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 Ic for all
Make the rule match regardless of the domain it is sent to.
.El
.Pp
Finally, method of delivery is specified:
.Bl -tag -width Ds
.It Ic deliver to mbox
Message is delivered to local user's system mailbox in
.Pa /var/mail .
.It Ic deliver to maildir Ar path
Message is added to a maildir.
Its location,
.Ar path ,
may contain format specifiers that are expanded before use,
see the
.Sx EXPANSION
section below.
If
.Ar path
is not provided, then
.Pa ~/Maildir
is assumed.
.It Ic deliver to mda Ar program
Message is piped to the specified
.Ar program ,
which is run with privileges of the user the message is destined to.
This parameter may use conversion specifiers that are expanded before use,
see the
.Sx EXPANSION
section below.
.It Ic relay
Message is relayed.
The routing decision is based on the DNS system.
.It Xo
.Ic relay via
.Ar host
.Op Ic port Ar port
.Op Ic tls | smtps | ssl
.Op Ic certificate Ar name
.Op Ic enable auth
.Xc
Message is relayed through the specified
.Ar host
and
.Ar port .
.Pp
Security of the communication channel may be enforced using the
.Ic tls
or
.Ic smtps
option.
Special keyword,
.Ic ssl ,
means any of the two is acceptable:
SMTPS is tried first, STARTTLS second.
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 SMTPAUTH session with
.Ar host
is desired, use the
.Ic enable auth
parameter.
.El
.Sh VIRTUAL DOMAINS
Virtual domains are kept in the virtual map.
To create single virtual address, add
.Dq user@example.com
to the virtual map.
To handle all mail destined to any user at example.com, add
.Dq @example.com
to the virtual map.
.Pp
In addition to adding an entry to the virtual map,
one must add a filter rule that accepts mail for the virtual domain,
for example:
.Bd -literal -offset indent
accept for domain "example.com" deliver to mbox
.Ed
.Sh EXPANSION
Some configuration directives expect expansion of their parameters at runtime.
Such directives (for example
.Ar deliver to maildir ,
.Ar deliver to mda ,
.Ar relay via )
may use format specifiers which will be expanded before delivery or
relaying.
The following formats are currently supported:
%a expands to the user part of the email address prior to the
resolution of aliases;
%u expands to the user part after aliases
resolution and will typically be the system account;
%d expands to the domain part of the email address.
.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 following example configures a machine to accept local delivery
for both localhost and example.com, as well as the relaying of mail
destined for example.org through the mx1.example.org server and mail
destined for example.net through regular MX record lookup:
.Bd -literal -offset indent
listen on lo0
accept for local deliver to mbox
accept for domain "example.com" deliver to mbox
accept for domain "example.org" relay via "mx1.example.org"
accept for domain "example.net" relay
.Ed
.Sh SEE ALSO
.Xr smtpctl 8 ,
.Xr smtpd 8
.Sh HISTORY
.Xr smtpd 8
first appeared in
.Ox 4.6 .