---
name: "smtpd.conf"
section: "5"
platform: "linux"
package: "opensmtpd"
version: "7.9.0p0-1"
release: "Arch Linux 2026-11-01"
platforms: ["linux", "openbsd"]
url: "https://new.carta.tech/smtpd.conf"
---

# smtpd.conf(5)

SMTP daemon configuration file

## NAME

**smtpd.conf** – SMTP daemon configuration file

## DESCRIPTION

**smtpd.conf** is the configuration file for the mail daemon [smtpd(8)](/smtpd/8.md).

When mail arrives, each “RCPT TO:” command generates a mail envelope. If an envelope matches any of a pre-designated set of criteria (using the **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 **action** directive). If an envelope does not match any options, it is rejected. The match rules are evaluated sequentially, with the first match winning.

The format of the configuration file is fairly flexible. The current line can be extended over multiple lines using a backslash (‘\\’). Comments can be put anywhere in the file using a hash mark (‘#’), 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. Arguments not beginning with a letter, digit, or underscore, as well as reserved words (such as **listen**, **match**, and **port**), must be quoted. Arguments containing whitespace should be surrounded by double quotes (").

A macro is defined with a command of the form *name*=*value*. The macro *name* can contain letters, digits, and underscores and cannot be a reserved word. Within unquoted arguments, the string $*name* is later expanded to *value*.

For example:

```
lan_addr = "192.168.0.1"
listen on $lan_addr
listen on $lan_addr tls auth
```

The syntax of **smtpd.conf** is described below.

- **action** *name* *method* \[*options*\]

  When the queue runner processes an envelope from the mail queue, it carries out the **action** *name*, selected by the **match** ... **action** directive when the message was received. The **action** directive provides configuration data for delivery attempts. Required lookups are performed at the time of each delivery attempt. Consequently, changing an **action** directive or the files it references and restarting the [smtpd(8)](/smtpd/8.md) daemon causes the changes to take effect for subsequent delivery attempts for the respective dispatcher *name*, even for messages that were already stuck in the queue prior to the configuration changes.

  The delivery *method* parameter may be one of the following:

  - **expand-only**

    Only accept the message if a delivery method was specified in an aliases or *.forward* file.

  - **forward-only**

    Only accept the message if the recipient results in a remote address after the processing of aliases or forward file.

  - **lmtp** *destination* \[**rcpt-to**\]

    Deliver the message to an LMTP server at *destination*. The location may be expressed as host:port or as a UNIX socket.

    Optionally, **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.

  - **maildir** \[*pathname*\] \[**junk**\]

    Deliver the message to the maildir in *pathname* if specified, or by default to *~/Maildir*.

    The *pathname* may contain format specifiers that are expanded before use (see FORMAT SPECIFIERS).

    If the **junk** argument is provided, the message will be moved to the ‘Junk’ folder if it contains a positive ‘X-Spam’ header. This folder will be created under *pathname* if it does not yet exist.

  - **mbox**

    Deliver the message to the user's mbox with [mail.local(8)](/mail.local/8.md).

  - **mda** *command*

    Delegate the delivery to a *command* that receives the message on its standard input (see MDA COMMANDS).

    The *command* may contain format specifiers that are expanded before use (see FORMAT SPECIFIERS).

  - **relay**

    Relay the message to another SMTP server.

    The local delivery methods support additional options:

    - **alias** \<*table*\>

      Use the mapping *table* for [aliases(5)](/aliases/5.md) expansion.

    -

      **ttl** *n* {**s**\|**m**\|**h**\|**d**} Specify how long a message may remain in the queue.

    - **user** *username*

      Specify the *username* for performing the delivery, to be looked up with [getpwnam(3)](/getpwnam/3.md).

      This is used for virtual hosting where a single username is in charge of handling delivery for all virtual users.

      This option is not usable with the **mbox** delivery method.

      Only the delivery user's *.forward* file will be processed.

    - **userbase** \<*table*\>

      Use the mapping *table* for user lookups instead of the [getpwnam(3)](/getpwnam/3.md) function.

      The **userbase** does not apply to the **user** option.

    - **virtual** \<*table*\>

      Use the mapping *table* for virtual expansion. The aliasing table format is described in [table(5)](/table/5.md).

    - **wrapper** *name*

      Use the wrapper specified in **mda** **wrapper**.

      The relay delivery methods also support additional options:

      - **backup**

        Operate as a backup mail exchanger delivering messages to any mail exchanger with higher priority.

      - **backup** **mx** *name*

        Operate as a backup mail exchanger delivering messages to any mail exchanger with higher priority than mail exchanger identified as *name*.

      - **ca** *caname*

        For secure connections, use the certificate authority associated with *caname* (declared in a **ca** directive) to validate the server's identity.

      - **helo** *heloname*

        Advertise *heloname* as the hostname to other mail exchangers during the HELO phase.

      - **helo-src** \<*table*\>

        Use the mapping *table* to look up a hostname matching the source address, to advertise during the HELO phase.

      - **domain** \<*domains*\>

        Do not perform MX lookups but look up destination domain in *domains* and use matching relay url as relay host.

      - **host** *relay-url*

        Do not perform MX lookups but relay messages to the relay host described by *relay-url*. The format for *relay-url* is \[*proto*://\[*label*@\]\] *host*\[:*port*\]. The following protocols are available:

        - smtp

          Normal SMTP session with opportunistic STARTTLS (the default).

        - smtp+tls

          Normal SMTP session with mandatory STARTTLS.

        - smtp+notls

          Plain text SMTP session without TLS.

        - lmtp

          LMTP session. *port* is required.

        - smtps

          SMTP session with forced TLS on connection. The default port is 465.

          Unless noted, *port* defaults to 25.

          The *label* corresponds to an entry in a credentials table, as documented in [table(5)](/table/5.md). It is used with the “smtp+tls” and “smtps” protocols for authentication. Server certificates for those protocols are verified by default.

      - **pki** *pkiname*

        For secure connections, use the certificate associated with *pkiname* (declared in a **pki** directive) to prove the client's identity to the remote mail server.

      - **srs**

        When relaying a mail resulting from a forward, use the Sender Rewriting Scheme to rewrite sender address.

      - **tls** \[**no-verify**\]

        Require TLS to be used when relaying, using mandatory STARTTLS by default. When used with a smarthost, the protocol must not be “smtp+notls://”. If **no-verify** is specified, do not require a valid certificate.

      - **protocols** *protostr*

        Define the protocol versions to be used for TLS sessions. Refer to the [tls\_config\_parse\_protocols(3)](/tls_config_parse_protocols/3.md) manpage for the format of *protostr*.

      - **ciphers** *cipherstr*

        Define the list of ciphers that may be used for TLS sessions. Refer to the [tls\_config\_set\_ciphers(3)](/tls_config_set_ciphers/3.md) manpage for the format of *cipherstr*.

      - **auth** \<*table*\>

        Use the mapping *table* for connecting to *relay-url* using credentials. This option is usable only with **host** option. The credential table format is described in [table(5)](/table/5.md).

      - **mail-from** *mailaddr*

        Use *mailaddr* as the MAIL FROM address within the SMTP transaction.

      - **src** *sourceaddr* \| \<*sourceaddr*\>

        Use the string or list table *sourceaddr* for the source IP address, which is useful on machines with multiple interfaces. 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.

- **admd** *authservid*

  The Administrative Management Domain this mail server belongs to. The authservid will be forwarded to filters using it to identify or mark authentication-results headers. If omitted, it defaults to the server name.

- **bounce** **warn-interval** *delay* \[, *delay* *...*\]

  Send warning messages to the envelope sender when temporary delivery failures cause a message to remain in the queue for longer than *delay*. Each *delay* parameter consists of a positive decimal integer and a unit **s**, **m**, **h**, or **d**. At most four *delay* parameters can be specified. The default is "**bounce** **warn-interval** 4h", sending a single warning after four hours.

- **ca** *caname* **cert** *cafile*

  Associate the Certificate Authority (CA) certificate file *cafile* with ca entry *caname*. The ca entry can be referenced in **listen** **on** and **action** **...** **relay** rules.

- **filter** *chain-name* **chain** {*filter-name* \[, *...*\]}

  Register a chain of filters *chain-name*, consisting of the filters listed in *filter-name*. Filters in a filter chain are executed in order of declaration for each phase that they are registered for. A filter chain may be used in place of a filter for any directive except filter chains themselves.

- **filter** *filter-name* **phase** *phase-name* **match** *conditions* *decision*

  Register a filter *filter-name*. A *decision* about what to do with the mail is taken at phase *phase-name* when matching *conditions*. Phases, matching conditions, and decisions are described in MAIL FILTERING, below.

- **filter** *filter-name* **proc** *proc-name*

  Register "proc" filter *filter-name* backed by the *proc-name* process.

- **filter** *filter-name* **proc-exec** *command*

  Register and execute "proc" filter *filter-name* from *command*, conformant with the [smtpd-filters(7)](/smtpd-filters/7.md) API. If *command* starts with a slash it is executed with an absolute path, otherwise it will be run from “/usr/lib/smtpd/opensmtpd”.

- **include** "*pathname*"

  Replace this directive with the content of the additional configuration file at the absolute *pathname*.

- **listen** **on** *interface* \[*family*\] \[*options*\]

  Listen on the *interface* for incoming connections, using the same syntax as [ifconfig(8)](/ifconfig/8.md). The *interface* parameter may also be an interface group, an IP address, or a domain name. Listening can optionally be restricted to a specific address *family*, which can be either **inet4** or **inet6**.

  The *options* are as follows:

  - **auth** \[\<*authtable*\>\]

    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 *authtable*, the format of which is described in [table(5)](/table/5.md).

  - **auth-optional** \[\<*authtable*\>\]

    Support SMTPAUTH optionally: clients need not authenticate, but may do so. This allows a **listen** **on** directive to both accept incoming mail from untrusted senders and permit outgoing mail from authenticated users (using **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.

  - **ca** *caname*

    For secure connections, use the CA certificate associated with *caname* (declared in a **ca** directive) as the CA certificate when verifying client certificates.

  - **filter** *name*

    Apply filter *name* on connections handled by this listener.

  - **hostname** *hostname*

    Use *hostname* in the greeting banner instead of the default server name.

  - **hostnames** \<*names*\>

    Override the server name for specific addresses. The *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.

  - **mask-src**

    Omit the **from** part when prepending “Received” headers.

  - **no-dsn**

    Disable the DSN (Delivery Status Notification) extension.

  - **pki** *pkiname*

    For secure connections, use the certificate associated with *pkiname* (declared in a **pki** directive) to prove a mail server's identity. This option can be used multiple times to provide alternate certificates for SNI.

  - **port** \[*port*\]

    Listen on the given *port* instead of the default port 25.

  - **proxy-v2**

    Support the PROXYv2 protocol, appropriately rewriting the source address received from proxy.

  - **received-auth**

    In “Received” headers, report whether the session was authenticated and by which local user.

  - **senders** \<*users*\> \[**masquerade**\]

    Look up the authenticated user in the *users* mapping table to find the email addresses that user is allowed to submit mail as. In addition, if the **masquerade** option is provided, the From header is rewritten to match the sender provided in the SMTP session.

  - **smtps** \[**verify**\]

    Support SMTPS, by default on port 465. Mutually exclusive with **tls**. With the **verify** option, clients must also provide a valid certificate to establish an SMTP session.

  - **tag** *tag*

    Clients connecting to the listener are tagged with the given *tag*.

  - **tls**

    Support STARTTLS, by default on port 25. Mutually exclusive with **smtps**.

  - **tls-require** \[**verify**\]

    Like **tls**, but force clients to establish a secure connection before being allowed to start an SMTP transaction. With the **verify** option, clients must also provide a valid certificate to establish an SMTP session.

  - **protocols** *protostr*

    Define the protocol versions to be used for TLS sessions. Refer to the [tls\_config\_parse\_protocols(3)](/tls_config_parse_protocols/3.md) manpage for the format of *protostr*.

  - **ciphers** *cipherstr*

    Define the list of ciphers that may be used for TLS sessions. Refer to the [tls\_config\_set\_ciphers(3)](/tls_config_set_ciphers/3.md) manpage for the format of *cipherstr*.

- **listen** **on** **socket** \[*options*\]

  Listen for incoming SMTP connections on the Unix domain socket */run/smtpd.sock*. This is done by default, even if the directive is absent.

  The *options* are as follows:

  - **filter** *name*

    Apply filter *name* on connections handled by this listener.

  - **mask-src**

    Omit the **from** part when prepending “Received” headers.

  - **no-dsn**

    Disable the DSN (Delivery Status Notification) extension.

  - **tag** *tag*

    Clients connecting to the listener are tagged with the given *tag*.

- **match** *options* **action** *name*

  If at least one mail envelope matches the *options* of one **match** **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 *name* which has to be declared beforehand with the **action** directive.

  The following matching options are supported and can all be negated:

  -

    \[**!**\] **for** **any** Specify that session may address any destination.

  -

    \[**!**\] **for** **local** Specify that session may address any local domain. This is the default, and may be omitted.

  -

    \[**!**\] **for** **domain** \[**regex**\] *domain* \| \<*domain*\> Specify that session may address the string or list table *domain*. The **regex** keyword is required if *domain* is a regular expression or table of regular expressions.

  -

    \[**!**\] **for** **rcpt-to** \[**regex**\] *recipient* \| \<*recipient*\> Specify that session may address the string or list table *recipient*. The **regex** keyword is required if *recipient* is a regular expression or table of regular expressions.

  -

    \[**!**\] **from** **any** Specify that session may originate from any source.

  -

    \[**!**\] **from** **auth** Specify that session may originate from any authenticated user, no matter the source IP address.

  -

    \[**!**\] **from** **auth** \[**regex**\] *user* \| \<*user*\> Specify that session may originate from authenticated user or user list *user*, no matter the source IP address. The **regex** keyword is required if *user* is a regular expression or table of regular expressions.

  -

    \[**!**\] **from** **local** Specify that session may only originate from a local IP address, or from the local enqueuer. This is the default, and may be omitted.

  -

    \[**!**\] **from** **mail-from** \[**regex**\] *sender* \| \<*sender*\> Specify that session may originate from sender or sender list *sender*, no matter the source IP address. The **regex** keyword is required if *sender* is a regular expression or table of regular expressions.

  -

    \[**!**\] **from** **rdns** Specify that session may only originate from an IP address that resolves to a reverse DNS.

  -

    \[**!**\] **from** **rdns** \[**regex**\] *hostname* \| \<*hostname*\> Specify that session may only originate from an IP address that resolves to a reverse DNS matching string or list string *hostname*. The **regex** keyword is required if *hostname* is a regular expression or table of regular expressions.

  -

    \[**!**\] **from** **socket** Specify that session may only originate from the local enqueuer.

  -

    \[**!**\] **from** **src** \[**regex**\] *address* \| \<*address*\> Specify that session may only originate from string or list table *address* which can be a specific address or a subnet expressed in CIDR-notation. The **regex** keyword is required if *address* is a regular expression or table of regular expressions.

    In addition, the following transaction options may be matched:

    -

      \[**!**\] **auth** Matches transactions which have been authenticated.

    -

      \[**!**\] **auth** \[**regex**\] *username* \| \<*username*\> Matches transactions which have been authenticated for user or user list *username*. The **regex** keyword is required if *username* is a regular expression or table of regular expressions.

    -

      \[**!**\] **helo** \[**regex**\] *helo-name* \| \<*helo-name*\> Specify that session's HELO / EHLO should match the string or list table *helo-name*. The **regex** keyword is required if *helo-name* is a regular expression or table of regular expressions.

    -

      \[**!**\] **mail-from** \[**regex**\] *sender* \| \<*sender*\> Specify that transaction's MAIL FROM should match the string or list table *sender*. The **regex** keyword is required if *sender* is a regular expression or table of regular expressions.

    -

      \[**!**\] **rcpt-to** \[**regex**\] *recipient* \| \<*recipient*\> Specify that transaction's RCPT TO should match the string or list table *recipient*. The **regex** keyword is required if *recipient* is a regular expression or table of regular expressions.

    -

      \[**!**\] **tag** \[**regex**\] *tag* Matches transactions tagged with the given *tag*. The **regex** keyword is required if *tag* is a regular expression.

    -

      \[**!**\] **tls** Specify that transaction should take place in a TLS channel.

- **match** *options* **reject**

  Reject the incoming message during the SMTP dialogue. The same *options* are supported as for the **match** **action** directive.

- **mda** **wrapper** *name* *command*

  Associate *command* with the mail delivery agent wrapper named *name*. When a local delivery specifies a wrapper, the *command* associated with the wrapper will be executed instead. The command may contain format specifiers (see FORMAT SPECIFIERS).

- **mta** **max-deferred** *number*

  When delivery to a given host is suspended due to temporary failures, cache at most *number* envelopes for that host such that they can be delivered as soon as another delivery succeeds to that host. The default is 100.

- **pki** *pkiname* **cert** *certfile*

  Associate certificate file *certfile* with pki entry *pkiname*. The pki entry defines a keypair configuration that can be referenced in listener rules and relay actions.

  A certificate chain may be created by appending one or many certificates, including a Certificate Authority certificate, to *certfile*. The creation of certificates is documented in [starttls(8)](/starttls/8.md).

- **pki** *pkiname* **key** *keyfile*

  Associate the key located in *keyfile* with pki entry *pkiname*.

- **pki** *pkiname* **dhe** *params*

  Specify the DHE parameters to use for DHE cipher suites with pki entry *pkiname*. 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.

- **proc** *proc-name* *command*

  Register an external process named *proc-name* from *command*, conformant with the [smtpd-filters(7)](/smtpd-filters/7.md) API. Such processes may be used to share the same instance between multiple filters. If *command* starts with a slash it is executed with an absolute path, otherwise it will be run from “/usr/lib/smtpd/opensmtpd”.

- **queue** **compression**

  Store queue files in a compressed format. This may be useful to save disk space.

- **queue** **encryption** \[*key*\]

  Encrypt queue files with EVP\_aes\_256\_gcm(3). If no *key* is specified, it is read with [getpass(3)](/getpass/3.md). If the string **stdin** or a single dash (‘-’) is given instead of a *key*, the key is read from the standard input.

- **queue** **ttl** *delay*

  Set the default expiration time for temporarily undeliverable messages, given as a positive decimal integer followed by a unit **s**, **m**, **h**, or **d**. The default is four days (4d).

- **smtp** **ciphers** *control*

  Set the *control* string for SSL\_CTX\_set\_cipher\_list(3). The default is "HIGH:!aNULL:!MD5".

- **smtp** **limit** **max-mails** *count*

  Limit the number of messages to *count* for each session. The default is 100.

- **smtp** **limit** **max-rcpt** *count*

  Limit the number of recipients to *count* for each transaction. The default is 1000.

- **smtp** **max-message-size** *size*

  Reject messages larger than *size*, given as a positive number of bytes or as a string to be parsed with scan\_scaled(3). The default is "35M".

- **smtp** **sub-addr-delim** *character*

  When resolving the local part of a local email address, ignore the ASCII *character* and all characters following it. The default is ‘+’.

- **srs** **key** \[**backup**\] *secret*

  Set the secret key to use for SRS, the Sender Rewriting Scheme. The **backup** option can be specified to set a secret key to use as a fallback for SRS; this can be used to implement SRS key rotation.

- **srs** **ttl** *delay*

  Set the time-to-live delay for SRS envelopes. After this delay, a bounce reply to the SRS address will be discarded to limit risks of forged addresses. The default is four days (4d).

- **table** *name* \[*type*:\]*pathname*

  Tables provide additional configuration information for [smtpd(8)](/smtpd/8.md) 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)](/table/5.md) for the exhaustive documentation.

  Each table is identified by an arbitrary, unique *name*.

  If the *type* is **db**, information is stored in a file created with [makemap(8)](/makemap/8.md); if it is **file** or omitted, information is stored in a plain text file using the format described in [table(5)](/table/5.md). The *pathname* to the file must be absolute.

- **table** *name* {*value* \[, *...*\]}

  Instead of using a separate file, declare a list table containing the given static *value*s. The table must contain at least one value and may declare multiple values as a comma-separated (whitespace optional) list.

- **table** *name* {*key*=*value* \[, *...*\]}

  Instead of using a separate file, declare a mapping table containing the given static *key*-*value* pairs. The table must contain at least one key-value pair and may declare multiple pairs as a comma-separated (whitespace optional) list.

### MAIL FILTERING

In a regular workflow, [smtpd(8)](/smtpd/8.md) may accept or reject a message based only on the content of envelopes. Its decisions are about the handling of the message, not about the handling of an active session.

Filtering extends the decision making process by allowing [smtpd(8)](/smtpd/8.md) to stop at each phase of an SMTP session, check that conditions are met, then decide if a session is allowed to move forward.

With filtering, a session may be interrupted at any phase before an envelope is complete. A message may also be rejected after being submitted, regardless of whether the envelope was accepted or not.

The following phases are currently supported:

| | |
| --- | --- |
| connect | upon connection, before a banner is displayed |
| helo | after HELO command is submitted |
| ehlo | after EHLO command is submitted |
| mail-from | after MAIL FROM command is submitted |
| rcpt-to | after RCPT TO command is submitted |
| data | after DATA command is submitted |
| commit | after message is fully submitted |

At each phase, various conditions may be matched. The fcrdns, rdns, and src data are available in all phases, but other data must have been already submitted before they are available.

| | |
| --- | --- |
| fcrdns | forward-confirmed reverse DNS is valid |
| rdns | session has a reverse DNS |
| rdns \<*table*\> | session has a reverse DNS in table |
| src \<*table*\> | source address is in table |
| helo \<*table*\> | helo name is in table |
| auth | session is authenticated |
| auth \<*table*\> | session username is in table |
| mail-from \<*table*\> | sender address is in table |
| rcpt-to \<*table*\> | recipient address is in table |

These conditions may all be negated by prefixing them with an exclamation mark:

| | |
| --- | --- |
| !fcrdns | forward-confirmed reverse DNS is invalid |

Any conditions using a table may indicate that the table contains regular expressions by prefixing the table name with the keyword regex.

| | |
| --- | --- |
| helo regex \<*table*\> | helo name matches a regex in table |

Finally, a number of decisions may be taken:

| | |
| --- | --- |
| bypass | the session or transaction bypasses filters |
| disconnect *message* | the session is disconnected with message |
| junk | the session or transaction is junked, i.e., an |
| reject *message* | the command is rejected with message |
| rewrite *value* | the command parameter is rewritten with value |

Decisions that involve a message require that the message be RFC valid, meaning that they should either start with a 4xx or 5xx status code. Decisions can be taken at any phase, though junking can only happen before a message is committed.

### FORMAT SPECIFIERS

Some configuration directives support expansion of their parameters at runtime. Such directives (for example **action** **maildir**, **action** **mda**) may use format specifiers which are expanded before delivery or relaying. The following formats are currently supported:

| | |
| --- | --- |
| %{sender} | sender email address, may be empty string |
| %{sender.user} | user part of the sender email address, may be empty |
| %{sender.domain} | domain part of the sender email address, may be empty |
| %{rcpt} | recipient email address |
| %{rcpt.user} | user part of the recipient email address |
| %{rcpt.domain} | domain part of the recipient email address |
| %{dest} | recipient email address after expansion |
| %{dest.user} | user part after expansion |
| %{dest.domain} | domain part after expansion |
| %{user.username} | local user |
| %{user.directory} | home directory of the local user |
| %{mbox.from} | name used in mbox From separator lines |
| %{mda} | mda command, only available for mda wrappers |

Expansion formats also support partial expansion using the optional bracket notations with substring offset. For example, with recipient domain “example.org”:

| | |
| --- | --- |
| %{rcpt.domain\[0\]} | expands to “e” |
| %{rcpt.domain\[1\]} | expands to “x” |
| %{rcpt.domain\[8:\]} | expands to “org” |
| %{rcpt.domain\[-3:\]} | expands to “org” |
| %{rcpt.domain\[0:6\]} | expands to “example” |
| %{rcpt.domain\[0:-4\]} | expands to “example” |

In addition, modifiers may be applied to the token. For example, with recipient “User+Tag@Example.org”:

| | |
| --- | --- |
| %{rcpt:lowercase} | expands to “user+tag@example.org” |
| %{rcpt:uppercase} | expands to “USER+TAG@EXAMPLE.ORG” |
| %{rcpt:strip} | expands to “User@Example.org” |
| %{rcpt:lowercase\|strip} | expands to “user@example.org” |

Modifiers and partial expansion can be used together. In such cases, the modifiers are applied before the partial expansion. For example, with sender “owner-tech+M123456@openbsd.org”:

| | |
| --- | --- |
| %{sender.user\[6:\]:strip} | expands to “tech” |

For security concerns, expanded values are sanitized and potentially dangerous characters are replaced with ‘:’. In situations where they are desirable, the “raw” modifier may be applied. For example, with recipient “user+t?g@example.org”:

| | |
| --- | --- |
| %{rcpt} | expands to “user+t:g@example.org” |
| %{rcpt:raw} | expands to “user+t?g@example.org” |

### MDA COMMANDS

When an action delivery method is **mda**, [smtpd(8)](/smtpd/8.md) runs the associated command for the delivery with the mail content provided via standard input. The command is expected to read all the mail content.

The exit code of the command reports the outcome of the delivery: status 0 (EX\_OK) is a successful delivery; status 71 (EX\_OSERR) and 75 (EX\_TEMPFAIL) are temporary failures; and all other exit status are considered permanent failures.

The following environment variables are set:

- DOMAIN

  The recipient domain.

- EXTENSION

  The sub address of the recipient (may be unset).

- HOME

  The delivery user's login directory.

- LOCAL

  The local part of the recipient user address.

- LOGNAME

  The login name of the user.

- ORIGINAL\_RECIPIENT

  The address of the original recipient.

- PATH

  Set to \_PATH\_DEFPATH. Traditionally */usr/bin:/bin*, but expanded to include */usr/sbin*, */sbin*, */usr/X11R6/bin*, */usr/local/bin*, and */usr/local/sbin* in OpenBSD.

- RECIPIENT

  The address of the final recipient.

- SENDER

  The address of the sender (might be empty).

- SHELL

  Set to */bin/sh*.

- USER

  Synonym of LOGNAME for backwards compatibility.

## FILES

- */etc/smtpd/smtpd.conf*

  Default [smtpd(8)](/smtpd/8.md) configuration file.

- */etc/smtpd/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)](/gethostname/3.md), either directly if it is a fully qualified domain name, or by retrieving the associated canonical name through [getaddrinfo(3)](/getaddrinfo/3.md).

