POSTCONF(5)

📦

version 3.11.7 · 10 versions

3.11.7 · alpine 3.24, arch rolling, nixos 26.05, nixpkgs unstable, ubuntu stonking (latest)
3.5.25 · centos-stream 9
11.0 · nixpkgs unstable
3.6.4 · ubuntu jammy
3.6.4 · ubuntu jammy
3.10.3 · fedora 43, opensuse-leap 16.0, ubuntu questing
3.8.6 · centos-stream 10, ubuntu noble
3.7.11 · debian bookworm
3.10.7 · fedora 44, ubuntu resolute
3.10.14 · alpine 3.22, alpine 3.23, debian trixie, fedora 43, fedora 44

, in alpine 3.24, arch rolling, nixos 26.05, nixpkgs unstable, ubuntu stonking

💖 POSTCONF(5) — postconf 💖

okay bestie, welcome to postconf, page 5 of the File Formats Manual. this is literally the dictionary of every Postfix configuration parameter. grab a snack, we're reading all of them. 🌸

✨ NAME ✨

postconf — Postfix configuration parameters.

that's it. that's the whole name. iconic, no notes. 👑

🎀 SYNOPSIS 🎀

postconf parameter ...

postconf -e "parameter=value" ...

💜 DESCRIPTION 💜

so the Postfix main.cf configuration file specifies the parameters that control the operation of the Postfix mail system. typically the file only contains a small subset of ALL the parameters; anything you don't specify is just left at its default value. she's low maintenance like that. 💅

the general format of the main.cf file goes like this:

Every logical line has the form "parameter = value". Whitespace around the "=" is ignored, and so is whitespace at the end of a logical line. flexibility, we love to see it.
Empty lines and whitespace-only lines are ignored, and so are lines whose first non-whitespace character is a '#'. (comments, our beloved 🫶)
A logical line starts with non-whitespace text. A line that starts with whitespace continues a logical line. continuation lines, periodt.
A parameter value may refer to functions or other parameters.
- The expressions "$name" and "${name}" are recursively replaced with the value of the named parameter. The parameter name must contain only characters from the set [a-zA-Z0-9_]. An undefined parameter value is replaced with the empty value.
- The expressions "${name?value}" and "${name?{value}}" are replaced with "value" when "$name" is non-empty. The parameter name must contain only characters from the set [a-zA-Z0-9_]. These forms are supported with Postfix versions >= 2.2 and >= 3.0, respectively.
- The expressions "${name:value}" and "${name:{value}}" are replaced with "value" when "$name" is empty. The parameter name must contain only characters from the set [a-zA-Z0-9_]. These forms are supported with Postfix versions >= 2.2 and >= 3.0, respectively.
- The expression "${name?{value1}:{value2}}" is replaced with "value1" when "$name" is non-empty, and with "value2" when "$name" is empty. The "{}" is required for "value1", optional for "value2". The parameter name must contain only characters from the set [a-zA-Z0-9_]. This form is supported with Postfix versions >= 3.0.
- The first item inside "${...}" may be a relational expression of the form: "{value3} == {value4}". Besides the "==" (equality) operator Postfix supports "!=" (inequality), "<", "<=", ">=", and ">". The comparison is numerical when both operands are all digits, otherwise the comparison is lexicographical. These forms are supported with Postfix versions >= 3.0.
- The expression "${name{value}}" is replaced with the result from calling the function name with the argument value after stripping whitespace between the "{", the value, and the "}". An example is the domain_to_ascii{} function.
- Each "value" is subject to recursive named parameter and relational expression evaluation, except where noted.
- Whitespace before or after each "{value}" is ignored.
- Specify "$$" to produce a single "$" character.
- The legacy form "$(...)" is equivalent to the preferred form "${...}".
When the same parameter is defined multiple times, only the last instance is remembered. (last one wins, sorry to the earlier ones 💀)
Otherwise, the order of main.cf parameter definitions does not matter.

the remainder of this document is a description of ALL Postfix configuration parameters. Default values are shown after the parameter name in parentheses, and can be looked up with the "postconf -d" command.

Note: this is not an invitation to make changes to Postfix configuration parameters. Unnecessary changes can impair the operation of the mail system. please bestie, do NOT freestyle on a mail server. 🙈

🌈 PARAMETERS 🌈

`2bounce_notice_recipient` (default: `postmaster`)

The recipient of undeliverable mail that cannot be returned to the sender. This feature is enabled with the notify_classes parameter.

`access_map_defer_code` (default: `450`)

The numerical Postfix SMTP server response code for an access(5) map "defer" action, including "defer_if_permit" or "defer_if_reject". Prior to Postfix 2.6, the response is hard-coded as "450".

Do not change this unless you have a complete understanding of RFC 5321. (fr fr, this is not a vibe-check-and-yolo situation 😭)

This feature is available in Postfix 2.6 and later.

`access_map_reject_code` (default: `554`)

The numerical Postfix SMTP server response code for an access(5) map "reject" action.

Do not change this unless you have a complete understanding of RFC 5321. ⭐

`address_verify_cache_cleanup_interval` (default: `12h`)

The amount of time between verify(8) address verification database cleanup runs. This feature requires that the database supports the "delete" and "sequence" operators. Specify a zero interval to disable database cleanup.

After each database cleanup run, the verify(8) daemon logs the number of entries that were retained and dropped. A cleanup run is logged as "partial" when the daemon terminates early after "postfix reload", "postfix stop", or no requests for $max_idle seconds.

Specify a non-negative time value (an integral value plus an optional one-letter suffix that specifies the time unit). Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). The default time unit is h (hours).

This feature is available in Postfix 2.7.

`address_verify_default_transport` (default: `$default_transport`)

Overrides the default_transport parameter setting for address verification probes.

This feature is available in Postfix 2.1 and later.

`address_verify_local_transport` (default: `$local_transport`)

Overrides the local_transport parameter setting for address verification probes.

This feature is available in Postfix 2.1 and later.

`address_verify_map` (default: Postfix >= 3.11: `$default_cache_db_type:$data_directory/verify_cache`; Postfix < 3.11: `btree:$data_directory/verify_cache`)

Lookup table for persistent address verification status storage. The table is maintained by the verify(8) service, and is opened before the process releases privileges.

The lookup table is persistent by default (Postfix 2.7 and later). Specify an empty table name to keep the information in volatile memory which is lost after "postfix reload" or "postfix stop". This is the default with Postfix version 2.6 and earlier.

Specify a location in a file system that will not fill up. If the database becomes corrupted, the world comes to an end. To recover, delete (NOT: truncate) the file and do "postfix reload". 💀

Postfix daemon processes do not use root privileges when opening this file (Postfix 2.5 and later). The file must therefore be stored under a Postfix-owned directory such as the data_directory. As a migration aid, an attempt to open the file under a non-Postfix directory is redirected to the Postfix-owned data_directory, and a warning is logged.

Examples:

address_verify_map = $default_cache_db_type:$data_directory/verify_cache
address_verify_map = lmdb:/var/lib/postfix/verify_cache
address_verify_map = btree:/var/lib/postfix/verify_cache

This feature is available in Postfix 2.1 and later.

`address_verify_negative_cache` (default: `yes`)

Enable caching of failed address verification probe results. When this feature is enabled, the cache may pollute quickly with garbage. When this feature is disabled, Postfix will generate an address probe for every lookup. (every single one. she's thorough 🦋)

This feature is available in Postfix 2.1 and later.

`address_verify_negative_expire_time` (default: `3d`)

The time after which a failed probe expires from the address verification cache.

Specify a non-zero time value (an integral value plus an optional one-letter suffix that specifies the time unit). Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). The default time unit is d (days).

This feature is available in Postfix 2.1 and later.

`address_verify_negative_refresh_time` (default: `3h`)

The time after which a failed address verification probe needs to be refreshed.

This feature is available in Postfix 2.1 and later.

`address_verify_pending_request_limit` (default: see `postconf -d` output)

A safety limit that prevents address verification requests from overwhelming the Postfix queue. By default, the number of pending requests is limited to 1/4 of the active queue maximum size (qmgr_message_active_limit). The queue manager enforces the limit by tempfailing requests that exceed the limit. This affects only unknown addresses and inactive addresses that have expired, because the verify(8) daemon automatically refreshes an active address before it expires.

This feature is available in Postfix 3.1 and later.

`address_verify_poll_count` (default: `normal: 3`, `overload: 1`)

How many times to query the verify(8) service for the completion of an address verification request in progress.

By default, the Postfix SMTP server polls the verify(8) service up to three times under non-overload conditions, and only once when under overload. With Postfix version 2.5 and earlier, the SMTP server always polls the verify(8) service up to three times by default.

Specify 1 to implement a crude form of greylisting, that is, always defer the first delivery request for a new address.

Examples:

# Postfix <= 2.6 default
address_verify_poll_count = 3
# Poor man's greylisting
address_verify_poll_count = 1

This feature is available in Postfix 2.1 and later.

`address_verify_poll_delay` (default: `3s`)

The delay between queries for the completion of an address verification request in progress.

The default polling delay is 3 seconds.

This feature is available in Postfix 2.1 and later.

`address_verify_positive_expire_time` (default: 31d)

So when a probe comes back and it worked ✨ — success, slay — this is how long that happy result just vibes in the address verification cache before it expires.

This feature is available in Postfix 2.1 and later.

`address_verify_positive_refresh_time` (default: 7d)

How long before a successful address verification probe needs a lil refresh 🫶. Important tea: the address verification status does not get updated when the probe fails (that's called optimistic caching, bestie).

This feature is available in Postfix 2.1 and later.

`address_verify_relay_transport` (default: $relay_transport)

Overrides the relay_transport parameter setting for address verification probes. Just for the probes tho — main character exception energy 💅.

This feature is available in Postfix 2.1 and later.

`address_verify_relayhost` (default: $relayhost)

Overrides the relayhost parameter setting for address verification probes. Heads up: this information can be overruled with the transport(5) table.

This feature is available in Postfix 2.1 and later.

`address_verify_sender` (default: $double_bounce_sender)

The sender address to use in address verification probes; prior to Postfix 2.5 the default was "postmaster". To avoid problems with address probes that are sent in response to address probes, the Postfix SMTP server excludes the probe sender address from all SMTPD access blocks.

Specify an empty value (address_verify_sender =) or <> if you want to use the null sender address. ⚠️ Beware, some sites reject mail from <>, even though RFCs require that such addresses be accepted.

Examples:

address_verify_sender = <>
address_verify_sender = postmaster@mydomain

This feature is available in Postfix 2.1 and later.

`address_verify_sender_dependent_default_transport_maps` (default: $sender_dependent_default_transport_maps)

Overrides the sender_dependent_default_transport_maps parameter setting for address verification probes.

This feature is available in Postfix 2.7 and later.

`address_verify_sender_dependent_relayhost_maps` (default: $sender_dependent_relayhost_maps)

Overrides the sender_dependent_relayhost_maps parameter setting for address verification probes.

This feature is available in Postfix 2.3 and later.

`address_verify_sender_ttl` (default: 0s)

The time between changes in the time-dependent portion of address verification probe sender addresses. That time-dependent portion gets appended to the localpart of the address you specified with the address_verify_sender parameter. This feature is ignored when the probe sender address is the null sender, i.e. when the address_verify_sender value is empty or <>.

Historically, the probe sender address was fixed. This has caused such addresses to end up on spammer mailing lists, and has resulted in wasted network and processing resources 😭.

To enable time-dependent probe sender addresses, specify a non-zero time value. Specify a value of at least several hours, to avoid problems with senders that use greylisting. Avoid nice TTL values, to make the result less predictable. 👑

This feature is available in Postfix 2.9 and later.

`address_verify_service_name` (default: verify)

The name of the verify(8) address verification service. This service maintains the status of sender and/or recipient address verification probes, and generates probes on request by other Postfix processes. Fr fr, it's the whole operation running in the background 🌸.

`address_verify_transport_maps` (default: $transport_maps)

Overrides the transport_maps parameter setting for address verification probes.

This feature is available in Postfix 2.1 and later.

`address_verify_virtual_transport` (default: $virtual_transport)

Overrides the virtual_transport parameter setting for address verification probes.

This feature is available in Postfix 2.1 and later.

`alias_database` (default: see `postconf -d` output)

The alias databases for local(8) delivery that are updated with "newaliases" or with "sendmail -bi".

This is a separate configuration parameter because not all the tables specified with $alias_maps have to be local files. iykyk.

Examples:

alias_database = $default_database_type:/etc/aliases
alias_database = lmdb:/etc/aliases
alias_database = lmdb:/etc/mail/aliases

Instead of lmdb:, some systems use cdb:, hash:, or dbm:.

`alias_maps` (default: see `postconf -d` output)

Optional lookup tables that are searched only with an email address localpart (no domain 💀) and that apply only to local(8) recipients; this is unlike virtual_alias_maps that are often searched with a full email address (including domain) and that apply to all recipients: local(8), virtual, and remote. The alias_maps table format and lookups are documented in aliases(5). For an overview of Postfix address manipulations see the ADDRESS_REWRITING_README document.

Specify zero or more "type:name" lookup tables, separated by whitespace or comma. Tables will be searched in the specified order until a match is found. Note: these lookups are recursive. 🔁

The default list is system dependent. On systems with NIS, the default is to search the local alias database, then the NIS alias database.

The local(8) delivery agent disallows regular expression substitution of $1 etc. in alias_maps, because that would open a security hole. 🚨

The local(8) delivery agent will silently ignore requests to use the proxymap(8) server within alias_maps. Instead it will open the table directly. Before Postfix version 2.2, the local(8) delivery agent will terminate with a fatal error.

Examples:

alias_maps = $default_database_type:/etc/aliases, nis:mail.aliases
alias_maps = $default_database_type:/etc/aliases
alias_maps = lmdb:/etc/mail/aliases
alias_maps = lmdb:/etc/aliases

Instead of lmdb:, some systems use cdb:, hash:, or dbm:.

Execute the command "postalias /path/to/aliases" after you change the aliases file, to (re)build a default-type indexed file. Execute "postalias type:/path/to/aliases" to specify an explicit type.

The default indexed file type is configured with the default_database_type parameter. To list available explicit types, execute the command "postconf -m".

Configuration changes will become visible after a minute or so. Use "postfix reload" to eliminate the delay. ⏱️

`allow_mail_to_commands` (default: alias, forward)

Restrict local(8) mail delivery to external commands. The default is to disallow delivery to "|command" in :include: files (see aliases(5) for the text that defines this terminology).

Specify zero or more of: alias, forward or include, in order to allow commands in aliases(5), .forward files or in :include: files, respectively.

Example:

allow_mail_to_commands = alias,forward,include

`allow_mail_to_files` (default: alias, forward)

Restrict local(8) mail delivery to external files. The default is to disallow "/file/name" destinations in :include: files (see aliases(5) for the text that defines this terminology).

Specify zero or more of: alias, forward or include, in order to allow "/file/name" destinations in aliases(5), .forward files and in :include: files, respectively.

Example:

allow_mail_to_files = alias,forward,include

`allow_min_user` (default: no)

Allow a sender or recipient address to have `-' as the first character. By default, this is not allowed, to avoid accidents with software that passes email addresses via the command line. Such software would not be able to distinguish a malicious address from a bona fide command-line option. Although this can be prevented by inserting a "--" option terminator into the command line, this is difficult to enforce consistently and globally.

As of Postfix version 2.5, this feature is implemented by trivial-rewrite(8). With earlier versions this feature was implemented by qmgr(8) and was limited to recipient addresses only.

`allow_percent_hack` (default: yes)

Enable the rewriting of the form "user%domain" to "user@domain". This is enabled by default. ✨

Note: as of Postfix version 2.2, message header address rewriting happens only when one of the following conditions is true:

The message is received with the Postfix sendmail(1) command,
The message is received from a network client that matches $local_header_rewrite_clients,
The message is received from the network, and the remote_header_rewrite_domain parameter specifies a non-empty value.

To get the behavior before Postfix version 2.2, specify "local_header_rewrite_clients = static:all".

Example:

allow_percent_hack = no

`allow_srv_lookup_fallback` (default: no)

When SRV record lookup fails or no SRV record exists, fall back to MX or IP address lookup as if SRV record lookup was not enabled. Basically a lil safety net 🦋.

This feature is available in Postfix 3.8 and later.

`allow_untrusted_routing` (default: no)

Forward mail with sender-specified routing (user[@%!]remote[@%!]site) from untrusted clients to destinations matching $relay_domains.

By default, this feature is turned off. This closes a nasty open relay loophole where a backup MX host can be tricked into forwarding junk mail to a primary MX host which then spams it out to the world. 💀 So like, keep it off unless you know what you're doing.

This parameter also controls if non-local addresses with sender-specified routing can match Postfix access tables. By default, such addresses cannot match Postfix access tables, because the address is ambiguous.

`alternate_config_directories` (default: empty)

A list of non-default Postfix configuration directories that may be specified with "-c config_directory" on the command line (in the case of sendmail(1), with the "-C" option), or via the MAIL_CONFIG environment parameter.

This list must be specified in the default Postfix main.cf file, and will be used by set-gid Postfix commands such as postqueue(1) and postdrop(1).

Specify absolute pathnames, separated by comma or space. Note: $name expansion is not supported. 🙅

`always_add_missing_headers` (default: `no`)

okay so this one is all about ✨politeness✨ — it makes Postfix always slap on the (Resent-) From:, To:, Date: or Message-ID: headers when they're not already there. bestie, nobody wants an email with a missing Date:, it's giving ghost mode.

so in Postfix 2.6 and later, these headers only get added when the client matches the local_header_rewrite_clients parameter setting. But earlier Postfix versions always add them, no questions asked — and ngl that can break DKIM signatures that cover headers that don't even exist. 💀

and the undisclosed_recipients_header parameter setting is the one that decides whether a To: header gets added at all. iykyk.

`always_bcc` (default: empty)

an optional address that gets a 🎀 "blind carbon copy" 🎀 of every single message that the Postfix mail system receives. sneaky but iconic.

Note: with Postfix 2.3 and later, the BCC address is added as if it was specified with NOTIFY=NONE. The sender will not be notified when the BCC address is undeliverable — as long as all down-stream software implements RFC 3461. fr fr.

Note: with Postfix 2.2 and earlier, the sender will be notified when the BCC address is undeliverable.

Note: automatic BCC recipients are produced only for new mail. To avoid mailer loops, automatic BCC recipients are not generated after Postfix forwards mail internally, or after Postfix generates mail itself. no infinite loop situations here bestie 🙈

Note: automatic BCC recipients are subject to address canonicalization (add missing domain), canonical_maps, masquerade_domains, and virtual_alias_maps. the glow-up pipeline 💅

`anvil_rate_time_unit` (default: `60s`)

the time unit over which client connection rates and other rates get calculated. this is the ✨vibe check window✨ for rate limiting.

this feature is implemented by the anvil(8) service, which has been available in Postfix version 2.2 and later.

the default interval is relatively short. because of the high frequency of updates, the anvil(8) server uses volatile memory only. which means... information is lost whenever the process terminates. 😭 it's giving short-term memory loss and honestly, same.

specify a non-zero time value (an integral value plus an optional one-letter suffix that specifies the time unit). Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). The default time unit is s (seconds).

`anvil_status_update_time` (default: `600s`)

how frequently the anvil(8) connection and rate limiting server logs peak usage information. it's the anvil server's little diary entry 📓✨

This feature is available in Postfix 2.2 and later.

`append_at_myorigin` (default: `yes`)

with locally submitted mail, append the string "@$myorigin" to mail addresses that have no domain information. With remotely submitted mail, append the string "@$remote_header_rewrite_domain" instead. basically: every address gets a lil domain bestie, nobody's left out 🫶

Note 1: this feature is enabled by default and must not be turned off. Postfix does not support domain-less addresses. periodt.

Note 2: with Postfix version 2.2, message header address rewriting happens only when one of the following conditions is true:

The message is received with the Postfix sendmail(1) command,
The message is received from a network client that matches $local_header_rewrite_clients,
The message is received from the network, and the remote_header_rewrite_domain parameter specifies a non-empty value.

To get the behavior before Postfix version 2.2, specify "local_header_rewrite_clients = static:all".

`append_dot_mydomain` (default: Postfix >= 3.0: `no`, Postfix < 3.0: `yes`)

with locally submitted mail, append the string ".$mydomain" to addresses that have no ".domain" information. With remotely submitted mail, append the string ".$remote_header_rewrite_domain" instead. the domain version of the above, but with a dot this time 🎀

Note 1: when disabled (Postfix 3.0 and later), users will not be able to send mail to "user@partialdomainname" — they'll have to specify full domain names instead. so no lazy partial domains, bestie, we're doing this properly now 💅

Note 2: with Postfix version 2.2, message header address rewriting happens only when one of the following conditions is true:

The message is received with the Postfix sendmail(1) command,
The message is received from a network client that matches $local_header_rewrite_clients,
The message is received from the network, and the remote_header_rewrite_domain parameter specifies a non-empty value.

To get the behavior before Postfix version 2.2, specify "local_header_rewrite_clients = static:all".

`application_event_drain_time` (default: `100s`)

how long the postkick(1) command waits for a request to enter the Postfix daemon process input buffer before giving up. it's the "hey bestie are you up? ...okay never mind" timer 😭

This feature is available in Postfix 2.1 and later.

`authorized_flush_users` (default: `static:anyone`)

the list of users who are authorized to flush the queue. this is a permissions list, so pay attention bestie 👑

by default, all users are allowed to flush the queue. Access is always granted if the invoking user is the super-user or the $mail_owner user. Otherwise, the real UID of the process is looked up in the system password file, and access is granted only if the corresponding login name is on the access list. The username "unknown" is used for processes whose real UID is not found in the password file.

Specify a list of user names, "/file/name" or "type:table" patterns, separated by commas and/or whitespace. The list is matched left to right, and the search stops on the first match. A "/file/name" pattern is replaced by its contents; a "type:table" lookup table is matched when a name matches a lookup key (the lookup result is ignored). Continue long lines by starting the next line with whitespace. Specify "!pattern" to exclude a name from the list. The form "!/file/name" is supported only in Postfix version 2.4 and later.

This feature is available in Postfix 2.2 and later.

`authorized_mailq_users` (default: `static:anyone`)

the list of users who are authorized to view the queue. the mailq equivalent of the above, same rules energy ✨

by default, all users are allowed to view the queue. Access is always granted if the invoking user is the super-user or the $mail_owner user. Otherwise, the real UID of the process is looked up in the system password file, and access is granted only if the corresponding login name is on the access list. The username "unknown" is used for processes whose real UID is not found in the password file.

Specify a list of user names, "/file/name" or "type:table" patterns, separated by commas and/or whitespace. The list is matched left to right, and the search stops on the first match. A "/file/name" pattern is replaced by its contents; a "type:table" lookup table is matched when a name matches a lookup key (the lookup result is ignored). Continue long lines by starting the next line with whitespace. Specify "!pattern" to exclude a user name from the list. The form "!/file/name" is supported only in Postfix version 2.4 and later.

This feature is available in Postfix 2.2 and later.

`authorized_submit_users` (default: `static:anyone`)

the list of users who are authorized to submit mail with the sendmail(1) command (and with the privileged postdrop(1) helper command). this is the bouncer at the door of mail submission 🚪✨

by default, all users are allowed to submit mail. Otherwise, the real UID of the process is looked up in the system password file, and access is granted only if the corresponding login name is on the access list. The username "unknown" is used for processes whose real UID is not found in the password file. To deny mail submission access to all users, specify an empty list.

Specify a list of user names, "/file/name" or "type:table" patterns, separated by commas and/or whitespace. The list is matched left to right, and the search stops on the first match. A "/file/name" pattern is replaced by its contents; a "type:table" lookup table is matched when a name matches a lookup key (the lookup result is ignored). Continue long lines by starting the next line with whitespace. Specify "!pattern" to exclude a user name from the list. The form "!/file/name" is supported only in Postfix version 2.4 and later.

Example:

authorized_submit_users = !www, static:all

This feature is available in Postfix 2.2 and later.

`authorized_verp_clients` (default: `$mynetworks`)

what remote SMTP clients are allowed to specify the XVERP command. That command requests that mail be delivered one recipient at a time with a per-recipient return address. it's giving personal attention to every single recipient 💅

by default, only trusted clients are allowed to specify XVERP.

This parameter was introduced with Postfix version 1.1. Postfix version 2.1 renamed this parameter to smtpd_authorized_verp_clients and changed the default to none. so if you're on 2.1+ and looking for the old name, bestie it's gone, it got a rebrand 😭

Specify a list of network/netmask patterns, separated by commas and/or whitespace. The mask specifies the number of bits in the network part of a host address. You can also specify hostnames or .domain names (the initial dot causes the domain to match any name below it), "/file/name" or "type:table" patterns. A "/file/name" pattern is replaced by its contents; a "type:table" lookup table is matched when a table entry matches a lookup string (the lookup result is ignored). Continue long lines by starting the next line with whitespace. Specify "!pattern" to exclude an address or network block from the list. The form "!/file/name" is supported only in Postfix version 2.4 and later.

Note: IP version 6 address information must be specified inside [] in the authorized_verp_clients value, and in files specified with "/file/name". IP version 6 addresses contain the ":" character, and would otherwise be confused with a "type:table" pattern. so wrap those bad boys in brackets fr fr 🙈

`backwards_bounce_logfile_compatibility` (default: `yes`)

produce additional bounce(8) logfile records that can be read by Postfix versions before 2.0. The current and more extensible "name = value" format is needed in order to implement more sophisticated functionality. so this is basically the legacy-compat mode — cute for the old servers, but the new format ate and left no crumbs 🔥

This feature is available in Postfix 2.1 and later.

`berkeley_db_create_buffer_size` (default: `16777216`)

the per-table I/O buffer size for programs that create Berkeley DB hash or btree tables. Specify a byte count. big buffer, big energy.

This feature is available in Postfix 2.0 and later.

`berkeley_db_read_buffer_size` (default: `131072`)

the per-table I/O buffer size for programs that read Berkeley DB hash or btree tables. Specify a byte count. same energy as the create one but for reading, and notably a much smaller number ngl 👀

This feature is available in Postfix 2.0 and later.

💖 best_mx_transport (default: empty)

Where the Postfix SMTP client should deliver mail when it sniffs out a "mail loops back to myself" error condition. This is what happens when the local MTA is the best SMTP mail exchanger for a destination that is not listed in $mydestination, $inet_interfaces, $proxy_interfaces, $virtual_alias_domains, or $virtual_mailbox_domains. By default, the Postfix SMTP client returns such mail as undeliverable. 🙈

Specify, for example, best_mx_transport = local to pass the mail from the Postfix SMTP client to the local(8) delivery agent. You can specify any message delivery "transport" or "transport:nexthop" that is defined in the master.cf file. The syntax and meaning of "transport" or "transport:nexthop"? That's all in the transport(5) manual page, bestie.

But okay, lowkey this feature is expensive, because it ties up a Postfix SMTP client process while the local(8) delivery agent is doing its work. It is more efficient (for Postfix) to list all hosted domains in a table or database. 🌸

🌼 biff (default: yes)

Whether or not to use the local biff service. This service sends "new mail" notifications to users who have requested new mail notification with the UNIX command biff y.

For compatibility reasons this feature is on by default. On systems with lots of interactive users, the biff service can be a performance drain. Specify biff = no in main.cf to disable it. 🚫

🔍 body_checks (default: empty)

Optional lookup tables for content inspection as specified in the body_checks(5) manual page.

Note: with Postfix versions before 2.0, these rules inspect all content after the primary message headers.

📏 body_checks_size_limit (default: 51200)

How much text in a message body segment (or attachment, if you prefer to use that term) is subjected to body_checks inspection. The amount of text is limited to avoid scanning huge attachments. Nothing worse than a giant attachment slowing your vibe check down.

This feature is available in Postfix 2.0 and later. ✨

📬 bounce_notice_recipient (default: postmaster)

The recipient of postmaster notifications with the message headers of mail that Postfix did not deliver and of SMTP conversation transcripts of mail that Postfix did not receive. This feature is enabled with the notify_classes parameter.

⏳ bounce_queue_lifetime (default: 5d)

Consider a bounce message as undeliverable when delivery fails with a temporary error, and the time in the queue has reached the bounce_queue_lifetime limit. By default, this limit is the same as for regular mail.

Specify 0 when mail delivery should be tried only once. One and done, periodt. 💅

This feature is available in Postfix 2.1 and later.

🌈 bounce_service_name (default: bounce)

The name of the bounce(8) service. This service maintains a record of failed delivery attempts and generates non-delivery notifications.

This feature is available in Postfix 2.0 and later.

🎀 bounce_size_limit (default: 50000)

The maximal amount of original message text that is sent in a non-delivery notification. Specify a byte count. A message is returned as either message/rfc822 (the complete original) or as text/rfc822-headers (the headers only). With Postfix version 2.4 and earlier, a message is always returned as message/rfc822 and is truncated when it exceeds the size limit.

Notes:

If you increase this limit, then you should increase the mime_nesting_limit value proportionally.
Be careful when making changes. Excessively large values will result in the loss of non-delivery notifications, when a bounce message size exceeds a local or remote MTA's message size limit.

📝 bounce_template_file (default: empty)

Pathname of a configuration file with bounce message templates. These override the built-in templates of delivery status notification (DSN) messages for undeliverable mail, delayed mail, successful delivery, or delivery verification. The bounce(5) manual page describes how to edit and test template files.

Template message body text may contain $name references to Postfix configuration parameters. The result of $name expansion can be previewed with postconf -b file_name before the file is placed into the Postfix configuration directory. Preview first, slay later. 🦋

This feature is available in Postfix 2.3 and later.

💀 broken_sasl_auth_clients (default: no)

Enable interoperability with remote SMTP clients that implement an obsolete version of the AUTH command (RFC 4954). Examples of such clients are MicroSoft Outlook Express version 4 and MicroSoft Exchange version 5.0. Yeah, it's giving vintage.

Specify broken_sasl_auth_clients = yes to have Postfix advertise AUTH support in a non-standard way.

👑 canonical_classes (default: envelope_sender, envelope_recipient, header_sender, header_recipient)

What addresses are subject to canonical_maps address mapping. By default, canonical_maps address mapping is applied to envelope sender and recipient addresses, and to header sender and header recipient addresses.

Specify one or more of: envelope_sender, envelope_recipient, header_sender, header_recipient

This feature is available in Postfix 2.2 and later.

🧚 canonical_maps (default: empty)

Optional address mapping lookup tables for message headers and envelopes. The mapping is applied to both sender and recipient addresses, in both envelopes and in headers, as controlled with the canonical_classes parameter. This is typically used to clean up dirty addresses from legacy mail systems, or to replace login names by Firstname.Lastname. The table format and lookups are documented in canonical(5). For an overview of Postfix address manipulations see the ADDRESS_REWRITING_README document.

Specify zero or more "type:name" lookup tables, separated by whitespace or comma. Tables will be searched in the specified order until a match is found. Note: these lookups are recursive. 🔁

Note: with Postfix version 2.2, message header address mapping happens only when message header address rewriting is enabled:

The message is received with the Postfix sendmail(1) command,
The message is received from a network client that matches $local_header_rewrite_clients,
The message is received from the network, and the remote_header_rewrite_domain parameter specifies a non-empty value.

To get the behavior before Postfix version 2.2, specify local_header_rewrite_clients = static:all.

Examples:

canonical_maps = lmdb:/etc/postfix/canonical

Instead of lmdb:, some systems use cdb:, hash:, or dbm:.

Execute the command postmap /etc/postfix/canonical after you change the canonical file, to (re)build a default-type indexed file. Execute postmap type:/etc/postfix/canonical to specify an explicit type.

The default indexed file type is configured with the default_database_type parameter. To list available explicit types, execute the command postconf -m.

Configuration changes will become visible after a minute or so. Use postfix reload to eliminate the delay. ⚡

✨ cleanup_replace_stray_cr_lf (default: yes)

Replace each stray <CR> or <LF> character in message content with a space character, to prevent outbound SMTP smuggling, and to make the evaluation of Postfix-added DKIM or other signatures independent from how a remote mail server handles such characters.

SMTP does not allow such characters unless they are part of a <CR><LF> sequence, and different mail systems handle such stray characters in an implementation-dependent manner. Stray <CR> or <LF> characters could be used for outbound SMTP smuggling, where an attacker uses a Postfix server to send message content with a non-standard End-of-DATA sequence that triggers inbound SMTP smuggling at a remote SMTP server. Not iconic, not slay, we are not doing that. 🛑

The replacement happens before all other content management, and before Postfix may add a DKIM etc. signature; if the signature were created first, the replacement could invalidate the signature.

In addition to preventing SMTP smuggling, replacing stray <CR> or <LF> characters ensures that the result of signature validation by later mail system will not depend on how that mail system handles those stray characters in an implementation-dependent manner.

Note: this feature is disabled with receive_override_options = no_header_body_checks.

This feature is available in Postfix >= 3.9, 3.8.5, 3.7.10, 3.6.14, and 3.5.24.

🧼 cleanup_service_name (default: cleanup)

The name of the cleanup(8) service. This service rewrites addresses into the standard form, and performs canonical(5) address mapping and virtual(5) aliasing. It's the glow-up service, honestly. 💅

This feature is available in Postfix 2.0 and later.

🗂️ command_directory (default: see postconf -d output)

The location of all postfix administrative commands.

🏠 command_execution_directory (default: empty)

The local(8) delivery agent working directory for delivery to external commands. Failure to change directory causes the delivery to be deferred.

The command_execution_directory value is not subject to Postfix configuration parameter $name expansion. Instead, the following $name expansions are done on command_execution_directory before the directory is used. Expansion happens in the context of the delivery request. The result of $name expansion is filtered with the character set that is specified with the execution_directory_expansion_filter parameter.

$user — The recipient's username.
$shell — The recipient's login shell pathname.
$home — The recipient's home directory.
$recipient — The full recipient address.
$extension — The optional recipient address extension.
$domain — The recipient domain.
$local — The entire recipient localpart.
$recipient_delimiter — The address extension delimiter that was found in the recipient address (Postfix 2.11 and later), or the system-wide recipient address extension delimiter (Postfix 2.10 and earlier).
${name?value}
${name?{value}} (Postfix >= 3.0) — Expands to value when $name is non-empty.
${name:value}
${name:{value}} (Postfix >= 3.0) — Expands to value when $name is empty.
${name?{value1}:{value2}} (Postfix >= 3.0) — Expands to value1 when $name is non-empty, value2 otherwise.

Instead of $name you can also specify ${name} or $(name).

This feature is available in Postfix 2.2 and later. 🌟

`command_expansion_filter` (default: see `postconf -d` output)

Okay so bestie, this one is a lil bouncer at the door of $name expansions 💅. It restricts the characters that the local(8) delivery agent is allowed to let through in $name expansions of $mailbox_command and $command_execution_directory. Anything outside the allowed set? Instantly replaced with underscores. Not deleted, just swapped — periodt.

`command_time_limit` (default: `1000s`)

The time limit for delivery to external commands, fr fr. The local(8) delivery agent uses this limit, and it's also the default time limit for delivery by the pipe(8) delivery agent.

Note: if you set this time limit to a large value, you must update the global ipc_timeout parameter as well. Do not skip this, bestie, it's giving "consequences" 😭

`compatibility_level` (default: `0`)

A safety net 🕸️ that makes Postfix run with backwards-compatible default settings after you upgrade to a newer Postfix version.

With backwards compatibility turned on (meaning the main.cf compatibility_level value is less than the Postfix built-in value), Postfix goes looking for settings that are still chilling at their implicit default value, and it logs a message when a backwards-compatible default setting is required.

using backwards-compatible default setting name=value
    to [accept a specific client request]

using backwards-compatible default setting name=value
    to [enable specific Postfix behavior]

See COMPATIBILITY_README for the specific message details. If one of these messages shows up in the context of a legitimate request, the system administrator should make that backwards-compatible setting permanent in main.cf or master.cf, like:

# postconf name=value
# postfix reload

When no more backwards-compatible settings need to be made permanent, the admin should turn off backwards compatibility by updating the compatibility_level setting in main.cf:

# postconf compatibility_level=N
# postfix reload

For N, put in the number that's logged in your postfix(1) warning message:

warning: To disable backwards compatibility use "postconf
    compatibility_level=N" and "postfix reload"

Starting with Postfix version 3.6, the compatibility level in that warning message up there is the Postfix version that introduced the last incompatible change. The level is formatted as major.minor.patch, where patch is usually omitted and defaults to zero. Earlier compatibility levels are 0, 1 and 2.

NOTE: this also introduces support for the "<level", "<=level", and other operators to compare compatibility levels. With the standard operators "<", "<=", etc., compatibility level "3.10" would be smaller than "3.9" which is, like, wildly undesirable 🙈

This feature is available in Postfix 3.0 and later.

`config_directory` (default: see `postconf -d` output)

The default location of the Postfix main.cf and master.cf configuration files. This can be overruled via the following mechanisms, bestie:

The MAIL_CONFIG environment variable (daemon processes and commands).
The "-c" command-line option (commands only).

With Postfix commands that run with set-gid privileges, a config_directory override either requires root privileges 👑, or it requires that the directory is listed with the alternate_config_directories parameter in the default main.cf file.

`confirm_delay_cleared` (default: `no`)

After sending a "your message is delayed" notification, inform the sender when the delay clears up. Honestly a sweet idea but it can result in a sudden burst of notifications at the end of a prolonged network outage, which is why it's disabled by default. It's giving "flooded inbox" 🌊

`connection_cache_protocol_timeout` (default: `5s`)

Time limit for connection cache connect, send or receive operations. The time limit is enforced in the client. No cap, it just hangs up on you.

This feature is available in Postfix 2.3 and later.

`connection_cache_service_name` (default: `scache`)

The name of the scache(8) connection cache service. This service maintains a limited pool of cached sessions, like a lil vibe preserve 🫶

This feature is available in Postfix 2.2 and later.

`connection_cache_status_update_time` (default: `600s`)

How frequently the scache(8) server logs usage statistics with connection cache hit and miss rates for logical destinations and for physical endpoints. Numbers, bestie, we love a good stat drop 📊

`connection_cache_ttl_limit` (default: `2s`)

The maximal time-to-live value that the scache(8) connection cache server allows. Requests that specify a larger TTL will be stored with the maximum allowed TTL. The purpose of this additional control is to protect the infrastructure against careless people 🙈. The cache TTL is already bounded by $max_idle.

`content_filter` (default: empty)

After the message is queued, send the entire message to the specified transport:destination. The transport name specifies the first field of a mail delivery agent definition in master.cf; the syntax of the next-hop destination is described in the manual page of the corresponding delivery agent. More info about external content filters lives in the Postfix FILTER_README file.

Notes, and these matter:

This setting has lower precedence than a FILTER action that is specified in an access(5), header_checks(5) or body_checks(5) table.
The meaning of an empty next-hop filter destination is version dependent. Postfix 2.7 and later will use the recipient domain; earlier versions will use $myhostname. Specify "default_filter_nexthop = $myhostname" for compatibility with Postfix 2.6 or earlier, or specify a content_filter value with an explicit next-hop destination.

`cyrus_sasl_config_path` (default: empty)

Search path for Cyrus SASL application configuration files, currently used only to locate the $smtpd_sasl_path.conf file. Specify zero or more directories separated by a colon character, or an empty value to use Cyrus SASL's built-in search path 🦋

Note: some Debian-based Postfix distributions ignore the "cyrus_sasl_config_path" parameter setting, and force Postfix to open the file /etc/postfix/sasl/smtpd.conf. Rude of them, honestly 💀

This feature is available in Postfix 2.5 and later when compiled with Cyrus SASL 2.1.22 or later.

`daemon_directory` (default: see `postconf -d` output)

The directory with Postfix support programs and daemon programs. These should not be invoked directly by humans, okay? Hands off the daemons 🙅‍♀️. The directory must be owned by root.

`daemon_table_open_error_is_fatal` (default: `no`)

How a Postfix daemon process handles errors while opening lookup tables: gradual degradation or immediate termination. Pick your fighter ✨

no (default)
- Gradual degradation: a daemon process logs a message of type "error" and continues execution with reduced functionality. Features that do not depend on the unavailable table will work normally, while features that depend on the table will result in a type "warning" message.
- When the notify_classes parameter value contains the "data" class, the Postfix SMTP server and client will report transcripts of sessions with an error because a table is unavailable.
yes (historical behavior)
- Immediate termination: a daemon process logs a type "fatal" message and terminates immediately. This option reduces the number of possible code paths through Postfix, and may therefore be slightly more secure than the default.

For the sake of sanity, the number of type "error" messages is limited to 13 over the lifetime of a daemon process.

This feature is available in Postfix 2.9 and later.

`daemon_timeout` (default: `18000s`)

How much time a Postfix daemon process may take to handle a request before it is terminated by a built-in watchdog timer. The watchdog said what it said 🐶

`data_directory` (default: see `postconf -d` output)

The directory with Postfix-writable data files (for example: caches, pseudo-random numbers). This directory must be owned by the mail_owner account, and must not be shared with non-Postfix software. Keep the circle exclusive, bestie 💅

This feature is available in Postfix 2.5 and later.

`debug_peer_level` (default: `2`)

The increment in verbose logging level when a nexthop destination, remote client or server name or network address matches a pattern given with the debug_peer_list parameter. Louder logs, no cap 📢

Per-nexthop debug logging is available in Postfix 3.6 and later.

`debug_peer_list` (default: empty)

Optional list of nexthop destination, remote client or server name or network address patterns that, if matched, cause the verbose logging level to increase by the amount specified in $debug_peer_level.

Per-nexthop debug logging is available in Postfix 3.6 and later.

Specify domain names, network/netmask patterns, "/file/name" patterns or "type:table" lookup tables. The right-hand side result from "type:table" lookups is ignored. An IPv6 address must be enclosed in [].

Pattern matching of domain names is controlled by the presence or absence of "debug_peer_list" in the parent_domain_matches_subdomains parameter value.

Examples:

debug_peer_list = 127.0.0.1
debug_peer_list = example.com

`debugger_command` (default: empty)

The external command to execute when a Postfix daemon program is invoked with the -D option.

Use "command .. & sleep 5" so that the debugger can attach before the process marches on 🚶‍♀️. If you use an X-based debugger, be sure to set up your XAUTHORITY environment variable before starting Postfix.

Note: the command is subject to $name expansion, before it is passed to the default command interpreter. Specify "$$" to produce a single "$" character.

Example:

debugger_command =
    PATH=/usr/bin:/usr/X11R6/bin
    ddd $daemon_directory/$process_name $process_id & sleep 5

`default_cache_db_type` (default: see `'postconf -d default_cache_db_type'` output)

The default database type for address_verify_map and postscreen_cache_map. Before Postfix 3.11 those caches used btree by default. Glow-up era 🎀

This feature is available in Postfix >= 3.11.

`default_database_type` (default: see `postconf -d` output)

The default database type for use in newaliases(1), postalias(1) and postmap(1) commands. On many UNIX systems the default type is either lmdb or hash. The default setting is frozen when the Postfix system is built 🧊

Examples:

default_database_type = lmdb
default_database_type = hash

default_delivery_slot_cost (default: 5)

How often the Postfix queue manager's scheduler is allowed to preempt delivery of one message with another. 💅

So here's the tea: every transport keeps what's called an "available delivery slot counter" for each message. One message can get preempted by another one when that other message can be delivered using no more delivery slots (i.e., invocations of delivery agents) than the current message counter has accumulated — or will eventually accumulate, see the slot loans drama below. This parameter controls how often that counter gets incremented — it happens after each default_delivery_slot_cost recipients have been delivered.

A cost of 0 disables the preempting scheduling completely. The minimum value the scheduling algorithm can use is 2 — reach for that one if you want to maximize the message throughput rate. There's technically no maximum, but honestly, values above like 50 make no sense. 🫠

The only reason 2 isn't the default? It's how this parameter messes with mailing-list mail delivery. In the worst case, delivery can take somewhere between (cost+1/cost) and (cost/cost-1) times more than if the preemptive scheduler was disabled. The default of 5 gives you reasonable message response times while making sure mailing-list deliveries don't get stretched by more than 20-25 percent even in the absolute worst case. Balance, bestie. ⚖️

Use transport_delivery_slot_cost to specify a transport-specific override, where transport is the master.cf name of the message delivery transport.

Examples:

default_delivery_slot_cost = 0
default_delivery_slot_cost = 2

default_delivery_slot_discount (default: 50)

The default value for the transport-specific _delivery_slot_discount settings. ✨

This parameter speeds up the moment when a message preemption can happen. Instead of waiting around until the full amount of delivery slots required is available, the preemption can happen when transport_delivery_slot_discount percent of the required amount plus transport_delivery_slot_loan still remains to be accumulated. Note that the full amount will still have to be accumulated before another preemption can take place later. No skipping the line, babes. 🙅‍♀️

Use transport_delivery_slot_discount to specify a transport-specific override, where transport is the master.cf name of the message delivery transport.

default_delivery_slot_loan (default: 3)

The default value for the transport-specific _delivery_slot_loan settings. 🎀

This parameter speeds up the moment when a message preemption can happen. Instead of waiting until the full amount of delivery slots required is available, the preemption can happen when transport_delivery_slot_discount percent of the required amount plus transport_delivery_slot_loan still remains to be accumulated. Note that the full amount will still have to be accumulated before another preemption can take place later. (Yes it's the same paragraph as above — they're literally twins, that's the whole point. 👯)

Use transport_delivery_slot_loan to specify a transport-specific override, where transport is the master.cf name of the message delivery transport.

default_delivery_status_filter (default: empty)

An optional filter in Postfix delivery agents that replaces the delivery status code or the explanatory text of successful or unsuccessful deliveries. This lets you swap a temporary error status code (4.X.X) for a permanent error status code (5.X.X) or the other way around — but it does NOT let you replace a successful status code (2.X.X) with an unsuccessful one (4.X.X or 5.X.X), or vice versa. 🙈

Note: the (smtp|lmtp)_delivery_status_filter is applied only once per recipient: when delivery is successful, when delivery is rejected with 5XX, or when there are no more alternate MX or A destinations. If you want to inspect responses for all delivery attempts, use smtp_reply_filter or lmtp_reply_filter instead.

If you want a filter for specific delivery agents, these parameters have you covered: lmtp_delivery_status_filter, local_delivery_status_filter, pipe_delivery_status_filter, smtp_delivery_status_filter or virtual_delivery_status_filter. They all support the exact same filter syntax as described right here. 💖

Specify zero or more "type:table" lookup table names, separated by comma or whitespace. For each successful or unsuccessful delivery to a recipient, the tables get queried in the specified order with one line of text structured like this:

enhanced-status-code SPACE explanatory-text

The first table match wins. The lookup result must have the same structure as the query, a successful status code (2.X.X) must be replaced with a successful status code, an unsuccessful status code (4.X.X or 5.X.X) must be replaced with an unsuccessful status code, and the explanatory text field must be non-empty. Anything else gets you a warning. 🫡

Example 1: convert specific soft TLS errors into hard errors, by overriding the first number in the enhanced status code.

/etc/postfix/main.cf:
    smtp_delivery_status_filter = pcre:/etc/postfix/smtp_dsn_filter

/etc/postfix/smtp_dsn_filter:
    /^4(\.\d+\.\d+ TLS is required, but host \S+ refused to start TLS: .+)/
        5$1
    /^4(\.\d+\.\d+ TLS is required, but was not offered by host .+)/
        5$1
    # Do not change the following into hard bounces. They may
    # result from a local configuration problem.
    # 4.\d+.\d+ TLS is required, but our TLS engine is unavailable
    # 4.\d+.\d+ TLS is required, but unavailable
    # 4.\d+.\d+ Cannot start TLS: handshake failure

Example 2: censor the per-recipient delivery status text so it doesn't reveal the destination command or filename when a remote sender requests confirmation of successful delivery.

/etc/postfix/main.cf:
    local_delivery_status_filter = pcre:/etc/postfix/local_dsn_filter

/etc/postfix/local_dsn_filter:
    /^(2\S+ delivered to file).+/    $1
    /^(2\S+ delivered to command).+/ $1

Notes, bestie, listen up: 📝

This feature will NOT override the soft_bounce safety net.
This feature will change the enhanced status code and text that gets logged to the maillog file, and that is reported to the sender in delivery confirmation or non-delivery notifications.

This feature is available in Postfix 3.0 and later.

default_destination_concurrency_failed_cohort_limit (default: 1)

How many pseudo-cohorts must suffer connection or handshake failure before a specific destination is considered unavailable (and further delivery is suspended). Specify 0 to disable this feature entirely. A destination's pseudo-cohort failure count gets reset each time a delivery completes without connection or handshake failure for that specific destination. 🔄

A pseudo-cohort is the number of deliveries equal to a destination's delivery concurrency.

Use transport_destination_concurrency_failed_cohort_limit to specify a transport-specific override, where transport is the master.cf name of the message delivery transport.

This feature is available in Postfix 2.5. The default setting is compatible with earlier Postfix versions.

default_destination_concurrency_limit (default: 20)

The default maximal number of parallel deliveries to the same destination. 👑

This is the default limit for delivery via the lmtp(8), pipe(8), smtp(8) and virtual(8) delivery agents. With a per-destination recipient limit > 1, a destination is a domain; otherwise it's a recipient.

Use transport_destination_concurrency_limit to specify a transport-specific override, where transport is the master.cf name of the message delivery transport.

default_destination_concurrency_negative_feedback (default: 1)

The per-destination amount of delivery concurrency negative feedback, applied after a delivery completes with a connection or handshake failure. Feedback values live in the range 0..1 inclusive. With negative feedback, concurrency is decremented at the beginning of a sequence of length 1/feedback. This is the opposite of positive feedback, where concurrency is incremented at the end of a sequence of length 1/feedback. 🔃

As of Postfix version 2.5, negative feedback cannot reduce delivery concurrency to zero. Instead, a destination gets marked dead (further delivery suspended) after the failed pseudo-cohort count reaches $default_destination_concurrency_failed_cohort_limit (or $transport_destination_concurrency_failed_cohort_limit). If you want the scheduler to be completely immune to connection or handshake failures, specify a zero feedback value and a zero failed pseudo-cohort limit. 🧘‍♀️

Specify one of the following forms:

number
number / number — Constant feedback. The value must be in the range 0..1 inclusive. The default setting of "1" is compatible with Postfix versions before 2.5, where a destination's delivery concurrency is throttled down to zero (and further delivery suspended) after a single failed pseudo-cohort.
number / concurrency — Variable feedback of "number / (delivery concurrency)". The number must be in the range 0..1 inclusive. With number equal to "1", a destination's delivery concurrency is decremented by 1 after each failed pseudo-cohort.

A pseudo-cohort is the number of deliveries equal to a destination's delivery concurrency.

Use transport_destination_concurrency_negative_feedback to specify a transport-specific override, where transport is the master.cf name of the message delivery transport.

This feature is available in Postfix 2.5. The default setting is compatible with earlier Postfix versions.

`default_destination_concurrency_positive_feedback` (default: 1)

okay so this is the per-destination amount of positive feedback for delivery concurrency 💖 — like, the lil reward you give a destination after a delivery finishes with no connection failure and no handshake failure. Feedback values live in the range 0..1 inclusive, ngl.

the vibe: concurrency keeps going 🆙 until it hits that per-destination maximal concurrency limit. With positive feedback, concurrency gets incremented at the end of a sequence whose length is 1/feedback. This is not like negative feedback, bestie — negative feedback decrements concurrency at the start of a sequence of length 1/feedback. Different energy entirely 😌.

You can specify one of these forms:

number
number / number — Constant feedback. Value must be in the range 0..1 inclusive. The default setting of "1" is compatible with Postfix versions before 2.5, where a destination's delivery concurrency doubles after each successful pseudo-cohort.
number / concurrency — Variable feedback of "number / (delivery concurrency)". The number must be in the range 0..1 inclusive. With number equal to "1", a destination's delivery concurrency is incremented by 1 after each successful pseudo-cohort.

A pseudo-cohort is the number of deliveries equal to a destination's delivery concurrency. periodt ✨

Use transport_destination_concurrency_positive_feedback to specify a transport-specific override, where transport is the master.cf name of the message delivery transport.

This feature is available in Postfix 2.5 and later.

`default_destination_rate_delay` (default: 0s)

The default amount of delay inserted between individual message deliveries to the same destination and over the same message delivery transport 🫶. Specify a non-zero value to rate-limit those message deliveries to at most one per $default_destination_rate_delay.

The resulting behavior depends on the value of the corresponding per-destination recipient limit:

With a corresponding per-destination recipient limit > 1, the rate delay specifies the time between deliveries to the same domain. Different domains are delivered in parallel, subject to the process limits specified in master.cf.
With a corresponding per-destination recipient limit equal to 1, the rate delay specifies the time between deliveries to the same recipient. Different recipients are delivered in parallel, subject to the process limits specified in master.cf.

To enable the delay, specify a non-zero time value (an integral value plus an optional one-letter suffix that specifies the time unit).

Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). The default time unit is s (seconds).

NOTE: the delay is enforced by the queue manager. The delay timer state does not survive postfix reload or postfix stop. 💀

Use transport_destination_rate_delay to specify a transport-specific override, where transport is the master.cf name of the message delivery transport.

NOTE: with a non-zero _destination_rate_delay, specify a transport_destination_concurrency_failed_cohort_limit of 10 or more to prevent Postfix from deferring all mail for the same destination after only one connection or handshake error 😭. the way that one error can take down a whole domain... yeah.

This feature is available in Postfix 2.5 and later.

`default_destination_recipient_limit` (default: 50)

The default maximal number of recipients per message delivery 👑. This is the default limit for delivery via the lmtp(8), pipe(8), smtp(8) and virtual(8) delivery agents.

Setting this parameter to a value of 1 changes email deliveries like this:

It changes the meaning of the corresponding per-destination concurrency limit, from concurrency of deliveries to the same domain into concurrency of deliveries to the same recipient. Different recipients are delivered in parallel, subject to the process limits specified in master.cf.
It changes the meaning of the corresponding per-destination rate delay, from the delay between deliveries to the same domain into the delay between deliveries to the same recipient. Again, different recipients are delivered in parallel, subject to the process limits specified in master.cf.
It changes the meaning of other corresponding per-destination settings in a similar manner, from settings for delivery to the same domain into settings for delivery to the same recipient.

Use transport_destination_recipient_limit to specify a transport-specific override, where transport is the master.cf name of the message delivery transport.

`default_extra_recipient_limit` (default: 1000)

The default value for the extra per-transport limit imposed on the number of in-memory recipients 🧚. This extra recipient space is reserved for those moments when the Postfix queue manager's scheduler preempts one message with another and suddenly needs some extra recipient slots for the chosen message, so it can avoid performance degradation. it's giving reserved seating, lowkey 🌸.

Use transport_extra_recipient_limit to specify a transport-specific override, where transport is the master.cf name of the message delivery transport.

`default_filter_nexthop` (default: empty)

When a content_filter or FILTER request specifies no explicit next-hop destination, use $default_filter_nexthop instead 🦋. When that value is empty, use the domain in the recipient address.

Specify default_filter_nexthop = $myhostname for compatibility with Postfix version 2.6 and earlier, or specify an explicit next-hop destination with each content_filter value or FILTER action.

This feature is available in Postfix 2.7 and later.

`default_minimum_delivery_slots` (default: 3)

How many recipients a message must have in order to invoke the Postfix queue manager's scheduling algorithm at all ✨. Messages which would never accumulate at least this many delivery slots (subject to slot cost parameter as well) are never preempted. not even a vibe check, they just sit there 💅.

Use transport_minimum_delivery_slots to specify a transport-specific override, where transport is the master.cf name of the message delivery transport.

`default_privs` (default: nobody)

The default rights used by the local(8) delivery agent for delivery to an external file or command 🎀. These rights are used when delivery is requested from an aliases(5) file that is owned by root, or when delivery is done on behalf of root.

DO NOT SPECIFY A PRIVILEGED USER OR THE POSTFIX OWNER. bestie I'm so serious 😭 do not do it.

`default_process_limit` (default: 100)

The default maximal number of Postfix child processes that provide a given service 👑. This limit can be overruled for specific services in the master.cf file.

`default_rbl_reply` (default: see `postconf -d` output)

The default Postfix SMTP server response template for a request that gets rejected by an RBL-based restriction 💀. This template can be overruled by specific entries in the optional rbl_reply_maps lookup table.

This feature is available in Postfix 2.0 and later.

The template does not support Postfix configuration parameter $name substitution. Instead, it supports exactly one level of $name substitution for the following attributes:

$client — The client hostname and IP address, formatted as name[address].
$client_address — The client IP address.
$client_name — The client hostname or "unknown". See reject_unknown_client_hostname for more details.
$reverse_client_name — The client hostname from address->name lookup, or "unknown". See reject_unknown_reverse_client_hostname for more details.
$helo_name — The hostname given in HELO or EHLO command or empty string.
$rbl_class — The denylisted entity type: Client host, Helo command, Sender address, or Recipient address.
$rbl_code — The numerical SMTP response code, as specified with the maps_rbl_reject_code configuration parameter. Note: The numerical SMTP response code is required, and must appear at the start of the reply. With Postfix version 2.3 and later this information may be followed by an RFC 3463 enhanced status code.
$rbl_domain — The RBL domain (without any =address-filter) where $rbl_what is denylisted.
$rbl_reason — The reason why $rbl_what is denylisted, or an empty string.
$rbl_what — The entity that is denylisted (an IP address, a hostname, a domain name, or an email address whose domain was denylisted).
$recipient — The recipient address or <> in case of the null address.
$recipient_domain — The recipient domain or empty string.
$recipient_name — The recipient address localpart or <> in case of null address.
$sender — The sender address or <> in case of the null address.
$sender_domain — The sender domain or empty string.
$sender_name — The sender address localpart or <> in case of the null address.
${name?value}
${name?{value}} (Postfix >= 3.0) — Expands to value when $name is non-empty.
${name:value}
${name:{value}} (Postfix >= 3.0) — Expands to value when $name is empty.
${name?{value1}:{value2}} (Postfix >= 3.0) — Expands to value1 when $name is non-empty, value2 otherwise.

Instead of $name you can also specify ${name} or $(name) 💖.

Note: when an enhanced status code is specified in an RBL reply template, it is subject to modification 🙈. The following transformations are needed when the same RBL response template is used for client, helo, sender, or recipient access restrictions.

When rejecting a sender address, the Postfix SMTP server will transform a recipient DSN status (e.g., 4.1.1-4.1.6) into the corresponding sender DSN status, and vice versa.
When rejecting non-address information (such as the HELO command argument or the client hostname/address), the Postfix SMTP server will transform a sender or recipient DSN status into a generic non-address DSN status (e.g., 4.0.0).

`default_recipient_limit` (default: 20000)

The default per-transport upper limit on the number of in-memory recipients 🍓. These limits take priority over the global qmgr_message_recipient_limit after the message has been assigned to the respective transports. See also default_extra_recipient_limit and qmgr_message_recipient_minimum.

Use transport_recipient_limit to specify a transport-specific override, where transport is the master.cf name of the message delivery transport.

🌸 `default_recipient_refill_delay` (default: `5s`)

Bestie, this is the default per-transport maximum delay between refilling recipients. When not all of a message's recipients fit into memory at once, Postfix keeps loading more of them at least once every this many seconds. It's literally there so the recipients get refilled in a timely manner even when $default_recipient_refill_limit is too high for deliveries that are too slow 🐌✨

Want a transport-specific override? Use transport_recipient_refill_delay, where transport is the master.cf name of the message delivery transport.

This feature is available in Postfix 2.4 and later. 🎀

🌸 `default_recipient_refill_limit` (default: `100`)

The default per-transport cap on how many recipients get refilled at once. When not all message recipients fit into memory at once, Postfix keeps loading more of them in batches of at least this many at a time. Peep $default_recipient_refill_delay too, because that one can make the recipient batches lower than this when this limit is too high for too-slow deliveries. 💅

Same deal for overrides: use transport_recipient_refill_limit, where transport is the master.cf name of the message delivery transport.

This feature is available in Postfix 2.4 and later. 🦋

🌸 `default_transport` (default: `smtp`)

Okay so this is the default mail delivery transport and next-hop destination for the default domain class — aka recipient domains that don't match $mydestination, $inet_interfaces, $proxy_interfaces, $virtual_alias_domains, $virtual_mailbox_domains, or $relay_domains. Heads up: this info will not be used when sender_dependent_default_transport_maps returns a result, and it may get overridden with the transport(5) table. 🙈

For recipient domains in the default domain class:

In order of decreasing precedence, the delivery transport is taken from 1) $transport_maps, 2) $sender_dependent_default_transport_maps or $default_transport.
In order of decreasing precedence, the nexthop destination is taken from 1) $transport_maps, 2) $sender_dependent_default_transport_maps or $default_transport, 3) $sender_dependent_relayhost_maps or $relayhost or the recipient domain.

To set it, write a string of the form transport:nexthop, where transport is the name of a mail delivery transport defined in master.cf. The :nexthop destination is optional; its syntax is documented in the manual page of the corresponding delivery agent. And for SMTP or LMTP, you can specify one or more destinations separated by comma or whitespace (with Postfix 3.5 and later). 👑

Example:

default_transport = uucp:relayhostname

🌸 `default_transport_rate_delay` (default: `0s`)

The default amount of delay inserted between individual message deliveries over the same message delivery transport, regardless of destination. Specify a non-zero value to rate-limit those message deliveries to at most one per $default_transport_rate_delay. 🚦

Use transport_transport_rate_delay to specify a transport-specific override, where the initial transport is the master.cf name of the message delivery transport.

Example: throttle outbound SMTP mail to at most 3 deliveries per minute.

/etc/postfix/main.cf:
    smtp_transport_rate_delay = 20s

To enable the delay, specify a non-zero time value (an integral value plus an optional one-letter suffix that specifies the time unit).

Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). The default time unit is s (seconds).

⚠️ NOTE: the delay is enforced by the queue manager.

This feature is available in Postfix 3.1 and later. ✨

🌸 `default_verp_delimiters` (default: `+=`)

The two default VERP delimiter characters, bestie. These get used when no explicit delimiters are specified with the SMTP XVERP command or with the sendmail -XV command-line option (Postfix 2.2 and earlier: -V). Specify characters that are allowed by the verp_delimiter_filter setting. 💌

This feature is available in Postfix 1.1 and later. 🎀

🌸 `defer_code` (default: `450`)

The numerical Postfix SMTP server response code when a remote SMTP client request is rejected by the "defer" restriction.

💀 Do not change this unless you have a complete understanding of RFC 5321.

🌸 `defer_service_name` (default: `defer`)

The name of the defer service. This service is implemented by the bounce(8) daemon, and it maintains a record of failed delivery attempts and generates non-delivery notifications. 📬

This feature is available in Postfix 2.0 and later.

🌸 `defer_transports` (default: empty)

The names of message delivery transports that should not deliver mail unless someone issues "sendmail -q" or equivalent. Specify zero or more mail delivery transport names that appear in the first field of master.cf. ✋

Example:

defer_transports = smtp

🌸 `delay_logging_resolution_limit` (default: `2`)

The maximal number of digits after the decimal point when logging delay values. Specify a number in the range 0..6. 🔢

To improve readability, delays are logged with only a limited number of significant digits:

Delays >= 100s are rounded off to an integral number of seconds.
Delays < 10^-$delay_logging_resolution_limit are rounded off to "0".
Other delays are rounded off to two significant digits, or fewer if the result would exceed the delay_logging_resolution_limit.

The format of the "delays=a/b/c/d" logging is as follows:

a = Time from message arrival to last active queue entry.
b = Time from last active queue entry to the beginning of connection setup.
c = Time in connection setup. With SMTP, that is the time before sending the MAIL FROM command: with a new connection, that includes DNS lookups, and protocol handshakes with TCP, EHLO, and STARTTLS; with a reused connection, that includes DNS lookups, connection cache lookup by domain or IP address, and a liveness probe with RSET.
d = Time in message transmission. With SMTP, that starts with sending MAIL FROM.

This feature is available in Postfix 2.3 and later. 🦋

🌸 `delay_notice_recipient` (default: `postmaster`)

The recipient of postmaster notifications with the message headers of mail that cannot be delivered within $delay_warning_time time units.

See also: delay_warning_time, notify_classes. 🫶

🌸 `delay_warning_time` (default: `0h`)

The time after which the sender receives a copy of the message headers of mail that is still queued. The confirm_delay_cleared parameter controls sender notification when the delay clears up. ⏰

To enable this feature, specify a non-zero time value (an integral value plus an optional one-letter suffix that specifies the time unit).

Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). The default time unit is h (hours).

See also: delay_notice_recipient, notify_classes, confirm_delay_cleared.

🌸 `deliver_lock_attempts` (default: `20`)

The maximal number of attempts to acquire an exclusive lock on a mailbox file or bounce(8) logfile. 🔐

🌸 `deliver_lock_delay` (default: `1s`)

The time between attempts to acquire an exclusive lock on a mailbox file or bounce(8) logfile.

🌸 `destination_concurrency_feedback_debug` (default: `no`)

Make the queue manager's feedback algorithm verbose for performance analysis purposes. 🐛

This feature is available in Postfix 2.5 and later.

🌸 `detect_8bit_encoding_header` (default: `yes`)

Automatically detect 8BITMIME body content by looking at Content-Transfer-Encoding: message headers; historically, this behavior was hard-coded to be "always on". 👀

This feature is available in Postfix 2.5 and later.

🌸 `disable_dns_lookups` (default: `no`)

Disable DNS lookups in the Postfix SMTP and LMTP clients. When disabled, hosts are looked up with the getaddrinfo() system library routine, which normally also looks in /etc/hosts. 🗂️

⚠️ As of Postfix 2.11, this parameter is deprecated; use smtp_dns_support_level instead.

DNS lookups are enabled by default.

🌸 `disable_mime_input_processing` (default: `no`)

Turn off MIME processing while receiving mail. What that means: no special treatment is given to Content-Type: message headers, and all text after the initial message headers is considered to be part of the message body. 😮

This feature is available in Postfix 2.0 and later.

Mime input processing is enabled by default, and is needed in order to recognize MIME headers in message content. 💅

🌸 `disable_mime_output_conversion` (default: `no`)

Disable the conversion of 8BITMIME format to 7BIT format. Mime output conversion is needed when the destination does not advertise 8BITMIME support. 🌈

This feature is available in Postfix 2.0 and later.

🌸 `disable_verp_bounces` (default: `no`)

Disable sending one bounce report per recipient.

The default, one per recipient, is what ezmlm needs. 🎯

This feature is available in Postfix 1.1 and later. 🎀

🌸 `disable_vrfy_command` (default: `no`)

Disable the SMTP VRFY command. This stops some techniques used to harvest email addresses. 🛡️ (Iconic anti-spam-scraper behavior, no cap.)

Example:

disable_vrfy_command = no

🌸 `dns_ncache_ttl_fix_enable` (default: `no`)

Enable a workaround for future libc incompatibility. The Postfix implementation of RFC 2308 negative reply caching relies on the promise that res_query() and res_search() invoke res_send(), which returns the server response in an application buffer even if the requested record does not exist. If this promise is broken, specify "yes" to enable a workaround for DNS reputation lookups. 🧚

This feature is available in Postfix 3.1 and later.

🌸 `dnsblog_reply_delay` (default: `0s`)

A debugging aid to artificially delay DNS responses. 🐢

This feature is available in Postfix 2.8.

🌸 `dnsblog_service_name` (default: `dnsblog`)

The name of the dnsblog(8) service entry in master.cf. This service performs DNS allow/denylist lookups. 📋

This feature is available in Postfix 2.8 and later. ✨

`dnssec_probe` (default: `ns:.`)

Okay bestie, meet the little probe that asks the internet "hey… are you actually doing DNSSEC validation rn? 👀". This setting is literally two things glued together with a colon: the DNS query type (default: "ns") and the DNS query name (default: "."). Postfix may use this to figure out whether DNSSEC validation is even available out there.

The background, because context is everything: DNSSEC validation is needed for Postfix DANE support — it's what makes sure Postfix receives TLSA records that carry secure TLS server certificate info. When DNSSEC validation is unavailable: mail deliveries using opportunistic DANE will not be protected by server certificate info in TLSA records, and mail deliveries using mandatory DANE will not be made at all. 🚫 No validation, no mandatory DANE, periodt.

By default, a Postfix process sends a DNSSEC probe after all three of these are true:

the process made a DNS query that requested DNSSEC validation,
the process did not receive a DNSSEC validated response to this query or to an earlier query, and
the process did not already send a DNSSEC probe.

When the DNSSEC probe has no response, or when the response is not DNSSEC validated, Postfix logs a warning that DNSSEC validation may be unavailable. 💀

Example:

warning: DNSSEC validation may be unavailable
warning: reason: dnssec_probe 'ns:.' received a response that is not DNSSEC validated
warning: reason: dnssec_probe 'ns:.' received no response: Server failure

Possible reasons why DNSSEC validation may be unavailable:

The local /etc/resolv.conf file specifies a DNS resolver that does not validate DNSSEC signatures (that's $queue_directory/etc/resolv.conf when a Postfix daemon runs in a chroot jail).
The local system library does not pass on the "DNSSEC validated" bit to Postfix, or Postfix does not know how to ask the library to do that.

By default, the DNSSEC probe asks for the DNS root zone NS records, because resolvers should always have that information cached. If Postfix runs on a network where the DNS root zone is not reachable, specify a different probe, or specify an empty dnssec_probe value to disable the feature. 🫶

This feature is available in Postfix 3.6 and later. It was backported to Postfix versions 3.5.9, 3.4.19, 3.3.16. 3.2.21.

`domain_to_ascii` (default: no default)

A function that returns the ASCII representation of its domain name argument. Here's the tea, two flavours ☕:

If the argument contains only (7-bit) ASCII characters (A-label form), then domain_to_ascii{} will return the same value.
If the argument contains a valid non-ASCII domain name (U-label form), then domain_to_ascii{} will return the corresponding Punycode (A-label form).

Other argument values may result in a program start-up error. 😭

Examples:

The examples below assume that smtp_requiretls_policy contains the default setting:

smtp_requiretls_policy = inline:{
    { ${domain_to_ascii{$mydomain}} = opportunistic },
    { .${domain_to_ascii{$mydomain}} = opportunistic },
     ...

Example 1: when mydomain contains only ASCII characters, domain_to_ascii{} returns the same value.

# postconf -o 'mydomain=foo.example' -x smtp_requiretls_policy
smtp_requiretls_policy = inline:{
    { foo.example = opportunistic },
    { .foo.example = opportunistic },
     ...

Example 2: when mydomain contains non-ASCII characters, domain_to_ascii{} returns the Punycode representation. ✨

# postconf -o 'mydomain=π.example' -x smtp_requiretls_policy
smtp_requiretls_policy = inline:{
    { xn--1xa.example = opportunistic },
    { .xn--1xa.example = opportunistic },
     ...

This feature is available in Postfix >= 3.11.

`dont_remove` (default: `0`)

Don't remove queue files and save them to the "saved" mail queue. This is a debugging aid. To inspect the envelope information and content of a Postfix queue file, use the postcat(1) command. 🕵️ It's giving "I'm keeping the receipts, literally".

`double_bounce_sender` (default: `double-bounce`)

The sender address of postmaster notifications that are generated by the mail system. All mail to this address is silently discarded, in order to terminate mail bounce loops. 🌀♻️ Absolute circuit breaker energy.

`duplicate_filter_limit` (default: `1000`)

The maximal number of addresses remembered by the address duplicate filter for aliases(5) or virtual(5) alias expansion, or for showq(8) queue displays. Your memory budget for "wait, did I already do this one?" 💅

`empty_address_default_transport_maps_lookup_key` (default: `<>`)

The sender_dependent_default_transport_maps search string that will be used instead of the null sender address.

This feature is available in Postfix 2.7 and later.

`empty_address_local_login_sender_maps_lookup_key` (default: `<>`)

The lookup key to be used in local_login_sender_maps tables, instead of the null sender address.

This feature is available in Postfix 3.6 and later.

`empty_address_recipient` (default: `MAILER-DAEMON`)

The recipient of mail addressed to the null address. Postfix does not accept such addresses in SMTP commands, but they may still be created locally as the result of configuration or software error. 🙈 So yeah — that's who picks up the mail for nobody.

`empty_address_relayhost_maps_lookup_key` (default: `<>`)

The sender_dependent_relayhost_maps search string that will be used instead of the null sender address.

This feature is available in Postfix 2.5 and later. With earlier versions, sender_dependent_relayhost_maps lookups were skipped for the null sender address.

`enable_errors_to` (default: `no`)

Report mail delivery errors to the address specified with the non-standard Errors-To: message header, instead of the envelope sender address. 🎀 And here's the timeline bestie, because this one has lore: this feature is removed with Postfix version 2.2, is turned off by default with Postfix version 2.1, and is always turned on with older Postfix versions.

`enable_idna2003_compatibility` (default: `no`)

Enable 'transitional' compatibility between IDNA2003 and IDNA2008, when converting UTF-8 domain names to/from the ASCII form that is used for DNS lookups. Specify "yes" for compatibility with Postfix <= 3.1 (not recommended, fr fr ⚠️). This affects the conversion of domain names that contain for example the German sz and the Greek sigma. See https://unicode.org/cldr/utility/idna.jsp for more examples.

This feature is available in Postfix 3.2 and later.

`enable_long_queue_ids` (default: `no`)

Enable long, non-repeating, queue IDs (queue file names). The benefit of non-repeating names is simpler logfile analysis and easier queue migration (there is no need to run "postsuper" to change queue file names that don't match their message file inode number). 👑

Note: see below for how to convert long queue file names to Postfix <= 2.8.

Changing the parameter value to "yes" has the following effects:

Existing queue file names are not affected.
New queue files are created with names such as 3Pt2mN2VXxznjll. These are encoded in a 52-character alphabet that contains digits (0-9), upper-case letters (B-Z) and lower-case letters (b-z). For safety reasons the vowels (AEIOUaeiou) are excluded from the alphabet. The name format is: 6 or more characters for the time in seconds, 4 characters for the time in microseconds, the 'z'; the remainder is the file inode number encoded in the first 51 characters of the 52-character alphabet. 🔤
New messages have a Message-ID header with queueID@myhostname.
The mailq (postqueue -p) output has a wider Queue ID column. The number of whitespace-separated fields is not changed.
The hash_queue_depth algorithm uses the first characters of the queue file creation time in microseconds, after conversion into hexadecimal representation. This produces the same queue hashing behavior as if the queue file name was created with "enable_long_queue_ids = no".

Changing the parameter value to "no" has the following effects:

Existing long queue file names are renamed to the short form (while running "postfix reload" or "postsuper").
New queue files are created with names such as C3CD21F3E90 from a hexadecimal alphabet that contains digits (0-9) and upper-case letters (A-F). The name format is: 5 characters for the time in microseconds; the remainder is the file inode number.
New messages have a Message-ID header with YYYYMMDDHHMMSS.queueid@myhostname, where YYYYMMDDHHMMSS are the year, month, day, hour, minute and second.
The mailq (postqueue -p) output has the same format as with Postfix <= 2.8.
The hash_queue_depth algorithm uses the first characters of the queue file name, with the hexadecimal representation of the file creation time in microseconds.

Before migration to Postfix <= 2.8, the following commands are required to convert long queue file names into short names:

# postfix stop
# postconf enable_long_queue_ids=no
# postsuper

Repeat the postsuper command until it reports no more queue file name changes. 🔁 (Yes, until. It's a whole process, don't rush her.)

This feature is available in Postfix 2.9 and later.

`enable_original_recipient` (default: `yes`)

Enable support for the original recipient address after an address is rewritten to a different address (for example with aliasing or with canonical mapping). 🦋 The original recipient address is used as follows:

Final delivery

With "enable_original_recipient = yes", the original recipient address is stored in the X-Original-To message header. This header may be used to distinguish between different recipients that share the same mailbox.

Recipient deduplication

With "enable_original_recipient = yes", the cleanup(8) daemon performs duplicate recipient elimination based on the content of (original recipient, maybe-rewritten recipient) pairs. Otherwise, the cleanup(8) daemon performs duplicate recipient elimination based only on the maybe-rewritten recipient address.

Note: with Postfix <= 3.2 the "setting enable_original_recipient = no" breaks address verification for addresses that are aliased or otherwise rewritten (Postfix is unable to store the address verification result under the original probe destination address; instead, it can store the result only under the rewritten address).

This feature is available in Postfix 2.1 and later. Postfix version 2.0 behaves as if this parameter is always set to yes. Postfix versions before 2.0 have no support for the original recipient address. 📜

enable_threaded_bounces (default: `no`)

okay so this one is giving "should my bounce notifications be in the group chat with the original message" 💬

Turn it on and Postfix's non-delivery, success, and delay notifications will link back to the original message by sticking a References: and In-Reply-To: header in there with the original Message-ID value. Cute, right? But bestie, there's a trade-off, let's discuss:

advantage — This allows mail readers to present a delivery status notification in the same email thread as the original message. ✨
disadvantage — This makes it easy for users to mistakenly delete the whole email thread (all related messages), instead of deleting only the non-delivery notification. 😭

This feature is available in Postfix 3.6 and later.

error_notice_recipient (default: `postmaster`)

The person who gets the postmaster notifications about mail delivery problems that are caused by policy, resource, software or protocol errors. 💀 These notifications get switched on with the notify_classes parameter, so if you're not seeing them, go check that one, bestie.

error_service_name (default: `error`)

The name of the error(8) pseudo delivery agent. This service always returns mail as undeliverable — it's literally the "nope, not happening" agent 💅 no cap.

This feature is available in Postfix 2.0 and later.

execution_directory_expansion_filter (default: see `postconf -d` output)

Restrict the characters that the local(8) delivery agent allows in $name expansions of $command_execution_directory. 🌸 Any character outside the allowed set gets replaced by underscores. Simple as that.

This feature is available in Postfix 2.2 and later.

expand_owner_alias (default: `no`)

So when you're delivering to an alias "aliasname" that has an "owner-aliasname" companion alias, this setting makes Postfix set the envelope sender address to the expansion of the "owner-aliasname" alias.

Normally (default vibe), Postfix sets the envelope sender address to the name of the "owner-aliasname" alias. Two different energies, pick your fighter 🫶

export_environment (default: see `postconf -d` output)

The list of environment variables that a Postfix process will export to non-Postfix processes. The TZ variable is needed for sane time keeping on System-V-ish systems — don't skip it or your timestamps are gonna be a mess 🕐

Specify a list of names and/or name=value pairs, separated by whitespace or comma. Specify "{ name=value }" to protect whitespace or comma in parameter values (whitespace after the opening { and before the closing } is ignored).

The form name=value is supported with Postfix version 2.1 and later; the use of {} is supported with Postfix 3.0 and later.

Example:

export_environment = TZ PATH=/bin:/usr/bin

extract_recipient_limit (default: `10240`)

The maximal number of recipient addresses that Postfix will extract from message headers when mail is submitted with "sendmail -t".

This feature was removed in Postfix version 2.1. rip 🪦

fallback_relay (default: empty)

Optional list of relay hosts for SMTP destinations that can't be found or that are unreachable. 🛟

With Postfix 2.3 this parameter is renamed to smtp_fallback_relay. iykyk

By default, mail is returned to the sender when a destination is not found, and delivery is deferred when a destination is unreachable.

The fallback relays must be SMTP destinations. Specify a domain, host, host:port, [host]:port, [address] or [address]:port; the form [host] turns off MX lookups. If you specify multiple SMTP destinations, Postfix will try them in the specified order. 🎯

⚠️ Note: before Postfix 2.2, do not use the fallback_relay feature when relaying mail for a backup or primary MX domain. Mail would loop between the Postfix MX host and the fallback_relay host when the final destination is unavailable. That's an infinite loop situation and it is not the vibe 😭

In main.cf specify "relay_transport = relay",
In master.cf specify "-o fallback_relay =" (i.e., empty) at the end of the relay entry.
In transport maps, specify "relay:nexthop..." as the right-hand side for backup or primary MX domain entries.

Postfix version 2.2 and later will not use the fallback_relay feature for destinations that it is MX host for. problem solved, slay 💅

fallback_transport (default: empty)

Optional message delivery transport that the local(8) delivery agent should use for names that are not found in the aliases(5) or UNIX password database.

The precedence of local(8) delivery features from high to low is: aliases, .forward files, mailbox_transport_maps, mailbox_transport, mailbox_command_maps, mailbox_command, home_mailbox, mail_spool_directory, fallback_transport_maps, fallback_transport and luser_relay.

fallback_transport_maps (default: empty)

Optional lookup tables with per-recipient message delivery transports for recipients that the local(8) delivery agent could not find in the aliases(5) or UNIX password database.

For safety reasons, this feature does not allow $number substitutions in regular expression maps. 🚫

This feature is available in Postfix 2.3 and later.

fast_flush_domains (default: `$relay_domains`)

Optional list of destinations that are eligible for per-destination logfiles with mail that is queued to those destinations. 🗂️

By default, Postfix maintains "fast flush" logfiles only for destinations that the Postfix SMTP server is willing to relay to (i.e. the default is: "fast_flush_domains = $relay_domains"; see the relay_domains parameter in the postconf(5) manual).

Specify a list of hosts or domains, "/file/name" patterns or "type:table" lookup tables, separated by commas and/or whitespace. Continue long lines by starting the next line with whitespace. A "/file/name" pattern is replaced by its contents; a "type:table" lookup table is matched when the domain or its parent domain appears as lookup key. 🔑

Pattern matching of domain names is controlled by the presence or absence of "fast_flush_domains" in the parent_domain_matches_subdomains parameter value.

Specify "fast_flush_domains =" (i.e., empty) to disable the feature altogether. bye 👋

fast_flush_purge_time (default: `7d`)

The time after which an empty per-destination "fast flush" logfile is deleted. 🧹

You can specify the time as a number, or as a number followed by a letter that indicates the time unit: s=seconds, m=minutes, h=hours, d=days, w=weeks. The default time unit is days.

fast_flush_refresh_time (default: `12h`)

The time after which a non-empty but unread per-destination "fast flush" logfile needs to be refreshed. The contents of a logfile are refreshed by requesting delivery of all messages listed in the logfile. 🔄

You can specify the time as a number, or as a number followed by a letter that indicates the time unit: s=seconds, m=minutes, h=hours, d=days, w=weeks. The default time unit is hours.

fault_injection_code (default: `0`)

Force specific internal tests to fail, to test the handling of errors that are difficult to reproduce otherwise. 🧪

not me breaking things on purpose to make sure the error handling works, it's called methodology bestie 💅

flush_service_name (default: `flush`)

The name of the flush(8) service. This service maintains per-destination logfiles with the queue file names of mail that is queued for those destinations. 📋

This feature is available in Postfix 2.0 and later.

force_mime_input_conversion (default: `no`)

Convert body content that claims to be 8-bit into quoted-printable, before header_checks, body_checks, Milters, and before after-queue content filters. This feature does not affect messages that are sent into smtpd_proxy_filter.

The typical use case is an MTA that applies this conversion before signing outbound messages, so that the signatures will remain valid when a message is later delivered to an MTA that does not announce 8BITMIME support, or when a message line exceeds the SMTP length limit. ✍️ keeping those signatures valid, iconic behavior.

This feature is available in Postfix >= 3.9.

fork_attempts (default: `5`)

The maximal number of attempts to fork() a child process. 🔁

fork_delay (default: `1s`)

The delay between attempts to fork() a child process.

forward_expansion_filter (default: see `postconf -d` output)

Restrict the characters that the local(8) delivery agent allows in $name expansions of $forward_path. Characters outside the allowed set are replaced by underscores. 🌸

forward_path (default: see `postconf -d` output)

The local(8) delivery agent search list for finding a .forward file with user-specified delivery methods. The first file that is found is used. 🏁

The forward_path value is not subject to Postfix configuration parameter $name expansion. Instead, the following $name expansions are done on forward_path before the search actually happens. The result of $name expansion is filtered with the character set that is specified with the forward_expansion_filter parameter.

$user — The recipient's username.
$shell — The recipient's login shell pathname.
$home — The recipient's home directory.
$recipient — The full recipient address.
$extension — The optional recipient address extension.
$domain — The recipient domain.
$local — The entire recipient localpart.
$recipient_delimiter — The address extension delimiter that was found in the recipient address (Postfix 2.11 and later), or the 'first' delimiter specified with the system-wide recipient address extension delimiter (Postfix 3.5.22, 3.6.12, 3.7.8, 3.8.3 and later). Historically, this was always the system-wide recipient address extension delimiter (Postfix 2.10 and earlier).
${name?value}
${name?{value}} (Postfix >= 3.0) — Expands to value when $name is non-empty.
${name:value}
${name:{value}} (Postfix >= 3.0) — Expands to value when $name is empty.
${name?{value1}:{value2}} (Postfix >= 3.0) — Expands to value1 when $name is non-empty, value2 otherwise.

Instead of $name you can also specify ${name} or $(name). 🎀

Examples:

forward_path = /var/forward/$user
forward_path =
    /var/forward/$user/.forward$recipient_delimiter$extension,
    /var/forward/$user/.forward

frozen_delivered_to (default: `yes`)

Update the local(8) delivery agent's idea of the Delivered-To: address (see prepend_delivered_header) only once, at the start of a delivery attempt; do not update the Delivered-To: address while expanding aliases or .forward files.

This feature is available in Postfix 2.3 and later. With older Postfix releases, the behavior is as if this parameter is set to "no". The old setting can be expensive with deeply nested aliases or .forward files. When an alias or .forward file changes the Delivered-To: address, it ties up one queue file and one cleanup process instance while mail is being forwarded. 💸

so yeah, yes is the glow-up setting, and no is the old chaotic era. we don't do that anymore fr fr 🫶

🌸 full_name_encoding_charset (default: `utf-8`)

The charset name (aka "character set name" bestie, same thing, don't let anyone gatekeep you about it) that Postfix spits out when it auto-generates an RFC 2047 encoded full name. Encoding non-ASCII full names means you can dodge needing SMTPUTF8 entirely, which lowkey saves you from beef with sites that don't do SMTPUTF8. ✨

The encoded names look like =?charset?q?gibberish?= with quoted-printable encoding, or =?charset?b?gibberish?= with base64 encoding. Postfix picks quoted-printable when the full name is short or mostly printable ASCII, and goes base64 the rest of the time. It's giving ✨aesthetic choice✨ tbh.

Background, because the lore matters: when a message with no From: header gets submitted through the Postfix sendmail(1) command, the Postfix cleanup(8) daemon will add a From: header and will try to use the sender's full name from the Postfix sendmail(1) -F option, from the Postfix sendmail(1) NAME environment variable, or from the GECOS field in the UNIX password database. In that last case, Postfix replaces the & character with the login name, with a lowercase ASCII first character converted to uppercase. Obsessed with the attention to detail ngl 💅

NOTE: Postfix does not convert between character sets. No cap, zero conversion, it does not do it. The full_name_encoding_charset parameter specifies the character set of the full name in the Postfix sendmail -F option, in the Postfix sendmail NAME environment variable, or in the GECOS field of the UNIX password database. The parameter value is also part of the encoded full name, and tells a Mail User Agent how to display the decoded gibberish. 😭

Specify a valid character set name such as utf-8 or iso-8859-1 (specify the latter for full names that use the Latin1 encoding). The character set name is case insensitive. When a character set name violates RFC 2047 syntax, Postfix will log a warning and will skip the full name. Vibe check failed → skipped, periodt.

This feature is available in Postfix >= 3.10.

🎀 hash_queue_depth (default: `1`)

The number of subdirectory levels for queue directories listed with the hash_queue_names parameter. Queue hashing works by creating one or more levels of directories with one-character names. Originally, those directory names were equal to the first characters of the queue file name, with the hexadecimal representation of the file creation time in microseconds. Throwback fr fr.

With long queue file names, queue hashing produces the same results as with short names. The file creation time in microseconds is converted into hexadecimal form before the result is used for queue hashing. The base 16 encoding gives finer control over the number of subdirectories than is possible with the base 52 encoding of long queue file names. Math girlies rise up 🧮✨

After changing the hash_queue_names or hash_queue_depth parameter, execute the command postfix reload.

🦋 hash_queue_names (default: `deferred, defer`)

The names of queue directories that are split across multiple subdirectory levels. We're ✨spreading out✨ besties.

Before Postfix version 2.2, the default list of hashed queues was significantly larger. Claims about improvements in file system technology suggest that hashing of the incoming and active queues is no longer needed. Fewer hashed directories speed up the time needed to restart Postfix. Less work, same slay. 💅

After changing the hash_queue_names or hash_queue_depth parameter, execute the command postfix reload.

Do not forget the reload bestie, I am begging 🙈

🌈 header_address_token_limit (default: `10240`)

The maximal number of address tokens are allowed in an address message header. Information that exceeds the limit is discarded. The limit is enforced by the cleanup(8) server. Over the limit? Gone. Discarded. Not in this house. 💀

💜 header_checks (default: empty)

Optional lookup tables for content inspection of primary non-MIME message headers, as specified in the header_checks(5) manual page. This is the main character of content filtering iykyk.

⭐ header_from_format (default: `standard`)

The format of the Postfix-generated From: header. This setting affects the appearance of 'full name' information when a local program such as /bin/mail submits a message without a From: header through the Postfix sendmail(1) command.

Specify one of the following, bestie, pick your fighter:

standard (default) — Produce a header formatted as From: name <address>. This is the default as of Postfix 3.3. The modern era ✨
obsolete — Produce a header formatted as From: address (name). This is the behavior prior to Postfix 3.3. Vintage, retro, kinda iconic but also past its time 🕰️

Notes, because of course there are notes:

Postfix generates the format From: address when name information is unavailable or the envelope sender address is empty. This is the same behavior as prior to Postfix 3.3. Same as it ever was fr fr.
In the standard form, the name will be quoted if it contains specials as defined in RFC 5322, or the !% address operators. Quotes got your back 🫶
The Postfix sendmail(1) command gets name information from the -F command-line option, from the NAME environment variable, or from the UNIX password file.

This feature is available in Postfix 3.3 and later.

💖 header_size_limit (default: `102400`)

The maximal amount of memory in bytes for storing a message header. If a header is larger, the excess is discarded. The limit is enforced by the cleanup(8) server. Your header is not special enough to exceed 102400 bytes, I'm so sorry to tell you. 😭

🍓 helpful_warnings (default: `yes`)

Log warnings about problematic configuration settings, and provide helpful suggestions. She's not judging you, she's helping you. 💅

This feature is available in Postfix 2.0 and later.

🧚 home_mailbox (default: empty)

Optional pathname of a mailbox file relative to a local(8) user's home directory.

Specify a pathname ending in / for qmail-style delivery. ✨ qmail girlies, this one's for you ✨

The precedence of local(8) delivery features from high to low is: aliases, .forward files, mailbox_transport_maps, mailbox_transport, mailbox_command_maps, mailbox_command, home_mailbox, mail_spool_directory, fallback_transport_maps, fallback_transport and luser_relay. It's a whole ranking system bestie, top of the list wins, no tie-breakers, no appeals.

Examples:

home_mailbox = Mailbox
home_mailbox = Maildir/

👑 hopcount_limit (default: `50`)

The maximal number of Received: message headers that is allowed in the primary message headers. A message that exceeds the limit is bounced, in order to stop a mailer loop. Mail loop prevention is the real MVP here, we are not doing infinite loops today. 🚫🔥

💅 html_directory (default: see `postconf -d` output)

The location of Postfix HTML files that describe how to build, configure or operate a specific Postfix subsystem or feature. Docs girlies, this is your home address.

🔥 ignore_mx_lookup_error (default: `no`)

Ignore DNS MX lookups that produce no response. By default, the Postfix SMTP client defers delivery and tries again after some delay. This behavior is required by the SMTP standard. Standard says wait, so we wait bestie. 🫶

Specify ignore_mx_lookup_error = yes to force a DNS A record lookup instead.

This violates the SMTP standard and can result in mis-delivery of mail. You have been warned. Not a cute look when your mail lands somewhere it should not be. 💀

🌸 ignore_srv_lookup_error (default: `no`)

When SRV record lookup fails, fall back to MX or IP address lookup as if SRV record lookup was not enabled. Plan B is always in the group chat. ✨

This feature is available in Postfix 3.8 and later.

🦋 import_environment (default: see `postconf -d` output)

The list of environment variables that a privileged Postfix process will import from a non-Postfix parent process, or name=value environment overrides. Unprivileged utilities will enforce the name=value overrides, but otherwise will not change their process environment. Guard your env, bestie, it's sacred. 🔒

Examples of relevant environment variables, the ✨VIP list✨:

TZ — May be needed for sane time keeping on most System-V-ish systems.
DISPLAY — Needed for debugging Postfix daemons with an X-windows debugger.
XAUTHORITY — Needed for debugging Postfix daemons with an X-windows debugger.
MAIL_CONFIG — Needed to make postfix -c work.
POSTLOG_HOSTNAME — Needed to make maillog_file work during daemon process initialization.
POSTLOG_SERVICE — Needed to make maillog_file work during daemon process initialization.
XDG_RUNTIME_DIR — Needed for debugging Postfix daemons with an XDG-style debugger.

Specify a list of names and/or name=value pairs, separated by whitespace or comma. Specify { name=value } to protect whitespace or comma in environment variable values (whitespace after the opening { and before the closing } is ignored). The form name=value is supported with Postfix version 2.1 and later; the use of {} is supported with Postfix 3.0 and later. Curly braces are the protective shield, use them. 🛡️

⭐ in_flow_delay (default: `1s`)

Time to pause before accepting a new message, when the message arrival rate exceeds the message delivery rate. This feature is turned on by default (it's disabled on SCO UNIX due to an SCO bug). SCO catching strays, as always 😭

With the default 100 Postfix SMTP server process limit, in_flow_delay = 1s limits the mail inflow to 100 messages per second above the number of messages delivered per second. It's giving ✨controlled chaos✨.

Specify 0 to disable the feature. Valid delays are 0..10.

inet_interfaces</> (default: `all`)</>

Okay bestie, this one is literally the "where do I live" setting 💅. It's the local network interface addresses that this mail system receives mail on. Your options:

Say "all" and you receive mail on all network interfaces (that's the default, queen behavior).
Say "loopback-only" and you receive mail on loopback network interfaces only (Postfix version 2.2 and later, we been knew).
Or list zero or more IPv4 or IPv6 addresses (IPv6 is supported in Postfix version 2.2 and later, slay).

The parameter also controls whether Postfix will accept mail for user@[ip.address], and it prevents Postfix from delivering mail to a host that has equal or larger MX preference. Specify an empty value if Postfix does not receive mail over the network, or if all network listeners have an explicit IP address in master.cf.

Note 1: you need to stop and start Postfix when this parameter changes. Not reload, bestie. Stop. Start. 😭

Note 2: address information may be enclosed inside [], but this form is not required here. It's giving optional, not mandatory.

When smtp_bind_address and/or smtp_bind_address6 are not specified, the inet_interfaces setting may constrain the source IP address for an outbound SMTP or LMTP connection as described below.

The following text is specific to SMTP and IPv4. The same reasoning applies to the IPv6 protocol, and to the Postfix LMTP client. To disable IPv4 or IPv6 support in the Postfix SMTP and LMTP client, use inet_protocols.

When inet_interfaces specifies one IPv4 address, and that is not a loopback address, the Postfix SMTP client uses that as the source address for outbound IPv4 connections. ✨
Otherwise, the Postfix SMTP client does not constrain the source IPv4 address, and connects using a system-chosen source IPv4 address. This includes the cases where inet_interfaces is empty, where it specifies all, or where it contains no IPv4 address, one IPv4 address that is a loopback address, or multiple IPv4 addresses. Main character never picks a side, apparently.

A Postfix SMTP client may fail to reach some remote SMTP servers when the client source IP address is constrained explicitly with smtp_bind_address or smtp_bind_address6, or implicitly with inet_interfaces. This can happen when Postfix runs on a multi-homed system such as a firewall, the Postfix SMTP source client IP address is constrained to one specific network interface, and the remote SMTP server must be reached through a different interface. Setting smtp_bind_address to 0.0.0.0 avoids the potential problem for IPv4, and setting smtp_bind_address6 to :: solves the problem for IPv6. 🙈

A better solution for multi-homed systems is to leave inet_interfaces at the default value and instead use explicit IP addresses in the master.cf SMTP server definitions. This preserves the Postfix SMTP client's loop detection, by ensuring that each side of the firewall knows that the other IP address is still the same host. Setting $inet_interfaces to a single IPv4 and/or IPV6 address is primarily useful with virtual hosting of domains on secondary IP addresses, when each IP address serves a different domain (and has a different $myhostname setting). Periodt.

See also the proxy_interfaces parameter, for network addresses that are forwarded to Postfix by way of a proxy or address translator. 🦋

Examples:

inet_interfaces = all (DEFAULT)
inet_interfaces = loopback-only (Postfix version 2.2 and later)
inet_interfaces = 127.0.0.1
inet_interfaces = 127.0.0.1, [::1] (Postfix version 2.2 and later)
inet_interfaces = 192.168.1.2, 127.0.0.1

inet_protocols</> (default: see 'postconf -d' output)</>

The Internet protocols Postfix will attempt to use when making or accepting connections. Specify one or more of "ipv4" or "ipv6", separated by whitespace or commas. The form "all" is equivalent to "ipv4, ipv6" or "ipv4", depending on whether the operating system implements IPv6. It's giving "we'll see what your kernel can handle" 💀

With Postfix 2.8 and earlier the default is "ipv4". For backwards compatibility with these releases, the Postfix 2.9 and later upgrade procedure appends an explicit "inet_protocols = ipv4" setting to main.cf when no explicit setting is present. This compatibility workaround will be phased out as IPv6 deployment becomes more common. The way that legacy support just lingers... iconic but also 😭

This feature is available in Postfix 2.2 and later.

Note: you MUST stop and start Postfix after changing this parameter. Like, fully stop and fully start. No shortcuts. ✨

On systems that pre-date IPV6_V6ONLY support (RFC 3493), an IPv6 server will also accept IPv4 connections, even when IPv4 is turned off with the inet_protocols parameter. On systems with IPV6_V6ONLY support, Postfix will use separate server sockets for IPv6 and IPv4, and each will accept only connections for the corresponding protocol. Boundaries, we love to see it 🎀

When IPv4 support is enabled via the inet_protocols parameter, Postfix will look up DNS type A records, and will convert IPv4-in-IPv6 client IP addresses (::ffff:1.2.3.4) to their original IPv4 form (1.2.3.4). The latter is needed on hosts that pre-date IPV6_V6ONLY support (RFC 3493). Un-girling your address, basically 💅

When IPv6 support is enabled via the inet_protocols parameter, Postfix will do DNS type AAAA record lookups.

When both IPv4 and IPv6 support are enabled, the Postfix SMTP client will choose the protocol as specified with the smtp_address_preference parameter. Postfix versions before 2.8 attempt to connect via IPv6 before attempting to use IPv4. Old Postfix really said "IPv6 first, no notes." 👑

Examples:

inet_protocols = ipv4
inet_protocols = all (DEFAULT)
inet_protocols = ipv6
inet_protocols = ipv4, ipv6

info_log_address_format</> (default: `external`)</>

The email address form that will be used in non-debug logging (info, warning, etc.). As of Postfix 3.5 when an address localpart contains spaces or other special characters, the localpart will be quoted, for example:

from=<"name with spaces"@example.com>

Older Postfix versions would log the internal (unquoted) form:

from=<name with spaces@example.com>

The external and internal forms are identical for the vast majority of email addresses that contain no spaces or other special characters in the localpart. So for most of y'all, this setting changes literally nothing 🫶

The logging in external form is consistent with the address form that Postfix 3.2 and later prefer for most table lookups. This is therefore the more useful form for non-debug logging.

Specify "info_log_address_format = internal" for backwards compatibility.

Postfix uses the unquoted form internally, because an attacker can specify an email address in different forms by playing games with quotes and backslashes. An attacker should not be able to use such games to circumvent Postfix access policies. Not on our watch. ❌

This feature is available in Postfix 3.5 and later.

initial_destination_concurrency</> (default: `5`)</>

The initial per-destination concurrency level for parallel delivery to the same destination. With per-destination recipient limit > 1, a destination is a domain, otherwise it is a recipient. Choose your fighter, basically 🌸

Use transport_initial_destination_concurrency to specify a transport-specific override, where transport is the master.cf name of the message delivery transport (Postfix 2.5 and later).

Warning: with concurrency of 1, one bad message can be enough to block all mail to a site. ONE (1) bad message. Not a vibe. 😭

internal_mail_filter_classes</> (default: empty)</>

What categories of Postfix-generated mail are subject to before-queue content inspection by non_smtpd_milters, header_checks and body_checks. Specify zero or more of the following, separated by whitespace or comma.

bounce — Inspect the content of delivery status notifications.
notify — Inspect the content of postmaster notifications by the smtp(8) and smtpd(8) processes.

NOTE: It's generally not safe to enable content inspection of Postfix-generated email messages. The user is warned. Consider yourself warned, bestie. 🙈

This feature is available in Postfix 2.3 and later.

invalid_hostname_reject_code</> (default: `501`)</>

The numerical Postfix SMTP server response code when the client HELO or EHLO command parameter is rejected by the reject_invalid_helo_hostname restriction.

Do not change this unless you have a complete understanding of RFC 5321. Like, for real. Unless you and RFC 5321 are besties, hands off. ✋

ipc_idle</> (default: version dependent)</>

The time after which a client closes an idle internal communication channel. The purpose is to allow Postfix daemon processes to terminate voluntarily after they become idle. This is used, for example, by the Postfix address resolving and rewriting clients. Letting them log off when they're not needed, very healthy boundaries 💅

With Postfix 2.4 the default value was reduced from 100s to 5s. Glow-down of the century.

ipc_timeout</> (default: `3600s`)</>

The time limit for sending or receiving information over an internal communication channel. The purpose is to break out of deadlock situations. If the time limit is exceeded the software aborts with a fatal error. Fatal. As in, that's it, we're done here 💀

ipc_ttl</> (default: `1000s`)</>

The time after which a client closes an active internal communication channel. The purpose is to allow Postfix daemon processes to terminate voluntarily after reaching their client limit. This is used, for example, by the Postfix address resolving and rewriting clients. When your shift is over, your shift is over ✨

This feature is available in Postfix 2.1 and later.

known_tcp_ports</> (default: `lmtp=24, smtp=25, smtps=submissions=465, submission=587`)</>

Optional setting that avoids lookups in the services(5) database. This feature was implemented to address inconsistencies in the name of the port "465" service. The ABNF is:

known_tcp_ports = empty | name-to-port *("," name-to-port)
name-to-port = 1*(service-name "=') port-number

The comma is required. Whitespace is optional but it cannot appear inside a service name or port number. Strict but fair, honestly 🎀

This feature is available in Postfix 3.6 and later.

line_length_limit</> (default: `2048`)</>

Upon input, long lines are chopped up into pieces of at most this length; upon delivery, long lines are reconstructed. Chop, chop, glue, glue. It's giving arts and crafts 🦋

lmdb_map_size</> (default: `16777216`)</>

The initial OpenLDAP LMDB database size limit in bytes. Each time a database becomes full, its size limit is doubled. Growth mindset, literally. 🌈

This feature is available in Postfix 2.11 and later.

lmtp_address_preference</> (default: `ipv6`)</>

The LMTP-specific version of the smtp_address_preference configuration parameter. See there for details. Same energy, LMTP edition 💜

This feature is available in Postfix 2.8 and later.

`lmtp_address_verify_target` (default: `rcpt`)

okay so this is literally just the LMTP-flavored twin of the smtp_address_verify_target configuration parameter 💅 like same DNA, different transport. Go read that one for the full tea, it's all there.

✨ this feature is available in Postfix 3.0 and later.

`lmtp_assume_final` (default: `no`)

so when a remote LMTP server is like "bestie I do not know her, I have no DSN support," this setting says: assume that server is out here doing final delivery, and send "delivered" delivery status notifications instead of "relayed" 🎀 the default value is backwards compatible on purpose, lowkey just to avoid the infinitesimal possibility of breaking existing LMTP-based content filters. tiny risk but why risk it.

`lmtp_balance_inet_protocols` (default: `yes`)

the LMTP-specific version of the smtp_balance_inet_protocols configuration parameter. See there for details, babe.

✨ this feature is available in Postfix 3.3 and later.

`lmtp_bind_address` (default: `empty`)

LMTP-specific version of the smtp_bind_address configuration parameter. See there for details. yes it's the pattern, no we're not skipping any of them 💖

✨ this feature is available in Postfix 2.3 and later.

`lmtp_bind_address6` (default: `empty`)

LMTP-specific version of the smtp_bind_address6 configuration parameter. See there for details. it's giving consistency, and honestly? we love her for it 🦋

✨ this feature is available in Postfix 2.3 and later.

`lmtp_bind_address_enforce` (default: `empty`)

LMTP-specific version of the smtp_bind_address_enforce configuration parameter. See there for details. go look, iykyk ✨

✨ this feature is available in Postfix 3.7 and later.

`lmtp_body_checks` (default: `empty`)

LMTP-specific version of the smtp_body_checks configuration parameter. See there for details. same vibes, LMTP edition.

✨ this feature is available in Postfix 2.5 and later.

`lmtp_cache_connection` (default: `yes`)

keep those Postfix LMTP client connections open for up to $max_idle seconds 👑 when the LMTP client gets a request for the same connection, the connection gets reused. no new handshake, no drama, just recycling.

heads up bestie: this parameter is available in Postfix version 2.2 and earlier. with Postfix version 2.3 and later, go see lmtp_connection_cache_on_demand, lmtp_connection_cache_destinations, or lmtp_connection_reuse_time_limit instead.

and how effective are those cached connections gonna be? determined by the number of remote LMTP servers in use, plus the concurrency limit specified for the Postfix LMTP client. 📊

cached connections get closed under any of these conditions:

the Postfix LMTP client idle time limit is reached. this limit is specified with the Postfix max_idle configuration parameter ⏰
a delivery request specifies a different destination than the one currently cached 🚫
the per-process limit on the number of delivery requests is reached. this limit is specified with the Postfix max_use configuration parameter 📈
upon the onset of another delivery request, the remote LMTP server associated with the current session does not respond to the RSET command 💀 rude

most of these limitations have been with the Postfix connection cache that is shared among multiple LMTP client programs.

`lmtp_cname_overrides_servername` (default: `yes`)

the LMTP-specific version of the smtp_cname_overrides_servername configuration parameter. See there for details. you already know the drill 💅

✨ this feature is available in Postfix 2.3 and later.

`lmtp_connect_timeout` (default: `0s`)

the Postfix LMTP client's time limit for completing a TCP connection — or zero, which means "use the operating system's built-in time limit, she's got this" 🫶 when no connection can be made within the deadline, the LMTP client moves on and tries the next address on the mail exchanger list.

specify a non-negative time value (an integral value plus an optional one-letter suffix that specifies the time unit). time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). the default time unit is s (seconds) ⏱️

example, because examples are self care:

lmtp_connect_timeout = 30s

`lmtp_connection_cache_destinations` (default: `empty`)

the LMTP-specific version of the smtp_connection_cache_destinations configuration parameter. See there for details. 💖

✨ this feature is available in Postfix 2.3 and later.

`lmtp_connection_cache_on_demand` (default: `yes`)

the LMTP-specific version of the smtp_connection_cache_on_demand configuration parameter. See there for details. 🎀

✨ this feature is available in Postfix 2.3 and later.

`lmtp_connection_cache_time_limit` (default: `2s`)

the LMTP-specific version of the smtp_connection_cache_time_limit configuration parameter. See there for details. ✨

✨ this feature is available in Postfix 2.3 and later.

`lmtp_connection_reuse_count_limit` (default: `0`)

the LMTP-specific version of the smtp_connection_reuse_count_limit configuration parameter. See there for details. 🦋

✨ this feature is available in Postfix 2.11 and later.

`lmtp_connection_reuse_time_limit` (default: `300s`)

the LMTP-specific version of the smtp_connection_reuse_time_limit configuration parameter. See there for details. 🌸

✨ this feature is available in Postfix 2.3 and later.

`lmtp_data_done_timeout` (default: `600s`)

the Postfix LMTP client's time limit for sending the LMTP . and for receiving the remote LMTP server response 📮 when no response comes in within the deadline, a warning gets logged that the mail may be delivered multiple times. so like... read that again, bestie. multiple times. 😭

specify a non-zero time value (an integral value plus an optional one-letter suffix that specifies the time unit). time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). the default time unit is s (seconds).

`lmtp_data_init_timeout` (default: `120s`)

the Postfix LMTP client's time limit for sending the LMTP DATA command, and for receiving the remote LMTP server response ✨

`lmtp_data_xfer_timeout` (default: `180s`)

the Postfix LMTP client's time limit for sending the LMTP message content 💌 when the connection stalls for more than $lmtp_data_xfer_timeout, the LMTP client terminates the transfer. not me waiting around, no ma'am, we're done here 💅

`lmtp_defer_if_no_mx_address_found` (default: `no`)

the LMTP-specific version of the smtp_defer_if_no_mx_address_found configuration parameter. See there for details. 👑

✨ this feature is available in Postfix 2.3 and later.

`lmtp_delivery_status_filter` (default: `empty`)

the LMTP-specific version of the smtp_delivery_status_filter configuration parameter. See there for details. 🎀

✨ this feature is available in Postfix 3.0 and later.

`lmtp_destination_concurrency_limit` (default: `$default_destination_concurrency_limit`)

the maximal number of parallel deliveries to the same destination via the lmtp message delivery transport 🔥 this limit is enforced by the queue manager. the message delivery transport name is the first field in the entry in the master.cf file.

`lmtp_destination_recipient_limit` (default: `$default_destination_recipient_limit`)

the maximal number of recipients per message for the lmtp message delivery transport 📬 this limit is enforced by the queue manager. the message delivery transport name is the first field in the entry in the master.cf file.

okay plot twist, and it's kind of iconic: setting this parameter to a value of 1 changes the meaning of lmtp_destination_concurrency_limit from concurrency per domain into concurrency per recipient 👛

`lmtp_discard_lhlo_keyword_address_maps` (default: `empty`)

lookup tables, indexed by the remote LMTP server address, with case insensitive lists of LHLO keywords (pipelining, starttls, auth, etc.) that the Postfix LMTP client will ignore in the LHLO response from a remote LMTP server 🙈 see lmtp_discard_lhlo_keywords for details. the table is not indexed by hostname, and that's for consistency with smtpd_discard_ehlo_keyword_address_maps. consistency is the moment, we respect it.

✨ this feature is available in Postfix 2.3 and later.

`lmtp_discard_lhlo_keywords` (default: `empty`)

a case insensitive list of LHLO keywords (pipelining, starttls, auth, etc.) that the Postfix LMTP client will ignore in the LHLO response from a remote LMTP server 🫶 like the LMTP client looks at that list and goes "nope, don't perceive that."

✨ this feature is available in Postfix 2.3 and later.

notes, because details matter:

specify the silent-discard pseudo keyword to prevent this action from being logged 🤫
use the lmtp_discard_lhlo_keyword_address_maps feature to discard LHLO keywords selectively 🎯

`lmtp_dns_reply_filter` (default: `empty`)

optional filter for Postfix LMTP client DNS lookup results 🔍 see smtp_dns_reply_filter for details including an example.

✨ this feature is available in Postfix 3.0 and later.

`lmtp_dns_resolver_options` (default: `empty`)

the LMTP-specific version of the smtp_dns_resolver_options configuration parameter. See there for details. 💜

✨ this feature is available in Postfix 2.8 and later.

`lmtp_dns_support_level` (default: `empty`)

the LMTP-specific version of the smtp_dns_support_level configuration parameter. See there for details. 🦋

✨ this feature is available in Postfix 2.11 and later.

`lmtp_enforce_tls` (default: `no`)

the LMTP-specific version of the smtp_enforce_tls configuration parameter. See there for details.

⚠️ bestie listen: this feature is deprecated as of Postfix 3.9. specify lmtp_tls_security_level instead. she's giving retired, and we honor her, but we don't use her ✨

✨ this feature is available in Postfix 2.3 and later.

`lmtp_fallback_relay` (default: `empty`)

optional list of relay hosts for LMTP destinations that can't be found or that are unreachable 🚧 in main.cf elements are separated by whitespace or commas.

by default, mail is returned to the sender when a destination is not found, and delivery is deferred when a destination is unreachable.

the fallback relays must be TCP destinations, specified without a leading inet: prefix 🌈 specify a host or host:port. since MX lookups do not apply with LMTP, there is no need to use the [host] or [host]:port forms — so don't, okay? 😌 if you specify multiple LMTP destinations, Postfix will try them in the specified order.

✨ this feature is available in Postfix 3.1 and later.

`lmtp_generic_maps` (default: `empty`)

the LMTP-specific version of the smtp_generic_maps configuration parameter. See there for details. 💖

✨ this feature is available in Postfix 2.3 and later.

`lmtp_header_checks` (default: `empty`)

the LMTP-specific version of the smtp_header_checks configuration parameter. See there for details. 📝

✨ this feature is available in Postfix 2.5 and later.

`lmtp_host_lookup` (default: `dns`)

the LMTP-specific version of the smtp_host_lookup configuration parameter. See there for details. 🔎

✨ this feature is available in Postfix 2.3 and later.

lmtp_lhlo_name (default: $myhostname) — bestie, this is literally the hostname that gets dropped into the LMTP LHLO command ✨

The out-of-the-box value is just the machine hostname, no thoughts head empty. But you can hand it a hostname, or a [ip.add.re.ss], or a [ip:v6:add:re::ss] — yes queen, bracketed IPv6 just like that 💅

You can set this in the main.cf file for every LMTP client, or in the master.cf file if you want it for one specific client only. Like, for example:

/etc/postfix/master.cf:
    mylmtp ... lmtp -o lmtp_lhlo_name=foo.bar.com

This feature is available in Postfix 2.3 and later.

lmtp_lhlo_timeout (default: 300s) — the time limit the Postfix LMTP client gets for sending the LHLO command and for receiving the initial response back from the remote LMTP server. It's giving patience but make it timed ⏰

Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). The default time unit is s (seconds).

lmtp_line_length_limit (default: 998) — the LMTP-specific version of the smtp_line_length_limit configuration parameter. See there for the details, iykyk 🫶

This feature is available in Postfix 2.3 and later.

lmtp_log_tls_feature_status (default: yes) — the LMTP-specific version of the smtp_log_tls_feature_status configuration parameter. See there for the details.

This feature is available in Postfix >= 3.11.

lmtp_mail_timeout (default: 300s) — the Postfix LMTP client time limit for sending the MAIL FROM command and for receiving the response from the remote LMTP server 💌

lmtp_mime_header_checks (default: empty) — the LMTP-specific version of the smtp_mime_header_checks configuration parameter. See there for the details.

This feature is available in Postfix 2.5 and later.

lmtp_min_data_rate (default: 500) — the LMTP-specific version of the smtp_min_data_rate configuration parameter. See there for the details.

This feature is available in Postfix 3.7 and later.

lmtp_mx_address_limit (default: 5) — the LMTP-specific version of the smtp_mx_address_limit configuration parameter. See there for the details.

This feature is available in Postfix 2.3 and later.

lmtp_mx_session_limit (default: 2) — the LMTP-specific version of the smtp_mx_session_limit configuration parameter. See there for the details.

This feature is available in Postfix 2.3 and later.

lmtp_nested_header_checks (default: empty) — the LMTP-specific version of the smtp_nested_header_checks configuration parameter. See there for the details.

This feature is available in Postfix 2.5 and later.

lmtp_per_record_deadline (default: no) — the LMTP-specific version of the smtp_per_record_deadline configuration parameter. See there for the details.

This feature is available in Postfix 2.9 and later.

lmtp_per_request_deadline (default: no) — the LMTP-specific version of the smtp_per_request_deadline configuration parameter. See there for the details.

This feature is available in Postfix 3.7 and later.

lmtp_pix_workaround_delay_time (default: 10s) — the LMTP-specific version of the smtp_pix_workaround_delay_time configuration parameter. See there for the details.

This feature is available in Postfix 2.3 and later.

lmtp_pix_workaround_maps (default: empty) — the LMTP-specific version of the smtp_pix_workaround_maps configuration parameter. See there for the details.

This feature is available in Postfix 2.4 and later.

lmtp_pix_workaround_threshold_time (default: 500s) — the LMTP-specific version of the smtp_pix_workaround_threshold_time configuration parameter. See there for the details.

This feature is available in Postfix 2.3 and later.

lmtp_pix_workarounds (default: empty) — the LMTP-specific version of the smtp_pix_workaround configuration parameter. See there for the details.

This feature is available in Postfix 2.4 and later.

lmtp_quit_timeout (default: 300s) — the Postfix LMTP client time limit for sending the QUIT command and for receiving the response from the remote LMTP server 👋

lmtp_quote_rfc821_envelope (default: yes) — the LMTP-specific version of the smtp_quote_rfc821_envelope configuration parameter. See there for the details.

This feature is available in Postfix 2.3 and later.

lmtp_randomize_addresses (default: yes) — the LMTP-specific version of the smtp_randomize_addresses configuration parameter. See there for the details.

This feature is available in Postfix 2.3 and later.

lmtp_rcpt_timeout (default: 300s) — the Postfix LMTP client time limit for sending the RCPT TO command and for receiving the response from the remote LMTP server 📬

lmtp_reply_filter (default: empty) — the LMTP-specific version of the smtp_reply_filter configuration parameter. See there for the details.

This feature is available in Postfix 2.7 and later.

lmtp_requiretls_policy (default: opportunistic) — the LMTP-specific version of the smtp_requiretls_policy configuration parameter. See there for the details.

This feature is available in Postfix >= 3.11.

lmtp_rset_timeout (default: 20s) — the Postfix LMTP client time limit for sending the RSET command and for receiving the response from the remote LMTP server. The LMTP client sends RSET in order to finish a recipient address probe, or to verify that a cached connection is still alive 🫧

lmtp_sasl_auth_cache_name (default: empty) — the LMTP-specific version of the smtp_sasl_auth_cache_name configuration parameter. See there for the details.

This feature is available in Postfix 2.5 and later.

lmtp_sasl_auth_cache_time (default: 90d) — the LMTP-specific version of the smtp_sasl_auth_cache_time configuration parameter. See there for the details.

This feature is available in Postfix 2.5 and later.

lmtp_sasl_auth_enable (default: no) — turn on SASL authentication in the Postfix LMTP client 🔐
lmtp_sasl_auth_soft_bounce (default: yes) — the LMTP-specific version of the smtp_sasl_auth_soft_bounce configuration parameter. See there for the details.

This feature is available in Postfix 2.5 and later.

lmtp_sasl_mechanism_filter (default: empty) — the LMTP-specific version of the smtp_sasl_mechanism_filter configuration parameter. See there for the details.

This feature is available in Postfix 2.3 and later.

lmtp_sasl_password_maps (default: empty) — optional Postfix LMTP client lookup tables holding one username:password entry per host or domain. And listen: if a remote host or domain has no username:password entry, then the Postfix LMTP client will not attempt to authenticate to that remote host. No entry, no vibes, no auth 🚫
lmtp_sasl_password_result_delimiter (default: :) — the LMTP-specific version of the smtp_sasl_password_result_delimiter configuration parameter. See there for the details.
lmtp_sasl_path (default: empty) — implementation-specific information that gets passed straight through to the SASL plug-in implementation chosen with lmtp_sasl_type. Typically this names a configuration file or a rendezvous point 📁

This feature is available in Postfix 2.3 and later.

lmtp_sasl_security_options (default: noplaintext, noanonymous) — SASL security options. As of Postfix 2.3, the list of available features depends on the SASL client implementation that's selected with lmtp_sasl_type 👑

These are the security features defined for the cyrus client SASL implementation:

noplaintext — disallow authentication methods that use plaintext passwords. (Protect the password bestie, fr fr.)
noactive — disallow authentication methods that are vulnerable to non-dictionary active attacks.
nodictionary — disallow authentication methods that are vulnerable to passive dictionary attacks.
noanonymous — disallow anonymous logins.

Example:

lmtp_sasl_security_options = noplaintext

lmtp_sasl_tls_security_options (default: $lmtp_sasl_security_options) — the LMTP-specific version of the smtp_sasl_tls_security_options configuration parameter. See there for the details.

This feature is available in Postfix 2.3 and later.

lmtp_sasl_tls_verified_security_options (default: $lmtp_sasl_tls_security_options) — the LMTP-specific version of the smtp_sasl_tls_verified_security_options configuration parameter. See there for the details.

This feature is available in Postfix 2.3 and later.

lmtp_sasl_type (default: cyrus) — the SASL plug-in type the Postfix LMTP client should use for authentication. The available types are listed with the "postconf -A" command 💅

This feature is available in Postfix 2.3 and later.

lmtp_send_dummy_mail_auth (default: no) — the LMTP-specific version of the smtp_send_dummy_mail_auth configuration parameter. See there for the details.

This feature is available in Postfix 2.9 and later.

lmtp_send_xforward_command (default: no) — send an XFORWARD command to the remote LMTP server when the LMTP LHLO server response announces XFORWARD support. This lets an lmtp(8) delivery agent, used for content filter message injection, forward the name, address, protocol and HELO name of the original client to the content filter and the downstream LMTP server 🚀

Before you change the value to yes, it is best to make sure that your content filter supports this command. Read the room first, bestie 🙈

This feature is available in Postfix 2.1 and later.

lmtp_sender_dependent_authentication (default: no) — the LMTP-specific version of the smtp_sender_dependent_authentication configuration parameter. See there for the details.

This feature is available in Postfix 2.3 and later.

lmtp_skip_5xx_greeting (default: yes) — the LMTP-specific version of the smtp_skip_5xx_greeting configuration parameter. See there for the details.

This feature is available in Postfix 2.3 and later.

lmtp_skip_quit_response (default: no) — wait for the response to the LMTP QUIT command. Yes, that is literally the whole thing. Simple queen behavior ⭐
lmtp_starttls_timeout (default: 300s) — the LMTP-specific version of the smtp_starttls_timeout configuration parameter. See there for the details.

This feature is available in Postfix 2.3 and later.

lmtp_tcp_port (default: 24) — the default TCP port that the Postfix LMTP client connects to. Hand it either a symbolic name (see services(5)) or a numeric port 🔢
lmtp_tls_CAfile (default: empty) — bestie this is literally the LMTP-flavored twin of the smtp_tls_CAfile config param. Same energy, different protocol. Go read that one for the deets 💅

Available in Postfix 2.3 and later ✨

lmtp_tls_CApath (default: empty) — the LMTP-specific version of smtp_tls_CApath. See there for the whole story, iykyk.

Available in Postfix 2.3 and later ✨

lmtp_tls_block_early_mail_reply (default: empty) — LMTP-specific twin of smtp_tls_block_early_mail_reply. The original has the lore, go check it.

Available in Postfix 2.7 and later ✨

lmtp_tls_cert_file (default: empty) — LMTP-specific version of smtp_tls_cert_file. Same vibes, LMTP edition 🎀

Available in Postfix 2.3 and later ✨

lmtp_tls_chain_files (default: empty) — the LMTP-specific version of smtp_tls_chain_files. All the details live over there, no cap.

Available in Postfix 3.4 and later ✨

lmtp_tls_ciphers (default: medium) — LMTP-specific take on smtp_tls_ciphers. See there for details, fr fr.

Available in Postfix 2.6 and later ✨

lmtp_tls_connection_reuse (default: no) — the LMTP-specific version of smtp_tls_connection_reuse. Details? Over there 👑

Available in Postfix 3.4 and later ✨

lmtp_tls_dcert_file (default: empty) — LMTP-specific version of smtp_tls_dcert_file. See there, bestie.

Available in Postfix 2.3 and later ✨

lmtp_tls_dkey_file (default: $lmtp_tls_dcert_file) — LMTP-specific version of smtp_tls_dkey_file. Yes it defaults to the cert file, that's the whole point, go read the original for the why 💖

Available in Postfix 2.3 and later ✨

lmtp_tls_eccert_file (default: empty) — LMTP-specific version of smtp_tls_eccert_file. See there for details.

Available in Postfix 2.6 and later, when Postfix is compiled and linked with OpenSSL 1.0.0 or later 🌸

lmtp_tls_eckey_file (default: empty) — LMTP-specific version of smtp_tls_eckey_file. See there for details.

Available in Postfix 2.6 and later, when Postfix is compiled and linked with OpenSSL 1.0.0 or later 🌸

lmtp_tls_enable_rpk (default: yes) — the LMTP-specific version of smtp_tls_enable_rpk. Details live at the original address 🦋

Available in Postfix 3.9 and later ✨

lmtp_tls_enforce_peername (default: yes) — LMTP-specific version of smtp_tls_enforce_peername. See there for details.

Available in Postfix 2.3 and later ✨

lmtp_tls_enforce_sts_mx_patterns (default: yes) — okay so this one just straight up says: see smtp_tls_enforce_sts_mx_patterns. Periodt 💅

Available in Postfix >= 3.10.5 ✨

lmtp_tls_exclude_ciphers (default: empty) — LMTP-specific version of smtp_tls_exclude_ciphers. See there for details.

Available in Postfix 2.3 and later ✨

lmtp_tls_fingerprint_cert_match (default: empty) — LMTP-specific version of smtp_tls_fingerprint_cert_match. The original has the tea ☕

Available in Postfix 2.5 and later ✨

lmtp_tls_fingerprint_digest (default: see postconf -d output) — LMTP-specific version of smtp_tls_fingerprint_digest. See there for details.

Available in Postfix 2.5 and later ✨

lmtp_tls_force_insecure_host_tlsa_lookup (default: no) — LMTP-specific version of smtp_tls_force_insecure_host_tlsa_lookup. See there for details.

Available in Postfix 2.11 and later ✨

lmtp_tls_key_file (default: $lmtp_tls_cert_file) — LMTP-specific version of smtp_tls_key_file. See there for details.

Available in Postfix 2.3 and later ✨

lmtp_tls_loglevel (default: 0) — LMTP-specific version of smtp_tls_loglevel. See there for details.

Available in Postfix 2.3 and later ✨

lmtp_tls_mandatory_ciphers (default: medium) — LMTP-specific version of smtp_tls_mandatory_ciphers. See there for details.

Available in Postfix 2.3 and later ✨

lmtp_tls_mandatory_exclude_ciphers (default: empty) — LMTP-specific version of smtp_tls_mandatory_exclude_ciphers. See there for details.

Available in Postfix 2.3 and later ✨

lmtp_tls_mandatory_protocols (default: see postconf -d output) — LMTP-specific version of smtp_tls_mandatory_protocols. See there for details.

Available in Postfix 2.3 and later ✨

lmtp_tls_note_starttls_offer (default: no) — LMTP-specific version of smtp_tls_note_starttls_offer. See there for details.

Available in Postfix 2.3 and later ✨

lmtp_tls_per_site (default: empty) — LMTP-specific version of smtp_tls_per_site. See there for details.

⚠️ Deprecated as of Postfix 3.9, bestie. Don't come crying to me. Specify lmtp_tls_policy_maps instead 💀

Available in Postfix 2.3 and later ✨

lmtp_tls_policy_maps (default: empty) — LMTP-specific version of smtp_tls_policy_maps. See there for details.

Available in Postfix 2.3 and later ✨

lmtp_tls_protocols (default: see postconf -d output) — LMTP-specific version of smtp_tls_protocols. See there for details.

Available in Postfix 2.6 and later ✨

lmtp_tls_scert_verifydepth (default: 9) — LMTP-specific version of smtp_tls_scert_verifydepth. See there for details.

Available in Postfix 2.3 and later ✨

lmtp_tls_secure_cert_match (default: nexthop) — LMTP-specific version of smtp_tls_secure_cert_match. See there for details.

Available in Postfix 2.3 and later ✨

lmtp_tls_security_level (default: empty) — LMTP-specific version of smtp_tls_security_level. See there for details.

Available in Postfix 2.3 and later ✨

lmtp_tls_servername (default: empty) — LMTP-specific version of smtp_tls_servername. See there for details.

Available in Postfix 3.4 and later ✨

lmtp_tls_session_cache_database (default: empty) — LMTP-specific version of smtp_tls_session_cache_database. See there for details.

Available in Postfix 2.3 and later ✨

lmtp_tls_session_cache_timeout (default: 3600s) — LMTP-specific version of smtp_tls_session_cache_timeout. See there for details.

Available in Postfix 2.3 and later ✨

lmtp_tls_trust_anchor_file (default: empty) — LMTP-specific version of smtp_tls_trust_anchor_file. See there for details.

Available in Postfix 2.11 and later ✨

lmtp_tls_verify_cert_match (default: hostname) — LMTP-specific version of smtp_tls_verify_cert_match. See there for details.

Available in Postfix 2.3 and later ✨

lmtp_tls_wrappermode (default: no) — LMTP-specific version of smtp_tls_wrappermode. See there for details.

Available in Postfix 3.0 and later ✨

lmtp_use_tls (default: no) — LMTP-specific version of smtp_use_tls. See there for details.

⚠️ Also deprecated as of Postfix 3.9, babes. Specify lmtp_tls_security_level instead 🙈

Available in Postfix 2.3 and later ✨

lmtp_xforward_timeout (default: 300s) — this is the Postfix LMTP client's time limit for sending the XFORWARD command and for receiving the remote LMTP server response. Both halves, okay? 👑

If stuff goes wrong, the client does NOT try the next address on the mail exchanger list. Not even a little. Which is lowkey dramatic of it but okay 💀

You gotta specify a non-zero time value — that's an integral value plus an optional one-letter suffix that tells it the time unit. The units are: s (seconds), m (minutes), h (hours), d (days), w (weeks). Default unit if you don't say? s (seconds) 💅

Available in Postfix 2.1 and later ✨

local_command_shell (default: empty) — optional shell program for local(8) delivery to non-Postfix commands 🐚

By default, non-Postfix commands are just executed directly. Commands only get handed off to the default shell (typically /bin/sh) when they contain shell meta characters or shell built-in commands. That's the whole vibe.

"sendmail's restricted shell" (smrsh) is what most people will use in order to restrict what programs can be run from e.g. .forward files (smrsh is part of the Sendmail distribution). Iconic security move, honestly 🫶

📝 Note: when a shell program is specified, it gets invoked even when the command contains no shell built-in commands or meta characters. Like, no exceptions.

Example:

local_command_shell = /some/where/smrsh -c
local_command_shell = /bin/bash -c

local_delivery_status_filter (default: $default_delivery_status_filter) — optional filter for the local(8) delivery agent to change the status code or the explanatory text of successful or unsuccessful deliveries ✨ See default_delivery_status_filter for details.

Available in Postfix 3.0 and later 🌸

local_destination_concurrency_limit (default: 2) — this is the maximal number of parallel deliveries, and which one it means depends on your recipient limit, so pay attention bestie:
- when local_destination_recipient_limit = 1, it's the max parallel deliveries via the local mail delivery transport to the same recipient
- when local_destination_recipient_limit > 1, it's the max parallel deliveries to the same local domain

This limit is enforced by the queue manager. The message delivery transport name is the first field in the entry in the master.cf file 🎀

A low limit of 2 is recommended, just in case someone has an expensive shell command in a .forward file or in an alias (e.g., a mailing list manager). You do not want to run lots of those at the same time, that's giving chaos energy 🔥

local_destination_recipient_limit (default: 1) — the maximal number of recipients per message delivery via the local mail delivery transport. This limit is enforced by the queue manager. The message delivery transport name is the first field in the entry in the master.cf file 💖

Setting this parameter to a value > 1 changes the meaning of local_destination_concurrency_limit from concurrency per recipient into concurrency per domain. Yes, it rewires the whole thing. Slay, but be aware 🦋

permit_tls_all_clientcerts — append the domain name in $myorigin or $mydomain when the remote SMTP client's TLS cert got successfully verified, no matter whether it's listed on the server, and no matter who the certifying authority is. Vibes only, no receipts.
check_address_map type:table
type:table — append the domain name in $myorigin or $mydomain when the client IP address matches the lookup table you named. The lookup result gets literally ignored, and no subnet lookup happens either. This is the one for, like, pop-before-smtp lookup tables. iykyk.

Examples:

The Postfix < 2.2 backwards compatible setting — always rewrite message headers, and always append your own domain to incomplete header addresses:

local_header_rewrite_clients = static:all

The purist (and default) setting — rewrite headers only in mail from Postfix sendmail and in SMTP mail from this machine:

local_header_rewrite_clients = permit_inet_interfaces

The intermediate setting — rewrite header addresses and append $myorigin or $mydomain info only with mail from Postfix sendmail, from local clients, or from authorized SMTP clients.

Note: this setting will not prevent remote mail header address rewriting when mail from a remote client is forwarded by a neighboring system.

local_header_rewrite_clients = permit_mynetworks,
    permit_sasl_authenticated permit_tls_clientcerts
    check_address_map lmdb:/etc/postfix/pop-before-smtp

Instead of lmdb:, some systems use cdb:, hash:, or dbm:. ✨

🌸 `local_login_sender_maps` (default: `static:*`)

A list of lookup tables that get searched by the UNIX login name, and that return a list of allowed envelope sender patterns separated by space or comma. These sender patterns are enforced by the Postfix postdrop(1) command. The default is backwards-compatible: every user may specify any sender envelope address. So like, free-for-all by default, bestie.

When no UNIX login name is available, the postdrop(1) command will prepend "uid:" to the numerical UID and use that instead.

This feature ignores address extensions in the user-specified envelope sender address.

Note: to enforce that the From: header address matches the envelope sender (MAIL FROM) address, specify an external filter such as a Milter, with the non_smtpd_milters parameter. For example: https://github.com/magcks/milterfrom.

The following sender patterns are special; these cannot be used as part of a longer pattern.

* — this pattern allows any envelope sender address. anything goes 💅
<> — this pattern allows the empty envelope sender address. See the empty_address_local_login_sender_maps_lookup_key configuration parameter.
@domain — this pattern allows an envelope sender address when the @ and domain part match.

Examples:

/etc/postfix/main.cf:

# Allow root and postfix full control, anyone else can only
# send mail as themselves. Use "uid:" followed by the numerical
# UID when the UID has no entry in the UNIX password file.
local_login_sender_maps =
    inline:{ { root = * }, { postfix = * } },
    pcre:/etc/postfix/login_senders

/etc/postfix/login_senders:

# Allow both the bare username and the user@domain forms.
 /(.+)/ $1 $1@example.com

⭐ This feature is available in Postfix 3.6 and later.

🎀 `local_recipient_maps` (default: `proxy:unix:passwd.byname $alias_maps`)

Lookup tables with all names or addresses of valid local recipients. A recipient address counts as local when its domain matches $mydestination, $inet_interfaces or $proxy_interfaces.

If the local_recipient_maps parameter value is non-empty (aka the default), then the Postfix SMTP server queries local_recipient_maps as specified in "Local recipient table query format", and rejects mail for unknown local recipients. Other Postfix interfaces such as the Postfix sendmail(1) command may still accept an "unknown" recipient. 👀

The default local_recipient_maps setting assumes that local_transport specifies the UNIX-compatible local(8) delivery agent which queries the UNIX passwd database (typically, /etc.passwd) and the local aliases database (typically, /etc/aliases). The proxy: agent allows the Postfix SMTP server to access the UNIX passwd database from outside a chroot jail. cute, right?

For other local mail delivery configurations, see "When you need to change the local_recipient_maps setting in main.cf".

Technically, tables listed with $local_recipient_maps are used as lists: the Postfix SMTP server needs to know only if a lookup string is found or not, but it does not use the result from table lookup.

Specify zero or more "type:name" lookup tables, separated by whitespace or comma. Tables will be searched in the specified order until a match is found.

To turn off local recipient checking in the Postfix SMTP server, specify "local_recipient_maps =" (i.e. empty).

Examples:

local_recipient_maps =

🦋 `local_transport` (default: `local:$myhostname`)

The default mail delivery transport and next-hop destination for final delivery to domains listed with mydestination, and for [ipaddress] destinations that match $inet_interfaces or $proxy_interfaces. This info can be overruled with the transport(5) table.

By default, local mail is delivered to the transport called "local", which is just the name of a service that is defined in the master.cf file.

Specify a string of the form transport:nexthop, where transport is the name of a mail delivery transport defined in master.cf. The :nexthop destination is optional; its syntax is documented in the manual page of the corresponding delivery agent.

Beware: if you override the default local delivery agent then you need to review the LOCAL_RECIPIENT_README document, otherwise the SMTP server may reject mail for local recipients. 😭 don't say I didn't warn you.

🌈 `luser_relay` (default: empty)

Optional catch-all destination for unknown local(8) recipients. By default, mail for unknown recipients in domains that match $mydestination, $inet_interfaces or $proxy_interfaces is returned as undeliverable.

The luser_relay value is not subject to Postfix configuration parameter $name expansion. Instead, the following $name expansions are done:

$domain — the recipient domain.
$extension — the recipient address extension.
$home — the recipient's home directory.
$local — the entire recipient address localpart.
$recipient — the full recipient address.
$recipient_delimiter — the address extension delimiter that was found in the recipient address (Postfix 2.11 and later), or the system-wide recipient address extension delimiter (Postfix 2.10 and earlier).
$shell — the recipient's login shell.
$user — the recipient username.
${name?value}
${name?{value}} (Postfix >= 3.0) — expands to value when $name is non-empty.
${name:value}
${name:{value}} (Postfix >= 3.0) — expands to value when $name is empty.
${name?{value1}:{value2}} (Postfix >= 3.0) — expands to value1 when $name is non-empty, value2 otherwise.

Instead of $name you can also specify ${name} or $(name).

Note: luser_relay works only for the Postfix local(8) delivery agent.

Note: if you use this feature for accounts not in the UNIX password file, then you must specify "local_recipient_maps =" (i.e. empty) in the main.cf file, otherwise the Postfix SMTP server will reject mail for non-UNIX accounts with "User unknown in local recipient table".

Examples:

luser_relay = $user@other.host
luser_relay = $local@other.host
luser_relay = admin+$local

💜 `mail_name` (default: `Postfix`)

The mail system name that is displayed in Received: headers, in the SMTP greeting banner, and in bounced mail. it's giving name tag energy ✨

👑 `mail_owner` (default: `postfix`)

The UNIX system account that owns the Postfix queue and most Postfix daemon processes. Specify the name of an unprivileged user account that does not share a user or group ID with other accounts, and that owns no other files or processes on the system. In particular, don't specify nobody or daemon. PLEASE USE A DEDICATED USER ID AND GROUP ID. no cap, this one matters fr fr.

When this parameter value is changed you need to re-run "postfix set-permissions" (with Postfix version 2.0 and earlier: "/etc/postfix/post-install set-permissions".

⭐ `mail_release_date` (default: see `postconf -d` output)

The Postfix release date, in "YYYYMMDD" format. 💖

🌸 `mail_spool_directory` (default: see `postconf -d` output)

The directory where local(8) UNIX-style mailboxes live, bestie. The default setting depends on your system type — so like, it's giving mystery but in a cute system-dependent way. ✨

Want maildir-style delivery instead? Just specify a name that ends in /. That trailing slash is the whole vibe, okurrr.

Note: maildir delivery is done with the privileges of the recipient. So if you're using the mail_spool_directory setting for maildir style delivery, you must create the top-level maildir directory in advance. Postfix will not create it. Not me being lazy, it's just literally not going to do it. 🫶

Examples:

mail_spool_directory = /var/mail
mail_spool_directory = /var/spool/mail

🌈 `mail_version` (default: see `postconf -d` output)

The version of the mail system 💅. Stable releases are named major.minor.patchlevel. Experimental releases also include the release date (so you know they're spicy 🌶️). The version string can be used in, for example, the SMTP greeting banner — very "hi bestie, this is who I am" energy.

🎀 `mailbox_command` (default: empty)

Optional external command that the local(8) delivery agent should use for mailbox delivery. The command is run with the user ID and the primary group ID privileges of the recipient 🔥 — except, plot twist: command delivery for root executes with $default_privs privileges. This is not a problem, because 1) mail for root should always be aliased to a real user and 2) don't log in as root, use su instead. Periodt.

The following environment variables are exported to the command:

CLIENT_ADDRESS — Remote client network address. Available in Postfix version 2.2 and later.
CLIENT_HELO — Remote client EHLO command parameter. Available in Postfix version 2.2 and later.
CLIENT_HOSTNAME — Remote client hostname. Available in Postfix version 2.2 and later.
CLIENT_PROTOCOL — Remote client protocol. Available in Postfix version 2.2 and later.
DOMAIN — The domain part of the recipient address.
ENVID — The optional RFC 3461 envelope ID. Available in Postfix version 3.9 and later.
EXTENSION — The optional address extension.
HOME — The recipient home directory.
LOCAL — The recipient address localpart.
LOGNAME — The recipient's username.
ORIGINAL_RECIPIENT — The entire recipient address, before any address rewriting or aliasing.
RECIPIENT — The full recipient address.
SASL_METHOD — SASL authentication method specified in the remote client AUTH command. Available in Postfix version 2.2 and later.
SASL_SENDER — SASL sender address specified in the remote client MAIL FROM command. Available in Postfix version 2.2 and later.
SASL_USER — SASL username specified in the remote client AUTH command. Available in Postfix version 2.2 and later.
SENDER — The full sender address.
SHELL — The recipient's login shell.
USER — The recipient username.

Unlike other Postfix configuration parameters, the mailbox_command parameter is not subjected to $name substitutions. This is to make it easier to specify shell syntax (see example below). So yes, it gets to be the ✨rebellious main character✨ here, iykyk.

If you can, avoid shell meta characters because they will force Postfix to run an expensive shell process 💀. If you're delivering via procmail then running a shell won't make a noticeable difference in the total cost, so do your thing.

Note: if you use the mailbox_command feature to deliver mail system-wide, you must set up an alias that forwards mail for root to a real user.

Examples:

mailbox_command = /some/where/procmail
mailbox_command = /some/where/procmail -a "$EXTENSION"
mailbox_command = /some/where/maildrop -d "$USER"
        -f "$SENDER" "$EXTENSION"

🦋 `mailbox_command_maps` (default: empty)

Optional lookup tables with per-recipient external commands to use for local(8) mailbox delivery. Behavior is as with mailbox_command — same energy, just on a per-recipient basis 💖.

Specify zero or more "type:name" lookup tables, separated by whitespace or comma. Tables will be searched in the specified order until a match is found. 🔍

🔒 `mailbox_delivery_lock` (default: see `postconf -d` output)

How to lock a UNIX-style local(8) mailbox before attempting delivery. For a list of available file locking methods, use the "postconf -l" command.

This setting is ignored with maildir style delivery, because such deliveries are safe without explicit locks. Slay, no lock needed 💅.

Note: The dotlock method requires that the recipient UID or GID has write access to the parent directory of the mailbox file.

Note: the default setting of this parameter is system dependent.

👑 `mailbox_size_limit` (default: `51200000`)

The maximal size of any local(8) individual mailbox or maildir file, or zero (no limit). In fact, this limits the size of any file that is written to upon local delivery, including files written by external commands that are executed by the local(8) delivery agent. So it's not just the mailbox, bestie, it's the whole friend group.

The value cannot exceed LONG_MAX (typically, a 32-bit or 64-bit signed integer).

This limit must not be smaller than the message size limit. Keep it bigger, always. 🙈

⭐ `mailbox_transport` (default: empty)

Optional message delivery transport that the local(8) delivery agent should use for mailbox delivery to all local recipients, whether or not they are found in the UNIX passwd database.

🧚 `mailbox_transport_maps` (default: empty)

Optional lookup tables with per-recipient message delivery transports to use for local(8) mailbox delivery, whether or not the recipients are found in the UNIX passwd database.

Specify zero or more "type:name" lookup tables, separated by whitespace or comma. Tables will be searched in the specified order until a match is found.

For safety reasons, this feature does not allow $number substitutions in regular expression maps. Safety first, chaos never. 🛡️

This feature is available in Postfix 2.3 and later.

🍓 `maillog_file` (default: empty)

The name of an optional logfile that is written by the Postfix postlogd(8) service. An empty value selects logging to syslogd(8). Specify "/dev/stdout" to select logging to standard output. Stdout logging requires that Postfix is started with "postfix start-fg".

Note 1: The maillog_file parameter value must contain a prefix that is specified with the maillog_file_prefixes parameter.

Note 2: Some Postfix non-daemon programs may still log information to syslogd(8), before they have processed their configuration parameters and command-line options.

This feature is available in Postfix 3.4 and later.

💜 `maillog_file_compressor` (default: `gzip`)

The program to run after rotating $maillog_file with "postfix logrotate". The command is run with the rotated logfile name as its first argument. 🌀

This feature is available in Postfix 3.4 and later.

✨ `maillog_file_permissions` (default: `0600`)

The file access permissions that will be set when the file $maillog_file is created for the first time, or when the file is created after an existing file is rotated. Specify one of: 0600 (only super-user read/write access), 0640 (adds 'group' read access), or 0644 (also adds 'other' read access). The leading '0' is optional.

This feature is available in Postfix 3.9 and later.

💖 `maillog_file_prefixes` (default: `/var`, `/dev/stdout`)

A list of allowed prefixes for a maillog_file value. This is a safety feature to contain the damage from a single configuration mistake. Specify one or more prefix strings, separated by comma or whitespace. One lil' typo, contained. 🫶

This feature is available in Postfix 3.4 and later.

🌸 `maillog_file_rotate_suffix` (default: `%Y%m%d-%H%M%S`)

The format of the suffix to append to $maillog_file while rotating the file with "postfix logrotate". See strftime(3) for syntax. The default suffix, YYYYMMDD-HHMMSS, allows logs to be rotated frequently — so many logs, so many timestamps, iconic honestly. 💅

This feature is available in Postfix 3.4 and later.

📬 `mailq_path` (default: see `postconf -d` output)

Sendmail compatibility feature that specifies where the Postfix mailq(1) command is installed. This command can be used to list the Postfix mail queue. Yes bestie, you can peek at the queue. 👀

📖 `manpage_directory` (default: see `postconf -d` output)

Where the Postfix manual pages are installed. The lore, archived. ✨

💀 `maps_rbl_domains` (default: empty)

Obsolete feature: use the reject_rbl_client feature instead. It's giving retired, respectfully. Move on, bestie.

🚫 `maps_rbl_reject_code` (default: `554`)

The numerical Postfix SMTP server response code when a remote SMTP client request is blocked by the reject_rbl_client, reject_rhsbl_client, reject_rhsbl_reverse_client, reject_rhsbl_sender or reject_rhsbl_recipient restriction.

Do not change this unless you have a complete understanding of RFC 5321. Like, complete complete. Not vibes-based understanding. 🔥

🎭 `masquerade_classes` (default: `envelope_sender, header_sender, header_recipient`)

What addresses are subject to address masquerading. Yes, we're putting on a little disguise. 🥸

By default, address masquerading is limited to envelope sender addresses, and to header sender and header recipient addresses. This allows you to use address masquerading on a mail gateway while still being able to forward mail to users on individual machines. Best of both worlds, fr fr.

Specify zero or more of: envelope_sender, envelope_recipient, header_sender, header_recipient

🌸 masquerade_domains (default: empty) 🌸

bestie. this one is the ✨aesthetic✨ filter for your email addresses. it's an optional list of domains whose subdomain structure gets stripped off in email addresses. bye bye, extra subdomains 💅

the list gets processed left to right, and the processing stops at the first match. no take-backs, no second chances. so like:

masquerade_domains = foo.example.com example.com

this strips "user@any.thing.foo.example.com" down to "user@foo.example.com" — slay — but it strips "user@any.thing.else.example.com" to "user@example.com". see how the second one skips all the way to example.com? because foo.example.com didn't match, so we kept going 🦋

now. a domain name prefixed with ! means do not masquerade this domain or its subdomains. protect it, guard it, no touchy. so:

masquerade_domains = !foo.example.com example.com

this does not change "user@any.thing.foo.example.com" or "user@foo.example.com", but it strips "user@any.thing.else.example.com" to "user@example.com". the ! said "not me" and the universe listened 🫶

Note: with Postfix version 2.2, message header address masquerading happens only when message header address rewriting is enabled:

the message is received with the Postfix sendmail(1) command,
the message is received from a network client that matches $local_header_rewrite_clients,
the message is received from the network, and the remote_header_rewrite_domain parameter specifies a non-empty value.

to get the behavior from before Postfix version 2.2, specify "local_header_rewrite_clients = static:all". vintage vibes, ig 🙈

Example:

masquerade_domains = $mydomain

💖 masquerade_exceptions (default: empty) 💖

the VIP list, fr fr. this is an optional list of user names that are not subjected to address masquerading, even when their addresses match $masquerade_domains. they said "not today" and the masquerade said "okay periodt" 👑

by default, address masquerading makes no exceptions. none. zero. nobody's special... until you say so.

so you specify a list of user names, "/file/name" or "type:table" patterns, separated by commas and/or whitespace. the list is matched left to right, and the search stops on the first match. a "/file/name" pattern is replaced by its contents; a "type:table" lookup table is matched when a name matches a lookup key (the lookup result is ignored — it's just here for the match, not the tea). continue long lines by starting the next line with whitespace. specify "!pattern" to exclude a name from the list. and heads up: the form "!/file/name" is supported only in Postfix version 2.4 and later 💀

Examples:

masquerade_exceptions = root, mailer-daemon
masquerade_exceptions = root

✨ master_service_disable (default: empty) ✨

selectively disable master(8) listener ports by service type or by service name and type. it's giving "turn off the lights in specific rooms" energy 🕯️

specify a list of service types ("inet", "unix", "fifo", or "pass") or "name/type" tuples, where "name" is the first field of a master.cf entry and "type" is a service type. as with other Postfix matchlists, a search stops at the first match. specify "!pattern" to exclude a service from the list. by default, all master(8) listener ports are enabled — everything's on, all the lights are lit 🌈

Note: this feature does not support "/file/name" or "type:table" patterns, nor does it support wildcards such as "*" or "all". this is intentional. no cap, it's on purpose bestie, don't fight it 💅

Examples:

# With Postfix 2.6..2.10 use '.' instead of '/'.
# Turn on all master(8) listener ports (the default).
master_service_disable =
# Turn off only the main SMTP listener port.
master_service_disable = smtp/inet
# Turn off all TCP/IP listener ports.
master_service_disable = inet
# Turn off all TCP/IP listener ports except "foo".
master_service_disable = !foo/inet, inet

this feature is available in Postfix 2.6 and later. 🎀

🦋 max_idle (default: 100s) 🦋

the maximum amount of time that an idle Postfix daemon process waits for an incoming connection before terminating voluntarily. it's the "okay i'm gonna head out" timer 🚪

this parameter is ignored by the Postfix queue manager and by other long-lived Postfix daemon processes — those ones don't clock out, they're the main characters 👑

specify a non-zero time value (an integral value plus an optional one-letter suffix that specifies the time unit). time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). the default time unit is s (seconds) ⏱️

🍓 max_use (default: 100) 🍓

the maximal number of incoming connections that a Postfix daemon process will service before terminating voluntarily. like a "okay, that's 100 customers, i'm closing my register" kinda situation 💅

just like max_idle, this parameter is ignored by the Postfix queue manager and by other long-lived Postfix daemon processes. not their problem, not their vibe 🧚

🌸 maximal_backoff_time (default: 4000s) 🌸

the maximal time between attempts to deliver a deferred message. the "how long do i wait before trying again" max 💭

this parameter should be set to a value greater than or equal to $minimal_backoff_time. see also $queue_run_delay. keep it consistent bestie 🔥

💜 maximal_queue_lifetime (default: 5d) 💜

consider a message as undeliverable when delivery fails with a temporary error, and the time in the queue has reached the maximal_queue_lifetime limit. it's the "okay we've been at this for 5 days, we're done here" deadline 😭

specify a non-negative time value (an integral value plus an optional one-letter suffix that specifies the time unit). time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). the default time unit is d (days) 📅

specify 0 when mail delivery should be tried only once. one shot, one opportunity, no retries 🙈

🎀 message_drop_headers (default: bcc, content-length, resent-bcc, return-path) 🎀

names of message headers that the cleanup(8) daemon will remove after applying header_checks(5) and before invoking Milter applications. it's the "cleanup on aisle header" moment 🧹✨

the default setting is compatible with Postfix < 3.0. so like, this is the classic vibe 💅

specify a list of header names, separated by comma or space. names are matched in a case-insensitive manner (uppercase, lowercase, we don't care bestie). the list of supported header names is limited only by available memory — go off, list as many as you want 🌈

this feature is available in Postfix 3.0 and later. 👑

✨ message_reject_characters (default: empty) ✨

the set of characters that Postfix will reject in message content. nope, not today, not in my house 💀

the usual C-like escape sequences are recognized: \a \b \f \n \r \t \v \ddd (up to three octal digits) and \\.

Note 1: this feature does not recognize text that requires MIME decoding. it inspects raw message content, just like header_checks and body_checks. raw and unfiltered, the way god intended 🙈

Note 2: this feature is disabled with "receive_override_options = no_header_body_checks".

Example:

message_reject_characters = \0

this feature is available in Postfix 2.3 and later. 🦋

🌸 message_size_limit (default: 10240000) 🌸

the maximal size in bytes of a message, including envelope information. the bouncer at the club door checking everyone's size 📏

the value cannot exceed LONG_MAX (typically, a 32-bit or 64-bit signed integer). respect the limit bestie, it's there for a reason 🔥

Note: be careful when making changes. excessively small values will result in the loss of non-delivery notifications, when a bounce message size exceeds the local or remote MTA's message size limit. so like... don't set this to 5 and then be surprised when the bounce bounces 💀

💖 message_strip_characters (default: empty) 💖

the set of characters that Postfix will remove from message content. not reject, not judge — just yeet them out silently 🧚

the usual C-like escape sequences are recognized: \a \b \f \n \r \t \v \ddd (up to three octal digits) and \\.

Note 1: this feature does not recognize text that requires MIME decoding. it inspects raw message content, just like header_checks and body_checks. same deal as its reject sibling, no MIME awareness bestie 🫶

Note 2: this feature is disabled with "receive_override_options = no_header_body_checks".

Example:

message_strip_characters = \0

this feature is available in Postfix 2.3 and later. 🌈

🦋 meta_directory (default: see `postconf -d` output) 🦋

the location of non-executable files that are shared among multiple Postfix instances, such as postfix-files, dynamicmaps.cf, and the multi-instance template files main.cf.proto and master.cf.proto. it's the shared group chat for all your Postfix instances 📁💬

this directory should contain only Postfix-related files. typically, the meta_directory parameter has the same default as the config_directory parameter (/etc/postfix or /usr/local/etc/postfix). they're besties, they match 💅

for backwards compatibility with Postfix versions 2.6..2.11, specify "meta_directory = $daemon_directory" in main.cf before installing or upgrading Postfix, or specify "meta_directory = /path/name" on the "make makefiles", "make install" or "make upgrade" command line. old-school moves for old-school versions 🕰️

this feature is available in Postfix 3.0 and later. 🎀

🍓 milter_command_timeout (default: 30s) 🍓

the time limit for sending an SMTP command to a Milter (mail filter) application, and for receiving the response. talk to me within 30 seconds or i'm moving on 💅

this feature is available in Postfix 2.3 and later. ✨

💜 milter_connect_macros (default: see `postconf -d` output) 💜

the macros that are sent to Milter (mail filter) applications after completion of an SMTP connection. like little notes passed in class 📝

see MILTER_README for a list of available macro names and their meanings. go read it bestie, iykyk 📖

this feature is available in Postfix 2.3 and later. 🌸

🎀 milter_connect_timeout (default: 30s) 🎀

the time limit for connecting to a Milter (mail filter) application, and for negotiating protocol options. the "how long do we wait at the door" timer 🚪⏱️

this feature is available in Postfix 2.3 and later. 🦋

🌈 milter_content_timeout (default: 300s) 🌈

the time limit for sending message content to a Milter (mail filter) application, and for receiving the response. sending the whole message over takes a lil longer, so 300 seconds — generous, iconic, queen behavior 👑

this feature is available in Postfix 2.3 and later. 💖

💅 milter_data_macros (default: see `postconf -d` output) 💅

the macros that are sent to version 4 or higher Milter (mail filter) applications after the SMTP DATA command. the glow-up edition, v4+ only ✨

see MILTER_README for a list of available macro names and their meanings. 📖

this feature is available in Postfix 2.3 and later. 🫶

`milter_default_action` — default: Postfix >= 3.11: `shutdown`; Postfix < 3.11: `tempfail`

okay so this one is the mood-ruiner fallback 🫠 it's the default action when a Milter (mail filter) response is unavailable — like when your Postfix config is busted or the Milter itself just died on us. Bestie, you get to pick one of these:

accept — act like the mail filter was never even there. Moving on, ignoring the drama ✨
reject — reject ALL further commands in this session with a permanent status code. Cold. Ice cold. 💅
tempfail — reject all further commands in this session with a temporary status code.
shutdown — with smtpd_milters, close the SMTP connection after sending a 421 SMTP reply; with non_smtpd_milters, report a queue file write error. Available in Postfix 3.11 and later. 👑
quarantine — like accept, but freeze the message in the "hold" queue. Available with Postfix 2.6 and later.

ngl the default action was "tempfail" with Postfix 3.10 and earlier. The default action is "shutdown" with Postfix 3.11 and later, i.e. disconnect the SMTP client. The whole reason they switched: with the old default, Postfix could tempfail all messages that the client sends over a long-lived connection, even if a Milter failure is only temporary. so yeah, that's the glow-up 💖

This feature is available in Postfix 2.3 and later.

`milter_end_of_data_macros` — default: see `postconf -d` output

The macros that are sent to Milter (mail filter) applications after the message end-of-data. Peep MILTER_README for a list of available macro names and their meanings 📖

This feature is available in Postfix 2.3 and later.

`milter_end_of_header_macros` — default: see `postconf -d` output

The macros that get sent to Milter (mail filter) applications after the end of the message header. Again, MILTER_README has a list of available macro names and their meanings 💫

This feature is available in Postfix 2.5 and later.

`milter_header_checks` — default: empty

Optional lookup tables for content inspection of message headers that are produced by Milter applications. Check the header_checks(5) manual page for the available actions. Currently, PREPEND is not implemented. not yet bestie, we wait 🙈

Here's an example that sends all mail that is marked as SPAM to a spam handling machine. Note that matches are case-insensitive by default 👇

/etc/postfix/main.cf:
    milter_header_checks = pcre:/etc/postfix/milter_header_checks

/etc/postfix/milter_header_checks:
    /^X-SPAM-FLAG:\s+YES/ FILTER mysmtp:sanitizer.example.com:25

The milter_header_checks mechanism could also be used for allowlisting ✨ For example it could be used to skip heavy content inspection for DKIM-signed mail from known friendly domains. main character behavior, honestly.

This feature is available in Postfix 2.7, and as an optional patch for Postfix 2.6.

`milter_helo_macros` — default: see `postconf -d` output

The macros that are sent to Milter (mail filter) applications after the SMTP HELO or EHLO command. MILTER_README lists available macro names and their meanings 🌸

This feature is available in Postfix 2.3 and later.

`milter_macro_daemon_name` — default: `$myhostname`

The {daemon_name} macro value for Milter (mail filter) applications. See MILTER_README for a list of available macro names and their meanings 👑

This feature is available in Postfix 2.3 and later.

`milter_macro_defaults` — default: empty

Optional list of name=value pairs that specify default values for arbitrary macros that Postfix may send to Milter applications. These defaults are used when there is no corresponding information from the message delivery context. like a lil backup plan 🫶

Specify name=value or {name=value} pairs separated by comma or whitespace. Enclose a pair in "{}" when a value contains comma or whitespace (this form ignores whitespace after the enclosing "{", around the "=", and before the enclosing "}").

This feature is available in Postfix 3.1 and later.

`milter_macro_v` — default: `$mail_name $mail_version`

The {v} macro value for Milter (mail filter) applications. Peep MILTER_README for a list of available macro names and their meanings 💜

This feature is available in Postfix 2.3 and later.

`milter_mail_macros` — default: see `postconf -d` output

The macros that are sent to Milter (mail filter) applications after the SMTP MAIL FROM command. MILTER_README has the list of available macro names and their meanings 📬

This feature is available in Postfix 2.3 and later.

`milter_protocol` — default: `6`

The mail filter protocol version and optional protocol extensions for communication with a Milter application; prior to Postfix 2.6 the default protocol is 2. Postfix sends this version number during the initial protocol handshake. It should match the version number that is expected by the mail filter application (or by its Milter library) 🤝

Protocol versions:

2 — Use Sendmail 8 mail filter protocol version 2 (default with Sendmail version 8.11 .. 8.13 and Postfix version 2.3 .. 2.5).
3 — Use Sendmail 8 mail filter protocol version 3.
4 — Use Sendmail 8 mail filter protocol version 4.
6 — Use Sendmail 8 mail filter protocol version 6 (default with Sendmail version 8.14 and Postfix version 2.6).

Protocol extensions:

no_header_reply — Specify this when the Milter application will not reply for each individual message header.

This feature is available in Postfix 2.3 and later.

`milter_rcpt_macros` — default: see `postconf -d` output

The macros that are sent to Milter (mail filter) applications after the SMTP RCPT TO command. MILTER_README lists available macro names and their meanings 💌

This feature is available in Postfix 2.3 and later.

`milter_unknown_command_macros` — default: see `postconf -d` output

The macros that are sent to version 3 or higher Milter (mail filter) applications after an unknown SMTP command. MILTER_README for a list of available macro names and their meanings 🦋

This feature is available in Postfix 2.3 and later.

`mime_boundary_length_limit` — default: `2048`

The maximal length of MIME multipart boundary strings. The MIME processor is unable to distinguish between boundary strings that do not differ in the first $mime_boundary_length_limit characters. so keep 'em distinguishable bestie 💀

This feature is available in Postfix 2.0 and later.

`mime_header_checks` — default: `$header_checks`

Optional lookup tables for content inspection of MIME related message headers, as described in the header_checks(5) manual page 🔎

This feature is available in Postfix 2.0 and later.

`mime_nesting_limit` — default: `100`

The maximal recursion level that the MIME processor will handle. Postfix refuses mail that is nested deeper than the specified limit. we do have a limit and we WILL enforce it 😤

This feature is available in Postfix 2.0 and later.

`minimal_backoff_time` — default: `300s`

The minimal time between attempts to deliver a deferred message; prior to Postfix 2.4 the default value was 1000s.

This parameter also limits the time an unreachable destination is kept in the short-term, in-memory, destination status cache.

This parameter should be set greater than or equal to $queue_run_delay. See also $maximal_backoff_time.

`multi_instance_directories` — default: empty

An optional list of non-default Postfix configuration directories; these directories belong to additional Postfix instances that share the Postfix executable files and documentation with the default Postfix instance, and that are started, stopped, etc., together with the default Postfix instance. Specify a list of pathnames separated by comma or whitespace. it's giving found family of instances 🫶

When $multi_instance_directories is empty, the postfix(1) command runs in single-instance mode and operates on a single Postfix instance only. Otherwise, the postfix(1) command runs in multi-instance mode and invokes the multi-instance manager specified with the multi_instance_wrapper parameter. The multi-instance manager in turn executes postfix(1) commands for the default instance and for all Postfix instances in $multi_instance_directories.

Currently, this parameter setting is ignored except for the default main.cf file. 🙈

This feature is available in Postfix 2.6 and later.

`multi_instance_enable` — default: `no`

Allow this Postfix instance to be started, stopped, etc., by a multi-instance manager. By default, new instances are created in a safe state that prevents them from being started inadvertently. This parameter is reserved for the multi-instance manager. safety first bestie, no accidental glow-ups 💅

This feature is available in Postfix 2.6 and later.

`multi_instance_group` — default: empty

The optional instance group name of this Postfix instance. A group identifies closely-related Postfix instances that the multi-instance manager can start, stop, etc., as a unit. This parameter is reserved for the multi-instance manager. squad goals ✨

This feature is available in Postfix 2.6 and later.

`multi_instance_name` — default: empty

The optional instance name of this Postfix instance. This name becomes also the default value for the syslog_name parameter. cute lil name drop 💖

This feature is available in Postfix 2.6 and later.

`multi_instance_wrapper` — default: empty

The pathname of a multi-instance manager command that the postfix(1) command invokes when the multi_instance_directories parameter value is non-empty. The pathname may be followed by initial command arguments separated by whitespace; shell metacharacters such as quotes are not supported in this context. no quotes, no tricks, we keep it simple 🙅

The postfix(1) command invokes the manager command with the postfix(1) non-option command arguments on the manager command line, and with all installation configuration parameters exported into the manager command process environment. The manager command in turn invokes the postfix(1) command for individual Postfix instances as "postfix -c config_directory command". 🎀

This feature is available in Postfix 2.6 and later.

`multi_recipient_bounce_reject_code` — default: `550`

The numerical Postfix SMTP server response code when a remote SMTP client request is blocked by the reject_multi_recipient_bounce restriction.

bestie do NOT change this unless you have a complete understanding of RFC 5321. seriously. i'm not playing 😭

This feature is available in Postfix 2.1 and later.

🌸 `mydestination` (default: `$myhostname, localhost.$mydomain, localhost`)

okay so this is THE list of domains that get delivered through the $local_transport mail delivery transport. bestie, by default that's the Postfix local(8) delivery agent, and it goes and looks up all the recipients in /etc/passwd and /etc/aliases. Meanwhile the SMTP server is out here validating recipient addresses with $local_recipient_maps and rejecting the non-existent ones. See also the local domain class in the ADDRESS_CLASS_README file. 💅

The default mydestination value only specifies names for the local machine, okay? The way that if you're running a mail domain gateway, you should also include $mydomain. ✨

The $local_transport delivery method also gets selected for mail addressed to user@[the.net.work.address] of the mail system (the IP addresses specified with the inet_interfaces and proxy_interfaces parameters).

Warnings: 🚨

Do not specify the names of virtual domains — those domains are specified elsewhere. See VIRTUAL_README for more information.
Do not specify the names of domains that this machine is backup MX host for. See STANDARD_CONFIGURATION_README for how to set up backup MX hosts.
By default, the Postfix SMTP server rejects mail for recipients not listed with the local_recipient_maps parameter. See the postconf(5) manual for a description of the local_recipient_maps and unknown_local_recipient_reject_code parameters.

Specify a list of host or domain names, "/file/name" or "type:table" patterns, separated by commas and/or whitespace. A "/file/name" pattern is replaced by its contents; a "type:table" lookup table is matched when a name matches a lookup key (the lookup result is ignored). Continue long lines by starting the next line with whitespace. 📝

Examples:

mydestination = $myhostname, localhost.$mydomain $mydomain
mydestination = $myhostname, localhost.$mydomain www.$mydomain, ftp.$mydomain

🦋 `mydomain` (default: see `postconf -d` output)

The internet domain name of this mail system. The default is to use $myhostname minus the first component, or "localdomain" (Postfix 2.3 and later). $mydomain is used as a default value for so many other configuration parameters, like it's genuinely the main character here. 👑

Example:

mydomain = domain.tld

🌈 `myhostname` (default: see `postconf -d` output)

The internet hostname of this mail system. The default is to use the fully-qualified domain name (FQDN) from gethostname(), or to use the non-FQDN result from gethostname() and append ".$mydomain". And $myhostname is used as a default value for many other configuration parameters too. 💖

Example:

myhostname = host.example.com

✨ `mynetworks` (default: see `postconf -d` output)

The list of "trusted" remote SMTP clients that have more privileges than "strangers". 💅

In particular, "trusted" SMTP clients are allowed to relay mail through Postfix. See the smtpd_relay_restrictions parameter description in the postconf(5) manual.

You can specify the list of "trusted" network addresses by hand, or you can just let Postfix do it for you (which is the default, bestie, it's giving delegation 💁). See the description of the mynetworks_style parameter for more information.

If you specify the mynetworks list by hand, Postfix ignores the mynetworks_style setting.

Specify a list of network addresses or network/netmask patterns, separated by commas and/or whitespace. Continue long lines by starting the next line with whitespace.

The netmask specifies the number of bits in the network part of a host address. You can also specify "/file/name" or "type:table" patterns. A "/file/name" pattern is replaced by its contents; a "type:table" lookup table is matched when a table entry matches a lookup string (the lookup result is ignored).

The list is matched left to right, and the search stops on the first match. Specify "!pattern" to exclude an address or network block from the list. The form "!/file/name" is supported only in Postfix version 2.4 and later. 🚧

Note 1: Pattern matching of domain names is controlled by the presence or absence of "mynetworks" in the parent_domain_matches_subdomains parameter value.

Note 2: IP version 6 address information must be specified inside [] in the mynetworks value, and in files specified with "/file/name". IP version 6 addresses contain the ":" character, and would otherwise be confused with a "type:table" pattern.

Note 3: CIDR ranges cannot be specified in hash tables. Use cidr tables if CIDR ranges are used.

Examples:

mynetworks = 127.0.0.0/8 168.100.189.0/28
mynetworks = !192.168.0.1, 192.168.0.0/28
mynetworks = 127.0.0.0/8 168.100.189.0/28 [::1]/128 [2001:240:587::]/64
mynetworks = $config_directory/mynetworks
mynetworks = lmdb:/etc/postfix/network_table
mynetworks = cidr:/etc/postfix/network_table.cidr

Instead of lmdb:, some systems use cdb:, hash:, or dbm:.

Configuration changes will become visible after a minute or so. Use "postfix reload" to eliminate the delay. ⏳

🎀 `mynetworks_style` (default: Postfix >= 3.0: `host`, Postfix < 3.0: `subnet`)

The method to generate the default value for the mynetworks parameter. This is the list of trusted networks for relay access control etc.

Specify "mynetworks_style = host" when Postfix should "trust" only the local machine.
Specify "mynetworks_style = subnet" when Postfix should "trust" remote SMTP clients in the same IP subnetworks as the local machine. On Linux, this works correctly only with interfaces specified with the "ifconfig" or "ip" command.
Specify "mynetworks_style = class" when Postfix should "trust" remote SMTP clients in the same IP class A/B/C networks as the local machine. Caution: this may cause Postfix to "trust" your entire provider's network. 😭 Instead, specify an explicit mynetworks list by hand, as described with the mynetworks configuration parameter.

🧚 `myorigin` (default: `$myhostname`)

The domain name that locally-posted mail appears to come from, and that locally posted mail is delivered to. The default, $myhostname, is adequate for small sites. If you run a domain with multiple machines, you should (1) change this to $mydomain and (2) set up a domain-wide alias database that aliases each user to user@that.users.mailhost. 💌

Example:

myorigin = $mydomain

💜 `nested_header_checks` (default: `$header_checks`)

Optional lookup tables for content inspection of non-MIME message headers in attached messages, as described in the header_checks(5) manual page. lowkey so useful for peeking inside things 👀

This feature is available in Postfix 2.0 and later.

🍓 `newaliases_path` (default: see `postconf -d` output)

Sendmail compatibility feature that specifies the location of the newaliases(1) command. This command can be used to rebuild the local(8) aliases(5) database.

🌸 `non_bdb_custom_mapping` (default: empty)

When non-Berkeley-DB migration is enabled, an optional mapping from a hash: or btree: type to a non-Berkeley-DB type. This mapping takes precedence over the default mapping from hash: to $default_database_type, and from btree: to $default_cache_db_type. 🗺️

Specify a lookup table with a search keys that are a Berkeley DB type (without ':') or type:name.
A search key with the form type:name takes precedence over type (without ':').
The lookup result must always be a non-Berkeley-DB type (without ':') and must not contain a :name.
The mapping table type must not be hash or btree.

This feature is available in Postfix >= 3.11.

⭐ `non_bdb_migration_allow_root_prefixes` (default: see `'postconf -d non_bdb_migration_allow_root_prefixes'` output)

A list of trusted pathname prefixes that must be matched when the non-Berkeley-DB migration service (nbdb_reindexd(8)) needs to run postmap(1) or postalias(1) commands with "root" privilege. 👑

This feature is available in Postfix >= 3.11.

🌈 `non_bdb_migration_allow_user_prefixes` (default: see `'postconf -d non_bdb_migration_allow_user_prefixes'` output)

A list of trusted pathname prefixes that must be matched when the non-Berkeley-DB migration service (nbdb_reindexd(8)) needs to run postmap(1) or postalias(1) commands with non-root privilege.

This feature is available in Postfix >= 3.11.

💖 `non_bdb_migration_level` (default: `disable`)

The non-Berkeley-DB migration service level. You are expected to use the command "postfix non-bdb name-of-level" to correctly configure the migration service level (see postfix-non-bdb(1).

disable — Disable all non-Berkeley-DB migration features. See NON_BERKELEYDB_README#disable for possible negative implications for integration with other software such as mailman.
enable-redirect (aliasing) — Enable redirection (aliasing) from Berkeley DB hash to $default_database_type, and from Berkeley DB btree to $default_cache_db_type, but do not automatically create the new cdb or lmdb indexed database files that Postfix programs need. See NON_BERKELEYDB_README#enable-redirect for details and limitations.
enable-reindex — In addition to enable-redirect, also create a non-Berkeley-DB indexed database file when a daemon program wants to access a file that does not yet exist. This feature uses the nbdb_reindexd(8) daemon to run postmap(1) or postalias(1). See NON_BERKELEYDB_README#enable-reindex for details and limitations.

NOTE: enable-reindex should be used only temporarily to generate most of the non-Berkeley-DB indexed database files that Postfix programs need. Leaving this level enabled may expose the system to privilege-escalation attacks. 🚨 There are no security concerns for using enable-redirect.

This feature is available in Postfix >= 3.11.

🎀 `non_bdb_migration_log_redirect` (default: `yes`)

Log actions that redirect from a legacy Berkeley-DB database type to a non-Berkeley-DB type. 🪵

This feature is available in Postfix >= 3.11.

🦋 `non_bdb_migration_service_name` (default: `nbdb_reindex`)

The name of a master.cf service that implements the non-Berkeley-DB migration service protocol.

This feature is available in Postfix >= 3.11.

💖 `non_empty_end_of_header_action` (default: `fix_quietly`)

okay so bestie, this one decides how the cleanup(8) daemon handles a message when the primary message header gets terminated by a non-empty line 👀 like, what happens when that header end doesn't end clean.

Here's the tea on the possible values 🌸

fix_quietly — the default vibe 💅 insert an empty line before the erroneous text. This stays backwards compatible with Postfix <= 3.10.
add_header — insert a MIME-Error: header plus an empty line before the erroneous text. Like so:

MIME-Error: message header was not terminated by empty line

reject — log the erroneous text and reject the message content, no cap 😤 here's what that looks like:

queueid reject: mime-error message header was terminated
with non-empty line: erroneous text; from=<sender>
to=<recipient>

This feature is available in Postfix >= 3.11. ✨

🎀 `non_fqdn_reject_code` (default: `504`)

this is the numerical Postfix SMTP server reply code 💌 the one that fires when a client request gets rejected by the reject_non_fqdn_helo_hostname, reject_non_fqdn_sender or reject_non_fqdn_recipient restriction. so yeah, that's the code it throws back at 'em 💅

🦋 `non_smtpd_milters` (default: empty)

a list of Milter (mail filter) applications for new mail that does not arrive via the Postfix smtpd(8) server 🫶 and bestie, that includes:

local submission via the sendmail(1) command line
new mail arriving via the Postfix qmqpd(8) server
old mail that gets re-injected into the queue with "postsuper -r"

Specify space or comma as a separator, easy peasy 🍓 See the MILTER_README document for the details.

This feature is available in Postfix 2.3 and later. ✨

🌈 `notify_classes` (default: `resource, software`)

the list of error classes that get reported to the postmaster 📬 these postmaster notifications do not replace user notifications, okurr. The default is to report only the most serious problems. The paranoid girlies may wish to turn on the policy (UCE and mail relaying) and protocol error (broken mail software) reports 👑

⚠️ NOTE: postmaster notifications may contain confidential information such as SASL passwords or message content 😭 like, actual secrets. It is the system administrator's responsibility to treat such information with care, periodt.

Here are the error classes, bestie 🧚

bounce (also implies 2bounce) — send the postmaster copies of the headers of bounced mail, and send transcripts of SMTP sessions when Postfix rejects mail. The notification goes to the address specified with the bounce_notice_recipient configuration parameter (default: postmaster).
2bounce — send undeliverable bounced mail to the postmaster. The notification is sent to the address specified with the 2bounce_notice_recipient configuration parameter (default: postmaster).
data — send the postmaster a transcript of the SMTP session with an error because a critical data file was unavailable. The notification goes to the address specified with the error_notice_recipient configuration parameter (default: postmaster). This feature is available in Postfix 2.9 and later.
delay — send the postmaster copies of the headers of delayed mail (see delay_warning_time). The notification goes to the address specified with the delay_notice_recipient configuration parameter (default: postmaster).
policy — send the postmaster a transcript of the SMTP session when a client request was rejected because of (UCE) policy. The notification goes to the address specified with the error_notice_recipient configuration parameter (default: postmaster).
protocol — send the postmaster a transcript of the SMTP session in case of client or server protocol errors. The notification goes to the address specified with the error_notice_recipient configuration parameter (default: postmaster).
resource — inform the postmaster of mail not delivered due to resource problems. The notification goes to the address specified with the error_notice_recipient configuration parameter (default: postmaster).
software — inform the postmaster of mail not delivered due to software problems. The notification goes to the address specified with the error_notice_recipient configuration parameter (default: postmaster).

Examples, because we love a demo 💅

notify_classes = bounce, delay, policy, protocol, resource, software
notify_classes = 2bounce, resource, software

💜 `openssl_path` (default: `openssl`)

the location of the OpenSSL command line program openssl(1) 🔐 the "postfix tls" command uses this to create private keys, certificate signing requests, self-signed certificates, and to compute public key digests for DANE TLSA records. In multi-instance environments, this parameter is always determined from the configuration of the default Postfix instance 🫶

Example:

    /etc/postfix/main.cf:
        # NetBSD pkgsrc:
        openssl_path = /usr/pkg/bin/openssl
        # Local build:
        openssl_path = /usr/local/bin/openssl

This feature is available in Postfix 3.1 and later. ✨

🌸 `owner_request_special` (default: `yes`)

this one enables special treatment for owner-listname entries in the aliases(5) file 📖 and it stops owner-listname and listname-request address localparts from getting split when the recipient_delimiter is set to "-". Super useful for mailing lists, no cap 💌

⭐ `parent_domain_matches_subdomains` (default: see `postconf -d` output)

a list of Postfix features where the pattern "example.com" also matches subdomains of example.com 🦋 instead of requiring you to write an explicit ".example.com" pattern. This is planned backwards compatibility: eventually, all Postfix features are expected to require explicit ".example.com" style patterns when you really want to match subdomains 👀 so enjoy this while it lasts.

The following Postfix feature names are supported, bestie 🎀

Postfix version 1.0 and later — debug_peer_list, fast_flush_domains, mynetworks, permit_mx_backup_networks, relay_domains, transport_maps
Postfix version 1.1 and later — qmqpd_authorized_clients, smtpd_access_maps,
Postfix version 2.8 and later — postscreen_access_list
Postfix version 3.0 and later — smtpd_client_event_limit_exceptions

🍓 `permit_mx_backup_networks` (default: empty)

this restricts the use of the permit_mx_backup SMTP access feature to only domains whose primary MX hosts match the listed networks 🔥 the parameter value syntax is the same as with the mynetworks parameter — note, however, that the default value here is empty 😌

Pattern matching of domain names is controlled by the presence or absence of "permit_mx_backup_networks" in the parent_domain_matches_subdomains parameter value 👑

🧚 `pickup_service_name` (default: `pickup`)

the name of the pickup(8) service 💖 this service picks up local mail submissions from the Postfix maildrop queue, iconic behaviour honestly.

This feature is available in Postfix 2.0 and later. ✨

💅 `pipe_delivery_status_filter` (default: `$default_delivery_status_filter`)

an optional filter for the pipe(8) delivery agent 🎀 it can change the delivery status code or the explanatory text of successful or unsuccessful deliveries. See default_delivery_status_filter for the details, iykyk.

This feature is available in Postfix 3.0 and later. ✨

🔥 `plaintext_reject_code` (default: `450`)

the numerical Postfix SMTP server response code when a request gets rejected by the reject_plaintext_session restriction 😤 simple as that.

This feature is available in Postfix 2.3 and later. ✨

💖 `postlog_service_name` (default: `postlog`)

the name of the postlogd(8) service entry in master.cf 📜 this service appends logfile records to the file specified with the maillog_file parameter. So cute, so useful 🌸

This feature is available in Postfix 3.4 and later. ✨

🦋 `postlogd_watchdog_timeout` (default: `10s`)

how much time a postlogd(8) process may take to process a request before it gets terminated by a built-in watchdog timer ⏰ this is a safety mechanism that prevents postlogd(8) from becoming non-responsive due to a bug in Postfix itself or in system software, bestie. And heads up: this limit cannot be set under 10s 💀

This feature is available in Postfix 3.4 and later. ✨

🌈 `postmulti_control_commands` (default: `reload flush`)

the postfix(1) commands that the postmulti(1) instance manager treats as "control" commands 👑 these operate on running instances. For these commands, disabled instances are skipped 💅

This feature is available in Postfix 2.6 and later. ✨

🎀 `postmulti_start_commands` (default: `start`)

the postfix(1) commands that the postmulti(1) instance manager treats as "start" commands 🚀 for these commands, disabled instances are "checked" rather than "started", and failure to "start" a member instance of an instance group will abort the start-up of later instances 😭 like, one fails and the whole chain stops, fr fr.

This feature is available in Postfix 2.6 and later. ✨

🌸 `postmulti_stop_commands` (default: see `postconf -d` output)

the postfix(1) commands that the postmulti(1) instance manager treats as "stop" commands 🛑 for these commands, disabled instances are skipped, and enabled instances are processed in reverse order 🔄 yes bestie, backwards.

This feature is available in Postfix 2.6 and later. ✨

`postscreen_access_list` (default: `permit_mynetworks`)

Permanent allow/denylist for remote SMTP client IP addresses. postscreen(8) searches this list the instant a remote SMTP client connects, bestie. ✨ You give it a comma- or whitespace-separated list of commands (upper or lower case, idc) or lookup tables, and the search stops the second a command fires for that client IP. Periodt.

permit_mynetworks — allowlist the client and terminate the search if the client IP matches $mynetworks. Do not subject the client to any before/after 220 greeting tests. Hand the connection straight to a Postfix SMTP server process, no delay, no drama. 💅 Pattern matching of domain names is controlled by the presence or absence of "postscreen_access_list" in the parent_domain_matches_subdomains parameter value.
type:table — query the specified lookup table. Each table lookup result is an access list, except that access lists inside a table cannot specify type:table entries. To discourage the use of hash, btree, etc. tables, there is no support for substring matching like smtpd(8). Use CIDR tables instead, fr fr.
permit — allowlist the client and terminate the search. Do not subject the client to any before/after 220 greeting tests. Pass the connection immediately to a Postfix SMTP server process.
reject — denylist the client and terminate the search. Subject the client to the action configured with the postscreen_denylist_action configuration parameter. 😤
dunno — all postscreen(8) access lists implicitly have this command at the end, no cap. When dunno is executed inside a lookup table, return from the lookup table and evaluate the next command. When dunno is executed outside a lookup table, terminate the search, and subject the client to the configured before/after 220 greeting tests.

Example, because it's giving tutorial-core: 🎀

/etc/postfix/main.cf:
    postscreen_access_list = permit_mynetworks,
        cidr:/etc/postfix/postscreen_access.cidr
    # Postfix < 3.6 use postscreen_blacklist_action.
    postscreen_denylist_action = enforce

/etc/postfix/postscreen_access.cidr:
    # Rules are evaluated in the order as specified.
    # Denylist 192.168.* except 192.168.0.1.
    192.168.0.1         dunno
    192.168.0.0/16      reject

This feature is available in Postfix 2.8. 👑

`postscreen_allowlist_interfaces` (default: `static:all`)

A list of local postscreen(8) server IP addresses where a non-allowlisted remote SMTP client can obtain postscreen(8)'s temporary allowlist status. This status is required before the client can talk to a Postfix SMTP server process. By default, a client can obtain postscreen(8)'s allowlist status on any local postscreen(8) server IP address. ✨

When postscreen(8) listens on both primary and backup MX addresses, the postscreen_allowlist_interfaces parameter can be configured to give the temporary allowlist status only when a client connects to a primary MX address. Once a client is allowlisted it can talk to a Postfix SMTP server on any address. Thus, clients that connect only to backup MX addresses will never become allowlisted, and will never be allowed to talk to a Postfix SMTP server process. 😭 the door is CLOSED.

Specify a list of network addresses or network/netmask patterns, separated by commas and/or whitespace. The netmask specifies the number of bits in the network part of a host address. Continue long lines by starting the next line with whitespace.

You can also specify "/file/name" or "type:table" patterns. A "/file/name" pattern is replaced by its contents; a "type:table" lookup table is matched when a table entry matches a lookup string (the lookup result is ignored).

The list is matched left to right, and the search stops on the first match. Specify "!pattern" to exclude an address or network block from the list. 🚫

Note: IP version 6 address information must be specified inside [] in the postscreen_allowlist_interfaces value, and in files specified with "/file/name". IP version 6 addresses contain the ":" character, and would otherwise be confused with a "type:table" pattern. iykyk. 💀

Example:

/etc/postfix/main.cf:
    # Don't allowlist connections to the backup IP address.
    # Postfix < 3.6 use postscreen_whitelist_interfaces.
    postscreen_allowlist_interfaces = !168.100.189.8, static:all

This feature is available in Postfix 3.6 and later.

Available as postscreen_whitelist_interfaces in Postfix 2.9 - 3.5. 🦋 (yes she got a glow-up and a new name)

`postscreen_bare_newline_action` (default: `ignore`)

The action that postscreen(8) takes when a remote SMTP client sends a bare newline character, that is, a newline not preceded by carriage return. Specify one of the following:

ignore — ignore the failure of this test. Allow other tests to complete. Do not repeat this test before the result from some other test expires. This option is useful for testing and collecting statistics without blocking mail permanently. 🌸
enforce — allow other tests to complete. Reject attempts to deliver mail with a 550 SMTP reply, and log the helo/sender/recipient information. Repeat this test the next time the client connects.
drop — drop the connection immediately with a 521 SMTP reply. Repeat this test the next time the client connects. 💀 bye!

This feature is available in Postfix 2.8.

`postscreen_bare_newline_enable` (default: `no`)

Enable "bare newline" SMTP protocol tests in the postscreen(8) server. Heads up bestie, these tests are expensive: a remote SMTP client must disconnect after it passes the test, before it can talk to a real Postfix SMTP server. 😮‍💨

This feature is available in Postfix 2.8.

`postscreen_bare_newline_ttl` (default: `30d`)

The amount of time that postscreen(8) remembers that a client IP address passed a "bare newline" SMTP protocol test, before it address is required to pass that test again. The default is long because a remote SMTP client must disconnect after it passes the test, before it can talk to a real Postfix SMTP server. 🕰️

This feature is available in Postfix 2.8.

`postscreen_blacklist_action` (default: `ignore`)

Renamed to postscreen_denylist_action in Postfix 3.6. 👋 it's giving rebrand era.

This feature is available in Postfix 2.8 - 3.5.

`postscreen_cache_cleanup_interval` (default: `12h`)

The amount of time between postscreen(8) cache cleanup runs. Cache cleanup increases the load on the cache database and should therefore not be run frequently, ok don't be extra about it. This feature requires that the cache database supports the "delete" and "sequence" operators. Specify a zero interval to disable cache cleanup.

After each cache cleanup run, the postscreen(8) daemon logs the number of entries that were retained and dropped. A cleanup run is logged as "partial" when the daemon terminates early after "postfix reload", "postfix stop", or no requests for $max_idle seconds. 🧹

This feature is available in Postfix 2.8.

`postscreen_cache_map` (default: Postfix >= 3.11: `$default_cache_db_type:$data_directory/postscreen_cache`; Postfix < 3.11: `btree:$data_directory/postscreen_cache`)

Persistent storage for the postscreen(8) server decisions. 💾

To share a postscreen(8) cache between multiple postscreen(8) instances, use "postscreen_cache_map = proxy:lmdb:/path/to/file" or "proxy:btree:/path/to/file". This requires Postfix version 2.9 or later; earlier proxymap(8) implementations don't support cache cleanup. For an alternative approach see the memcache_table(5) manpage.

This feature is available in Postfix 2.8.

`postscreen_cache_retention_time` (default: `7d`)

The amount of time that postscreen(8) will cache an expired temporary allowlist entry before it is removed. This prevents clients from being logged as "NEW" just because their cache entry expired an hour ago. It also prevents the cache from filling up with clients that passed some deep protocol test once and never came back. 🙈 ghosting the cache, iconic.

This feature is available in Postfix 2.8.

`postscreen_client_connection_count_limit` (default: `$smtpd_client_connection_count_limit`)

How many simultaneous connections any remote SMTP client is allowed to have with the postscreen(8) daemon. By default, this limit is the same as with the Postfix SMTP server. Note that the triage process can take several seconds, with the time spent in postscreen_greet_wait delay, and with the time spent talking to the postscreen(8) built-in dummy SMTP protocol engine. ⏳

This feature is available in Postfix 2.8.

`postscreen_command_count_limit` (default: `20`)

The limit on the total number of commands per SMTP session for postscreen(8)'s built-in SMTP protocol engine. This SMTP engine defers or rejects all attempts to deliver mail, therefore there is no need to enforce separate limits on the number of junk commands and error commands. 🎯

This feature is available in Postfix 2.8.

`postscreen_command_filter` (default: `$smtpd_command_filter`)

A mechanism to transform commands from remote SMTP clients. See smtpd_command_filter for further details. ✨

This feature is available in Postfix 2.8 and later.

`postscreen_command_time_limit` (default: `normal: 300s, overload: 10s`)

The time limit to read an entire command line with postscreen(8)'s built-in SMTP protocol engine. ⏱️

This feature is available in Postfix 2.8.

postscreen_denylist_action (default: ignore) — the move postscreen(8) pulls when a remote SMTP client gets permanently denylisted via the postscreen_access_list parameter. Pick one of these, bestie:
- ignore (default) — literally just ignore this result 🙈 let the other tests finish up, and run this test again next time the client comes back. This one's for testing and collecting stats without blocking anybody's mail. Low-stakes, no drama.
- enforce — let the other tests complete, then reject the delivery attempt with a 550 SMTP reply and log the helo/sender/recipient info. Repeat next time the client connects.
- drop — yeet the connection immediately with a 521 SMTP reply. Repeat next time the client connects.

This feature is available in Postfix 3.6 and later.

Available as postscreen_blacklist_action in Postfix 2.8 - 3.5.

postscreen_disable_vrfy_command (default: $disable_vrfy_command) — turns off the SMTP VRFY command inside the postscreen(8) daemon. Peep disable_vrfy_command for the whole story. ✨

This feature is available in Postfix 2.8.

postscreen_discard_ehlo_keyword_address_maps (default: $smtpd_discard_ehlo_keyword_address_maps) — lookup tables, indexed by the remote SMTP client address, holding case insensitive lists of EHLO keywords (pipelining, starttls, auth, etc.) that the postscreen(8) server will not send in the EHLO response to a remote SMTP client. Check smtpd_discard_ehlo_keywords for details. Heads up: the table is not searched by hostname, for robustness reasons. 🫶

This feature is available in Postfix 2.8 and later.

postscreen_discard_ehlo_keywords (default: $smtpd_discard_ehlo_keywords) — a case insensitive list of EHLO keywords (pipelining, starttls, auth, etc.) that the postscreen(8) server will not send in the EHLO response to a remote SMTP client. Again, smtpd_discard_ehlo_keywords has the details. 💅

This feature is available in Postfix 2.8 and later.

postscreen_dnsbl_action (default: ignore) — the move postscreen(8) makes when a remote SMTP client's combined DNSBL score hits or exceeds a threshold (threshold defined by the postscreen_dnsbl_sites and postscreen_dnsbl_threshold parameters). Choose one:
- ignore (default) — ignore this test failing, let the other tests run to completion, and repeat this test next time the client connects. Great for testing and gathering statistics without blocking mail. ✨
- enforce — let other tests complete. Reject delivery attempts with a 550 SMTP reply and log the helo/sender/recipient information. Repeat next time the client connects.
- drop — drop the connection immediately with a 521 SMTP reply. Repeat next time the client connects.

This feature is available in Postfix 2.8.

postscreen_dnsbl_allowlist_threshold (default: 0) — lets a remote SMTP client skip the "before" and "after 220 greeting" protocol tests, based on its combined DNSBL score as defined with the postscreen_dnsbl_sites parameter.

Set a negative value to switch this feature on. When a client passes the postscreen_dnsbl_allowlist_threshold without having failed other tests, all pending or disabled tests get flagged as completed with an expiration time based on the DNS reply TTL. When a test was already completed, its expiration time is updated — but only if it was less than the value based on the DNS reply TTL. Also check out postscreen_dnsbl_max_ttl and postscreen_dnsbl_min_ttl. 👑

This feature is available in Postfix 3.6 and later.

Available as postscreen_dnsbl_whitelist_threshold in Postfix 2.11 - 3.5.

postscreen_dnsbl_max_ttl (default: ${postscreen_dnsbl_ttl?{$postscreen_dnsbl_ttl}:{1}}h) — the maximum amount of time postscreen(8) remembers that a client IP address passed a DNS-based reputation test, before it has to pass that test again. If the DNS reply specifies a shorter TTL value, that shorter value gets used — unless it would come out smaller than postscreen_dnsbl_min_ttl.

Give it a non-zero time value (an integral value plus an optional one-letter suffix for the time unit). Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). Default time unit is h (hours). ⏳

This feature is available in Postfix 3.1. The default setting is backwards-compatible with older Postfix versions.

postscreen_dnsbl_min_ttl (default: 60s) — the minimum amount of time postscreen(8) remembers that a client IP address passed a DNS-based reputation test, before it has to pass that test again. If the DNS reply specifies a larger TTL value, that larger value gets used — unless it would come out bigger than postscreen_dnsbl_max_ttl.

Give it a non-zero time value (integral value plus an optional one-letter suffix for the time unit). Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). Default time unit is s (seconds). 🌸

This feature is available in Postfix 3.1.

postscreen_dnsbl_reply_map (default: empty) — a mapping from an actual DNSBL domain name (which includes a secret password) to the DNSBL domain name that postscreen will reply with when it rejects mail. When no mapping is found, the actual DNSBL domain gets used.

For maximal stability, bestie, use a file that gets read into memory — like pcre:, regexp: or texthash:. Quick note: texthash: is similar to hash:, except a) there's no need to run postmap(1) before the file can be used, and b) texthash: does not detect changes after the file is read. 🎀

Example:

/etc/postfix/main.cf:
    postscreen_dnsbl_reply_map = texthash:/etc/postfix/dnsbl_reply

/etc/postfix/dnsbl_reply:
   secret.zen.spamhaus.org      zen.spamhaus.org

NOTE: this feature differs from the Postfix SMTP server's rbl_reply_maps feature, where 1) the table search key includes the optional "=address-filter", and where 2) the lookup result contains free text with $name variables.

This feature is available in Postfix 2.8.

postscreen_dnsbl_sites (default: empty) — an optional list of patterns with DNS allow/denylist domains, filters and weight factors. When this list is non-empty, the dnsblog(8) daemon queries these domains with the reversed IP addresses of remote SMTP clients, and postscreen(8) updates an SMTP client's DNSBL score with each non-error reply, as described below. 🦋

NOTE: always respect the usage policies of reputation services. Avoid public or ISP resolvers, unless the queries use your unique API key.

Caution: when postscreen rejects mail, its SMTP response contains the DNSBL domain name. Use the postscreen_dnsbl_reply_map feature to hide "password" information in DNSBL domain names. 💀

When a client's score is equal to or greater than the threshold specified with postscreen_dnsbl_threshold, postscreen(8) can drop the connection with the remote SMTP client.

Specify a list of domain=filter*weight patterns, separated by comma or whitespace.

When a pattern specifies no =filter, postscreen(8) will use any non-error DNSBL query result. Otherwise, postscreen(8) will use only DNSBL query results that match the filter. The filter has the form d.d.d.d, where each d is a number, or a pattern inside [] that contains one or more ;-separated numbers or number..number ranges.
When a pattern specifies no *weight, the weight of the pattern is 1. Otherwise, the weight must be an integral number. Specify a negative number for allowlisting.
When a pattern matches one or more DNSBL query results, postscreen(8) adds that pattern's weight once to the remote SMTP client's DNSBL score.

Examples:

To use example.com as a high-confidence blocklist, and to block mail with example.net and example.org only when both agree:

postscreen_dnsbl_threshold = 2
postscreen_dnsbl_sites = example.com*2, example.net, example.org

To filter only DNSBL replies containing 127.0.0.4:

postscreen_dnsbl_sites = example.com=127.0.0.4

This feature is available in Postfix 2.8.

postscreen_dnsbl_threshold (default: 1) — the inclusive lower bound for blocking a remote SMTP client, based on its combined DNSBL score as defined with the postscreen_dnsbl_sites parameter. No cap. ✋

This feature is available in Postfix 2.8.

postscreen_dnsbl_timeout (default: 10s) — the time limit for DNSBL or DNSWL lookups. This one is separate from the timeouts in the dnsblog(8) daemon, which are defined by system resolver(3) routines.

This feature is available in Postfix 3.0.

postscreen_dnsbl_ttl (default: 1h) — the amount of time postscreen(8) remembers that a client IP address passed a DNS-based reputation test, before it's required to pass that test again.

This feature is available in Postfix 2.8-3.0. It was replaced by postscreen_dnsbl_max_ttl in Postfix 3.1.

postscreen_dnsbl_whitelist_threshold (default: 0) — renamed to postscreen_dnsbl_allowlist_threshold in Postfix 3.6.

This feature is available in Postfix 2.11 - 3.5.

postscreen_enforce_tls (default: $smtpd_enforce_tls) — Mandatory TLS: announce STARTTLS support to remote SMTP clients, and require that clients use TLS encryption 🔒. Check smtpd_postscreen_enforce_tls for details.

This feature is available in Postfix 2.8 and later. Preferably, use postscreen_tls_security_level instead.

postscreen_expansion_filter (default: see postconf -d output) — list of characters that are permitted in postscreen_reject_footer attribute expansions. Peep smtpd_expansion_filter for more.

This feature is available in Postfix 2.8 and later.

postscreen_forbidden_commands (default: $smtpd_forbidden_commands) — list of commands that the postscreen(8) server considers in violation of the SMTP protocol. See smtpd_forbidden_commands for the syntax, and postscreen_non_smtp_command_action for the possible actions. 🚫

This feature is available in Postfix 2.8.

postscreen_greet_action (default: ignore) — the move postscreen(8) makes when a remote SMTP client runs its mouth before its turn, inside the window set by postscreen_greet_wait. Pick one of these bestie:
- ignore (default) — let the test fail and move on, no drama. Other tests still finish. Next time the client connects, we run this test again. Perfect for vibing out, testing, and farming stats without blocking anyone's mail 💅
- enforce — other tests still finish, but mail delivery attempts get rejected with a 550 SMTP reply, and the helo/sender/recipient info gets logged. Test repeats next connection.
- drop — hang up immediately with a 521 SMTP reply. Test repeats next connection.

Either way, no allowlisting for that remote SMTP client IP address. Not today. In either case, postscreen(8) will not allowlist the remote SMTP client IP address.

✨ Available in Postfix 2.8. ✨

postscreen_greet_banner (default: $smtpd_banner) — the lil text in the optional "220-text..." server response that postscreen(8) sends ahead of the real Postfix SMTP server's "220 text..." response. Why? To confuse bad SMTP clients into speaking before their turn (pre-greet). It's giving bait 🎣 Set it empty and the whole feature goes bye bye.

✨ Available in Postfix 2.8. ✨

postscreen_greet_ttl (default: 1d) — how long postscreen(8) remembers that a client IP passed a PREGREET test before it has to pass it all over again. The default is pretty short on purpose, because a good client can just immediately talk to a real Postfix SMTP server. No need to gatekeep a good one 🫶

Give it a non-zero time value (an integral value plus an optional one-letter suffix that specifies the time unit). Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). Default time unit is d (days).

✨ Available in Postfix 2.8. ✨

postscreen_greet_wait (default: normal: 6s, overload: 2s) — how long postscreen(8) waits for an SMTP client to send a command before its turn, and for DNS blocklist lookup results to land (default: up to 2 seconds under stress, up to 6 seconds otherwise).

✨ Available in Postfix 2.8. ✨

postscreen_helo_required (default: $smtpd_helo_required) — require that a remote SMTP client sends HELO or EHLO before starting a MAIL transaction. Manners, bestie. Say hi first 👋

✨ Available in Postfix 2.8. ✨

postscreen_non_smtp_command_action (default: drop) — the move postscreen(8) makes when a remote SMTP client sends non-SMTP commands, as specified with the postscreen_forbidden_commands parameter. Pick one:
- ignore — let the test fail, other tests still finish. Do not repeat this test before the result from some other test expires. Great for testing and collecting stats without blocking mail permanently.
- enforce — other tests still finish, but mail delivery attempts get rejected with a 550 SMTP reply, and the helo/sender/recipient info gets logged. Test repeats next connection.
- drop — hang up immediately with a 521 SMTP reply. Test repeats next connection. Same energy as the Postfix SMTP server's smtpd_forbidden_commands feature.

✨ Available in Postfix 2.8. ✨

postscreen_non_smtp_command_enable (default: no) — turn on the "non-SMTP command" tests in the postscreen(8) server. Heads up tho: these tests are expensive — a client has to disconnect after it passes the test before it can talk to a real Postfix SMTP server. It's giving ✨commitment✨

✨ Available in Postfix 2.8. ✨

postscreen_non_smtp_command_ttl (default: 30d) — how long postscreen(8) remembers that a client IP passed a "non_smtp_command" SMTP protocol test before it has to pass it again. The default is long for a reason: a client must disconnect after passing the test before it can talk to a real Postfix SMTP server. Earn that break, bestie 💅

✨ Available in Postfix 2.8. ✨

postscreen_pipelining_action (default: enforce) — the move postscreen(8) makes when a remote SMTP client sends multiple commands instead of sending one command and waiting for the server to respond. Rude. Pick one:
- ignore — let the test fail, other tests still finish. Do not repeat this test before the result from some other test expires. Useful for testing and collecting stats without blocking mail permanently.
- enforce — other tests still finish, but mail delivery attempts get rejected with a 550 SMTP reply, and the helo/sender/recipient info gets logged. Test repeats next connection.
- drop — hang up immediately with a 521 SMTP reply. Test repeats next connection.

✨ Available in Postfix 2.8. ✨

postscreen_pipelining_enable (default: no) — turn on the "pipelining" SMTP protocol tests in the postscreen(8) server. These tests are expensive: a good client must disconnect after it passes the test before it can talk to a real Postfix SMTP server. So it's not just a villain filter, it holds up the good ones too 😭

✨ Available in Postfix 2.8. ✨

postscreen_pipelining_ttl (default: 30d) — how long postscreen(8) remembers that a client IP passed a "pipelining" SMTP protocol test before it has to pass it again. Long default because a good client must disconnect after it passes the test before it can talk to a real Postfix SMTP server.

✨ Available in Postfix 2.8. ✨

postscreen_post_queue_limit (default: $default_process_limit) — how many clients can be waiting for service from a real Postfix SMTP server process. When this queue is full, every client gets a 421 response. The line is long, bestie 🫣

✨ Available in Postfix 2.8. ✨

postscreen_pre_queue_limit (default: $default_process_limit) — how many non-allowlisted clients can be waiting for a decision on whether they'll get service from a real Postfix SMTP server process. When this queue is full, all non-allowlisted clients get a 421 response. Sorry babes, waiting room's closed 🚪

✨ Available in Postfix 2.8. ✨

postscreen_reject_footer (default: $smtpd_reject_footer) — optional info appended after a 4XX or 5XX postscreen(8) server response. See smtpd_reject_footer for the deets 🔍

✨ Available in Postfix 2.8 and later. ✨

postscreen_reject_footer_maps (default: $smtpd_reject_footer_maps) — optional lookup table for info appended after a 4XX or 5XX postscreen(8) server response. See smtpd_reject_footer_maps for more.

✨ Available in Postfix 3.4 and later. ✨

postscreen_tls_security_level (default: $smtpd_tls_security_level) — the SMTP TLS security level for the postscreen(8) server. When you set a non-empty value, it overrides the obsolete parameters postscreen_use_tls and postscreen_enforce_tls. See smtpd_tls_security_level for all the details. Slay the old ways ✨

✨ Available in Postfix 2.8 and later. ✨

postscreen_upstream_proxy_protocol (default: empty) — the name of the proxy protocol used by an optional before-postscreen proxy agent. When a proxy agent is out here doing its thing, this protocol conveys local and remote address and port info. Set "postscreen_upstream_proxy_protocol = haproxy" to enable the haproxy protocol; version 2 is supported with Postfix 3.5 and later 💖

✨ Available in Postfix 2.10 and later. ✨

postscreen_upstream_proxy_timeout (default: 5s) — the time limit for the proxy protocol specified with the postscreen_upstream_proxy_protocol parameter. Clock's ticking ⏰

✨ Available in Postfix 2.10 and later. ✨

postscreen_use_tls (default: $smtpd_use_tls) — opportunistic TLS: announce STARTTLS support to remote SMTP clients but don't require that clients use TLS encryption. Flexible, no pressure 💅

✨ Available in Postfix 2.8 and later. Preferably, use postscreen_tls_security_level instead. ✨

postscreen_watchdog_timeout (default: 10s) — how much time a postscreen(8) process may take to respond to a remote SMTP client command or to perform a cache operation before it gets terminated by a built-in watchdog timer. It's a safety mechanism so postscreen(8) doesn't go non-responsive because of a bug in Postfix itself or in system software. And listen: to avoid false alarms and unnecessary cache corruption, this limit cannot be set under 10s. Non-negotiable, periodt 🛑

✨ Available in Postfix 2.8. ✨

postscreen_whitelist_interfaces (default: static:all) — renamed to postscreen_allowlist_interfaces in Postfix 3.6. Glow-up era, bestie 🦋

✨ Available in Postfix 2.9 - 3.5. ✨

prepend_delivered_header (default: command, file, forward) — the message delivery contexts where the Postfix local(8) delivery agent prepends a Delivered-To: message header with the address that the mail was delivered to. This info is how mail delivery loop detection works 🌀

By default, the Postfix local delivery agent prepends a Delivered-To: header when forwarding mail and when delivering to file (mailbox) and command. And no cap: turning off the Delivered-To: header when forwarding mail is not recommended 🙅‍♀️

Specify zero or more of forward, file, or command.

Example:

prepend_delivered_header = forward

process_id (read-only) — the process ID of a Postfix command or daemon process. Just a lil number identifying your fave process 🎀
process_id_directory (default: pid) — the location of Postfix PID files relative to $queue_directory. Heads up: this is a read-only parameter 👀
process_name (read-only) — the process name of a Postfix command or daemon process. Name check ✨
propagate_unmatched_extensions (default: canonical, virtual) — bestie, this is the setting that decides which lookup tables lowkey carry an address extension along for the ride, copying it from the lookup key straight into the lookup result. 💅

Like, say you've got a virtual(5) mapping of "joe@example.com => joe.user@example.net". With this on, the address "joe+foo@example.com" would rewrite itself to "joe.user+foo@example.net". The extension just... comes with. Iconic behavior honestly.

You can specify zero or more of canonical, virtual, alias, forward, include or generic. And what do those do, you ask? They cause address extension propagation with canonical(5), virtual(5), and aliases(5) maps, with local(8) .forward and :include: file lookups, and with smtp(8) generic maps, respectively. One for each, we love a clean assignment. ✨

⚠️ Okay so real talk: enabling this for types other than canonical and virtual is likely to cause problems when mail gets forwarded to other sites — especially mail that's sent to a mailing list exploder address. It's giving chaos, so be careful.

Examples, because seeing it helps:

propagate_unmatched_extensions = canonical, virtual, alias,
        forward, include
propagate_unmatched_extensions = canonical, virtual

proxy_interfaces (default: empty) — the remote network interface addresses that this mail system receives mail on by way of a proxy or network address translation unit. 🌐

This feature is available in Postfix 2.0 and later.

You must specify your "outside" proxy/NAT addresses when your system is a backup MX host for other domains — otherwise mail delivery loops will happen when the primary MX host is down. Not a vibe, fix it. 😭

Example:

proxy_interfaces = 1.2.3.4

proxy_read_maps (default: see postconf -d output) — the lookup tables that the proxymap(8) server is allowed to access for the read-only service. 🔒

Specify zero or more type:name lookup tables, separated by whitespace or comma. Table references that don't begin with proxy: are ignored. Like, don't even bother.

This feature is available in Postfix 2.0 and later.

proxy_write_maps (default: see postconf -d output) — the lookup tables that the proxymap(8) server is allowed to access for the read-write service. Postfix-owned local database files should be stored under the Postfix-owned data_directory. Table references that don't begin with proxy: are ignored here too. 🫶

This feature is available in Postfix 2.5 and later.

proxymap_service_name (default: proxymap) — the name of the proxymap read-only table lookup service. This service is normally implemented by the proxymap(8) daemon. ✨

This feature is available in Postfix 2.6 and later.

proxywrite_service_name (default: proxywrite) — the name of the proxywrite read-write table lookup service. This service is normally implemented by the proxymap(8) daemon. Twin energy with the one above, no cap. 💅

This feature is available in Postfix 2.6 and later.

qmgr_clog_warn_time (default: 300s) — the minimal delay between warnings that a specific destination is clogging up the Postfix active queue. Specify 0 to disable. 🚦

This feature is enabled with the helpful_warnings parameter.

This feature is available in Postfix 2.0 and later.

qmgr_daemon_timeout (default: 1000s) — how much time a Postfix queue manager process may take to handle a request before it is terminated by a built-in watchdog timer. It's giving "you have one job and a deadline". ⏰

This feature is available in Postfix 2.8 and later.

qmgr_fudge_factor (default: 100) — obsolete feature, bestie. It was the percentage of delivery resources that a busy mail system will use up for delivery of a large mailing list message. 💀

This feature exists only in the oqmgr(8) old queue manager. The current queue manager solves the problem in a better way. So like, we don't need her anymore.

qmgr_ipc_timeout (default: 60s) — the time limit for the queue manager to send or receive information over an internal communication channel. The purpose is to break out of deadlock situations. If the time limit is exceeded the software either retries or aborts the operation. Real "we're not stuck here forever" energy. 🔥

This feature is available in Postfix 2.8 and later.

qmgr_message_active_limit (default: 20000) — the maximal number of messages in the active queue. That's the cap, periodt. 👑
qmgr_message_recipient_limit (default: 20000) — the maximal number of recipients held in memory by the Postfix queue manager, and the maximal size of the short-term, in-memory "dead" destination status cache. Two jobs, one setting, we love a multitasker. ✨
qmgr_message_recipient_minimum (default: 10) — the minimal number of in-memory recipients for any message. This takes priority over any other in-memory recipient limits (i.e., the global qmgr_message_recipient_limit and the per transport _recipient_limit) if necessary. She overrides everybody, main character energy fr fr. 💅 The minimum value allowed for this parameter is 1.
qmqpd_authorized_clients (default: empty) — what remote QMQP clients are allowed to connect to the Postfix QMQP server port. 🚪

By default, no client is allowed to use the service. This is because the QMQP server will relay mail to any destination. Yeah, wide open, so we gatekeep.

Specify a list of client patterns. A list pattern specifies a host name, a domain name, an internet address, or a network/mask pattern, where the mask specifies the number of bits in the network part. When a pattern specifies a file name, its contents are substituted for the file name; when a pattern is a "type:table" table specification, table lookup is used instead. An IPv6 address must be enclosed in []. 🦋

Patterns are separated by whitespace and/or commas. In order to reverse the result, precede a pattern with an exclamation point (!). The form "!/file/name" is supported only in Postfix version 2.4 and later.

Pattern matching of domain names is controlled by the presence or absence of "qmqpd_authorized_clients" in the parent_domain_matches_subdomains parameter value.

Example:

qmqpd_authorized_clients = !192.168.0.1, 192.168.0.0/24

qmqpd_client_port_logging (default: no) — enable logging of the remote QMQP client port in addition to the hostname and IP address. The logging format is "host[address]:port". Receipts, basically. 🧾

This feature is available in Postfix 2.5 and later.

qmqpd_error_delay (default: 1s) — how long the Postfix QMQP server will pause before sending a negative reply to the remote QMQP client. The purpose is to slow down confused or malicious clients. A little dramatic pause before the "no", honestly iconic. 💅

qmqpd_timeout (default: 300s) — the time limit for sending or receiving information over the network. If a read or write operation blocks for more than $qmqpd_timeout seconds the Postfix QMQP server gives up and disconnects. Not ghosting, just setting a boundary. ✋

queue_directory (default: see postconf -d output) — the location of the Postfix top-level queue directory. This is the root directory of Postfix daemon processes that run chrooted. 🏠 It's the home base, the whole address.
queue_file_attribute_count_limit (default: 100) — the maximal number of (name=value) attributes that may be stored in a Postfix queue file. The limit is enforced by the cleanup(8) server. She's the bouncer, no cap. 🎀

This feature is available in Postfix 2.0 and later.

queue_minfree (default: 0) — the minimal amount of free space in bytes in the queue file system that is needed to receive mail. This is currently used by the Postfix SMTP server to decide if it will accept any mail at all. 🍓

By default, the Postfix SMTP server rejects MAIL FROM commands when the amount of free space is less than 1.5*$message_size_limit (Postfix version 2.1 and later). To specify a higher minimum free space limit, specify a queue_minfree value that is at least 1.5*$message_size_limit.

With Postfix versions 2.0 and earlier, a queue_minfree value of zero means there is no minimum required amount of free space.

queue_run_delay (default: 300s) — the time between deferred queue scans by the queue manager; prior to Postfix 2.4 the default value was 1000s. ⏳

This parameter should be set less than or equal to $minimal_backoff_time. See also $maximal_backoff_time.

queue_service_name (default: qmgr) — the name of the qmgr(8) service. This service manages the Postfix queue and schedules delivery requests. The whole operation runs through her, periodt. 👑

This feature is available in Postfix 2.0 and later.

🌸 rbl_reply_maps (default: empty) 🌸

Optional lookup tables with RBL or RHSBL response templates, bestie. The table search key is the reject_rbl_* or reject_rhsbl_* argument, including any optional "=address-filter". And with Postfix 3.10 and later, if the result is "not found" and the search key has the form domain=address-filter, then rbl_reply_maps will also search with the domain. ok so multi-lookup era 💅

By default, Postfix uses the template as specified with the default_rbl_reply configuration parameter. Go read there for the whole discussion of the response template syntax — it's giving lore.

Example:

/etc/postfix/main.cf:
    rbl_reply_maps = lmdb:/etc/postfix/rbl_reply
    smtpd_recipient_restrictions =
        permit_mynetworks,
        reject_rbl_client secret.zen.dq.spamhaus.net=127.0.0.[2..11],
        ...
/etc/postfix/rbl_reply:
    # See https://www.postfix.org/postconf.5.html#default_rbl_reply
    # for the definition of the $client_address and $rbl_class etc.
    # variables.
    secret.zen.dq.spamhaus.net=127.0.0.[2..11]
        554 $rbl_class $rbl_what blocked using ZEN - see https://www.spamhaus.org/query/ip/$client_address for details

    # Postfix >= 3.10: if a search key domain=address-filter
    # is not found, then rbl_reply_maps will also search with the
    # domain.
    secret.zen.dq.spamhaus.net
        554 $rbl_class $rbl_what blocked using ZEN - see https://www.spamhaus.org/query/ip/$client_address for details

Instead of lmdb:, some systems use cdb:, hash:, or dbm: — pick your fave database girlie 🎀

NOTE: This feature differs from postscreen_dnsbl_reply_map where the table search key is only a domain name (no "=address-filter", no "*weight" factor) and where the lookup result should be only a domain name (no free text, no $name variables). Not the same thing, don't mix them up bestie.

Execute the command postmap /etc/postfix/rbl_reply after you change the rbl_reply file, to (re)build a default-type indexed file. Execute postmap type:/etc/postfix/rbl_reply to specify an explicit type. lowkey obsessed with postmap ✨

The default indexed file type is configured with the default_database_type parameter. To list available explicit types, execute the command postconf -m.

Configuration changes will become visible after a minute or so. Use postfix reload to eliminate the delay. impatient? same. 🦋

This feature is available in Postfix 2.0 and later. The "=address-filter" feature is available in Postfix 2.8 and later.

🌈 readme_directory (default: see `postconf -d` output) 🌈

The location of Postfix README files that describe how to build, configure or operate a specific Postfix subsystem or feature. it's literally the docs folder of the whole vibe, periodt

💖 receive_override_options (default: empty) 💖

Enable or disable recipient validation, built-in content filtering, or address mapping. Typically, these are specified in master.cf as command-line arguments for the smtpd(8), qmqpd(8) or pickup(8) daemons.

Specify zero or more of the following options. The options override main.cf settings and are either implemented by smtpd(8), qmqpd(8), or pickup(8) themselves, or they are forwarded to the cleanup server. team work makes the dream work 🫶

no_unknown_recipient_checks — Do not try to reject unknown recipients (SMTP server only). This is typically specified AFTER an external content filter.
no_address_mappings — Disable canonical address mapping, virtual alias map expansion, address masquerading, and automatic BCC (blind carbon-copy) recipients. This is typically specified BEFORE an external content filter.
no_header_body_checks — Disable header/body_checks. This is typically specified AFTER an external content filter.
no_milters — Disable Milter (mail filter) applications. This is typically specified AFTER an external content filter.

Note: when the "BEFORE content filter" receive_override_options setting is specified in the main.cf file, specify the "AFTER content filter" receive_override_options setting in master.cf (and vice versa). location matters bestie, don't fumble the ordering 💀

Examples:

receive_override_options =
    no_unknown_recipient_checks, no_header_body_checks
receive_override_options = no_address_mappings

This feature is available in Postfix 2.1 and later.

🎀 recipient_bcc_maps (default: empty) 🎀

Optional BCC (blind carbon-copy) address lookup tables, indexed by envelope recipient address. The BCC address (multiple results are not supported) is added when mail enters from outside of Postfix. sneaky lil copy, iconic 🌸

Specify zero or more "type:name" lookup tables, separated by whitespace or comma. Tables will be searched in the specified order until a match is found.

The table search order is as follows:

Look up the "user+extension@domain.tld" address including the optional address extension.
Look up the "user@domain.tld" address without the optional address extension.
Look up the "user+extension" address local part when the recipient domain equals $myorigin, $mydestination, $inet_interfaces or $proxy_interfaces.
Look up the "user" address local part when the recipient domain equals $myorigin, $mydestination, $inet_interfaces or $proxy_interfaces.
Look up the "@domain.tld" part.

Note: with Postfix 2.3 and later the BCC address is added as if it was specified with NOTIFY=NONE. The sender will not be notified when the BCC address is undeliverable, as long as all down-stream software implements RFC 3461.

Note: with Postfix 2.2 and earlier the sender will unconditionally be notified when the BCC address is undeliverable.

Note: automatic BCC recipients are produced only for new mail. To avoid mailer loops, automatic BCC recipients are not generated after Postfix forwards mail internally, or after Postfix generates mail itself. no infinite BCC ouroboros pls 🐍

Note: automatic BCC recipients are subject to address canonicalization (add missing domain), canonical_maps, masquerade_domains, and virtual_alias_maps.

Example:

recipient_bcc_maps = lmdb:/etc/postfix/recipient_bcc

Instead of lmdb:, some systems use cdb:, hash:, or dbm:.

Execute the command postmap /etc/postfix/recipient_bcc after you change the recipient_bcc file, to (re)build a default-type indexed file. Execute postmap type:/etc/postfix/recipient_bcc to specify an explicit type.

The default indexed file type is configured with the default_database_type parameter. To list available explicit types, execute the command postconf -m.

Configuration changes will become visible after a minute or so. Use postfix reload to eliminate the delay.

This feature is available in Postfix 2.1 and later.

⭐ recipient_canonical_classes (default: `envelope_recipient, header_recipient`) ⭐

What addresses are subject to recipient_canonical_maps address mapping. By default, recipient_canonical_maps address mapping is applied to envelope recipient addresses, and to header recipient addresses. both of them bestie, no crumbs left 💅

Specify one or more of: envelope_recipient, header_recipient

This feature is available in Postfix 2.2 and later.

💜 recipient_canonical_maps (default: empty) 💜

Optional address mapping lookup tables for envelope and header recipient addresses. The table format and lookups are documented in canonical(5). go read the sister page fr fr

Note: $recipient_canonical_maps is processed before $canonical_maps. order matters, always 🦋

Example:

recipient_canonical_maps = lmdb:/etc/postfix/recipient_canonical

Instead of lmdb:, some systems use cdb:, hash:, or dbm:.

Execute the command postmap /etc/postfix/recipient_canonical after you change the recipient_canonical file, to (re)build a default-type indexed file. Execute postmap type:/etc/postfix/recipient_canonical to specify an explicit type.

The default indexed file type is configured with the default_database_type parameter. To list available explicit types, execute the command postconf -m.

Configuration changes will become visible after a minute or so. Use postfix reload to eliminate the delay.

✨ recipient_delimiter (default: empty) ✨

The set of characters that can separate an email address localpart, user name, or a .forward file name from its extension. For example, with "recipient_delimiter = +", the software tries user+foo@example.com before trying user@example.com, user+foo before trying user, and .forward+foo before trying .forward. it's giving plus-addressing supremacy 🔥

More formally, an email address localpart or user name is separated from its extension by the first character that matches the recipient_delimiter set. The delimiter character and extension may then be used to generate an extended .forward file name. This implementation recognizes one delimiter character and one extension per email address localpart or email address. With Postfix 2.10 and earlier, the recipient_delimiter specifies a single character. one char only back then, rip 💀

See canonical(5), local(8), relocated(5) and virtual(5) for the effects of recipient_delimiter on lookups in aliases, canonical, virtual, and relocated maps, and see the propagate_unmatched_extensions parameter for propagating an extension from one email address to another.

When used in command_execution_directory, forward_path, or luser_relay, ${recipient_delimiter} is replaced with the actual recipient delimiter that was found in the recipient email address (Postfix 2.11 and later), or it is replaced with the main.cf recipient_delimiter parameter value (Postfix 2.10 and earlier).

The recipient_delimiter is not applied to the mailer-daemon address, the postmaster address, or the double-bounce address. With the default "owner_request_special = yes" setting, the recipient_delimiter is also not applied to addresses with the special "owner-" prefix or the special "-request" suffix. those ones are protected bestie, hands off 🙈

Examples:

# Handle Postfix-style extensions.
recipient_delimiter = +

# Handle both Postfix and qmail extensions (Postfix 2.11 and later).
recipient_delimiter = +-

# Use .forward for mail without address extension, and for mail with
# an unrecognized address extension.
forward_path = $home/.forward${recipient_delimiter}${extension},
    $home/.forward

👑 reject_code (default: 554) 👑

The numerical Postfix SMTP server response code when a remote SMTP client request is rejected by the "reject" restriction.

Do not change this unless you have a complete understanding of RFC 5321. seriously bestie, don't just vibe-edit this one, it's giving danger 😭

💖 `reject_tempfail_action` (default: `defer_if_permit`)

okay so bestie, this one is about what the Postfix SMTP server does when a reject-type restriction fails because of a temporary error condition. 🌩️

Set it to "defer" and the remote SMTP client request gets deferred immediately, no questions asked, straight to jail. But with the default "defer_if_permit" action, the Postfix SMTP server keeps scrolling for more chances to reject the mail, and only defers the client request if it would've otherwise been accepted. 👑

Want more surgical control? Go look at: unverified_recipient_tempfail_action, unverified_sender_tempfail_action, unknown_address_tempfail_action, and unknown_helo_hostname_tempfail_action. 🎯

This feature is available in Postfix 2.6 and later. ✨

🔐 `relay_clientcerts` (default: empty)

A list of tables holding remote SMTP client-certificate fingerprints (or public key fingerprints, Postfix 2.9 and later) for which the Postfix SMTP server will allow access with the permit_tls_clientcerts feature. 💅

The fingerprint digest algorithm is configurable via the smtpd_tls_fingerprint_digest parameter (and ngl it was hard-coded as md5 prior to Postfix version 2.5 🙈).

So here's the tea on algorithms: the default algorithm is sha256 with Postfix >= 3.6 and the compatibility_level set to 3.6 or higher. With Postfix <= 3.5, the default algorithm is md5. The best-practice algorithm is now sha256. Recent advances in hash function cryptanalysis have led to md5 and sha1 being deprecated in favor of sha256. However — as long as there are no known "second pre-image" attacks against the older algorithms, their use in this context, though not recommended, is still likely safe. 👀

⚠️ lowkey important: md5 and sha1 are deprecated, bestie. sha256 is the moment. But not like, panic-dangerous yet.

Postfix lookup tables are in the form of (key, value) pairs. Since we only need the key, the value can be chosen freely, e.g. the name of the user or host:

D7:04:2F:A7:0B:8C:A5:21:FA:31:77:E1:41:8A:EE:80 lutzpc.at.home

Example:

relay_clientcerts = lmdb:/etc/postfix/relay_clientcerts

Instead of lmdb:, some systems use cdb:, hash:, or dbm:. 🌈

For more fine-grained control, use check_ccert_access to select an appropriate access(5) policy for each client. See RESTRICTION_CLASS_README. 🔍

Execute the command "postmap /etc/postfix/relay_clientcerts" after you change the relay_clientcerts file, to (re)build a default-type indexed file. Execute "postmap type:/etc/postfix/relay_clientcerts" to specify an explicit type. 🛠️

The default indexed file type is configured with the default_database_type parameter. To list available explicit types, execute the command "postconf -m".

Configuration changes will become visible after a minute or so. ⏳ Use "postfix reload" to eliminate the delay. slay.

This feature is available with Postfix version 2.2. 💫

🚦 `relay_destination_concurrency_limit` (default: `$default_destination_concurrency_limit`)

The maximal number of parallel deliveries to the same destination via the relay message delivery transport. This limit is enforced by the queue manager. 📬

The message delivery transport name is the first field in the entry in the master.cf file. iykyk.

This feature is available in Postfix 2.0 and later. ✨

👥 `relay_destination_recipient_limit` (default: `$default_destination_recipient_limit`)

The maximal number of recipients per message for the relay message delivery transport. This limit is also enforced by the queue manager. The message delivery transport name is the first field in the entry in the master.cf file, same as before bestie. 🎀

Setting this parameter to a value of 1 changes the meaning of relay_destination_concurrency_limit from concurrency per domain into concurrency per recipient. 🌪️

This feature is available in Postfix 2.0 and later.

🌍 `relay_domains` (default: Postfix >= 3.0: empty, Postfix < 3.0: `$mydestination`)

What destination domains (and subdomains thereof) this system will relay mail to. 🛫 For details about how the relay_domains value is used, see the description of the permit_auth_destination and reject_unauth_destination SMTP recipient restrictions.

Domains that match $relay_domains are delivered with the $relay_transport mail delivery transport. The SMTP server validates recipient addresses with $relay_recipient_maps and rejects non-existent recipients. See also the relay domains address class in the ADDRESS_CLASS_README file. 📖

🌟 heads up: Postfix will not automatically forward mail for domains that list this system as their primary or backup MX host. See the permit_mx_backup restriction in the postconf(5) manual page. no cap.

Specify a list of host or domain names, "/file/name" patterns or "type:table" lookup tables, separated by commas and/or whitespace. Continue long lines by starting the next line with whitespace. A "/file/name" pattern is replaced by its contents; a "type:table" lookup table is matched when a (parent) domain appears as lookup key. Specify "!pattern" to exclude a domain from the list. The form "!/file/name" is supported only in Postfix version 2.4 and later. 🔥

Pattern matching of domain names is controlled by the presence or absence of "relay_domains" in the parent_domain_matches_subdomains parameter value.

🛑 `relay_domains_reject_code` (default: `554`)

The numerical Postfix SMTP server response code when a client request is rejected by the reject_unauth_destination recipient restriction. 📮

Do not change this unless you have a complete understanding of RFC 5321. like, fr fr, don't touch it. 🙅‍♀️

📋 `relay_recipient_maps` (default: empty)

Optional lookup tables with all valid addresses in the domains that match $relay_domains. ✨

Specify @domain as a wild-card for domains that have no valid recipient list, and become a source of backscatter mail: Postfix accepts spam for non-existent recipients and then floods innocent people with undeliverable mail. 😭 that's the villain origin story right there.

Technically, tables listed with $relay_recipient_maps are used as lists: Postfix needs to know only if a lookup string is found or not, but it does not use the result from the table lookup.

Specify zero or more "type:name" lookup tables, separated by whitespace or comma. Tables will be searched in the specified order until a match is found. 🔎

If this parameter is non-empty, then the Postfix SMTP server will reject mail to unknown relay users. This feature is off by default. 💤

See also the relay domains address class in the ADDRESS_CLASS_README file.

Example:

relay_recipient_maps = lmdb:/etc/postfix/relay_recipients

Instead of lmdb:, some systems use cdb:, hash:, or dbm:. 🌈

Execute the command "postmap /etc/postfix/relay_recipients" after you change the relay_recipients file, to (re)build a default-type indexed file. Execute "postmap type:/etc/postfix/relay_recipients" to specify an explicit type. 🛠️

The default indexed file type is configured with the default_database_type parameter. To list available explicit types, execute the command "postconf -m".

Configuration changes will become visible after a minute or so. ⏳ Use "postfix reload" to eliminate the delay.

This feature is available in Postfix 2.0 and later. 💜

🚚 `relay_transport` (default: `relay`)

The default mail delivery transport and next-hop destination for the relay domain address class: recipient domains that match $relay_domains. 📦

For recipient domains in the relay domain address class:

In order of decreasing precedence, the message delivery transport is taken from 1) $transport_maps, 2) $relay_transport. 🥇
In order of decreasing precedence, the nexthop destination is taken from 1) $transport_maps, 2) $relay_transport, 3) $sender_dependent_relayhost_maps or $relayhost or the recipient domain. 🥈

Specify a string of the form transport:nexthop, where transport is the name of a mail delivery transport defined in master.cf. The :nexthop destination is optional; its syntax is documented in the manual page of the corresponding delivery agent. 📚

See also the relay domains address class in the ADDRESS_CLASS_README file.

This feature is available in Postfix 2.0 and later. ⭐

📮 `relayhost` (default: empty)

The next-hop destination(s) for non-local mail; takes precedence over non-local domains in recipient addresses. This information will not be used when the sender matches $sender_dependent_relayhost_maps. 👀

In order of decreasing precedence:

For recipient domains in the relay domain address class (domains matching $relay_domains), the nexthop destination is taken from 1) $transport_maps, 2) $relay_transport, 3) $sender_dependent_relayhost_maps or $relayhost or the recipient domain. 🥇
For recipient domains in the default domain address class (domains that do not match $mydestination, $inet_interfaces, $proxy_interfaces, $virtual_alias_domains, $virtual_mailbox_domains, or $relay_domains), the nexthop destination is taken from 1) $transport_maps, 2) $sender_dependent_default_transport_maps or $default_transport, 3) $sender_dependent_relayhost_maps or $relayhost or the recipient domain. 🥈

On an intranet, specify the organizational domain name. If your internal DNS uses no MX records, specify the name of the intranet gateway host instead. 🏢

In the case of SMTP delivery, specify one or more destinations in the form of a domain name, hostname, hostname:service, [hostname]:service, [hostaddress] or [hostaddress]:service, separated by comma or whitespace. The form [hostname] turns off MX or SRV lookups. Multiple destinations are supported in Postfix 3.5 and later. Each destination is tried in the specified order. 🎯

If an SMTP destination is a load balancer, and there are no alternative destinations, specify the load balancer multiple times. Without the duplicate info, the Postfix SMTP client would not reconnect immediately to the same load balancer after a remote SMTP server failure. 💥

If you're connected via UUCP, see the UUCP_README file for useful information. ☎️

Examples:

relayhost = $mydomain
relayhost = [gateway.example.com]
relayhost = mail1.example:587, mail2.example:587
relayhost = [an.ip.add.ress]

relocated_maps (default: empty) 💌

Optional lookup tables holding the new contact info for users or domains that literally don't exist anymore. All the table format + lookup lore lives in relocated(5).

Spill zero or more type:name lookup tables, separated by whitespace or comma (yes bestie, both work 💅). Tables get searched in the order you listed them, and it stops at the first match.

Examples:

relocated_maps = lmdb:/etc/postfix/relocated

Instead of lmdb:, some systems use cdb:, hash:, or dbm:.

After you change the relocated file, run the command postmap /etc/postfix/relocated to (re)build a default-type indexed file. Run postmap type:/etc/postfix/relocated when you wanna specify an explicit type.

The default indexed file type is configured with the default_database_type parameter. To list available explicit types, run the command postconf -m.

Config changes become visible after a minute or so. Use postfix reload to eliminate the delay. ⏱️✨

relocated_prefix_enable (default: yes) 🎀

Prepend the prefix 5.1.6 User has moved to to all relocated_maps lookup results. With relocated_prefix_enable = no, all lookup results must contain a valid RFC 3463 compliant enhanced status code and text (format: [45].number.number text...).

Example:

/etc/postfix/main.cf:
    relocated_maps = lmdb:/etc/postfix/relocated
    relocated_prefix_enable = no
/etc/postfix/relocated:
    user@example.com 5.2.1 User account is disabled

Instead of lmdb:, some systems use cdb:, hash:, or dbm:.

After you change the relocated file, run the command postmap /etc/postfix/relocated to (re)build a default-type indexed file. Run postmap type:/etc/postfix/relocated to specify an explicit type.

The default indexed file type is configured with the default_database_type parameter. To list available explicit types, run the command postconf -m.

Config changes become visible after a minute or so. Use postfix reload to eliminate the delay.

This feature is available in Postfix 3.11 and later. 🦋

remote_header_rewrite_domain (default: empty) 📬

Rewrite or add message headers in mail from remote clients — but only if this parameter's value is non-empty. When it is, incomplete addresses get updated with the domain you specified here, and missing headers get added.

The local_header_rewrite_clients parameter controls what clients Postfix considers local. 👀

Examples:

The safe setting: append domain.invalid to incomplete header addresses from remote SMTP clients, so those addresses can't get confused with local addresses.

remote_header_rewrite_domain = domain.invalid

The default, purist setting: don't rewrite headers from remote clients at all. Periodt.

remote_header_rewrite_domain =

require_home_directory (default: no) 🏠

Require that a local(8) recipient's home directory exists before mail delivery is attempted. By default this test is disabled. It can be useful for environments that import home directories to the mail server.

⚠️ IMPORTING HOME DIRECTORIES IS NOT RECOMMENDED. bestie don't do it

requiretls_enable (default: yes) 🔐

Enable support for the ESMTP verb REQUIRETLS in the MAIL FROM command. As defined in RFC 8689, when a message specifies REQUIRETLS:

deliveries with SMTP or LMTP must use a TLS connection,
to a securely looked up MX server (e.g., DNSSEC or MTA-STS),
with a matched server certificate (Postfix SMTP or LMTP client TLS security levels secure, verify, fingerprint, dane-only, or opportunistic dane),
and the server must announce REQUIRETLS support after the STARTTLS handshake.

When delivering a message that specifies REQUIRETLS, the Postfix SMTP client will try one or more servers, limited by the smtp_mx_address_limit and smtp_mx_session_limit parameters, until it finds an MX server that satisfies the above requirements. If such a server is not found, the Postfix SMTP or LMTP client returns the message as undeliverable. 💀

Notes:

With the Postfix SMTP or LMTP clients, REQUIRETLS enforcement is controlled with smtp_requiretls_policy or lmtp_requiretls_policy. It is initially not enforced for deliveries to local servers, including LMTP message stores and local content filters.
The ESMTP REQUIRETLS option overrides the TLS-Required: no message header.

This feature is available in Postfix >= 3.11. 🎉

requiretls_esmtp_header (default: yes) 🏷️

Record the ESMTP REQUIRETLS request in a Require-TLS-ESMTP: yes message header. This is needed to propagate the REQUIRETLS request through an external content filter that is configured with smtpd_proxy_filter, with content_filter, or with a FILTER action in an SMTPD access(5) table, header_checks(5) or body_checks(5). The header is not needed with Milter-based content filters.

This header will be visible to remote and local recipients. 👁️ It can safely be disabled if a configuration does not use any of the above content filters that need the header.

This feature is available in Postfix 3.11 and later. ✨

requiretls_redact_dsn (default: yes) 🙈

When sending a delivery status notification for an original message received with the REQUIRETLS option, do not send the original message body (as if that message was received with RET=HDRS) and do not enforce REQUIRETLS (as if that message was received without REQUIRETLS). For a detailed discussion see RFC 8689 section 5.

⚠️ Note: the 'reverse' path for sending a delivery status notification may differ from the 'forward' path for receiving the original message. Not every hop in the reverse path may support REQUIRETLS, even though every hop in the forward path supported it. The setting requiretls_redact_dsn = no may therefore result in the loss of a delivery status notification. 😭

reset_owner_alias (default: no) 🧑‍🤝‍🧑

Reset the local(8) delivery agent's idea of the owner-alias attribute, when delivering mail to a child alias that does not have its own owner alias.

This feature is available in Postfix 2.8 and later. With older Postfix releases, the behavior is as if this parameter is set to yes.

As documented in aliases(5), when an alias name has a companion alias named owner-name, this will replace the envelope sender address, so that delivery errors will be reported to the owner alias instead of the sender. This configuration is recommended for mailing lists. 📧

A less known property of the owner alias is that it also forces the local(8) delivery agent to write local and remote addresses from alias expansion to a new queue file, instead of attempting to deliver mail to local addresses as soon as they come out of alias expansion.

Writing local addresses from alias expansion to a new queue file allows for robust handling of temporary delivery errors: errors with one local member have no effect on deliveries to other members of the list. On the other hand, delivery to local addresses as soon as they come out of alias expansion is fragile: a temporary error with one local address from alias expansion will cause the entire alias to be expanded repeatedly until the error goes away, or until the message expires in the queue. In that case, a problem with one list member results in multiple message deliveries to other list members. 💀💀

The default behavior of Postfix 2.8 and later is to keep the owner-alias attribute of the parent alias, when delivering mail to a child alias that does not have its own owner alias. Then, local addresses from that child alias will be written to a new queue file, and a temporary error with one local address will not affect delivery to other mailing list members. 👑

Unfortunately, older Postfix releases reset the owner-alias attribute when delivering mail to a child alias that does not have its own owner alias. To be precise, this resets only the decision to create a new queue file, not the decision to override the envelope sender address. The local(8) delivery agent then attempts to deliver local addresses as soon as they come out of child alias expansion. If delivery to any address from child alias expansion fails with a temporary error condition, the entire mailing list may be expanded repeatedly until the mail expires in the queue, resulting in multiple deliveries of the same message to mailing list members. 🫠

resolve_dequoted_address (default: yes) 🔍

Resolve a recipient address safely instead of correctly, by looking inside quotes.

By default, the Postfix address resolver does not quote the address localpart as per RFC 822, so that additional @ or % or ! operators remain visible. This behavior is safe but it is also technically incorrect. 🤷‍♀️

If you specify resolve_dequoted_address = no, then the Postfix resolver will not know about additional @ etc. operators in the address localpart. This opens opportunities for obscure mail relay attacks with user@domain@domain addresses when Postfix provides backup MX service for Sendmail systems. 🚨

resolve_null_domain (default: no) 🕳️

Resolve an address that ends in the @ null domain as if the local hostname were specified, instead of rejecting the address as invalid.

This feature is available in Postfix 2.1 and later. Earlier versions always resolve the null domain as the local hostname.

The Postfix SMTP server uses this feature to reject mail from or to addresses that end in the @ null domain, and from addresses that rewrite into a form that ends in the @ null domain.

resolve_numeric_domain (default: no) 🔢

Resolve user@ipaddress as user@[ipaddress], instead of rejecting the address as invalid.

This feature is available in Postfix 2.3 and later. ⭐

respectful_logging (default: see `postconf -d` output) 🌈

Avoid logging that implies white is better than black. Instead use allowlist, denylist, and variations of those words. 💖

This feature is available in Postfix 3.6 and later.

rewrite_service_name (default: rewrite) ✍️

The name of the address rewriting service. This service rewrites addresses to standard form and resolves them to a (delivery method, next-hop host, recipient) triple.

This feature is available in Postfix 2.0 and later.

sample_directory (default: /etc/postfix) 📁

The name of the directory with example Postfix configuration files. Starting with Postfix 2.1, these files have been replaced with the postconf(5) manual page. 🫶

💌 send_cyrus_sasl_authzid — default: `no`

okay so when you're authenticating to a remote SMTP or LMTP server and this is set to the default no, you send no SASL authoriZation ID (authzid) at all — you send only the SASL authentiCation ID (authcid) plus that authcid's password. clean, minimal, no extra. 💅

The non-default yes switches on the behavior of older Postfix versions. Those always send a SASL authzid that is equal to the SASL authcid — but bestie, that causes interoperability problems with some SMTP servers. 😭 not it.

This feature is available in Postfix 2.4.4 and later. ✨

🚫 sender_based_routing — default: `no`

Do not use this parameter. nope. it's retired. 💀

It was replaced by sender_dependent_relayhost_maps in Postfix version 2.3. like, that's the glow-up, use that one instead.

📋 sender_bcc_maps — default: empty

Optional BCC (blind carbon-copy) address lookup tables, indexed by envelope sender address. The BCC address gets added when mail enters from outside of Postfix. and heads up: multiple results are not supported. one BCC, that's the vibe. 🎀

Specify zero or more type:name lookup tables, separated by whitespace or comma. Tables get searched in the order you listed them, and the search stops as soon as there's a match. 🦋

The table search order goes like this:

Look up the user+extension@domain.tld address, including the optional address extension.
Look up the user@domain.tld address, without the optional address extension.
Look up the user+extension address local part when the sender domain equals $myorigin, $mydestination, $inet_interfaces or $proxy_interfaces.
Look up the user address local part when the sender domain equals $myorigin, $mydestination, $inet_interfaces or $proxy_interfaces.
Look up the @domain.tld part.

Note: with Postfix 2.3 and later the BCC address is added as if it was specified with NOTIFY=NONE. The sender will not be notified when the BCC address is undeliverable, as long as all down-stream software implements RFC 3461. slay.

Note: with Postfix 2.2 and earlier the sender will be notified when the BCC address is undeliverable. ok boomer behavior 🙈

Note: automatic BCC recipients are produced only for new mail. To avoid mailer loops, automatic BCC recipients are not generated after Postfix forwards mail internally, or after Postfix generates mail itself.

Note: automatic BCC recipients are subject to address canonicalization (add missing domain), canonical_maps, masquerade_domains, and virtual_alias_maps.

Example:

sender_bcc_maps = lmdb:/etc/postfix/sender_bcc

Instead of lmdb:, some systems use cdb:, hash:, or dbm:. iykyk 🌸

Execute the command postmap /etc/postfix/sender_bcc after you change the sender_bcc file, to (re)build a default-type indexed file. Execute postmap type:/etc/postfix/sender_bcc to specify an explicit type.

The default indexed file type is configured with the default_database_type parameter. To list available explicit types, execute the command postconf -m. 👑

Configuration changes will become visible after a minute or so. Use postfix reload to eliminate the delay. ⚡

This feature is available in Postfix 2.1 and later.

🎯 sender_canonical_classes — default: `envelope_sender, header_sender`

Which addresses are subject to sender_canonical_maps address mapping. By default, sender_canonical_maps address mapping is applied to envelope sender addresses, and to header sender addresses. both. iconic. 💖

Specify one or more of: envelope_sender, header_sender

This feature is available in Postfix 2.2 and later.

🪞 sender_canonical_maps — default: empty

Optional address mapping lookup tables for envelope and header sender addresses. The table format and lookups are documented in canonical(5). 📖

Example: you want to rewrite the SENDER address user@ugly.example to user@pretty.example, while still being able to send mail to the RECIPIENT address user@ugly.example. glow-up the sender only, periodt. ✨

Note: $sender_canonical_maps is processed before $canonical_maps. order matters bestie 🫶

Example:

sender_canonical_maps = lmdb:/etc/postfix/sender_canonical

Instead of lmdb:, some systems use cdb:, hash:, or dbm:.

Execute the command postmap /etc/postfix/sender_canonical after you change the sender_canonical file, to (re)build a default-type indexed file. Execute postmap type:/etc/postfix/sender_canonical to specify an explicit type.

The default indexed file type is configured with the default_database_type parameter. To list available explicit types, execute the command postconf -m. 🌈

Configuration changes will become visible after a minute or so. Use postfix reload to eliminate the delay.

🚚 sender_dependent_default_transport_maps — default: empty

A sender-dependent override for the global default_transport parameter setting. The tables are searched by the envelope sender address and @domain. A lookup result of DUNNO terminates the search without overriding the global default_transport parameter setting. This information is overruled with the transport(5) table. the transport table is the main character here, fr fr 👑

This setting affects only the default domain address class (recipient domains that do not match $mydestination, $inet_interfaces, $proxy_interfaces, $virtual_alias_domains, $virtual_mailbox_domains, or $relay_domains):

In order of decreasing precedence, the delivery transport is taken from 1) $transport_maps, 2) $sender_dependent_default_transport_maps or $default_transport.
In order of decreasing precedence, the nexthop destination is taken from 1) $transport_maps, 2) $sender_dependent_default_transport_maps or $default_transport, 3) $sender_dependent_relayhost_maps or $relayhost or the recipient domain.

Note: this overrides default_transport, not transport_maps, and therefore the expected syntax is that of default_transport, not the syntax of transport_maps. Specifically, this does not support the transport_maps syntax for null transport, null nexthop, or null email addresses. ⚠️ read that twice bestie

Specify zero or more type:name lookup tables, separated by whitespace or comma. Tables will be searched in the specified order until a match is found. 🦋

For safety reasons, this feature does not allow $number substitutions in regular expression maps. 🔒

This feature is available in Postfix 2.7 and later.

📬 sender_dependent_relayhost_maps — default: empty

A sender-dependent override for the global relayhost parameter setting. The tables are searched by the envelope sender address and @domain. A lookup result of DUNNO terminates the search without overriding the global relayhost parameter setting (Postfix 2.6 and later). 🙅‍♀️

In order of decreasing precedence:

For recipient domains in the relay domain address class (domains matching $relay_domains), the nexthop destination is taken from 1) $transport_maps, 2) $relay_transport, 3) $sender_dependent_relayhost_maps or $relayhost or the recipient domain.
For recipient domains in the default domain address class (domains that do not match mydestination, $inet_interfaces, $proxy_interfaces, $virtual_alias_domains, $virtual_mailbox_domains, $relay_domains), the nexthop destination is taken from 1) $transport_maps, 2) $sender_dependent_default_transport_maps or $default_transport, 3) $sender_dependent_relayhost_maps or $relayhost or the recipient domain.

Specify zero or more type:name lookup tables, separated by whitespace or comma. Tables will be searched in the specified order until a match is found. ✨

For safety reasons, this feature does not allow $number substitutions in regular expression maps. 🔒

This feature is available in Postfix 2.3 and later.

🛠️ sendmail_fix_line_endings — default: `always`

Controls how the Postfix sendmail command converts email message line endings from <CR><LF> into UNIX format (<LF>). little line-ending makeover, cute 🌸

always — Always convert message lines ending in <CR><LF>. This setting is the default with Postfix 2.9 and later.
strict — Convert message lines ending in <CR><LF> only if the first input line ends in <CR><LF>. This setting is backwards-compatible with Postfix 2.8 and earlier.
never — Never convert message lines ending in <CR><LF>. This setting exists for completeness only. (like, it's just there. it's giving "i'm in the options list for the plot" 💀)

This feature is available in Postfix 2.9 and later.

📮 sendmail_path — default: see `postconf -d` output

A Sendmail compatibility feature that specifies the location of the Postfix sendmail(1) command. This command can be used to submit mail into the Postfix queue. 🫶

🏷️ service_name — read-only

The master.cf service name of a Postfix daemon process. This can be used to distinguish the logging from different services that use the same program name. so your logs know who's who 💅

Example master.cf entries:

# Distinguish inbound MTA logging from submission and submissions logging.
smtp      inet  n       -       n       -       -       smtpd
submission inet n       -       n       -       -       smtpd
    -o syslog_name=postfix/$service_name
submissions inet n      -       n       -       -       smtpd
    -o syslog_name=postfix/$service_name

# Distinguish outbound MTA logging from inbound relay logging.
smtp      unix  -       -       n       -       -       smtp
relay     unix  -       -       n       -       -       smtp
    -o syslog_name=postfix/$service_name

This feature is available in Postfix 3.3 and later. ✨

⏳ service_throttle_time — default: `60s`

How long the Postfix master(8) waits before forking a server that appears to be malfunctioning. sir, you need a minute. 🧘‍♀️

🔐 setgid_group — default: `postdrop`

The group ownership of set-gid Postfix commands and of group-writable Postfix directories. When this parameter value is changed you need to re-run postfix set-permissions (with Postfix version 2.0 and earlier: /etc/postfix/post-install set-permissions).

don't forget the re-run, bestie, otherwise your permissions are just sitting there all wrong 😭🙈

🌸 `shlib_directory` 🌸 (default: see `postconf -d` output)

okay so this one is where your Postfix dynamically-linked libraries live — we're talking the libpostfix-*.so files. It's also the default hangout spot for Postfix database plugins (postfix-*.so) that have a relative pathname in the dynamicmaps.cf file. 📚

Now the default is a lil ✨version-dependent✨ situation: shlib_directory defaults to "no" when Postfix dynamically-linked libraries and database plugins are disabled at compile time, otherwise it typically defaults to /usr/lib/postfix or /usr/local/lib/postfix. Bestie, it literally depends on how you built it. 💅

Notes, because there are always notes:

🚨 The directory you point shlib_directory at should contain only Postfix-related files. Like, only. Postfix dynamically-linked libraries and database plugins should not be installed in a "public" system directory such as /usr/lib or /usr/local/lib. Linking Postfix dynamically-linked library files or database plugins into non-Postfix programs is not supported. Why? Because Postfix dynamically-linked libraries and database plugins implement a Postfix-internal API that changes without maintaining compatibility. It's giving "private group chat, not a public forum" energy. 🙈
🛠️ You can change the shlib_directory value after Postfix is built. However, you may have to run ldconfig or equivalent to prevent Postfix programs from failing because the libpostfix-*.so files are not found. No ldconfig command is needed if you keep the libpostfix-*.so files in the compiled-in default $shlib_directory location. Slay, low effort. 👑

This feature is available in Postfix 3.0 and later.

💖 `show_user_unknown_table_name` 💖 (default: yes)

So this one controls whether you display the name of the recipient table in the "User unknown" responses. 🕵️‍♀️

The extra detail makes troubleshooting easier — but it also reveals information that is nobody else's business. Like, hi, why is the whole internet in my business?? 😭 Your call, bestie. Privacy vs. convenience, the eternal vibe check.

This feature is available in Postfix 2.0 and later.

🎀 `showq_service_name` 🎀 (default: showq)

The name of the showq(8) service. 📬 This service produces mail queue status reports. That's it, that's the whole thing. Short and iconic. ✨

This feature is available in Postfix 2.0 and later.

🌈 `smtp_address_preference` 🌈 (default: any)

This is the address type ("ipv6", "ipv4" or "any") that the Postfix SMTP client will try first, when a destination has IPv6 and IPv4 addresses with equal MX preference. 🏁

Heads up: this feature has no effect unless the inet_protocols setting enables both IPv4 and IPv6. So like, don't expect magic if you only turned on one of them. 🙅‍♀️

Also, the Postfix SMTP client address preference has evolved, periodt. With Postfix 2.8 the default is "ipv6"; earlier implementations are hard-coded to prefer IPv6 over IPv4. Glow-up energy. 🦋

Notes for mail delivery between sites that have both IPv4 and IPv6 connectivity:

💀 The setting "smtp_address_preference = ipv6" is unsafe. All deliveries will suffer delays during an IPv6 outage, even while the destination is still reachable over IPv4. And it gets worse: mail may be stuck in the queue with Postfix versions < 3.3 that do not implement "smtp_balance_inet_protocols". For similar reasons, the setting "smtp_address_preference = ipv4" is also unsafe. Not me picking a favorite, they're both risky. 😬
✅ The setting "smtp_address_preference = any" is safe. With this, and "smtp_balance_inet_protocols = yes" (the default), only half of deliveries will suffer delays if there is an outage that affects IPv6 or IPv4, as long as it does not affect both. Half the drama, we love to see it. 🫶
🚫 The setting "smtp_address_preference = ipv4" is not a solution for remote servers that flag email received over IPv6 as more 'spammy' (the client IPv6 address has a bad or missing PTR or AAAA record, bad network neighbors, etc.). Instead, configure Postfix to receive mail over both IPv4 and IPv6, and to deliver mail over only IPv4. Like so:

/etc/postfix/main.cf:
    inet_protocols = all

/etc/postfix/master.cf
    smtp ...other fields... smtp -o inet_protocols=ipv4

This feature is available in Postfix 2.8 and later.

🔥 `smtp_address_verify_target` 🔥 (default: rcpt)

In the context of email address verification, this is the SMTP protocol stage that determines whether an email address is deliverable. 🎯 Specify one of "rcpt" or "data". The latter is needed with remote SMTP servers that reject recipients after the DATA command. Rude of them, honestly, but okay. 🙄

Use transport_maps to apply this feature selectively:

/etc/postfix/main.cf:
    transport_maps = lmdb:/etc/postfix/transport

/etc/postfix/transport:
    smtp-domain-that-verifies-after-data    smtp-data-target:
    lmtp-domain-that-verifies-after-data    lmtp-data-target:

/etc/postfix/master.cf:
    smtp-data-target    unix    -    -    n    -    -    smtp
        -o smtp_address_verify_target=data
    lmtp-data-target    unix    -    -    n    -    -    lmtp
        -o lmtp_address_verify_target=data

Instead of lmdb:, some systems use cdb:, hash:, or dbm:. Different strokes for different hosts. 💁‍♀️

Unselective use of the "data" target does no harm, but will result in unnecessary "lost connection after DATA" events at remote SMTP/LMTP servers. Extra noise in your logs = extra noise in your life. 🙈

Run the command postmap /etc/postfix/transport after you change the transport file, to (re)build a default-type indexed file. Run postmap type:/etc/postfix/transport to specify an explicit type. 🔨

The default indexed file type is configured with the default_database_type parameter. To list available explicit types, execute the command postconf -m. 📋

Configuration changes will become visible after a minute or so. Use postfix reload to eliminate the delay. ⏱️ (Patience is a virtue but reload is faster, fr fr.)

This feature is available in Postfix 3.0 and later.

✨ `smtp_always_send_ehlo` ✨ (default: yes)

Always send EHLO at the start of an SMTP session. Hi bestie, hello, hi. 👋

With "smtp_always_send_ehlo = no", the Postfix SMTP client sends EHLO only when the word "ESMTP" appears in the server greeting banner. Like this:

220 spike.porcupine.org ESMTP Postfix

That's the little vibe check before it commits. 💅

👑 `smtp_balance_inet_protocols` 👑 (default: yes)

When a remote destination resolves to a combination of IPv4 and IPv6 addresses, this makes sure the Postfix SMTP client can try both address types before it runs into the smtp_mx_address_limit. 🧚

This avoids an interoperability problem when a destination resolves to primarily IPv6 addresses, the smtp_address_limit feature eliminates most or all IPv4 addresses, and the destination is not reachable over IPv6. Disaster avoided, ate that. 🍽️

This feature is available in Postfix 3.3 and later.

💜 `smtp_bind_address` 💜 (default: empty)

An optional numerical network address that the Postfix SMTP client should bind to when making an IPv4 connection. 🔒

This can be specified in the main.cf file for all SMTP clients, or it can be specified in the master.cf file for a specific client, for example:

/etc/postfix/master.cf:
    smtp ... smtp -o smtp_bind_address=11.22.33.44

See smtp_bind_address_enforce for how Postfix should handle errors (Postfix 3.7 and later).

Note 1: when inet_interfaces specifies no more than one IPv4 address, and that address is a non-loopback address, it is automatically used as the smtp_bind_address. This supports virtual IP hosting, but can be a problem on multi-homed firewalls. See the inet_interfaces documentation for more detail. 🧐

Note 2: address information may be enclosed inside [], but this form is not required here.

🦋 `smtp_bind_address6` 🦋 (default: empty)

An optional numerical network address that the Postfix SMTP client should bind to when making an IPv6 connection. The sequel, but better. ✨

This feature is available in Postfix 2.2 and later.

This can be specified in the main.cf file for all SMTP clients, or it can be specified in the master.cf file for a specific client, for example:

/etc/postfix/master.cf:
    smtp ... smtp -o smtp_bind_address6=1:2:3:4:5:6:7:8

See smtp_bind_address_enforce for how Postfix should handle errors (Postfix 3.7 and later).

Note 1: when inet_interfaces specifies no more than one IPv6 address, and that address is a non-loopback address, it is automatically used as the smtp_bind_address6. This supports virtual IP hosting, but can be a problem on multi-homed firewalls. See the inet_interfaces documentation for more detail. 🧐

Note 2: address information may be enclosed inside [], but this form is not recommended here. (Different from its IPv4 sibling, iykyk.)

🍓 `smtp_bind_address_enforce` 🍓 (default: no)

Defer delivery when the Postfix SMTP client cannot apply the smtp_bind_address or smtp_bind_address6 setting. 😤

By default, the Postfix SMTP client will continue delivery after logging a warning. So like, "noted, moving on" energy. If you want it to actually stop and think about it, flip this on.

This feature is available in Postfix 3.7 and later.

🌸 `smtp_body_checks` 🌸 (default: empty)

Restricted body_checks(5) tables for the Postfix SMTP client. 📝 These tables are searched while mail is being delivered.

Important caveat: actions that change the delivery time or destination are not available here. So keep those expectations in check, bestie.

This feature is available in Postfix 2.5 and later.

⭐ `smtp_cname_overrides_servername` ⭐ (default: version dependent)

When the remote SMTP servername is a DNS CNAME, this replaces the servername with the result from CNAME expansion for the purpose of logging, SASL password lookup, TLS policy decisions, or TLS certificate verification. 🔍

The value "no" hardens Postfix smtp_tls_per_site hostname-based policies against false hostname information in DNS CNAME records, and makes SASL password file lookups more predictable. This is the default setting as of Postfix 2.3.

This feature is available in Postfix 2.2.9 and later, deprecated as of Postfix 3.11. ⚠️ Yes, deprecated, we said what we said.

🧚 `smtp_connect_timeout` 🧚 (default: 30s)

The Postfix SMTP client time limit for completing a TCP connection, or zero (use the operating system built-in time limit). ⏳

When no connection can be made within the deadline, the Postfix SMTP client tries the next address on the mail exchanger list. Specify 0 to disable the time limit (i.e. use whatever timeout is implemented by the operating system). No cap, the OS decides. 💀

Specify a non-negative time value (an integral value plus an optional one-letter suffix that specifies the time unit). Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). The default time unit is s (seconds). 🕰️

`smtp_connection_cache_destinations` (default: empty)

Okay bestie, this one is about keeping the door open instead of slamming it shut every single time 💅 Permanently turn on SMTP connection caching for the destinations you name. What does caching even mean here? With SMTP connection caching, a connection does not get closed right after a mail transaction finishes. Nope — instead, the connection is kept open for up to $smtp_connection_cache_time_limit seconds. That way the same connection can be reused for other deliveries, and mail delivery performance can get so much better. slay

Give it a comma or white space separated list of destinations, or pseudo-destinations:

if mail is sent without a relay host: a domain name (that's the right-hand side of an email address, without the [] around a numeric IP address),
if mail is sent via a relay host: a relay host name (without [] or non-default TCP port), as specified in main.cf or in the transport map,
if mail is sent via a UNIX-domain socket: a pathname (without the unix: prefix),
a /file/name with domain names and/or relay host names as defined above,
a "type:table" with domain names and/or relay host names on the left-hand side. The right-hand side result from "type:table" lookups is ignored 🫶

This feature is available in Postfix 2.2 and later.

`smtp_connection_cache_on_demand` (default: yes)

This one is the "only when it's busy" version ✨ Temporarily enable SMTP connection caching while a destination has a high volume of mail in the active queue. Same deal as before: with SMTP connection caching, a connection is not closed immediately after completion of a mail transaction — it's kept open for up to $smtp_connection_cache_time_limit seconds, so connections can be reused for other deliveries and mail delivery performance can improve.

This feature is available in Postfix 2.2 and later.

`smtp_connection_cache_time_limit` (default: 2s)

When SMTP connection caching is on, this is how long an unused SMTP client socket is kept open before it gets closed. 🕐

Do not specify larger values without permission from the remote sites. Like, actual permission. From the actual people. fr fr.

This feature is available in Postfix 2.2 and later.

`smtp_connection_reuse_count_limit` (default: 0)

When SMTP connection caching is on, this is the number of times an SMTP session may be reused before it's closed — or zero, which means no limit at all. 🌈 With a reuse count limit of N, a connection is used up to N+1 times.

NOTE: This feature is unsafe. Here's why, and it's giving chaos 😭: when a high-volume destination has multiple inbound MTAs, the slowest inbound MTA will attract the most connections to that destination. This limitation does not exist with the smtp_connection_reuse_time_limit feature.

This feature is available in Postfix 2.11.

`smtp_connection_reuse_time_limit` (default: 300s)

Bestie, this one has lore. Sit down, hydrate, it's a whole story 🍓

This is the amount of time during which Postfix will use an SMTP connection repeatedly. The timer starts when the connection is initiated — so it includes the connect, greeting and helo latency, plus the latencies of subsequent mail delivery transactions. ⏱️

This feature addresses a performance stability problem with remote SMTP servers. And no, it's not a Postfix-specific thing: it can happen when any MTA sends large amounts of SMTP email to a site that has multiple MX hosts.

The problem starts when one of a set of MX hosts becomes slower than the rest. Even though SMTP clients connect to fast and slow MX hosts with equal probability, the slow MX host ends up with more simultaneous inbound connections than the faster MX hosts, because the slow MX host needs more time to serve each client request. 💀

The slow MX host becomes a connection attractor. If one MX host becomes N times slower than the rest, it dominates mail delivery latency unless there are more than N fast MX hosts to counter the effect. And if the number of MX hosts is smaller than N, the mail delivery latency becomes effectively that of the slowest MX host divided by the total number of MX hosts.

The solution uses connection caching in a way that differs from Postfix version 2.2. By limiting the amount of time during which a connection can be used repeatedly (instead of limiting the number of deliveries over that connection), Postfix not only restores fairness in the distribution of simultaneous connections across a set of MX hosts, it also favors deliveries over connections that perform well — which is exactly what we want. 👑

The default reuse time limit, 300s, is comparable to the various smtp transaction timeouts, which are fair estimates of maximum excess latency for a slow delivery. Note that hosts may accept thousands of messages over a single connection within the default connection reuse time limit. This number is much larger than the default Postfix version 2.2 limit of 10 messages per cached connection. It may prove necessary to lower the limit to avoid interoperability issues with MTAs that exhibit bugs when many messages are delivered via a single connection. A lower reuse time limit risks losing the benefit of connection reuse when the average connection and mail delivery latency exceeds the reuse time limit.

This feature is available in Postfix 2.3 and later.

`smtp_data_done_timeout` (default: 600s)

The Postfix SMTP client time limit for sending the SMTP ., and for receiving the remote SMTP server response. 📨

When no response is received within the deadline, a warning is logged that the mail may be delivered multiple times. (yeah. multiple times. beware 👀)

`smtp_data_init_timeout` (default: 120s)

The Postfix SMTP client time limit for sending the SMTP DATA command, and for receiving the remote SMTP server response. ✨

Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). The default time unit is s (seconds).

`smtp_data_xfer_timeout` (default: 180s)

The Postfix SMTP client time limit for sending the SMTP message content. When the connection makes no progress for more than $smtp_data_xfer_timeout seconds, the Postfix SMTP client terminates the transfer. no progress, no patience, bye 💅

Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). The default time unit is s (seconds).

`smtp_defer_if_no_mx_address_found` (default: no)

Defer mail delivery when no MX record resolves to an IP address. 🛑

The default (no) is to return the mail as undeliverable. With older Postfix versions, the default was to keep trying to deliver the mail until someone fixed the MX record or until the mail was too old.

Note: the Postfix SMTP client always ignores MX records with equal or worse preference than the local MTA itself. <gray>always always.</gray>

This feature is available in Postfix 2.1 and later.

`smtp_delivery_status_filter` (default: `$default_delivery_status_filter`)

An optional filter for the smtp(8) delivery agent to change the delivery status code or explanatory text of successful or unsuccessful deliveries. See default_delivery_status_filter for the deets. 🫶

NOTE: This feature modifies Postfix SMTP client error or non-error messages that may or may not be derived from remote SMTP server responses. In contrast, the smtp_reply_filter feature modifies remote SMTP server responses only. iykyk 💜

`smtp_destination_concurrency_limit` (default: `$default_destination_concurrency_limit`)

The maximal number of parallel deliveries to the same destination via the smtp message delivery transport. This limit is enforced by the queue manager. The message delivery transport name is the first field in the entry in the master.cf file. 🔥

`smtp_destination_recipient_limit` (default: `$default_destination_recipient_limit`)

The maximal number of recipients per message for the smtp message delivery transport. This limit is enforced by the queue manager. The message delivery transport name is the first field in the entry in the master.cf file.

Setting this parameter to a value of 1 changes the meaning of smtp_destination_concurrency_limit from concurrency per domain into concurrency per recipient. plot twist ✨

`smtp_discard_ehlo_keyword_address_maps` (default: empty)

Lookup tables, indexed by the remote SMTP server address, with case insensitive lists of EHLO keywords (pipelining, starttls, auth, etc.) that the Postfix SMTP client will ignore in the EHLO response from a remote SMTP server. See smtp_discard_ehlo_keywords for the details. The table is not indexed by hostname, for consistency with smtpd_discard_ehlo_keyword_address_maps. 🌸

Specify zero or more "type:name" lookup tables, separated by whitespace or comma. Tables will be searched in the specified order until a match is found.

This feature is available in Postfix 2.2 and later.

`smtp_discard_ehlo_keywords` (default: empty)

A case insensitive list of EHLO keywords (pipelining, starttls, auth, etc.) that the Postfix SMTP client will ignore in the EHLO response from a remote SMTP server. ignore them, they're not the vibe 🚫

This feature is available in Postfix 2.2 and later.

Notes:

Specify the silent-discard pseudo keyword to prevent this action from being logged. 🤫
Use the smtp_discard_ehlo_keyword_address_maps feature to discard EHLO keywords selectively.

`smtp_dns_reply_filter` (default: empty)

okay so this one is literally a filter for Postfix SMTP client DNS lookup results 💅 bestie, you get to peek at what DNS said back and go "hmm, no 💀". You can give it zero or more lookup tables, and they get searched in the order you wrote them for a match with the DNS lookup result — which first gets converted into this exact form:

name ttl class type preference value

Some deets on that little line, so you're not confused:

the class field is always "IN"
the preference field exists only for MX records
names of hosts, domains, etc. end in "." (yes, the trailing dot is real, it's giving FQDN energy ✨)
and those names are in ASCII form (the xn--mumble form, in the case of UTF8 names)

When a match is found, the table lookup result specifies an action. By default, the table query and the action name are case-insensitive. Currently, only the IGNORE action is implemented — so that's your one move, periodt 💅

Notes:

Postfix DNS reply filters have no effect on implicit DNS lookups through nsswitch.conf or equivalent mechanisms 🙈 (so don't come for me when those still go through, they're not invited to this party)
The Postfix SMTP/LMTP client uses smtp_dns_reply_filter and lmtp_dns_reply_filter only to discover a remote SMTP or LMTP service (record types MX, A, AAAA, and TLSA). These lookups are also made to implement the features reject_unverified_sender and reject_unverified_recipient.
The Postfix SMTP/LMTP client defers mail delivery when a filter removes all lookup results from a successful query 😭
Postfix SMTP server uses smtpd_dns_reply_filter only to look up MX, A, AAAA, and TXT records to implement the features reject_unknown_helo_hostname, reject_unknown_sender_domain, reject_unknown_recipient_domain, reject_rbl_*, and reject_rhsbl_*.
The Postfix SMTP server logs a warning or defers mail delivery when a filter removes all lookup results from a successful query.

Example: ignore Google AAAA records in Postfix SMTP client DNS lookups, because Google sometimes hard-rejects mail from IPv6 clients with valid PTR etc. records. (ngl this one's iconic 🔥)

/etc/postfix/main.cf:
    smtp_dns_reply_filter = pcre:/etc/postfix/smtp_dns_reply_filter

/etc/postfix/smtp_dns_reply_filter:
    # /domain ttl IN AAAA address/ action, all case-insensitive.
    # Note: the domain name ends in ".".
    /^\S+\.google\.com\.\s+\S+\s+\S+\s+AAAA\s+/ IGNORE

This feature is available in Postfix 3.0 and later. 🦋

`smtp_dns_resolver_options` (default: empty)

DNS Resolver options for the Postfix SMTP client, bestie 🧚 Specify zero or more of the following options, separated by comma or whitespace. kinda important: option names are case-sensitive 👀 Some options refer to domain names that are specified in the file /etc/resolv.conf or equivalent.

res_defnames — Append the current domain name to single-component names (those that do not contain a "." character). This can produce incorrect results, and is the hard-coded behavior prior to Postfix 2.8. 💀
res_dnsrch — Search for host names in the current domain and in parent domains. This can produce incorrect results and is therefore not recommended 🙅‍♀️

This feature is available in Postfix 2.8 and later.

`smtp_dns_support_level` (default: empty)

Level of DNS support in the Postfix SMTP client, and this one has lore okay. With "smtp_dns_support_level" left at its empty default value, the legacy "disable_dns_lookups" parameter controls whether DNS is enabled in the Postfix SMTP client — otherwise the legacy parameter is ignored 👑

Specify one of the following:

disabled — Disable DNS lookups. No MX lookups are performed and hostname to address lookups are unconditionally "native". This setting is not appropriate for hosts that deliver mail to the public Internet 🚫. Some obsolete how-to documents recommend disabling DNS lookups in some configurations with content_filters. This is no longer required and strongly discouraged — like, put that down, bestie.
enabled — Enable DNS lookups. Nexthop destination domains not enclosed in "[]" will be subject to MX lookups. If "dns" and "native" are included in the "smtp_host_lookup" parameter value, DNS will be queried first to resolve MX-host A records, followed by "native" lookups if no answer is found in DNS.
dnssec — Enable DNSSEC lookups. The "dnssec" setting differs from the "enabled" setting above in the following ways:
- Any MX lookups will set RES_USE_DNSSEC and RES_USE_EDNS0 to request DNSSEC-validated responses. If the MX response is DNSSEC-validated the corresponding hostnames are considered validated ✨
- The address lookups of validated hostnames are also validated, (provided of course "smtp_host_lookup" includes "dns", see below).
- Temporary failures in DNSSEC-enabled hostname-to-address resolution block any "native" lookups. Additional "native" lookups only happen when DNSSEC lookups hard-fail (NODATA or NXDOMAIN).

The Postfix SMTP client considers non-MX "[nexthop]" and "[nexthop]:port" destinations equivalent to statically-validated MX records of the form "nexthop. IN MX 0 nexthop." Therefore, with "dnssec" support turned on, validated hostname-to-address lookups apply to the nexthop domain of any "[nexthop]" or "[nexthop]:port" destination. This is also true for LMTP "inet:host" and "inet:host:port" destinations, as LMTP hostnames are never subject to MX lookups.

The "dnssec" setting is recommended only if you plan to use the dane or dane-only TLS security level — otherwise enabling DNSSEC support in Postfix offers no additional security. Postfix DNSSEC support relies on an upstream recursive nameserver that validates DNSSEC signatures. Such a DNS server will always filter out forged DNS responses, even when Postfix itself is not configured to use DNSSEC.

When using Postfix DANE support the "smtp_host_lookup" parameter should include "dns", as DANE is not applicable to hosts resolved via "native" lookups.

As mentioned above, Postfix is not a validating stub resolver; it relies on the system's configured DNSSEC-validating recursive nameserver to perform all DNSSEC validation. Since this nameserver's DNSSEC-validated responses will be fully trusted, it is strongly recommended that the MTA host have a local DNSSEC-validating recursive caching nameserver listening on a loopback address, and be configured to use only this nameserver for all lookups. Otherwise, Postfix may remain subject to man-in-the-middle attacks that forge responses from the recursive nameserver 😱💀

DNSSEC support requires a version of Postfix compiled against a reasonably-modern resolver(3) library that implements the RES_USE_DNSSEC and RES_USE_EDNS0 resolver options.

This feature is available in Postfix 2.11 and later.

`smtp_enforce_tls` (default: no)

Enforcement mode, bestie — this one does not play 🫶 require that remote SMTP servers use TLS encryption, and never send mail in the clear. This also requires that the remote SMTP server hostname matches the information in the remote server certificate, and that the remote SMTP server certificate was issued by a CA that is trusted by the Postfix SMTP client. If the certificate doesn't verify or the hostname doesn't match, delivery is deferred and mail stays in the queue 📬 (it's waiting, it's patient, it's not going anywhere).

The server hostname is matched against all names provided as dNSNames in the SubjectAlternativeName. If no dNSNames are specified, the CommonName is checked. The behavior may be changed with the smtp_tls_enforce_peername option.

This option is useful only if you are definitely sure that you will only connect to servers that support RFC 2487 _and_ that provide valid server certificates. Typical use is for clients that send all their email to a dedicated mailhub.

This feature is available in Postfix 2.2 and later. With Postfix 2.3 and later use smtp_tls_security_level instead 👑 (yes that's the glow-up, use the new one).

`smtp_fallback_relay` (default: `$fallback_relay`)

Optional list of relay destinations that will be used when an SMTP destination is not found, or when delivery fails due to a non-permanent error. With Postfix 2.2 and earlier this parameter is called fallback_relay (throwback name, honestly kinda cute 💜).

By default, smtp_fallback_relay is empty, mail is returned to the sender when a destination is not found, and delivery is deferred after it fails due to a non-permanent error.

With bulk email deliveries, it can be beneficial to run the fallback relay MTA on the same host, so that it can reuse the sender IP address. This speeds up deliveries that are delayed by IP-based reputation systems (greylist, etc.) 🔥

The fallback relays must be SMTP destinations. Specify a domain, host, host:port, [host]:port, [address] or [address]:port; the form [host] turns off MX lookups. If you specify multiple SMTP destinations, Postfix will try them in the specified order.

To prevent mailer loops between MX hosts and fall-back hosts, Postfix version 2.2 and later will not use the fallback relays for destinations that it is MX host for (assuming DNS lookup is turned on) 🙅‍♀️

`smtp_generic_maps` (default: empty)

Optional lookup tables that perform address rewriting in the Postfix SMTP client — typically to transform a locally valid address into a globally valid address when sending mail across the Internet ✨ This is needed when the local machine does not have its own Internet domain name, but uses something like localdomain.local instead. (we've all been there, no shame.)

Specify zero or more "type:name" lookup tables, separated by whitespace or comma. Tables will be searched in the specified order until a match is found.

The table format and lookups are documented in generic(5); examples are shown in the ADDRESS_REWRITING_README and STANDARD_CONFIGURATION_README documents.

This feature is available in Postfix 2.2 and later.

`smtp_header_checks` (default: empty)

Restricted header_checks(5) tables for the Postfix SMTP client 🎀 These tables are searched while mail is being delivered. Heads up bestie: actions that change the delivery time or destination are not available here 🚫

This feature is available in Postfix 2.5 and later.

`smtp_helo_name` (default: `$myhostname`)

The hostname to send in the SMTP HELO or EHLO command 👋 your little "hi, it's me" to the other server.

The default value is the machine hostname. Specify a hostname or [ip.add.re.ss].

This information can be specified in the main.cf file for all SMTP clients, or it can be specified in the master.cf file for a specific client, for example:

/etc/postfix/master.cf:
    mysmtp ... smtp -o smtp_helo_name=foo.bar.com

This feature is available in Postfix 2.0 and later.

`smtp_helo_timeout` (default: 300s)

The Postfix SMTP client time limit for sending the HELO or EHLO command, and for receiving the initial remote SMTP server response ⏰ (so it's a two-for-one timeout, efficient queen).

Specify a non-zero time value (an integral value plus an optional one-letter suffix that specifies the time unit). Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). The default time unit is s (seconds) 💅

💖 smtp_host_lookup (default: `dns`)

okay so this one is literally about how the Postfix SMTP client goes looking for a host's IP address — like, which mechanism does it use, bestie. lowkey important.

Heads up though — this whole parameter gets ignored when DNS lookups are disabled (peep disable_dns_lookups and smtp_dns_support_level).

And the tea ☕: the dns mechanism is always tried before native if you list both of them.

Specify one of these:

dns — hosts can be found in the DNS (this is the preferred one, queen behavior 👑)
native — use the native naming service only (nsswitch.conf, or an equivalent mechanism)
dns, native — use the native service for hosts that aren't found in the DNS

This feature is available in Postfix 2.1 and later. ✨

✂️ smtp_line_length_limit (default: `998`)

the maximal length of message header and body lines that Postfix will send via SMTP. and no, this limit does not include the <CR><LF> at the end of each line, bestie — it's just the line itself.

Longer lines get broken by inserting "<CR><LF><SPACE>", so we minimize the damage to MIME formatted mail. 💅

Specify zero to disable this limit entirely.

The Postfix limit of 998 characters not including <CR><LF> is consistent with the SMTP limit of 1000 characters including <CR><LF>. and fun fact: the Postfix limit was 990 with Postfix 2.8 and earlier. glow-up tbh 📈

📝 smtp_log_tls_feature_status (default: `yes`)

Enable logging of TLS feature information in delivery status logging. This summarizes how features such as TLS and REQUIRETLS were used. A list of examples is at the end of this text. ✨

The logging is inserted between the "delays=a/b/c/d" and the "dsn=x.y.z, status=..." information.
The general format is "tls=feature/feature/...". See below for examples.
The first feature name is the TLS security level: 'none', 'may', 'encrypt', etc. Other features are shown only if activated. The REQUIRETLS extension's feature name is 'requiretls'.
When a ':downgrade-level' is appended to a feature name, the feature was downgraded to the indicated level. A downgrade-level none indicates that the feature was unavailable. The result of a downgrade may violate a strict policy, but may still be compliant with a permissive policy.
When "!" is prepended to a feature, the policy for that feature was violated and the connection was not used. 💀
When "?" is appended to a feature, the policy for that feature was undecided. This is typically the result of a lost connection or an incorrect configuration.

Examples for TLS security levels 🧚

tls=none — A connection with TLS disabled.
tls=may — Opportunistic TLS. The connection was used after a successful TLS handshake.
tls=may? — Opportunistic TLS. The status was undecided because no connection was made, or no server could be reached.
tls=may:none — Opportunistic TLS. The client was willing to use TLS, but the remote server did not support STARTTLS, and the connection was used in plaintext as permitted by the opportunistic TLS policy.
tls=dane — DANE policy compliant, no downgrade.
tls=dane:halfdane — Opportunistic DANE. The connection security was downgraded to 'halfdane' to indicate that mail server records were not DNSSEC-signed.
tls=dane:encrypt — Opportunistic DANE. The connection security was downgraded to 'encrypt' because none of the TLSA records were usable.
tls=dane? — DANE policy status was undecided, because the connection failed before or in the TLS handshake.

Examples for REQUIRETLS policies 🌈

(set with smtp_requiretls_policy), where "xxx" is a TLS security level:

tls=xxx/requiretls — 'Enforce' policy compliant. After a successful TLS handshake that required a certificate match, the remote server announced REQUIRETLS support, and the client sent REQUIRETLS.
tls=xxx/!requiretls:nocertmatch — 'Enforce' policy violation. The connection was not used because the remote server certificate did not match as required by the TLS security policy, or no connection was made because the TLS security policy disabled server certificate matching.
tls=xxx/requiretls:nocertmatch — 'Opportunistic+starttls' or 'opportunistic' policy compliant. After a successful TLS handshake that did not require a server certificate match, the remote server announced REQUIRETLS support, and the client sent REQUIRETLS.
tls=xxx/!requiretls:nostarttls — 'Enforce' or 'opportunistic+starttls' policy violation. The connection was not used because the remote server did not support STARTTLS.
tls=xxx/!requiretls:noencryption — 'Enforce' or 'opportunistic+starttls' policy violation. No connection was made because the TLS security policy disabled encryption.
tls=xxx/!requiretls:none — 'Enforce' policy violation. After a successful TLS handshake, the connection was not used because the remote server did not support REQUIRETLS.
tls=xxx/requiretls:none — 'Opportunistic+starttls' policy compliant. After a successful TLS handshake, the remote server did not announce REQUIRETLS support, and the connection was used without sending REQUIRETLS.
tls=xxx/requiretls:none — 'Opportunistic' policy compliant. The remote server did not announce support for STARTTLS or REQUIRETLS, and the connection was used without sending REQUIRETLS.
tls=xxx/requiretls? — Policy status was undecided, because the connection failed before or in the TLS handshake, or no connection was made due to a policy configuration error.

This feature is available in Postfix 3.11 and later. 🎀

⏰ smtp_mail_timeout (default: `300s`)

The Postfix SMTP client time limit for sending the MAIL FROM command, and for receiving the remote SMTP server response. like, the whole vibe has a deadline bestie ⏳

🩷 smtp_mime_header_checks (default: empty)

Restricted mime_header_checks(5) tables for the Postfix SMTP client. These tables are searched while mail is being delivered. Actions that change the delivery time or destination are not available. 🙅‍♀️

This feature is available in Postfix 2.5 and later.

🚀 smtp_min_data_rate (default: `500`)

The minimum plaintext data transfer rate in bytes/second for DATA requests, when deadlines are enabled with smtp_per_request_deadline.

here's the math, bestie 🧮 — after a write operation transfers N plaintext message bytes (possibly after TLS encryption), and after the DATA request deadline is decremented by the elapsed time of that write operation, the DATA request deadline is incremented by N/smtp_min_data_rate seconds.

However, the deadline will never be incremented beyond the time limit specified with smtp_data_xfer_timeout.

This feature is available in Postfix 3.7 and later. ✨

📬 smtp_mx_address_limit (default: `5`)

The maximal number of MX (mail exchanger) IP addresses that can result from Postfix SMTP client mail exchanger lookups, or zero (no limit). Prior to Postfix version 2.3, this limit was disabled by default.

This feature is available in Postfix 2.1 and later.

🌀 smtp_mx_session_limit (default: `2`)

The maximal number of SMTP sessions per delivery request before the Postfix SMTP client gives up or delivers to a fall-back relay host, or zero (no limit).

this restriction ignores sessions that fail to complete the SMTP initial handshake (Postfix version 2.2 and earlier) or that fail to complete the EHLO and TLS handshake (Postfix version 2.3 and later). so like, those don't count, periodt 💅

This feature is available in Postfix 2.1 and later.

🪆 smtp_nested_header_checks (default: empty)

Restricted nested_header_checks(5) tables for the Postfix SMTP client. These tables are searched while mail is being delivered. Actions that change the delivery time or destination are not available. 🙈

This feature is available in Postfix 2.5 and later.

🚫 smtp_never_send_ehlo (default: `no`)

Never send EHLO at the start of an SMTP session. See also the smtp_always_send_ehlo parameter. (yes bestie, they're opposites, it's giving enemies to lovers 😭)

📏 smtp_per_record_deadline (default: `no`)

Change the behavior of the smtp_*_timeout time limits, from a time limit per read or write system call, to a time limit to send or receive a complete record (an SMTP command line, SMTP response line, SMTP message content line, or TLS protocol message). This limits the impact from hostile peers that trickle data one byte at a time. 🐌➡️🚫

Note: when per-record deadlines are enabled, a short timeout may cause problems with TLS over very slow network connections. The reasons are that a TLS protocol message can be up to 16 kbytes long (with TLSv1), and that an entire TLS protocol message must be sent or received within the per-record deadline.

This feature is available in Postfix 2.9-3.6. With older Postfix releases, the behavior is as if this parameter is set to "no". Postfix 3.7 and later use smtp_per_request_deadline.

⏱️ smtp_per_request_deadline (default: `no`)

Change the behavior of the smtp_*_timeout time limits, from a time limit per plaintext or TLS read or write call, to a combined time limit for sending a complete SMTP request and for receiving a complete SMTP response.

The deadline limits only the time spent waiting for plaintext or TLS read or write calls, not time spent elsewhere. The per-request deadline limits the impact from hostile peers that trickle data one byte at a time. 🛑

See smtp_min_data_rate for how the per-request deadline is managed during the DATA phase.

Note: when per-request deadlines are enabled, a short time limit may cause problems with TLS over very slow network connections. The reason is that a TLS protocol message can be up to 16 kbytes long (with TLSv1), and that an entire TLS protocol message must be transferred within the per-request deadline. 😭

This feature is available in Postfix 3.7 and later. A weaker feature, called smtp_per_record_deadline, is available with Postfix 2.9-3.6.

This feature is available in Postfix 3.7 and later.

🔥 smtp_pix_workaround_delay_time (default: `10s`)

How long the Postfix SMTP client pauses before sending ".<CR><LF>" in order to work around the PIX firewall "<CR><LF>.<CR><LF>" bug. yes this is a real thing, a whole firewall bug, iconic behavior honestly 💀

Choosing too short a time makes this workaround ineffective when sending large messages over slow network connections. so don't be cheap with the pause, bestie 🫶

`smtp_pix_workaround_maps` (default: empty)

Okay bestie, this one is a lookup-table situation 💅 and it's indexed by the remote SMTP server address, giving you per-destination workarounds for them CISCO PIX firewall bugs. Note that it is not indexed by hostname — that's on purpose, for consistency with smtp_discard_ehlo_keyword_address_maps. iykyk 🎀

Specify zero or more type:name lookup tables, separated by whitespace or comma. Tables get searched in the order you specified them, and we stop at the first match. Periodt.

This feature is available in Postfix 2.4 and later. ✨

`smtp_pix_workaround_threshold_time` (default: 500s)

How long a message has to sit in the queue before the Postfix SMTP client turns on the PIX firewall <CR><LF>.<CR><LF> bug workaround, for deliveries going through firewalls with "smtp fixup" mode turned on. 💀

By default, the workaround is turned off for mail that's been queued for less than 500 seconds. Translation bestie: the workaround is normally off for the first delivery attempt. 🌸

Specify 0 to enable the PIX firewall <CR><LF>.<CR><LF> bug workaround upon the first delivery attempt.

`smtp_pix_workarounds` (default: `disable_esmtp, delay_dotcrlf`)

A list specifying zero or more workarounds for CISCO PIX firewall bugs. These workarounds are implemented by the Postfix SMTP client itself. Workaround names are separated by comma or space, and they are case insensitive. This parameter setting can be overruled with per-destination smtp_pix_workaround_maps settings. 🔥

delay_dotcrlf — Insert a delay before sending ".<CR><LF>" after the end of the message content. That delay is subject to the smtp_pix_workaround_delay_time and smtp_pix_workaround_threshold_time parameter settings.
disable_esmtp — Disable all extended SMTP commands: send HELO instead of EHLO.

This feature is available in Postfix 2.4 and later. The default settings are backwards compatible with earlier Postfix versions. 👑

`smtp_quit_timeout` (default: 300s)

The Postfix SMTP client time limit for sending the QUIT command, and for receiving the remote SMTP server response. 🦋

`smtp_quote_rfc821_envelope` (default: yes)

Quote addresses in Postfix SMTP client MAIL FROM and RCPT TO commands as required by RFC 5321. This includes putting quotes around an address localpart that ends in ".". 🎀

The default is to comply with RFC 5321. If you've gotta send mail to a broken SMTP server (sigh, we've all been there bestie), configure a special SMTP client in master.cf:

/etc/postfix/master.cf:
    broken-smtp . . . smtp -o smtp_quote_rfc821_envelope=no

and route mail for the destination in question to the "broken-smtp" message delivery with a transport(5) table.

This feature is available in Postfix 2.1 and later. ✨

`smtp_randomize_addresses` (default: yes)

Randomize the order of equal-preference MX host addresses. This is a performance feature of the Postfix SMTP client. shuffle-core energy, no cap 🌀

`smtp_rcpt_timeout` (default: 300s)

The Postfix SMTP client time limit for sending the SMTP RCPT TO command, and for receiving the remote SMTP server response. 💜

`smtp_reply_filter` (default: empty)

A mechanism to transform replies from remote SMTP servers one line at a time. This is a last-resort tool to work around server replies that break interoperability with the Postfix SMTP client. Other uses involve fault injection to test Postfix's handling of invalid responses. 🙈

Notes:

In the case of a multi-line reply, the Postfix SMTP client uses the final reply line's numerical SMTP reply code and enhanced status code.
The numerical SMTP reply code (XYZ) takes precedence over the enhanced status code (X.Y.Z). When the enhanced status code initial digit differs from the SMTP reply code initial digit, or when no enhanced status code is present, the Postfix SMTP client uses a generic enhanced status code (X.0.0) instead.

Specify the name of a "type:table" lookup table. The search string is a single SMTP reply line as received from the remote SMTP server, except that the trailing <CR><LF> are removed. When the lookup succeeds, the result replaces the single SMTP reply line. ✨

Examples:

/etc/postfix/main.cf:
    smtp_reply_filter = pcre:/etc/postfix/reply_filter

/etc/postfix/reply_filter:
    # Some Microsoft servers violate RFC 2554 section 4, causing Postfix
    # to complain with "non-empty initial GSSAPI challenge from server"
    /^334\s+GSSAPI\s+supported/ 334

    # Transform garbage into "250-filler..." so that it looks like
    # one line from a multi-line reply. It does not matter what we
    # substitute here as long it has the right syntax.  The Postfix
    # SMTP client will use the final line's numerical SMTP reply
    # code and enhanced status code.
    !/^([2-5][0-9][0-9]($|[- ]))/ 250-filler for garbage

This feature is available in Postfix 2.7. 🌈

`smtp_requiretls_policy` (default: see `'postconf -d smtp_requiretls_policy'` output)

How the Postfix SMTP and LMTP client will enforce REQUIRETLS for messages received with the REQUIRETLS option. Policy examples for SMTP and LMTP are at the end. 👑

Specify a list of items, separated with whitespace or comma; continue a long line by starting the next line with whitespace.
Each item must be an action (see below), or a type:table lookup table that must return an action (it must not return a type:table).
In the text that follows, the TLS next-hop destination for TCP connections is the recipient domain by default, but this can be overruled with destinations specified with transport_maps, relayhost, content_filter, or other routing features. The next-hop destination for LMTP over UNIX-domain connections is always the value of myhostname.
A type:table lookup table is searched with the TLS next-hop destination (without any [ ], :service, or :port). A non-ASCII next-hop destination is converted into ASCII form (Punycode) before making a policy query; lookup tables must answer ASCII-form queries.
A fixed-string table (such as lmdb:, cdb:, or hash:) is also searched with the next-hop ".parent" domains (in a table key, prepend a '.' to a parent domain name). These ".parent" domain queries are not made with pattern-based lookup tables such as regexp: or pcre: or with socketmap: or tcp: tables.

Supported actions, assuming that TLS feature status logging is enabled with "smtp_log_tls_feature_status = yes" (the default):

enforce

Skip servers that do not support STARTTLS, skip connections without a server certificate match, and skip servers that don't support REQUIRETLS after STARTTLS.

If a suitable server is found, request REQUIRETLS, deliver the message, and log "tls=level/requiretls" in delivery status logging, where level shows the current SMTP client TLS security level.

If no suitable server is found, return the message as undeliverable and log a policy violation "tls=level/!requiretls:nocertmatch", "tls=level/!requiretls:noencryption", or "tls=level/!requiretls:nostarttls", as described under smtp_log_tls_feature_status.

NOTE: this is also used implicitly when no REQUIRETLS policy match is found.

opportunistic+starttls

Skip servers that don't announce STARTTLS support, but do not require a server certificate match or remote REQUIRETLS support.

If a suitable server is found, send REQUIRETLS if that server supports REQUIRETLS and log "tls=level/requiretls" or "tls=level/requiretls:nomatch" in delivery status logging, or simply deliver the message as if the sender did not request REQUIRETLS and log "tls=level/requiretls:none, where level shows the current SMTP client TLS security level.

If no suitable server is found, return the message as undeliverable and log a policy violation "tls=level/!requiretls:noencryption" or "tls=level/!requiretls:nostarttls" as described under smtp_log_tls_feature_status.

This relaxed policy can be appropriate for an outbound perimeter MTA, when forwarding messages from internal systems to the Internet, at a time that many domains support TLS but have no DANE or MTA-STS policies. 💅

opportunistic

Do not require STARTTLS, a server certificate match, or remote REQUIRETLS support.

Request REQUIRETLS if the server supports both STARTTLS and REQUIRETLS and log "tls=level/requiretls" or "tls=level/requiretls:nomatch" in delivery status logging, otherwise simply deliver the message as if the sender did not request REQUIRETLS and log "tls=level/requiretls:none, where level shows the current SMTP client TLS security level.

This REQUIRETLS policy is non-intrusive, because there can be no REQUIRETLS policy violation. 🌸

This weak policy can be appropriate for an inbound perimeter MTA, when forwarding messages from the Internet to internal servers or content filters that may not support STARTTLS or REQUIRETLS, using internal connections instead of the public Internet. This setting may also be useful for an outbound MTA to discover what destinations support some form of REQUIRETLS without risking mail delivery problems.

disable

Disable REQUIRETLS support. Deliver all messages as if the sender did not request REQUIRETLS. This may be used as a last-resort workaround when a server announces REQUIRETLS support, but the support is inoperable. 😭

Notes:

To match any name below the domain "example.com" specify a table entry with the storage key ".example.com" in type:table lookup tables that need an exact match. This is appropriate, for example, with lmdb:, cdb: or hash:.
Do not specify a match pattern for ".domain" with regexp:, pcre:, socketmap:, or tcp:, as smtp_requiretls_policy will not query those tables with that form.

SMTP client examples 💌

Also like… go read REQUIRETLS_README for the real tea, bestie. This is just the highlights. 🫶

The simplest policy ever: when a sender requests REQUIRETLS, you request REQUIRETLS when an external or internal server supports both STARTTLS and REQUIRETLS (lines 4, 5), and you enforce a TLS certificate match only if the destination publishes a DANE or STS policy (line 3). And when the sender requests REQUIRETLS but that external or internal server doesn't support both STARTTLS and REQUIRETLS? You just deliver the message as if the sender never asked for REQUIRETLS at all (lines 4, 5). Chill. 😌

1 /etc/postfix/main.cf:
2     smtp_tls_security_level = may
3     smtp_tls_policy_maps = ...dane/sts plugin...
4     smtp_requiretls_policy = opportunistic
5     lmtp_requiretls_policy = opportunistic

The default SMTP client REQUIRETLS policy (lines 4-12): when a sender requests REQUIRETLS, you require that an external server supports STARTTLS and REQUIRETLS, and you require that its server certificate matches a DANE or STS policy (lines 3, 12). But for deliveries to internal destinations or content filters — whether they're specified as a symbolic name (lines 5-8) or as a numeric address (lines 9-11) — you make REQUIRETLS support optional. An internationalized domain name has to be written in ASCII form (lines 6-7); the default policy below uses ${domain_to_ascii{$mydomain}}, which hands you back $mydomain when the domain name is pure ASCII, and Punycode (xn--mumble) when $mydomain has non-ASCII in it. 💅

⚠️ Note: if you specify a domain list outside main.cf, then the automatic $name expansions and Punycode conversions will not happen, and you'll have to type out explicit ASCII domain names yourself. No shortcuts, babe.

 1 /etc/postfix/main.cf:
 2     smtp_tls_security_level = may
 3     smtp_tls_policy_maps = ...dane/sts plugin...
 4     smtp_requiretls_policy =
 5         inline:{
 6             { ${domain_to_ascii{$mydomain}} = opportunistic }
 7             { .${domain_to_ascii{$mydomain}} = opportunistic }
 8             { localhost = opportunistic } }
 9         cidr:{
10             { 0.0.0.0/0 opportunistic },
11             { ::/0 opportunistic } },
12         enforce

An SMTP client REQUIRETLS policy that's relaxed for external destinations (line 12): when a sender requests REQUIRETLS, require that an external server supports STARTTLS, but enforce a TLS certificate match only if the receiver publishes a DANE or STS policy (line 3) — and do not require that an external server supports REQUIRETLS. Copy that same policy from above for internal destinations or content filters (lines 5-11). And again, an internationalized domain name must be specified in ASCII form (lines 6-7); the policy uses ${domain_to_ascii{$mydomain}}, which returns $mydomain when the domain name contains only ASCII characters, and which returns Punycode (xn--mumble) when $mydomain contains non-ASCII. 🌸

⚠️ Note: if you specify a domain list outside main.cf, then the automatic $name expansions and Punycode conversions will not happen, and you will need to enter explicit ASCII domain names. (Yes, same warning. It's that important fr fr.)

 1 /etc/postfix/main.cf:
 2     smtp_tls_security_level = may
 3     smtp_tls_policy_maps = ...dane/sts plugin...
 4     smtp_requiretls_policy =
 5         inline:{
 6             { ${domain_to_ascii{$mydomain}} = opportunistic }
 7             { .${domain_to_ascii{$mydomain}} = opportunistic }
 8             { localhost = opportunistic } }
 9         cidr:{
10             { 0.0.0.0/0 opportunistic },
11             { ::/0 opportunistic } },
12         opportunistic+starttls

Same energy, but with the external destinations listed in a separate file because that's just easier to maintain, honestly.

/etc/postfix/main.cf:
    smtp_tls_security_level = may
    smtp_tls_policy_maps = ...dane/sts plugin...
    smtp_requiretls_policy =
        inline:{
            { ${domain_to_ascii{$mydomain}} = opportunistic }
            { .${domain_to_ascii{$mydomain}} = opportunistic }
            { localhost = opportunistic } }
        cidr:{
            { 0.0.0.0/0 opportunistic },
            { ::/0 opportunistic } },
        lmdb:/etc/postfix/requiretls-per-site
        opportunistic+starttls

/etc/postfix/requiretls-per-site:
    one.example         enforce
    two.example         enforce
    three.example       opportunistic
    ...

Instead of lmdb:, some systems use cdb:, hash:, or dbm:.

Run the command postmap /etc/postfix/requiretls-per-site after you change that requiretls-per-site file, so your default-type indexed file gets (re)built. ✨ And run postmap type:/etc/postfix/requiretls-per-site if you wanna specify an explicit type.

The default indexed file type is configured with the default_database_type parameter. Wanna see which explicit types are even available? Run the command postconf -m and find out. 👑

Config changes become visible after a minute or so. Use postfix reload if you simply cannot wait that long. ⏱️

LMTP client examples 🦋

Again, go peep REQUIRETLS_README for the discussion.

The default LMTP client REQUIRETLS policy: when a sender requests REQUIRETLS, you request REQUIRETLS if the server supports REQUIRETLS — otherwise you deliver the message just as if the sender hadn't requested REQUIRETLS at all.

📌 Note: with deliveries over a UNIX-domain socket, the next-hop destination for lmtp_requiretls_policy lookups will be the myhostname parameter value. iykyk.

/etc/postfix/main.cf:
    lmtp_requiretls_policy = opportunistic

This feature is available in Postfix >= 3.11. 🎀

smtp_rset_timeout (default: 20s) — the Postfix SMTP client's time limit for sending the RSET command, and for receiving the remote SMTP server's response. The SMTP client sends RSET to finish a recipient address probe, or to verify that a cached session is still usable. 👑

This feature is available in Postfix 2.1 and later.

smtp_sasl_auth_cache_name (default: empty) — an optional table that stops you from repeating SASL authentication failures with the same remote SMTP server hostname, username and password. Every table (key, value) pair holds a server name, a username and password, and the full server response. This gets stored when a remote SMTP server rejects an authentication attempt with a 535 reply code. As long as the smtp_sasl_password_maps information doesn't change, and as long as the smtp_sasl_auth_cache_name information doesn't expire (check smtp_sasl_auth_cache_time), the Postfix SMTP client avoids SASL authentication attempts with that same server, username and password, and instead bounces or defers mail as controlled by the smtp_sasl_auth_soft_bounce configuration parameter. 🚫

Use a per-destination delivery concurrency of 1 (for example, "smtp_destination_concurrency_limit = 1", "relay_destination_concurrency_limit = 1", etc.), otherwise multiple delivery agents may experience a login failure at the same time. Not the moment, bestie. 😭

The table must be accessed via the proxywrite service, i.e. the map name must start with "proxy:". And the table should be stored under the directory specified with the data_directory parameter. 📂

This feature uses cryptographic hashing to protect plain-text passwords, and requires that Postfix is compiled with TLS support. 🔐

Examples:

smtp_sasl_auth_cache_name = proxy:lmdb:/var/lib/postfix/sasl_auth_cache
smtp_sasl_auth_cache_name = proxy:btree:/var/lib/postfix/sasl_auth_cache

This feature is available in Postfix 2.5 and later.

smtp_sasl_auth_cache_time (default: 90d) — the maximal age of an smtp_sasl_auth_cache_name entry before it gets removed. 🗑️

This feature is available in Postfix 2.5 and later.

smtp_sasl_auth_enable (default: no) — enable SASL authentication in the Postfix SMTP client. By default, the Postfix SMTP client uses no authentication at all. ✨

Example:

smtp_sasl_auth_enable = yes

smtp_sasl_auth_soft_bounce (default: yes) — when a remote SMTP server rejects a SASL authentication request with a 535 reply code, defer mail delivery instead of returning the mail as undeliverable. That latter behavior was hard-coded prior to Postfix version 2.5. 💀

📌 Note: the setting "yes" overrides the global soft_bounce parameter, but the setting "no" does not.

Example:

# Default as of Postfix 2.5
smtp_sasl_auth_soft_bounce = yes
# The old hard-coded default
smtp_sasl_auth_soft_bounce = no

This feature is available in Postfix 2.5 and later.

smtp_sasl_mechanism_filter (default: empty) — if it's non-empty, it's a Postfix SMTP client filter for the remote SMTP server's list of offered SASL mechanisms. Different client and server implementations may support different mechanism lists; by default, the Postfix SMTP client will use the intersection of the two. smtp_sasl_mechanism_filter specifies an optional third mechanism list to intersect with. 🌈

Specify mechanism names, "/file/name" patterns or "type:table" lookup tables. The right-hand side result from "type:table" lookups is ignored. Specify "!pattern" to exclude a mechanism name from the list. The form "!/file/name" is supported only in Postfix version 2.4 and later.

This feature is available in Postfix 2.2 and later.

Examples:

smtp_sasl_mechanism_filter = plain, login
smtp_sasl_mechanism_filter = /etc/postfix/smtp_mechs
smtp_sasl_mechanism_filter = !gssapi, !login, static:rest

🌸 still more to come, don't go anywhere bestie 🌸

`smtp_sasl_password_maps` (default: empty) 🔐

Okay bestie, this is where the ✨secrets✨ live. These are the optional Postfix SMTP client lookup tables, and they hold one username:password entry per sender, remote hostname, or next-hop domain. It's giving little black book of credentials, fr fr.

Quick thing though: the per-sender lookup only happens when sender-dependent authentication is enabled. And if there's no username:password entry to be found? Then the Postfix SMTP client just... won't try to authenticate to the remote host. No entry, no vibe, no login. Periodt.

Wanna use a different separator between username and password? That's what smtp_sasl_password_result_delimiter is for, my love.

Also this is lowkey iconic: the Postfix SMTP client opens the lookup table before going into the chroot jail, so you can absolutely leave the password file chillin' in /etc/postfix. 🎀

Specify zero or more "type:name" lookup tables, separated by whitespace or comma. Tables get searched in the order you listed them, until a match is found. Slay.

`smtp_sasl_password_result_delimiter` (default: `:`) 💅

This is the delimiter sitting between username and password in sasl_passwd_maps lookup results. You specify one non-whitespace character that does not appear in the username. One. Singular. Don't get cute.

This feature is available in Postfix >= 3.9. ✨

`smtp_sasl_path` (default: empty) 🛣️

Implementation-specific info that the Postfix SMTP client just passes straight through to the SASL plug-in implementation selected with smtp_sasl_type. Typically this specifies the name of a configuration file or a rendezvous point.

This feature is available in Postfix 2.3 and later. 🫶

`smtp_sasl_security_options` (default: `noplaintext, noanonymous`) 🔒

Postfix SMTP client SASL security options, bestie. And heads up: as of Postfix 2.3, the list of available features depends on the SASL client implementation selected with smtp_sasl_type. So like, it's giving choose-your-own-adventure.

The following security features are defined for the cyrus client SASL implementation. Specify zero or more of these:

noplaintext — Disallow methods that use plaintext passwords. Protect the girlies. 🛡️
noactive — Disallow methods subject to active (non-dictionary) attack.
nodictionary — Disallow methods subject to passive (dictionary) attack.
noanonymous — Disallow methods that allow anonymous authentication. 🚫
mutual_auth — Only allow methods that provide mutual authentication (not available with SASL version 1).

Example, because we love a demo:

smtp_sasl_security_options = noplaintext

`smtp_sasl_tls_security_options` (default: `$smtp_sasl_security_options`) 🌸

The SASL authentication security options that the Postfix SMTP client uses for TLS encrypted SMTP sessions. Your girl is secure, obviously.

This feature is available in Postfix 2.2 and later.

`smtp_sasl_tls_verified_security_options` (default: `$smtp_sasl_tls_security_options`) 👑

Okay this one is the main character. These are the SASL authentication security options that the Postfix SMTP client uses for TLS encrypted SMTP sessions with a verified server certificate. The certificate has to actually check out, no cap.

So here's the lore: when mail is sent to the public MX host for the recipient's domain, server certificates are by default optional, and delivery proceeds even if certificate verification fails. Yeah. For delivery via a submission service that requires SASL authentication, it may be appropriate to send plaintext passwords only when the connection to the server is strongly encrypted and the server identity is verified. That's the vibe check.

The smtp_sasl_tls_verified_security_options parameter makes it possible to only enable plaintext mechanisms when a secure connection to the server is available. Submission servers subject to this policy must either have verifiable certificates or offer suitable non-plaintext SASL mechanisms. No shortcuts, bestie.

This feature is available in Postfix 2.6 and later. 🦋

`smtp_sasl_type` (default: `cyrus`) 🌈

The SASL plug-in type that the Postfix SMTP client should use for authentication. The available types are listed with the "postconf -A" command. Go check 'em, I'll wait.

This feature is available in Postfix 2.3 and later.

`smtp_send_dummy_mail_auth` (default: `no`) 📨

Whether or not to append the "AUTH=<>" option to the MAIL FROM command in SASL-authenticated SMTP sessions. The default is not to send this, to avoid problems with broken remote SMTP servers. (Broken servers are not passing the vibe check, sorry not sorry.)

Before Postfix 2.9 the behavior is as if "smtp_send_dummy_mail_auth = yes".

This feature is available in Postfix 2.9 and later.

`smtp_send_xforward_command` (default: `no`) ⭐

Send the non-standard XFORWARD command when the Postfix SMTP server EHLO response announces XFORWARD support.

This allows a Postfix SMTP delivery agent — the one used for injecting mail into a content filter — to forward the name, address, protocol and HELO name of the original client to the content filter and downstream queuing SMTP server. This can produce more useful logging than localhost[127.0.0.1] etc. So instead of that sad little localhost situation, you get the whole story. Iconic, honestly.

This feature is available in Postfix 2.1 and later. 💜

`smtp_sender_dependent_authentication` (default: `no`) 🙋‍♀️

Enable sender-dependent authentication in the Postfix SMTP client! This is available only with SASL authentication, and heads up: it disables SMTP connection caching to ensure that mail from different senders will use the appropriate credentials. Everyone gets their own login, as they should.

This feature is available in Postfix 2.3 and later.

`smtp_skip_4xx_greeting` (default: `yes`) 🚪

Skip SMTP servers that greet with a 4XX status code (go away, try again later). Rude of them, but okay.

By default, the Postfix SMTP client moves on to the next mail exchanger. Specify "smtp_skip_4xx_greeting = no" if Postfix should defer delivery immediately instead.

This feature is available in Postfix 2.0 and earlier. Later Postfix versions always skip remote SMTP servers that greet with a 4XX status code — so lowkey this is a historical artifact. 🏛️

`smtp_skip_5xx_greeting` (default: `yes`) 💀

Skip remote SMTP servers that greet with a 5XX status code. Yeah, we're not doing that today.

By default, the Postfix SMTP client moves on to the next mail exchanger. Specify "smtp_skip_5xx_greeting = no" if Postfix should bounce the mail immediately.

⚠️ Caution: the latter behavior appears to contradict RFC 2821. Not me telling you to be careful with the RFCs, but like... be careful with the RFCs.

`smtp_skip_quit_response` (default: `yes`) 👋

Do not wait for the response to the SMTP QUIT command. You said goodbye, you're gone, you don't need a reply. Leaving them on read, fr fr.

`smtp_starttls_timeout` (default: `300s`) ⏳

Time limit for Postfix SMTP client write and read operations during TLS startup and shutdown handshake procedures. The handshake has a curfew, bestie.

This feature is available in Postfix 2.2 and later. ✨

`smtp_tcp_port` (default: `smtp`) 🔌

The default TCP port that the Postfix SMTP client connects to. Specify a symbolic name (see services(5)) or a numeric port. Your choice, queen.

`smtp_tls_CAfile` (default: empty) 📜

A file containing CA certificates of root CAs trusted to sign either remote SMTP server certificates or intermediate CA certificates. These get loaded into memory before the smtp(8) client enters the chroot jail. If the number of trusted roots is large, consider using smtp_tls_CApath instead — but note that the latter directory must be present in the chroot jail if the smtp(8) client is chrooted. Chroot timing matters, okay?

This file may also be used to augment the client certificate trust chain, but it is best to include all the required certificates directly in $smtp_tls_cert_file (or, Postfix >= 3.4, $smtp_tls_chain_files).

Specify "smtp_tls_CAfile = /path/to/system_CA_file" to use ONLY the system-supplied default Certification Authority certificates.

Specify "tls_append_default_CA = no" to prevent Postfix from appending the system-supplied default CAs and trusting third-party certificates.

Example:

smtp_tls_CAfile = /etc/postfix/CAcert.pem

This feature is available in Postfix 2.2 and later. 🎀

`smtp_tls_CApath` (default: empty) 📁

Directory with PEM format Certification Authority certificates that the Postfix SMTP client uses to verify a remote SMTP server certificate. Don't forget to create the necessary "hash" links with, for example, "$OPENSSL_HOME/bin/c_rehash /etc/postfix/certs". Do not forget. I will know.

To use this option in chroot mode, this directory (or a copy) must be inside the chroot jail. Yes, a copy works. You're welcome.

Specify "smtp_tls_CApath = /path/to/system_CA_directory" to use ONLY the system-supplied default Certification Authority certificates.

Specify "tls_append_default_CA = no" to prevent Postfix from appending the system-supplied default CAs and trusting third-party certificates.

Example:

smtp_tls_CApath = /etc/postfix/certs

This feature is available in Postfix 2.2 and later. 🌸

`smtp_tls_block_early_mail_reply` (default: `no`) 🕵️‍♀️

Try to detect a mail hijacking attack based on a TLS protocol vulnerability (CVE-2009-3555), where an attacker prepends malicious HELO, MAIL, RCPT, DATA commands to a Postfix SMTP client TLS session.

The attack would succeed with non-Postfix SMTP servers that reply to the malicious HELO, MAIL, RCPT, DATA commands after negotiating the Postfix SMTP client TLS session. So like... the fake commands sneak in first and the server answers them thinking it's all normal. Not the vibe. Detect it.

This feature is available in Postfix 2.7. 🔥

`smtp_tls_cert_file` (default: empty)

Ooh bestie this one's a big one. So this is the file holding the Postfix SMTP client RSA certificate, in PEM format. ✨ Cute part? That same file can also hold the Postfix SMTP client private RSA key, and like, it could even be literally the same file as your Postfix SMTP server RSA certificate and key file. Sharing is caring 💖

But heads up: with Postfix >= 3.4 the preferred way to set up client keys and certs is through the "smtp_tls_chain_files" parameter. So this one's kinda the legacy route, iykyk.

Do not configure client certificates unless you genuinely must present client TLS certificates to one or more servers, okay? Client certificates are usually not needed, and they can cause problems in configurations that work perfectly fine without them. 😭 The recommended setting is just… letting the defaults stand:

    smtp_tls_cert_file =
    smtp_tls_key_file =
    smtp_tls_eccert_file =
    smtp_tls_eckey_file =
    # Obsolete DSA parameters
    smtp_tls_dcert_file =
    smtp_tls_dkey_file =
    # Postfix >= 3.4 interface
    smtp_tls_chain_files =

The best way to use the default settings is to comment out the above parameters in main.cf if they're present. Periodt.

Now, to enable remote SMTP servers to verify the Postfix SMTP client certificate, the issuing CA certificates have to be made available to the server. So you should include the required certificates in the client certificate file — client certificate first, then the issuing CA(s) (bottom-up order, bestie, bottom-up 🌸).

Example: the certificate for "client.example.com" was issued by "intermediate CA", which itself has a certificate issued by "root CA". So as the "root" super-user, create the client.pem file with:

# umask 077
# cat client_key.pem client_cert.pem intermediate_CA.pem > chain.pem

If you also want to verify remote SMTP server certificates issued by these CAs, you can add the CA certificates to the smtp_tls_CAfile — and in that case it's not necessary to have them in the smtp_tls_cert_file, smtp_tls_dcert_file (obsolete) or smtp_tls_eccert_file. Flexible queen behavior 💅

A certificate supplied here must be usable as an SSL client certificate, so it has to pass the "openssl verify -purpose sslclient ..." test. No skipping the vibe check. ✨

Example:

smtp_tls_cert_file = /etc/postfix/chain.pem

This feature is available in Postfix 2.2 and later.

`smtp_tls_chain_files` (default: empty)

Okay so this is the main character of client key config. 👑 It's a list of one or more PEM files, each holding one or more private keys directly followed by a corresponding certificate chain. The file names are separated by commas and/or whitespace. This parameter obsoletes the legacy algorithm-specific key and certificate file settings. And when this parameter is non-empty, the legacy parameters get ignored, and a warning is logged if any of them are also non-empty. Bye legacy, you had a good run 🫶

With the proliferation of multiple private key algorithms — which, as of OpenSSL 1.1.1, include DSA (obsolete), RSA, ECDSA, Ed25519 and Ed448 — it's getting increasingly impractical to use separate parameters to configure the key and certificate chain for each algorithm. So Postfix now supports storing multiple keys and corresponding certificate chains in a single file, or in a set of files. Iconic. 💖

Each key must appear immediately before the corresponding certificate, optionally followed by additional issuer certificates that complete the certificate chain for that key. When multiple files are specified, they're equivalent to a single file concatenated from those files in the given order. So like — while a key must always precede its certificate and issuer chain, it can be in a separate file, as long as that file is listed immediately before the file holding the corresponding certificate chain. Once all the files are concatenated, the sequence of PEM objects must be:

key1, cert1, [chain1], key2, cert2, [chain2], ..., keyN, certN, [chainN]

ngl, storing the private key in the same file as the corresponding certificate is more reliable. When the key and certificate live in separate files, there's a chance that during key rollover a Postfix process might load a private key and certificate from separate files that don't match. 😭 And various operational errors may even result in a persistent broken configuration where the certificate doesn't match the private key. That's the 💀 scenario. Avoid it.

The file or files must contain at most one key of each type. If, for example, two or more RSA keys and corresponding chains are listed, then depending on the version of OpenSSL, either only the last one will be used or a configuration error may be detected. Note that while "Ed25519" and "Ed448" are considered separate algorithms, the various ECDSA curves (typically one of prime256v1, secp384r1 or secp521r1) are considered as different parameters of a single "ECDSA" algorithm — so it is not presently possible to configure keys for more than one ECDSA curve. One curve per lifetime bestie, that's the rule 😤

Example (separate files for each key and corresponding certificate chain):

/etc/postfix/main.cf:
    smtp_tls_chain_files =
        ${config_directory}/ed25519.pem,
        ${config_directory}/ed448.pem,
        ${config_directory}/rsa.pem

/etc/postfix/ed25519.pem:
    -----BEGIN PRIVATE KEY-----
    MC4CAQAwBQYDK2VwBCIEIEJfbbO4BgBQGBg9NAbIJaDBqZb4bC4cOkjtAH+Efbz3
    -----END PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIIBKzCB3qADAgECAhQaw+rflRreYuUZBp0HuNn/e5rMZDAFBgMrZXAwFDESMBAG
    ...
    nC0egv51YPDWxEHom4QA
    -----END CERTIFICATE-----

/etc/postfix/ed448.pem:
    -----BEGIN PRIVATE KEY-----
    MEcCAQAwBQYDK2VxBDsEOQf+m0P+G0qi+NZ0RolyeiE5zdlPQR8h8y4jByBifpIe
    LNler7nzHQJ1SLcOiXFHXlxp/84VZuh32A==
    -----END PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIIBdjCB96ADAgECAhQSv4oP972KypOZPNPF4fmsiQoRHzAFBgMrZXEwFDESMBAG
    ...
    pQcWsx+4J29e6YWH3Cy/CdUaexKP4RPCZDrPX7bk5C2BQ+eeYOxyThMA
    -----END CERTIFICATE-----

/etc/postfix/rsa.pem:
    -----BEGIN PRIVATE KEY-----
    MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDc4QusgkahH9rL
    ...
    ahQkZ3+krcaJvDSMgvu0tDc=
    -----END PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIIC+DCCAeCgAwIBAgIUIUkrbk1GAemPCT8i9wKsTGDH7HswDQYJKoZIhvcNAQEL
    ...
    Rirz15HGVNTK8wzFd+nulPzwUo6dH2IU8KazmyRi7OGvpyrMlm15TRE2oyE=
    -----END CERTIFICATE-----

Example (all keys and certificates in a single file):

/etc/postfix/main.cf:
    smtp_tls_chain_files = ${config_directory}/chains.pem

/etc/postfix/chains.pem:
    -----BEGIN PRIVATE KEY-----
    MC4CAQAwBQYDK2VwBCIEIEJfbbO4BgBQGBg9NAbIJaDBqZb4bC4cOkjtAH+Efbz3
    -----END PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIIBKzCB3qADAgECAhQaw+rflRreYuUZBp0HuNn/e5rMZDAFBgMrZXAwFDESMBAG
    ...
    nC0egv51YPDWxEHom4QA
    -----END CERTIFICATE-----
    -----BEGIN PRIVATE KEY-----
    MEcCAQAwBQYDK2VxBDsEOQf+m0P+G0qi+NZ0RolyeiE5zdlPQR8h8y4jByBifpIe
    LNler7nzHQJ1SLcOiXFHXlxp/84VZuh32A==
    -----END PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIIBdjCB96ADAgECAhQSv4oP972KypOZPNPF4fmsiQoRHzAFBgMrZXEwFDESMBAG
    ...
    pQcWsx+4J29e6YWH3Cy/CdUaexKP4RPCZDrPX7bk5C2BQ+eeYOxyThMA
    -----END CERTIFICATE-----
    -----BEGIN PRIVATE KEY-----
    MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDc4QusgkahH9rL
    ...
    ahQkZ3+krcaJvDSMgvu0tDc=
    -----END PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIIC+DCCAeCgAwIBAgIUIUkrbk1GAemPCT8i9wKsTGDH7HswDQYJKoZIhvcNAQEL
    ...
    Rirz15HGVNTK8wzFd+nulPzwUo6dH2IU8KazmyRi7OGvpyrMlm15TRE2oyE=
    -----END CERTIFICATE-----

This feature is available in Postfix 3.4 and later. 🌈

`smtp_tls_cipherlist` (default: empty)

Okay so this is the obsolete Postfix < 2.3 control for the Postfix SMTP client TLS cipher list. F in the chat for the old days 🙈

Since this feature applies to all TLS security levels, it's super easy to create interoperability problems by choosing a non-default cipher list. Do not use a non-default TLS cipher list on hosts that deliver email to the public Internet — you will be unable to send email to servers that only support the ciphers you exclude. Like, you just won't be able to reach them, bestie. 💀

Using a restricted cipher list may be more appropriate for an internal MTA, where one can exert some control over the TLS software and settings of the peer servers. That's the only place it makes sense.

Note: do not use "" quotes around the parameter value. Just don't. 😭

This feature is available in Postfix version 2.2. It is not used with Postfix 2.3 and later; use smtp_tls_mandatory_ciphers instead.

`smtp_tls_ciphers` (default: `medium`)

The minimum TLS cipher grade that the Postfix SMTP client will use with opportunistic TLS encryption. ✨ Cipher types listed in smtp_tls_exclude_ciphers get excluded from the base definition of the selected cipher grade. The default value is "medium" for Postfix releases after the middle of 2015, and "export" for older releases. So if you're on anything recent, medium is your girlypop setting 🎀

When TLS is mandatory the cipher grade is chosen via the smtp_tls_mandatory_ciphers configuration parameter — go check there for syntax details. And see smtp_tls_policy_maps for info on how to configure ciphers on a per-destination basis (yes, you can be picky per destination 👑).

This feature is available in Postfix 2.6 and later. With earlier Postfix releases only the smtp_tls_mandatory_ciphers parameter is implemented, and opportunistic TLS always uses "export" or better (i.e. all) ciphers.

`smtp_tls_connection_reuse` (default: `no`)

Try to make multiple deliveries per TLS-encrypted connection. ♻️ Efficiency icon behavior. This uses the tlsproxy(8) service to encrypt an SMTP connection, uses the scache(8) service to save that connection, and relies on hints from the qmgr(8) daemon. Teamwork makes the dream work 🫶

See "Client-side TLS connection reuse" for background details.

This feature is available in Postfix 3.4 and later.

smtp_tls_dane_insecure_mx_policy (default: dane)

OK so picture this: your nexthop destination security level is dane, but the MX record got found through an insecure MX lookup, and the MX host has "secure" TLSA records. What do we do?? This parameter is the vibe check for exactly that situation. The choices are:

may — the TLSA records get straight-up ignored and TLS is optional. If the MX host doesn't seem to support STARTTLS, or the STARTTLS handshake just ✨fails✨, mail can be sent in the clear. 😬
encrypt — the TLSA records signal that TLS is required. Encryption is mandatory, but no authentication happens. It's giving "we have a lock but no ID check."
dane — the TLSA records are used exactly like with "secure" MX records. TLS encryption is required, and if at least one of the TLSA records is "usable", authentication is also required. When authentication succeeds, it gets logged only as Trusted, not Verified, because bestie… the MX host name could have been forged. 🫠 The default setting is dane as of Postfix versions 3.6.17, 3.7.13, 3.8.8, 3.9.2, and 3.10.0. With earlier versions the default was mistakenly dependent on the smtp_tls_security_level setting. 🙈

So yeah — with "insecure" MX records, an active attacker can compromise SMTP transport security by returning forged MX records. But here's the thing: those attacks are "tamper-evident" because any forged MX hostnames will be recorded in the mail logs. Attackers who place a high value on staying hidden may be deterred from forging MX records. Sloppy and loud = not the move, apparently. 💅

This feature is available in Postfix 3.1 and later. The may policy is backwards-compatible with earlier Postfix versions.

smtp_tls_dcert_file (default: empty)

A file with the Postfix SMTP client DSA certificate in PEM format. This file may also contain the Postfix SMTP client private DSA key. And ngl — the DSA algorithm is obsolete and should not be used. 🚫 It's giving 2003.

See the discussion under smtp_tls_cert_file for more details.

Example:

smtp_tls_dcert_file = /etc/postfix/client-dsa.pem

This feature is available in Postfix 2.2 and later.

smtp_tls_dkey_file (default: $smtp_tls_dcert_file)

A file with the Postfix SMTP client DSA private key in PEM format. This file may be combined with the Postfix SMTP client DSA certificate file specified with $smtp_tls_dcert_file. Again: the DSA algorithm is obsolete and should not be used. 💀

The private key must be accessible without a pass-phrase, i.e. it must not be encrypted. File permissions should grant read-only access to the system superuser account ("root"), and no access to anyone else. Nobody else. Not even your group chat. 🔐

This feature is available in Postfix 2.2 and later.

smtp_tls_eccert_file (default: empty)

A file with the Postfix SMTP client ECDSA certificate in PEM format. This file may also contain the Postfix SMTP client ECDSA private key. But heads up bestie: with Postfix >= 3.4, the preferred way to configure client keys and certificates is via the "smtp_tls_chain_files" parameter. ✨

See the discussion under smtp_tls_cert_file for more details.

Example:

smtp_tls_eccert_file = /etc/postfix/ecdsa-ccert.pem

This feature is available in Postfix 2.6 and later, when Postfix is compiled and linked with OpenSSL 1.0.0 or later.

smtp_tls_eckey_file (default: $smtp_tls_eccert_file)

A file with the Postfix SMTP client ECDSA private key in PEM format. This file may be combined with the Postfix SMTP client ECDSA certificate file specified with $smtp_tls_eccert_file. And once more for the people in the back: with Postfix >= 3.4 the preferred way to configure client keys and certificates is via the "smtp_tls_chain_files" parameter. 🎀

This feature is available in Postfix 2.6 and later, when Postfix is compiled and linked with OpenSSL 1.0.0 or later.

smtp_tls_enable_rpk (default: no)

Request that remote SMTP servers send an RFC7250 raw public key instead of an X.509 certificate. 🌈 This feature and the enable_rpk policy attribute are ignored when there's no raw public key support in the local TLS implementation. So if your TLS stack isn't built for it, it just doesn't hear you. 🙉

At the "may", "encrypt" and "fingerprint" security levels, with parameter setting "smtp_tls_enable_rpk = yes" or with "enable_rpk = yes" in a policy entry, the Postfix SMTP client will indicate in the TLS handshake that it prefers to receive a raw server public key, but it will still accept a server public key certificate. Polite but opinionated. 🫶
At the "fingerprint" security level, with parameter setting "smtp_tls_enable_rpk = yes" or with "enable_rpk = yes" in a policy entry, server authentication based on certificate fingerprints becomes more fragile. Even if the server private key and certificate remain unchanged, the remote SMTP server will fail fingerprint authentication (won't match the configured list of fingerprints) when it starts sending a raw public key instead of a certificate, after its TLS implementation is updated with raw public key support. Therefore, DO NOT enable raw public keys to remote destinations authenticated by server certificate fingerprints. You should enable raw public keys only for servers matched via their public key fingerprint. 🚨 This is one of those "please actually read this" moments.
At the "verify" and "secure" security levels, the Postfix SMTP client always ignores the parameter setting smtp_tls_enable_rpk or the enable_rpk policy attribute. Periodt.
At the opportunistic "dane" security level, the Postfix SMTP client ignores the parameter setting smtp_tls_enable_rpk or the enable_rpk policy attribute (but it will respect them when it falls back to the "may" or "encrypt" level). When all valid TLSA records specify only server public keys (no certificates) and the local TLS implementation supports raw public keys, the client will indicate in the TLS handshake that it prefers to receive a raw public key, but it will still accept a public key certificate.
At the mandatory "dane-only" security level, the Postfix SMTP client always ignores the parameter setting smtp_tls_enable_rpk or the enable_rpk policy attribute. When all valid TLSA records specify only server public keys (no certificates) and the local TLS implementation supports raw public keys, the client will indicate in the TLS handshake that it prefers to receive a raw public key, but it will still accept a public key certificate.

The Postfix SMTP client is always willing to send raw public keys to servers that solicit them when a client certificate is configured and the local TLS implementation supports raw public keys. So generous of it. 💖

Sample commands to compute certificate and public key SHA256 digests:

# SHA256 digest of the first certificate in "cert.pem"
$ openssl x509 -in cert.pem -outform DER | openssl dgst -sha256 -c

# SHA256 digest of the SPKI of the first certificate in "cert.pem"
$ openssl x509 -in cert.pem -pubkey -noout |
    openssl pkey -pubin -outform DER | openssl dgst -sha256 -c

# SHA256 digest of the SPKI of the first private key in "pkey.pem"
$ openssl pkey -in pkey.pem -pubout -outform DER |
    openssl dgst -sha256 -c

This feature is available in Postfix 3.9 and later.

smtp_tls_enforce_peername (default: yes)

With mandatory TLS encryption, require that the remote SMTP server hostname matches the information in the remote SMTP server certificate. As of RFC 2487 the requirements for hostname checking for MTA clients are not specified. (Iconic: a whole RFC just… not saying anything. 🙃)

This option can be set to "no" to disable strict peer name checking. This setting has no effect on sessions that are controlled via the smtp_tls_per_site table.

Disabling the hostname verification can make sense in a closed environment where special CAs are created. But if not used carefully, this option opens the danger of a "man-in-the-middle" attack (the CommonName of this attacker will be logged). 😭 So like… it WILL be in the logs. Rude little breadcrumb.

This feature is available in Postfix 2.2 and later. With Postfix 2.3 and later use smtp_tls_security_level instead.

smtp_tls_enforce_sts_mx_patterns (default: yes)

Transform the TLS policy from an STS policy plugin: connect to an MX host only if its name matches any STS policy MX host pattern, and match the server certificate against the MX hostname. This setting takes effect only when an STS policy plugin has TLSRPT support enabled, so that it forwards STS policy attributes to Postfix. This works even if Postfix TLSRPT support is disabled at build time or at runtime. Sneaky but functional. 🧚

Without the above configuration settings for Postfix and STS plugins, the old behavior stays in effect: connect to any MX host listed in DNS, and match a server certificate against any STS policy MX host pattern.

This feature is available in Postfix >= 3.10.5.

smtp_tls_exclude_ciphers (default: empty)

List of ciphers or cipher types to exclude from the Postfix SMTP client cipher list at all TLS security levels. This is not an OpenSSL cipherlist, bestie — it's a simple list separated by whitespace and/or commas. The elements are a single cipher, or one or more + separated cipher properties, in which case only ciphers matching all the properties are excluded. Every property, no partial credit. 💅

Examples (some of these will cause problems):

smtp_tls_exclude_ciphers = aNULL
smtp_tls_exclude_ciphers = MD5, DES
smtp_tls_exclude_ciphers = DES+MD5
smtp_tls_exclude_ciphers = AES256-SHA, DES-CBC3-MD5
smtp_tls_exclude_ciphers = kEDH+aRSA

The first setting disables anonymous ciphers. The next setting disables ciphers that use the MD5 digest algorithm or the (single) DES encryption algorithm. The next setting disables ciphers that use MD5 and DES together. The next setting disables the two ciphers "AES256-SHA" and "DES-CBC3-MD5". The last setting disables ciphers that use "EDH" key exchange with RSA authentication. See? Same syntax, completely different filter logic — that's why you read the whole thing. 👑

This feature is available in Postfix 2.3 and later.

smtp_tls_fingerprint_cert_match (default: empty) — the list of remote SMTP server cert fingerprints you're willing to accept for the "fingerprint" TLS security level (that's smtp_tls_security_level = fingerprint). Bestie, at this level we do NOT care about Certification Authorities and we literally ignore certificate expiration times 💀. Instead, server certs get verified straight-up by their certificate fingerprint or their public key fingerprint (Postfix 2.9 and later). The fingerprint is a message digest of the server certificate (or the public key, whatever). Which digest algorithm? That's a whole separate vibe — it's picked by the smtp_tls_fingerprint_digest parameter 🌸.

The colons between each pair of nibbles in the fingerprint value are optional (Postfix >= 3.6). In earlier Postfix releases, they were required — annoying, ik.

When an smtp_tls_policy_maps table entry specifies the "fingerprint" security level, any "match" attributes in that entry specify the list of valid fingerprints for the corresponding destination. You can combine multiple fingerprints with a "|" delimiter in a single match attribute, or you can just use multiple match attributes. Both work, queen 👑.

Example: Certificate fingerprint verification with internal mailhub. Two matching fingerprints are listed. The relayhost may be multiple physical hosts behind a load-balancer, each with its own private/public key and self-signed certificate. Alternatively, a single relayhost may be in the process of switching from one set of private/public keys to another, and both keys are trusted just prior to the transition. So relatable honestly 💅.

relayhost = [mailhub.example.com]
smtp_tls_security_level = fingerprint
smtp_tls_fingerprint_digest = sha256
smtp_tls_fingerprint_cert_match =
    cd:fc:d8:db:f8:c4:82:96:6c:...:28:71:e8:f5:8d:a5:0d:9b:d4:a6
    dd:5c:ef:f5:c3:bc:64:25:36:...:99:36:06:ce:40:ef:de:2e:ad:a4

Example: Certificate fingerprint verification with selected destinations. As in the example above, we show two matching fingerprints:

/etc/postfix/main.cf:
    smtp_tls_policy_maps = lmdb:/etc/postfix/tls_policy
    smtp_tls_fingerprint_digest = sha256

/etc/postfix/tls_policy:
    example.com fingerprint
        match=51:e9:af:2e:1e:40:1f:...:64:0a:30:35:2d:09:16:31:5a:eb:82:76
        match=b6:b4:72:34:e2:59:cd:...:c2:ca:63:0d:4d:cc:2c:7d:84:de:e6:2f

Instead of lmdb:, some systems use cdb:, hash:, or dbm:. Pick your fighter ✨.

Run the command postmap /etc/postfix/tls_policy after you change the tls_policy file, to (re)build a default-type indexed file. And run postmap type:/etc/postfix/tls_policy to specify an explicit type. Don't forget bestie, otherwise nothing updates and you'll be sitting there like 🙈.

The default indexed file type is configured with the default_database_type parameter. To list available explicit types, run the command postconf -m. Iconic.

Configuration changes will become visible after a minute or so ⏳. Use postfix reload to eliminate the delay — do it, it's the slay move fr fr.

This feature is available in Postfix 2.5 and later.

smtp_tls_fingerprint_digest (default: see postconf -d output) — the message digest algorithm used to construct remote SMTP server certificate fingerprints. At the "fingerprint" TLS security level (smtp_tls_security_level = fingerprint), the server certificate is verified by directly matching its certificate fingerprint or its public key fingerprint (Postfix 2.9 and later). The fingerprint is the message digest of the server certificate (or its public key) using the selected algorithm. With a digest algorithm resistant to "second pre-image" attacks, it is not feasible to create a new public key and a matching certificate (or public/private key-pair) that has the same fingerprint. So it's giving actual security 🔥.

The default algorithm is sha256 with Postfix >= 3.6 and the compatibility_level set to 3.6 or higher. With Postfix <= 3.5, the default algorithm is md5. Yeah, md5. We don't talk about it 😭.

The best-practice algorithm is now sha256. Recent advances in hash function cryptanalysis have led to md5 and sha1 being deprecated in favor of sha256. However, as long as there are no known "second pre-image" attacks against the older algorithms, their use in this context, though not recommended, is still likely safe. So like... it's fine but also don't.

While additional digest algorithms are often available with OpenSSL's libcrypto, only those used by libssl in SSL cipher suites are available to Postfix. You'll likely find support for md5, sha1, sha256 and sha512.

To find the fingerprint of a specific certificate file, with a specific digest algorithm, run:

$ openssl x509 -noout -fingerprint -digest -in certfile.pem

The text to the right of the "=" sign is the desired fingerprint. For example:

$ openssl x509 -noout -fingerprint -sha256 -in cert.pem
SHA256 Fingerprint=D4:6A:AB:19:24:...:BB:A6:CB:66:82:C0:8E:9B:EE:29:A8:1A

To extract the public key fingerprint from an X.509 certificate, you need to extract the public key from the certificate and compute the appropriate digest of its DER (ASN.1) encoding. With OpenSSL the "-pubkey" option of the "x509" command extracts the public key always in "PEM" format. We pipe the result to another OpenSSL command that converts the key to DER and then to the "dgst" command to compute the fingerprint. Piping queen 🎀.

The actual command to transform the key to DER format depends on the version of OpenSSL used. As of OpenSSL 1.0.0, the "pkey" command supports all key types.

# OpenSSL >= 1.0 with SHA-256 fingerprints.
$ openssl x509 -in cert.pem -noout -pubkey |
    openssl pkey -pubin -outform DER |
    openssl dgst -sha256 -c
(stdin)= 64:3f:1f:f6:e5:1e:d4:2a:56:...:fc:09:1a:61:98:b5:bc:7c:60:58

The Postfix SMTP server and client log the peer (leaf) certificate fingerprint and the public key fingerprint when the TLS loglevel is 2 or higher. So bump that loglevel if you're debugging, bestie 👀.

This feature is available in Postfix 2.5 and later.

smtp_tls_force_insecure_host_tlsa_lookup (default: no) — lookup the associated DANE TLSA RRset even when a hostname is not an alias and its address records lie in an unsigned zone. This is unlikely to ever yield DNSSEC validated results, since child zones of unsigned zones are also unsigned in the absence of DLV or locally configured non-root trust-anchors. We anticipate that such mechanisms will not be used for just the "_tcp" subdomain of a host. Suppressing the TLSA RRset lookup reduces latency and avoids potential interoperability problems with nameservers for unsigned zones that are not prepared to handle the new TLSA RRset. So like, it's a "yes I know this probably won't work but do it anyway" switch 💀.

This feature is available in Postfix 2.11.

smtp_tls_key_file (default: $smtp_tls_cert_file) — file with the Postfix SMTP client RSA private key in PEM format 🔐. This file may be combined with the Postfix SMTP client RSA certificate file specified with $smtp_tls_cert_file. With Postfix >= 3.4 the preferred way to configure client keys and certificates is via the "smtp_tls_chain_files" parameter — that's the modern route fr fr.

The private key must be accessible without a pass-phrase, i.e. it must not be encrypted. File permissions should grant read-only access to the system superuser account ("root"), and no access to anyone else. Lock it down, it's not a group project 🙅‍♀️.

Example:

smtp_tls_key_file = $smtp_tls_cert_file

This feature is available in Postfix 2.2 and later.

smtp_tls_loglevel (default: 0) — enable extra Postfix SMTP client logging of TLS activity ✨. Each logging level also includes the information that is logged at a lower logging level, so it stacks, cute.
- 0 — Disable logging of TLS activity.
- 1 — Log only a summary message on TLS handshake completion — no logging of remote SMTP server certificate trust-chain verification errors if server certificate verification is not required. With Postfix 2.8 and earlier, log the summary message and unconditionally log trust-chain verification errors.
- 2 — Also enable verbose logging in the Postfix TLS library, log session cache operations, and enable OpenSSL logging of the progress of the SSL handshake.
- 3 — Also log the hexadecimal and ASCII dump of the TLS negotiation process.
- 4 — Also log the hexadecimal and ASCII dump of complete transmission after STARTTLS.

Do not use "smtp_tls_loglevel = 2" or higher except in case of problems. Use of loglevel 4 is strongly discouraged. Like, genuinely, it spits out so much you'll regret it 😭.

This feature is available in Postfix 2.2 and later.

`smtp_tls_mandatory_ciphers` (default: `medium`)

okay so this is the minimum cipher grade your Postfix SMTP client will accept when TLS is mandatory — like, when you're actually enforcing encryption and not just being cute about it. The default medium is the move for basically most destinations you'd want to enforce TLS with, and bestie it's genuinely beyond the reach of today's cryptanalytic methods. 🫶

Wanna do ciphers per-destination instead? Go peek at smtp_tls_policy_maps, it's all there.

Here are the cipher grades you can pick from:

high — only "HIGH" grade OpenSSL ciphers, no crumbs. This one's appropriate when all your mandatory TLS destinations (say, when literally all mail is routed to a suitably capable relayhost) support at least one "HIGH" grade cipher. The underlying cipherlist lives in the tls_high_cipherlist config parameter, and bestie you are strongly encouraged not to change it. 💅
medium — "MEDIUM" grade or better. Underlying cipherlist = tls_medium_cipherlist, and again, strongly encouraged not to change that.
null — only the "NULL" OpenSSL ciphers, which give you authentication without encryption. This one's only appropriate in the rare case where all servers are prepared to use NULL ciphers (which are not normally enabled in TLS servers). A plausible use-case? An LMTP server listening on a UNIX-domain socket that's configured to support "NULL" ciphers. Underlying cipherlist = tls_null_cipherlist, and yeah — strongly encouraged not to change it. 🙂
low — "LOW" grade or stronger OpenSSL ciphers. In Postfix >= 3.8 this grade is always identical to medium. Recent versions of OpenSSL don't support any "LOW" grade ciphers at all. In earlier Postfix releases the underlying cipherlist was set via tls_low_cipherlist, which you were strongly encouraged not to change. This obsolete cipher grade SHOULD NOT be used. ma'am this is a wendy's 💀
export — "EXPORT" grade or stronger OpenSSL ciphers. In Postfix >= 3.8 this grade is always identical to medium too. Recent OpenSSL doesn't support any "EXPORT" grade ciphers. In earlier Postfix releases the underlying cipherlist was specified via tls_export_cipherlist, strongly encouraged not to change. This obsolete cipher grade SHOULD NOT be used either. periodt.

So the cipherlists for every grade except null include anonymous ciphers — but those get automatically filtered out if the Postfix SMTP client is configured to verify server certificates. You are very unlikely to need to do anything to exclude anonymous ciphers, they get handled automatically as needed. ✨

But if you absolutely must exclude anonymous ciphers at the may or encrypt security levels — when the Postfix SMTP client doesn't need or use peer certificates — set:

smtp_tls_exclude_ciphers = aNULL

And to exclude anonymous ciphers only when TLS is enforced, set:

smtp_tls_mandatory_exclude_ciphers = aNULL

This feature is available in Postfix 2.3 and later. 🌈

`smtp_tls_mandatory_exclude_ciphers` (default: empty)

This is the extra list of ciphers or cipher types you want excluded from the Postfix SMTP client cipher list at mandatory TLS security levels. It works in addition to whatever's already listed in smtp_tls_exclude_ciphers (go there for the syntax details, bestie). 🎀

Starting with Postfix 2.6, you can specify mandatory cipher exclusions on a per-destination basis via the TLS policy "exclude" attribute. See smtp_tls_policy_maps for the notes and examples.

This feature is available in Postfix 2.3 and later.

`smtp_tls_mandatory_protocols` (default: see `postconf -d` output)

The TLS protocols the Postfix SMTP client will use with mandatory TLS encryption. In main.cf the values are separated by whitespace, commas or colons. But in the policy table "protocols" attribute (see smtp_tls_policy_maps) the only valid separator is a colon. An empty value means allow all protocols. 🦋

The valid protocol names (see SSL_get_version(3)) are "SSLv2", "SSLv3", "TLSv1", "TLSv1.1", "TLSv1.2" and "TLSv1.3". Starting with Postfix 3.6, the default value is ">=TLSv1", which sets TLS 1.0 as the lowest supported TLS protocol version (more on that below). Older releases use the "!" exclusion syntax, also described below.

As of Postfix 3.6, the preferred way to limit the range of acceptable protocols is to set a lowest acceptable TLS protocol version and/or a highest acceptable TLS protocol version. To set the lower bound, include an element like ">=version", where version is either one of the TLS protocol names listed above, or a hexadecimal number corresponding to the desired TLS protocol version (0301 for TLS 1.0, 0302 for TLS 1.1, etc.). For the upper bound, use "<=version". There must be no whitespace between the ">=" or "<=" symbols and the protocol name or number. 🚫

Hexadecimal protocol numbers let you specify protocol bounds for TLS versions that are known to OpenSSL but might not be known to Postfix. They cannot be used with the legacy exclusion syntax. Leading "0" or "0x" prefixes are supported, but not required. So "301", "0301", "0x301" and "0x0301" are all equivalent to "TLSv1". Hexadecimal versions unknown to OpenSSL will fail to set the upper or lower bound, and a warning will be logged. Hex versions should only be used when Postfix is linked with some future version of OpenSSL that supports TLS 1.4 or later, but Postfix doesn't yet support a symbolic name for that protocol version. 🙈

Hexadecimal example (Postfix >= 3.6):

# Allow only TLS 1.2 through (hypothetical) TLS 1.4, once supported
# in some future version of OpenSSL (presently a warning is logged).
smtp_tls_mandatory_protocols = >=TLSv1.2, <=0305
# Allow only TLS 1.2 and up:
smtp_tls_mandatory_protocols = >=0x0303

With Postfix < 3.6 there's no support for a minimum or maximum version, and the protocol range is configured via protocol exclusions instead. To require at least TLS 1.0, set "smtp_tls_mandatory_protocols = !SSLv2, !SSLv3". Listing the protocols to include, rather than the protocols to exclude, is supported — but not recommended. The exclusion syntax more accurately matches the underlying OpenSSL interface. ✨

When using the exclusion syntax, take care to ensure the range of protocols supported by the Postfix SMTP client is contiguous. When a protocol version is enabled, disabling any higher version implicitly disables all versions above that higher version. So like, for example:

smtp_tls_mandatory_protocols = !SSLv2, !SSLv3, !TLSv1.1

also disables any protocol versions higher than TLSv1.1, leaving only "TLSv1" enabled. the way it just cascades 😭

Support for "TLSv1.3" was introduced in OpenSSL 1.1.1. Disabling this protocol via "!TLSv1.3" has been supported since Postfix 3.4 (or patch releases >= 3.0.14, 3.1.10, 3.2.7 and 3.3.2). 💜

While the vast majority of SMTP servers with DANE TLSA records now support at least TLS 1.2, a few still only support TLS 1.0. If you use "dane" or "dane-only" it's best not to disable TLSv1 — except perhaps via the policy table for destinations which you're sure will support "TLSv1.2". 🧚

See the documentation of the smtp_tls_policy_maps parameter and TLS_README for more info about security levels.

Example:

# Preferred syntax with Postfix >= 3.6:
smtp_tls_mandatory_protocols = >=TLSv1.2, <=TLSv1.3
# Legacy syntax:
smtp_tls_mandatory_protocols = !SSLv2, !SSLv3, !TLSv1, !TLSv1.1

This feature is available in Postfix 2.3 and later.

`smtp_tls_note_starttls_offer` (default: `no`)

Set this to log the hostname of a remote SMTP server that offers STARTTLS, when TLS isn't already enabled for that server. 👑

The logfile record looks like this:

postfix/smtp[pid]:  Host offered STARTTLS: [name.of.host]

This feature is available in Postfix 2.2 and later. 🌸

`smtp_tls_per_site` (default: empty)

okay so this one is the OLD way of doing TLS policy, and bestie, it's giving "vintage but problematic" 💀. It's optional lookup tables that tell the Postfix SMTP client what TLS usage policy to use, keyed by next-hop destination and also by remote SMTP server hostname. Two lookups, two chances to match. When both lookups succeed, here's the tea ☕:

the more specific per-site policy (NONE, MUST, etc.) wins over the less specific one (MAY)
the more secure per-site policy (MUST, etc.) wins over the less secure one (NONE)

🚨 With Postfix 2.3 and later, smtp_tls_per_site is strongly discouraged: use smtp_tls_policy_maps instead. Like, please. It's right there.

Also, using the bare hostname as the per-site table lookup key? Discouraged. 🙅 Always use the full destination nexthop (enclosed in [] with a possible ":port" suffix). A recipient domain or MX-enabled transport next-hop with no port suffix may look like a bare hostname, but it's still a suitable destination. no cap.

So on the left-hand side you put a next-hop destination or server hostname — and no wildcards are allowed, periodt. The next-hop destination is either:

the recipient domain, or
the destination specified with a transport(5) table, the relayhost parameter, or the relay_transport parameter

On the right hand side, you pick one of these keywords:

NONE — Don't use TLS at all. This overrides a less specific MAY lookup result from the alternate host or next-hop lookup key, and it also overrides the global smtp_use_tls, smtp_enforce_tls, and smtp_tls_enforce_peername settings. 🔥
MAY — Try to use TLS if the server announces support, otherwise use an unencrypted connection. After a failed TLS handshake or TLS session, fall back to plaintext if the message has spent minimal_backoff_time in the mail queue. This level has less precedence than a more specific result (including NONE) from the alternate host or next-hop lookup key, and less precedence than the more specific global smtp_enforce_tls = yes or smtp_tls_enforce_peername = yes. 🦋
MUST_NOPEERMATCH — Require TLS encryption, but do not require that the remote SMTP server hostname matches the information in the remote SMTP server certificate, or that the server certificate was issued by a trusted CA. This overrides a less secure NONE or a less specific MAY lookup result from the alternate host or next-hop lookup key, and overrides the global smtp_use_tls, smtp_enforce_tls and smtp_tls_enforce_peername settings.
MUST — Require TLS encryption, require that the remote SMTP server hostname matches the information in the remote SMTP server certificate, and require that the remote SMTP server certificate was issued by a trusted CA. This overrides a less secure NONE or MUST_NOPEERMATCH or a less specific MAY lookup result from the alternate host or next-hop lookup key, and overrides the global smtp_use_tls, smtp_enforce_tls and smtp_tls_enforce_peername settings. 👑

The above keywords correspond to the "none", "may", "encrypt" and "verify" security levels for the new smtp_tls_security_level parameter introduced in Postfix 2.3. Starting with Postfix 2.3, and independently of how the policy is specified, the smtp_tls_mandatory_ciphers and smtp_tls_mandatory_protocols parameters apply when TLS encryption is mandatory. Connections for which encryption is optional typically enable all "export" grade and better ciphers (see smtp_tls_ciphers and smtp_tls_protocols). ✨

Now the scary part 😭 — as long as no secure DNS lookup mechanism is available, false hostnames in MX or CNAME responses can change the server hostname that Postfix uses for TLS policy lookup and server certificate verification. Even with a perfect match between the server hostname and the server certificate, there is no guarantee that Postfix is connected to the right server. See TLS_README (Closing a DNS loophole with obsolete per-site TLS policies) for a possible work-around.

This feature is available in Postfix 2.2 and later. With Postfix 2.3 and later, use smtp_tls_policy_maps instead. 🫶

`smtp_tls_policy_maps` (default: empty)

okay THIS one is the glow-up ✨. These are optional lookup tables with the Postfix SMTP client TLS security policy, keyed by next-hop destination. When a non-empty value is specified, this overrides the obsolete smtp_tls_per_site parameter (grandma, we love you, but...). See TLS_README for a more detailed discussion of TLS security levels, and see TLSRPT_README for additional configuration that may be needed for MTA-STS plugins. 📬

Specify zero or more "type:name" lookup tables, separated by whitespace or comma. Tables will be searched in the specified order until a match is found. 🎯

The TLS policy table is indexed by the full next-hop destination, which is either the recipient domain, or the verbatim next-hop specified in the transport table, $local_transport, $virtual_transport, $relay_transport or $default_transport. This includes any enclosing square brackets and any non-default destination server port suffix. The LMTP socket type prefix (inet: or unix:) is not included in the lookup key. iykyk 💅

Only the next-hop domain, or $myhostname with LMTP over UNIX-domain sockets, is used as the nexthop name for certificate verification. The port and any enclosing square brackets are used in the table lookup key, but are not used for server name verification. 🦋

When the lookup key is a domain name without enclosing square brackets or any :port suffix (typically the recipient domain), and the full domain is not found in the table — just as with the transport(5) table — the parent domain starting with a leading "." is matched recursively. This lets you specify a security policy for a recipient domain and all its sub-domains. iconic behavior, honestly 👑

The lookup result is a security level, followed by an optional list of whitespace and/or comma separated name=value attributes that override related main.cf settings. The TLS security levels in order of increasing security are:

none — No TLS. No additional attributes are supported at this level.
may — Opportunistic TLS. Since sending in the clear is acceptable, demanding stronger than default TLS security merely reduces interoperability. The optional "ciphers", "exclude", and "protocols" attributes (available for opportunistic TLS with Postfix >= 2.6) and "connection_reuse" attribute (Postfix >= 3.4) override the "smtp_tls_ciphers", "smtp_tls_exclude_ciphers", "smtp_tls_protocols", and "smtp_tls_connection_reuse" configuration parameters. In the policy table, multiple ciphers, protocols or excluded ciphers must be separated by colons, as attribute values may not contain whitespace or commas. At this level and higher, the optional "servername" attribute (available with Postfix >= 3.4) overrides the global "smtp_tls_servername" parameter, enabling per-destination configuration of the SNI extension sent to the remote SMTP server. The optional "enable_rpk" attribute (Postfix >= 3.9) overrides the main.cf smtp_tls_enable_rpk parameter. When opportunistic TLS handshakes fail, Postfix retries the connection with TLS disabled. This allows mail delivery to sites with non-interoperable TLS implementations. 🙈
encrypt — Mandatory TLS encryption. Mail is delivered only if the remote SMTP server offers STARTTLS and the TLS handshake succeeds. At this level and higher, the optional "protocols" attribute overrides the main.cf smtp_tls_mandatory_protocols parameter, the optional "ciphers" attribute overrides the main.cf smtp_tls_mandatory_ciphers parameter, the optional "exclude" attribute (Postfix >= 2.6) overrides the main.cf smtp_tls_mandatory_exclude_ciphers parameter, and the optional "connection_reuse" attribute (Postfix >= 3.4) overrides the main.cf smtp_tls_connection_reuse parameter. In the policy table, multiple ciphers, protocols or excluded ciphers must be separated by colons, as attribute values may not contain whitespace or commas. The optional "enable_rpk" attribute (Postfix >= 3.9) overrides the main.cf smtp_tls_enable_rpk parameter. 🔒
dane — Opportunistic DANE TLS. The TLS policy for the destination is obtained via TLSA records in DNSSEC. If no TLSA records are found, the effective security level used is may. If TLSA records are found, but none are usable, the effective security level is encrypt. When usable TLSA records are obtained for the remote SMTP server, the server certificate must match the TLSA records. RFC 7672 (DANE) TLS authentication and DNSSEC support is available with Postfix 2.11 and later. The optional "connection_reuse" attribute (Postfix >= 3.4) overrides the main.cf smtp_tls_connection_reuse parameter. When the effective security level used is may, the optional "ciphers", "exclude", and "protocols" attributes (Postfix >= 2.6) override the "smtp_tls_ciphers", "smtp_tls_exclude_ciphers", and "smtp_tls_protocols" configuration parameters. When the effective security level used is encrypt, the optional "ciphers", "exclude", and "protocols" attributes (Postfix >= 2.6) override the "smtp_tls_mandatory_ciphers", "smtp_tls_mandatory_exclude_ciphers", and "smtp_tls_mandatory_protocols" configuration parameters. 🌈
dane-only — Mandatory DANE TLS. The TLS policy for the destination is obtained via TLSA records in DNSSEC. If no TLSA records are found, or none are usable, no connection is made to the server. When usable TLSA records are obtained for the remote SMTP server, the server certificate must match the TLSA records. RFC 7672 (DANE) TLS authentication and DNSSEC support is available with Postfix 2.11 and later. The optional "ciphers", "exclude", and "protocols" attributes (Postfix >= 2.6) override the "smtp_tls_mandatory_ciphers", "smtp_tls_mandatory_exclude_ciphers", and "smtp_tls_mandatory_protocols" configuration parameters. The optional "connection_reuse" attribute (Postfix >= 3.4) overrides the main.cf smtp_tls_connection_reuse parameter. 💀

fingerprint

okay bestie, this level is Certificate fingerprint verification 💅 and it's available with Postfix 2.5 and later. so at this security level there are like... no trusted Certification Authorities. at all. the certificate trust chain, expiration date, ... are not checked. nope. not a thing here.

instead, the optional policy table "match" attribute — or if you don't have that, the main.cf smtp_tls_fingerprint_cert_match parameter — lists the certificate fingerprints or the public key fingerprints (Postfix 2.9 and later) of acceptable server certificates. and the digest algorithm used to calculate the fingerprint? that's selected by the smtp_tls_fingerprint_digest parameter, mwah 💖

multiple fingerprints can be combined with a "|" delimiter in a single match attribute, or you can just use multiple match attributes. whatever vibes. but heads up: the ":" character is not used as a delimiter, because it literally occurs between each pair of fingerprint (hexadecimal) digits. so yeah, that would be chaos 🫠

the optional "ciphers", "exclude", and "protocols" attributes (Postfix >= 2.6) override the "smtp_tls_mandatory_ciphers", "smtp_tls_mandatory_exclude_ciphers", and "smtp_tls_mandatory_protocols" configuration parameters. the optional "connection_reuse" attribute (Postfix >= 3.4) overrides the main.cf smtp_tls_connection_reuse parameter. and the optional "enable_rpk" attribute (Postfix >= 3.9) overrides the main.cf smtp_tls_enable_rpk parameter. so many lil overrides, it's giving customization 😌✨

verify

Mandatory TLS verification. mail is delivered only if the TLS handshake succeeds, the remote SMTP server certificate chain can be validated, and a DNS name in the certificate matches the specified match criteria. three green flags or we're not going 💚

at this security level, DNS MX lookups are presumed to be secure enough, and the name verified in the server certificate is potentially obtained via unauthenticated DNS MX lookups. so like... it's trusting the vibes of DNS a little bit.

the optional "match" attribute overrides the main.cf smtp_tls_verify_cert_match parameter. and in the policy table, multiple match patterns and strategies must be separated by colons. : : : that's the separator bestie, not commas.

in practice explicit control over matching is more common with the "secure" policy, described below 👇

with Postfix >= 2.11 the optional "tafile" policy table attribute modifies trust chain verification in the same manner as the "smtp_tls_trust_anchor_file" parameter. and the "tafile" attribute may be specified multiple times to load multiple trust-anchor files, no cap 🔥

the optional "connection_reuse" attribute (Postfix >= 3.4) overrides the main.cf smtp_tls_connection_reuse parameter.

secure

Secure certificate verification. mail is delivered only if the TLS handshake succeeds, the remote SMTP server certificate chain can be validated, and a DNS name in the certificate matches the specified match criteria. same deal as verify, but with way higher standards, she's the main character 👑

at this security level, DNS MX lookups — though potentially used to determine the candidate next-hop gateway IP addresses — are not presumed to be secure enough for TLS peername verification. so, no trusting DNS here.

instead, the default name verified in the server certificate is obtained directly from the next-hop, or is explicitly specified via the optional "match" attribute which overrides the main.cf smtp_tls_secure_cert_match parameter. in the policy table, multiple match patterns and strategies must be separated by colons.

the match attribute is most useful when multiple domains are supported by a common server: the policy entries for additional domains specify matching rules for the primary domain certificate. while transport table overrides that route the secondary domains to the primary nexthop also allow secure verification, they risk delivery to the wrong destination when domains change hands or are re-assigned to new gateways 😬 with the "match" attribute approach, routing is not perturbed, and mail is deferred if verification of a new MX host fails. much safer, we love a low-risk queen.

with Postfix >= 2.11 the "tafile" attribute optionally modifies trust chain verification in the same manner as the "smtp_tls_trust_anchor_file" parameter. the "tafile" attribute may be specified multiple times to load multiple trust-anchor files ✨

the optional "connection_reuse" attribute (Postfix >= 3.4) overrides the main.cf smtp_tls_connection_reuse parameter.

Example:

/etc/postfix/main.cf:
    smtp_tls_policy_maps = lmdb:/etc/postfix/tls_policy
    # Postfix 2.5 and later.
    #
    # The default digest is sha256 with Postfix >= 3.6 and
    # compatibility level >= 3.
    #
    smtp_tls_fingerprint_digest = sha256

/etc/postfix/tls_policy:
    example.edu                 none
    example.mil                 may
    example.gov                 encrypt protocols=TLSv1
    example.com                 verify ciphers=high
    example.net                 secure
    .example.net                secure match=.example.net:example.net
    [mail.example.org]:587      secure match=nexthop
    # Postfix 2.5 and later
    [thumb.example.org]          fingerprint
        match=b6:b4:72:34:e2:59:cd:...:c2:ca:63:0d:4d:cc:2c:7d:84:de:e6:2f
        match=51:e9:af:2e:1e:40:1f:...:64:0a:30:35:2d:09:16:31:5a:eb:82:76

instead of lmdb:, some systems use cdb:, hash:, or dbm:. depends on your OS's mood 💁‍♀️

⚠️ Note: the "hostname" strategy if listed in a non-default setting of smtp_tls_secure_cert_match or in the "match" attribute in the policy table can render the "secure" level vulnerable to DNS forgery. do not use the "hostname" strategy for secure-channel configurations in environments where DNS security is not assured. fr fr, this is not a drill 🚨

execute the command postmap /etc/postfix/tls_policy after you change the tls_policy file, to (re)build a default-type indexed file. and execute postmap type:/etc/postfix/tls_policy to specify an explicit type.

the default indexed file type is configured with the default_database_type parameter. to list available explicit types, execute the command postconf -m. so handy 🙌

configuration changes will become visible after a minute or so. use postfix reload to eliminate the delay. impatient girlies stay winning 💅

this feature is available in Postfix 2.3 and later.

smtp_tls_protocols 🌈 (default: see '`postconf -d`' output)

TLS protocols that the Postfix SMTP client will use with opportunistic TLS encryption. okay so in main.cf the values are separated by whitespace, commas or colons. but in the policy table "protocols" attribute (see smtp_tls_policy_maps) the only valid separator is colon. an empty value means allow all protocols — go wild, bestie 🦋

the valid protocol names (see SSL_get_version(3)) are "SSLv2", "SSLv3", "TLSv1", "TLSv1.1", "TLSv1.2" and "TLSv1.3". starting with Postfix 3.6, the default value is ">=TLSv1", which sets TLS 1.0 as the lowest supported TLS protocol version (see below). older releases use the "!" exclusion syntax, also described below.

as of Postfix 3.6, the preferred way to limit the range of acceptable protocols is to set the lowest acceptable TLS protocol version and/or the highest acceptable TLS protocol version. to set the lower bound include an element of the form: ">=version" where version is either one of the TLS protocol names listed above, or a hexadecimal number corresponding to the desired TLS protocol version (0301 for TLS 1.0, 0302 for TLS 1.1, etc.). for the upper bound, use "<=version". there must be no whitespace between the ">=" or "<=" symbols and the protocol name or number. none. zero. ⭐

hexadecimal protocol numbers make it possible to specify protocol bounds for TLS versions that are known to OpenSSL, but might not be known to Postfix. they cannot be used with the legacy exclusion syntax. leading "0" or "0x" prefixes are supported, but not required. therefore, "301", "0301", "0x301" and "0x0301" are all equivalent to "TLSv1". hexadecimal versions unknown to OpenSSL will fail to set the upper or lower bound, and a warning will be logged. hexadecimal versions should only be used when Postfix is linked with some future version of OpenSSL that supports TLS 1.4 or later, but Postfix does not yet support a symbolic name for that protocol version. foreshadowing much? 🔮

hexadecimal example (Postfix >= 3.6):

# Allow only TLS 1.0 through (hypothetical) TLS 1.4, once supported
# in some future version of OpenSSL (presently a warning is logged).
smtp_tls_protocols = >=TLSv1, <=0305
# Allow only TLS 1.0 and up:
smtp_tls_protocols = >=0x0301

with Postfix < 3.6 there is no support for a minimum or maximum version, and the protocol range is configured via protocol exclusions. to require at least TLS 1.0, set "smtp_tls_protocols = !SSLv2, !SSLv3". listing the protocols to include, rather than protocols to exclude, is supported, but not recommended. the exclusion form more accurately matches the underlying OpenSSL interface. so like, technically allowed but don't 😭

when using the exclusion syntax, take care to ensure that the range of protocols advertised by an SSL/TLS client is contiguous. when a protocol version is enabled, disabling any higher version implicitly disables all versions above that higher version. thus, for example:

smtp_tls_protocols = !SSLv2, !SSLv3, !TLSv1.1

also disables any protocols version higher than TLSv1.1 leaving only "TLSv1" enabled. sneaky lil side effect, watch out 🫶

support for "TLSv1.3" was introduced in OpenSSL 1.1.1. disabling this protocol via "!TLSv1.3" is supported since Postfix 3.4 (or patch releases >= 3.0.14, 3.1.10, 3.2.7 and 3.3.2).

example:

# Preferred syntax with Postfix >= 3.6:
smtp_tls_protocols = >=TLSv1, <=TLSv1.3
# Legacy syntax:
smtp_tls_protocols = !SSLv2, !SSLv3

this feature is available in Postfix 2.6 and later. 🎀

`smtp_tls_scert_verifydepth` (default: 9)

okay so this one sets the verification depth for remote SMTP server certificates. 🎀 What does that even mean? Basically: a depth of 1 is plenty if the issuing CA is listed in a local CA file. That's it, that's the whole vibe for the simple case.

Now for the lore: the default verification depth is 9, which is literally the OpenSSL default, kept around for compatibility with earlier Postfix behavior. Before Postfix 2.5 the default value was 5 — but plot twist 🙈 — that limit wasn't actually enforced. So if you've set this to a lower non-default value, certificates with longer trust chains may now fail to verify. She's stricter now, no cap.

Certificate chains with 1 or 2 CAs are common, deeper chains are more rare, and any number between 5 and 9 should suffice in practice. You can pick a lower number if, for example, you trust certificates directly signed by an issuing CA but not any CAs it delegates to. very "I only trust you, not your friends" energy 💅

This feature is available in Postfix 2.2 and later. ✨

`smtp_tls_secure_cert_match` (default: nexthop, dot-nexthop)

This is how the Postfix SMTP client verifies the server certificate peername for the "secure" TLS security level. 🦋 And here's the fun part: in a "secure" TLS policy table ($smtp_tls_policy_maps) entry, the optional "match" attribute overrides this main.cf setting. Policy table stays winning, bestie.

This parameter specifies one or more patterns or strategies separated by commas, whitespace or colons. But heads up — in the policy table, the only valid separator is the colon character. no commas allowed over there, she's picky.

For a description of the pattern and strategy syntax, go look at the smtp_tls_verify_cert_match parameter. And a real warning here: the "hostname" strategy should be avoided in this context, because in the absence of a secure global DNS, using the results of MX lookups in certificate verification is not immune to active (man-in-the-middle) attacks on DNS. 😭 stay safe out there.

Sample main.cf setting:

smtp_tls_secure_cert_match = nexthop

Sample policy table override:

example.net     secure match=example.com:.example.com
.example.net    secure match=example.com:.example.com

This feature is available in Postfix 2.3 and later. 🌈

`smtp_tls_security_level` (default: Postfix >= 3.11: may; Postfix < 3.11: empty)

The default SMTP TLS security level for the Postfix SMTP client. 👑 When a non-empty value is specified, this overrides the obsolete parameters smtp_use_tls, smtp_enforce_tls, and smtp_tls_enforce_peername. And when no value is specified for those obsolete parameters, the default SMTP TLS security level is may (compatibility_level >= 3.11) or none (compatibility_level < 3.11). yes queen, context-dependent defaults, we love her 💅

Specify one of the following security levels:

none — No TLS. TLS will not be used unless enabled for specific destinations via smtp_tls_policy_maps.
may — Opportunistic TLS. Use TLS if this is supported by the remote SMTP server, otherwise use plaintext; after a failed TLS handshake or TLS session, fall back to plaintext if the message has spent minimal_backoff_time in the mail queue. Since sending in the clear is acceptable, demanding stronger than default TLS security merely reduces interoperability. The "smtp_tls_ciphers" and "smtp_tls_protocols" (Postfix >= 2.6) configuration parameters provide control over the protocols and cipher grade used with opportunistic TLS. With earlier releases the opportunistic TLS cipher grade is always "export" and no protocols are disabled. When TLS handshakes fail, the connection is retried with TLS disabled. This allows mail delivery to sites with non-interoperable TLS implementations.
encrypt — Mandatory TLS encryption. Since a minimum level of security is intended, it is reasonable to be specific about sufficiently secure protocol versions and ciphers. At this security level and higher, the main.cf parameters smtp_tls_mandatory_protocols and smtp_tls_mandatory_ciphers specify the TLS protocols and minimum cipher grade which the administrator considers secure enough for mandatory encrypted sessions. This security level is not an appropriate default for systems delivering mail to the Internet.
dane — Opportunistic DANE TLS. At this security level, the TLS policy for the destination is obtained via DNSSEC. For TLSA policy to be in effect, the destination domain's containing DNS zone must be signed and the Postfix SMTP client's operating system must be configured to send its DNS queries to a recursive DNS nameserver that is able to validate the signed records. Each MX host's DNS zone should also be signed, and should publish DANE TLSA (RFC 7672) records that specify how that MX host's TLS certificate is to be verified. TLSA records do not preempt the normal SMTP MX host selection algorithm, if some MX hosts support TLSA and others do not, TLS security will vary from delivery to delivery. It is up to the domain owner to configure their MX hosts and their DNS sensibly. To configure the Postfix SMTP client for DNSSEC lookups see the documentation for the smtp_dns_support_level main.cf parameter. When DNSSEC-validated TLSA records are not found the effective tls security level is "may". When TLSA records are found, but are all unusable the effective security level is "encrypt". For purposes of protocol and cipher selection, the "dane" security level is treated like a "mandatory" TLS security level, and weak ciphers and protocols are disabled. Since DANE authenticates server certificates the "aNULL" cipher-suites are transparently excluded at this level, no need to configure this manually. RFC 7672 (DANE) TLS authentication is available with Postfix 2.11 and later.
dane-only — Mandatory DANE TLS. This is just like "dane" above, but DANE TLSA authentication is required. There is no fallback to "may" or "encrypt" when TLSA records are missing or unusable. RFC 7672 (DANE) TLS authentication is available with Postfix 2.11 and later.
fingerprint — Certificate fingerprint verification. At this security level, there are no trusted Certification Authorities. The certificate trust chain, expiration date, etc., are not checked. Instead, the smtp_tls_fingerprint_cert_match parameter lists the certificate fingerprint or public key fingerprint (Postfix 2.9 and later) of the valid server certificate. The digest algorithm used to calculate the fingerprint is selected by the smtp_tls_fingerprint_digest parameter. Available with Postfix 2.5 and later.
verify — Mandatory TLS verification. At this security level, DNS MX lookups are trusted to be secure enough, and the name verified in the server certificate is usually obtained indirectly via unauthenticated DNS MX lookups. The smtp_tls_verify_cert_match parameter controls how the server name is verified. In practice explicit control over matching is more common at the "secure" level, described below. This security level is not an appropriate default for systems delivering mail to the Internet.
secure — Secure-channel TLS. At this security level, DNS MX lookups, though potentially used to determine the candidate next-hop gateway IP addresses, are not trusted to be secure enough for TLS peername verification. Instead, the default name verified in the server certificate is obtained from the next-hop domain as specified in the smtp_tls_secure_cert_match configuration parameter. The default matching rule is that a server certificate matches when its name is equal to or is a sub-domain of the nexthop domain. This security level is not an appropriate default for systems delivering mail to the Internet.

Examples:

# No TLS. Formerly: smtp_use_tls=no and smtp_enforce_tls=no.
smtp_tls_security_level = none

# Opportunistic TLS.
smtp_tls_security_level = may
# Do not tweak opportunistic ciphers or protocols unless it is essential
# to do so (if a security vulnerability is found in the SSL library that
# can be mitigated by disabling a particular protocol or raising the
# cipher grade).
smtp_tls_ciphers = medium
smtp_tls_protocols = >=TLSv1
# Legacy (Postfix < 3.6) syntax:
smtp_tls_protocols = !SSLv2, !SSLv3

# Mandatory (high-grade) TLS encryption.
smtp_tls_security_level = encrypt
smtp_tls_mandatory_ciphers = high

# Authenticated TLS 1.2 or better matching the nexthop domain or a
# subdomain.
smtp_tls_security_level = secure
smtp_tls_mandatory_ciphers = high
smtp_tls_mandatory_protocols = >=TLSv1.2
smtp_tls_secure_cert_match = nexthop, dot-nexthop

# Certificate fingerprint verification (Postfix >= 2.5).
# The CA-less "fingerprint" security level only scales to a limited
# number of destinations. As a global default rather than a per-site
# setting, this is practical only when mail for all recipients is sent
# to a central mail hub.
relayhost = [mailhub.example.com]
smtp_tls_security_level = fingerprint
smtp_tls_mandatory_protocols = >=TLSv1.2
smtp_tls_mandatory_ciphers = high
smtp_tls_fingerprint_cert_match =
    3D:95:34:51:...:40:99:C0:C1
    EC:3B:2D:B0:...:A3:9D:72:F6

ngl the fingerprint level is giving "I know exactly who you are and I'm not asking anyone else" 💀 it genuinely only scales to a limited number of destinations, so don't go making it your global default unless everything funnels to one central mail hub.

This feature is available in Postfix 2.3 and later. 💖

💖 `smtp_tls_servername` 💖 (default: empty)

Optional name to send off to the remote SMTP server in the TLS Server Name Indication (SNI) extension. Bestie, listen: the SNI extension is always on when DANE is doing the server authentication, and in that case the SNI name that gets sent is the one RFC7672 requires — so this parameter just gets ignored entirely. 🙈

Some SMTP servers use the SNI name they receive to pick which certificate chain to show the client. Which sounds cute, and it may improve interoperability with those servers — but it may also reduce interoperability with other servers that decide to just abort the connection when they don't have a certificate chain configured for the name you asked for. 😭 Those servers should pick a default certificate chain and keep the handshake going, but some of them... do not. So, absent DANE, no SNI name gets sent by default. Periodt.

The SNI name has to be either a valid DNS hostname, or one of the special values hostname or nexthop — those pick the remote hostname or the nexthop domain respectively. DNS names for SNI must be in A-label (punycode) form. Invalid DNS names log a configuration error warning and mail delivery is deferred.

Except when you're using a relayhost to forward all your email, the only sensible non-empty main.cf setting for this parameter is hostname. Other non-empty values only really make sense on a per-destination basis via the servername attribute of the Postfix TLS policy table. When in doubt: leave this empty and configure per-destination SNI as needed. ✨

This feature is available in Postfix 3.4 and later.

🎀 `smtp_tls_session_cache_database` 🎀 (default: empty)

Name of the file that holds the optional Postfix SMTP client TLS session cache. Specify a database type that supports enumeration, like lmdb or btree — no need for concurrent access support here. The file gets created if it doesn't exist, easy.

Plot twist: the smtp(8) daemon doesn't use this parameter directly. Instead the cache is implemented indirectly in the tlsmgr(8) daemon. Which means per-smtp-instance master.cf overrides of this parameter are not effective. 👀

Also, each of the cache databases supported by the tlsmgr(8) daemon — $smtpd_tls_session_cache_database, $smtp_tls_session_cache_database (and with Postfix 2.3 and later $lmtp_tls_session_cache_database) — needs to be stored separately. It is not at this time possible to store multiple caches in a single database.

⚠️ Note: dbm databases are not suitable. TLS session objects are too large.

As of version 2.5, Postfix no longer uses root privileges when opening this file. It should now live under the Postfix-owned data_directory. As a migration aid, if you try to open the file under a non-Postfix directory, it gets redirected to the Postfix-owned data_directory and a warning is logged. 🫶

Example:

smtp_tls_session_cache_database = lmdb:/var/lib/postfix/smtp_scache
smtp_tls_session_cache_database = btree:/var/lib/postfix/smtp_scache

This feature is available in Postfix 2.2 and later.

🦋 `smtp_tls_session_cache_timeout` 🦋 (default: 3600s)

How long Postfix SMTP client TLS session cache info sticks around before it expires. A cache cleanup happens periodically, every $smtp_tls_session_cache_timeout seconds. And just like $smtp_tls_session_cache_database, this parameter is implemented in the tlsmgr(8) daemon, so per-smtp-instance master.cf overrides are simply not possible. 😤

As of Postfix 2.11 this setting cannot exceed 100 days. If you set it <= 0, session caching is disabled. If you set it to a positive value less than 2 minutes, the minimum value of 2 minutes is used instead.

This feature is available in Postfix 2.2 and later.

🌸 `smtp_tls_trust_anchor_file` 🌸 (default: empty)

Zero or more PEM-format files with trust-anchor certificates and/or public keys. If this parameter is not empty, the root CAs in CAfile and CApath are no longer trusted — instead, the Postfix SMTP client will only trust certificate-chains signed by one of the trust-anchors inside the files you chose. 💅

The trust-anchor certificates and public keys you specify are not subject to expiration, and they don't have to be (self-signed) root CAs. They may, if you want, be intermediate certificates. Which means these certificates can also show up "in the middle" of the trust chain the remote SMTP server presents, and any untrusted issuing parent certificates get ignored. Specify a list of pathnames separated by comma or whitespace.

Whether you set it in main.cf or on a per-destination basis, the trust-anchor PEM file must be accessible to the Postfix SMTP client in the chroot jail if applicable. That file should contain only certificates and public keys, no private key material, and it must be readable by the non-privileged $mail_owner user. This is what lets you bind destinations to a specific set of CAs or public keys without trusting those same CAs for everybody. 👑

The main.cf parameter supports single-purpose Postfix installations that send mail to a fixed set of SMTP peers. At most sites, if trust-anchor files get used at all, they'll be specified per-destination via the "tafile" attribute of the "verify" and "secure" levels in smtp_tls_policy_maps.

The underlying mechanism is in support of RFC 7672 (DANE TLSA), which defines mechanisms for an SMTP client MTA to securely determine server TLS certificates via DNS.

If you want your trust anchors to be public keys, with OpenSSL you can extract a single PEM public key from a PEM X.509 file containing a single certificate, like this:

$ openssl x509 -in cert.pem -out ta-key.pem -noout -pubkey

This feature is available in Postfix 2.11 and later.

⭐ `smtp_tls_verify_cert_match` ⭐ (default: hostname)

How the Postfix SMTP client verifies the server certificate peername for the "verify" TLS security level. In a "verify" TLS policy table ($smtp_tls_policy_maps) entry, the optional "match" attribute overrides this main.cf setting. iykyk. 💁‍♀️

This parameter specifies one or more patterns or strategies separated by commas, whitespace or colons. In the policy table, the only valid separator is the colon character.

Patterns specify domain names, or domain name suffixes:

example.com — match the example.com domain, i.e. one of the names in the server certificate must be example.com. Upper and lower case distinctions are ignored.
.example.com — match subdomains of the example.com domain, i.e. match a name in the server certificate that consists of a non-zero number of labels followed by a .example.com suffix. Case distinctions are ignored.

Strategies specify a transformation from the next-hop domain to the expected name in the server certificate:

nexthop — match against the next-hop domain, which is either the recipient domain, or the transport next-hop configured for the domain stripped of any optional socket type prefix, enclosing square brackets and trailing port. When MX lookups are not suppressed, this is the original nexthop domain prior to the MX lookup, not the result of the MX lookup. For LMTP delivery via UNIX-domain sockets, the verified next-hop name is $myhostname. This strategy is suitable for use with the "secure" policy. Case is ignored.
dot-nexthop — as above, but match server certificate names that are subdomains of the next-hop domain. Case is ignored.
hostname — match against the hostname of the server, often obtained via an unauthenticated DNS MX lookup. For LMTP delivery via UNIX-domain sockets, the verified name is $myhostname. This matches the verification strategy of the "MUST" keyword in the obsolete smtp_tls_per_site table, and is suitable for use with the "verify" security level. When the next-hop name is enclosed in square brackets to suppress MX lookups, the "hostname" strategy is the same as the "nexthop" strategy. Case is ignored.

Sample main.cf setting:

smtp_tls_verify_cert_match = hostname, nexthop, dot-nexthop

Sample policy table override:

example.com     verify  match=hostname:nexthop
.example.com    verify  match=example.com:.example.com:hostname

This feature is available in Postfix 2.3 and later.

🌈 `smtp_tls_wrappermode` 🌈 (default: no)

Ask the Postfix SMTP client to connect using the SUBMISSIONS (formerly called SMTPS) protocol instead of using the STARTTLS command. 🔥

This mode requires smtp_tls_security_level = encrypt or stronger.

Example: deliver all remote mail via a provider's submissions service at "mail.example.com".

/etc/postfix/main.cf:

# Client-side SUBMISSIONS requires "encrypt" or stronger.
smtp_tls_security_level = encrypt
smtp_tls_wrappermode = yes
# The [] suppress MX lookups.
relayhost = [mail.example.com]:submissions

More examples are in TLS_README, including examples for older Postfix versions.

This feature is available in Postfix 3.0 and later.

💜 `smtp_tlsrpt_enable` 💜 (default: no)

Turn on support for RFC 8460 TLSRPT notifications. A mail receiving domain can publish a TLSRPT policy in DNS to request periodic summaries of successful and failed SMTP over TLS connections to their MX servers. Heads up: this feature requires that Postfix is built with a TLSRPT supporting library. 🧚

See TLSRPT_README for configuration examples and additional requirements for MTA-STS smtp_tls_policy_maps plugins.

This feature is available in Postfix >= 3.10.

🍓 `smtp_tlsrpt_skip_reused_handshakes` 🍓 (default: Postfix >= 3.11: no, Postfix 3.10: yes)

When set to "yes", report the TLSRPT status only for "new" TLS sessions. When set to "no", also report the TLSRPT status for TLS protocol handshakes that reuse a previously-negotiated TLS session.

Note: if an SMTP over TLS connection is reused, there is no second etc. TLS handshake to report.

This feature is available in Postfix >= 3.10.

✨ `smtp_tlsrpt_socket_name` ✨ (default: empty)

The pathname of a UNIX-domain datagram socket that is managed by a local TLSRPT reporting service. This parameter must specify a pathname (absolute, or relative to $queue_directory) when "smtp_tlsrpt_enable = yes". 👑

See TLSRPT_README for configuration examples and additional requirements for MTA-STS smtp_tls_policy_maps plugins.

This feature is available in Postfix >= 3.10.

`smtp_use_tls` (default: `no`)

Opportunistic mode, bestie 🌸 — use TLS whenever a remote SMTP server announces STARTTLS support, and otherwise just send the mail in the clear. No drama.

But beware: some SMTP servers offer STARTTLS even when it isn't actually configured. Awkward. And heads up, with Postfix < 2.3, if the TLS handshake fails and no other server is available, delivery gets deferred and the mail just sits there in the queue 😭. If that's a thing you care about, use the smtp_tls_per_site feature instead.

This feature is available in Postfix 2.2 and later. With Postfix 2.3 and later, use smtp_tls_security_level instead. 💅

`smtp_xforward_timeout` (default: `300s`)

The Postfix SMTP client's time limit for sending the XFORWARD command, and for receiving the remote SMTP server response. Clock's ticking ⏰.

Specify a non-zero time value — that's an integral value plus an optional one-letter suffix that says which time unit you mean. The units, bestie: s (seconds), m (minutes), h (hours), d (days), w (weeks). The default time unit is s (seconds).

Available in Postfix 2.1 and later. ✨

`smtpd_authorized_verp_clients` (default: `$authorized_verp_clients`)

Which remote SMTP clients are allowed to specify the XVERP command. That command requests that mail be delivered one recipient at a time, with a per recipient return address. So yeah, it's a whole thing. 🎀

By default, no clients are allowed to specify XVERP.

This parameter was renamed with Postfix version 2.1. The default value is backwards compatible with Postfix version 2.0. Glow-up complete 👑

Specify a list of network/netmask patterns, separated by commas and/or whitespace. The mask specifies the number of bits in the network part of a host address. You can also specify hostnames or .domain names (the initial dot causes the domain to match any name below it), "/file/name" or "type:table" patterns. A "/file/name" pattern is replaced by its contents; a "type:table" lookup table is matched when a table entry matches a lookup string (the lookup result is ignored). Continue long lines by starting the next line with whitespace. Specify "!pattern" to exclude an address or network block from the list. The form "!/file/name" is supported only in Postfix version 2.4 and later.

Note: IP version 6 address information must be specified inside [] in the smtpd_authorized_verp_clients value, and in files specified with "/file/name". IP version 6 addresses contain the ":" character, and would otherwise be confused with a "type:table" pattern. Not the vibes we want 💀

`smtpd_authorized_xclient_hosts` (default: `empty`)

Which remote SMTP clients are allowed to use the XCLIENT feature. This command overrides remote SMTP client information that is used for access control. Typical use is for SMTP-based content filters, fetchmail-like programs, or SMTP server access rule testing. See the XCLIENT_README document for details 🔍.

This feature is available in Postfix 2.1 and later.

By default, no clients are allowed to specify XCLIENT.

Specify a list of network/netmask patterns, separated by commas and/or whitespace. The mask specifies the number of bits in the network part of a host address. You can also specify hostnames or .domain names (the initial dot causes the domain to match any name below it), "/file/name" or "type:table" patterns. A "/file/name" pattern is replaced by its contents; a "type:table" lookup table is matched when a table entry matches a lookup string (the lookup result is ignored). Continue long lines by starting the next line with whitespace. Specify "!pattern" to exclude an address or network block from the list. The form "!/file/name" is supported only in Postfix version 2.4 and later.

Note: IP version 6 address information must be specified inside [] in the smtpd_authorized_xclient_hosts value, and in files specified with "/file/name". IP version 6 addresses contain the ":" character, and would otherwise be confused with a "type:table" pattern. 🦋

`smtpd_authorized_xforward_hosts` (default: `empty`)

Which remote SMTP clients are allowed to use the XFORWARD feature. This command forwards information that is used to improve logging after SMTP-based content filters. See the XFORWARD_README document for details 📋.

This feature is available in Postfix 2.1 and later.

By default, no clients are allowed to specify XFORWARD.

Specify a list of network/netmask patterns, separated by commas and/or whitespace. The mask specifies the number of bits in the network part of a host address. You can also specify hostnames or .domain names (the initial dot causes the domain to match any name below it), "/file/name" or "type:table" patterns. A "/file/name" pattern is replaced by its contents; a "type:table" lookup table is matched when a table entry matches a lookup string (the lookup result is ignored). Continue long lines by starting the next line with whitespace. Specify "!pattern" to exclude an address or network block from the list. The form "!/file/name" is supported only in Postfix version 2.4 and later.

Note: IP version 6 address information must be specified inside [] in the smtpd_authorized_xforward_hosts value, and in files specified with "/file/name". IP version 6 addresses contain the ":" character, and would otherwise be confused with a "type:table" pattern. 🌈

`smtpd_banner` (default: `$myhostname ESMTP $mail_name`)

The text that follows the 220 status code in the SMTP greeting banner. Some people like to see the mail version advertised 👀. By default, Postfix shows no version — mysterious, iconic, love that for us.

You MUST specify $myhostname at the start of the text. This is required by the SMTP protocol, like, non-negotiable bestie 🫶.

Example:

smtpd_banner = $myhostname ESMTP $mail_name ($mail_version)

`smtpd_client_auth_rate_limit` (default: `0`)

The maximal number of AUTH commands that any client is allowed to send to this service per time unit, regardless of whether or not Postfix actually accepts those commands. The time unit is specified with the anvil_rate_time_unit configuration parameter ⏳.

By default, there is no limit on the number of AUTH commands that a client may send.

To disable this feature, specify a limit of 0.

WARNING: The purpose of this feature is to limit abuse. It must not be used to regulate legitimate mail traffic. Fr fr, don't do it 🙈

This feature is available in Postfix 3.1 and later.

`smtpd_client_connection_count_limit` (default: `50`)

How many simultaneous connections any client is allowed to make to this service. By default, the limit is set to half the default process limit value. Half! Math 💅

To disable this feature, specify a limit of 0.

WARNING: The purpose of this feature is to limit abuse. It must not be used to regulate legitimate mail traffic.

This feature is available in Postfix 2.2 and later.

`smtpd_client_connection_limit_exceptions` (default: `$mynetworks`)

Renamed to smtpd_client_event_limit_exceptions in Postfix 2.2. That's it, that's the whole entry — a lil name change story 🎀

`smtpd_client_connection_rate_limit` (default: `0`)

The maximal number of connection attempts any client is allowed to make to this service per time unit. The time unit is specified with the anvil_rate_time_unit configuration parameter ⏱️.

By default, a client can make as many connections per time unit as Postfix can accept.

To disable this feature, specify a limit of 0.

WARNING: The purpose of this feature is to limit abuse. It must not be used to regulate legitimate mail traffic.

This feature is available in Postfix 2.2 and later.

Example:

smtpd_client_connection_rate_limit = 1000

`smtpd_client_event_limit_exceptions` (default: `$mynetworks`)

Clients that are excluded from smtpd_client_*_count/rate_limit restrictions. See the mynetworks parameter description for the parameter value syntax 👑.

By default, clients in trusted networks are excluded. Specify a list of network blocks, hostnames or .domain names (the initial dot causes the domain to match any name below it).

Note: IP version 6 address information must be specified inside [] in the smtpd_client_event_limit_exceptions value, and in files specified with "/file/name". IP version 6 addresses contain the ":" character, and would otherwise be confused with a "type:table" pattern. 💀

Pattern matching of domain names is controlled by the presence or absence of "smtpd_client_event_limit_exceptions" in the parent_domain_matches_subdomains parameter value (Postfix 3.0 and later).

This feature is available in Postfix 2.2 and later.

`smtpd_client_ipv4_prefix_length` (default: `32`)

Aggregate smtpd_client_*_count and smtpd_client_*_rate statistics by IPv4 network blocks with the specified network prefix. Aggregation uses fewer anvil(8) resources to maintain counters 🧚. By default, aggregation is disabled for IPv4.

This feature is available in Postfix 3.8 and later.

`smtpd_client_ipv6_prefix_length` (default: `84`)

Aggregate smtpd_client_*_count and smtpd_client_*_rate statistics by IPv6 network blocks with the specified network prefix. Aggregation uses fewer anvil(8) resources to maintain counters 🧚. By default, aggregation is enabled for IPv6.

This feature is available in Postfix 3.8 and later.

`smtpd_client_message_rate_limit` (default: `0`)

The maximal number of message delivery requests that any client is allowed to make to this service per time unit, regardless of whether or not Postfix actually accepts those messages. The time unit is specified with the anvil_rate_time_unit configuration parameter ⏳.

By default, a client can send as many message delivery requests per time unit as Postfix can accept.

To disable this feature, specify a limit of 0.

WARNING: The purpose of this feature is to limit abuse. It must not be used to regulate legitimate mail traffic. Periodt.

This feature is available in Postfix 2.2 and later.

Example:

smtpd_client_message_rate_limit = 1000

`smtpd_client_new_tls_session_rate_limit` (default: `0`)

The maximal number of new (i.e., uncached) TLS sessions that a remote SMTP client is allowed to negotiate with this service per time unit. The time unit is specified with the anvil_rate_time_unit configuration parameter 🔐.

By default, a remote SMTP client can negotiate as many new TLS sessions per time unit as Postfix can accept.

To disable this feature, specify a limit of 0. Otherwise, specify a limit that is at least the per-client concurrent session limit, or else legitimate client sessions may be rejected 😭. Yeah, that's the catch.

WARNING: The purpose of this feature is to limit abuse. It must not be used to regulate legitimate mail traffic.

This feature is available in Postfix 2.3 and later.

Example:

smtpd_client_new_tls_session_rate_limit = 100

smtpd_client_port_logging (default: no) — okay so this one is a lil glow-up for your logs ✨ turn it on and Postfix logs the remote SMTP client's port too, not just the hostname and IP. The format it spits out is literally "host[address]:port".

This feature is available in Postfix 2.5 and later.

smtpd_client_recipient_rate_limit (default: 0) — this is the max number of recipient addresses any one client can send to this service per time unit, and it counts regardless of whether Postfix actually accepts those recipients or not 👀. The time unit comes from the anvil_rate_time_unit configuration parameter.

By default, a client can send as many recipient addresses per time unit as Postfix can accept. Periodt.

To disable this feature, specify a limit of 0.

WARNING: The purpose of this feature is to limit abuse. It must not be used to regulate legitimate mail traffic. fr fr, it's an abuse brake, not a traffic cop 🚨

This feature is available in Postfix 2.2 and later.

Example:

smtpd_client_recipient_rate_limit = 1000

smtpd_client_restrictions (default: empty) — optional restrictions that the Postfix SMTP server applies in the context of a client connection request 💅. See SMTPD_ACCESS_README, section "Delayed evaluation of SMTP access restriction lists" for a discussion of evaluation context and time.

The default is to allow all connection requests. no cap.

Specify a list of restrictions, separated by commas and/or whitespace. Continue long lines by starting the next line with whitespace. Restrictions are applied in the order as specified; the first restriction that matches wins.

The following restrictions are specific to client hostname or client network address information 👇

check_ccert_access type:table — By default use the remote SMTP client certificate fingerprint or the public key fingerprint (Postfix 2.9 and later) as the lookup key for the specified access(5) database; with Postfix version 2.2, also require that the remote SMTP client certificate is verified successfully. The fingerprint digest algorithm is configurable via the smtpd_tls_fingerprint_digest parameter (hard-coded as md5 prior to Postfix version 2.5). This feature requires "smtpd_tls_ask_ccert = yes" and is available with Postfix version 2.2 and later.

The default algorithm is sha256 with Postfix >= 3.6 and the compatibility_level set to 3.6 or higher. With Postfix <= 3.5, the default algorithm is md5. The best-practice algorithm is now sha256. Recent advances in hash function cryptanalysis have led to md5 and sha1 being deprecated in favor of sha256. However, as long as there are no known "second pre-image" attacks against the older algorithms, their use in this context, though not recommended, is still likely safe.

Alternatively, check_ccert_access accepts an explicit search order (Postfix 3.5 and later). The default search order as described above corresponds with:

check_ccert_access { type:table, { search_order =
cert_fingerprint, pubkey_fingerprint } }

The commas are optional.

check_client_access type:table — Search the specified access database for the client hostname or IP address. See the access(5) manual page for details.
check_client_a_access type:table — Search the specified access(5) database for the IP addresses for the client hostname, and execute the corresponding action. Note: a result of "OK" is not allowed for safety reasons 🫣. Instead, use DUNNO in order to exclude specific hosts from denylists. This feature is available in Postfix 3.0 and later.
check_client_mx_access type:table — Search the specified access(5) database for the MX hosts for the client hostname, and execute the corresponding action. If no MX record is found, look up A or AAAA records, just like the Postfix SMTP client would. Note: a result of "OK" is not allowed for safety reasons 🫣. Instead, use DUNNO in order to exclude specific hosts from denylists. This feature is available in Postfix 2.7 and later.
check_client_ns_access type:table — Search the specified access(5) database for the DNS servers for the client hostname, and execute the corresponding action. Note: a result of "OK" is not allowed for safety reasons 🫣. Instead, use DUNNO in order to exclude specific hosts from denylists. This feature is available in Postfix 2.7 and later.
check_reverse_client_hostname_access type:table — Search the specified access database for the unverified reverse client hostname or IP address. See the access(5) manual page for details. Note: a result of "OK" is not allowed for safety reasons 🫣. Instead, use DUNNO in order to exclude specific hosts from denylists. This feature is available in Postfix 2.6 and later.
check_reverse_client_hostname_a_access type:table — Search the specified access(5) database for the IP addresses for the unverified reverse client hostname, and execute the corresponding action. Note: a result of "OK" is not allowed for safety reasons 🫣. Instead, use DUNNO in order to exclude specific hosts from denylists. This feature is available in Postfix 3.0 and later.
check_reverse_client_hostname_mx_access type:table — Search the specified access(5) database for the MX hosts for the unverified reverse client hostname, and execute the corresponding action. If no MX record is found, look up A or AAAA records, just like the Postfix SMTP client would. Note: a result of "OK" is not allowed for safety reasons 🫣. Instead, use DUNNO in order to exclude specific hosts from denylists. This feature is available in Postfix 2.7 and later.
check_reverse_client_hostname_ns_access type:table — Search the specified access(5) database for the DNS servers for the unverified reverse client hostname, and execute the corresponding action. Note: a result of "OK" is not allowed for safety reasons 🫣. Instead, use DUNNO in order to exclude specific hosts from denylists. This feature is available in Postfix 2.7 and later.
check_sasl_access type:table — Use the remote SMTP client SASL user name as the lookup key for the specified access(5) database. The lookup key has the form "username@domainname" when the smtpd_sasl_local_domain parameter value is non-empty. Unlike the check_client_access feature, check_sasl_access does not perform matches of parent domains or IP subnet ranges. This feature is available with Postfix version 2.11 and later.
permit_inet_interfaces — Permit the request when the client IP address matches $inet_interfaces.
permit_mynetworks — Permit the request when the client IP address matches any network or network address listed in $mynetworks.
permit_sasl_authenticated — Permit the request when the client is successfully authenticated via the RFC 4954 (AUTH) protocol. 🔐
permit_tls_all_clientcerts — Permit the request when the remote SMTP client certificate is verified successfully. This option must be used only if a special CA issues the certificates and only this CA is listed as a trusted CA. Otherwise, clients with a third-party certificate would also be allowed to relay 😭. Specify "tls_append_default_CA = no" when the trusted CA is specified with smtpd_tls_CAfile or smtpd_tls_CApath, to prevent Postfix from appending the system-supplied default CAs. This feature requires "smtpd_tls_ask_ccert = yes" and is available with Postfix version 2.2 and later.
permit_tls_clientcerts — Permit the request when the remote SMTP client certificate fingerprint or public key fingerprint (Postfix 2.9 and later) is listed in $relay_clientcerts. The fingerprint digest algorithm is configurable via the smtpd_tls_fingerprint_digest parameter (hard-coded as md5 prior to Postfix version 2.5). This feature requires "smtpd_tls_ask_ccert = yes" and is available with Postfix version 2.2 and later.

reject_rbl_client rbl_domain=d.d.d.d — Reject the request when the reversed client network address is listed with the A record "d.d.d.d" under rbl_domain (Postfix version 2.1 and later only). Each "d" is a number, or a pattern inside "[]" that contains one or more ";"-separated numbers or number..number ranges (Postfix version 2.8 and later). If no "=d.d.d.d" is specified, reject the request when the reversed client network address is listed with any A record under rbl_domain.

The maps_rbl_reject_code parameter specifies the response code for rejected requests (default: 554), the default_rbl_reply parameter specifies the default server reply, and the rbl_reply_maps parameter specifies tables with server replies indexed by rbl_domain.

NOTE: Always respect the usage policies of reputation services. Avoid public or ISP resolvers, unless the queries use your unique API key (see rbl_reply_maps for how to avoid leaking the key in SMTP server responses). pls don't be the person who leaks their API key in the SMTP response 🙈

This feature is available in Postfix 2.0 and later.

`permit_dnswl_client` dnswl_domain=d.d.d.d

Accept the request when the reversed client network address is listed with the A record "d.d.d.d" under dnswl_domain. Each d is a number, or a pattern inside "[]" that holds one or more ";"-separated numbers or number..number ranges. If you don't specify =d.d.d.d, then bestie, it accepts whenever the reversed client network address is listed with any A record under dnswl_domain. Slay.

For safety, permit_dnswl_client is silently ignored when it would override reject_unauth_destination. The result is DEFER_IF_REJECT when the allowlist lookup fails. 🫶

NOTE: Always respect the usage policies of reputation services. Avoid public or ISP resolvers, unless the queries use your unique API key (see rbl_reply_maps for how to avoid leaking an API key in SMTP server responses).

This feature is available in Postfix 2.8 and later. ✨

`reject_rhsbl_client` rbl_domain=d.d.d.d

Reject the request when the client hostname is listed with the A record "d.d.d.d" under rbl_domain (Postfix version 2.1 and later only, no cap). Each d is a number, or a pattern inside "[]" containing one or more ";"-separated numbers or number..number ranges (Postfix version 2.8 and later). If no =d.d.d.d is specified, it rejects when the client hostname is listed with any A record under rbl_domain. See the reject_rbl_client description above for additional RBL related configuration parameters. iykyk 💅

NOTE: Always respect the usage policies of reputation services. Avoid public or ISP resolvers, unless the queries use your unique API key (see rbl_reply_maps for how to avoid leaking an API key in SMTP server responses).

This feature is available in Postfix 2.0 and later; with Postfix version 2.8 and later, reject_rhsbl_reverse_client will usually produce better results. Lowkey an upgrade, ngl.

`permit_rhswl_client` rhswl_domain=d.d.d.d

Accept the request when the client hostname is listed with the A record "d.d.d.d" under rhswl_domain. Each d is a number, or a pattern inside "[]" containing one or more ";"-separated numbers or number..number ranges. If no =d.d.d.d is specified, accept the request when the client hostname is listed with any A record under rhswl_domain.

Caution: client name allowlisting is fragile, since the client name lookup can fail due to temporary outages. Client name allowlisting should be used only to reduce false positives in e.g. DNS-based blocklists, and not for making access rule exceptions. Fr fr, don't do it.

For safety, permit_rhswl_client is silently ignored when it would override reject_unauth_destination. The result is DEFER_IF_REJECT when the allowlist lookup fails. 😭

NOTE: Always respect the usage policies of reputation services. Avoid public or ISP resolvers, unless the queries use your unique API key (see rbl_reply_maps for how to avoid leaking an API key in SMTP server responses).

This feature is available in Postfix 2.8 and later. 🌸

`reject_rhsbl_reverse_client` rbl_domain=d.d.d.d

Reject the request when the unverified reverse client hostname is listed with the A record "d.d.d.d" under rbl_domain. Each d is a number, or a pattern inside "[]" that contains one or more ";"-separated numbers or number..number ranges. If no =d.d.d.d is specified, reject the request when the unverified reverse client hostname is listed with any A record under rbl_domain. See the reject_rbl_client description above for additional RBL related configuration parameters.

NOTE: Always respect the usage policies of reputation services. Avoid public or ISP resolvers, unless the queries use your unique API key (see rbl_reply_maps for how to avoid leaking an API key in SMTP server responses).

This feature is available in Postfix 2.8 and later. ✨

`reject_unknown_client_hostname` (with Postfix < 2.3: `reject_unknown_client`)

Reject the request when:

the client IP address->name mapping fails, or
the name->address mapping fails, or
the name->address mapping does not match the client IP address.

This is a stronger restriction than the reject_unknown_reverse_client_hostname feature, which triggers only under condition 1) above. It's giving extra credit requirements tbh. 💀

The unknown_client_reject_code parameter specifies the response code for rejected requests (default: 450). The reply is always 450 in case the address->name or name->address lookup failed due to a temporary problem.

`reject_unknown_reverse_client_hostname`

Reject the request when the client IP address has no address->name mapping. 🚫

This is a weaker restriction than the reject_unknown_client_hostname feature, which requires not only that the address->name and name->address mappings exist, but also that the two mappings reproduce the client IP address.

The unknown_client_reject_code parameter specifies the response code for rejected requests (default: 450). The reply is always 450 in case the address->name lookup failed due to a temporary problem.

This feature is available in Postfix 2.3 and later. 🦋

In addition, you can use any of the following generic restrictions. These restrictions are applicable in any SMTP command context. Iconic behavior honestly.

`check_policy_service` servername

Query the specified policy server. See the SMTPD_POLICY_README document for details. This feature is available in Postfix 2.1 and later.

`defer`

Defer the request. The client is told to try again later. This restriction is useful at the end of a restriction list, to make the default policy explicit.

The defer_code parameter specifies the SMTP server reply code (default: 450).

`defer_if_permit`

Defer the request if some later restriction would result in an explicit or implicit PERMIT action. This is useful when a denylisting feature fails due to a temporary problem. This feature is available in Postfix version 2.1 and later.

`defer_if_reject`

Defer the request if some later restriction would result in a REJECT action. This is useful when an allowlisting feature fails due to a temporary problem. This feature is available in Postfix version 2.1 and later.

`permit`

Permit the request. This restriction is useful at the end of a restriction list, to make the default policy explicit.

`reject_multi_recipient_bounce`

Reject the request when the envelope sender is the null address, and the message has multiple envelope recipients. This usage has rare but legitimate applications: under certain conditions, multi-recipient mail that was posted with the DSN option NOTIFY=NEVER may be forwarded with the null sender address.

Note: this restriction can only work reliably when used in smtpd_data_restrictions or smtpd_end_of_data_restrictions, because the total number of recipients is not known at an earlier stage of the SMTP conversation. Use at the RCPT stage will only reject the second etc. recipient. 🙈

The multi_recipient_bounce_reject_code parameter specifies the response code for rejected requests (default: 550). This feature is available in Postfix 2.1 and later.

`reject_plaintext_session`

Reject the request when the connection is not encrypted. This restriction should not be used before the client has had a chance to negotiate encryption with the AUTH or STARTTLS commands.

The plaintext_reject_code parameter specifies the response code for rejected requests (default: 450). This feature is available in Postfix 2.3 and later.

`reject_unauth_pipelining`

Reject the request when the client sends SMTP commands ahead of time where it is not allowed, or when the client sends SMTP commands ahead of time without knowing that Postfix actually supports ESMTP command pipelining. This stops mail from bulk mail software that improperly uses ESMTP command pipelining in order to speed up deliveries. 🚫💨

With Postfix 2.6 and later, the SMTP server sets a per-session flag whenever it detects illegal pipelining, including pipelined HELO or EHLO commands. The reject_unauth_pipelining feature simply tests whether the flag was set at any point in time during the session.

With older Postfix versions, reject_unauth_pipelining checks the current status of the input read queue, and its usage is not recommended in contexts other than smtpd_data_restrictions.

`reject`

Reject the request. This restriction is useful at the end of a restriction list, to make the default policy explicit. The reject_code configuration parameter specifies the response code for rejected requests (default: 554).

`sleep` seconds

Pause for the specified number of seconds and proceed with the next restriction in the list, if any. This may stop zombie mail when used as:

/etc/postfix/main.cf:
    smtpd_client_restrictions =
        sleep 1, reject_unauth_pipelining
    smtpd_delay_reject = no

This feature is available in Postfix 2.3.

`warn_if_reject`

A safety net for testing. When "warn_if_reject" is placed before a reject-type restriction, access table query, or check_policy_service query, this logs a "reject_warning" message instead of rejecting a request (when a reject-type restriction fails due to a temporary error, this logs a "reject_warning" message for any implicit "defer_if_permit" actions that would normally prevent mail from being accepted by some later access restriction). This feature has no effect on defer_if_reject restrictions. 👑

Other restrictions that are valid in this context:

SMTP command specific restrictions that are described under the smtpd_helo_restrictions, smtpd_sender_restrictions or smtpd_recipient_restrictions parameters. When helo, sender or recipient restrictions are listed under smtpd_client_restrictions, they have effect only with "smtpd_delay_reject = yes", so that $smtpd_client_restrictions is evaluated at the time of the RCPT TO command.

Example:

smtpd_client_restrictions = permit_mynetworks, reject_unknown_client_hostname

💌 `smtpd_command_filter` (default: empty)

OK so bestie, this one is a glow-up machine for incoming SMTP commands ✨. It transforms commands that remote SMTP clients send you. This is a last-resort tool — like, the "in case of emergency, break glass" of interop fixes — meant to work around client commands that break interoperability with the Postfix SMTP server. Other uses involve fault injection to test how Postfix handles invalid commands. 🧪

Specify the name of a "type:table" lookup table. The search string is the SMTP command as received from the remote SMTP client, except that initial whitespace and the trailing <CR><LF> are removed. The result value is executed by the Postfix SMTP server. 🔥

Lowkey, there is no need to use smtpd_command_filter for the following cases:

Use resolve_numeric_domain = yes to accept user@ipaddress. 🍓
Postfix already accepts the correct form user@[ipaddress]. Use virtual_alias_maps or canonical_maps to translate these into domain names if necessary.
Use strict_rfc821_envelopes = no to accept RCPT TO:<User Name <user@example.com>>. Postfix will ignore the "User Name" part and deliver to the <user@example.com> address. 💅

Examples of problems that can be solved with the smtpd_command_filter feature:

/etc/postfix/main.cf:
    smtpd_command_filter = pcre:/etc/postfix/command_filter

/etc/postfix/command_filter:
    # Work around clients that send malformed HELO commands.
    /^HELO\s*$/ HELO domain.invalid

    # Work around clients that send empty lines.
    /^\s*$/     NOOP

    # Work around clients that send RCPT TO:<'user@domain'>.
    # WARNING: do not lose the parameters that follow the address.
    /^(RCPT\s+TO:\s*<)'([^[:space:]]+)'(>.*)/     $1$2$3

    # Append XVERP to MAIL FROM commands to request VERP-style delivery.
    # See VERP_README for more information on how to use Postfix VERP.
    /^(MAIL\s+FROM:\s*<listname@example\.com>.*)/   $1 XVERP

    # Bounce-never mail sink. Use notify_classes=bounce,resource,software
    # to send bounced mail to the postmaster (with message body removed).
    /^(RCPT\s+TO:\s*<.*>.*)\s+NOTIFY=\S+(.*)/     $1 NOTIFY=NEVER$2
    /^(RCPT\s+TO:.*)/                             $1 NOTIFY=NEVER

⚠️ Note the WARNING in that third example: do not lose the parameters that follow the address. The regex keeps $1$2$3 for a reason, bestie. Don't get cute with it. 😭

This feature is available in Postfix 2.7. 🎀

🚦 `smtpd_data_restrictions` (default: empty)

Optional access restrictions that the Postfix SMTP server applies in the context of the SMTP DATA command. See SMTPD_ACCESS_README, section "Delayed evaluation of SMTP access restriction lists" for a discussion of evaluation context and time. ⏰

This feature is available in Postfix 2.0 and later.

The following restrictions are valid in this context:

Generic restrictions that can be used in any SMTP command context, described under smtpd_client_restrictions.
SMTP command specific restrictions described under smtpd_client_restrictions, smtpd_helo_restrictions, smtpd_sender_restrictions or smtpd_recipient_restrictions.
However, no recipient information is available in the case of multi-recipient mail. Acting on only one recipient would be misleading, because any decision will affect all recipients equally. Acting on all recipients would require a possibly very large amount of memory, and would also be misleading for the reasons mentioned before. 💀

Examples:

smtpd_data_restrictions = reject_unauth_pipelining
smtpd_data_restrictions = reject_multi_recipient_bounce

⏳ `smtpd_delay_open_until_valid_rcpt` (default: yes)

Postpone the start of an SMTP mail transaction until a valid RCPT TO command is received. Specify no to create a mail transaction as soon as the Postfix SMTP server receives a valid MAIL FROM command. 🫶

With sites that reject lots of mail, the default setting reduces the use of disk, CPU and memory resources. The downside is that rejected recipients are logged with NOQUEUE instead of a mail transaction ID (also known as a queue ID). 🙈

This feature is available in Postfix 2.3 and later.

🕰️ `smtpd_delay_reject` (default: yes)

Wait until the RCPT TO command before evaluating $smtpd_client_restrictions, $smtpd_helo_restrictions and $smtpd_sender_restrictions, or wait until the ETRN command before evaluating $smtpd_client_restrictions and $smtpd_helo_restrictions. ⏲️

This feature is turned on by default because some clients apparently mis-behave when the Postfix SMTP server rejects commands before RCPT TO. 😬

The default setting has one major benefit: it allows Postfix to log recipient address information when rejecting a client name/address or sender address, so that it is possible to find out whose mail is being rejected. 🔍 Iconic, honestly.

🎯 `smtpd_discard_ehlo_keyword_address_maps` (default: empty)

Lookup tables, indexed by the remote SMTP client address, with case insensitive lists of EHLO keywords (pipelining, starttls, auth, etc.) that the Postfix SMTP server will not send in the EHLO response to a remote SMTP client. See smtpd_discard_ehlo_keywords for details. The tables are not searched by hostname for robustness reasons. 🛡️

Specify zero or more "type:name" lookup tables, separated by whitespace or comma. Tables will be searched in the specified order until a match is found.

This feature is available in Postfix 2.2 and later.

🤫 `smtpd_discard_ehlo_keywords` (default: empty)

A case insensitive list of EHLO keywords (pipelining, starttls, auth, etc.) that the Postfix SMTP server will not send in the EHLO response to a remote SMTP client. Keep it mysterious, bestie. 💅

This feature is available in Postfix 2.2 and later.

Notes:

Specify the silent-discard pseudo keyword to prevent this action from being logged. 🤐
Use the smtpd_discard_ehlo_keyword_address_maps feature to discard EHLO keywords selectively.

🔎 `smtpd_dns_reply_filter` (default: empty)

Optional filter for Postfix SMTP server DNS lookup results. See smtp_dns_reply_filter for details including an example. 📡

This feature is available in Postfix 3.0 and later.

🏁 `smtpd_end_of_data_restrictions` (default: empty)

Optional access restrictions that the Postfix SMTP server applies in the context of the SMTP END-OF-DATA command. See SMTPD_ACCESS_README, section "Delayed evaluation of SMTP access restriction lists" for a discussion of evaluation context and time. 🕐

This feature is available in Postfix 2.2 and later.

See smtpd_data_restrictions for details and limitations. (Yes, same energy, same caveats — go read that one, it's right up there. ⬆️)

🔐 `smtpd_enforce_tls` (default: no)

Mandatory TLS: announce STARTTLS support to remote SMTP clients, and reject all plaintext commands except HELO, EHLO, XCLIENT, STARTTLS, NOOP, QUIT, and (Postfix >= 3.9) HELP. According to RFC 2487 this MUST NOT be applied in case of a publicly-referenced SMTP server. Instead, this should be used on dedicated servers, for example submission (port 587). This option is therefore off by default. 🚫🌍

Note 1: smtpd_enforce_tls = yes implies smtpd_tls_auth_only = yes.

Note 2: when invoked via sendmail -bs, Postfix will never offer STARTTLS due to insufficient privileges to access the server private key. This is intended behavior. 🔑

💀 This feature is deprecated as of Postfix 3.9. Specify smtpd_tls_security_level instead.

This feature is available in Postfix 2.2 and later. With Postfix 2.3 and later use smtpd_tls_security_level instead.

😴 `smtpd_error_sleep_time` (default: 1s)

With Postfix version 2.1 and later: the SMTP server response delay after a client has made more than $smtpd_soft_error_limit errors, and fewer than $smtpd_hard_error_limit errors, without delivering mail. 🐢

With Postfix version 2.0 and earlier: the SMTP server delay before sending a reject (4xx or 5xx) response, when the client has made fewer than $smtpd_soft_error_limit errors without delivering mail. When the client has made $smtpd_soft_error_limit or more errors, delay all responses with the larger of (number of errors) seconds or $smtpd_error_sleep_time. ⏱️

📬 `smtpd_etrn_restrictions` (default: empty)

Optional restrictions that the Postfix SMTP server applies in the context of a client ETRN command. See SMTPD_ACCESS_README, section "Delayed evaluation of SMTP access restriction lists" for a discussion of evaluation context and time. ⏳

The Postfix ETRN implementation accepts only destinations that are eligible for the Postfix "fast flush" service. See the ETRN_README file for details. 🚿

The following restrictions are specific to the domain name information received with the ETRN command.

🔍 `check_etrn_access` type:table

Search the specified access database for the ETRN domain name. See the access(5) manual page for details. 📖

Other restrictions that are valid in this context:

Generic restrictions that can be used in any SMTP command context, described under smtpd_client_restrictions.
SMTP command specific restrictions described under smtpd_client_restrictions and smtpd_helo_restrictions.

Example:

smtpd_etrn_restrictions = permit_mynetworks, reject

🌸 `smtpd_expansion_filter` (default: see `postconf -d` output)

What characters are allowed in $name expansions of RBL reply templates. Characters not in the allowed set are replaced by "_". Use C like escapes to specify special characters such as whitespace. 🎀

The smtpd_expansion_filter value is not subject to Postfix configuration parameter $name expansion. (No inception happening here, bestie. 🌀)

This feature is available in Postfix 2.0 and later.

smtpd_forbid_bare_newline (default: Postfix >= 3.9: normalize) — okay bestie this one is the ✨important✨ one. It decides whether the server rejects or just tolerates input lines from an SMTP client that end in a bare <LF> instead of the standard <CR><LF>. UNIX-based SMTP servers commonly allow those bare line endings, but it's a whole RFC 5321 violation, and letting them slide can make your server vulnerable to SMTP smuggling. Big yikes. So you pick one of these values (case does NOT matter, we're not picky):
- normalize (default for Postfix >= 3.9) — require the standard End-of-DATA sequence <CR><LF>.<CR><LF>. Otherwise, allow command or message content lines that end in the non-standard <LF>, and process them as if the client sent the standard <CR><LF>. This keeps you compatible with the many legit SMTP client applications that send a mix of standard and non-standard line endings, but it will fail to receive email from client implementations that don't terminate DATA content with the standard End-of-DATA sequence <CR><LF>.<CR><LF>. Those clients can be excluded with smtpd_forbid_bare_newline_exclusions.
- note — same as normalize, but it also notes in the log whether the Postfix SMTP server received any lines with "bare <LF>". The information is formatted as "disconnect from name[address] ... notes=bare_lf". The notes value is expected to become a list of comma-separated names. This feature is available in Postfix 3.9 and later.
- yes — compatibility alias for normalize. slay, same thing, different name 💅
- reject — require the standard End-of-DATA sequence <CR><LF>.<CR><LF>. Reject a command or message content when a line contains bare <LF>, log a "bare <LF> received" error, and reply with the SMTP status code in $smtpd_forbid_bare_newline_reject_code. This will reject email from SMTP clients that send any non-standard line endings such as web applications, netcat, or load balancer health checks. This will also reject email from services that use BDAT to send MIME text containing a bare newline (RFC 3030 Section 3 requires canonical MIME format for text message types, defined in RFC 2045 Sections 2.7 and 2.8). Such clients can be excluded with smtpd_forbid_bare_newline_exclusions (or, in the case of BDAT violations, BDAT can be selectively disabled with smtpd_discard_ehlo_keyword_address_maps, or globally disabled with smtpd_discard_ehlo_keywords).
- no (default for Postfix < 3.9) — do not require the standard End-of-DATA sequence <CR><LF>.<CR><LF>. Always process a bare <LF> as if the client sent <CR><LF>. This option is fully backwards compatible, but it is not recommended for an Internet-facing SMTP server, because it is vulnerable to SMTP smuggling. 💀 fr fr don't do this on the public internet.

Recommended settings:

# Require the standard End-of-DATA sequence <CR><LF>.<CR><LF>.
# Otherwise, allow bare <LF> and process it as if the client sent
# <CR><LF>.
#
# This maintains compatibility with many legitimate SMTP client
# applications that send a mix of standard and non-standard line
# endings, but will fail to receive email from client implementations
# that do not terminate DATA content with the standard End-of-DATA
# sequence <CR><LF>.<CR><LF>.
#
# Such clients can be allowlisted with smtpd_forbid_bare_newline_exclusions.
# The example below allowlists SMTP clients in trusted networks.
#
smtpd_forbid_bare_newline = normalize
smtpd_forbid_bare_newline_exclusions = $mynetworks

Alternative:

# Reject input lines that contain <LF> and log a "bare <LF> received"
# error. Require that input lines end in <CR><LF>, and require the
# standard End-of-DATA sequence <CR><LF>.<CR><LF>.
#
# This will reject email from SMTP clients that send any non-standard
# line endings such as web applications, netcat, or load balancer
# health checks.
#
# This will also reject email from services that use BDAT to send
# MIME text containing a bare newline (RFC 3030 Section 3 requires
# canonical MIME format for text message types, defined in RFC 2045
# Sections 2.7 and 2.8).
#
# Such clients can be allowlisted with smtpd_forbid_bare_newline_exclusions.
# The example below allowlists SMTP clients in trusted networks.
#
smtpd_forbid_bare_newline = reject
smtpd_forbid_bare_newline_exclusions = $mynetworks
#
# Alternatively, in the case of BDAT violations, BDAT can be selectively
# disabled with smtpd_discard_ehlo_keyword_address_maps, or globally
# disabled with smtpd_discard_ehlo_keywords.
#
# smtpd_discard_ehlo_keyword_address_maps = cidr:/path/to/file
# /path/to/file:
#     10.0.0.0/24 chunking, silent-discard
# smtpd_discard_ehlo_keywords = chunking, silent-discard

This feature with settings yes and no is available in Postfix 3.8.4, 3.7.9, 3.6.13, and 3.5.23. Additionally, the settings reject, and normalize are available with Postfix >= 3.9, 3.8.5, 3.7.10, 3.6.14, and 3.5.24.

smtpd_forbid_bare_newline_exclusions (default: $mynetworks) — exclude the specified clients from smtpd_forbid_bare_newline enforcement 🫶 the allowlist, basically. This setting uses the same syntax and parent-domain matching behavior as mynetworks. This feature is available in Postfix >= 3.9, 3.8.4, 3.7.9, 3.6.13, and 3.5.23.
smtpd_forbid_bare_newline_reject_code (default: 550) — the numerical Postfix SMTP server response code when rejecting a request with "smtpd_forbid_bare_newline = reject". Specify a 5XX status code (521 to disconnect). This feature is available in Postfix >= 3.9, 3.8.5, 3.7.10, 3.6.14, and 3.5.24.

smtpd_forbid_unauth_pipelining (default: Postfix >= 3.9: yes) — disconnect remote SMTP clients that violate RFC 2920 (or 5321) command pipelining constraints 🚫 the server replies with "554 5.5.0 Error: SMTP protocol synchronization" and logs the unexpected remote SMTP client input. This feature is enabled by default with Postfix >= 3.9. Specify "smtpd_forbid_unauth_pipelining = no" to disable. This feature is available in Postfix >= 3.9, 3.8.1, 3.7.6, 3.6.10, and 3.5.20.
smtpd_forbidden_commands (default: CONNECT GET POST regexp:{{/^[^A-Z]/ Bogus}}) — list of commands that cause the Postfix SMTP server to immediately terminate the session with a 221 code 👋 this can be used to disconnect clients that obviously attempt to abuse the system. In addition to the commands listed in this parameter, commands that follow the "Label:" format of message headers will also cause a disconnect. With Postfix versions 3.6 and earlier, the default value is "CONNECT GET POST". This feature is available in Postfix 2.2 and later. Support for inline regular expressions was added in Postfix version 3.7. See regexp_table(5) for a description of the syntax and features.
smtpd_hard_error_limit (default: normal: 20, overload: 1) — the maximal number of errors a remote SMTP client is allowed to make without delivering mail. The Postfix SMTP server disconnects when the limit is reached 🚪 normally the default limit is 20, but it changes under overload to just 1. With Postfix 2.5 and earlier, the SMTP server always allows up to 20 errors by default. Valid values are greater than zero.
smtpd_helo_required (default: no) — require that a remote SMTP client introduces itself with the HELO or EHLO command before sending the MAIL command or other commands that require EHLO negotiation ✨ no skipping the intros bestie, we're not animals. Example:

smtpd_helo_required = yes

smtpd_helo_restrictions (default: empty) 💖

okay so bestie, these are the optional restrictions your Postfix SMTP server slaps onto a client's HELO command. context matters here — peep SMTPD_ACCESS_README, section "Delayed evaluation of SMTP access restriction lists" for the whole discussion of evaluation context and time. ✨

Default vibe? permit everything. everyone's welcome. 🫶

Note: say smtpd_helo_required = yes to fully enforce this restriction. without smtpd_helo_required = yes, a client can literally just skip smtpd_helo_restrictions by not sending HELO or EHLO. no cap, that's a giant loophole. 💀

You give it a list of restrictions, separated by commas and/or whitespace. Long lines? Just start the next line with whitespace and keep going. 🌸 Restrictions are applied in the order as specified; the first restriction that matches wins. periodt.

The following restrictions are specific to the hostname info that came in with the HELO or EHLO command: 👑

check_helo_access type:table — searches the specified access(5) database for the HELO or EHLO hostname, and executes the corresponding action. Note: specify smtpd_helo_required = yes to fully enforce this restriction (without smtpd_helo_required = yes, a client can simply skip check_helo_access by not sending HELO or EHLO). 🙈
check_helo_a_access type:table — searches the specified access(5) database for the IP addresses for the HELO or EHLO hostname, and executes the corresponding action. Note 1: a result of "OK" is not allowed for safety reasons — instead, use DUNNO in order to exclude specific hosts from denylists. Note 2: specify smtpd_helo_required = yes to fully enforce this restriction (without smtpd_helo_required = yes, a client can simply skip check_helo_a_access by not sending HELO or EHLO). This feature is available in Postfix 3.0 and later. ⭐
check_helo_mx_access type:table — searches the specified access(5) database for the MX hosts for the HELO or EHLO hostname, and executes the corresponding action. If no MX record is found, look up A or AAAA records, just like the Postfix SMTP client would. Note 1: a result of "OK" is not allowed for safety reasons — instead, use DUNNO in order to exclude specific hosts from denylists. Note 2: specify smtpd_helo_required = yes to fully enforce this restriction (without smtpd_helo_required = yes, a client can simply skip check_helo_mx_access by not sending HELO or EHLO). This feature is available in Postfix 2.1 and later. 🦋
check_helo_ns_access type:table — searches the specified access(5) database for the DNS servers for the HELO or EHLO hostname, and executes the corresponding action. Note 1: a result of "OK" is not allowed for safety reasons — instead, use DUNNO in order to exclude specific hosts from denylists. Note 2: specify smtpd_helo_required = yes to fully enforce this restriction (without smtpd_helo_required = yes, a client can simply skip check_helo_ns_access by not sending HELO or EHLO). This feature is available in Postfix 2.1 and later. 💅
reject_invalid_helo_hostname (with Postfix < 2.3: reject_invalid_hostname) — rejects the request when the HELO or EHLO hostname is malformed. Note: specify smtpd_helo_required = yes to fully enforce this restriction (without smtpd_helo_required = yes, a client can simply skip reject_invalid_helo_hostname by not sending HELO or EHLO). The invalid_hostname_reject_code specifies the response code for rejected requests (default: 501). 🔥
reject_non_fqdn_helo_hostname (with Postfix < 2.3: reject_non_fqdn_hostname) — rejects the request when the HELO or EHLO hostname is not in fully-qualified domain or address literal form, as required by the RFC. Note: specify smtpd_helo_required = yes to fully enforce this restriction (without smtpd_helo_required = yes, a client can simply skip reject_non_fqdn_helo_hostname by not sending HELO or EHLO). The non_fqdn_reject_code parameter specifies the response code for rejected requests (default: 504). 🎀
reject_rhsbl_helo rbl_domain=d.d.d.d — rejects the request when the HELO or EHLO hostname is listed with the A record "d.d.d.d" under rbl_domain (Postfix version 2.1 and later only). Each "d" is a number, or a pattern inside "[]" that contains one or more ";"-separated numbers or number..number ranges (Postfix version 2.8 and later). If no "=d.d.d.d" is specified, reject the request when the HELO or EHLO hostname is listed with any A record under rbl_domain. See the reject_rbl_client description for additional RBL related configuration parameters. Note: specify smtpd_helo_required = yes to fully enforce this restriction (without smtpd_helo_required = yes, a client can simply skip reject_rhsbl_helo by not sending HELO or EHLO).

NOTE: Always respect the usage policies of reputation services. Avoid public or ISP resolvers, unless the queries use your unique API key (see rbl_reply_maps for how to avoid leaking an API key in SMTP server responses). 🚨

This feature is available in Postfix 2.0 and later.

reject_unknown_helo_hostname (with Postfix < 2.3: reject_unknown_hostname) — rejects the request when the HELO or EHLO hostname has no DNS A or MX record. The reply is specified with the unknown_hostname_reject_code parameter (default: 450) or unknown_helo_hostname_tempfail_action (default: defer_if_permit). See the respective parameter descriptions for details. Note: specify smtpd_helo_required = yes to fully enforce this restriction (without smtpd_helo_required = yes, a client can simply skip reject_unknown_helo_hostname by not sending HELO or EHLO). 🌈

Other restrictions that are valid in this context: 👇

Generic restrictions that can be used in any SMTP command context, described under smtpd_client_restrictions.
Client hostname or network address specific restrictions described under smtpd_client_restrictions.
SMTP command specific restrictions described under smtpd_sender_restrictions or smtpd_recipient_restrictions. When sender or recipient restrictions are listed under smtpd_helo_restrictions, they have effect only with smtpd_delay_reject = yes, so that $smtpd_helo_restrictions is evaluated at the time of the RCPT TO command. ✨

Examples: 💫

smtpd_helo_restrictions = permit_mynetworks, reject_invalid_helo_hostname
smtpd_helo_restrictions = permit_mynetworks, reject_unknown_helo_hostname

smtpd_hide_client_session (default: no) 🙈

Do not include SMTP client session information in the Postfix SMTP server's Received: message header. sneaky but make it classy. 💅

The default setting, smtpd_hide_client_session = no, must be used for the port 25 MTA service. It provides information that is required by RFC 5321 section 4.4. 📜
The setting smtpd_hide_client_session = yes may be used for the port 587 and 465 MUA services. This hides the SMTP client hostname and IP address, TLS session details, SASL login details, and SMTP protocol details. 🕵️

Depending on the number of recipients, a redacted Received: header has one of the following forms:

Received: by mail.example.com (Postfix) id postfix-queue-id
        for <user@example.com>; Day, dd Mon yyyy hh:mm:ss tz-offset (zone)
Received: by mail.example.com (Postfix) id postfix-queue-id;
        Day, dd Mon yyyy hh:mm:ss tz-offset (zone)

The redacted form hides that a message was received with SMTP, and therefore it does not need to provide the FROM clause according to RFC 5321 section 4.4. The redacted form still meets RFC 5322 requirements. 💖

This feature is available in Postfix >= 3.10. ⭐

smtpd_history_flush_threshold (default: 100) 🧚

The maximal number of lines in the Postfix SMTP server command history before it gets flushed upon receipt of EHLO, RSET, or end of DATA. basically a memory vibe check. 🌸

smtpd_junk_command_limit (default: normal: 100, overload: 1) 💀

The number of junk commands (NOOP, VRFY, ETRN or RSET) that a remote SMTP client can send before the Postfix SMTP server starts to increment the error counter with each junk command. The junk command count gets reset after mail is delivered. 👑

See also the smtpd_error_sleep_time and smtpd_soft_error_limit configuration parameters. Normally the default limit is 100, but it changes under overload to just 1. With Postfix 2.5 and earlier, the SMTP server always allows up to 100 junk commands by default. 🔥

smtpd_log_access_permit_actions (default: empty) 🌈

Enable logging of the named "permit" actions in SMTP server access lists (by default, the SMTP server logs "reject" actions but not "permit" actions). This feature does not affect conditional actions such as defer_if_permit. 🙅

Specify a list of "permit" action names, /file/name or type:table patterns, separated by commas and/or whitespace. The list is matched left to right, and the search stops on the first match. A /file/name pattern is replaced by its contents; a type:table lookup table is matched when a name matches a lookup key (the lookup result is ignored). Continue long lines by starting the next line with whitespace. Specify !pattern to exclude a name from the list. ✨

Examples: 💫

/etc/postfix/main.cf:
    # Log all "permit" actions.
    smtpd_log_access_permit_actions = static:all

/etc/postfix/main.cf:
    # Log "permit_dnswl_client" only.
    smtpd_log_access_permit_actions = permit_dnswl_client

This feature is available in Postfix 2.10 and later. ⭐

smtpd_milter_maps (default: empty) 🦋

Lookup tables with Milter settings per remote SMTP client IP address. The lookup result overrides the smtpd_milters setting, and has the same syntax. main character energy, honestly. 👑

Note: lookup tables cannot return empty responses. Specify a lookup result of DISABLE (case does not matter) to indicate that Milter support should be disabled. 🚨

Example to disable Milters for local clients:

/etc/postfix/main.cf:
    smtpd_milter_maps = cidr:/etc/postfix/smtpd_milter_map
    smtpd_milters = inet:host:port, { inet:host:port, ... }, ...

/etc/postfix/smtpd_milter_map:
    # Disable Milters for local clients.
    127.0.0.0/8    DISABLE
    192.168.0.0/16 DISABLE
    ::/64          DISABLE
    2001:db8::/32  DISABLE

This feature is available in Postfix 3.2 and later. 💖

smtpd_milters (default: empty) 💖

okay bestie so this one is a list of Milter (mail filter) applications that get to peek at all the shiny new mail coming in through the Postfix smtpd(8) server. you separate the entries with a space or a comma, dealer's choice. the whole lore lives in the MILTER_README document, so go read that if you wanna know more.

this feature is available in Postfix 2.3 and later. ✨

smtpd_min_data_rate (default: 500) 🦋

this is the minimum plaintext data transfer rate in bytes/second for DATA and BDAT requests — but ONLY when deadlines are turned on with smtpd_per_request_deadline. here's the mechanics, stay with me:

after a read operation transfers N plaintext message bytes (yes, possibly after TLS decryption),
and after the DATA or BDAT request deadline gets decremented by however long that read took,
the DATA or BDAT request deadline gets incremented by N/smtpd_min_data_rate seconds.

BUT — and this is the important part — the deadline will never be incremented beyond the time limit you set with smtpd_timeout. no infinite generosity here. 💅

this feature is available in Postfix 3.7 and later.

smtpd_noop_commands (default: empty) 🌸

a list of commands where the Postfix SMTP server just replies "250 Ok" and moves on — no syntax checks, no state changes, nothing. it's giving "sure bestie, whatever you say." 🫶

this list overrides any commands that are built into the Postfix SMTP server itself, so it's genuinely the boss here.

smtpd_null_access_lookup_key (default: <>) 🎀

the lookup key that gets used in SMTP access(5) tables instead of the null sender address. that's the whole job. short and iconic.

smtpd_peername_lookup (default: yes) 🔥

when this is on, Postfix tries to look up the remote SMTP client hostname, and verifies that the name actually matches the client IP address. if it can't be looked up, can't be verified, or if name lookup is disabled, the client name gets set to "unknown".

turning name lookup off cuts down the delays from DNS lookups and raises the maximal inbound delivery rate — so it's a speed-vs-info tradeoff, and lowkey the speed one is tempting.

this feature is available in Postfix 2.3 and later.

smtpd_per_record_deadline (default: normal: no, overload: yes) ⭐

this flips how the smtpd_timeout and smtpd_starttls_timeout time limits behave — from a time limit per read or write system call to a time limit for sending or receiving a complete record.

what counts as a record? an SMTP command line, an SMTP response line, an SMTP message content line, or a TLS protocol message. that's the list, no more no less.

why do we care? because it limits the damage from hostile peers that trickle data one byte at a time. 😭 rude behavior, blocked.

Note: when per-record deadlines are enabled, a short timeout may cause problems with TLS over very slow network connections. the reasons are that a TLS protocol message can be up to 16 kbytes long (with TLSv1), and that an entire TLS protocol message must be sent or received within the per-record deadline.

this feature is available in Postfix 2.9-3.6. with older Postfix releases, the behavior is as if this parameter is set to "no". Postfix 3.7 and later use smtpd_per_request_deadline instead.

smtpd_per_request_deadline (default: normal: no, overload: yes) 👑

same energy as the last one, but glowier. this changes the behavior of smtpd_timeout and smtpd_starttls_timeout from a time limit per plaintext or TLS read or write call, into a combined time limit for:

receiving a complete SMTP request, and
sending a complete SMTP response.

the deadline only limits the time spent waiting for plaintext or TLS read/write calls — not the time spent elsewhere. and it limits the impact from hostile peers that trickle data one byte at a time. same villains as before.

see smtpd_min_data_rate for how the per-request deadline is managed during the DATA and BDAT phase.

Note: when per-request deadlines are enabled, a short time limit may cause problems with TLS over very slow network connections. the reason is that a TLS protocol message can be up to 16 kbytes long (with TLSv1), and that an entire TLS protocol message must be transferred within the per-request deadline.

this feature is available in Postfix 3.7 and later. a weaker feature, called smtpd_per_record_deadline, is available with Postfix 2.9-3.6. with older Postfix releases, the behavior is as if this parameter is set to "no".

this feature is available in Postfix 3.7 and later.

smtpd_policy_service_default_action (default: 451 4.3.5 Server configuration problem) 💀

the default action for when an SMTPD policy service request fails. if you set it to "DUNNO", it behaves as if the failed SMTPD policy service request was never sent at all, and just continues processing other access restrictions, if there are any.

Limitations:

This parameter may specify any value that would be a valid SMTPD policy server response (or access(5) map lookup result). An access(5) map or policy server in this parameter value may need to be declared in advance with a restriction_class setting.
If the specified action invokes another check_policy_service request, that request will have the built-in default action.

this feature is available in Postfix 3.0 and later.

smtpd_policy_service_max_idle (default: 300s) 🧚

the time after which an idle SMTPD policy service connection gets closed. bye bestie, you weren't doing anything anyway. 👋

specify a non-zero time value — that's an integral value plus an optional one-letter suffix that tells you the time unit. the time units are: s (seconds), m (minutes), h (hours), d (days), w (weeks). the default time unit is s (seconds).

this feature is available in Postfix 2.1 and later.

smtpd_policy_service_max_ttl (default: 1000s) 💜

the time after which an active SMTPD policy service connection gets closed. this one's for the ones that are still yapping, but have hit their ttl.

specify a non-zero time value — an integral value plus an optional one-letter suffix that specifies the time unit. time units: s (seconds), m (minutes), h (hours), d (days), w (weeks). the default time unit is s (seconds).

this feature is available in Postfix 2.1 and later.

smtpd_policy_service_policy_context (default: empty) 🍓

optional info that the Postfix SMTP server drops into the "policy_context" attribute of a policy service request. originally this existed so you could share the same service endpoint among multiple check_policy_service clients. sharing is caring fr fr.

this feature is available in Postfix 3.1 and later.

smtpd_policy_service_request_limit (default: 0) 🌈

the maximal number of requests per SMTPD policy service connection — or zero, which means no limit. once a connection hits this limit, it gets closed and the next request goes over a brand new connection.

this is a workaround to dodge error-recovery delays with policy servers that can't maintain a persistent connection. not glamorous, but it works.

this feature is available in Postfix 3.0 and later.

smtpd_policy_service_retry_delay (default: 1s) ✨

the delay between attempts to resend a failed SMTPD policy service request. you gotta specify a value greater than zero. no zero, no negatives, we don't do that here.

this feature is available in Postfix 3.0 and later.

smtpd_policy_service_timeout (default: 100s) 🎀

the time limit for connecting to, writing to, or receiving from a delegated SMTPD policy server. that's the whole vibe check.

this feature is available in Postfix 2.1 and later.

smtpd_policy_service_try_limit (default: 2) 🦋

the maximal number of attempts to send an SMTPD policy service request before just giving up. specify a value greater than zero — this is not a place for zero, bestie.

this feature is available in Postfix 3.0 and later.

smtpd_proxy_ehlo (default: $myhostname) 🔥

how the Postfix SMTP server announces itself to the proxy filter. by default, the Postfix hostname is used. it's giving "hi, it's me" energy.

this feature is available in Postfix 2.1 and later.

smtpd_proxy_filter (default: empty) 👑

the hostname and TCP port of the mail filtering proxy server. the proxy receives all mail from the Postfix SMTP server, and is supposed to hand the result off to another Postfix SMTP server process. it's the middleman, the go-between, the relay of destiny.

specify "host:port" or "inet:host:port" for a TCP endpoint, or
"unix:pathname" for a UNIX-domain endpoint.

the host can be an IP address or a symbolic name; no MX lookups are done. when no "host" or "host:" is specified, the local machine is assumed. pathname interpretation is relative to the Postfix queue directory.

this feature is available in Postfix 2.1 and later.

the "inet:" and "unix:" prefixes are available in Postfix 2.3 and later.

smtpd_proxy_options (default: empty) 🌸

a list of options controlling how the Postfix SMTP server talks to a before-queue content filter. specify zero or more of the following, separated by comma or whitespace:

speed_adjust — do not connect to a before-queue content filter until an entire message has been received. this reduces the number of simultaneous before-queue content filter processes. fewer little filter processes wandering around, cuter, calmer.

NOTE 1: a filter must not selectively reject recipients of a multi-recipient message. rejecting all recipients is OK, as is accepting all recipients. pick a lane, bestie. 💅 NOTE 2: this feature increases the minimum amount of free queue space by $message_size_limit. the extra space is needed to save the message to a temporary file.

this feature is available in Postfix 2.7 and later.

smtpd_proxy_timeout (default: 100s) 🫶

the time limit for connecting to a proxy filter and for sending or receiving information. when a connection fails, the client gets a generic error message, while the more detailed information goes into the maillog file. vague to them, tea to you. 😌

this feature is available in Postfix 2.1 and later.

smtpd_recipient_limit (default: 1000) ⭐

the maximal number of recipients that the Postfix SMTP server accepts per message delivery request. one thousand besties max, per delivery request.

smtpd_recipient_overshoot_limit (default: 1000) 💀

the number of recipients a remote SMTP client can send in excess of the limit specified with $smtpd_recipient_limit, before the Postfix SMTP server increments the per-session error count for each excess recipient.

so like: you've got some wiggle room, but every single recipient past the limit costs you an error. it's a whole "we said no but you kept going" situation. 🙈

`smtpd_recipient_restrictions` (default: see `postconf -d` output)

ok bestie, this is the big one 💅 these are the optional restrictions your Postfix SMTP server slaps onto things in the context of a client RCPT TO command, and they kick in after smtpd_relay_restrictions has already had its moment. ✨

and if you want the full tea on when exactly these get evaluated (yes, timing matters, it's giving delayed), go read SMTPD_ACCESS_README, section "Delayed evaluation of SMTP access restriction lists" — it explains the whole evaluation context and time thing. 📖

the lore: why this parameter got a glow-up in 2.10 🦋

ngl, before Postfix 2.10 the rules for relay permission and spam blocking were just... combined under smtpd_recipient_restrictions, and it was error-prone configuration fr fr. 😭 As of Postfix 2.10, relay permission rules are preferably implemented with smtpd_relay_restrictions instead — so that a permissive spam blocking policy sitting under smtpd_recipient_restrictions will no longer result in a permissive mail relay policy. slay, honestly. 👑

For backwards compatibility though, sites that migrate from Postfix versions before 2.10 can still set smtpd_relay_restrictions to the empty value, and use smtpd_recipient_restrictions exactly as before. old habits, iconic behavior, we respect it. 🫶

IMPORTANT ⚠️ — either the smtpd_relay_restrictions or the smtpd_recipient_restrictions parameter must specify at least one of these restrictions. Otherwise Postfix will refuse to receive mail, and you'll be sitting there like 🧍: reject, reject_unauth_destination defer, defer_if_permit, defer_unauth_destination

how to write the list ✍️

the recipient-specific girlies 💖

The following restrictions are specific to the recipient address that is received with the RCPT TO command. iykyk. 🌸

check_recipient_access type:table — search the specified access(5) database for the resolved RCPT TO address, and execute the corresponding action. 🔍
check_recipient_a_access type:table — search the specified access(5) database for the IP addresses for the RCPT TO domain, and execute the corresponding action. Note: a result of "OK" is not allowed for safety reasons. Instead, use DUNNO in order to exclude specific hosts from denylists. this feature is available in Postfix 3.0 and later. ✨
check_recipient_mx_access type:table — search the specified access(5) database for the MX hosts for the RCPT TO domain, and execute the corresponding action. If no MX record is found, look up A or AAAA records, just like the Postfix SMTP client would. Note: a result of "OK" is not allowed for safety reasons. Instead, use DUNNO in order to exclude specific hosts from denylists. this feature is available in Postfix 2.1 and later. 💌
check_recipient_ns_access type:table — search the specified access(5) database for the DNS servers for the RCPT TO domain, and execute the corresponding action. Note: a result of "OK" is not allowed for safety reasons. Instead, use DUNNO in order to exclude specific hosts from denylists. this feature is available in Postfix 2.1 and later. 🌐
permit_auth_destination — permit the request when one of the following is true:
- Postfix is a mail forwarder: the resolved RCPT TO domain matches $relay_domains or a subdomain thereof, and the address contains no sender-specified routing (user@elsewhere@domain),
- Postfix is the final destination: the resolved RCPT TO domain matches $mydestination, $inet_interfaces, $proxy_interfaces, $virtual_alias_domains, or $virtual_mailbox_domains, and the address contains no sender-specified routing (user@elsewhere@domain).
permit_mx_backup — permit the request when the local mail system is a backup MX for the RCPT TO domain, or when the domain is an authorized destination (see permit_auth_destination for definition). and now the safety notes, because bestie, this one has receipts 📋:
- Safety: permit_mx_backup does not accept addresses that have sender-specified routing information (example: user@elsewhere@domain).
- Safety: permit_mx_backup can be vulnerable to mis-use when access is not restricted with permit_mx_backup_networks. 🚨
- Safety: as of Postfix version 2.3, permit_mx_backup no longer accepts the address when the local mail system is a primary MX for the recipient domain. Exception: permit_mx_backup accepts the address when it specifies an authorized destination (see permit_auth_destination for definition).
- Limitation: mail may be rejected in case of a temporary DNS lookup problem with Postfix prior to version 2.0. 💀
reject_non_fqdn_recipient — reject the request when the RCPT TO address specifies a domain that is not in fully-qualified domain form, as required by the RFC. The non_fqdn_reject_code parameter specifies the response code for rejected requests (default: 504). 📭
reject_rhsbl_recipient rbl_domain=d.d.d.d — reject the request when the RCPT TO domain is listed with the A record "d.d.d.d" under rbl_domain (Postfix version 2.1 and later only). Each "d" is a number, or a pattern inside "[]" that contains one or more ";"-separated numbers or number..number ranges (Postfix version 2.8 and later). If no "=d.d.d.d" is specified, reject the request when the RCPT TO domain is listed with any A record under rbl_domain. The maps_rbl_reject_code parameter specifies the response code for rejected requests (default: 554); the default_rbl_reply parameter specifies the default server reply; and the rbl_reply_maps parameter specifies tables with server replies indexed by rbl_domain. NOTE: Always respect the usage policies of reputation services. Avoid public or ISP resolvers, unless the queries use your unique API key (see rbl_reply_maps for how to avoid leaking an API key in SMTP server responses). This feature is available in Postfix version 2.0 and later. 🔑
reject_unauth_destination — reject the request unless one of the following is true:
- Postfix is a mail forwarder: the resolved RCPT TO domain matches $relay_domains or a subdomain thereof, and contains no sender-specified routing (user@elsewhere@domain),
- Postfix is the final destination: the resolved RCPT TO domain matches $mydestination, $inet_interfaces, $proxy_interfaces, $virtual_alias_domains, or $virtual_mailbox_domains, and contains no sender-specified routing (user@elsewhere@domain).

The relay_domains_reject_code parameter specifies the response code for rejected requests (default: 554). ✋

defer_unauth_destination — reject the same requests as reject_unauth_destination, with a non-permanent error code. This feature is available in Postfix 2.10 and later. ⏳
reject_unknown_recipient_domain — reject the request when Postfix is not final destination for the recipient domain, and the RCPT TO domain has 1) no DNS MX and no DNS A record or 2) a malformed MX record such as a record with a zero-length MX hostname (Postfix version 2.3 and later). The reply is specified with the unknown_address_reject_code parameter (default: 450), unknown_address_tempfail_action (default: defer_if_permit), or 556 (nullmx, Postfix 3.0 and later). See the respective parameter descriptions for details. 🕵️
reject_unlisted_recipient (with Postfix version 2.0: check_recipient_maps) — reject the request when the RCPT TO address is not listed in the list of valid recipients for its domain class. See the smtpd_reject_unlisted_recipient parameter description for details. This feature is available in Postfix 2.1 and later. 📝
reject_unverified_recipient — reject the request when mail to the RCPT TO address is known to bounce, or when the recipient address destination is not reachable. Address verification information is managed by the verify(8) server; see the ADDRESS_VERIFICATION_README file for details. The unverified_recipient_reject_code parameter specifies the numerical response code when an address is known to bounce (default: 450, change it to 550 when you are confident that it is safe to do so). The unverified_recipient_defer_code parameter specifies the numerical response code when an address probe failed due to a temporary problem (default: 450). The unverified_recipient_tempfail_action parameter specifies the action after address probe failure due to a temporary problem (default: defer_if_permit). This feature breaks for aliased addresses with "enable_original_recipient = no" (Postfix <= 3.2). This feature is available in Postfix 2.1 and later. 🔬

other restrictions that are valid in this context 🍓

Generic restrictions that can be used in any SMTP command context, described under smtpd_client_restrictions. 🌈
SMTP command specific restrictions described under smtpd_client_restrictions, smtpd_helo_restrictions and smtpd_sender_restrictions. 🎀

example time, bestie 👑

# The Postfix before 2.10 default mail relay policy. Later Postfix
# versions implement this preferably with smtpd_relay_restrictions.
smtpd_recipient_restrictions = permit_mynetworks, reject_unauth_destination

and that's the whole vibe on this one — go forth and reject responsibly 💖

`smtpd_reject_filter_maps` — default: empty

okay so this one is a glow-up filter for your reject messages 💅 it's an optional filter that can replace a reject response coming from the Postfix SMTP server itself, or from a program that replies through the Postfix SMTP server. The filter gets applied before the optional reject footers get tacked on. Usually you're gonna want this to be a regexp: or pcre: table, where the left-hand side is a pattern and the right-hand side is the replacement text.

What goes in is a server response starting with a 4XX or 5XX reply code (check RFC 5321), usually followed by an enhanced status code (RFC 3463) and then some text. The filter hands back replacement text, or it says "nah, no match here." And listen — this feature cannot turn a reject reply into a non-reject one, or the other way around. It's cosmetic-adjacent only, bestie.

LIMITATION: smtpd_reject_filter_maps will not replace text that was already logged before the Postfix SMTP server replies to the remote SMTP client. To help with logfile analysis, the Postfix SMTP server logs both the unmodified reply (logged below as "reject filter in") and the replacement reply (logged below as "reject filter out"). Two receipts, no secrets ✨

Example:

/etc/postfix/main.cf:
    smtpd_reject_filter_maps = regexp:/etc/postfix/smtpd_reject_filter

/etc/postfix/smtpd_reject_filter:
    # Replace soft reject with hard reject.
    /^451 4(\.6\.0 Alias expansion error)/ 550 5${1}

    # Silly rule for demo purposes.
    /^(4.+[^.])\.*$/ $1. See you later.

/var/log/maillog:
    NOQUEUE: reject filter in: 451 4.6.0 Alias expansion error
    NOQUEUE: reject filter out: 550 5.6.0 Alias expansion error

This feature is available in Postfix >= 3.11. 🎀

`smtpd_reject_footer` — default: empty

Optional info that gets appended after every single Postfix SMTP server 4XX or 5XX response. Like a little signature on your rejection emails 💌

The example below uses "\c" at the start of the template (supported in Postfix 2.10 and later) to suppress the line break between the reply text and the footer text. Heads up: with earlier Postfix versions, the footer text always starts on a new line, and the "\c" just gets output literally. Awkward. 🙈

/etc/postfix/main.cf:
    smtpd_reject_footer = \c. For assistance, call 800-555-0101.
     Please provide the following information in your problem report:
     time ($localtime), client ($client_address) and server
     ($server_name).

Server response:

    550-5.5.1 <user@example> Recipient address rejected: User
    unknown. For assistance, call 800-555-0101. Please provide the
    following information in your problem report: time (Jan 4 15:42:00),
    client (192.168.1.248) and server (mail1.example.com).

Note: the text above is meant to make it easier to find the Postfix logfile records for a failed SMTP session. The text itself is not logged to the Postfix SMTP server's maillog file.

Be sure to keep the text as short as possible, fr fr. Long text may be truncated before it reaches the remote SMTP client's maillog file, or before it gets returned to the sender in a delivery status notification. Nobody wants your footer to get cut off mid-sentence 😭

The template text is not subject to Postfix configuration parameter $name expansion. Instead, this feature supports a limited number of $name attributes in the footer text, which get swapped out for their current value for that SMTP session.

Note: specify $$name in footer text that is looked up from regexp: or pcre:-based smtpd_reject_footer_maps, otherwise the Postfix server will not use the footer text and will log a warning instead. Don't forget the double dollar, iykyk 💀

client_address — the Client IP address that is logged in the maillog file.
client_port — the client TCP port that is logged in the maillog file.
localtime — the server local time (Mmm dd hh:mm:ss) that is logged in the maillog file.
server_name — the server's myhostname value. This attribute is made available for sites with multiple MTAs (maybe chillin' behind a load-balancer), where the server name can help the server support team quickly find the right log files. iconic for debugging 🕵️♀️

Notes:

NOT SUPPORTED are other attributes such as sender, recipient, or main.cf parameters.
For safety reasons, text that does not match $smtpd_expansion_filter is censored. 🫣

This feature supports the two-character sequence \n as a request for a line break in the footer text. Postfix automatically inserts, after each line break, the three-digit SMTP reply code (and optional enhanced status code) from the original Postfix reject message.

To work around mail software that mis-handles multi-line replies, specify the two-character sequence \c at the start of the template. This suppresses the line break between the reply text and the footer text (Postfix 2.10 and later).

This feature is available in Postfix 2.8 and later. 🌸

`smtpd_reject_footer_maps` — default: empty

Lookup tables, indexed by the complete Postfix SMTP server 4xx or 5xx response, holding reject footer templates. Peep smtpd_reject_footer for the details.

Specify zero or more "type:name" lookup tables, separated by whitespace or comma. Tables get searched in the order you list them, and it stops at the first match. 🎯

This feature is available in Postfix 3.4 and later.

`smtpd_reject_unlisted_recipient` — default: yes

This asks the Postfix SMTP server to reject mail for unknown recipient addresses, even when no explicit reject_unlisted_recipient access restriction is specified. It keeps the Postfix queue from filling up with undeliverable MAILER-DAEMON messages — very protective, very mindful 👑

An address counts as "unknown" when 1) it doesn't match a virtual(5) alias or canonical(5) mapping, and 2) the address isn't valid for its address class. For a definition of class-based address validation, see ADDRESS_CLASS_README.

This feature is available in Postfix 2.1 and later.

`smtpd_reject_unlisted_sender` — default: no

This asks the Postfix SMTP server to reject mail from unknown sender addresses, even when no explicit reject_unlisted_sender access restriction is specified. It can slow down an explosion of forged mail from worms or viruses. germ deterrent basically 🦠

This feature is available in Postfix 2.1 and later.

`smtpd_relay_before_recipient_restrictions` — default: see `postconf -d` output

Evaluate smtpd_relay_restrictions before smtpd_recipient_restrictions. Historically, smtpd_relay_restrictions was evaluated after smtpd_recipient_restrictions, which straight up contradicted documented behavior. the audacity 😤

Background: the smtpd_relay_restrictions feature is primarily designed to enforce a mail relaying policy, while smtpd_recipient_restrictions is primarily designed to enforce spam blocking policy. Both get evaluated while replying to the RCPT TO command, and both support the same features.

This feature is available in Postfix 3.6 and later.

`smtpd_relay_restrictions` — default: `permit_mynetworks, permit_sasl_authenticated, defer_unauth_destination`

Access restrictions for mail relay control that the Postfix SMTP server applies in the context of the RCPT TO command, before smtpd_recipient_restrictions. See SMTPD_ACCESS_README, section "Delayed evaluation of SMTP access restriction lists" for a whole discussion about evaluation context and time. ⏰

With Postfix versions before 2.10, the rules for relay permission and spam blocking were combined under smtpd_recipient_restrictions, which made configuration error-prone. As of Postfix 2.10, relay permission rules are preferably implemented with smtpd_relay_restrictions, so that a permissive spam blocking policy under smtpd_recipient_restrictions will no longer result in a permissive mail relay policy. separation of concerns ate 🔥

For backwards compatibility, sites that migrate from Postfix versions before 2.10 can set smtpd_relay_restrictions to the empty value, and use smtpd_recipient_restrictions exactly as before.

By default, the Postfix SMTP server accepts:

Mail from clients whose IP address matches $mynetworks, or:
Mail from clients who are SASL authenticated, or:
Mail to remote destinations that match $relay_domains, except for addresses that contain sender-specified routing (user@elsewhere@domain), or:
Mail to local destinations that match $inet_interfaces or $proxy_interfaces, $mydestination, $virtual_alias_domains, or $virtual_mailbox_domains.

IMPORTANT: Either the smtpd_relay_restrictions or the smtpd_recipient_restrictions parameter must specify at least one of the following restrictions. Otherwise Postfix will refuse to receive mail:

reject, reject_unauth_destination

defer, defer_if_permit, defer_unauth_destination

Specify a list of restrictions, separated by commas and/or whitespace. Continue long lines by starting the next line with whitespace. The same restrictions are available as documented under smtpd_recipient_restrictions.

This feature is available in Postfix 2.10 and later.

`smtpd_restriction_classes` — default: empty

User-defined aliases for groups of access restrictions. 💫 These aliases can be specified in smtpd_recipient_restrictions etc., and on the right-hand side of a Postfix access(5) table.

One major application is implementing per-recipient UCE control. See the RESTRICTION_CLASS_README document for other examples.

`smtpd_sasl_application_name` — default: `smtpd`

The application name that the Postfix SMTP server uses for SASL server initialization. This controls the name of the SASL configuration file. The default value is smtpd, which corresponds to a SASL configuration file named smtpd.conf.

This feature is available in Postfix 2.1 and 2.2. With Postfix 2.3 it was renamed to smtpd_sasl_path. glow-up era ✨

`smtpd_sasl_auth_enable` — default: no

Enable SASL authentication in the Postfix SMTP server. By default, the Postfix SMTP server does not use authentication.

If a remote SMTP client is authenticated, the permit_sasl_authenticated access restriction can be used to permit relay access, like this:

# With Postfix 2.10 and later, the mail relay policy is
# preferably specified under smtpd_relay_restrictions.
smtpd_relay_restrictions =
    permit_mynetworks, permit_sasl_authenticated, ...

# With Postfix before 2.10, the relay policy can be
# specified only under smtpd_recipient_restrictions.
smtpd_recipient_restrictions =
    permit_mynetworks, permit_sasl_authenticated, ...

To reject all SMTP connections from unauthenticated clients, specify "smtpd_delay_reject = yes" (which is the default) and use:

smtpd_client_restrictions = permit_sasl_authenticated, reject

See the SASL_README file for SASL configuration and operation details. 🧚

🌸 `smtpd_sasl_authenticated_header` (default: `no`)

Okay so this one is a yes/no vibe check on whether the smtpd(8) Received message header gets to spill the SASL authenticated user name. Set it and the name shows up in the header. 💖

This feature is available in Postfix 2.3 and later.

🦋 `smtpd_sasl_exceptions_networks` (default: empty)

Which remote SMTP clients the Postfix SMTP server will not offer AUTH support to. Basically the "do not pass AUTH, do not collect a login" list.

Some clients — Netscape 4 at least, iconic in the worst way 😭 — have a bug that makes them demand a login and password whenever AUTH is offered, whether it's necessary or not. To work around that, specify, for example, $mynetworks to stop Postfix from offering AUTH to local clients. No cap, that's the whole trick.

Specify a list of network/netmask patterns, separated by commas and/or whitespace. The mask specifies the number of bits in the network part of a host address. You can also specify "/file/name" or "type:table" patterns. A "/file/name" pattern is replaced by its contents; a "type:table" lookup table is matched when a table entry matches a lookup string (the lookup result is ignored, bestie, it's just there for the match). Continue long lines by starting the next line with whitespace. Specify "!pattern" to exclude an address or network block from the list. The form "!/file/name" is supported only in Postfix version 2.4 and later.

Note: IP version 6 address information must be specified inside [] in the smtpd_sasl_exceptions_networks value, and in files specified with "/file/name". IP version 6 addresses contain the ":" character, and would otherwise be confused with a "type:table" pattern. 💅

Example:

smtpd_sasl_exceptions_networks = $mynetworks

This feature is available in Postfix 2.1 and later.

🎀 `smtpd_sasl_local_domain` (default: empty)

The name of the Postfix SMTP server's local SASL authentication realm. That's it, that's the realm. 👑

By default, the local authentication realm name is the null string.

Examples:

smtpd_sasl_local_domain = $mydomain
smtpd_sasl_local_domain = $myhostname

✨ `smtpd_sasl_mechanism_filter` (default: `!external, static:rest`)

If non-empty, a filter for the SASL mechanism names that the Postfix SMTP server will announce in the EHLO response. By default, the Postfix SMTP server will not announce the EXTERNAL mechanism, because Postfix support for that is not implemented. It's giving "we're not doing that and we're not pretending to." 🙈

Specify mechanism names, "/file/name" patterns, or "type:table" lookup tables, separated by comma or whitespace. The right-hand side result from "type:table" lookups is ignored. Specify "!pattern" to exclude a mechanism name from the list.

Examples:

smtpd_sasl_mechanism_filter = !external, !gssapi, static:rest
smtpd_sasl_mechanism_filter = login, plain
smtpd_sasl_mechanism_filter = /etc/postfix/smtpd_mechs

This feature is available in Postfix 3.6 and later.

🌈 `smtpd_sasl_path` (default: `smtpd`)

Implementation-specific information that the Postfix SMTP server passes through to the SASL plug-in implementation that is selected with smtpd_sasl_type. Typically this specifies the name of a configuration file or rendezvous point. Lowkey just "here's the address, go meet up." 🫶

This feature is available in Postfix 2.3 and later. In earlier releases it was called smtpd_sasl_application_name. (Glow-up + name change, we love to see it.)

💜 `smtpd_sasl_response_limit` (default: `12288`)

The maximum length of a SASL client's response to a server challenge. When the client's "initial response" is longer than the normal limit for SMTP commands, the client must omit its initial response, and wait for an empty server challenge; it can then send what would have been its "initial response" as a response to the empty server challenge. RFC4954 requires the server to accept client responses up to at least 12288 octets of base64-encoded text. The default value is therefore also the minimum value accepted for this parameter. So don't get cute and lower it, bestie. 💀

This feature is available in Postfix 3.4 and later. Prior versions use "line_length_limit", which may need to be raised to accommodate larger client responses, as may be needed with GSSAPI authentication of Windows AD users who are members of many groups. (If that's your situation, sending hugs. 😭)

🔥 `smtpd_sasl_security_options` (default: `noanonymous`)

Postfix SMTP server SASL security options; as of Postfix 2.3 the list of available features depends on the SASL server implementation that is selected with smtpd_sasl_type.

The following security features are defined for the cyrus server SASL implementation:

Restrict what authentication mechanisms the Postfix SMTP server will offer to the client. The list of available authentication mechanisms is system dependent.

Specify zero or more of the following:

noplaintext — Disallow methods that use plaintext passwords.
noactive — Disallow methods subject to active (non-dictionary) attack.
nodictionary — Disallow methods subject to passive (dictionary) attack.
noanonymous — Disallow methods that allow anonymous authentication.
forward_secrecy — Only allow methods that support forward secrecy (Dovecot only).
mutual_auth — Only allow methods that provide mutual authentication (not available with Cyrus SASL version 1).

By default, the Postfix SMTP server accepts plaintext passwords but not anonymous logins.

Warning: it appears that clients try authentication methods in the order as advertised by the server (e.g., PLAIN ANONYMOUS CRAM-MD5) which means that if you disable plaintext passwords, clients will log in anonymously, even when they should be able to use CRAM-MD5. So, if you disable plaintext logins, disable anonymous logins too. Postfix treats anonymous login as no authentication. So like, do both or enjoy your security theatre. 🎭

Example:

smtpd_sasl_security_options = noanonymous, noplaintext

🍓 `smtpd_sasl_service` (default: `smtp`)

The service name that is passed to the SASL plug-in that is selected with smtpd_sasl_type and smtpd_sasl_path.

This feature is available in Postfix 2.11 and later. Prior versions behave as if "smtp" is specified.

🌸 `smtpd_sasl_tls_security_options` (default: `$smtpd_sasl_security_options`)

The SASL authentication security options that the Postfix SMTP server uses for TLS encrypted SMTP sessions. Same energy as the non-TLS one, but locked behind TLS. 🔒

This feature is available in Postfix 2.2 and later.

👑 `smtpd_sasl_type` (default: `cyrus`)

The SASL plug-in type that the Postfix SMTP server should use for authentication. The available types are listed with the "postconf -a" command. Go peek if you're indecisive. ✨

This feature is available in Postfix 2.3 and later.

🧚 `smtpd_sender_login_maps` (default: empty)

Optional lookup table with the SASL login names that own the envelope sender (MAIL FROM) addresses. Like a little guest list for who's allowed to claim which sender. 🎀

Note: to enforce that the From: header address matches the envelope sender (MAIL FROM) address, use an external filter such as a Milter, for the submission or submissions (formerly called smtps) services. For example: https://github.com/magcks/milterfrom.

Specify zero or more "type:name" lookup tables, separated by whitespace or comma. Tables will be searched in the specified order until a match is found. With lookups from indexed files such as DB or DBM, or from networked tables such as NIS, LDAP or SQL, the following search operations are done with a sender address of user@domain:

user@domain — This table lookup is always done and has the highest precedence.
user — This table lookup is done only when the domain part of the sender address matches $myorigin, $mydestination, $inet_interfaces or $proxy_interfaces.
@domain — This table lookup is done last and has the lowest precedence.

In all cases the result of table lookup must be either "not found" or a list of SASL login names separated by comma and/or whitespace.

`smtpd_sender_restrictions` (default: empty) 💌

Okay bestie, this one is a big deal — these are the optional restrictions the Postfix SMTP server hits you with in the context of a client MAIL FROM command. Wanna know when exactly these get evaluated? Peep SMTPD_ACCESS_README, section "Delayed evaluation of SMTP access restriction lists", it spills all the tea on evaluation context and time. ☕

The default is to permit everything. (Yeah. No gatekeeping, everyone's welcome. 🫶)

So how do you write these? You give a list of restrictions, separated by commas and/or whitespace. Long lines get continued by starting the next line with whitespace (classic). Restrictions are applied in the order as specified, and the first restriction that matches wins — no second chances, no appeals. ✨

The following restrictions are specific to the sender address received with the MAIL FROM command. 👇

`check_sender_access type:table`

Search the specified access(5) database for the MAIL FROM address, and execute the corresponding action. Simple as. 🔍

`check_sender_a_access type:table`

Search the specified access(5) database for the IP addresses for the MAIL FROM domain, and execute the corresponding action. ⚠️ Note: a result of "OK" is not allowed for safety reasons. Instead, use DUNNO in order to exclude specific hosts from denylists. This feature is available in Postfix 3.0 and later.

`check_sender_mx_access type:table`

Search the specified access(5) database for the MX hosts for the MAIL FROM domain, and execute the corresponding action. If no MX record is found, look up A or AAAA records, just like the Postfix SMTP client would. ⚠️ Note: a result of "OK" is not allowed for safety reasons. Instead, use DUNNO in order to exclude specific hosts from denylists. This feature is available in Postfix 2.1 and later.

`check_sender_ns_access type:table`

Search the specified access(5) database for the DNS servers for the MAIL FROM domain, and execute the corresponding action. ⚠️ Note: a result of "OK" is not allowed for safety reasons. Instead, use DUNNO in order to exclude specific hosts from denylists. This feature is available in Postfix 2.1 and later.

`reject_authenticated_sender_login_mismatch`

Reject the request when the client is authenticated with SASL, but either the MAIL FROM address is not listed in $smtpd_sender_login_maps, or the SASL login name is not an owner for that address. 🚫

This prevents an authenticated client from using a MAIL FROM address that they do not explicitly own. No pretending to be someone else, that's giving identity theft energy. 🙈

Note: to enforce that the From: header address matches the envelope sender (MAIL FROM) address, use an external filter such as a Milter, for the submission or submissions (formerly called smtps) services. For example: https://github.com/magcks/milterfrom.

This feature is available in Postfix version 2.1 and later.

`reject_known_sender_login_mismatch`

When the client is authenticated with SASL, reject the request when the MAIL FROM address is listed in $smtpd_sender_login_maps, but the SASL login name is not an owner for that address.

When the client is not authenticated with SASL, reject the request when SASL is enabled, and the MAIL FROM address is listed in $smtpd_sender_login_maps.

This protects any MAIL FROM address that is listed in $smtpd_sender_login_maps, while still allowing a client to use any unlisted MAIL FROM address. Locking down the VIPs while letting the randoms vibe. 🔐

Note: to enforce that the From: header address matches the envelope sender (MAIL FROM) address, use an external filter such as a Milter, for the submission or submissions (formerly called smtps) services. For example: https://github.com/magcks/milterfrom.

This feature is available in Postfix version 2.11 and later.

`reject_non_fqdn_sender`

Reject the request when the MAIL FROM address specifies a domain that is not in fully-qualified domain form as required by the RFC. Like, the RFC said what it said and it meant it. 📜

The non_fqdn_reject_code parameter specifies the response code for rejected requests (default: 504).

`reject_rhsbl_sender rbl_domain=d.d.d.d`

Reject the request when the MAIL FROM domain is listed with the A record "d.d.d.d" under rbl_domain (Postfix version 2.1 and later only). Each "d" is a number, or a pattern inside "[]" that contains one or more ";"-separated numbers or number..number ranges (Postfix version 2.8 and later). If no "=d.d.d.d" is specified, reject the request when the MAIL FROM domain is listed with any A record under rbl_domain.

The maps_rbl_reject_code parameter specifies the response code for rejected requests (default: 554); the default_rbl_reply parameter specifies the default server reply; and the rbl_reply_maps parameter specifies tables with server replies indexed by rbl_domain.

NOTE: Always respect the usage policies of reputation services. Avoid public or ISP resolvers, unless the queries use your unique API key (see rbl_reply_maps for how to avoid leaking an API key in SMTP server responses).

This feature is available in Postfix 2.0 and later.

`reject_sender_login_mismatch`

As of Postfix 2.1, this is an alias for "reject_authenticated_sender_login_mismatch, reject_unauthenticated_sender_login_mismatch". Two-for-one, iconic. 👑

`reject_unauthenticated_sender_login_mismatch`

Reject the request when SASL is enabled, the MAIL FROM address is listed in $smtpd_sender_login_maps, but the client is not authenticated with SASL.

With SASL enabled, this prevents an unauthenticated client from using any MAIL FROM address that is listed in $smtpd_sender_login_maps. 🛑

Note: to enforce that the From: header address matches the envelope sender (MAIL FROM) address, use an external filter such as a Milter, for the submission or submissions (formerly called smtps) services. For example: https://github.com/magcks/milterfrom.

This feature is available in Postfix version 2.1 and later.

`reject_unknown_sender_domain`

Reject the request when Postfix is not the final destination for the sender address, and the MAIL FROM domain has

no DNS MX and no DNS A record, or
a malformed MX record such as a record with a zero-length MX hostname (Postfix version 2.3 and later).

The reply is specified with the unknown_address_reject_code parameter (default: 450), unknown_address_tempfail_action (default: defer_if_permit), or 550 (nullmx, Postfix 3.0 and later). See the respective parameter descriptions for details. 📖

`reject_unlisted_sender`

Reject the request when the MAIL FROM address is not listed in the list of valid recipients for its domain class. See the smtpd_reject_unlisted_sender parameter description for details.

This feature is available in Postfix 2.1 and later.

`reject_unverified_sender`

Reject the request when mail to the MAIL FROM address is known to bounce, or when the sender address destination is not reachable. 💀

Address verification information is managed by the verify(8) server; see the ADDRESS_VERIFICATION_README file for details.

The unverified_sender_reject_code parameter specifies the numerical response code when an address is known to bounce (default: 450, change into 550 when you are confident that it is safe to do so).
The unverified_sender_defer_code specifies the numerical response code when an address probe failed due to a temporary problem (default: 450).
The unverified_sender_tempfail_action parameter specifies the action after address probe failure due to a temporary problem (default: defer_if_permit).

This feature breaks for aliased addresses with "enable_original_recipient = no" (Postfix <= 3.2). 😭

This feature is available in Postfix 2.1 and later.

Other restrictions that are valid in this context: 🫰

Generic restrictions that can be used in any SMTP command context, described under smtpd_client_restrictions.
SMTP command specific restrictions described under smtpd_client_restrictions and smtpd_helo_restrictions.
SMTP command specific restrictions described under smtpd_recipient_restrictions. When recipient restrictions are listed under smtpd_sender_restrictions, they have effect only with "smtpd_delay_reject = yes", so that $smtpd_sender_restrictions is evaluated at the time of the RCPT TO command.

Examples: ✨

smtpd_sender_restrictions = reject_unknown_sender_domain
smtpd_sender_restrictions = reject_unknown_sender_domain,
    check_sender_access lmdb:/etc/postfix/access

Instead of lmdb:, some systems use cdb:, hash:, or dbm:.

Execute the command "postmap /etc/postfix/access" after you change the access file, to (re)build a default-type indexed file. Execute "postmap type:/etc/postfix/access" to specify an explicit type.

The default indexed file type is configured with the default_database_type parameter. To list available explicit types, execute the command "postconf -m".

Configuration changes will become visible after a minute or so. Use "postfix reload" to eliminate the delay. ⏱️

`smtpd_service_name` (default: `smtpd`)

The internal service that postscreen(8) hands off allowed connections to. In a future version there may be different classes of SMTP service. 🔮

This feature is available in Postfix 2.8.

`smtpd_soft_error_limit` (default: `10`)

The number of errors a remote SMTP client is allowed to make without delivering mail before the Postfix SMTP server slows down all its responses. It's giving timeout corner, but make it intentional. 🐌

With Postfix version 2.1 and later, when the error count is > $smtpd_soft_error_limit, the Postfix SMTP server delays all responses by $smtpd_error_sleep_time.
With Postfix versions 2.0 and earlier, when the error count is > $smtpd_soft_error_limit, the Postfix SMTP server delays all responses by the larger of (number of errors) seconds or $smtpd_error_sleep_time.
With Postfix versions 2.0 and earlier, when the error count is <= $smtpd_soft_error_limit, the Postfix SMTP server delays 4XX and 5XX responses by $smtpd_error_sleep_time.
smtpd_starttls_timeout (default: check your postconf -d output bestie, it's literally stress-dependent ✨) — this is the time limit for the Postfix SMTP server's write and read operations during the TLS startup and shutdown handshake procedures. The current default value is stress-dependent (yes, it vibes with the workload). Before Postfix version 2.8, it was fixed at 300s.

This feature is available in Postfix 2.2 and later.

smtpd_timeout (default: normal: 300s, overload: 10s) — so when the Postfix SMTP server wants to send an SMTP server response, this is how long it'll wait for the underlying network write operation to complete. And when the server wants to receive an SMTP client request, it's how long it waits for the underlying network read operation to complete. See the smtpd_per_request_deadline for how this time limit may be enforced (and with Postfix 2.9-3.6, peep smtpd_per_record_deadline instead 👀).

Normally the default limit is 300s, but it switches up under overload to just 10s. With Postfix 2.5 and earlier, the SMTP server always uses a time limit of 300s by default.

Note: if you set SMTP time limits to very large values you may have to update the global ipc_timeout parameter. Don't say we didn't warn you 💀

smtpd_tls_CAfile (default: empty) — a file containing (PEM format) CA certificates of root CAs trusted to sign either remote SMTP client certificates or intermediate CA certificates 🎀 These get loaded into memory before the smtpd(8) server enters the chroot jail. If the number of trusted roots is large, consider using smtpd_tls_CApath instead, but note that the latter directory must be present in the chroot jail if the smtpd(8) server is chrooted. This file may also be used to augment the server certificate trust chain, but it is best to include all the required certificates directly in the server certificate file.

Specify smtpd_tls_CAfile = /path/to/system_CA_file to use ONLY the system-supplied default Certification Authority certificates.

Specify tls_append_default_CA = no to prevent Postfix from appending the system-supplied default CAs and trusting third-party certificates.

By default (see smtpd_tls_ask_ccert), client certificates are not requested, and smtpd_tls_CAfile should remain empty. If you do make use of client certificates, the distinguished names (DNs) of the Certification Authorities listed in smtpd_tls_CAfile are sent to the remote SMTP client in the client certificate request message. MUAs with multiple client certificates may use the list of preferred Certification Authorities to select the correct client certificate. You may want to put your "preferred" CA or CAs in this file, and install other trusted CAs in $smtpd_tls_CApath.

Example:

smtpd_tls_CAfile = /etc/postfix/CAcert.pem

This feature is available in Postfix 2.2 and later.

smtpd_tls_CApath (default: empty) — a directory containing (PEM format) CA certificates of root CAs trusted to sign either remote SMTP client certificates or intermediate CA certificates. Do not forget to create the necessary "hash" links with, for example, "$OPENSSL_HOME/bin/c_rehash /etc/postfix/certs" 🔑 To use smtpd_tls_CApath in chroot mode, this directory (or a copy) must be inside the chroot jail.

Specify smtpd_tls_CApath = /path/to/system_CA_directory to use ONLY the system-supplied default Certification Authority certificates.

Specify tls_append_default_CA = no to prevent Postfix from appending the system-supplied default CAs and trusting third-party certificates.

By default (see smtpd_tls_ask_ccert), client certificates are not requested, and smtpd_tls_CApath should remain empty. In contrast to smtpd_tls_CAfile, DNs of Certification Authorities installed in $smtpd_tls_CApath are not included in the client certificate request message. MUAs with multiple client certificates may use the list of preferred Certification Authorities to select the correct client certificate. You may want to put your "preferred" CA or CAs in $smtpd_tls_CAfile, and install the remaining trusted CAs in $smtpd_tls_CApath.

Example:

smtpd_tls_CApath = /etc/postfix/certs

This feature is available in Postfix 2.2 and later.

smtpd_tls_always_issue_session_ids (default: yes) — forces the Postfix SMTP server to issue a TLS session id, even when TLS session caching is turned off (smtpd_tls_session_cache_database is empty). This behavior is compatible with Postfix < 2.3.

With Postfix 2.3 and later the Postfix SMTP server can disable session id generation when TLS session caching is turned off. This keeps remote SMTP clients from caching sessions that almost certainly cannot be re-used ✨

By default, the Postfix SMTP server always generates TLS session ids. This works around a known defect in mail client applications such as MS Outlook, and may also prevent interoperability issues with other MTAs.

Example:

smtpd_tls_always_issue_session_ids = no

This feature is available in Postfix 2.3 and later.

smtpd_tls_ask_ccert (default: no) — ask a remote SMTP client for a client certificate 🫶 This info is needed for certificate based mail relaying with, for example, the permit_tls_clientcerts feature.

Some clients such as Netscape will either complain if no certificate is available (for the list of CAs in $smtpd_tls_CAfile) or will offer multiple client certificates to choose from. This may be annoying, so this option is "off" by default. Periodt.

This feature is available in Postfix 2.2 and later.

smtpd_tls_auth_only (default: no) — when TLS encryption is optional in the Postfix SMTP server, do not announce or accept SASL authentication over unencrypted connections 🔒 So if there's no TLS, no SASL, no exceptions.

This feature is available in Postfix 2.2 and later.

smtpd_tls_ccert_verifydepth (default: 9) — the verification depth for remote SMTP client certificates. A depth of 1 is sufficient if the issuing CA is listed in a local CA file.

The default verification depth is 9 (the OpenSSL default) for compatibility with earlier Postfix behavior. Prior to Postfix 2.5, the default value was 5, but the limit was not actually enforced. If you have set this to a lower non-default value, certificates with longer trust chains may now fail to verify 😭 Certificate chains with 1 or 2 CAs are common, deeper chains are more rare and any number between 5 and 9 should suffice in practice. You can choose a lower number if, for example, you trust certificates directly signed by an issuing CA but not any CAs it delegates to.

This feature is available in Postfix 2.2 and later.

smtpd_tls_cert_file (default: empty) — file with the Postfix SMTP server RSA certificate in PEM format 💖 This file may also contain the Postfix SMTP server private RSA key. With Postfix >= 3.4 the preferred way to configure server keys and certificates is via the smtpd_tls_chain_files parameter (that's the glow-up, bestie).

Public Internet MX hosts without certificates signed by a "reputable" CA must generate, and be prepared to present to most clients, a self-signed or private-CA signed certificate. The client will not be able to authenticate the server, but unless it is running Postfix 2.3 or similar software, it will still insist on a server certificate.

For servers that are not public Internet MX hosts, Postfix supports configurations with no certificates. This entails the use of just the anonymous TLS ciphers, which are not supported by typical SMTP clients. Since some clients may not fall back to plain text after a TLS handshake failure, a certificate-less Postfix SMTP server will be unable to receive email from some TLS-enabled clients. To avoid accidental configurations with no certificates, Postfix enables certificate-less operation only when the administrator explicitly sets smtpd_tls_cert_file = none. This ensures that new Postfix SMTP server configurations will not accidentally enable TLS without certificates. No cap.

Note that server certificates are not optional in TLS 1.3. To run without certificates you'd have to disable the TLS 1.3 protocol by including !TLSv1.3 in smtpd_tls_protocols and perhaps also smtpd_tls_mandatory_protocols. It is simpler instead to just configure a certificate chain. Certificate-less operation is not recommended 💀

Both RSA and DSA certificates are supported. When both types are present, the cipher used determines which certificate will be presented to the client. For Netscape and OpenSSL clients without special cipher choices the RSA certificate is preferred.

To enable a remote SMTP client to verify the Postfix SMTP server certificate, the issuing CA certificates must be made available to the client. You should include the required certificates in the server certificate file, the server certificate first, then the issuing CA(s) (bottom-up order) 🌸

Example: the certificate for server.example.com was issued by intermediate CA which itself has a certificate of root CA. Create the server.pem file with cat server_cert.pem intermediate_CA.pem root_CA.pem > server.pem.

If you also want to verify client certificates issued by these CAs, you can add the CA certificates to the smtpd_tls_CAfile, in which case it is not necessary to have them in the smtpd_tls_cert_file, smtpd_tls_dcert_file (obsolete) or smtpd_tls_eccert_file.

A certificate supplied here must be usable as an SSL server certificate and hence pass the openssl verify -purpose sslserver ... test.

Example:

smtpd_tls_cert_file = /etc/postfix/server.pem

This feature is available in Postfix 2.2 and later.

`smtpd_tls_chain_files` (default: empty) 🔑✨

okay bestie, this one is a whole glow-up for how Postfix handles TLS keys, so listen up. This is a list of one or more PEM files, and each one is holding one or more private keys directly followed by a corresponding certificate chain. The file names get separated by commas and/or whitespace — either works, no stress.

This parameter is the moment that obsoletes the legacy algorithm-specific key and certificate file settings. And it's not playing around: when this parameter is non-empty, those legacy parameters are ignored, and a warning gets logged if any of them are also non-empty. Consider it a gentle "girl, we moved on" 💅.

So here's the tea. With the proliferation of multiple private key algorithms — which, as of OpenSSL 1.1.1, include DSA (obsolete), RSA, ECDSA, Ed25519 and Ed448 — it is increasingly impractical to use separate parameters to configure the key and certificate chain for each algorithm. So Postfix now supports storing multiple keys and their corresponding certificate chains in a single file or in a set of files. Iconic, honestly.

The rules, and yes you need to know them:

Each key must appear immediately before the corresponding certificate.
After that certificate you can optionally tack on additional issuer certificates that complete the certificate chain for that key.
When multiple files are specified, they're equivalent to a single file that is concatenated from those files in the given order.
So while a key must always precede its certificate and issuer chain, it can live in a separate file — as long as that file is listed immediately before the file that holds the corresponding certificate chain.
Once all the files are concatenated, the sequence of PEM objects must be: key1, cert1, [chain1], key2, cert2, [chain2], ..., keyN, certN, [chainN].

Real talk 🫶: storing the private key in the same file as the corresponding certificate is more reliable. With the key and certificate in separate files, there's a chance that during key rollover a Postfix process might load a private key and certificate from separate files that don't match. And various operational errors may even result in a persistent broken configuration in which the certificate does not match the private key. Not the vibe. 😭

Also, the file or files must contain at most one key of each type. If, for example, two or more RSA keys and corresponding chains are listed, then depending on the version of OpenSSL either only the last one will be used or a configuration error may be detected. The way that's just gambling with your config 💀.

And a lil note: while "Ed25519" and "Ed448" are considered separate algorithms, the various ECDSA curves (typically one of prime256v1, secp384r1 or secp521r1) are considered as different parameters of a single "ECDSA" algorithm, so it is not presently possible to configure keys for more than one ECDSA curve. Sad but true, bestie.

Where we're at algorithm-wise: RSA is still the most widely supported algorithm. Presently (late 2018), ECDSA support is common, but not yet universal, and Ed25519 and Ed448 support is mostly absent. Therefore, an RSA key should generally be configured, along with any additional keys for the other algorithms when desired. 🔥

Example — separate files for each key and corresponding certificate chain:

/etc/postfix/main.cf:
    smtpd_tls_chain_files =
        ${config_directory}/ed25519.pem,
        ${config_directory}/ed448.pem,
        ${config_directory}/rsa.pem

/etc/postfix/ed25519.pem:
    -----BEGIN PRIVATE KEY-----
    MC4CAQAwBQYDK2VwBCIEIEJfbbO4BgBQGBg9NAbIJaDBqZb4bC4cOkjtAH+Efbz3
    -----END PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIIBKzCB3qADAgECAhQaw+rflRreYuUZBp0HuNn/e5rMZDAFBgMrZXAwFDESMBAG
    ...
    nC0egv51YPDWxEHom4QA
    -----END CERTIFICATE-----

/etc/postfix/ed448.pem:
    -----BEGIN PRIVATE KEY-----
    MEcCAQAwBQYDK2VxBDsEOQf+m0P+G0qi+NZ0RolyeiE5zdlPQR8h8y4jByBifpIe
    LNler7nzHQJ1SLcOiXFHXlxp/84VZuh32A==
    -----END PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIIBdjCB96ADAgECAhQSv4oP972KypOZPNPF4fmsiQoRHzAFBgMrZXEwFDESMBAG
    ...
    pQcWsx+4J29e6YWH3Cy/CdUaexKP4RPCZDrPX7bk5C2BQ+eeYOxyThMA
    -----END CERTIFICATE-----

/etc/postfix/rsa.pem:
    -----BEGIN PRIVATE KEY-----
    MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDc4QusgkahH9rL
    ...
    ahQkZ3+krcaJvDSMgvu0tDc=
    -----END PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIIC+DCCAeCgAwIBAgIUIUkrbk1GAemPCT8i9wKsTGDH7HswDQYJKoZIhvcNAQEL
    ...
    Rirz15HGVNTK8wzFd+nulPzwUo6dH2IU8KazmyRi7OGvpyrMlm15TRE2oyE=
    -----END CERTIFICATE-----

Example — all keys and certificates in a single file:

/etc/postfix/main.cf:
    smtpd_tls_chain_files = ${config_directory}/chains.pem

/etc/postfix/chains.pem:
    -----BEGIN PRIVATE KEY-----
    MC4CAQAwBQYDK2VwBCIEIEJfbbO4BgBQGBg9NAbIJaDBqZb4bC4cOkjtAH+Efbz3
    -----END PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIIBKzCB3qADAgECAhQaw+rflRreYuUZBp0HuNn/e5rMZDAFBgMrZXAwFDESMBAG
    ...
    nC0egv51YPDWxEHom4QA
    -----END CERTIFICATE-----
    -----BEGIN PRIVATE KEY-----
    MEcCAQAwBQYDK2VxBDsEOQf+m0P+G0qi+NZ0RolyeiE5zdlPQR8h8y4jByBifpIe
    LNler7nzHQJ1SLcOiXFHXlxp/84VZuh32A==
    -----END PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIIBdjCB96ADAgECAhQSv4oP972KypOZPNPF4fmsiQoRHzAFBgMrZXEwFDESMBAG
    ...
    pQcWsx+4J29e6YWH3Cy/CdUaexKP4RPCZDrPX7bk5C2BQ+eeYOxyThMA
    -----END CERTIFICATE-----
    -----BEGIN PRIVATE KEY-----
    MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDc4QusgkahH9rL
    ...
    ahQkZ3+krcaJvDSMgvu0tDc=
    -----END PRIVATE KEY-----
    -----BEGIN CERTIFICATE-----
    MIIC+DCCAeCgAwIBAgIUIUkrbk1GAemPCT8i9wKsTGDH7HswDQYJKoZIhvcNAQEL
    ...
    Rirz15HGVNTK8wzFd+nulPzwUo6dH2IU8KazmyRi7OGvpyrMlm15TRE2oyE=
    -----END CERTIFICATE-----

This feature is available in Postfix 3.4 and later. 💖

`smtpd_tls_cipherlist` (default: empty) 🚫

ngl bestie, this one is obsolete. It's the Postfix < 2.3 control for the Postfix SMTP server TLS cipher list. It's easy to create interoperability problems by choosing a non-default cipher list. So do not use a non-default TLS cipherlist for MX hosts on the public Internet. Clients that begin the TLS handshake, but are unable to agree on a common cipher, may not be able to send any email to the SMTP server. That's giving "silently undelivered mail" energy and we hate that 😭.

Using a restricted cipher list may be more appropriate for a dedicated MSA or an internal mailhub, where one can exert some control over the TLS software and settings of the connecting clients. That's the only context where this makes sense, okay?

Note: do not use "" quotes around the parameter value. Fr fr, just don't.

This feature is available with Postfix version 2.2. It is not used with Postfix 2.3 and later — use smtpd_tls_mandatory_ciphers instead. Moving on! 💅

`smtpd_tls_ciphers` (default: medium) 🔐

This sets the minimum TLS cipher grade that the Postfix SMTP server will use with opportunistic TLS encryption. Cipher types listed in smtpd_tls_exclude_ciphers are excluded from the base definition of the selected cipher grade — so that's the carve-out, bestie.

The default value is "medium" for Postfix releases after the middle of 2015, and "export" for older releases.

When TLS is mandatory, the cipher grade is chosen via the smtpd_tls_mandatory_ciphers configuration parameter — go look there for syntax details. 👑

This feature is available in Postfix 2.6 and later. With earlier Postfix releases only the smtpd_tls_mandatory_ciphers parameter is implemented, and opportunistic TLS always uses "export" or better (i.e. all) ciphers. Wild, but okay. 🌈

`smtpd_tls_dcert_file` (default: empty) 📜

A file with the Postfix SMTP server DSA certificate in PEM format. This file may also contain the Postfix SMTP server private DSA key.

Heads up 🫶: the DSA algorithm is obsolete and should not be used. Keep it in the history books.

See the discussion under smtpd_tls_cert_file for more details.

Example:

smtpd_tls_dcert_file = /etc/postfix/server-dsa.pem

This feature is available in Postfix 2.2 and later.

`smtpd_tls_dh1024_param_file` (default: empty) 🌳

A file with DH parameters that the Postfix SMTP server should use with non-export EDH ciphers.

With Postfix >= 3.7, built with OpenSSL version 3.0.0 or later, if the parameter value is either empty or "auto", then the DH parameter selection is delegated to the OpenSSL library, which selects appropriate parameters based on the TLS handshake. This choice is likely to be the most interoperable with SMTP clients using various TLS libraries, and custom local parameters are no longer recommended when using Postfix >= 3.7 built against OpenSSL 3.0.0. So basically: just let OpenSSL cook 🔥.

The best-practice choice of parameters uses a 2048-bit prime. This is fine, despite the historical "1024" in the parameter name — don't let the name gaslight you. Do not be tempted to use much larger values: performance degrades quickly, and you may also cease to interoperate with some mainstream SMTP clients. 😭 As of Postfix 3.1, the compiled-in default prime is 2048-bits, and it is not strictly necessary, though perhaps somewhat beneficial, to generate custom DH parameters.

Instead of using the exact same parameter sets as distributed with other TLS packages, it is more secure to generate your own set of parameters with something like the following commands:

openssl dhparam -out /etc/postfix/dh2048.pem 2048
openssl dhparam -out /etc/postfix/dh1024.pem 1024
# As of Postfix 3.6, export-grade 512-bit DH parameters are no longer
# supported or needed.
openssl dhparam -out /etc/postfix/dh512.pem 512

It is safe to share the same DH parameters between multiple Postfix instances. If you prefer, you can generate separate parameters for each instance. Your call, bestie 💅.

If you want to take maximal advantage of ciphers that offer forward secrecy, see the Getting started section of FORWARD_SECRECY_README. The full document conveniently presents all information about Postfix "perfect" forward secrecy support in one place: what forward secrecy is, how to tweak settings, and what you can expect to see when Postfix uses ciphers with forward secrecy. Obsessed with a one-stop doc, honestly 🎀.

Example:

smtpd_tls_dh1024_param_file = /etc/postfix/dh2048.pem

This feature is available in Postfix 2.2 and later.

`smtpd_tls_dh512_param_file` (default: empty) 🌸

A file with DH parameters that the Postfix SMTP server should use with export-grade EDH ciphers. The default SMTP server cipher grade is "medium" with Postfix releases after the middle of 2015, and as a result export-grade cipher suites are by default not used.

With Postfix >= 3.6, export-grade Diffie-Hellman key exchange is no longer supported, and this parameter is silently ignored. It said "not me showing up to a party that ended" 💀.

See also the discussion under the smtpd_tls_dh1024_param_file configuration parameter.

Example:

smtpd_tls_dh512_param_file = /etc/postfix/dh_512.pem

This feature is available in Postfix 2.2 and later, but is ignored in Postfix 3.6 and later.

`smtpd_tls_dkey_file` (default: `$smtpd_tls_dcert_file`)

okay so bestie, this one is the file holding the Postfix SMTP server's DSA private key, in PEM format 💖. You can literally combine it with the Postfix SMTP server DSA certificate file you set with $smtpd_tls_dcert_file. cute, right?

🛑 but no cap — the DSA algorithm is obsolete and should not be used. periodt. leave it in the past where it belongs 🙈

The private key has to be accessible without a pass-phrase, aka it must not be encrypted. And the file permissions? They should grant read-only access to the system superuser account ("root") and no access to anyone else. Not even your most trusted mutual. 🚫

This feature is available in Postfix 2.2 and later. ✨

`smtpd_tls_eccert_file` (default: empty)

File with the Postfix SMTP server ECDSA certificate in PEM format 🌸. This file may also contain the Postfix SMTP server private ECDSA key — two icons in one file, we love efficiency 💅.

With Postfix >= 3.4 the preferred way to configure server keys and certificates is via the "smtpd_tls_chain_files" parameter. so like, if you're on 3.4+ that's the moment, that's the move 👑

See the discussion under smtpd_tls_cert_file for more details. (we already covered that one, scroll up bestie 🫶)

Example:

smtpd_tls_eccert_file = /etc/postfix/ecdsa-scert.pem

This feature is available in Postfix 2.6 and later, when Postfix is compiled and linked with OpenSSL 1.0.0 or later. ⭐

`smtpd_tls_eckey_file` (default: `$smtpd_tls_eccert_file`)

File with the Postfix SMTP server ECDSA private key in PEM format 🔐. This file may be combined with the Postfix SMTP server ECDSA certificate file specified with $smtpd_tls_eccert_file. And yeah, same energy as before: with Postfix >= 3.4 the preferred way to configure server keys and certificates is via the "smtpd_tls_chain_files" parameter 💜.

The private key must be accessible without a pass-phrase, i.e. it must not be encrypted. File permissions should grant read-only access to the system superuser account ("root"), and no access to anyone else. seriously, nobody else 😤

This feature is available in Postfix 2.6 and later, when Postfix is compiled and linked with OpenSSL 1.0.0 or later. ✨

`smtpd_tls_eecdh_grade` (default: see `postconf -d` output)

The Postfix SMTP server security grade for ephemeral elliptic-curve Diffie-Hellman (EECDH) key exchange 🌈. As of Postfix 3.6, the value of this parameter is always ignored, and Postfix behaves as though the auto value (described below) was chosen.

💀 This feature is not used as of Postfix 3.6. Do not specify. like, don't even bother.

The available choices are:

auto — Use the most preferred curve that is supported by both the client and the server. This setting requires Postfix >= 3.2 compiled and linked with OpenSSL >= 1.0.2. This is the default setting under the above conditions (and the only setting used with Postfix >= 3.6). 👑
none — Don't use EECDH. Ciphers based on EECDH key exchange will be disabled. This is the default in Postfix versions 2.6 and 2.7.
strong — Use EECDH with approximately 128 bits of security at a reasonable computational cost. This is the default in Postfix versions 2.8-3.5. 💪
ultra — Use EECDH with approximately 192 bits of security at computational cost that is approximately twice as high as 128 bit strength ECC. highkey extra, lowkey expensive 🔥

If you want to take maximal advantage of ciphers that offer forward secrecy see the Getting started section of FORWARD_SECRECY_README 📖. The full document conveniently presents all information about Postfix "perfect" forward secrecy support in one place: what forward secrecy is, how to tweak settings, and what you can expect to see when Postfix uses ciphers with forward secrecy. one doc, all the lore, obsessed 🎀

This feature is available in Postfix 2.6 and later, when it is compiled and linked with OpenSSL 1.0.0 or later on platforms where EC algorithms have not been disabled by the vendor.

`smtpd_tls_enable_rpk` (default: no)

Request that remote SMTP clients send an RFC7250 raw public key instead of an X.509 certificate, when asking for or requiring client authentication 🔑. This feature is ignored when there is no raw public key support in the local TLS implementation. (no support, no vibes, it just shrugs 🫠)

The Postfix SMTP server will log a warning when "smtpd_tls_enable_rpk = yes", but the remote SMTP client sends a certificate, the certificate's public key fingerprint does not match a check_ccert_access table, while the certificate fingerprint does match a check_ccert_access table. The remote SMTP client would lose access when it starts sending a raw public key instead of a certificate, after its TLS implementation is updated with raw public key support. 😭 so yeah, read that warning, it's giving foreshadowing.

The Postfix SMTP server always sends a raw public key instead of a certificate, if solicited by the remote SMTP client and the local TLS implementation supports raw public keys. If the client sends a server name indication with an SNI TLS extension, and tls_server_sni_maps is configured, the server will extract a raw public key from the indicated certificate. 🦋

Sample commands to compute certificate and public key SHA256 digests:

# SHA256 digest of the first certificate in "cert.pem"
$ openssl x509 -in cert.pem -outform DER | openssl dgst -sha256 -c

# SHA256 digest of the SPKI of the first certificate in "cert.pem"
$ openssl x509 -in cert.pem -pubkey -noout |
    openssl pkey -pubin -outform DER | openssl dgst -sha256 -c

# SHA256 digest of the SPKI of the first private key in "pkey.pem"
$ openssl pkey -in pkey.pem -pubout -outform DER |
    openssl dgst -sha256 -c

This feature is available in Postfix 3.9 and later. ⭐

`smtpd_tls_exclude_ciphers` (default: empty)

List of ciphers or cipher types to exclude from the SMTP server cipher list at all TLS security levels 🚫. Excluding valid ciphers can create interoperability problems.

⚠️ DO NOT exclude ciphers unless it is essential to do so. like, fr fr, this is the "don't touch it unless you have to" button.

This is not an OpenSSL cipherlist; it is a simple list separated by whitespace and/or commas. The elements are a single cipher, or one or more "+" separated cipher properties, in which case only ciphers matching all the properties are excluded. 💅

Examples (some of these will cause problems):

smtpd_tls_exclude_ciphers = aNULL
smtpd_tls_exclude_ciphers = MD5, DES
smtpd_tls_exclude_ciphers = DES+MD5
smtpd_tls_exclude_ciphers = AES256-SHA, DES-CBC3-MD5
smtpd_tls_exclude_ciphers = kEDH+aRSA

The first setting disables anonymous ciphers. The next setting disables ciphers that use the MD5 digest algorithm or the (single) DES encryption algorithm. The next setting disables ciphers that use MD5 and DES together. The next setting disables the two ciphers "AES256-SHA" and "DES-CBC3-MD5". The last setting disables ciphers that use "EDH" key exchange with RSA authentication. see how it adds up? math is math 📐

This feature is available in Postfix 2.3 and later. ✨

`smtpd_tls_fingerprint_digest` (default: see `postconf -d` output)

The message digest algorithm to construct remote SMTP client-certificate fingerprints or public key fingerprints (Postfix 2.9 and later) for check_ccert_access and permit_tls_clientcerts 🔍.

The default algorithm is sha256 with Postfix >= 3.6 and the compatibility_level set to 3.6 or higher. With Postfix <= 3.5, the default algorithm is md5.

The best-practice algorithm is now sha256. Recent advances in hash function cryptanalysis have led to md5 and sha1 being deprecated in favor of sha256. However, as long as there are no known "second pre-image" attacks against the older algorithms, their use in this context, though not recommended, is still likely safe. yk, the old ones are probably fine, but why settle 💅

While additional digest algorithms are often available with OpenSSL's libcrypto, only those used by libssl in SSL cipher suites are available to Postfix. You'll likely find support for md5, sha1, sha256 and sha512. 🌸

To find the fingerprint of a specific certificate file, with a specific digest algorithm, run:

$ openssl x509 -noout -fingerprint -digest -in certfile.pem

The text to the right of "=" sign is the desired fingerprint. For example:

$ openssl x509 -noout -fingerprint -sha256 -in cert.pem
SHA256 Fingerprint=D4:6A:AB:19:24:...:A6:CB:66:82:C0:8E:9B:EE:29:A8:1A

To extract the public key fingerprint from an X.509 certificate, you need to extract the public key from the certificate and compute the appropriate digest of its DER (ASN.1) encoding 🧚. With OpenSSL the "-pubkey" option of the "x509" command extracts the public key always in "PEM" format. We pipe the result to another OpenSSL command that converts the key to DER and then to the "dgst" command to compute the fingerprint. pipe pipe pipe, it's giving assembly line 🏭

Example:

$ openssl x509 -in cert.pem -noout -pubkey |
    openssl pkey -pubin -outform DER |
    openssl dgst -sha256 -c
(stdin)= 64:3f:1f:f6:e5:1e:d4:2a:56:8b:fc:09:1a:61:98:b5:bc:7c:60:58

The Postfix SMTP server and client log the peer (leaf) certificate fingerprint and public key fingerprint when the TLS loglevel is 2 or higher 👀.

Example: client-certificate access table, with sha256 fingerprints:

/etc/postfix/main.cf:
    smtpd_tls_fingerprint_digest = sha256
    smtpd_client_restrictions =
        check_ccert_access lmdb:/etc/postfix/access,
        reject

/etc/postfix/access:
    # Action folded to next line...
    AF:88:7C:AD:51:95:6F:36:96:...:01:FB:2E:48:CD:AB:49:25:A2:3B
        OK
    85:16:78:FD:73:6E:CE:70:E0:...:5F:0D:3C:C8:6D:C4:2C:24:59:E1
        permit_auth_destination

Instead of lmdb:, some systems use cdb:, hash:, or dbm:.

The default indexed file type is configured with the default_database_type parameter. To list available explicit types, execute the command "postconf -m".

Configuration changes will become visible after a minute or so ⏳. Use "postfix reload" to eliminate the delay. impatient? same. reload it 💅

This feature is available in Postfix 2.5 and later. ⭐

`smtpd_tls_key_file` (default: `$smtpd_tls_cert_file`)

File with the Postfix SMTP server RSA private key in PEM format 🔐. This file may be combined with the Postfix SMTP server RSA certificate file specified with $smtpd_tls_cert_file. With Postfix >= 3.4 the preferred way to configure server keys and certificates is via the "smtpd_tls_chain_files" parameter 👑.

smtpd_tls_loglevel (default: 0) — turns on extra logging of TLS happenings in the Postfix SMTP server. Every level bundles in everything the lower levels log too, so it's cumulative, bestie.
- 0 — nah, zero TLS logging. Silence.
- 1 — logs just a lil summary message when the TLS handshake finishes. Does NOT log client certificate trust-chain verification errors if client cert verification isn't required. On Postfix 2.8 and earlier it logs the summary message, peer certificate summary info, and unconditionally logs trust-chain verification errors.
- 2 — also enables verbose logging in the Postfix TLS library, logs session cache operations, and turns on OpenSSL logging of the SSL handshake progress.
- 3 — also logs a hexadecimal and ASCII dump of the TLS negotiation process.
- 4 — also logs a hexadecimal and ASCII dump of the complete transmission after STARTTLS.

Real talk: do not use smtpd_tls_loglevel = 2 or higher except when you're actually troubleshooting problems. Loglevel 4 is strongly discouraged. 🫣

This feature is available in Postfix 2.2 and later.

smtpd_tls_mandatory_ciphers (default: medium) — the minimum TLS cipher grade the Postfix SMTP server will accept when TLS encryption is mandatory. Like, the floor, bestie. The default grade (medium) is genuinely strong enough that globally restricting TLS sessions to a stricter grade is probably giving negligible benefit — especially since so many implementations still don't even offer any stronger (high grade) ciphers, and the ones that do will always use high grade ciphers anyway. So insisting on high grade is, lowkey, counter-productive. ✨ Allowing export or low ciphers is typically not a good idea, since systems limited to just those are limited to obsolete browsers. No known SMTP clients fail to support at least one medium or high grade cipher, so, yeah.

These are the cipher grades that exist:

high — only HIGH grade OpenSSL ciphers. The underlying cipherlist is specified via the tls_high_cipherlist configuration parameter, and you are strongly encouraged to not change it.
medium — MEDIUM grade or stronger OpenSSL ciphers. These use 128-bit or longer symmetric bulk-encryption keys. This is the default minimum strength for mandatory TLS encryption. The underlying cipherlist is specified via the tls_medium_cipherlist configuration parameter, which you are strongly encouraged not to change.
null — only the NULL OpenSSL ciphers, which provide authentication without encryption. This setting is only appropriate in that rare case where every single client is prepared to use NULL ciphers (not normally enabled in TLS clients, fyi). The underlying cipherlist is specified via the tls_null_cipherlist configuration parameter, which you are strongly encouraged not to change.
low — LOW grade or stronger OpenSSL ciphers. In Postfix >= 3.8 this cipher grade is always identical to medium. Recent versions of OpenSSL don't support any LOW grade ciphers at all. In earlier Postfix releases the underlying cipherlist was specified via the tls_low_cipherlist configuration parameter, which you are strongly encouraged not to change. This obsolete cipher grade SHOULD NOT be used. 🚩
export — EXPORT grade or stronger OpenSSL ciphers. In Postfix >= 3.8 this cipher grade is always identical to medium. Recent versions of OpenSSL don't support any EXPORT grade ciphers. In earlier Postfix releases the underlying cipherlist was specified via the tls_export_cipherlist configuration parameter, which you are strongly encouraged not to change. This obsolete cipher grade SHOULD NOT be used either. 🚩

Cipher types listed in smtpd_tls_mandatory_exclude_ciphers or smtpd_tls_exclude_ciphers get excluded from the base definition of whatever cipher grade you picked. For the cipher controls that apply to opportunistic TLS, go see smtpd_tls_ciphers.

The underlying cipherlists for grades other than null include anonymous ciphers, but these get automatically filtered out if the server is configured to ask for remote SMTP client certificates. You are very unlikely to ever need to take any steps to exclude anonymous ciphers — they're excluded automatically as required, it's handled, periodt. If you genuinely must exclude anonymous ciphers even when Postfix does not need or use peer certificates, set smtpd_tls_exclude_ciphers = aNULL. To exclude anonymous ciphers only when TLS is enforced, set smtpd_tls_mandatory_exclude_ciphers = aNULL.

This feature is available in Postfix 2.3 and later.

smtpd_tls_mandatory_exclude_ciphers (default: empty) — an additional list of ciphers or cipher types to exclude from the Postfix SMTP server cipher list at mandatory TLS security levels. This list works on top of the exclusions already listed with smtpd_tls_exclude_ciphers (go look over there for the syntax deets, iykyk).

This feature is available in Postfix 2.3 and later.

smtpd_tls_mandatory_protocols (default: see postconf -d output) — the TLS protocols the Postfix SMTP server accepts when TLS encryption is mandatory. If the list is empty, the server supports all available TLS protocol versions. A non-empty value is a list of protocol names to include or exclude, separated by whitespace, commas or colons.

The valid protocol names (see SSL_get_version(3)) are SSLv2, SSLv3, TLSv1, TLSv1.1, TLSv1.2 and TLSv1.3. Starting with Postfix 3.6, the default value is >=TLSv1, which sets TLS 1.0 as the lowest supported TLS protocol version (more on that below). Older releases use the ! exclusion syntax, also described below, bestie don't worry.

As of Postfix 3.6, the preferred way to limit the range of acceptable protocols is to set the lowest acceptable TLS protocol version and/or the highest acceptable TLS protocol version. To set the lower bound, include an element of the form >=version where version is either one of the TLS protocol names listed above, or a hexadecimal number corresponding to the desired TLS protocol version (0301 for TLS 1.0, 0302 for TLS 1.1, etc.). For the upper bound, use <=version. There must be no whitespace between the >= or <= symbols and the protocol name or number. Fussy, I know, but that's the vibe.

Hexadecimal protocol numbers make it possible to specify protocol bounds for TLS versions that are known to OpenSSL but might not be known to Postfix. They cannot be used with the legacy exclusion syntax. Leading 0 or 0x prefixes are supported, but not required. Therefore, 301, 0301, 0x301 and 0x0301 are all equivalent to TLSv1. Hexadecimal versions unknown to OpenSSL will fail to set the upper or lower bound, and a warning will be logged. Hexadecimal versions should only be used when Postfix is linked with some future version of OpenSSL that supports TLS 1.4 or later, but Postfix does not yet support a symbolic name for that protocol version.

Hexadecimal example (Postfix >= 3.6):

# Allow only TLS 1.2 through (hypothetical) TLS 1.4, once supported
# in some future version of OpenSSL (presently a warning is logged).
smtpd_tls_mandatory_protocols = >=TLSv1.2, <=0305
# Allow only TLS 1.2 and up:
smtpd_tls_mandatory_protocols = >=0x0303

With Postfix < 3.6 there is no support for a minimum or maximum version, and the protocol range is configured via protocol exclusions. To require at least TLS 1.0, set smtpd_tls_mandatory_protocols = !SSLv2, !SSLv3. Listing the protocols to include, rather than protocols to exclude, is supported, but not recommended. The exclusion form more accurately matches the underlying OpenSSL interface.

Support for TLSv1.3 was introduced in OpenSSL 1.1.1. Disabling this protocol via !TLSv1.3 is supported since Postfix 3.4 (or patch releases >= 3.0.14, 3.1.10, 3.2.7 and 3.3.2).

Example:

# Preferred syntax with Postfix >= 3.6:
smtpd_tls_mandatory_protocols = >=TLSv1.2, <=TLSv1.3
# Legacy syntax:
smtpd_tls_mandatory_protocols = !SSLv2, !SSLv3, !TLSv1, !TLSv1.1

This feature is available in Postfix 2.3 and later.

smtpd_tls_protocols (default: see 'postconf -d' output)

TLS protocols that your Postfix SMTP server is willing to vibe with when it's doing opportunistic TLS encryption. If the list is empty, bestie, the server supports every single available TLS protocol version — all of them, no filter. 💅 A non-empty value is a list of protocol names to include or exclude, separated by whitespace, commas or colons.

The valid protocol names (peep SSL_get_version(3)) are "SSLv2", "SSLv3", "TLSv1", "TLSv1.1", "TLSv1.2" and "TLSv1.3". Starting with Postfix 3.6, the default value is ">=TLSv1", which sets TLS 1.0 as the lowest supported TLS protocol version (see below). Older releases use the "!" exclusion syntax, also described below.

As of Postfix 3.6, the preferred way to limit the range of acceptable protocols is to set the lowest acceptable TLS protocol version and/or the highest acceptable TLS protocol version. To set the lower bound include an element of the form: ">=version" where version is a either one of the TLS protocol names listed above, or a hexadecimal number corresponding to the desired TLS protocol version (0301 for TLS 1.0, 0302 for TLS 1.1, etc.). For the upper bound, use "<=version". There must be no whitespace between the ">=" or "<=" symbols and the protocol name or number. ⚠️

Hexadecimal protocol numbers make it possible to specify protocol bounds for TLS versions that are known to OpenSSL, but might not be known to Postfix. They cannot be used with the legacy exclusion syntax. Leading "0" or "0x" prefixes are supported, but not required. Therefore, "301", "0301", "0x301" and "0x0301" are all equivalent to "TLSv1". Hexadecimal versions unknown to OpenSSL will fail to set the upper or lower bound, and a warning will be logged. Hexadecimal versions should only be used when Postfix is linked with some future version of OpenSSL that supports TLS 1.4 or later, but Postfix does not yet support a symbolic name for that protocol version. 🔮

Hexadecimal example (Postfix >= 3.6):

# Allow only TLS 1.0 through (hypothetical) TLS 1.4, once supported
# in some future version of OpenSSL (presently a warning is logged).
smtpd_tls_protocols = >=TLSv1, <=0305
# Allow only TLS 1.0 and up:
smtpd_tls_protocols = >=0x0301

With Postfix < 3.6 there is no support for a minimum or maximum version, and the protocol range is configured via protocol exclusions. To require at least TLS 1.0, set "smtpd_tls_protocols = !SSLv2, !SSLv3". Listing the protocols to include, rather than protocols to exclude, is supported, but not recommended. The exclusion form more accurately matches the underlying OpenSSL interface.

Support for "TLSv1.3" was introduced in OpenSSL 1.1.1. Disabling this protocol via "!TLSv1.3" is supported since Postfix 3.4 (or patch releases >= 3.0.14, 3.1.10, 3.2.7 and 3.3.2).

Example:

# Preferred syntax with Postfix >= 3.6:
smtpd_tls_protocols = >=TLSv1, <=TLSv1.3
# Legacy syntax:
smtpd_tls_protocols = !SSLv2, !SSLv3

This feature is available in Postfix 2.6 and later.

smtpd_tls_received_header (default: no)

Request that the Postfix SMTP server produces Received: message headers that include information about the protocol and cipher used, as well as the remote SMTP client CommonName and client certificate issuer CommonName. 📨

This is disabled by default, as the information may be modified in transit through other mail servers. Only information that was recorded by the final destination can be trusted. Don't @ me, that's just how it is. 😭

This feature is available in Postfix 2.2 and later.

smtpd_tls_req_ccert (default: no)

With mandatory TLS encryption, require a trusted remote SMTP client certificate in order to allow TLS connections to proceed. 🔒 This option implies "smtpd_tls_ask_ccert = yes".

When TLS encryption is optional, this setting is ignored with a warning written to the mail log. ✍️

This feature is available in Postfix 2.2 and later.

smtpd_tls_security_level (default: empty)

The SMTP TLS security level for the Postfix SMTP server; when a non-empty value is specified, this overrides the obsolete parameters smtpd_use_tls and smtpd_enforce_tls. This parameter is ignored with "smtpd_tls_wrappermode = yes".

Specify one of the following security levels:

none — TLS will not be used. 🚫
may — Opportunistic TLS: announce STARTTLS support to remote SMTP clients, but do not require that clients use TLS encryption. 😌
encrypt — Mandatory TLS encryption: announce STARTTLS support to remote SMTP clients, and reject all plaintext commands except HELO, EHLO, XCLIENT, STARTTLS, NOOP, QUIT, and (Postfix >= 3.9) HELP. According to RFC 2487 this MUST NOT be applied in case of a publicly-referenced SMTP server. Instead, this should be used on dedicated servers, for example submission (port 587). 🔥

Note 1: the "fingerprint", "verify" and "secure" levels are not supported here. The Postfix SMTP server logs a warning and uses "encrypt" instead. To verify remote SMTP client certificates, see TLS_README for a discussion of the smtpd_tls_ask_ccert, smtpd_tls_req_ccert, and permit_tls_clientcerts features. 👑

Note 2: The parameter setting "smtpd_tls_security_level = encrypt" implies "smtpd_tls_auth_only = yes". 💖

Note 3: when invoked via "sendmail -bs", Postfix will never offer STARTTLS due to insufficient privileges to access the server private key. This is intended behavior. 🤷♀️

This feature is available in Postfix 2.3 and later.

smtpd_tls_session_cache_database (default: empty)

Name of the file containing the optional Postfix SMTP server TLS session cache. 🗄️ Specify a database type that supports enumeration, such as btree or sdbm; there is no need to support concurrent access. The file is created if it does not exist. The smtpd(8) daemon does not use this parameter directly, rather the cache is implemented indirectly in the tlsmgr(8) daemon. This means that per-smtpd-instance master.cf overrides of this parameter are not effective. Note that each of the cache databases supported by tlsmgr(8) daemon: $smtpd_tls_session_cache_database, $smtp_tls_session_cache_database (and with Postfix 2.3 and later $lmtp_tls_session_cache_database), needs to be stored separately. It is not at this time possible to store multiple caches in a single database. 🙅♀️

Note: dbm databases are not suitable. TLS session objects are too large. 💀

As of version 2.5, Postfix no longer uses root privileges when opening this file. The file should now be stored under the Postfix-owned data_directory. As a migration aid, an attempt to open the file under a non-Postfix directory is redirected to the Postfix-owned data_directory, and a warning is logged. 📝

As of Postfix 2.11 the preferred mechanism for session resumption is RFC 5077 TLS session tickets, which don't require server-side storage. Consequently, for Postfix >= 2.11 this parameter should generally be left empty. TLS session tickets require an OpenSSL library (at least version 0.9.8h) that provides full support for this TLS extension. See also smtpd_tls_session_cache_timeout. 🎟️

Examples:

smtpd_tls_session_cache_database = lmdb:/var/lib/postfix/smtpd_scache
smtpd_tls_session_cache_database = btree:/var/lib/postfix/smtpd_scache

This feature is available in Postfix 2.2 and later.

smtpd_tls_session_cache_timeout (default: 3600s)

The expiration time of Postfix SMTP server TLS session cache information. ⏳ A cache cleanup is performed periodically every $smtpd_tls_session_cache_timeout seconds. As with $smtpd_tls_session_cache_database, this parameter is implemented in the tlsmgr(8) daemon and therefore per-smtpd-instance master.cf overrides are not possible.

As of Postfix 2.11 this setting cannot exceed 100 days. If set <= 0, session caching is disabled, not just via the database, but also via RFC 5077 TLS session tickets, which don't require server-side storage. If set to a positive value less than 2 minutes, the minimum value of 2 minutes is used instead. TLS session tickets require an OpenSSL library (at least version 0.9.8h) that provides full support for this TLS extension. 🦋

This feature is available in Postfix 2.2 and later, and updated for TLS session ticket support in Postfix 2.11.

smtpd_tls_wrappermode (default: no)

Run the Postfix SMTP server in TLS "wrapper" mode, instead of using the STARTTLS command. 🎁

If you want to support this service, enable a special port in master.cf, and specify "-o smtpd_tls_wrappermode=yes" on the SMTP server's command line. Port 465 (submissions, formerly called smtps) is reserved for this purpose. 📮

This feature is available in Postfix 2.2 and later.

smtpd_upstream_proxy_protocol (default: empty)

The name of the proxy protocol used by an optional before-smtpd proxy agent. When a proxy agent is used, this protocol conveys local and remote address and port information. Specify "smtpd_upstream_proxy_protocol = haproxy" to enable the haproxy protocol; version 2 is supported with Postfix 3.5 and later. 🛰️

NOTE: To use the nginx proxy with smtpd(8), enable the XCLIENT protocol with smtpd_authorized_xclient_hosts. This supports SASL authentication in the proxy agent (Postfix 2.9 and later). 🌸

This feature is available in Postfix 2.10 and later.

smtpd_upstream_proxy_timeout (default: 5s)

The time limit for the proxy protocol specified with the smtpd_upstream_proxy_protocol parameter. ⏱️

This feature is available in Postfix 2.10 and later.

smtpd_use_tls (default: no)

Opportunistic TLS: announce STARTTLS support to remote SMTP clients, but do not require that clients use TLS encryption. 😌

Note: when invoked via "sendmail -bs", Postfix will never offer STARTTLS due to insufficient privileges to access the server private key. This is intended behavior. 🤷♀️

This feature is deprecated as of Postfix 3.9. Specify smtpd_tls_security_level instead. 🫶

This feature is available in Postfix 2.2 and later. With Postfix 2.3 and later use smtpd_tls_security_level instead.

🌸 `smtputf8_autodetect_classes` (default: `sendmail, verify`)

okay so this one is basically a little detective 🕵️‍♀️ it detects that a message actually requires SMTPUTF8 support, but only for the mail origin classes you list here. why tho? because it's a workaround for the chicken-and-egg problem during the initial SMTPUTF8 roll-out, in environments where there are already mail flows floating around that contain UTF8. those flows should NOT break just because Postfix suddenly refuses to deliver that mail to down-stream MTAs that don't announce SMTPUTF8 support. that would be so rude of it. 💀

the ✨problem✨ is that Postfix can't rely solely on the sender's declaration that a message requires SMTPUTF8 support, because UTF8 may be introduced during local processing. examples bestie, don't worry I got you:

the client hostname in Postfix's Received: header
adding @$myorigin or .$mydomain to an incomplete address
address rewriting
alias expansion
automatic BCC recipients
local forwarding
changes made by header checks or Milter applications

for now, the default is to enable "SMTPUTF8 required" autodetection only for Postfix sendmail command-line submissions and address verification probes. this may change once SMTPUTF8 support achieves world domination 👑 (their words, not mine). HOWEVER, sites that add UTF8 content via local processing (that whole list up there ⬆️) should autodetect the need for SMTPUTF8 support for all email.

specify one or more of these:

sendmail — submission with the Postfix sendmail(1) command.
smtpd — mail received with the smtpd(8) daemon.
qmqpd — mail received with the qmqpd(8) daemon.
forward — local forwarding or aliasing. when a message is received with "SMTPUTF8 required", then the forwarded (aliased) message always has "SMTPUTF8 required".
bounce — submission by the bounce(8) daemon. when a message is received with "SMTPUTF8 required", then the delivery status notification always has "SMTPUTF8 required".
notify — postmaster notification from the smtp(8) or smtpd(8) daemon.
verify — address verification probe from the verify(8) daemon.
all — enable SMTPUTF8 autodetection for all mail.

this feature is available in Postfix 3.0 and later. 🎀

🌈 `smtputf8_enable` (default: `yes`)

turns on preliminary SMTPUTF8 support for the protocols described in RFC 6531, RFC 6532, and RFC 6533. this requires that Postfix is built to support these protocols — so like, if it isn't, no amount of vibes will fix that. 🙈

this feature is available in Postfix 3.0 and later. ✨

🦋 `socketmap_max_reply_size` (default: `100000`)

the maximum allowed reply size from a socketmap server — and nope, this does not include the netstring encapsulation. 💅

this feature is available in Postfix >= 3.10.

🫶 `soft_bounce` (default: `no`)

the safety net 🥅 keeping mail queued that would otherwise get returned to the sender. this parameter:

disables locally-generated bounces,
changes the handling of negative responses from remote servers, content filters or plugins,
and prevents the Postfix SMTP server from rejecting mail permanently, by changing 5xx reply codes into 4xx.

however — and this is important bestie — soft_bounce is no cure for address rewriting mistakes or mail routing mistakes. it literally cannot fix those. 😭

Note: "soft_bounce = yes" is in some cases implemented by modifying server responses. therefore, the response that Postfix logs may differ from the response that Postfix actually sends or receives. so like, don't read the log and assume that's the whole story. 👀

Example:

soft_bounce = yes

🧚 `stale_lock_time` (default: `500s`)

the time after which a stale exclusive mailbox lockfile gets yeeted 🗑️. used for delivery to file or mailbox.

specify a non-zero time value — that's an integral value plus an optional one-letter suffix that tells you the time unit. the units are:

s (seconds)
m (minutes)
h (hours)
d (days)
w (weeks)

the default time unit is s (seconds).

💜 `stress` (default: `empty`)

this feature is documented in the STRESS_README document. (go read it, it's got lore 📖)

this feature is available in Postfix 2.5 and later.

🍓 `strict_7bit_headers` (default: `no`)

rejects mail that has 8-bit text in message headers. this blocks mail from poorly written applications. bye 👋

this feature should not be enabled on a general purpose mail server, because it is likely to reject legitimate email. like, it's giving "tough but fair" and then immediately being unfair. 💀

this feature is available in Postfix 2.0 and later.

🌟 `strict_8bitmime` (default: `no`)

enables both strict_7bit_headers and strict_8bitmime_body. a two-for-one, but like, the risky kind of two-for-one.

this feature should not be enabled on a general purpose mail server, because it is likely to reject legitimate email.

this feature is available in Postfix 2.0 and later.

🎀 `strict_8bitmime_body` (default: `no`)

rejects 8-bit message body text that doesn't come with 8-bit MIME content encoding information. this blocks mail from poorly written applications. slay? no. not slay. 🙈

unfortunately, this also rejects:

majordomo approval requests, when the included request contains valid 8-bit MIME mail
bounces from mailers that do not MIME encapsulate 8-bit content (for example, bounces from qmail or from old versions of Postfix)

this feature should not be enabled on a general purpose mail server, because it is likely to reject legitimate email.

this feature is available in Postfix 2.0 and later.

✨ `strict_mailbox_ownership` (default: `yes`)

defers delivery when a mailbox file is not owned by its recipient. the default setting is not backwards compatible — so heads up if you're coming from the old ways. 👑

this feature is available in Postfix 2.5.3 and later.

💖 `strict_mime_encoding_domain` (default: `no`)

rejects mail with invalid Content-Transfer-Encoding: information for the message/* or multipart/* MIME content types. this blocks mail from poorly written software.

this feature should not be enabled on a general purpose mail server, because it will reject mail after a single violation. one strike and you're out, no cap. 😭

this feature is available in Postfix 2.0 and later.

🌸 `strict_rfc821_envelopes` (default: `no`)

requires that addresses received in SMTP MAIL FROM and RCPT TO commands are enclosed with <>, and that those addresses do not contain RFC 822 style comments or phrases. this stops mail from poorly written software.

by default, the Postfix SMTP server accepts RFC 822 syntax in MAIL FROM and RCPT TO addresses.

🦋 `strict_smtputf8` (default: `no`)

enables stricter enforcement of the SMTPUTF8 protocol. the Postfix SMTP server accepts UTF8 sender or recipient addresses only when the client requests an SMTPUTF8 mail transaction.

this feature is available in Postfix 3.0 and later.

💅 `sun_mailtool_compatibility` (default: `no`)

obsolete SUN mailtool compatibility feature. instead, use "mailbox_delivery_lock = dotlock". it's giving legacy, bestie, let it go. 🫶

⭐ `swap_bangpath` (default: `yes`)

enables the rewriting of "site!user" into "user@site". this is necessary if your machine is connected to UUCP networks. it is enabled by default.

Note: with Postfix version 2.2, message header address rewriting happens only when one of the following conditions is true: - the message is received with the Postfix sendmail(1) command, - the message is received from a network client that matches $local_header_rewrite_clients, - the message is received from the network, and the remote_header_rewrite_domain parameter specifies a non-empty value.

to get the behavior from before Postfix version 2.2, specify "local_header_rewrite_clients = static:all". time travel, basically. ✨

Example:

swap_bangpath = no

🧚 `syslog_facility` (default: `mail`)

the syslog facility of Postfix logging. specify a facility as defined in syslog.conf(5). the default facility is "mail".

Warning: a non-default syslog_facility setting takes effect only after a Postfix process has completed initialization. errors during process initialization will be logged with the default facility. examples are errors while parsing the command line arguments, and errors while accessing the Postfix main.cf configuration file. so like, the fancy facility doesn't kick in until it's fully awake. 😴

💜 `syslog_name` (default: see `postconf -d` output)

a prefix that gets prepended to the process name in syslog records, so that, for example, "smtpd" becomes "prefix/smtpd". cute little name tag 🏷️

Warning: a non-default syslog_name setting takes effect only after a Postfix process has completed initialization. errors during process initialization will be logged with the default name. examples are errors while parsing the command line arguments, and errors while accessing the Postfix main.cf configuration file.

🌈 `tcp_windowsize` (default: `0`)

an optional workaround for routers that break TCP window scaling. 😤 specify a value > 0 and < 65536 to enable this feature. with Postfix TCP servers (smtpd(8), qmqpd(8)), this feature is implemented by the Postfix master(8) daemon.

to change this parameter without stopping Postfix, you need to first terminate all Postfix TCP servers:

# postconf -e master_service_disable=inet
# postfix reload

this immediately terminates all processes that accept network connections. next, you enable Postfix TCP servers with the updated tcp_windowsize setting:

# postconf -e tcp_windowsize=65535 master_service_disable=
# postfix reload

if you skip these steps with a running Postfix system, then the tcp_windowsize change will work only for Postfix TCP clients (smtp(8), lmtp(8)). so like, half-working. the audacity. 💀

this feature is available in Postfix 2.6 and later.

🍓 `tls_append_default_CA` (default: `no`)

appends the system-supplied default Certification Authority certificates to the ones specified with *_tls_CApath or *_tls_CAfile. the default is "no"; this prevents Postfix from trusting third-party certificates and giving them relay permission with permit_tls_all_clientcerts. 🚫 trusting strangers is a no from me.

this feature is available in Postfix 2.4.15, 2.5.11, 2.6.8, 2.7.2 and later versions. specify "tls_append_default_CA = yes" for backwards compatibility, to avoid breaking certificate verification with sites that don't use permit_tls_all_clientcerts. 🌟

tls_config_file (default: default) — okay bestie, this one is a lil config file where you can drop baseline OpenSSL settings. 🌸 OpenSSL loads any SSL settings it finds in that file for the application name you picked (see tls_config_name), or else it falls back to the built-in application name openssl_conf when you didn't name one, or when there's no matching configuration section for it.

Now for the tea ☕: with OpenSSL releases 1.1.1 and 1.1.1a, applications (and yes, that includes Postfix) can neither specify an alternative configuration file nor skip loading the default configuration file. Sorry bestie, that's just how those releases woke up.

With OpenSSL 1.1.1b or later, this parameter may be set to one of:

default (default) — load the system-wide openssl.cnf configuration file. 🎀
none (recommended, OpenSSL 1.1.1b or later only) — this setting disables loading of the system-wide openssl.cnf file. Slay, honestly.
/absolute-path (OpenSSL 1.1.1b or later only) — load the configuration file specified by /absolute-path. With this setting it is an error for the file to not contain any settings for the selected tls_config_name. There is no fallback to the default openssl_conf name. 😭

Failures in processing of the built-in default configuration file are silently ignored. Any errors in loading a non-default configuration file are detected by Postfix, and cause TLS support to be disabled. 💀

The OpenSSL configuration file format is not documented here, beyond giving two examples. That's the whole vibe check, fr.

Example: Default settings for all applications. ✨

# The name 'openssl_conf' is the default application name
# The section name to the right of the '=' sign is arbitrary,
# any name will do, so long as it refers to the desired section.
#
# The name 'system_default' selects the settings applied internally
# by the SSL library as part of SSL object creation.  Applications
# can then apply any additional settings of their choice.
#
# In this example, TLS versions prior to 1.2 are disabled by default.
#
openssl_conf = system_wide_settings
[system_wide_settings]
ssl_conf = ssl_library_settings
[ssl_library_settings]
system_default = initial_ssl_settings
[initial_ssl_settings]
MinProtocol = TLSv1.2

Example: Custom settings for an application named postfix. 💅

# The mapping from an application name to the corresponding configuration
# section must appear near the top of the file, (in what is sometimes called
# the "default section") prior to the start of any explicitly named
# "[sections]".  The named sections can appear in any order and don't nest.
#
postfix = postfix_settings
[postfix_settings]
ssl_conf = postfix_ssl_settings
[postfix_ssl_settings]
system_default = baseline_postfix_settings
[baseline_postfix_settings]
MinProtocol = TLSv1

Example: Custom OpenSSL group settings. 🦋

main.cf:

tls_config_file = ${config_directory}/openssl.cnf
tls_config_name = postfix
# Clear Postfix curve/group settings to let custom OpenSSL
# configuration settings take effect.  For most users, the
# default Postfix settings are strongly recommended.
tls_eecdh_auto_curves =
tls_ffdhe_auto_groups =

openssl.cnf:

postfix = postfix_settings

[postfix_settings]
ssl_conf = postfix_ssl_settings

[postfix_ssl_settings]
system_default = baseline_postfix_settings

[baseline_postfix_settings]
# New OpenSSL 3.5 syntax, for older releases consider
# the Postfix default:
#
# Groups = X25519:X448:prime256v1:secp384r1:secp521r1:ffdhe2048:ffdhe3072
#
Groups = ?X25519MLKEM768 / ?*X25519:?secp256r1 / ?X448:?secp384r1:?secp521r1 / ?ffdhe2048:?ffdhe3072

Caution, bestie, listen up 👑: it is typically best to just use the compiled-in default OpenSSL group settings, by setting tls_config_file = none. Overly strict system-wide TLS settings will conflict with Postfix's opportunistic TLS, where being less restrictive is better than downgrading to cleartext SMTP. And we do not want cleartext SMTP, no cap. 🌈

This feature is available in Postfix >= 3.9, 3.8.1, 3.7.6, 3.6.10, and 3.5.20. ⭐

tls_config_name (default: empty) — this is the application name Postfix hands over to the OpenSSL library initialization functions. The name is used to select the desired configuration "section" in the OpenSSL configuration file you specified via the tls_config_file parameter. 🎀 When it's empty, or when the selected name is not present in the configuration file, the default application name (openssl_conf) is used as a fallback. Iconic fallback behaviour, honestly.

This feature is available in Postfix >= 3.9. ✨

tls_daemon_random_bytes (default: 32) — the number of pseudo-random bytes that an smtp(8) or smtpd(8) process requests from the tlsmgr(8) server in order to seed its internal pseudo random number generator (PRNG). 🌸 The default of 32 bytes (equivalent to 256 bits) is sufficient to generate a 128bit (or 168bit) session key. Look at her go, mathematically sound AND cute. 🧚

This feature is available in Postfix 2.2 and later. 💜

tls_dane_digest_agility (default: on) — configures RFC7671 DANE TLSA digest algorithm agility. 🦋 Do not change this setting from its default value. I'm serious, bestie, hands off. 🙈

See Section 8 of RFC7671 for correct key rotation procedures. iykyk.

This feature is available in Postfix 2.11 through 3.1. Postfix 3.2 and later ignore this configuration parameter and behave as though it were set to "on". 💅

tls_dane_digests (default: sha512 sha256) — DANE TLSA (RFC 6698, RFC 7671, RFC 7672) resource-record "matching type" digest algorithms, in descending preference order. 🔥 All the specified algorithms must be supported by the underlying OpenSSL library, otherwise the Postfix SMTP client will not support DANE TLSA security. So, uh, no cap on that requirement.

Specify a list of digest names separated by commas and/or whitespace. Each digest name may be followed by an optional "=<number>" suffix. For example, "sha512" may instead be specified as "sha512=2" and "sha256" may instead be specified as "sha256=1". The optional number must match the IANA assigned TLSA matching type number the algorithm in question — that's over at https://www.iana.org/assignments/dane-parameters/dane-parameters.xhtml#matching-types if you wanna peek. 🎀 Postfix will check this constraint for the algorithms it knows about. Additional matching type algorithms registered with IANA can be added with explicit numbers, provided they are supported by OpenSSL. Go off, extensibility. ✨

Invalid list elements are logged with a warning and disable DANE support. TLSA RRs that specify digests not included in the list are ignored with a warning. 😭

Note: it is unwise to omit sha256 from the digest list. This digest algorithm is the only mandatory-to-implement digest algorithm in RFC 6698, and many servers are expected to publish TLSA records with just sha256 digests. Unless one of the standard digests is seriously compromised and servers have had ample time to update their TLSA records, you should not omit any standard digests — just arrange them in order from strongest to weakest. That's the whole assignment. 📝💖

This feature is available in Postfix 2.11 and later. ⭐

tls_dane_trust_anchor_digest_enable (default: yes) — enables support for RFC 6698 (DANE TLSA) DNS records that contain digests of trust-anchors with certificate usage "2". 🛡️ Do not change this setting from its default value. Again, bestie, we do not touch. 🙈

This feature is available in Postfix 2.11 through 3.1. It has been withdrawn in Postfix 3.2, as trust-anchor TLSA records are now widely used and have proved sufficiently reliable. 💅 Postfix 3.2 and later ignore this configuration parameter and behaves as though it were set to "yes". She grew up and moved out, periodt. 🌈

tls_disable_workarounds (default: see postconf -d output)

Okay bestie, this one is a list or a bit-mask — and it's literally the list of OpenSSL bug work-arounds you want to turn OFF. 💅

So, context: the OpenSSL toolkit ships with a whole lil collection of work-arounds for buggy SSL/TLS implementations. Applications — like Postfix — that wanna maximize interoperability go ahead and ask the OpenSSL library to enable the full set of recommended work-arounds. 🫶

But every so often, plot twist: it gets discovered that a work-around creates a security issue and should no longer be used. If upgrading OpenSSL to a fixed version is not an option, or an upgrade is not available in a timely manner, or you're in closed environments where no buggy clients or servers exist, it may be appropriate to disable some or all of the OpenSSL interoperability work-arounds. And this parameter is the one that says which bug work-arounds to disable. ✨

If the value of the parameter is a hexadecimal long integer starting with "0x", the bug work-arounds corresponding to the bits specified in its value are removed from the SSL_OP_ALL work-around bit-mask (see openssl/ssl.h and SSL_CTX_set_options(3)). You can specify more bits than are present in SSL_OP_ALL — excess bits are totally ignored, no cap. Specifying 0xFFFFFFFF disables all bug-workarounds on a 32-bit system. This should also be sufficient on 64-bit systems, until OpenSSL abandons support for 32-bit systems and starts using the high 32 bits of a 64-bit bug-workaround mask. 💀
Otherwise, the parameter is a white-space or comma separated list of specific named bug work-arounds chosen from the list below. Heads up though: it is possible that your OpenSSL version includes new bug work-arounds added after your Postfix source code was last updated — in that case you can only disable one of these via the hexadecimal syntax above. 🙈

The named ones, bestie, alphabetically:

CRYPTOPRO_TLSEXT_BUG — New with GOST support in OpenSSL 1.0.0.
DONT_INSERT_EMPTY_FRAGMENTS — See SSL_CTX_set_options(3)
LEGACY_SERVER_CONNECT — See SSL_CTX_set_options(3)
MICROSOFT_BIG_SSLV3_BUFFER — See SSL_CTX_set_options(3)
MICROSOFT_SESS_ID_BUG — See SSL_CTX_set_options(3)
MSIE_SSLV2_RSA_PADDING — also aliased as CVE-2005-2969. Postfix 2.8 disables this work-around by default with OpenSSL versions that may predate the fix. Fixed in OpenSSL 0.9.7h and OpenSSL 0.9.8a.
NETSCAPE_CHALLENGE_BUG — See SSL_CTX_set_options(3)
NETSCAPE_REUSE_CIPHER_CHANGE_BUG — also aliased as CVE-2010-4180. Postfix 2.8 disables this work-around by default with OpenSSL versions that may predate the fix. Fixed in OpenSSL 0.9.8q and OpenSSL 1.0.0c.
SSLEAY_080_CLIENT_DH_BUG — See SSL_CTX_set_options(3)
SSLREF2_REUSE_CERT_TYPE_BUG — See SSL_CTX_set_options(3)
TLS_BLOCK_PADDING_BUG — See SSL_CTX_set_options(3)
TLS_D5_BUG — See SSL_CTX_set_options(3)
TLS_ROLLBACK_BUG — See SSL_CTX_set_options(3). This is disabled in OpenSSL 0.9.7 and later. Nobody should still be using 0.9.6! 😭
TLSEXT_PADDING — Postfix >= 3.4. See SSL_CTX_set_options(3).

This feature is available in Postfix 2.8 and later. 🎀

tls_eecdh_auto_curves (default: see postconf -d output)

This is the prioritized list of elliptic curves that should be enabled in the Postfix SMTP client and server. 🌸 The selected curves should be implemented by OpenSSL and be standardized for use in the TLS "supported groups" extension (RFC8422, RFC8446 and RFC8447). Be sure to include at least "x25519" and "prime256v1" (the OpenSSL name for "secp256r1", a.k.a. "P-256"). The default list is suitable for most users, fr. 👑

On the client side, the first curve listed will be used to construct the client's initial TLS 1.3 "keyshare". If this is not supported by the server, the TLS handshake may require an additional round-trip after the server issues a HelloRetryRequest (HRR) indicating a suitable mutually supported curve. 🦋

Postfix skips curve names that are unknown to OpenSSL, or that are known but not yet implemented. This makes it possible to "anticipate" support for curves that should be used once they become available, or to deploy the same setting on a server "farm" where not all servers support the same curves. Lowkey genius behavior tbh. ✨

As of Postfix 3.10, when compiled with OpenSSL 3.0 or later, the "curve" names can be more general key encapsulation mechanisms (KEMs), and/or may be loaded from an external "provider" (via a suitable tls_config_file). 👑

See also the "tls_ffdhe_auto_groups" parameter, which supports customizing the list of FFDHE groups enabled with TLS 1.3. That setting is introduced with Postfix 3.8, when built against OpenSSL 3.0 or later. 🫶

Post-quantum cryptography support: OpenSSL 3.5 introduces new configuration syntax that Postfix will not attempt to emulate. That said, when compiled against OpenSSL 3.5 or later, the Postfix default setting is a minor adjustment of the OpenSSL compiled-in default setting — it just delays generation of the hybrid post-quantum X25519MLKEM768 key-share until it is explicitly requested by the server. This avoids interoperability issues with some SMTP servers that are unable to handle the resulting large TLS Client Hello. 💀

If, despite the strongly recommended defaults, you need fine-grained control over the supported groups, with Postfix 3.6.17, 3.7.13, 3.8.8, 3.9.2, and later, set both tls_eecdh_auto_curves and if available tls_ffdhe_auto_groups to the empty value, to enable algorithm selection through OpenSSL configuration. See tls_config_file for a configuration example. 🎀

This feature is available in Postfix 3.2 and later, when it is compiled and linked with OpenSSL 1.0.2 or later on platforms where EC algorithms have not been disabled by the vendor.

tls_eecdh_strong_curve (default: prime256v1)

The elliptic curve used by the Postfix SMTP server for sensibly strong ephemeral ECDH key exchange. 🌈 This curve is used by the Postfix SMTP server when "smtpd_tls_eecdh_grade = strong". And what does "sensibly strong" mean, bestie? It means approximately 128-bit security based on best known attacks. 💅

The selected curve must be implemented by OpenSSL (as reported by ecparam(1) with the "-list_curves" option) and be one of the curves listed in Section 5.1.1 of RFC 8422. You should not generally change this setting. Remote SMTP client implementations must support this curve for EECDH key exchange to take place. It is unwise to choose only "bleeding-edge" curves supported by only a small subset of clients. 🙈

This feature is not used as of Postfix 3.6. Do not specify. 🚫

The default "strong" curve is rated in NSA Suite B for information classified up to SECRET.

Note: elliptic curve names are poorly standardized; different standards groups are assigning different names to the same underlying curves. The curve with the X9.62 name "prime256v1" is also known under the SECG name "secp256r1", but OpenSSL does not recognize the latter name. 😭 (not OpenSSL being picky about naming)

If you want to take maximal advantage of ciphers that offer forward secrecy see the Getting started section of FORWARD_SECRECY_README. The full document conveniently presents all information about Postfix "perfect" forward secrecy support in one place: what forward secrecy is, how to tweak settings, and what you can expect to see when Postfix uses ciphers with forward secrecy. 📖✨

This feature is available in Postfix 2.6 and later, when it is compiled and linked with OpenSSL 1.0.0 or later on platforms where EC algorithms have not been disabled by the vendor.

tls_eecdh_ultra_curve (default: secp384r1)

The elliptic curve used by the Postfix SMTP server for maximally strong ephemeral ECDH key exchange. 👑 This curve is used by the Postfix SMTP server when "smtpd_tls_eecdh_grade = ultra". And "maximally strong" = approximately 192-bit security based on best known attacks.

But listen — this additional strength comes at a significant computational cost, and most users should instead set "smtpd_tls_eecdh_grade = strong". 💀 The selected curve must be implemented by OpenSSL (as reported by ecparam(1) with the "-list_curves" option) and be one of the curves listed in Section 5.1.1 of RFC 8422. You should not generally change this setting. Remote SMTP client implementations must support this curve for EECDH key exchange to take place. It is unwise to choose only "bleeding-edge" curves supported by only a small subset of clients. 🙈

This feature is not used as of Postfix 3.6. Do not specify. 🚫

This default "ultra" curve is rated in NSA Suite B for information classified up to TOP SECRET. (yes ma'am, top secret energy only 😌)

This feature is available in Postfix 2.6 and later, when it is compiled and linked with OpenSSL 1.0.0 or later on platforms where EC algorithms have not been disabled by the vendor.

tls_export_cipherlist (default: see postconf -d output)

The OpenSSL cipherlist for "export" or higher grade ciphers. 🌸

Ignored as of Postfix 3.8. 🚫

In earlier Postfix releases this defined the meaning of the "export" setting in smtpd_tls_ciphers, smtpd_tls_mandatory_ciphers, smtp_tls_ciphers, smtp_tls_mandatory_ciphers, lmtp_tls_ciphers, and lmtp_tls_mandatory_ciphers. You are strongly encouraged not to change this setting. 💅

This feature is available in Postfix 2.3 and later.

tls_fast_shutdown_enable (default: yes)

A workaround for implementations that hang Postfix while shutting down a TLS session, until Postfix times out. 😭 With this enabled, Postfix will not wait for the remote TLS peer to respond to a TLS 'close' notification. This behavior is recommended for TLSv1.0 and later. ✨🫶

tls_ffdhe_auto_groups (default: see postconf -d output) — this is the prioritized list of finite-field Diffie-Hellman ephemeral (FFDHE) key exchange groups that the Postfix SMTP client and server are down with. 💪

So here's the tea: OpenSSL 3.0 adds support for FFDHE key agreement in TLS 1.3. In OpenSSL 1.1.1, TLS 1.3 was only supported with elliptic-curve based key agreement. The tls_ffdhe_auto_groups parameter makes it possible to configure the list of FFDHE groups that the Postfix client or server will enable in OpenSSL 3.0 and up. This parameter has no effect when Postfix is built against earlier OpenSSL versions. 🚫

The default list of FFDHE groups that Postfix enables in OpenSSL 3.0 and up includes just the 2048 and 3072-bit groups. Stronger FFDHE groups perform poorly and EC groups are a much better choice for the same security level, so like… why bother. 😭 Postfix ignores group names that are unknown to OpenSSL, or that are known but not yet implemented. The FFDHE groups are largely a backup, in case some peer does not support EC key exchange, or EC key exchange needs to be disabled for some pressing reason.

Setting this parameter empty disables FFDHE support in TLS 1.3, unless FFDHE groups are included in the tls_eecdh_auto_curves setting, perhaps indirectly, as with the DEFAULT keyword available with OpenSSL 3.5 or later. In that case, prefixing each group name with a - has the effect of removing it from the list. Whether FFDHE key agreement is enabled in TLS 1.2 and earlier depends on whether any of the kDHE ciphers are included in the cipherlist. 👑

Conversely, setting tls_eecdh_auto_curves empty disables TLS 1.3 EC key agreement in OpenSSL 3.0 and later. If both are set empty, Postfix will fall back to OpenSSL preferences as described in the documentation of tls_eecdh_auto_curves.

The default list includes ffdhe2048 and ffdhe3072. While it should not be necessary in most cases, you can add ffdhe4096 to the list if you run into an exotic server that does not support ECDHE and insists on much stronger than sensible DHE parameters. 🙈

This feature is available in Postfix 3.8 and later, when it is compiled and linked with OpenSSL 3.0 or later. ✨

tls_high_cipherlist (default: see postconf -d output) — the OpenSSL cipherlist for "high" grade ciphers. This defines the meaning of the "high" setting in smtpd_tls_ciphers, smtpd_tls_mandatory_ciphers, smtp_tls_ciphers, smtp_tls_mandatory_ciphers, lmtp_tls_ciphers, and lmtp_tls_mandatory_ciphers. You are strongly encouraged not to change this setting. fr fr, leave it alone bestie 🫶

This feature is available in Postfix 2.3 and later.

tls_legacy_public_key_fingerprints (default: no) — a temporary migration aid for sites that use certificate public-key fingerprints with Postfix 2.9.0..2.9.5, which use an incorrect algorithm. This parameter has no effect on the certificate fingerprint support that is available since Postfix 2.2. 🙅

Specify tls_legacy_public_key_fingerprints = yes temporarily, pending a migration from configuration files with incorrect Postfix 2.9.0..2.9.5 certificate public-key finger prints, to the correct fingerprints used by Postfix 2.9.6 and later. To compute the correct certificate public-key fingerprints, see TLS_README. 📖

This feature is available in Postfix 2.9.6 through 3.10. This parameter has had no effect since Postfix 3.9.0, and has been removed as of postfix 3.11.0. 💀

tls_low_cipherlist (default: see postconf -d output) — the OpenSSL cipherlist for "low" or higher grade ciphers. Ignored as of Postfix 3.8. In earlier Postfix releases this defined the meaning of the "low" setting in smtpd_tls_ciphers, smtpd_tls_mandatory_ciphers, smtp_tls_ciphers, smtp_tls_mandatory_ciphers, lmtp_tls_ciphers, and lmtp_tls_mandatory_ciphers. You are strongly encouraged not to change this setting. 🎀

This feature is available in Postfix 2.3 and later.

tls_medium_cipherlist (default: see postconf -d output) — the OpenSSL cipherlist for "medium" or higher grade ciphers. This defines the meaning of the "medium" setting in smtpd_tls_ciphers, smtpd_tls_mandatory_ciphers, smtp_tls_ciphers, smtp_tls_mandatory_ciphers, lmtp_tls_ciphers, and lmtp_tls_mandatory_ciphers. This is the default cipherlist for mandatory TLS encryption in the TLS client (with anonymous ciphers disabled when verifying server certificates). This is the default cipherlist for opportunistic TLS with Postfix releases after the middle of 2015. You are strongly encouraged not to change this setting. 🌟

This feature is available in Postfix 2.3 and later.

tls_null_cipherlist (default: eNULL:!aNULL) — the OpenSSL cipherlist for "NULL" grade ciphers that provide authentication without encryption. This defines the meaning of the "null" setting in smtpd_tls_mandatory_ciphers, smtp_tls_mandatory_ciphers and lmtp_tls_mandatory_ciphers. You are strongly encouraged not to change this setting. 💅

This feature is available in Postfix 2.3 and later.

tls_preempt_cipherlist (default: no) — with SSLv3 and later, use the Postfix SMTP server's cipher preference order instead of the remote client's cipher preference order. 👑

By default, the OpenSSL server selects the client's most preferred cipher that the server supports. With SSLv3 and later, the server may choose its own most preferred cipher that is supported (offered) by the client. Setting tls_preempt_cipherlist = yes enables server cipher preferences.

While server cipher selection may in some cases lead to a more secure or performant cipher choice, there is some risk of interoperability issues. In the past, some SSL clients have listed lower priority ciphers that they did not implement correctly. If the server chooses a cipher that the client prefers less, it may select a cipher whose client implementation is flawed. Most notably Windows 2003 Microsoft Exchange servers have flawed implementations of DES-CBC3-SHA, which OpenSSL considers stronger than RC4-SHA. Enabling server cipher-suite selection may create interoperability issues with Windows 2003 Microsoft Exchange clients. 😭

This feature is available in Postfix 2.8 and later, in combination with OpenSSL 0.9.7 and later.

tls_random_bytes (default: 32) — the number of bytes that tlsmgr(8) reads from $tls_random_source when (re)seeding the in-memory pseudo random number generator (PRNG) pool. The default of 32 bytes (256 bits) is good enough for 128bit symmetric keys. If using EGD or a device file, a maximum of 255 bytes is read. 🔢

This feature is available in Postfix 2.2 and later.

tls_random_exchange_name (default: see postconf -d output) — name of the pseudo random number generator (PRNG) state file that is maintained by tlsmgr(8). The file is created when it does not exist, and its length is fixed at 1024 bytes. 📁

As of version 2.5, Postfix no longer uses root privileges when opening this file, and the default file location was changed from ${config_directory}/prng_exch to ${data_directory}/prng_exch. As a migration aid, an attempt to open the file under a non-Postfix directory is redirected to the Postfix-owned data_directory, and a warning is logged. ⚠️

This feature is available in Postfix 2.2 and later.

tls_random_prng_update_period (default: 3600s) — the time between attempts by tlsmgr(8) to save the state of the pseudo random number generator (PRNG) to the file specified with $tls_random_exchange_name. ⏰

This feature is available in Postfix 2.2 and later.

tls_random_reseed_period (default: 3600s) — the maximal time between attempts by tlsmgr(8) to re-seed the in-memory pseudo random number generator (PRNG) pool from external sources. The actual time between re-seeding attempts is calculated using the PRNG, and is between 0 and the time specified. 🎲

This feature is available in Postfix 2.2 and later.

tls_random_source (default: see postconf -d output) — the external entropy source for the in-memory tlsmgr(8) pseudo random number generator (PRNG) pool. Be sure to specify a non-blocking source. If this source is not a regular file, the entropy source type must be prepended: egd:/path/to/egd_socket for a source with EGD compatible socket interface, or dev:/path/to/device for a device file. 🌀

Note: on OpenBSD systems specify dev:/dev/arandom when dev:/dev/urandom gives timeout errors.

This feature is available in Postfix 2.2 and later.

tls_required_enable (default: yes) — enable support for the TLS-Required: no message header, defined in RFC 8689. By adding this header to a message, a sender requests no enforcement of TLS policy. This disables TLS policy lookup, and limits the Postfix SMTP client TLS security level to "may", that is, do not verify remote SMTP server certificates, and fall back to plaintext if TLS is unavailable. If a message contains a TLS-Required: no header, then Postfix will add that header to a delivery status notification for that message. 📨

Note: the ESMTP REQUIRETLS option overrides the TLS-Required: no message header.

This feature is available in Postfix >= 3.10. 🌈

💖 `tls_server_sni_maps` 💖

(default: empty)

Okay bestie, this one is the SNI glow-up ✨. It's an optional lookup table (or tables!) that maps the names a remote SMTP client sends in through the TLS Server Name Indication (SNI) extension to the right keys and certificate chains. It lives in the Postfix TLS library, and it applies to both smtpd(8) and the SMTP server mode of tlsproxy(8). So yes, it's doing the most, and it's doing it for both of them 💅.

When this parameter is not empty, the Postfix SMTP server turns on SNI extension processing, and it logs SNI values that are invalid or that don't match an entry in the specified tables. When an entry does match, the SNI name gets logged as part of the connection summary at log levels 1 and higher — so it's giving receipts 📝.

The lookup key is either the verbatim SNI domain name, or an ancestor domain with a leading dot in front of it. And for internationalized domains, the lookup key must be in IDNA 2008 A-label form (that's what the TLS SNI extension requires, no cap).

The syntax of the lookup value is the same as with the smtp_tls_chain_files parameter (go read that one for the extra deets), but here it's scoped to just the TLS connections where the client sends a matching SNI domain name. Targeted. Focused. Main character behavior 💅.

Example:

/etc/postfix/main.cf:
    #
    # The indexed SNI table must be created with "postmap -F"
    #
    indexed = ${default_database_type}:${config_directory}/
    tls_server_sni_maps = ${indexed}sni

/etc/postfix/sni:
    #
    # The example.com domain has both an RSA and ECDSA certificate
    # chain.  The chain files MUST start with the private key,
    # with the certificate chain next, starting with the leaf
    # (server) certificate, and then the issuer certificates.
    #
    example.com /etc/postfix/sni-chains/rsa2048.example.com.pem,
                /etc/postfix/sni-chains/ecdsa-p256.example.com.pem
    #
    # The example.net domain has a wildcard certificate, and two
    # additional DNS names.  So its certificate chain is also used
    # with any subdomain, plus the additional names.
    #
    example.net /etc/postfix/sni-chains/example.net.pem
    .example.net /etc/postfix/sni-chains/example.net.pem
    example.info /etc/postfix/sni-chains/example.net.pem
    example.org /etc/postfix/sni-chains/example.net.pem

Lowkey important: your SNI lookup tables should also have entries for the domains that correspond to the Postfix SMTP server's default certificate(s). Why? Because that makes sure the remote SMTP client's TLS SNI extension gets a positive response when it names one of the Postfix SMTP server's default domains, and it also makes sure the Postfix SMTP server won't log an SNI name mismatch for such a domain. And then — plot twist — the Postfix SMTP server's default certificates only get used when the client sends no SNI at all, or when it sends SNI with a domain the server knows no certificate(s) for. Awkward for them, honestly 🙈.

The mapping from an SNI domain name to a certificate chain is indirect, iykyk. Here's the tea, table by table:

In the input source files for "cdb", "hash", "btree" or other tables that get converted to on-disk indexed files via postmap(1), the value you specify for each key is a list of filenames. When postmap(1) is used with the -F option, the generated table stores, for each lookup key, the base64-encoded contents of the associated files. And when you query tables via postmap -Fq, the table value is decoded from base64, yielding the original file content, plus a new line. Chef's kiss 🎀.
With "regexp", "pcre", "inline", "texthash", "static" and similar tables that are interpreted at run-time, and that don't have a separate source format, the table value is again a list of files, and those get loaded into memory when the table is opened.
With tables whose content is managed outside of Postfix — like LDAP, MySQL, PostgreSQL, socketmap and tcp — the value must be a concatenation of the desired PEM keys and certificate chains, which is then further encoded to yield a single-line base64 string. And heads up: creating such tables and storing them securely (the value includes private key material!) is outside the responsibility of Postfix. That part is on you, bestie 🫶.

⚠️ With "socketmap" and "tcp" the data gets transmitted in the clear, and there's no query access control, so those are generally unsuitable for storing SNI chains. With LDAP and SQL, you should restrict read access and use TLS to protect the sensitive data in transit. Protect the bag, fr fr 🔒.

Typically there's only one private key and its chain of certificates, starting with the "leaf" certificate that corresponds to that key, and then continuing with the appropriate intermediate issuer CA certificates, with each certificate ideally followed by its issuer. And for servers that have keys and certificates for more than one algorithm (e.g. both an RSA key and an ECDSA key, or even RSA, ECDSA and Ed25519), you can use multiple chains concatenated together, with the key always listed before the corresponding certificates. Order matters, no notes ✨.

This feature is available in Postfix 3.4 and later.

🔐 `tls_session_ticket_cipher` 🔐

(default: Postfix >= 3.0: aes-256-cbc, Postfix < 3.0: aes-128-cbc)

This is the algorithm used to encrypt RFC5077 TLS session tickets. The rules are strict, bestie: this algorithm must use CBC mode, must have a 128-bit block size, and must have a key length between 128 and 256 bits. The default is aes-256-cbc. And overriding the default to pick a different algorithm is discouraged. So like… don't 💀.

Setting this parameter empty disables session ticket support in the Postfix SMTP server. Another way to disable session ticket support is via the tls_ssl_options parameter. Two roads, one destination 🌈.

This feature is available in Postfix 3.0 and later.

🎛️ `tls_ssl_options` 🎛️

(default: empty)

A list or bit-mask of OpenSSL options to enable. We love a configurable queen 👑.

The OpenSSL toolkit provides a set of options that applications can enable to tune OpenSSL's behavior. Some of these work around bugs in other implementations and are on by default. You can use the tls_disable_workarounds parameter to selectively disable some or all of those bug work-arounds, which makes OpenSSL more strict — but at the cost of non-interoperability with SSL clients or servers that exhibit the bugs. Strict vs. friendly, pick your fighter.

Other options are off by default, and they typically enable or disable features rather than working around bugs. Those you may turn on (with care!) via the tls_ssl_options parameter. The value is a white-space or comma separated list of named options chosen from the list below. The names are not case-sensitive — lower-case works fine if that's your vibe. The upper case values below match the corresponding macro name in the ssl.h header file with the SSL_OP_ prefix removed. And fair warning: it's possible that your OpenSSL version includes new options added after your Postfix source code was last updated. In that case you can only enable one of those via the hexadecimal syntax below. FOMO but make it cryptography 😭.

You should only enable features via the hexadecimal mask when the need to control the feature is critical (like, dealing with a new vulnerability or a serious interoperability problem). Postfix DOES NOT promise backwards compatible behavior with respect to the mask bits. A feature enabled via the mask in one release may be enabled by other means in a later release, and the mask bit will then be ignored. So the hexadecimal mask is only a temporary measure until a new Postfix or OpenSSL release provides a better solution. It's giving "for now" energy 💅.

If the value of the parameter is a hexadecimal long integer starting with "0x", the options corresponding to the bits specified in its value are enabled (see openssl/ssl.h and SSL_CTX_set_options(3)). You can only enable options not already controlled by other Postfix settings. For example, you cannot disable protocols or enable server cipher preference. And do not attempt to enable all features by specifying 0xFFFFFFFF — this is unlikely to be a good idea, bestie, please 🙈. Some bug work-arounds are also valid here, which lets them be re-enabled if/when they're no longer enabled by default. The supported values include:

ENABLE_MIDDLEBOX_COMPAT — Postfix >= 3.4. See SSL_CTX_set_options(3).
LEGACY_SERVER_CONNECT — See SSL_CTX_set_options(3).
NO_TICKET — Enabled by default when needed in fully-patched Postfix >= 2.7. Not needed at all for Postfix >= 2.11, unless for some reason you do not want to support TLS session resumption. Best not set explicitly. See SSL_CTX_set_options(3).
NO_COMPRESSION — Disable SSL compression even if supported by the OpenSSL library. Compression is CPU-intensive, and compression before encryption does not always improve security.
NO_RENEGOTIATION — Postfix >= 3.4. This can reduce opportunities for a potential CPU exhaustion attack. See SSL_CTX_set_options(3).
NO_SESSION_RESUMPTION_ON_RENEGOTIATION — Postfix >= 3.4. See SSL_CTX_set_options(3).
PRIORITIZE_CHACHA — Postfix >= 3.4. See SSL_CTX_set_options(3).

This feature is available in Postfix 2.11 and later.

🦋 `tls_wildcard_matches_multiple_labels` 🦋

(default: yes)

This one is about matching multiple DNS labels with "*" in wildcard certificates. So slay, wildcards are flexible here 🌸.

Some mail service providers prepend the customer domain name to a base domain for which they have a wildcard TLS certificate. For example, the MX records for example.com hosted by example.net may be:

example.com. IN MX 0 example.com.mx1.example.net.
example.com. IN MX 0 example.com.mx2.example.net.

and the TLS certificate may be for "*.example.net". The "*" then corresponds with multiple labels in the mail server domain name. And while multi-label wildcards are not widely supported, and are not blessed by any standard, there's little to be gained by disallowing their use in this context. So we allow it. Generous queen behavior 👑.

Notes:

In a certificate name, the "*" is special only when it is used as the first label.
While Postfix (2.11 or later) can match "*" with multiple domain name labels, other implementations likely will not. So like… don't count on the group chat to be normal about it 😭.
Earlier Postfix implementations behave as if "tls_wildcard_matches_multiple_labels = no".

This feature is available in Postfix 2.11 and later.

🧚 `tlsmgr_service_name` 🧚

(default: tlsmgr)

The name of the tlsmgr(8) service entry in master.cf. This service maintains TLS session caches and other information in support of TLS. It's the backstage crew keeping the whole TLS show running, and honestly, we're obsessed with it 🎀.

This feature is available in Postfix 2.11 and later.

🌈 `tlsproxy_client_CAfile` 🌈

(default: $smtp_tls_CAfile)

A file containing CA certificates of root CAs trusted to sign either remote TLS server certificates or intermediate CA certificates. See smtp_tls_CAfile for further details. Yes, it's a little referral situation — go read the other one for the full lore 📚.

This feature is available in Postfix 3.4 and later.

`tlsproxy_client_CApath` (default: `$smtp_tls_CApath`)

okay so this one is a directory (not a file, bestie, a whole directory 💖) full of PEM format Certification Authority certificates. The tlsproxy(8) client uses them to verify a remote TLS server certificate. Want the whole breakdown? See smtp_tls_CApath, it's got the lore.

This feature is available in Postfix 3.4 and later. ✨

`tlsproxy_client_cert_file` (default: `$smtp_tls_cert_file`)

A file holding the tlsproxy(8) client RSA certificate, in PEM format. Details live in smtp_tls_cert_file, go read it.

BUT — and this is the part people miss — the preferred way to configure tlsproxy client keys and certificates is via the tlsproxy_client_chain_files parameter. Do that instead, it's giving main character energy. 👑

This feature is available in Postfix 3.4 and later.

`tlsproxy_client_chain_files` (default: `$smtp_tls_chain_files`)

Files with the tlsproxy(8) client keys and certificate chains in PEM format, together, like a little bundle 🎀. See smtp_tls_chain_files for the tea.

This feature is available in Postfix 3.4 and later.

`tlsproxy_client_dcert_file` (default: `$smtp_tls_dcert_file`)

File with the tlsproxy(8) client DSA certificate in PEM format. See smtp_tls_dcert_file for more.

⚠️ DSA is obsolete and should not be used. Not even a little. 💀

This feature is available in Postfix 3.4 and later.

`tlsproxy_client_dkey_file` (default: `$smtp_tls_dkey_file`)

File with the tlsproxy(8) client DSA private key in PEM format. See smtp_tls_dkey_file for further details.

⚠️ Again for the people in the back: DSA is obsolete and should not be used. 🫶

This feature is available in Postfix 3.4 and later.

`tlsproxy_client_eccert_file` (default: `$smtp_tls_eccert_file`)

File with the tlsproxy(8) client ECDSA certificate in PEM format. See smtp_tls_eccert_file for further details. And yep, same deal: the preferred way to configure tlsproxy client keys and certificates is via the tlsproxy_client_chain_files parameter. ✨

This feature is available in Postfix 3.4 and later.

`tlsproxy_client_eckey_file` (default: `$smtp_tls_eckey_file`)

File with the tlsproxy(8) client ECDSA private key in PEM format. See smtp_tls_eckey_file for further details. And once again, bestie: the preferred way to configure tlsproxy client keys and certificates is via the tlsproxy_client_chain_files parameter. 🔑

This feature is available in Postfix 3.4 and later.

`tlsproxy_client_enforce_tls` (default: `$smtp_enforce_tls`)

Enforcement mode, periodt: it requires that SMTP servers use TLS encryption. See smtp_enforce_tls for further details. But like… use tlsproxy_client_security_level instead. 😌

🚫 This feature is deprecated as of Postfix 3.9. Specify tlsproxy_client_security_level instead.

This feature is available in Postfix 3.4 and later.

`tlsproxy_client_fingerprint_digest` (default: `$smtp_tls_fingerprint_digest`)

The message digest algorithm used to construct remote TLS server certificate fingerprints. See smtp_tls_fingerprint_digest for further details. 🧚

This feature is available in Postfix 3.4 and later.

`tlsproxy_client_key_file` (default: `$smtp_tls_key_file`)

File with the tlsproxy(8) client RSA private key in PEM format. See smtp_tls_key_file for further details. And (say it with me 💅) the preferred way to configure tlsproxy client keys and certificates is via the tlsproxy_client_chain_files parameter.

This feature is available in Postfix 3.4 and later.

`tlsproxy_client_level` (default: `$smtp_tls_security_level`)

The default TLS security level for the tlsproxy(8) client. See smtp_tls_security_level for further details.

This feature is available in Postfix 3.4 - 3.6. It was renamed to tlsproxy_client_security_level in Postfix 3.7. Glow-up era. 🌈

`tlsproxy_client_loglevel` (default: `$smtp_tls_loglevel`)

Turns on extra tlsproxy(8) client logging of TLS activity. See smtp_tls_loglevel for further details. Louder = more clues when something's weird, iykyk. 🔥

This feature is available in Postfix 3.4 and later.

`tlsproxy_client_loglevel_parameter` (default: `smtp_tls_loglevel`)

The name of the parameter that provides the tlsproxy_client_loglevel value. That's it, that's the whole vibe. 🌸

This feature is available in Postfix 3.4 and later.

`tlsproxy_client_per_site` (default: `$smtp_tls_per_site`)

Optional lookup tables with the tlsproxy(8) client TLS usage policy, organized by next-hop destination and by remote TLS server hostname. See smtp_tls_per_site for further details.

🚫 This feature is deprecated as of Postfix 3.9. Specify tlsproxy_client_policy_maps instead.

This feature is available in Postfix 3.4 and later.

`tlsproxy_client_policy` (default: `$smtp_tls_policy_maps`)

Optional lookup tables with the tlsproxy(8) client TLS security policy, by next-hop destination. See smtp_tls_policy_maps for further details.

This feature is available in Postfix 3.4 - 3.6. It was renamed to tlsproxy_client_policy_maps in Postfix 3.7.

`tlsproxy_client_policy_maps` (default: `$smtp_tls_policy_maps`)

Optional lookup tables with the tlsproxy(8) client TLS security policy, by next-hop destination. See smtp_tls_policy_maps for further details. 🗺️

This feature is available in Postfix 3.7 and later. It was previously called tlsproxy_client_policy.

`tlsproxy_client_scert_verifydepth` (default: `$smtp_tls_scert_verifydepth`)

The verification depth for remote TLS server certificates. See smtp_tls_scert_verifydepth for further details.

This feature is available in Postfix 3.4 and later.

`tlsproxy_client_security_level` (default: `$smtp_tls_security_level`)

The default TLS security level for the tlsproxy(8) client. See smtp_tls_security_level for further details. 💖

This feature is available in Postfix 3.7 and later. It was previously called tlsproxy_client_level.

`tlsproxy_client_use_tls` (default: `$smtp_use_tls`)

Opportunistic mode: use TLS whenever a remote server announces TLS support. See smtp_use_tls for further details. But bestie… use tlsproxy_client_security_level instead. 🙈

🚫 This feature is deprecated as of Postfix 3.9. Specify tlsproxy_client_security_level instead.

This feature is available in Postfix 3.4 and later.

`tlsproxy_enforce_tls` (default: `$smtpd_enforce_tls`)

Mandatory TLS energy: announce STARTTLS support to remote SMTP clients, and require that clients use TLS encryption. See smtpd_enforce_tls for further details. Use tlsproxy_tls_security_level instead. 😤

🚫 This feature is deprecated as of Postfix 3.9. Specify tlsproxy_tls_security_level instead.

This feature is available in Postfix 2.8 and later.

`tlsproxy_service_name` (default: `tlsproxy`)

The name of the tlsproxy(8) service entry in master.cf. This service performs the plaintext <=> TLS ciphertext conversion — it's literally the translator of the operation. 🌐

This feature is available in Postfix 2.8 and later.

`tlsproxy_tls_CAfile` (default: `$smtpd_tls_CAfile`)

A file containing (PEM format) CA certificates of root CAs that are trusted to sign either remote SMTP client certificates or intermediate CA certificates. See smtpd_tls_CAfile for further details. 🌸

This feature is available in Postfix 2.8 and later.

`tlsproxy_tls_CApath` (default: `$smtpd_tls_CApath`)

A directory containing (PEM format) CA certificates of root CAs trusted to sign either remote SMTP client certificates or intermediate CA certificates. See smtpd_tls_CApath for further details. 📁

This feature is available in Postfix 2.8 and later.

`tlsproxy_tls_always_issue_session_ids` (default: `$smtpd_tls_always_issue_session_ids`)

Forces the tlsproxy(8) server to issue a TLS session id — even when TLS session caching is turned off. See smtpd_tls_always_issue_session_ids for further details. Stubborn in the best way. 💅

This feature is available in Postfix 2.8 and later.

`tlsproxy_tls_ask_ccert` (default: `$smtpd_tls_ask_ccert`)

Asks a remote SMTP client for a client certificate. See smtpd_tls_ask_ccert for further details. 🎀

This feature is available in Postfix 2.8 and later.

`tlsproxy_tls_ccert_verifydepth` (default: `$smtpd_tls_ccert_verifydepth`)

The verification depth for remote SMTP client certificates. A depth of 1 is sufficient if the issuing CA is listed in a local CA file. See smtpd_tls_ccert_verifydepth for further details. ⭐

This feature is available in Postfix 2.8 and later.

`tlsproxy_tls_cert_file` (default: `$smtpd_tls_cert_file`)

File with the tlsproxy(8) server RSA certificate in PEM format. Fun fact: this file may also contain the tlsproxy(8) server private RSA key. See smtpd_tls_cert_file for further details. With Postfix >= 3.4, the preferred way to configure tlsproxy server keys and certificates is via the tlsproxy_tls_chain_files parameter. 👑

This feature is available in Postfix 2.8 and later.

`tlsproxy_tls_chain_files` (default: `$smtpd_tls_chain_files`)

Files with the tlsproxy(8) server keys and certificate chains in PEM format. See smtpd_tls_chain_files for further details. 🎀

This feature is available in Postfix 3.4 and later.

`tlsproxy_tls_ciphers` (default: `$smtpd_tls_ciphers`)

The minimum TLS cipher grade that the tlsproxy(8) server will use with opportunistic TLS encryption. See smtpd_tls_ciphers for further details.

This feature is available in Postfix 2.8 and later.

`tlsproxy_tls_dcert_file` (default: `$smtpd_tls_dcert_file`)

File with the tlsproxy(8) server DSA certificate in PEM format. This file may also contain the tlsproxy(8) server private DSA key. See smtpd_tls_dcert_file for further details.

⚠️ DSA is obsolete and should not be used. Yeah, we're saying it every time. 💀

This feature is available in Postfix 2.8 and later.

`tlsproxy_tls_dh1024_param_file` (default: `$smtpd_tls_dh1024_param_file`)

File with DH parameters that the tlsproxy(8) server should use with non-export EDH ciphers. See smtpd_tls_dh1024_param_file for further details.

🚫 This feature is deprecated as of Postfix 3.9. Do not specify. For real, just don't. 😭

This feature is available in Postfix 2.8 and later.

`tlsproxy_tls_dh512_param_file` (default: `$smtpd_tls_dh512_param_file`)

File with DH parameters that the tlsproxy(8) server should use with export-grade EDH ciphers. See smtpd_tls_dh512_param_file for further details.

Heads up though: the default SMTP server cipher grade is "medium" with Postfix releases after the middle of 2015, and as a result export-grade cipher suites are by default not used. 🫠

And with Postfix >= 3.6, export-grade Diffie-Hellman key exchange is no longer supported, so this parameter is silently ignored. Not a peep. 🤫

This feature is available in Postfix 2.8 and later.

`tlsproxy_tls_dkey_file` (default: `$smtpd_tls_dkey_file`)

File with the tlsproxy(8) server DSA private key in PEM format. This file may be combined with the tlsproxy(8) server DSA certificate file specified with $smtpd_tls_dcert_file. See smtpd_tls_dkey_file for further details.

⚠️ DSA is obsolete and should not be used. Every single time, bestie. 💅

This feature is available in Postfix 2.8 and later.

`tlsproxy_tls_eccert_file` (default: `$smtpd_tls_eccert_file`)

File with the tlsproxy(8) server ECDSA certificate in PEM format. This file may also contain the tlsproxy(8) server private ECDSA key. See smtpd_tls_eccert_file for further details. With Postfix >= 3.4, the preferred way to configure tlsproxy server keys and certificates is via the tlsproxy_tls_chain_files parameter. ✨

This feature is available in Postfix 2.8 and later.

tlsproxy_tls_eckey_file (default: $smtpd_tls_eckey_file) — the file holding the Postfix tlsproxy(8) server's ECDSA private key, in PEM format. ✨

You can lowkey combine this file with the Postfix tlsproxy(8) server ECDSA certificate file that you specify with $smtpd_tls_eccert_file. See smtpd_tls_eckey_file for further details. And bestie, heads up: with Postfix >= 3.4 the preferred way to configure tlsproxy server keys and certificates is via the "tlsproxy_tls_chain_files" parameter. 💅

This feature is available in Postfix 2.8 and later.

tlsproxy_tls_eecdh_grade (default: $smtpd_tls_eecdh_grade) — the Postfix tlsproxy(8) server security grade for ephemeral elliptic-curve Diffie-Hellman (EECDH) key exchange. See smtpd_tls_eecdh_grade for further details.

This feature is not used as of Postfix 3.6. Do not specify. 🚫

This feature is available in Postfix 2.8 and later.

tlsproxy_tls_enable_rpk (default: $smtpd_tls_enable_rpk) — asks remote SMTP clients to send an RFC7250 raw public key instead of an X.509 certificate, whenever you're asking for or requiring client authentication. See $smtpd_tls_enable_rpk for details. 🦋

This feature is available in Postfix 3.9 and later.

tlsproxy_tls_exclude_ciphers (default: $smtpd_tls_exclude_ciphers) — the list of ciphers (or cipher types) to exclude from the tlsproxy(8) server cipher list at all TLS security levels. See smtpd_tls_exclude_ciphers for further details.

This feature is available in Postfix 2.8 and later.

tlsproxy_tls_fingerprint_digest (default: $smtpd_tls_fingerprint_digest) — the message digest algorithm used to construct remote SMTP client-certificate fingerprints. See smtpd_tls_fingerprint_digest for further details. 🔍

This feature is available in Postfix 2.8 and later.

tlsproxy_tls_key_file (default: $smtpd_tls_key_file) — the file with the Postfix tlsproxy(8) server's RSA private key, in PEM format. 🔑

It may be combined with the Postfix tlsproxy(8) server RSA certificate file specified with $smtpd_tls_cert_file. See smtpd_tls_key_file for further details. With Postfix >= 3.4 the preferred way to configure tlsproxy server keys and certificates is via the "tlsproxy_tls_chain_files" parameter.

This feature is available in Postfix 2.8 and later.

tlsproxy_tls_loglevel (default: $smtpd_tls_loglevel) — turns on extra Postfix tlsproxy(8) server logging of TLS activity. Each logging level also includes the info that gets logged at a lower logging level. See smtpd_tls_loglevel for further details. 📝

This feature is available in Postfix 2.8 and later.

tlsproxy_tls_mandatory_ciphers (default: $smtpd_tls_mandatory_ciphers) — the minimum TLS cipher grade the Postfix tlsproxy(8) server will use with mandatory TLS encryption. See smtpd_tls_mandatory_ciphers for further details.

This feature is available in Postfix 2.8 and later.

tlsproxy_tls_mandatory_exclude_ciphers (default: $smtpd_tls_mandatory_exclude_ciphers) — an additional list of ciphers or cipher types to exclude from the tlsproxy(8) server cipher list at mandatory TLS security levels. See smtpd_tls_mandatory_exclude_ciphers for further details. 🌸

This feature is available in Postfix 2.8 and later.

tlsproxy_tls_mandatory_protocols (default: $smtpd_tls_mandatory_protocols) — the SSL/TLS protocols the Postfix tlsproxy(8) server accepts with mandatory TLS encryption. If the list is empty, the server supports all available SSL/TLS protocol versions. See smtpd_tls_mandatory_protocols for further details.

This feature is available in Postfix 2.8 and later.

tlsproxy_tls_protocols (default: $smtpd_tls_protocols) — the list of TLS protocols the Postfix tlsproxy(8) server will exclude or include with opportunistic TLS encryption. See smtpd_tls_protocols for further details. 🌈

This feature is available in Postfix 2.8 and later.

tlsproxy_tls_req_ccert (default: $smtpd_tls_req_ccert) — with mandatory TLS encryption, require a trusted remote SMTP client certificate before letting TLS connections proceed. See smtpd_tls_req_ccert for further details. 🎀

This feature is available in Postfix 2.8 and later.

tlsproxy_tls_security_level (default: $smtpd_tls_security_level) — the SMTP TLS security level for the Postfix tlsproxy(8) server. When you set it to a non-empty value, it overrides the obsolete parameters smtpd_use_tls and smtpd_enforce_tls. See smtpd_tls_security_level for further details.

This feature is available in Postfix 2.8 and later.

tlsproxy_tls_session_cache_timeout (default: $smtpd_tls_session_cache_timeout) — an obsolete expiration time for Postfix tlsproxy(8) server TLS session cache information. Since the cache is shared with smtpd(8) and managed by tlsmgr(8), there's literally only one expiration time for the SMTP server cache shared by all three services, and it's smtpd_tls_session_cache_timeout. 💀

This feature is available in Postfix 2.8-2.10.

tlsproxy_use_tls (default: $smtpd_use_tls) — opportunistic TLS: announce STARTTLS support to remote SMTP clients, but don't require that clients use TLS encryption. See smtpd_use_tls for further details. Use tlsproxy_tls_security_level instead.

This feature is deprecated as of Postfix 3.9. Specify tlsproxy_tls_security_level instead. 🙈

This feature is available in Postfix 2.8 and later.

tlsproxy_watchdog_timeout (default: 10s) — how much time a tlsproxy(8) process may take to process local or remote I/O before a built-in watchdog timer terminates it. ⏰

This is a safety mechanism that keeps tlsproxy(8) from going non-responsive because of a bug in Postfix itself or in system software. And to avoid false alarms plus unnecessary cache corruption, this limit cannot be set under 10s.

This feature is available in Postfix 2.8 and later

trace_service_name (default: trace) — the name of the trace service. This service is implemented by the bounce(8) daemon, and it maintains a record of mail deliveries and produces a mail delivery report when verbose delivery is requested with "sendmail -v". 👑

This feature is available in Postfix 2.1 and later.

transport_delivery_slot_cost (default: $default_delivery_slot_cost) — a transport-specific override for the default_delivery_slot_cost parameter value, where transport is the master.cf name of the message delivery transport.

Note: transport_delivery_slot_cost parameters will not show up in "postconf" command output before Postfix version 2.9. This limitation applies to many parameters whose name is a combination of a master.cf service name and a built-in suffix (in this case: _delivery_slot_cost). 😭

transport_delivery_slot_discount (default: $default_delivery_slot_discount) — a transport-specific override for the default_delivery_slot_discount parameter value, where transport is the master.cf name of the message delivery transport.

Note: transport_delivery_slot_discount parameters will not show up in "postconf" command output before Postfix version 2.9. This limitation applies to many parameters whose name is a combination of a master.cf service name and a built-in suffix (in this case: _delivery_slot_discount).

transport_delivery_slot_loan (default: $default_delivery_slot_loan) — a transport-specific override for the default_delivery_slot_loan parameter value, where transport is the master.cf name of the message delivery transport.

Note: transport_delivery_slot_loan parameters will not show up in "postconf" command output before Postfix version 2.9. This limitation applies to many parameters whose name is a combination of a master.cf service name and a built-in suffix (in this case: _delivery_slot_loan). 💫

transport_destination_concurrency_failed_cohort_limit (default: $default_destination_concurrency_failed_cohort_limit) — a transport-specific override for the default_destination_concurrency_failed_cohort_limit parameter value, where transport is the master.cf name of the message delivery transport.

Note: some transport_destination_concurrency_failed_cohort_limit parameters will not show up in "postconf" command output before Postfix version 2.9. This limitation applies to many parameters whose name is a combination of a master.cf service name and a built-in suffix (in this case: _destination_concurrency_failed_cohort_limit). 🫶

This feature is available in Postfix 2.5 and later.

transport_destination_concurrency_limit (default: $default_destination_concurrency_limit) — a transport-specific override for the default_destination_concurrency_limit parameter value, where transport is the master.cf name of the message delivery transport.

Note: some transport_destination_concurrency_limit parameters will not show up in "postconf" command output before Postfix version 2.9. This limitation applies to many parameters whose name is a combination of a master.cf service name and a built-in suffix (in this case: _destination_concurrency_limit). ⭐

transport_destination_concurrency_negative_feedback (default: $default_destination_concurrency_negative_feedback) — a transport-specific override for the default_destination_concurrency_negative_feedback parameter value, where transport is the master.cf name of the message delivery transport.

Note: some transport_destination_concurrency_negative_feedback parameters will not show up in "postconf" command output before Postfix version 2.9. This limitation applies to many parameters whose name is a combination of a master.cf service name and a built-in suffix (in this case: _destination_concurrency_negative_feedback). 💜

This feature is available in Postfix 2.5 and later.

transport_destination_concurrency_positive_feedback (default: $default_destination_concurrency_positive_feedback) — a transport-specific override for the default_destination_concurrency_positive_feedback parameter value, where transport is the master.cf name of the message delivery transport.

Note: some transport_destination_concurrency_positive_feedback parameters will not show up in "postconf" command output before Postfix version 2.9. This limitation applies to many parameters whose name is a combination of a master.cf service name and a built-in suffix (in this case: _destination_concurrency_positive_feedback). ✨

This feature is available in Postfix 2.5 and later.

transport_destination_rate_delay (default: $default_destination_rate_delay) — a transport-specific override for the default_destination_rate_delay parameter value, where transport is the master.cf name of the message delivery transport.

Note: some transport_destination_rate_delay parameters will not show up in "postconf" command output before Postfix version 2.9. This limitation applies to many parameters whose name is a combination of a master.cf service name and a built-in suffix (in this case: _destination_rate_delay). 🔥

This feature is available in Postfix 2.5 and later.

transport_destination_recipient_limit (default: $default_destination_recipient_limit) — okay so, this is a transport-specific override for the default_destination_recipient_limit parameter value, where transport is the master.cf name of the message delivery transport. 💅

📌 Note: some transport_destination_recipient_limit parameters will not show up in postconf command output before Postfix version 2.9. This limitation applies to many parameters whose name is a combination of a master.cf service name and a built-in suffix (in this case: _destination_recipient_limit). iykyk 🫶

transport_extra_recipient_limit (default: $default_extra_recipient_limit) — a transport-specific override for the default_extra_recipient_limit parameter value, where transport is the master.cf name of the message delivery transport. ✨

📌 Note: transport_extra_recipient_limit parameters will not show up in postconf command output before Postfix version 2.9. This limitation applies to many parameters whose name is a combination of a master.cf service name and a built-in suffix (in this case: _extra_recipient_limit). 🦋

transport_initial_destination_concurrency (default: $initial_destination_concurrency) — a transport-specific override for the initial_destination_concurrency parameter value, where transport is the master.cf name of the message delivery transport. 🌸

📌 Note: some transport_initial_destination_concurrency parameters will not show up in postconf command output before Postfix version 2.9. This limitation applies to many parameters whose name is a combination of a master.cf service name and a built-in suffix (in this case: _initial_destination_concurrency). 💜

This feature is available in Postfix 2.5 and later. ⭐

transport_maps (default: empty) — the main character fr 💖 optional lookup tables with mappings from recipient address to (message delivery transport, next-hop destination). See transport(5) for syntax details, bestie.

This info may override the message delivery transport and/or next-hop destination that are specified with $local_transport, $virtual_transport, $relay_transport, $default_transport, $sender_dependent_relayhost_maps, $relayhost, $sender_dependent_default_transport_maps, or the recipient domain. 👑

Specify zero or more type:table lookup tables, separated by whitespace or comma. Tables get searched in the specified order until a match is found — first come, first served, no cap. 🔍

Pattern matching of domain names is controlled by the presence or absence of transport_maps in the parent_domain_matches_subdomains parameter value. 🧚

🚨 For safety reasons, as of Postfix 2.3 this feature does not allow $number substitutions in regular expression maps. Not a vibe to ignore, fr fr.

Examples:

transport_maps = lmdb:/etc/postfix/transport

Instead of lmdb:, some systems use cdb:, hash:, or dbm:. 🌈

Execute the command postmap /etc/postfix/transport after you change the transport file, to (re)build a default-type indexed file. Execute postmap type:/etc/postfix/transport to specify an explicit type. 💅

The default indexed file type is configured with the default_database_type parameter. To list available explicit types, execute the command postconf -m. 📋

Configuration changes will become visible after a minute or so. Use postfix reload to eliminate the delay. ⚡

transport_minimum_delivery_slots (default: $default_minimum_delivery_slots) — a transport-specific override for the default_minimum_delivery_slots parameter value, where transport is the master.cf name of the message delivery transport. 🎀

📌 Note: transport_minimum_delivery_slots parameters will not show up in postconf command output before Postfix version 2.9. This limitation applies to many parameters whose name is a combination of a master.cf service name and a built-in suffix (in this case: _minimum_delivery_slots). 🙈

transport_recipient_limit (default: $default_recipient_limit) — a transport-specific override for the default_recipient_limit parameter value, where transport is the master.cf name of the message delivery transport. 🌸

📌 Note: some transport_recipient_limit parameters will not show up in postconf command output before Postfix version 2.9. This limitation applies to many parameters whose name is a combination of a master.cf service name and a built-in suffix (in this case: _recipient_limit). 💀

transport_recipient_refill_delay (default: $default_recipient_refill_delay) — a transport-specific override for the default_recipient_refill_delay parameter value, where transport is the master.cf name of the message delivery transport. 🦋

📌 Note: transport_recipient_refill_delay parameters will not show up in postconf command output before Postfix version 2.9. This limitation applies to many parameters whose name is a combination of a master.cf service name and a built-in suffix (in this case: _recipient_refill_delay). 🫶

This feature is available in Postfix 2.4 and later. ⭐

transport_recipient_refill_limit (default: $default_recipient_refill_limit) — a transport-specific override for the default_recipient_refill_limit parameter value, where transport is the master.cf name of the message delivery transport. 🎀

📌 Note: transport_recipient_refill_limit parameters will not show up in postconf command output before Postfix version 2.9. This limitation applies to many parameters whose name is a combination of a master.cf service name and a built-in suffix (in this case: _recipient_refill_limit). 🙈

This feature is available in Postfix 2.4 and later. ⭐

transport_retry_time (default: 60s) — the time between attempts by the Postfix queue manager to contact a malfunctioning message delivery transport. Like, it's giving patience, but with a timer. ⏱️

transport_time_limit (default: $command_time_limit) — a transport-specific override for the command_time_limit parameter value, where transport is the master.cf name of the message delivery transport. 🔥

📌 Note: transport_time_limit parameters will not show up in postconf command output before Postfix version 2.9. This limitation applies to many parameters whose name is a combination of a master.cf service name and a built-in suffix (in this case: _time_limit). 🦋

transport_transport_rate_delay (default: $default_transport_rate_delay) — a transport-specific override for the default_transport_rate_delay parameter value, where the initial transport in the parameter name is the master.cf name of the message delivery transport. (yes, "transport" twice, it's iconic, don't question it 👑)

📌 Note: transport_transport_rate_delay parameters will not show up in postconf command output before Postfix version 2.9. This limitation applies to many parameters whose name is a combination of a master.cf service name and a built-in suffix (in this case: _transport_rate_delay). 💜

trigger_timeout (default: 10s) — the time limit for sending a trigger to a Postfix daemon (for example, the pickup(8) or qmgr(8) daemon). This time limit prevents programs from getting stuck when the mail system is under heavy load. no one wants to be stuck, bestie 😭

undisclosed_recipients_header (default: see postconf -d output) — the message header that the Postfix cleanup(8) server inserts when a message contains no To: or Cc: message header. With Postfix 2.8 and later, the default value is empty. With Postfix 2.4-2.7, specify an empty value to disable this feature. 🕵️♀️

Example:

# Default value before Postfix 2.8.
# Note: the ":" and ";" are both required.
undisclosed_recipients_header = To: undisclosed-recipients:;

(the : and the ; are both required, that's not a suggestion, that's a whole situation) 💅

unknown_address_reject_code (default: 450) — the numerical response code when the Postfix SMTP server rejects a sender or recipient address because its domain is unknown. This is one of the possible replies from the restrictions reject_unknown_sender_domain and reject_unknown_recipient_domain. 🚫

⚠️ Do not change this unless you have a complete understanding of RFC 5321. Like, genuinely. This is not the moment for main character energy.

unknown_address_tempfail_action (default: $reject_tempfail_action) — the Postfix SMTP server's action when reject_unknown_sender_domain or reject_unknown_recipient_domain fail due to a temporary error condition. Specify defer to defer the remote SMTP client request immediately. With the default defer_if_permit action, the Postfix SMTP server continues to look for opportunities to reject mail, and defers the client request only if it would otherwise be accepted. 🎯

This feature is available in Postfix 2.6 and later. ⭐

unknown_client_reject_code (default: 450) — the numerical Postfix SMTP server response code when a client without valid address <=> name mapping is rejected by the reject_unknown_client_hostname restriction. The SMTP server always replies with 450 when the mapping failed due to a temporary error condition. 💀

⚠️ Do not change this unless you have a complete understanding of RFC 5321. Same energy as before, bestie.

unknown_helo_hostname_tempfail_action (default: $reject_tempfail_action) — the Postfix SMTP server's action when reject_unknown_helo_hostname fails due to a temporary error condition. Specify defer to defer the remote SMTP client request immediately. With the default defer_if_permit action, the Postfix SMTP server continues to look for opportunities to reject mail, and defers the client request only if it would otherwise be accepted. ✨

This feature is available in Postfix 2.6 and later. ⭐

unknown_hostname_reject_code (default: 450) — the numerical Postfix SMTP server response code when the hostname specified with the HELO or EHLO command is rejected by the reject_unknown_helo_hostname restriction. 📮

⚠️ Do not change this unless you have a complete understanding of RFC 5321. Periodt. 👑

unknown_local_recipient_reject_code (default: 550)

okay so this is the numerical Postfix SMTP server response code for when a recipient address is local and $local_recipient_maps hands over a list of lookup tables that does not match the recipient 🫶

and like, a recipient address counts as local when its domain matches $mydestination, $proxy_interfaces or $inet_interfaces.

the default is 550 (aka reject the mail, bye ✋) but ngl it is safer to start out with 450 (try again later) so you actually have time to find out whether your local_recipient_maps settings are OK. do this. i am begging 🙏

Example:

unknown_local_recipient_reject_code = 450

This feature is available in Postfix 2.0 and later.

unknown_relay_recipient_reject_code (default: 550)

the numerical Postfix SMTP server reply code for when a recipient address matches $relay_domains, and relay_recipient_maps specifies a list of lookup tables that does not match the recipient address. the vibes are immaculate, the recipient is simply not on the list 💅

This feature is available in Postfix 2.0 and later.

unknown_virtual_alias_reject_code (default: 550)

the Postfix SMTP server reply code for when a recipient address matches $virtual_alias_domains, and $virtual_alias_maps specifies a list of lookup tables that does not match the recipient address. same energy as above, different domain class ✨

This feature is available in Postfix 2.0 and later.

unknown_virtual_mailbox_reject_code (default: 550)

the Postfix SMTP server reply code for when a recipient address matches $virtual_mailbox_domains, and $virtual_mailbox_maps specifies a list of lookup tables that does not match the recipient address. mailbox said no ❌

This feature is available in Postfix 2.0 and later.

unverified_recipient_defer_code (default: 450)

the numerical Postfix SMTP server response when a recipient address probe fails because of a temporary error condition. it's giving "not now, maybe later" 🦋

Unlike elsewhere in Postfix, you can specify 250 in order to accept the address anyway.

Do not change this unless you have a complete understanding of RFC 5321. fr fr, do not just vibe-edit this one 😭

This feature is available in Postfix 2.6 and later.

unverified_recipient_reject_code (default: 450)

the numerical Postfix SMTP server response when a recipient address gets rejected by the reject_unverified_recipient restriction.

Unlike elsewhere in Postfix, you can specify 250 in order to accept the address anyway.

Do not change this unless you have a complete understanding of RFC 5321. no cap 📢

This feature is available in Postfix 2.1 and later.

unverified_recipient_reject_reason (default: empty)

the Postfix SMTP server's reply when it's rejecting mail with reject_unverified_recipient. do not include the numeric SMTP reply code or the enhanced status code, bestie, those are handled for you 💅 By default, the response includes actual address verification details.

Example:

unverified_recipient_reject_reason = Recipient address lookup failed

This feature is available in Postfix 2.6 and later.

unverified_recipient_tempfail_action (default: $reject_tempfail_action)

what the Postfix SMTP server does when reject_unverified_recipient fails due to a temporary error condition. specify "defer" to defer the remote SMTP client request immediately. with the default "defer_if_permit" action, the Postfix SMTP server keeps looking for opportunities to reject mail, and only defers the client request if it would otherwise be accepted. the way that it keeps shopping around for a reason to say no… iconic 🔥

This feature is available in Postfix 2.6 and later.

unverified_sender_defer_code (default: 450)

the numerical Postfix SMTP server response code when a sender address probe fails due to a temporary error condition.

Unlike elsewhere in Postfix, you can specify 250 in order to accept the address anyway.

Do not change this unless you have a complete understanding of RFC 5321. ⭐

This feature is available in Postfix 2.6 and later.

unverified_sender_reject_code (default: 450)

the numerical Postfix SMTP server response code when a recipient address is rejected by the reject_unverified_sender restriction. (yes, it says recipient — that's what it says, we do not edit the sacred text 🎀)

Unlike elsewhere in Postfix, you can specify 250 in order to accept the address anyway.

Do not change this unless you have a complete understanding of RFC 5321. 😤

This feature is available in Postfix 2.1 and later.

unverified_sender_reject_reason (default: empty)

the Postfix SMTP server's reply when rejecting mail with reject_unverified_sender. do not include the numeric SMTP reply code or the enhanced status code — By default, the response includes actual address verification details 🌸

Example:

unverified_sender_reject_reason = Sender address lookup failed

This feature is available in Postfix 2.6 and later.

unverified_sender_tempfail_action (default: $reject_tempfail_action)

the Postfix SMTP server's action when reject_unverified_sender fails due to a temporary error condition. specify "defer" to defer the remote SMTP client request immediately. with the default "defer_if_permit" action, the Postfix SMTP server continues to look for opportunities to reject mail, and defers the client request only if it would otherwise be accepted. same main character energy as the recipient version, just for senders 👑

This feature is available in Postfix 2.6 and later.

use_srv_lookup (default: empty)

enables discovery for the specified service(s) using DNS SRV records. for example, with "use_srv_lookup = submission" and "relayhost = example.com:submission", the Postfix SMTP client will look up DNS SRV records for _submission._tcp.example.com, and will relay email through the hosts and ports that are specified with those records. See RFC 2782 for details of the host selection process. this is the glow-up your relay config has been waiting for ✨

specify zero or more service names separated by comma and/or whitespace. any name in the services(5) database may be specified, though in practice only submission or submissions (formerly called smtp) make sense. yeah, only those two really 💀

when SRV record lookup is enabled with use_srv_lookup, you can enclose a domain name in "[]" to force IP address lookup instead of SRV record lookup.

Example 1: MUA-to-MTA submission using SRV record lookup for the "submission" service for domain "example.com". this uses the default SMTP delivery agent with STARTTLS, and looks up SRV records for "_submission._tcp.example.com".

/etc/postfix/main.cf:
    use_srv_lookup = submission
    relayhost = example.com:submission
    smtp_tls_security_level = may
    ...see SASL_README for sasl configuration...

Example 2: MUA-to-MTA submission using SRV record lookup for the "submissions" service for domain "example.org". this uses a dedicated SMTP delivery agent (smtp-wraptls) with tls_wrappermode turned on, and looks up SRV records for "_submissions._tcp.example.org".

Note: specify the older name "smtps" instead of "submissions" when a provider has DNS SRV records like "_smtps._tcp.example.org" instead of "_submissions._tcp.example.org". 🫶

/etc/postfix/main.cf:
    use_srv_lookup = submissions
    default_transport = smtp-wraptls:example.org:submissions
    ...see SASL_README for sasl configuration...

/etc/postfix/master.cf:
    smtp-wraptls   unix   ...   ...   ...   ...   ...   smtp
        -o { smtp_tls_wrappermode = yes }
        -o { smtp_tls_security_level = encrypt }

Example 3: sender-dependent selection for a combination of MUA-to-MTA submission services. this combines examples 1 and 2 with examples of how to disable SRV and look up IP address records for "smtp-relay.example.net" and "smtp-relay.other.example". again, specify the older name "smtps" instead of "submissions" when a provider has DNS SRV records like "_smtps._tcp.example.org" instead of "_submissions._tcp.example.org".

/etc/postfix/main.cf:
    use_srv_lookup = submission, submissions
    sender_dependent_default_transport_maps = inline:{
        # Destinations that support SRV record lookup.
        { user1@example.com = smtp:example.com:submission }
        { user2@example.org = smtp-wraptls:example.org:submissions }
        # Use [destination] to force IP address lookups.
        { user3@example.net = smtp:[smtp-relay.example.net]:submission }
        { user4@other.example =
              smtp-wraptls:[smtp-relay.other.example]:submissions } }
    ...see SASL_README for sasl configuration...

Example 4: MTA-to-MTA traffic, using SRV record lookup for the SMTP service. this is useful for Postfix tests, and may be useful in environments where ports are dynamically assigned to servers. lowkey niche but highkey handy 🌈

/etc/postfix/main.cf:
    use_srv_lookup = smtp
    # Fall back to MX record lookup when SRV records are unavailable.
    #allow_srv_lookup_fallback = yes
    #ignore_srv_lookup_error = yes

This feature is available in Postfix 3.8 and later.

verp_delimiter_filter (default: -=+)

the characters Postfix accepts as VERP delimiter characters on the Postfix sendmail(1) command line and in SMTP commands. that's it, that's the whole vibe 🎀

This feature is available in Postfix 1.1 and later.

virtual_alias_address_length_limit (default: 1000)

the maximal length of an email address after virtual alias expansion. this stops virtual aliasing loops that increase the address length exponentially — think of it as a ✨safety rail✨ so your aliases don't spiral into infinity and take the whole server with them 😭

This feature is available in Postfix 3.0 and later.

virtual_alias_domains (default: $virtual_alias_maps)

Postfix is the final destination for the specified list of virtual alias domains, that is, domains for which all addresses are aliased to addresses in other local or remote domains. the SMTP server validates recipient addresses with $virtual_alias_maps and rejects non-existent recipients. See also the virtual alias domain class in the ADDRESS_CLASS_README file 📖

This feature is available in Postfix 2.0 and later. The default value is backwards compatible with Postfix version 1.1.

the default value is $virtual_alias_maps so that you can keep all information about virtual alias domains in one place. bestie, if you have many users, it is better to separate information that changes more frequently (virtual address -> local or remote address mapping) from information that changes less frequently (the list of virtual domain names). divide and conquer, it's giving organization 💅

specify a list of host or domain names, "/file/name" or "type:table" patterns, separated by commas and/or whitespace. a "/file/name" pattern is replaced by its contents; a "type:table" lookup table is matched when a table entry matches a host or domain name (the lookup result is ignored). continue long lines by starting the next line with whitespace. specify "!pattern" to exclude a host or domain name from the list. the form "!/file/name" is supported only in Postfix version 2.4 and later. 🦋

See also the VIRTUAL_README and ADDRESS_CLASS_README documents for further information.

Example:

virtual_alias_domains = virtual1.tld virtual2.tld

`virtual_alias_expansion_limit` (default: `1000`) 🎀

The maximal number of addresses that virtual alias expansion produces from each original recipient. Like, one address goes in, and this is the cap on how many can come out the other side. Bestie, there's a limit, okay? 💅

This feature is available in Postfix 2.1 and later.

`virtual_alias_maps` (default: `$virtual_maps`) 💖

Optional lookup tables that are often searched with a full email address (including domain) and that apply to all recipients: local(8), virtual, and remote. And the way this is unlike alias_maps, which are only searched with an email address localpart (no domain) and apply only to local(8) recipients. So yes, they're cousins, not twins. 🙈

The virtual_alias_maps table format and lookups are documented in virtual(5). For an overview of Postfix address manipulations, see the ADDRESS_REWRITING_README document. 📖

This feature is available in Postfix 2.0 and later. The default value is backwards compatible with Postfix version 1.1.

Specify zero or more "type:name" lookup tables, separated by whitespace or comma. Tables will be searched in the specified order until a match is found. Note: these lookups are recursive. 🔁

Examples:

virtual_alias_maps = lmdb:/etc/postfix/virtual

Instead of lmdb:, some systems use cdb:, hash:, or dbm:.

Execute the command postmap /etc/postfix/virtual after you change the virtual file, to (re)build a default-type indexed file. Execute postmap type:/etc/postfix/virtual to specify an explicit type. ✨

The default indexed file type is configured with the default_database_type parameter. To list available explicit types, execute the command postconf -m.

Configuration changes will become visible after a minute or so. Use postfix reload to eliminate the delay. (So impatient, love that for us 🫶)

`virtual_alias_recursion_limit` (default: `1000`) 🌀

The maximal nesting depth of virtual alias expansion. Currently the recursion limit is applied only to the left branch of the expansion graph, so the depth of the tree can in the worst case reach the sum of the expansion and recursion limits. This may change in the future. ⚠️ (yes, it's giving "we'll fix it later", no cap)

This feature is available in Postfix 2.1 and later.

`virtual_delivery_status_filter` (default: `$default_delivery_status_filter`) 🌈

Optional filter for the virtual(8) delivery agent to change the delivery status code or explanatory text of successful or unsuccessful deliveries. See default_delivery_status_filter for details.

This feature is available in Postfix 3.0 and later.

`virtual_destination_concurrency_limit` (default: `$default_destination_concurrency_limit`) 🔥

The maximal number of parallel deliveries to the same destination via the virtual message delivery transport. This limit is enforced by the queue manager. The message delivery transport name is the first field in the entry in the master.cf file.

`virtual_destination_recipient_limit` (default: `$default_destination_recipient_limit`) 🍓

The maximal number of recipients per message for the virtual message delivery transport. This limit is enforced by the queue manager. The message delivery transport name is the first field in the entry in the master.cf file.

Setting this parameter to a value of 1 changes the meaning of virtual_destination_concurrency_limit from concurrency per domain into concurrency per recipient. Main character plot twist tbh. 👑

`virtual_gid_maps` (default: empty) 🎀

Lookup tables with the per-recipient group ID for virtual(8) mailbox delivery.

This parameter is specific to the virtual(8) delivery agent. It does not apply when mail is delivered with a different mail delivery program. 🙅

Specify zero or more "type:name" lookup tables, separated by whitespace or comma. Tables will be searched in the specified order until a match is found.

In a lookup table, specify a left-hand side of "@domain.tld" to match any user in the specified domain that does not have a specific "user@domain.tld" entry.

When a recipient address has an optional address extension (user+foo@domain.tld), the virtual(8) delivery agent looks up the full address first, and when the lookup fails, it looks up the unextended address (user@domain.tld).

Note 1: for security reasons, the virtual(8) delivery agent disallows regular expression substitution of $1 etc. in regular expression lookup tables, because that would open a security hole. 🚨

Note 2: for security reasons, the virtual(8) delivery agent will silently ignore requests to use the proxymap(8) server. Instead it will open the table directly. Before Postfix version 2.2, the virtual(8) delivery agent will terminate with a fatal error. 💀

`virtual_mailbox_base` (default: empty) 🌸

A prefix that the virtual(8) delivery agent prepends to all pathname results from $virtual_mailbox_maps table lookups. This is a safety measure to ensure that an out of control map doesn't litter the file system with mailboxes. While virtual_mailbox_base could be set to "/", this setting isn't recommended. (bestie, don't 😭)

This parameter is specific to the virtual(8) delivery agent. It does not apply when mail is delivered with a different mail delivery program.

Example:

virtual_mailbox_base = /var/mail

`virtual_mailbox_domains` (default: `$virtual_mailbox_maps`) 💜

Postfix is the final destination for the specified list of domains; mail is delivered via the $virtual_transport mail delivery transport. By default this is the Postfix virtual(8) delivery agent. The SMTP server validates recipient addresses with $virtual_mailbox_maps and rejects mail for non-existent recipients. See also the virtual mailbox domain class in the ADDRESS_CLASS_README file. 🦋

This parameter expects the same syntax as the mydestination configuration parameter.

This feature is available in Postfix 2.0 and later. The default value is backwards compatible with Postfix version 1.1.

`virtual_mailbox_limit` (default: `51200000`) 🧚

The maximal size in bytes of an individual virtual(8) mailbox or maildir file, or zero (no limit).

This parameter is specific to the virtual(8) delivery agent. It does not apply when mail is delivered with a different mail delivery program.

`virtual_mailbox_lock` (default: see `postconf -d` output) 🔒

How to lock a UNIX-style virtual(8) mailbox before attempting delivery. For a list of available file locking methods, use the postconf -l command.

This parameter is specific to the virtual(8) delivery agent. It does not apply when mail is delivered with a different mail delivery program.

This setting is ignored with maildir style delivery, because such deliveries are safe without application-level locks. ✨

Note 1: the dotlock method requires that the recipient UID or GID has write access to the parent directory of the recipient's mailbox file.

Note 2: the default setting of this parameter is system dependent.

`virtual_mailbox_maps` (default: empty) 🌟

Optional lookup tables with all valid addresses in the domains that match $virtual_mailbox_domains.

Specify zero or more "type:name" lookup tables, separated by whitespace or comma. Tables will be searched in the specified order until a match is found.

In a lookup table, specify a left-hand side of "@domain.tld" to match any user in the specified domain that does not have a specific "user@domain.tld" entry.

With the default "virtual_mailbox_domains = $virtual_mailbox_maps", lookup tables also need entries with a left-hand side of "domain.tld" to satisfy virtual_mailbox_domain lookups (the right-hand side is required but will not be used). 🙈

The remainder of this text is specific to the virtual(8) delivery agent. It does not apply when mail is delivered with a different mail delivery program.

The virtual(8) delivery agent uses this table to look up the per-recipient mailbox or maildir pathname. If the lookup result ends in a slash ("/"), maildir-style delivery is carried out, otherwise the path is assumed to specify a UNIX-style mailbox file. Note that $virtual_mailbox_base is unconditionally prepended to this path. 💅

Note 1: for security reasons, the virtual(8) delivery agent disallows regular expression substitution of $1 etc. in regular expression lookup tables, because that would open a security hole. 🚨

Note 2: for security reasons, the virtual(8) delivery agent will silently ignore requests to use the proxymap(8) server. Instead it will open the table directly. Before Postfix version 2.2, the virtual(8) delivery agent will terminate with a fatal error. 💀

`virtual_maps` (default: empty) 🎀

Optional lookup tables with a) names of domains for which all addresses are aliased to addresses in other local or remote domains, and b) addresses that are aliased to addresses in other local or remote domains. Available before Postfix version 2.0. With Postfix version 2.0 and later, this is replaced by separate controls: virtual_alias_domains and virtual_alias_maps. (out with the old, in with the slay ✨)

`virtual_minimum_uid` (default: `100`) 👑

The minimum user ID value that the virtual(8) delivery agent accepts as a result from $virtual_uid_maps table lookup. Returned values less than this will be rejected, and the message will be deferred. 😭

This parameter is specific to the virtual(8) delivery agent. It does not apply when mail is delivered with a different mail delivery program.

`virtual_transport` (default: `virtual`) 🦋

The default mail delivery transport and next-hop destination for final delivery to domains listed with $virtual_mailbox_domains. This information can be overruled with the transport(5) table.

This feature is available in Postfix 2.0 and later.

💖 virtual_uid_maps (default: empty)

okay bestie so this one is the lookup table situation for which user ID the virtual(8) delivery agent runs as while it's writing to a recipient's mailbox — like, per-recipient UIDs, every single one, no cap. 🫶

heads up though: this parameter is specific to the virtual(8) delivery agent. It does not apply when mail gets delivered with a different mail delivery program. So if you're not on virtual(8), this is not your moment, periodt. 💅

You specify zero or more type:name lookup tables, separated by whitespace or comma — and the tables get searched in the order you wrote them, stopping the second a match hits. ✨

Now for the table itself: pop a left-hand side of @domain.tld in there to match any user in that domain that doesn't already have its own specific user@domain.tld entry. Catch-all energy, but make it UID. 👑

And when a recipient address has an optional address extension (user+foo@domain.tld), the virtual(8) delivery agent looks up the full address first, and when that lookup fails? it goes for the unextended address (user@domain.tld). Two tries, always in that order. 💫

Note 1: for security reasons, the virtual(8) delivery agent disallows regular expression substitution of $1 etc. in regular expression lookup tables — because that would open a security hole. Not a vibe, not allowed, we're not doing it. 🚫

Note 2: for security reasons, the virtual(8) delivery agent will silently ignore requests to use the proxymap(8) server. Instead it will open the table directly. And before Postfix version 2.2, the virtual(8) delivery agent will terminate with a fatal error. 💀 so like, ancient Postfix said "absolutely not" and just died about it.

✨ SEE ALSO ✨

postconf(1), Postfix configuration parameter maintenance
master(5), Postfix daemon configuration maintenance

🌈 LICENSE 🌈

The Secure Mailer license must be distributed with this software.

👑 AUTHOR(S) 👑

Wietse Venema IBM T.J. Watson Research P.O. Box 704 Yorktown Heights, NY 10598, USA
Wietse Venema Google, Inc. 111 8th Avenue New York, NY 10011, USA
Viktor Dukhovni

and that's a wrap bestie!! 🎀 that was the very last chunk of POSTCONF(5) — you made it all the way to the end and honestly? iconic behaviour, main character energy, you ate. 💖✨ now go look up a table or something, ily, bye 🦋💜

📦 where this page comes from

alpine 3.24: postfix-doc 3.11.7-r0 · IPL-1.0 EPL-2.0
arch rolling: postfix 3.11.7-1 · EPL-2.0 OR IPL-1.0 AND BSD-4-Clause-UC
nixos 26.05: postfix 3.11.7
nixpkgs unstable: postfix 3.11.7
ubuntu stonking: postfix 3.11.7-1ubuntu2
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms

POSTCONF(5)

💖 POSTCONF(5) — postconf 💖

✨ NAME ✨

🎀 SYNOPSIS 🎀

💜 DESCRIPTION 💜

🌈 PARAMETERS 🌈

2bounce_notice_recipient (default: postmaster)

access_map_defer_code (default: 450)

access_map_reject_code (default: 554)

address_verify_cache_cleanup_interval (default: 12h)

address_verify_default_transport (default: $default_transport)

address_verify_local_transport (default: $local_transport)

address_verify_map (default: Postfix >= 3.11: $default_cache_db_type:$data_directory/verify_cache; Postfix < 3.11: btree:$data_directory/verify_cache)

address_verify_negative_cache (default: yes)

address_verify_negative_expire_time (default: 3d)

address_verify_negative_refresh_time (default: 3h)

address_verify_pending_request_limit (default: see postconf -d output)

address_verify_poll_count (default: normal: 3, overload: 1)

address_verify_poll_delay (default: 3s)

address_verify_positive_expire_time (default: 31d)

address_verify_positive_refresh_time (default: 7d)

address_verify_relay_transport (default: $relay_transport)

address_verify_relayhost (default: $relayhost)

address_verify_sender (default: $double_bounce_sender)

address_verify_sender_dependent_default_transport_maps (default: $sender_dependent_default_transport_maps)

address_verify_sender_dependent_relayhost_maps (default: $sender_dependent_relayhost_maps)

address_verify_sender_ttl (default: 0s)

address_verify_service_name (default: verify)

address_verify_transport_maps (default: $transport_maps)

address_verify_virtual_transport (default: $virtual_transport)

alias_database (default: see postconf -d output)

alias_maps (default: see postconf -d output)

allow_mail_to_commands (default: alias, forward)

allow_mail_to_files (default: alias, forward)

allow_min_user (default: no)

allow_percent_hack (default: yes)

allow_srv_lookup_fallback (default: no)

allow_untrusted_routing (default: no)

alternate_config_directories (default: empty)

always_add_missing_headers (default: no)

always_bcc (default: empty)

anvil_rate_time_unit (default: 60s)

anvil_status_update_time (default: 600s)

append_at_myorigin (default: yes)

append_dot_mydomain (default: Postfix >= 3.0: no, Postfix < 3.0: yes)

application_event_drain_time (default: 100s)

authorized_flush_users (default: static:anyone)

authorized_mailq_users (default: static:anyone)

authorized_submit_users (default: static:anyone)

authorized_verp_clients (default: $mynetworks)

backwards_bounce_logfile_compatibility (default: yes)

berkeley_db_create_buffer_size (default: 16777216)

berkeley_db_read_buffer_size (default: 131072)

💖 best_mx_transport (default: empty)

🌼 biff (default: yes)

🔍 body_checks (default: empty)

📏 body_checks_size_limit (default: 51200)

📬 bounce_notice_recipient (default: postmaster)

⏳ bounce_queue_lifetime (default: 5d)

🌈 bounce_service_name (default: bounce)

🎀 bounce_size_limit (default: 50000)

📝 bounce_template_file (default: empty)

💀 broken_sasl_auth_clients (default: no)

👑 canonical_classes (default: envelope_sender, envelope_recipient, header_sender, header_recipient)

🧚 canonical_maps (default: empty)

✨ cleanup_replace_stray_cr_lf (default: yes)

🧼 cleanup_service_name (default: cleanup)

🗂️ command_directory (default: see postconf -d output)

🏠 command_execution_directory (default: empty)

command_expansion_filter (default: see postconf -d output)

command_time_limit (default: 1000s)

compatibility_level (default: 0)

config_directory (default: see postconf -d output)

confirm_delay_cleared (default: no)

connection_cache_protocol_timeout (default: 5s)

connection_cache_service_name (default: scache)

connection_cache_status_update_time (default: 600s)

connection_cache_ttl_limit (default: 2s)

content_filter (default: empty)

cyrus_sasl_config_path (default: empty)

`2bounce_notice_recipient` (default: `postmaster`)

`access_map_defer_code` (default: `450`)

`access_map_reject_code` (default: `554`)

`address_verify_cache_cleanup_interval` (default: `12h`)

`address_verify_default_transport` (default: `$default_transport`)

`address_verify_local_transport` (default: `$local_transport`)

`address_verify_map` (default: Postfix >= 3.11: `$default_cache_db_type:$data_directory/verify_cache`; Postfix < 3.11: `btree:$data_directory/verify_cache`)

`address_verify_negative_cache` (default: `yes`)

`address_verify_negative_expire_time` (default: `3d`)

`address_verify_negative_refresh_time` (default: `3h`)

`address_verify_pending_request_limit` (default: see `postconf -d` output)

`address_verify_poll_count` (default: `normal: 3`, `overload: 1`)

`address_verify_poll_delay` (default: `3s`)

`address_verify_positive_expire_time` (default: 31d)

`address_verify_positive_refresh_time` (default: 7d)

`address_verify_relay_transport` (default: $relay_transport)

`address_verify_relayhost` (default: $relayhost)

`address_verify_sender` (default: $double_bounce_sender)

`address_verify_sender_dependent_default_transport_maps` (default: $sender_dependent_default_transport_maps)

`address_verify_sender_dependent_relayhost_maps` (default: $sender_dependent_relayhost_maps)

`address_verify_sender_ttl` (default: 0s)

`address_verify_service_name` (default: verify)

`address_verify_transport_maps` (default: $transport_maps)

`address_verify_virtual_transport` (default: $virtual_transport)

`alias_database` (default: see `postconf -d` output)

`alias_maps` (default: see `postconf -d` output)

`allow_mail_to_commands` (default: alias, forward)

`allow_mail_to_files` (default: alias, forward)

`allow_min_user` (default: no)

`allow_percent_hack` (default: yes)

`allow_srv_lookup_fallback` (default: no)

`allow_untrusted_routing` (default: no)

`alternate_config_directories` (default: empty)

`always_add_missing_headers` (default: `no`)

`always_bcc` (default: empty)

`anvil_rate_time_unit` (default: `60s`)

`anvil_status_update_time` (default: `600s`)

`append_at_myorigin` (default: `yes`)

`append_dot_mydomain` (default: Postfix >= 3.0: `no`, Postfix < 3.0: `yes`)

`application_event_drain_time` (default: `100s`)

`authorized_flush_users` (default: `static:anyone`)

`authorized_mailq_users` (default: `static:anyone`)

`authorized_submit_users` (default: `static:anyone`)

`authorized_verp_clients` (default: `$mynetworks`)

`backwards_bounce_logfile_compatibility` (default: `yes`)

`berkeley_db_create_buffer_size` (default: `16777216`)

`berkeley_db_read_buffer_size` (default: `131072`)

`command_expansion_filter` (default: see `postconf -d` output)

`command_time_limit` (default: `1000s`)

`compatibility_level` (default: `0`)

`config_directory` (default: see `postconf -d` output)

`confirm_delay_cleared` (default: `no`)

`connection_cache_protocol_timeout` (default: `5s`)

`connection_cache_service_name` (default: `scache`)

`connection_cache_status_update_time` (default: `600s`)

`connection_cache_ttl_limit` (default: `2s`)

`content_filter` (default: empty)

`cyrus_sasl_config_path` (default: empty)

`daemon_directory` (default: see `postconf -d` output)

`daemon_table_open_error_is_fatal` (default: `no`)

`daemon_timeout` (default: `18000s`)

`data_directory` (default: see `postconf -d` output)

`debug_peer_level` (default: `2`)

`debug_peer_list` (default: empty)

`debugger_command` (default: empty)

`default_cache_db_type` (default: see `'postconf -d default_cache_db_type'` output)

`default_database_type` (default: see `postconf -d` output)

`default_destination_concurrency_positive_feedback` (default: 1)

`default_destination_rate_delay` (default: 0s)

`default_destination_recipient_limit` (default: 50)

`default_extra_recipient_limit` (default: 1000)

`default_filter_nexthop` (default: empty)

`default_minimum_delivery_slots` (default: 3)

`default_privs` (default: nobody)

`default_process_limit` (default: 100)

`default_rbl_reply` (default: see `postconf -d` output)

`default_recipient_limit` (default: 20000)

🌸 `default_recipient_refill_delay` (default: `5s`)

🌸 `default_recipient_refill_limit` (default: `100`)

🌸 `default_transport` (default: `smtp`)