OpenSMTPD Options [FAQ Index]

• Introduction
• Table Option
• Listen Option
• Miscellaneous Options
• Example Options

Introduction

Table Option

table name [type:]config

The table is identified using table name name; the name itself is arbitrarily chosen. type specifies the table backend, and should be one of the following:

db

Information is stored in a file created using makemap(8).

file

Information is stored in a plain text file using the same format as used to generate makemap(8) mappings. This is the default.

config specifies a configuration file for the table data. It must be an absolute path to a file for the “file” and “db” table types.

table name {value [, ...]}

Tables containing list of static values may be declared using an inlined notation. The table is identified using table name name; the name itself is arbitrarily chosen. The table must contain at least one value and may declare many values as a list of comma-separated strings.

table name {key=value [, ...]}

Tables containing static key-value mappings may be declared using an inlined notation. The table is identified using table name name; the name itself is arbitrarily chosen. The table must contain at least one key-value mapping and may declare many mappings as a list of comma-separated key=value descriptions.

Listen Option

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] [no-dsn] [dsn-notify disable] [dsn-ret headers]

Specify an interface and port to listen on. An interface group, an IP address or a domain name may be used in place of interface. The family parameter can be used to listen only on specific address family. Accepted values are inet4 and inet6.

A filter may be specified to use a filter or filter chain with the given name on SMTP transactions.

Secured connections are provided either using STARTTLS (tls), by default on port 25, or SMTPS (smtps), by default on port 465. tls-require may be used to force clients to establish a secure connection before being allowed to start an SMTP transaction.

If tls-require verify is specified, the client must provide a valid certificate to be able to establish an SMTP session.

secure may be specified to provide both STARTTLS and SMTPS services. Host certificates may be used for these connections, and must be previously declared using the pki directive. If pki is specified, a certificate matching name is searched for. Moreover, a previously declared ca directive may be specified to use a custom CA certificate.

If the auth parameter is used, then a client may only start an SMTP transaction after a successful authentication. Any remote sender that passed SMTPAUTH is treated as if it was the server's local user that was sending the mail. This means that filter rules using from local will be matched. If auth-optional is specified, then SMTPAUTH is not required to establish an SMTP transaction. This is only useful to let a listener accept incoming mail from untrusted senders and outgoing mail from authenticated users in situations where it is not possible to listen on the submission port.

Both auth and auth-optional accept an optional table as a parameter. When provided, credentials are looked up in this table. The credentials format is described in table(5).

If the tag parameter is used, then clients connecting to the listener will be tagged tag.

If the hostname parameter is used, then it will be used in the greeting banner instead of the default server name. The hostnames parameter overrides the server name for specific addresses. Table names contains a mapping of IP addresses to hostnames and smtpd(8) will use the hostname that matches the address on which the connection arrives if it is found in the mapping.

If the senders parameter is used, then smtpd(8) will lookup in a mapping of username to email addresses if the authenticated user is allowed to submit mail as the sender that was provided in the SMTP session. In addition, if the masquerade option is provided, the From header will be rewritten to match the sender provided in the SMTP session.

If the mask-source parameter is used, then the listener will skip the from part when prepending the “Received” header.

If the no-dsn parameter is used, DSN (Delivery Status Notification) extension will not be enabled. If the dsn-notify parameter is used with the disable argument, the listener will not generate DSN upon delivery failures. If the dsn-ret parameter is used with the headers argument, DSN will be generated without the content of the original message.

Miscellaneous Options

bounce-warn n{s|m|h|d}[, ...]

Specify the delays for which temporary failure reports must be generated when messages are stuck in the queue. The default is 4h.

expire n{s|m|h|d}

Specify how long a message can stay in the queue. The default value is 4d.

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.

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.

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 follows:

# openssl rand -hex 16

If the key parameter is not specified, it is read with getpass(3) at startup. If key is stdin, then it is read from the standard input at startup. The only supported algorithm is AES-256 in GCM mode. Envelopes and messages may be inspected using the smtpctl(8) utility. Queue encryption can be used with queue compression and will always perform compression before encryption.

Options Example

table hosts file:/etc/mail/hosts   # set hostnames table
listen on egress hostnames <hosts> # use server name from hosts table

bounce-warn 1h, 6h, 2d             # generate a failure report when an
                                   # envelope is in the queue for more
                                   # than 1 hour, 6 hours, and 2 days

expire 4d                          # expire after 4 days
expire 10h	                   # expire after 10 hours

limit session max-rcpts 500        # limit recipients in queue to 500
limit session max-mails 50         # limit mails in queue to 50
limit mta for gmail.com inet4      # no ipv6 with gmail.com
limit scheduler max-inflight 2500  # suspend scheduling at 2500

max-message-size 20M               # set maximum message size to 20MB

queue compression                  # enable queue compression
queue encryption                   # enable queue encryption reading the
                                   # key on startup