smtpd.conf (5) - Linux Manuals
smtpd.conf: Simple Mail Transfer Protocol daemon configuration file
NAME
smtpd.conf - Simple Mail Transfer Protocol daemon configuration fileDESCRIPTION
smtpd.conf is the configuration file for the mail daemon smtpd(8).The current line can be extended over multiple lines using a backslash (Sq \.) Comments can be put anywhere in the file using a hash mark (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 must be quoted. Arguments containing whitespace should be surrounded by double quotes (".)
Macros can be defined that will later be expanded in context. Macro names must start with a letter, digit, or underscore, and may contain any of those characters. Macro names may not be reserved words (for example listen, accept, port). Macros are not expanded inside quotes.
For example:
-
lan_addr = "192.168.0.1" listen on $lan_addr listen on $lan_addr tls auth
- include "/etc/opensmtpd/smtpd.conf.local"
- accept | reject
- smtpd(8) accepts and rejects messages based on information gathered during the SMTP session.
- tagged
- [ !] tag If specified, the rule will only be matched if the client session was tagged with tag.
- from any
- Make the rule match regardless of the IP of connecting client.
- from
- [ !] local The rule matches only locally originating connections. This is the default, and may be omitted.
- from
- [ !] source Pf < table > The rule matches if the connection is made from a client whose address is declared in the table table.
- sender
- [ !] Pf < senders > If specified, the rule will only be matched if the sender email address is found in the table senders. The table may contain complete email addresses or apply to an entire domain if prefixed with Sq @.
- for any [ alias < aliases >]
- Make the rule match regardless of the domain it is sent to. If specified, the table aliases is used for looking up alternative destinations for all addresses.
- for any virtual < vmap >
- Make the rule match regardless of the domain it is sent to. The vmap table will be used as the virtual domain mapping.
- for
- [ !]
domain
domain
[ alias < aliases >]
This rule applies to mail destined for the specified
domain.
This parameter supports the
Sq *
wildcard,
so that a single rule for all sub-domains can be used, for example:
- accept for domain "*.example.com" deliver to mbox
- for
- [ !] domain Pf < domains > [ alias < aliases >] This rule applies to mail destined to domains which are part of the table domains.
- for
- [ !]
domain
domain
virtual < users >
This rule applies to mail destined for the specified virtual
domain.
This parameter supports the
Sq *
wildcard,
so that a single rule for all sub-domains can be used, for example:
- accept for domain "*.example.com" \ virtual <users> deliver to mbox
- for
- [ !] domain Pf < domains > virtual < users > This rule applies to mail destined for the virtual domains specified in the table domains.
- for
- [ !] local [ alias < aliases >] This rule applies to mail destined to ``localhost'' and to the default server name. See the FILES entry for /etc/opensmtpd/mailname below for details of how the server name is determined.
- for
- [ !] local virtual < vmap > This rule applies to mail destined to ``localhost'' and to the default server name. The vmap table will be used as the virtual domain mapping.
- recipient
- [ !] Pf < recipients > If specified, the rule will only be matched if the recipient email address is found in the table recipients. The table may contain complete email addresses or apply to an entire domain if prefixed with Sq @.
- [ userbase < table >]
- Look up users in the table table instead of performing system lookups using the getpwnam(3) function.
- forward-only
- Mail is accepted for local recipients ONLY if it is redirected to an external address via an alias or a ~/.forward file.
- accept for domain opensmtpd.org forward-only
- deliver to lmtp
- [host: port | socket] [ rcpt-to] [ as user] Mail is delivered to host: port, or to the Ux socket over LMTP with the privileges of the specified user.
- deliver to maildir [path]
- Mail is added to a maildir. Its location, path, may contain format specifiers that are expanded before use (see .B FORMAT SPECIFIERS .) If path is not provided, then ~/Maildir is assumed.
- deliver to mbox
- Mail is delivered to the local user's system mailbox in /var/mail.
- deliver to mda program [ as user]
- Mail is piped to the specified program, which is run with the privileges of the specified user or the user the message is destined to. This parameter may use conversion specifiers that are expanded before use (see .B FORMAT SPECIFIERS .)
- Bk -words
- relay [ backup [mx]] [ as address] [ source < source >] [ hostname name] [ hostnames < names >] [ pki pkiname] [ tls [ verify]] Ek
- relay via
- host [ auth < auth >] [ as address] [ source < source >] [ hostname name] [ hostnames < names >] [ pki pkiname] [ verify]
- smtp://mx1.example.org # use SMTP smtp://mx1.example.org:4321 # use SMTP \ # with port 4321 lmtp://localhost:2026 # use LMTP \ # with port 2026
- tls://mx1.example.org # use TLS smtps://mx1.example.org # use SMTPS secure://mx1.example.org # try SMTPS and \ # fallback to TLS
- tls+auth://label@mx.example.org # over TLS smtps+auth://label@mx.example.org # over SMTPS secure+auth://label@mx.example.org # over either \ # SMTPS or TLS
- expire
- Sm off n {s | m | h | d} Sm on Specify how long a message that matched this rule can stay in the queue.
- bounce-warn
- Sm off
n
{s | m | h | d}
[,
Sm on
...
]
Specify the delays for which temporary failure reports must be generated
when messages are stuck in the queue.
For example:
- bounce-warn 1h, 6h, 2d
- ca hostname certificate cafile
- Associate a custom CA certificate located in cafile with hostname.
- ciphers cipher-list
- Specify an alternate list of ciphers to use when establishing TLS sessions. It is highly recommended to avoid making use of this option unless there is a good understanding of the implications.
- expire
- Sm off
n
{s | m | h | d}
Sm on
Specify how long a message can stay in the queue.
The default value is 4d.
For example:
- expire 4d # expire after 4 days expire 10h # expire after 10 hours
- filter name filter [arguments]
- Specify a filter with the given name and the program filter using the given filter arguments. Filters are used to hook into the SMTP dialog and provide additional filtering options for smtpd(8).
- filter name chain filter ...
- Specify a filter chain with the given name and filters.
- limit session
- {max-rcpt | max-mails} num Instruct smtpd(8) to accept a maximum number of recipients or emails at once in the receiving queue. Defaults are 100 for max-mails and 1000 for max-rcpt.
- limit mta
- [ for domain domain] family Instruct smtpd(8) to only use the specified address family for outgoing connections. Accepted values are inet4 and inet6. If a domain is specified, the restriction only applies when connecting to MXs for this domain.
- limit scheduler max-inflight num
- Suspend the scheduling of envelopes for deliver/relay until the number of inflight envelopes falls below num. Changing the default value might degrade performance.
- listen on socket
- [ filter name] [ mask-source] br Bk -words listen on interface [family] [ port port] [ filter name] [ tls | tls-require | tls-require verify | smtps | secure] [ pki pkiname] [ ca caname] [ auth | auth-optional [< authtable >]] [ tag tag] [ hostname hostname] [ hostnames < names >] [ senders < users >[masquerade]] [ mask-source] [ received-auth] [ no-dsn] Ek
- max-message-size n
- Specify a maximum message size of n bytes. The argument may contain a multiplier, as documented in scan_scaled(3). The default maximum message size is 35MB if none is specified.
- pki hostname certificate certfile
- Associate the certificate located in certfile with hostname.
- pki hostname key keyfile
- Associate the key located in keyfile with hostname.
- pki hostname dhe params
- Specify the DHE parameters to use for DHE cipher suites with hostname. Valid parameter values are none, legacy and auto. For legacy a fixed key length of 1024 bits is used, whereas for auto the key length is determined automatically. The default is none, which disables DHE cipher suites.
- queue compression
- Enable transparent compression of envelopes and messages. The only supported algorithm at the moment is gzip. Envelopes and messages may be inspected using the smtpctl(8) or gzcat(1) utilities.
- queue encryption [key key]
- Enable transparent encryption of envelopes and messages.
key
must be a 16-byte random key in hexadecimal representation.
It can be obtained using the
openssl(1)
utility as follow:
- $ openssl rand -hex 16
- table name [type:] config
- Tables are used to provide additional configuration information for 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 table(5) for the exhaustive documentation.
- table name {value [, ...]}
- Tables containing list of static values may be declared using an inlined notation.
- table name {key=value [, ...]}
- Tables containing static key-value mappings may be declared using an inlined notation.
FORMAT SPECIFIERS
Some configuration directives support expansion of their parameters at runtime. Such directives (for example deliver to maildir, deliver to mda) may use format specifiers which will be expanded before delivery or relaying. The following formats are currently supported:-
- %{sender} Ta sender email address
- %{sender.user} Ta user part of the sender email address
- %{sender.domain} Ta domain part of the sender email address
- %{rcpt} Ta recipient email address
- %{rcpt.user} Ta user part of the recipient email address
- %{rcpt.domain} Ta domain part of the recipient email address
- %{dest} Ta recipient email address after expansion
- %{dest.user} Ta user part after expansion
- %{dest.domain} Ta domain part after expansion
- %{user.username} Ta local user
- %{user.directory} Ta home directory of the local user
Expansion formats also support partial expansion using the optional bracket notations with substring offset. For example, with recipient domain ``example.org :''
-
- %{rcpt.domain[0]} Ta expands to ``e''
- %{rcpt.domain[1]} Ta expands to ``x''
- %{rcpt.domain[8:]} Ta expands to ``org''
- %{rcpt.domain[-3:]} Ta expands to ``org''
- %{rcpt.domain[0:6]} Ta expands to ``example''
- %{rcpt.domain[0:-4]} Ta expands to ``example''
In addition, modifiers may be applied to the token. For example, with recipient ``User+Tag [at] Example.org :''
-
- %{rcpt:lowercase} Ta expands to ``user+tag [at] example.org''
- %{rcpt:uppercase} Ta expands to ``USER+TAG [at] EXAMPLE.ORG''
- %{rcpt:strip} Ta expands to ``User [at] Example.org''
- %{rcpt:lowercase|strip} Ta expands to ``user [at] example.org''
For security concerns, expanded values are sanitized and potentially dangerous characters are replaced with Sq :. In situations where they are desirable, the ``raw'' modifier may be applied. For example, with recipient ``user+t?g@example.org :''
-
- %{rcpt} Ta expands to ``user+t:g@example.org''
- %{rcpt:raw} Ta expands to ``user+t?g@example.org''
FILES
-
- /etc/opensmtpd/smtpd.conf
- Default smtpd(8) configuration file.
- /etc/opensmtpd/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 gethostname(3), either directly if it is a fully qualified domain name, or by retrieving the associated canonical name through getaddrinfo(3).
- /var/spool/smtpd/
- Spool directories for mail during processing.
EXAMPLES
The default smtpd.conf file listens on the loopback network interface (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.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:
-
# touch /etc/opensmtpd/secrets # chmod 640 /etc/opensmtpd/secrets # chown root:_smtpd /etc/opensmtpd/secrets # echo "label username:password" > /etc/opensmtpd/secrets
- table aliases file:/etc/opensmtpd/aliases table secrets file:/etc/opensmtpd/secrets listen on lo0 accept for local alias <aliases> deliver to mbox accept for any relay via tls+auth://label@smtp.example.com \ auth <secrets>
- # openssl genrsa -out /etc/ssl/private/mail.example.com.key 4096 # openssl req -new -x509 -key /etc/ssl/private/mail.example.com.key \ -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
- pki mail.example.com certificate "/etc/ssl/mail.example.com.crt" pki mail.example.com key "/etc/ssl/private/mail.example.com.key" table aliases file:/etc/opensmtpd/aliases listen on lo0 listen on egress tls pki mail.example.com auth accept for local alias <aliases> deliver to mda "/path/to/mda -f -" accept from any for domain example.com \ deliver to mda "/path/to/mda -f -" accept for any relay
- table aliases file:/etc/opensmtpd/aliases listen on lo0 listen on lo0 port 10028 tag DKIM accept for local alias <aliases> deliver to mbox accept tagged DKIM for any relay accept from local for any relay via smtp://127.0.0.1:10027
- table aliases file:/etc/opensmtpd/aliases table other-relays file:/etc/opensmtpd/other-relays listen on lo0 listen on egress accept for local alias <aliases> deliver to mbox accept from local for any relay reject from ! source <other-relays> sender "@example.com" for any accept from any for domain example.com \ alias <aliases> deliver to mbox
HISTORY
smtpd(8) first appeared in OpenBSD 4.6.