1.\" $OpenBSD: smtpd.conf.5,v 1.22 2009/10/13 04:53:33 jmc Exp $ 2.\" 3.\" Copyright (c) 2008 Janne Johansson <jj@openbsd.org> 4.\" Copyright (c) 2009 Jacek Masiulaniec <jacekm@dobremiasto.net> 5.\" 6.\" Permission to use, copy, modify, and distribute this software for any 7.\" purpose with or without fee is hereby granted, provided that the above 8.\" copyright notice and this permission notice appear in all copies. 9.\" 10.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 11.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 12.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 13.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 14.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 15.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 16.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 17.\" 18.\" 19.Dd $Mdocdate: October 13 2009 $ 20.Dt SMTPD.CONF 5 21.Os 22.Sh NAME 23.Nm smtpd.conf 24.Nd Simple Mail Transfer Protocol daemon configuration file 25.Sh DESCRIPTION 26.Nm 27is the configuration file for the mail daemon 28.Xr smtpd 8 . 29.Pp 30Comments can be put anywhere in the file using a hash mark 31.Pq # , 32and extend to the end of the current line. 33Arguments containing whitespace should be surrounded by double quotes 34.Pq \&" . 35.Pp 36Macros can be defined that will later be expanded in context. 37Macro names must start with a letter, and may contain letters, digits 38and underscores. 39Macro names may not be reserved words (for example 40.Ar listen , 41.Ar accept , 42.Ar port ) . 43Macros are not expanded inside quotes. 44.Pp 45For example: 46.Bd -literal -offset indent 47wan_if = "fxp0" 48listen on $wan_if 49listen on $wan_if tls enable auth 50.Ed 51.Pp 52Some configuration directives expect expansion of their parameters at runtime. 53Such directives (for example 54.Ar deliver to maildir , 55.Ar deliver to mda , 56.Ar relay via ) 57may use format specifiers which will be expanded before delivery or 58relaying. 59The following formats are currently supported: 60%a expands to the user part of the email address prior to the 61resolution of aliases; 62%u expands to the user part after aliases 63resolution and will typically be the system account; 64%d expands to the domain part of the email address. 65.Pp 66Additional configuration files can be included with the 67.Ic include 68keyword, for example: 69.Bd -literal -offset indent 70include "/etc/mail/smtpd.conf.local" 71.Ed 72.Pp 73The syntax of 74.Nm 75is described below. 76.Bl -tag -width Ds 77.It Ic hostname Ar name 78Specify the domain name of the server. 79By default the current host name is used, 80as returned by 81.Xr hostname 1 . 82.It Xo 83.Ic listen on Ar interface 84.Op Ic port Ar port 85.Op Ic tls | smtps 86.Op Ic certificate Ar name 87.Op Ic enable auth 88.Xc 89Specify an 90.Ar interface 91and 92.Ar port 93to listen on. 94An IP address or domain name may be used in place of 95.Ar interface . 96.Pp 97Secured connections are provided either using STARTTLS 98.Pq Ic tls , 99by default on port 25, 100or SMTPS 101.Pq Ic smtps , 102by default on port 465. 103Creation of certificates is documented in 104.Xr starttls 8 . 105If no certificate 106.Ar name 107is specified, the 108.Pa /etc/mail/certs 109directory is searched for a file named by joining 110the interface name with a .crt extension, e.g.\& 111.Pa /etc/mail/certs/fxp0.crt . 112.Pp 113If the 114.Ic enable auth 115parameter is used, 116any remote sender that passed SMTPAUTH is treated as if 117it was the server's local user that was sending the mail. 118This means that filter rules using "from local" will be matched. 119.It Xo 120.Ic map Ar map 121.No { 122.Op Ic type Ar maptype 123.Ic source Ar mapsource 124.No } 125.Xc 126Maps are used to provide additional configuration information for 127.Xr smtpd 8 . 128.Pp 129.Ar map 130may be one of the following: 131.Pp 132.Bl -tag -width "virtualXXX" -compact 133.It alias 134Map queried for mail aliases. 135See 136.Xr aliases 5 137and 138.Xr newaliases 8 . 139.It secrets 140Map queried for remote host credentials. 141See 142.Xr makemap 8 . 143.It virtual 144Map queried for virtual domains. 145See 146.Xr makemap 8 . 147.El 148.Pp 149.Ar maptype 150may be one of the following: 151.Pp 152.Bl -tag -width "fileXXX" -compact 153.It db 154Mappings are stored in a file created using 155.Nm . 156This is the default type if none is specified. 157.It dns 158Not implemented yet. 159.It file 160Not implemented yet. 161.El 162.Pp 163.Ar mapsource 164specifies the source of the map data. 165It must be an absolute path to a file for the 166.Dq file 167and 168.Dq db 169maptypes, 170or a domain name for the 171.Dq dns 172maptype. 173.It Ic accept | reject 174.Xr smtpd 8 175accepts and rejects messages 176based on information gathered during the SMTP session. 177.Pp 178For each message processed by the daemon, 179the filter rules are evaluated in sequential order, 180from first to last. 181The first matching rule decides what action is taken. 182If no rule matches the message, 183the default action is to reject the message. 184.Pp 185Following the accept/reject 186decision comes the client's IP address filter: 187.Bl -tag -width Ds 188.It Ic from all 189Make the rule match regardless of the IP of connecting client. 190.It Ic from local 191The rule matches only locally originating connections. 192This is the default, 193and may be omitted. 194.It Ic from Ar network 195The rule matches if the connection is made from the specified 196.Ar network . 197.El 198.Pp 199Next comes the selection based on the domain the message is sent to: 200.Bl -tag -width Ds 201.It Ic for all 202Make the rule match regardless of the domain it is sent to. 203.It Ic for domain Ar domain 204This rule applies to mail destined for the specified 205.Ar domain . 206This parameter supports the 207.Sq * 208wildcard, 209so that a single rule for all sub-domains can be used, for example: 210.Bd -literal -offset indent 211accept for domain "*.example.com" deliver to mbox 212.Ed 213.It Ic for local 214This rule applies to mail destined to 215.Dq localhost 216and to the server's fully qualified domain name, 217as returned by 218.Xr hostname 1 . 219.It Ic for virtual map Ar map 220This rule applies to mail destined for the virtual domains specified 221in the map 222.Ar map . 223For an example of how to configure a virtual map, see 224.Xr makemap 8 . 225.El 226.Pp 227Finally, the method of delivery is specified: 228.Bl -tag -width Ds 229.It Ic deliver to maildir Ar path 230Mail is added to a maildir. 231Its location, 232.Ar path , 233may contain format specifiers that are expanded before use 234(see above). 235If 236.Ar path 237is not provided, then 238.Pa ~/Maildir 239is assumed. 240.It Ic deliver to mbox 241Mail is delivered to the local user's system mailbox in 242.Pa /var/mail . 243.It Ic deliver to mda Ar program 244Mail is piped to the specified 245.Ar program , 246which is run with the privileges of the user the message is destined to. 247This parameter may use conversion specifiers that are expanded before use 248(see above). 249.It Ic relay 250Mail is relayed. 251The routing decision is based on the DNS system. 252.It Xo 253.Ic relay via 254.Ar host 255.Op Ic port Ar port 256.Op Ic tls | smtps | ssl 257.Op Ic certificate Ar name 258.Op Ic enable auth 259.Xc 260Mail is relayed through the specified 261.Ar host 262and 263.Ar port . 264.Pp 265The communication channel may be secured using the 266.Ic tls 267or 268.Ic smtps 269options. 270The special keyword 271.Ic ssl 272means that any of the two is acceptable: 273SMTPS is tried first, STARTTLS second. 274If a certificate 275.Ar name 276is specified and exists in the 277.Pa /etc/mail/certs 278directory with a .crt extension, it will be used if the remote server 279requests a client certificate. 280Creation of certificates is documented in 281.Xr starttls 8 . 282.Pp 283If an SMTPAUTH session with 284.Ar host 285is desired, use the 286.Ic enable auth 287parameter. 288.El 289.El 290.Sh FILES 291.Bl -tag -width "/etc/mail/smtpd.confXXX" -compact 292.It Pa /etc/mail/smtpd.conf 293Default 294.Xr smtpd 8 295configuration file. 296.It Pa /var/spool/smtpd/ 297Spool directories for mail during processing. 298.El 299.Sh EXAMPLES 300The default 301.Nm 302file which ships with 303.Ox 304listens on the loopback network interface (lo0), 305and allows for mail from users and daemons on the local machine, 306as well as permitting email to remote servers. 307Some more complex configurations are given below. 308.Pp 309This first example is the same as the default configuration, 310but all outgoing mail is forwarded to a gmail SMTP server. 311A secrets file is needed to specify a username and password: 312.Bd -literal -offset indent 313# touch /etc/mail/secrets 314# chmod 640 /etc/mail/secrets 315# chown root:_smtpd /etc/mail/secrets 316# echo "smtp.gmail.com username:password" \*(Gt /etc/mail/secrets 317# makemap /etc/mail/secrets 318.Ed 319.Pp 320.Nm 321would look like this: 322.Bd -literal -offset indent 323listen on lo0 324map aliases { source db "/etc/mail/aliases.db" } 325map secrets { source db "/etc/mail/secrets.db" } 326accept for local deliver to mbox 327accept for all relay via smtp.gmail.com tls enable auth 328.Ed 329.Pp 330In this second example, 331the aim is to permit mail relaying for any user that can authenticate 332using their normal login credentials. 333An RSA certificate must be provided to prove the server's identity. 334The mail server has an external interface pppoe0. 335Mail with a local destination should be sent to procmail. 336First, the RSA certificate is created: 337.Bd -literal -offset indent 338# openssl genrsa -out /etc/mail/certs/pppoe0.key 4096 339# openssl req -new -x509 -key /etc/mail/certs/pppoe0.key \e 340 -out /etc/mail/certs/pppoe0.crt -days 365 341# chmod 600 /etc/mail/certs/pppoe0.* 342.Ed 343.Pp 344In the example above, 345a certificate valid for one year was created. 346The configuration file would look like this: 347.Bd -literal -offset indent 348listen on lo0 349listen on pppoe0 tls enable auth 350map aliases { source db "/etc/mail/aliases.db" } 351accept for local deliver to mda "procmail -f -" 352accept from all for domain example.org deliver to mda "procmail -f -" 353accept for all relay 354.Ed 355.Sh SEE ALSO 356.Xr mailer.conf 5 , 357.Xr makemap 8 , 358.Xr smtpd 8 359.Sh HISTORY 360.Xr smtpd 8 361first appeared in 362.Ox 4.6 . 363