.\" $OpenBSD: smtpd.conf.5,v 1.10 2009/05/10 11:29:40 jacekm Exp $ .\" .\" Copyright (c) 2008 Janne Johansson .\" Copyright (c) 2009 Jacek Masiulaniec .\" .\" 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: May 10 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, sender that passed SMTPAUTH is allowed to relay mail using standard DNS-based routing, unless a filter rule was matched that dictated different action. .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. .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 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. .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 .