- */run/smtpd.sock*

  Unix domain socket for incoming SMTP connections.

- */var/spool/smtpd/*

  Spool directories for mail during processing.

## EXAMPLES

The default **smtpd.conf** file which ships with OpenBSD 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 similar to 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/smtpd/secrets
# chmod 640 /etc/smtpd/secrets
# chown root:smtpd /etc/smtpd/secrets
# echo "bob username:password" > /etc/smtpd/secrets
```

**smtpd.conf** would look like this:

```
table aliases file:/etc/smtpd/aliases
table secrets file:/etc/smtpd/secrets
listen on lo0
action "local_mail" mbox alias <aliases>
action "outbound" relay host smtp+tls://bob@smtp.example.com \
	auth <secrets>
match from local for local action "local_mail"
match from local for any action "outbound"
```

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:

```
# 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
```

In the example above, a certificate valid for one year was created. The configuration file would look like this:

```
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/smtpd/aliases
listen on lo0
listen on egress tls pki mail.example.com auth
action mda_with_aliases mda "/path/to/mda -f -" alias <aliases>
action mda_without_aliases mda "/path/to/mda -f -"
action "outbound" relay
match for local action mda_with_aliases
match from any for domain example.com action mda_without_aliases
match for any action "outbound"
match auth from any for any action "outbound"
```

For sites that wish to sign messages using DKIM, the following example uses **opensmtpd-filter-dkimsign** for DKIM signing:

```
table aliases file:/etc/smtpd/aliases
filter "dkimsign" proc-exec "filter-dkimsign -d <domain> -s <selector> \
	-k /etc/smtpd/dkim/private.key" user _dkimsign group _dkimsign
listen on socket filter "dkimsign"
listen on lo0 filter "dkimsign"
action "local_mail" mbox alias <aliases>
action "outbound" relay
match for local action "local_mail"
match for any action "outbound"
```

Alternatively, the **opensmtpd-filter-rspamd** package may be used to provide integration with **rspamd**, a third-party daemon which provides multiple antispam features as well as DKIM signing. As well as configuring **rspamd** itself, it requires use of the **proc-exec** keyword:

```
filter "rspamd" proc-exec "filter-rspamd"
```

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 *other-relays* to specify the IP addresses of relays that may legitimately originate mail with the owner's domain as the sender.

```
table aliases file:/etc/smtpd/aliases
table other-relays file:/etc/smtpd/other-relays
listen on lo0
listen on egress
action "local_mail" mbox alias <aliases>
action "outbound" relay
match for local action "local_mail"
match for any action "outbound"
match !from src <other-relays> mail-from "@example.com" for any \
      reject
match from any for domain example.com action "local_mail"
```

## SEE ALSO

[mailer.conf(5)](/mailer.conf/5.md), [table(5)](/table/5.md), [smtpd-filters(7)](/smtpd-filters/7.md), [makemap(8)](/makemap/8.md), [smtpd(8)](/smtpd/8.md)

## HISTORY

[smtpd(8)](/smtpd/8.md) first appeared in OpenBSD 4.6.