From 1c9b3e03c3d0a99e4caa58fa777f687fcb42ce41 Mon Sep 17 00:00:00 2001 From: Jacek Masiulaniec Date: Thu, 9 Apr 2009 20:32:46 +0000 Subject: make the manpage fairly complete, contains bits from jmc@ --- usr.sbin/smtpd/smtpd.conf.5 | 266 ++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 243 insertions(+), 23 deletions(-) (limited to 'usr.sbin') diff --git a/usr.sbin/smtpd/smtpd.conf.5 b/usr.sbin/smtpd/smtpd.conf.5 index d3bdb2cc46d..cb6036bdd45 100644 --- a/usr.sbin/smtpd/smtpd.conf.5 +++ b/usr.sbin/smtpd/smtpd.conf.5 @@ -1,4 +1,4 @@ -.\" $OpenBSD: smtpd.conf.5,v 1.7 2009/03/17 00:18:39 gilles Exp $ +.\" $OpenBSD: smtpd.conf.5,v 1.8 2009/04/09 20:32:45 jacekm Exp $ .\" .\" Copyright (c) 2008 Janne Johansson .\" @@ -15,7 +15,7 @@ .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. .\" .\" -.Dd $Mdocdate: March 17 2009 $ +.Dd $Mdocdate: April 9 2009 $ .Dt SMTPD.CONF 5 .Os .Sh NAME @@ -23,23 +23,36 @@ .Nd Simple Mail Transfer Protocol daemon configuration file .Sh DESCRIPTION .Nm -is used to configure -.Xr smtpd 8 , -a small SMTP daemon. +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 -Lines beginning with -.Sq # -and empty lines are regarded as comments, -and ignored. -Lines may be split using the -.Sq \e -character. +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/sub.smtpd.conf" +include "/etc/mail/smtpd.conf.local" .Ed .Sh MACROS Macros can be defined that will later be expanded in context. @@ -51,18 +64,225 @@ Macro names may not be reserved words (for example .Ar port ) . Macros are not expanded inside quotes. .Pp -For example, +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: +.Pp +.Bl -tag -width Ds -compact +.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 . +.Pp +.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. +.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 -smtpport = 25 -listen on 127.0.0.1 port $smtpport -listen on fxp0 port $smtp_port -ssmtp listen on fxp0 port $smtp_port enable auth +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 parameter at -runtime. +Some configuration directives expect expansion of their parameters at runtime. Such directives (for example -.Ar deliver to mbox , .Ar deliver to maildir , .Ar deliver to mda , .Ar relay via ) @@ -87,7 +307,7 @@ Spool directories for mail during processing. 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 records lookup: +destined for example.net through regular MX record lookup: .Bd -literal -offset indent listen on lo0 accept for local deliver to mbox @@ -101,4 +321,4 @@ accept for domain "example.net" relay .Sh HISTORY .Xr smtpd 8 first appeared in -.Ox 4.5 . +.Ox 4.6 . -- cgit v1.2.3