.\" $OpenBSD: smtpd.conf.5,v 1.206 2018/10/08 06:10:17 miko Exp $ .\" .\" Copyright (c) 2008 Janne Johansson .\" Copyright (c) 2009 Jacek Masiulaniec .\" Copyright (c) 2012 Gilles Chehade .\" .\" 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: October 8 2018 $ .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 When mail arrives, each .Dq RCPT TO: command generates a mail envelope. If an envelope matches any of a pre-designated set of criteria (using the .Ic match directive), the message is accepted for delivery. A copy of the message, as well as its associated envelopes, is saved in the mail queue and later dispatched according to an associated set of actions (using the .Ic action directive). If an envelope does not match any options, it is rejected. The match rules are evaluated sequentially, with the first match winning. .Pp The format of the configuration file is fairly flexible. 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. Argument names not beginning with a letter, digit, or underscore, as well as reserved words (such as .Ic listen , .Ic match , and .Cm port ) , must be quoted. Arguments containing whitespace should be surrounded by double quotes .Pq \&" . .Pp Macros can be defined that are later expanded in context. Macro names must start with a letter, digit, or underscore, and may contain any of those characters, but may not be reserved words. Macros are not expanded inside quotes. For example: .Bd -literal -offset indent lan_addr = "192.168.0.1" listen on $lan_addr listen on $lan_addr tls auth .Ed .Pp The syntax of .Nm is described below. .Bl -tag -width Ds .It Ic action Ar name method Op Ar options When the queue runner processes an envelope from the mail queue, it carries out the .Ic action .Ar name , selected by the .Ic match No ... Cm action directive when the message was received. The .Ic action directive provides configuration data for delivery attempts. Required lookups are performed at the time of each delivery attempt. Consequently, changing an .Ic action directive or the files it references and restarting the .Xr smtpd 8 daemon causes the changes to take effect for subsequent delivery attempts for the respective dispatcher .Ar name , even for messages that were already stuck in the queue prior to the configuration changes. .Pp The delivery .Ar method parameter may be one of the following: .Bl -tag -width Ds .It Cm expand\-only Only accept the message if a delivery method was specified in an aliases or .Pa .forward file. .It Cm forward\-only Only accept the message if the recipient results in a remote address after the processing of aliases or forward file. .It Cm lmtp Ar destination Op Ar rcpt-to Deliver the message to an LMTP server at .Ar destination . The location may be expressed as host:port or as a UNIX socket. .Pp Optionally, .Ar rcpt-to might be specified to use the recipient email address (after expansion) instead of the local user in the LMTP session as RCPT TO. .It Cm maildir Op Ar pathname Op Cm junk Deliver the message to the maildir in .Ar pathname if specified, or by default to .Pa ~/Maildir . .Pp The .Ar pathname may contain format specifiers that are expanded before use .Pq see Sx FORMAT SPECIFIERS . .Pp If the .Cm junk argument is provided, the message will be moved to the Junk folder if it contains a positive X-Spam header. .It Cm mbox Deliver the message to the user's mbox with .Xr mail.local 8 . .It Cm mda Ar command Delegate the delivery to a .Ar command that receives the message on its standard input. .Pp The .Ar command may contain format specifiers that are expanded before use .Pq see Sx FORMAT SPECIFIERS . .It Cm relay Relay the message to another SMTP server. .El .Pp The local delivery methods support additional options: .Bl -tag -width Ds .It Cm alias Pf < Ar table Ns > Use the mapping .Ar table for .Xr aliases 5 expansion. .It Xo .Cm ttl .Sm off .Ar n .Brq Cm s | m | h | d .Sm on .Xc Specify how long a message may remain in the queue. .It Cm user Ar username Specify the .Ar username for performing the delivery, to be looked up with .Xr getpwnam 3 . .Pp This is used for virtual hosting where a single username is in charge of handling delivery for all virtual users. .Pp This option is not usable with the .Cm mbox delivery method. .It Cm userbase Pf < Ar table Ns > Use the mapping .Ar table for user lookups instead of the .Xr getpwnam 3 function. .Pp The .Cm userbase does not apply for the .Cm user option. .It Cm virtual Pf < Ar table Ns > Use the mapping .Ar table for virtual expansion. The aliasing table format is described in .Xr table 5 . .It Cm wrapper Ar name Use the wrapper specified in .Cm mda wrapper . .El .Pp The relay delivery methods also support additional options: .Bl -tag -width Ds .It Cm backup Operate as a backup mail exchanger delivering messages to any mail exchanger with higher priority. .It Cm backup mx Ar name Operate as a backup mail exchanger delivering messages to any mail exchanger with higher priority than mail exchanger identified as .Ar name . .It Cm helo Ar heloname Advertise .Ar heloname as the hostname to other mail exchangers during the HELO phase. .It Cm helo\-src Pf < Ar table Ns > Use the mapping .Ar table to look up a hostname matching the source address, to advertise during the HELO phase. .It Cm host Ar relay-url Do not perform MX lookups but relay messages to the relay host described by .Ar relay-url . The format for .Ar relay-url is .Sm off .Op Ar proto No :// Op Ar label No @ .Ar host Op : Ar port . .Sm on The following protocols are available: .Pp .Bl -tag -width "smtp+notls" -compact .It smtp Normal SMTP session with opportunistic STARTTLS (the default). .It smtp+tls Normal SMTP session with mandatory STARTTLS. .It smtp+notls Plain text SMTP session without TLS. .It lmtp LMTP session. .It smtps SMTP session with forced TLS on connection. .El .Pp The .Ar label corresponds to an entry in a credentials table, as documented in .Xr table 5 . It is used with the .Dq smtp+tls and .Dq smtps protocols for authentication. Server certificates for those protocols are verified by default. .It Cm tls Op no-verify Require TLS to be used when relaying, using mandatory STARTTLS by default. When used with a smarthost, the protocol must not be .Dq smtp+notls:// . If .Op no-verify is specified, do not require a valid certificate. .It Cm auth Pf < Ar table Ns > Use the mapping .Ar table for connecting to .Ar relay-url using credentials. This option is usable only with .Cm host option. The credential table format is described in .Xr table 5 . .It Cm mail\-from Ar mailaddr Use .Ar mailaddr as the MAIL FROM address within the SMTP transaction. .It Cm src Ar address | Pf < Ar address Ns > Use the string or list table .Ar address for the source IP address. If the list contains more than one address, all of them are used in such a way that traffic is routed as efficiently as possible. .El .It Ic bounce Cm warn\-interval Ar delay Op , Ar delay ... Send warning messages to the envelope sender when temporary delivery failures cause a message to remain on the queue for longer than .Ar delay . Each .Ar delay parameter consists of a positive decimal integer and a unit .Cm s , m , h , or .Cm d . At most four .Ar delay parameters can be specified. The default is .Qq Ic bounce Cm warn\-interval No 4h , sending a single warning after four hours. .It Ic ca Ar caname Cm cert Ar cafile Associate the Certificate Authority (CA) certificate file .Ar cafile with host .Ar caname , and use that file as the CA certificate for that host. .Ar caname is the server's name, derived from the default hostname or set using either .Pa /etc/mail/mailname or using the .Ic hostname directive. .It Ic include Qq Ar pathname Replace this directive with the content of the additional configuration file at the absolute .Ar pathname . .It Ic listen on Ar interface Oo Ar family Oc Op Ar options Listen on the .Ar interface for incoming connections, using the same syntax as for .Xr ifconfig 8 . The .Ar interface parameter may also be an interface group, an IP address, or a domain name. Listening can optionally be restricted to a specific address .Ar family , which can be either .Cm inet4 or .Cm inet6 . .Pp The .Ar options are as follows: .Bl -tag -width Ds .It Cm auth Op Pf < Ar authtable Ns > Support SMTPAUTH: clients may only start SMTP transactions after successful authentication. Users are authenticated against either their own normal login credentials or a credentials table .Ar authtable , the format of which is described in .Xr table 5 . .It Cm auth\-optional Op Pf < Ar authtable Ns > Support SMTPAUTH optionally: clients need not authenticate, but may do so. This allows a .Ic listen on directive to both accept incoming mail from untrusted senders and permit outgoing mail from authenticated users (using .Cm match auth ) . It can be used in situations where it is not possible to listen on a separate port (usually the submission port, 587) for users to authenticate. .It Ic ca Ar caname For secure connections, use the CA certificate associated with .Ar caname (declared in a .Ic ca directive) as the CA certificate when verifying client certificates. .It Cm hostname Ar hostname Use .Ar hostname in the greeting banner instead of the default server name. .It Cm hostnames Pf < Ar names Ns > Override the server name for specific addresses. The .Ar names table contains a mapping of IP addresses to hostnames. If the address on which the connection arrives appears in the mapping, the associated hostname is used. .It Cm mask\-src Omit the .Sy from part when prepending .Dq Received headers. .It Cm no\-dsn Disable the DSN (Delivery Status Notification) extension. .It Cm pki Ar pkiname For secure connections, use the certificate associated with .Ar pkiname (declared in a .Ic pki directive) to prove a mail server's identity. .It Cm port Op Ar port Listen on the given .Ar port instead of the default port 25. .It Cm received\-auth In .Dq Received headers, report whether the session was authenticated and by which local user. .It Cm senders Pf < Ar users Ns > Op Cm masquerade Look up the authenticated user in the .Ar users mapping table to find the email addresses that user is allowed to submit mail as. In addition, if the .Cm masquerade option is provided, the From header is rewritten to match the sender provided in the SMTP session. .It Cm smtps Support SMTPS, by default on port 465. Mutually exclusive with .Cm tls . .It Cm tag Ar tag Clients connecting to the listener are tagged with the given .Ar tag . .It Cm tls Support STARTTLS, by default on port 25. Mutually exclusive with .Cm smtps . .It Cm tls\-require Op Cm verify Like .Cm tls , but force clients to establish a secure connection before being allowed to start an SMTP transaction. With the .Cm verify option, clients must also provide a valid certificate to establish an SMTP session. .El .It Ic listen on Cm socket Op Cm mask\-src Listen for incoming SMTP connections on the Unix domain socket .Pa /var/run/smtpd.sock . This is done by default, even if the directive is absent. If the .Cm mask\-src option is specified, printing of the HELO name, hostname, and IP address of the originating host is suppressed in Received: header lines. .\" XXX The option .\" Cm filter Ar string .\" is parsed, but not implemented, see smtpf_session.c. .It Ic match Ar options Cm action Ar name If at least one mail envelope matches the .Ar options of one .Ic match Cm action directive, receive the incoming message, put a copy into each matching envelope, and atomically save the envelopes to the mail spool for later processing by the respective dispatcher .Ar name . .Pp The following matching options are supported and can all be negated: .Bl -tag -width Ds .It Xo .Op Ic \&! .Cm for any .Xc Specify that session may address any destination. .It Xo .Op Ic \&! .Cm for local .Xc Specify that session may address any local domain. This is the default, and may be omitted. .It Xo .Op Ic \&! .Cm for domain .Ar domain | Pf < Ar domain Ns > .Xc Specify that session may address the string or list table .Ar domain . .It Xo .Op Ic \&! .Cm from any .Xc Specify that session may originate from any source. .It Xo .Op Ic \&! .Cm from local .Xc Specify that session may only originate from a local IP address, or from the local enqueuer. This is the default, and may be omitted. .It Xo .Op Ic \&! .Cm from socket .Xc Specify that session may only originate from the local enqueuer. .It Xo .Op Ic \&! .Cm from src .Ar address | Pf < Ar address Ns > .Xc Specify that session may only originate from string or list table .Ar address which can be a specific address or a subnet expressed in CIDR-notation. .El .Pp In addition, the following transaction options: .Bl -tag -width Ds .It Xo .Op Ic \&! .Cm auth .Xc Matches transactions which have been authenticated. .It Xo .Op Ic \&! .Cm helo .Ar helo-name | Pf < Ar helo-name Ns > .Xc Specify that session's HELO / EHLO should match the string or list table .Ar helo-name . .It Xo .Op Ic \&! .Cm mail\-from .Ar sender | Pf < Ar sender Ns > .Xc Specify that transactions's MAIL FROM should match the string or list table .Ar sender . .It Xo .Op Ic \&! .Cm rcpt\-to .Ar recipient | Pf < Ar recipient Ns > .Xc Specify that transaction's RCPT TO should match the string or list table .Ar recipient . .It Xo .Op Ic \&! .Cm tag Ar tag .Xc Matches transactions tagged with the given .Ar tag . .It Xo .Op Ic \&! .Cm tls .Xc Specify that transaction should take place in a TLS channel. .El .It Ic match Ar options Cm reject Reject the incoming message during the SMTP dialogue. The same .Ar options are supported as for the .Ic match Cm action directive. .It Ic mda Cm wrapper Ar name command Associate .Ar command with the mail delivery agent wrapper named .Ar name . When a local delivery specifies a wrapper, the .Ar command associated with the wrapper will be executed instead. The command may contain format specifiers .Pq see Sx FORMAT SPECIFIERS . .It Ic mta Cm max\-deferred Ar number When delivery to a given host is suspended due to temporary failures, cache at most .Ar number envelopes for that host such that they can be delivered as soon as another delivery succeeds to that host. The default is 100. .It Ic pki Ar pkiname Cm cert Ar certfile Associate certificate file .Ar certfile with host .Ar pkiname , and use that file to prove the identity of the mail server to clients. .Ar pkiname is the server's name, derived from the default hostname or set using either .Pa /etc/mail/mailname or using the .Ic hostname directive. If a fallback certificate or SNI is wanted, the .Sq * wildcard may be used as .Ar pkiname . .Pp A certificate chain may be created by appending one or many certificates, including a Certificate Authority certificate, to .Ar certfile . The creation of certificates is documented in .Xr starttls 8 . .It Ic pki Ar pkiname Cm key Ar keyfile Associate the key located in .Ar keyfile with host .Ar pkiname . .It Ic pki Ar pkiname Cm dhe Ar params Specify the DHE parameters to use for DHE cipher suites with host .Ar pkiname . Valid parameter values are .Cm none , .Cm legacy , and .Cm auto . For .Cm legacy , a fixed key length of 1024 bits is used, whereas for .Cm auto , the key length is determined automatically. The default is .Cm none , which disables DHE cipher suites. .It Ic queue Cm compression Store queue files in a compressed format. This may be useful to save disk space. .It Ic queue Cm encryption Op Ar key Encrypt queue files with .Xr EVP_aes_256_gcm 3 . If no .Ar key is specified, it is read with .Xr getpass 3 . If the string .Cm stdin or a single dash .Pq Ql \- is given instead of a .Ar key , the key is read from the standard input. .It Ic queue Cm ttl Ar delay Set the default expiration time for temporarily undeliverable messages, given as a positive decimal integer followed by a unit .Cm s , m , h , or .Cm d . The default is four days .Pq 4d . .It Ic smtp Cm ciphers Ar control Set the .Ar control string for .Xr SSL_CTX_set_cipher_list 3 . The default is .Qq HIGH:!aNULL:!MD5 . .It Ic smtp Cm max\-message\-size Ar size Reject messages larger than .Ar size , given as a positive number of bytes or as a string to be parsed with .Xr scan_scaled 3 . The default is .Qq 35M . .It Ic smtp Cm sub\-addr\-delim Ar character When resolving the local part of a local email address, ignore the ASCII .Ar character and all characters following it. The default is .Ql + . .It Ic table Ar name Oo Ar type : Oc Ns Ar pathname Tables provide additional configuration information for .Xr smtpd 8 in the form of lists or key-value mappings. The format of the entries depends on what the table is used for. Refer to .Xr table 5 for the exhaustive documentation. .Pp Each table is identified by an arbitrary, unique .Ar name . .Pp If the .Ar type is .Cm db , information is stored in a file created with .Xr makemap 8 ; if it is .Cm file or omitted, information is stored in a plain text file using the format described in .Xr table 5 . The .Ar pathname to the file must be absolute. .It Ic table Ar name Brq Ar value Op , Ar ... Instead of using a separate file, declare a list table containing the given static .Ar value Ns s . The table must contain at least one value and may declare multiple values as a comma-separated (whitespace optional) list. .It Ic table Ar name Brq Ar key Ns = Ns Ar value Op , Ar ... Instead of using a separate file, declare a mapping table containing the given static .Ar key Ns - Ns Ar value pairs. The table must contain at least one key-value pair and may declare multiple pairs as a comma-separated (whitespace optional) list. .El .Ss FORMAT SPECIFIERS Some configuration directives support expansion of their parameters at runtime. Such directives (for example .Ic action Cm maildir , .Ic action Cm mda ) may use format specifiers which are expanded before delivery or relaying. The following formats are currently supported: .Bl -column %{user.directory} -offset indent .It %{sender} Ta sender email address, may be empty string .It %{sender.user} Ta user part of the sender email address, may be empty .It %{sender.domain} Ta domain part of the sender email address, may be empty .It %{rcpt} Ta recipient email address .It %{rcpt.user} Ta user part of the recipient email address .It %{rcpt.domain} Ta domain part of the recipient email address .It %{dest} Ta recipient email address after expansion .It %{dest.user} Ta user part after expansion .It %{dest.domain} Ta domain part after expansion .It %{user.username} Ta local user .It %{user.directory} Ta home directory of the local user .It %{mbox.from} Ta name used in mbox From separator lines .It %{mda} Ta mda command, only available for mda wrappers .El .Pp Expansion formats also support partial expansion using the optional bracket notations with substring offset. For example, with recipient domain .Dq example.org : .Bl -column %{rcpt.domain[0:\-4]} -offset indent .It %{rcpt.domain[0]} Ta expands to Dq e .It %{rcpt.domain[1]} Ta expands to Dq x .It %{rcpt.domain[8:]} Ta expands to Dq org .It %{rcpt.domain[\-3:]} Ta expands to Dq org .It %{rcpt.domain[0:6]} Ta expands to Dq example .It %{rcpt.domain[0:\-4]} Ta expands to Dq example .El .Pp In addition, modifiers may be applied to the token. For example, with recipient .Dq User+Tag@Example.org : .Bl -column %{rcpt:lowercase|strip} -offset indent .It %{rcpt:lowercase} Ta expands to Dq user+tag@example.org .It %{rcpt:uppercase} Ta expands to Dq USER+TAG@EXAMPLE.ORG .It %{rcpt:strip} Ta expands to Dq User@Example.org .It %{rcpt:lowercase|strip} Ta expands to Dq user@example.org .El .Pp For security concerns, expanded values are sanitized and potentially dangerous characters are replaced with .Sq \&: . In situations where they are desirable, the .Dq raw modifier may be applied. For example, with recipient .Dq user+t?g@example.org : .Bl -column %{rcpt:raw} -offset indent .It %{rcpt} Ta expands to Dq user+t:g@example.org .It %{rcpt:raw} Ta expands to Dq user+t?g@example.org .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 /etc/mail/mailname If this file exists, the first line is used as the server name. Otherwise, the server name is derived from the local hostname returned by .Xr gethostname 3 , either directly if it is a fully qualified domain name, or by retrieving the associated canonical name through .Xr getaddrinfo 3 . .It Pa /var/run/smtpd.sock Unix domain socket for incoming SMTP connections. .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 .Pq Pa 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 "bob username:password" > /etc/mail/secrets .Ed .Pp .Nm would look like this: .Bd -literal -offset indent table aliases file:/etc/mail/aliases table secrets file:/etc/mail/secrets listen on lo0 action "local" mbox alias action "relay" relay host smtp+tls://bob@smtp.example.com \e auth match for local action "local" match for any action "relay" .Ed .Pp In this second example, the aim is to permit mail delivery and relaying only for users that can authenticate (using their normal login credentials). An RSA certificate must be provided to prove the server's identity. The mail server listens on all interfaces the default routes point to. Mail with a local destination is sent to an external MDA. First, the RSA certificate is created: .Bd -literal -offset indent # openssl genrsa \-out /etc/ssl/private/mail.example.com.key 4096 # openssl req \-new \-x509 \-key /etc/ssl/private/mail.example.com.key \e \-out /etc/ssl/mail.example.com.crt \-days 365 # chmod 600 /etc/ssl/mail.example.com.crt # chmod 600 /etc/ssl/private/mail.example.com.key .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 pki mail.example.com cert "/etc/ssl/mail.example.com.crt" pki mail.example.com key "/etc/ssl/private/mail.example.com.key" table aliases file:/etc/mail/aliases listen on lo0 listen on egress tls pki mail.example.com auth action mda_with_aliases mda "/path/to/mda \-f \-" alias action mda_without_aliases mda "/path/to/mda \-f \-" action "relay" relay match for local action mda_with_aliases match from any for domain example.com action mda_without_aliases match for any action "relay" match auth from any for any action "relay" .Ed .Pp For sites that wish to sign messages using DKIM, the .Sy dkimproxy package may be used as a filter. The following example is the same as the default configuration, but all outgoing mail is passed to dkimproxy_out on port 10027 for signing. The signed messages are received on port 10028 and tagged for relaying. .Bd -literal -offset indent table aliases file:/etc/mail/aliases listen on lo0 listen on lo0 port 10028 tag DKIM action "mbox" mbox alias action "relay" relay action relay_dkim relay host smtp://127.0.0.1:10027 match for local action "mbox" match tag DKIM for any action "relay" match for any action relay_dkim .Ed .Pp Sites that accept non-local messages may be able to cut down on the volume of spam received by rejecting forged messages that claim to be from the local domain. The following example uses a list table .Em other-relays to specify the IP addresses of relays that may legitimately originate mail with the owner's domain as the sender. .Bd -literal -offset indent table aliases file:/etc/mail/aliases table other-relays file:/etc/mail/other-relays listen on lo0 listen on egress action "mbox" mbox alias action "relay" relay match for local action "mbox" match for any action "relay" match !from src mail\-from "@example.com" for any \e reject match from any for domain example.com action "mbox" .Ed .Sh SEE ALSO .Xr mailer.conf 5 , .Xr table 5 , .Xr makemap 8 , .Xr smtpd 8 .Sh HISTORY .Xr smtpd 8 first appeared in .Ox 4.6 .