1POSTCONF(5) File Formats Manual POSTCONF(5)
2
6 postconf - Postfix configuration parameters
7
9 postconf parameter ...
10 postconf -e "parameter=value" ...
12
14 The Postfix main.cf configuration file specifies parameters that con‐
15 trol the operation of the Postfix mail system. Typically the file con‐
16 tains only a small subset of all parameters; parameters not specified
17 are left at their default values.
18 The general format of the main.cf file is as follows:
20 • Each logical line has the form "parameter = value". Whitespace
22 around the "=" is ignored, as is whitespace at the end of a log‐
23 ical line.
24 • Empty lines and whitespace-only lines are ignored, as are lines
26 whose first non-whitespace character is a `#'.
27 • A logical line starts with non-whitespace text. A line that
29 starts with whitespace continues a logical line.
30 • A parameter value may refer to other parameters.
32 • The expressions "$name" and "${name}" are recursively re‐
34 placed with the value of the named parameter. The parame‐
35 ter name must contain only characters from the set [a-zA-
36 Z0-9_]. An undefined parameter value is replaced with the
37 empty value.
38 • The expressions "${name?value}" and "${name?{value}}" are
40 replaced with "value" when "$name" is non-empty. The pa‐
41 rameter name must contain only characters from the set
42 [a-zA-Z0-9_]. These forms are supported with Postfix ver‐
43 sions >= 2.2 and >= 3.0, respectively.
44 • The expressions "${name:value}" and "${name:{value}}" are
46 replaced with "value" when "$name" is empty. The parame‐
47 ter name must contain only characters from the set [a-zA-
48 Z0-9_]. These forms are supported with Postfix versions
49 >= 2.2 and >= 3.0, respectively.
50 • The expression "${name?{value1}:{value2}}" is replaced
52 with "value1" when "$name" is non-empty, and with
53 "value2" when "$name" is empty. The "{}" is required for
54 "value1", optional for "value2". The parameter name must
55 contain only characters from the set [a-zA-Z0-9_]. This
56 form is supported with Postfix versions >= 3.0.
57 • The first item inside "${...}" may be a relational ex‐
59 pression of the form: "{value3} == {value4}". Besides the
60 "==" (equality) operator Postfix supports "!=" (inequal‐
61 ity), "<", "<=", ">=", and ">". The comparison is numeri‐
62 cal when both operands are all digits, otherwise the com‐
63 parison is lexicographical. These forms are supported
64 with Postfix versions >= 3.0.
65 • Each "value" is subject to recursive named parameter and
67 relational expression evaluation, except where noted.
68 • Whitespace before or after each "{value}" is ignored.
70 • Specify "$$" to produce a single "$" character.
72 • The legacy form "$(...)" is equivalent to the preferred
74 form "${...}".
75 • When the same parameter is defined multiple times, only the last
77 instance is remembered.
78 • Otherwise, the order of main.cf parameter definitions does not
80 matter.
81 The remainder of this document is a description of all Postfix configu‐
83 ration parameters. Default values are shown after the parameter name in
84 parentheses, and can be looked up with the "postconf -d" command.
85 Note: this is not an invitation to make changes to Postfix configura‐
87 tion parameters. Unnecessary changes can impair the operation of the
88 mail system.
89
91 The recipient of undeliverable mail that cannot be returned to the
92 sender. This feature is enabled with the notify_classes parameter.
93
95 The numerical Postfix SMTP server response code for an access(5) map
96 "defer" action, including "defer_if_permit" or "defer_if_reject". Prior
97 to Postfix 2.6, the response is hard-coded as "450".
98 Do not change this unless you have a complete understanding of RFC
100 5321.
101 This feature is available in Postfix 2.6 and later.
103
105 The numerical Postfix SMTP server response code for an access(5) map
106 "reject" action.
107 Do not change this unless you have a complete understanding of RFC
109 5321.
110
112 The amount of time between verify(8) address verification database
113 cleanup runs. This feature requires that the database supports the
114 "delete" and "sequence" operators. Specify a zero interval to disable
115 database cleanup.
116 After each database cleanup run, the verify(8) daemon logs the number
118 of entries that were retained and dropped. A cleanup run is logged as
119 "partial" when the daemon terminates early after "postfix reload",
120 "postfix stop", or no requests for $max_idle seconds.
121 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
123 This feature is available in Postfix 2.7.
125
127 Overrides the default_transport parameter setting for address verifica‐
128 tion probes.
129 This feature is available in Postfix 2.1 and later.
131
133 Overrides the local_transport parameter setting for address verifica‐
134 tion probes.
135 This feature is available in Postfix 2.1 and later.
137
139 Lookup table for persistent address verification status storage. The
140 table is maintained by the verify(8) service, and is opened before the
141 process releases privileges.
142 The lookup table is persistent by default (Postfix 2.7 and later).
144 Specify an empty table name to keep the information in volatile memory
145 which is lost after "postfix reload" or "postfix stop". This is the de‐
146 fault with Postfix version 2.6 and earlier.
147 Specify a location in a file system that will not fill up. If the data‐
149 base becomes corrupted, the world comes to an end. To recover delete
150 (NOT: truncate) the file and do "postfix reload".
151 Postfix daemon processes do not use root privileges when opening this
153 file (Postfix 2.5 and later). The file must therefore be stored under
154 a Postfix-owned directory such as the data_directory. As a migration
155 aid, an attempt to open the file under a non-Postfix directory is redi‐
156 rected to the Postfix-owned data_directory, and a warning is logged.
157 Examples:
159 address_verify_map = hash:/var/lib/postfix/verify
161 address_verify_map = btree:/var/lib/postfix/verify
162 This feature is available in Postfix 2.1 and later.
164
166 Enable caching of failed address verification probe results. When this
167 feature is enabled, the cache may pollute quickly with garbage. When
168 this feature is disabled, Postfix will generate an address probe for
169 every lookup.
170 This feature is available in Postfix 2.1 and later.
172
174 The time after which a failed probe expires from the address verifica‐
175 tion cache.
176 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
178 This feature is available in Postfix 2.1 and later.
180
182 The time after which a failed address verification probe needs to be
183 refreshed.
184 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
186 This feature is available in Postfix 2.1 and later.
188
190 A safety limit that prevents address verification requests from over‐
191 whelming the Postfix queue. By default, the number of pending requests
192 is limited to 1/4 of the active queue maximum size (qmgr_message_ac‐
193 tive_limit). The queue manager enforces the limit by tempfailing re‐
194 quests that exceed the limit. This affects only unknown addresses and
195 inactive addresses that have expired, because the verify(8) daemon au‐
196 tomatically refreshes an active address before it expires.
197 This feature is available in Postfix 3.1 and later.
199
201 How many times to query the verify(8) service for the completion of an
202 address verification request in progress.
203 By default, the Postfix SMTP server polls the verify(8) service up to
205 three times under non-overload conditions, and only once when under
206 overload. With Postfix version 2.5 and earlier, the SMTP server always
207 polls the verify(8) service up to three times by default.
208 Specify 1 to implement a crude form of greylisting, that is, always de‐
210 fer the first delivery request for a new address.
211 Examples:
213 # Postfix <= 2.6 default
215 address_verify_poll_count = 3
216 # Poor man's greylisting
217 address_verify_poll_count = 1
218 This feature is available in Postfix 2.1 and later.
220
222 The delay between queries for the completion of an address verification
223 request in progress.
224 The default polling delay is 3 seconds.
226 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
228 This feature is available in Postfix 2.1 and later.
230
232 The time after which a successful probe expires from the address veri‐
233 fication cache.
234 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
236 This feature is available in Postfix 2.1 and later.
238
240 The time after which a successful address verification probe needs to
241 be refreshed. The address verification status is not updated when the
242 probe fails (optimistic caching).
243 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
245 This feature is available in Postfix 2.1 and later.
247
249 Overrides the relay_transport parameter setting for address verifica‐
250 tion probes.
251 This feature is available in Postfix 2.1 and later.
253
255 Overrides the relayhost parameter setting for address verification
256 probes. This information can be overruled with the transport(5) table.
257 This feature is available in Postfix 2.1 and later.
259
261 The sender address to use in address verification probes; prior to
262 Postfix 2.5 the default was "postmaster". To avoid problems with ad‐
263 dress probes that are sent in response to address probes, the Postfix
264 SMTP server excludes the probe sender address from all SMTPD access
265 blocks.
266 Specify an empty value (address_verify_sender =) or <> if you want to
268 use the null sender address. Beware, some sites reject mail from <>,
269 even though RFCs require that such addresses be accepted.
270 Examples:
272 address_verify_sender = <>
274 address_verify_sender = postmaster@my.domain
275 This feature is available in Postfix 2.1 and later.
277
279 pendent_default_transport_maps)
280 Overrides the sender_dependent_default_transport_maps parameter setting
281 for address verification probes.
282 This feature is available in Postfix 2.7 and later.
284
286 layhost_maps)
287 Overrides the sender_dependent_relayhost_maps parameter setting for ad‐
288 dress verification probes.
289 This feature is available in Postfix 2.3 and later.
291
293 The time between changes in the time-dependent portion of address veri‐
294 fication probe sender addresses. The time-dependent portion is appended
295 to the localpart of the address specified with the address_ver‐
296 ify_sender parameter. This feature is ignored when the probe sender ad‐
297 dresses is the null sender, i.e. the address_verify_sender value is
298 empty or <>.
299 Historically, the probe sender address was fixed. This has caused such
301 addresses to end up on spammer mailing lists, and has resulted in
302 wasted network and processing resources.
303 To enable time-dependent probe sender addresses, specify a non-zero
305 time value (an integral value plus an optional one-letter suffix that
306 specifies the time unit). Specify a value of at least several hours,
307 to avoid problems with senders that use greylisting. Avoid nice TTL
308 values, to make the result less predictable. Time units are: s (sec‐
309 onds), m (minutes), h (hours), d (days), w (weeks).
310 This feature is available in Postfix 2.9 and later.
312
314 The name of the verify(8) address verification service. This service
315 maintains the status of sender and/or recipient address verification
316 probes, and generates probes on request by other Postfix processes.
317
319 Overrides the transport_maps parameter setting for address verification
320 probes.
321 This feature is available in Postfix 2.1 and later.
323
325 Overrides the virtual_transport parameter setting for address verifica‐
326 tion probes.
327 This feature is available in Postfix 2.1 and later.
329
331 The alias databases for local(8) delivery that are updated with
332 "newaliases" or with "sendmail -bi".
333 This is a separate configuration parameter because not all the tables
335 specified with $alias_maps have to be local files.
336 Examples:
338 alias_database = hash:/etc/aliases
340 alias_database = hash:/etc/mail/aliases
341
343 The alias databases that are used for local(8) delivery. See aliases(5)
344 for syntax details. Specify zero or more "type:name" lookup tables,
345 separated by whitespace or comma. Tables will be searched in the speci‐
346 fied order until a match is found. Note: these lookups are recursive.
347 The default list is system dependent. On systems with NIS, the default
349 is to search the local alias database, then the NIS alias database.
350 If you change the alias database, run "postalias /etc/aliases" (or
352 wherever your system stores the mail alias file), or simply run
353 "newaliases" to build the necessary DBM or DB file.
354 The local(8) delivery agent disallows regular expression substitution
356 of $1 etc. in alias_maps, because that would open a security hole.
357 The local(8) delivery agent will silently ignore requests to use the
359 proxymap(8) server within alias_maps. Instead it will open the table
360 directly. Before Postfix version 2.2, the local(8) delivery agent will
361 terminate with a fatal error.
362 Examples:
364 alias_maps = hash:/etc/aliases, nis:mail.aliases
366 alias_maps = hash:/etc/aliases
367
369 Restrict local(8) mail delivery to external commands. The default is
370 to disallow delivery to "|command" in :include: files (see aliases(5)
371 for the text that defines this terminology).
372 Specify zero or more of: alias, forward or include, in order to allow
374 commands in aliases(5), .forward files or in :include: files, respec‐
375 tively.
376 Example:
378 allow_mail_to_commands = alias,forward,include
380
382 Restrict local(8) mail delivery to external files. The default is to
383 disallow "/file/name" destinations in :include: files (see aliases(5)
384 for the text that defines this terminology).
385 Specify zero or more of: alias, forward or include, in order to allow
387 "/file/name" destinations in aliases(5), .forward files and in :in‐
388 clude: files, respectively.
389 Example:
391 allow_mail_to_files = alias,forward,include
393
395 Allow a sender or recipient address to have `-' as the first character.
396 By default, this is not allowed, to avoid accidents with software that
397 passes email addresses via the command line. Such software would not be
398 able to distinguish a malicious address from a bona fide command-line
399 option. Although this can be prevented by inserting a "--" option ter‐
400 minator into the command line, this is difficult to enforce consis‐
401 tently and globally.
402 As of Postfix version 2.5, this feature is implemented by trivial-re‐
404 write(8). With earlier versions this feature was implemented by
405 qmgr(8) and was limited to recipient addresses only.
406
408 Enable the rewriting of the form "user%domain" to "user@domain". This
409 is enabled by default.
410 Note: as of Postfix version 2.2, message header address rewriting hap‐
412 pens only when one of the following conditions is true:
413 • The message is received with the Postfix sendmail(1) command,
415 • The message is received from a network client that matches $lo‐
417 cal_header_rewrite_clients,
418 • The message is received from the network, and the re‐
420 mote_header_rewrite_domain parameter specifies a non-empty
421 value.
422 To get the behavior before Postfix version 2.2, specify "lo‐
424 cal_header_rewrite_clients = static:all".
425 Example:
427 allow_percent_hack = no
429
431 Forward mail with sender-specified routing (user[@%!]remote[@%!]site)
432 from untrusted clients to destinations matching $relay_domains.
433 By default, this feature is turned off. This closes a nasty open relay
435 loophole where a backup MX host can be tricked into forwarding junk
436 mail to a primary MX host which then spams it out to the world.
437 This parameter also controls if non-local addresses with sender-speci‐
439 fied routing can match Postfix access tables. By default, such ad‐
440 dresses cannot match Postfix access tables, because the address is am‐
441 biguous.
442
444 A list of non-default Postfix configuration directories that may be
445 specified with "-c config_directory" on the command line (in the case
446 of sendmail(1), with the "-C" option), or via the MAIL_CONFIG environ‐
447 ment parameter.
448 This list must be specified in the default Postfix main.cf file, and
450 will be used by set-gid Postfix commands such as postqueue(1) and post‐
451 drop(1).
452 Specify absolute pathnames, separated by comma or space. Note: $name
454 expansion is not supported.
455
457 Always add (Resent-) From:, To:, Date: or Message-ID: headers when not
458 present. Postfix 2.6 and later add these headers only when clients
459 match the local_header_rewrite_clients parameter setting. Earlier
460 Postfix versions always add these headers; this may break DKIM signa‐
461 tures that cover non-existent headers. The undisclosed_recipi‐
462 ents_header parameter setting determines whether a To: header will be
463 added.
464
466 Optional address that receives a "blind carbon copy" of each message
467 that is received by the Postfix mail system.
468 Note: with Postfix 2.3 and later the BCC address is added as if it was
470 specified with NOTIFY=NONE. The sender will not be notified when the
471 BCC address is undeliverable, as long as all down-stream software im‐
472 plements RFC 3461.
473 Note: with Postfix 2.2 and earlier the sender will be notified when the
475 BCC address is undeliverable.
476 Note: automatic BCC recipients are produced only for new mail. To
478 avoid mailer loops, automatic BCC recipients are not generated after
479 Postfix forwards mail internally, or after Postfix generates mail it‐
480 self.
481
483 The time unit over which client connection rates and other rates are
484 calculated.
485 This feature is implemented by the anvil(8) service which is available
487 in Postfix version 2.2 and later.
488 The default interval is relatively short. Because of the high frequency
490 of updates, the anvil(8) server uses volatile memory only. Thus, infor‐
491 mation is lost whenever the process terminates.
492 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
494 The default time unit is s (seconds).
495
497 How frequently the anvil(8) connection and rate limiting server logs
498 peak usage information.
499 This feature is available in Postfix 2.2 and later.
501 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
503 The default time unit is s (seconds).
504
506 With locally submitted mail, append the string "@$myorigin" to mail ad‐
507 dresses without domain information. With remotely submitted mail, ap‐
508 pend the string "@$remote_header_rewrite_domain" instead.
509 Note 1: this feature is enabled by default and must not be turned off.
511 Postfix does not support domain-less addresses.
512 Note 2: with Postfix version 2.2, message header address rewriting hap‐
514 pens only when one of the following conditions is true:
515 • The message is received with the Postfix sendmail(1) command,
517 • The message is received from a network client that matches $lo‐
519 cal_header_rewrite_clients,
520 • The message is received from the network, and the re‐
522 mote_header_rewrite_domain parameter specifies a non-empty
523 value.
524 To get the behavior before Postfix version 2.2, specify "lo‐
526 cal_header_rewrite_clients = static:all".
527
529 With locally submitted mail, append the string ".$mydomain" to ad‐
530 dresses that have no ".domain" information. With remotely submitted
531 mail, append the string ".$remote_header_rewrite_domain" instead.
532 Note 1: this feature is enabled by default. If disabled, users will not
534 be able to send mail to "user@partialdomainname" but will have to spec‐
535 ify full domain names instead.
536 Note 2: with Postfix version 2.2, message header address rewriting hap‐
538 pens only when one of the following conditions is true:
539 • The message is received with the Postfix sendmail(1) command,
541 • The message is received from a network client that matches $lo‐
543 cal_header_rewrite_clients,
544 • The message is received from the network, and the re‐
546 mote_header_rewrite_domain parameter specifies a non-empty
547 value.
548 To get the behavior before Postfix version 2.2, specify "lo‐
550 cal_header_rewrite_clients = static:all".
551
553 How long the postkick(1) command waits for a request to enter the Post‐
554 fix daemon process input buffer before giving up.
555 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
557 The default time unit is s (seconds).
558 This feature is available in Postfix 2.1 and later.
560
562 List of users who are authorized to flush the queue.
563 By default, all users are allowed to flush the queue. Access is always
565 granted if the invoking user is the super-user or the $mail_owner user.
566 Otherwise, the real UID of the process is looked up in the system pass‐
567 word file, and access is granted only if the corresponding login name
568 is on the access list. The username "unknown" is used for processes
569 whose real UID is not found in the password file.
570 Specify a list of user names, "/file/name" or "type:table" patterns,
572 separated by commas and/or whitespace. The list is matched left to
573 right, and the search stops on the first match. A "/file/name" pattern
574 is replaced by its contents; a "type:table" lookup table is matched
575 when a name matches a lookup key (the lookup result is ignored). Con‐
576 tinue long lines by starting the next line with whitespace. Specify
577 "!pattern" to exclude a name from the list. The form "!/file/name" is
578 supported only in Postfix version 2.4 and later.
579 This feature is available in Postfix 2.2 and later.
581
583 List of users who are authorized to view the queue.
584 By default, all users are allowed to view the queue. Access is always
586 granted if the invoking user is the super-user or the $mail_owner user.
587 Otherwise, the real UID of the process is looked up in the system pass‐
588 word file, and access is granted only if the corresponding login name
589 is on the access list. The username "unknown" is used for processes
590 whose real UID is not found in the password file.
591 Specify a list of user names, "/file/name" or "type:table" patterns,
593 separated by commas and/or whitespace. The list is matched left to
594 right, and the search stops on the first match. A "/file/name" pattern
595 is replaced by its contents; a "type:table" lookup table is matched
596 when a name matches a lookup key (the lookup result is ignored). Con‐
597 tinue long lines by starting the next line with whitespace. Specify
598 "!pattern" to exclude a user name from the list. The form "!/file/name"
599 is supported only in Postfix version 2.4 and later.
600 This feature is available in Postfix 2.2 and later.
602
604 List of users who are authorized to submit mail with the sendmail(1)
605 command (and with the privileged postdrop(1) helper command).
606 By default, all users are allowed to submit mail. Otherwise, the real
608 UID of the process is looked up in the system password file, and access
609 is granted only if the corresponding login name is on the access list.
610 The username "unknown" is used for processes whose real UID is not
611 found in the password file. To deny mail submission access to all users
612 specify an empty list.
613 Specify a list of user names, "/file/name" or "type:table" patterns,
615 separated by commas and/or whitespace. The list is matched left to
616 right, and the search stops on the first match. A "/file/name" pattern
617 is replaced by its contents; a "type:table" lookup table is matched
618 when a name matches a lookup key (the lookup result is ignored). Con‐
619 tinue long lines by starting the next line with whitespace. Specify
620 "!pattern" to exclude a user name from the list. The form "!/file/name"
621 is supported only in Postfix version 2.4 and later.
622 Example:
624 authorized_submit_users = !www, static:all
626 This feature is available in Postfix 2.2 and later.
628
630 What remote SMTP clients are allowed to specify the XVERP command.
631 This command requests that mail be delivered one recipient at a time
632 with a per recipient return address.
633 By default, only trusted clients are allowed to specify XVERP.
635 This parameter was introduced with Postfix version 1.1. Postfix ver‐
637 sion 2.1 renamed this parameter to smtpd_authorized_verp_clients and
638 changed the default to none.
639 Specify a list of network/netmask patterns, separated by commas and/or
641 whitespace. The mask specifies the number of bits in the network part
642 of a host address. You can also specify hostnames or .domain names (the
643 initial dot causes the domain to match any name below it),
644 "/file/name" or "type:table" patterns. A "/file/name" pattern is re‐
645 placed by its contents; a "type:table" lookup table is matched when a
646 table entry matches a lookup string (the lookup result is ignored).
647 Continue long lines by starting the next line with whitespace. Specify
648 "!pattern" to exclude an address or network block from the list. The
649 form "!/file/name" is supported only in Postfix version 2.4 and later.
650 Note: IP version 6 address information must be specified inside [] in
652 the authorized_verp_clients value, and in files specified with
653 "/file/name". IP version 6 addresses contain the ":" character, and
654 would otherwise be confused with a "type:table" pattern.
655
657 Produce additional bounce(8) logfile records that can be read by Post‐
658 fix versions before 2.0. The current and more extensible "name = value"
659 format is needed in order to implement more sophisticated functional‐
660 ity.
661 This feature is available in Postfix 2.1 and later.
663
665 The per-table I/O buffer size for programs that create Berkeley DB hash
666 or btree tables. Specify a byte count.
667 This feature is available in Postfix 2.0 and later.
669
671 The per-table I/O buffer size for programs that read Berkeley DB hash
672 or btree tables. Specify a byte count.
673 This feature is available in Postfix 2.0 and later.
675
677 Where the Postfix SMTP client should deliver mail when it detects a
678 "mail loops back to myself" error condition. This happens when the lo‐
679 cal MTA is the best SMTP mail exchanger for a destination not listed in
680 $mydestination, $inet_interfaces, $proxy_interfaces, $virtual_alias_do‐
681 mains, or $virtual_mailbox_domains. By default, the Postfix SMTP
682 client returns such mail as undeliverable.
683 Specify, for example, "best_mx_transport = local" to pass the mail from
685 the Postfix SMTP client to the local(8) delivery agent. You can specify
686 any message delivery "transport" or "transport:nexthop" that is defined
687 in the master.cf file. See the transport(5) manual page for the syntax
688 and meaning of "transport" or "transport:nexthop".
689 However, this feature is expensive because it ties up a Postfix SMTP
691 client process while the local(8) delivery agent is doing its work. It
692 is more efficient (for Postfix) to list all hosted domains in a table
693 or database.
694
696 Whether or not to use the local biff service. This service sends "new
697 mail" notifications to users who have requested new mail notification
698 with the UNIX command "biff y".
699 For compatibility reasons this feature is on by default. On systems
701 with lots of interactive users, the biff service can be a performance
702 drain. Specify "biff = no" in main.cf to disable.
703
705 Optional lookup tables for content inspection as specified in the
706 body_checks(5) manual page.
707 Note: with Postfix versions before 2.0, these rules inspect all content
709 after the primary message headers.
710
712 How much text in a message body segment (or attachment, if you prefer
713 to use that term) is subjected to body_checks inspection. The amount
714 of text is limited to avoid scanning huge attachments.
715 This feature is available in Postfix 2.0 and later.
717
719 The recipient of postmaster notifications with the message headers of
720 mail that Postfix did not deliver and of SMTP conversation transcripts
721 of mail that Postfix did not receive. This feature is enabled with the
722 notify_classes parameter.
723
725 Consider a bounce message as undeliverable, when delivery fails with a
726 temporary error, and the time in the queue has reached the
727 bounce_queue_lifetime limit. By default, this limit is the same as for
728 regular mail.
729 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
731 The default time unit is d (days).
732 Specify 0 when mail delivery should be tried only once.
734 This feature is available in Postfix 2.1 and later.
736
738 The name of the bounce(8) service. This service maintains a record of
739 failed delivery attempts and generates non-delivery notifications.
740 This feature is available in Postfix 2.0 and later.
742
744 The maximal amount of original message text that is sent in a non-de‐
745 livery notification. Specify a byte count. A message is returned as
746 either message/rfc822 (the complete original) or as text/rfc822-headers
747 (the headers only). With Postfix version 2.4 and earlier, a message is
748 always returned as message/rfc822 and is truncated when it exceeds the
749 size limit.
750 Notes:
752 • If you increase this limit, then you should increase the
754 mime_nesting_limit value proportionally.
755 • Be careful when making changes. Excessively large values will
757 result in the loss of non-delivery notifications, when a bounce
758 message size exceeds a local or remote MTA's message size limit.
759
761 Pathname of a configuration file with bounce message templates. These
762 override the built-in templates of delivery status notification (DSN)
763 messages for undeliverable mail, for delayed mail, successful delivery,
764 or delivery verification. The bounce(5) manual page describes how to
765 edit and test template files.
766 Template message body text may contain $name references to Postfix con‐
768 figuration parameters. The result of $name expansion can be previewed
769 with "postconf -b file_name" before the file is placed into the Postfix
770 configuration directory.
771 This feature is available in Postfix 2.3 and later.
773
775 Enable interoperability with remote SMTP clients that implement an ob‐
776 solete version of the AUTH command (RFC 4954). Examples of such clients
777 are MicroSoft Outlook Express version 4 and MicroSoft Exchange version
778 5.0.
779 Specify "broken_sasl_auth_clients = yes" to have Postfix advertise AUTH
781 support in a non-standard way.
782
784 header_sender, header_recipient)
785 What addresses are subject to canonical_maps address mapping. By de‐
786 fault, canonical_maps address mapping is applied to envelope sender and
787 recipient addresses, and to header sender and header recipient ad‐
788 dresses.
789 Specify one or more of: envelope_sender, envelope_recipient,
791 header_sender, header_recipient
792 This feature is available in Postfix 2.2 and later.
794
796 Optional address mapping lookup tables for message headers and en‐
797 velopes. The mapping is applied to both sender and recipient addresses,
798 in both envelopes and in headers, as controlled with the canoni‐
799 cal_classes parameter. This is typically used to clean up dirty ad‐
800 dresses from legacy mail systems, or to replace login names by First‐
801 name.Lastname. The table format and lookups are documented in canoni‐
802 cal(5). For an overview of Postfix address manipulations see the AD‐
803 DRESS_REWRITING_README document.
804 Specify zero or more "type:name" lookup tables, separated by whitespace
806 or comma. Tables will be searched in the specified order until a match
807 is found. Note: these lookups are recursive.
808 If you use this feature, run "postmap /etc/postfix/canonical" to build
810 the necessary DBM or DB file after every change. The changes will be‐
811 come visible after a minute or so. Use "postfix reload" to eliminate
812 the delay.
813 Note: with Postfix version 2.2, message header address mapping happens
815 only when message header address rewriting is enabled:
816 • The message is received with the Postfix sendmail(1) command,
818 • The message is received from a network client that matches $lo‐
820 cal_header_rewrite_clients,
821 • The message is received from the network, and the re‐
823 mote_header_rewrite_domain parameter specifies a non-empty
824 value.
825 To get the behavior before Postfix version 2.2, specify "lo‐
827 cal_header_rewrite_clients = static:all".
828 Examples:
830 canonical_maps = dbm:/etc/postfix/canonical
832 canonical_maps = hash:/etc/postfix/canonical
833
835 The name of the cleanup(8) service. This service rewrites addresses
836 into the standard form, and performs canonical(5) address mapping and
837 virtual(5) aliasing.
838 This feature is available in Postfix 2.0 and later.
840
842 The location of all postfix administrative commands.
843
845 The local(8) delivery agent working directory for delivery to external
846 command. Failure to change directory causes the delivery to be de‐
847 ferred.
848 The command_execution_directory value is not subject to Postfix config‐
850 uration parameter $name expansion. Instead, the following $name expan‐
851 sions are done on command_execution_directory before the directory is
852 used. Expansion happens in the context of the delivery request. The
853 result of $name expansion is filtered with the character set that is
854 specified with the execution_directory_expansion_filter parameter.
855 $user The recipient's username.
857 $shell The recipient's login shell pathname.
859 $home The recipient's home directory.
861 $recipient
863 The full recipient address.
864 $extension
866 The optional recipient address extension.
867 $domain
869 The recipient domain.
870 $local The entire recipient localpart.
872 $recipient_delimiter
874 The address extension delimiter that was found in the recipient
875 address (Postfix 2.11 and later), or the system-wide recipient
876 address extension delimiter (Postfix 2.10 and earlier).
877 ${name?value}
879 Expands to value when $name is non-empty.
880 ${name:value}
882 Expands to value when $name is empty.
883 Instead of $name you can also specify ${name} or $(name).
885 This feature is available in Postfix 2.2 and later.
887
889 Restrict the characters that the local(8) delivery agent allows in
890 $name expansions of $mailbox_command and $command_execution_directory.
891 Characters outside the allowed set are replaced by underscores.
892
894 Time limit for delivery to external commands. This limit is used by the
895 local(8) delivery agent, and is the default time limit for delivery by
896 the pipe(8) delivery agent.
897 Note: if you set this time limit to a large value you must update the
899 global ipc_timeout parameter as well.
900
902 A safety net that causes Postfix to run with backwards-compatible de‐
903 fault settings after an upgrade to a newer Postfix version.
904 With backwards compatibility turned on (the main.cf compatibility_level
906 value is less than the Postfix built-in value), Postfix looks for set‐
907 tings that are left at their implicit default value, and logs a message
908 when a backwards-compatible default setting is required.
909 using backwards-compatible default setting name=value
911 to [accept a specific client request]
912 using backwards-compatible default setting name=value
914 to [enable specific Postfix behavior]
915 See COMPATIBILITY_README for specific message details. If such a mes‐
917 sage is logged in the context of a legitimate request, the system ad‐
918 ministrator should make the backwards-compatible setting permanent in
919 main.cf or master.cf, for example:
920 # postconf name=value
922 # postfix reload
923 When no more backwards-compatible settings need to be made permanent,
925 the administrator should turn off backwards compatibility by updating
926 the compatibility_level setting in main.cf:
927 # postconf compatibility_level=N
929 # postfix reload
930 For N specify the number that is logged in your postfix(1) warning mes‐
932 sage:
933 warning: To disable backwards compatibility use "postconf
935 compatibility_level=N" and "postfix reload"
936 Starting with Postfix version 3.6, the compatibility level in the above
938 warning message is the Postfix version that introduced the last incom‐
939 patible change. The level is formatted as major.minor.patch, where
940 patch is usually omitted and defaults to zero. Earlier compatibility
941 levels are 0, 1 and 2.
942 NOTE: this also introduces support for the "<level", "<=level", and
944 other operators to compare compatibility levels. With the standard op‐
945 erators "<", "<=", etc., compatibility level "3.10" would be smaller
946 than "3.9" which is undesirable.
947 This feature is available in Postfix 3.0 and later.
949
951 The default location of the Postfix main.cf and master.cf configuration
952 files. This can be overruled via the following mechanisms:
953 • The MAIL_CONFIG environment variable (daemon processes and com‐
955 mands).
956 • The "-c" command-line option (commands only).
958 With Postfix commands that run with set-gid privileges, a config_direc‐
960 tory override either requires root privileges, or it requires that the
961 directory is listed with the alternate_config_directories parameter in
962 the default main.cf file.
963
965 After sending a "your message is delayed" notification, inform the
966 sender when the delay clears up. This can result in a sudden burst of
967 notifications at the end of a prolonged network outage, and is there‐
968 fore disabled by default.
969 See also: delay_warning_time.
971 This feature is available in Postfix 3.0 and later.
973
975 Time limit for connection cache connect, send or receive operations.
976 The time limit is enforced in the client.
977 This feature is available in Postfix 2.3 and later.
979
981 The name of the scache(8) connection cache service. This service main‐
982 tains a limited pool of cached sessions.
983 This feature is available in Postfix 2.2 and later.
985
987 How frequently the scache(8) server logs usage statistics with connec‐
988 tion cache hit and miss rates for logical destinations and for physical
989 endpoints.
990
992 The maximal time-to-live value that the scache(8) connection cache
993 server allows. Requests that specify a larger TTL will be stored with
994 the maximum allowed TTL. The purpose of this additional control is to
995 protect the infrastructure against careless people. The cache TTL is
996 already bounded by $max_idle.
997
999 After the message is queued, send the entire message to the specified
1000 transport:destination. The transport name specifies the first field of
1001 a mail delivery agent definition in master.cf; the syntax of the
1002 next-hop destination is described in the manual page of the correspond‐
1003 ing delivery agent. More information about external content filters is
1004 in the Postfix FILTER_README file.
1005 Notes:
1007 • This setting has lower precedence than a FILTER action that is
1009 specified in an access(5), header_checks(5) or body_checks(5)
1010 table.
1011 • The meaning of an empty next-hop filter destination is version
1013 dependent. Postfix 2.7 and later will use the recipient domain;
1014 earlier versions will use $myhostname. Specify "default_fil‐
1015 ter_nexthop = $myhostname" for compatibility with Postfix 2.6 or
1016 earlier, or specify a content_filter value with an explicit
1017 next-hop destination.
1018
1020 Search path for Cyrus SASL application configuration files, currently
1021 used only to locate the $smtpd_sasl_path.conf file. Specify zero or
1022 more directories separated by a colon character, or an empty value to
1023 use Cyrus SASL's built-in search path.
1024 This feature is available in Postfix 2.5 and later when compiled with
1026 Cyrus SASL 2.1.22 or later.
1027
1029 The directory with Postfix support programs and daemon programs. These
1030 should not be invoked directly by humans. The directory must be owned
1031 by root.
1032
1034 How a Postfix daemon process handles errors while opening lookup ta‐
1035 bles: gradual degradation or immediate termination.
1036 no (default)
1038 Gradual degradation: a daemon process logs a message of type
1039 "error" and continues execution with reduced functionality. Fea‐
1040 tures that do not depend on the unavailable table will work nor‐
1041 mally, while features that depend on the table will result in a
1042 type "warning" message.
1043 When the notify_classes parameter value contains the "data"
1044 class, the Postfix SMTP server and client will report tran‐
1045 scripts of sessions with an error because a table is unavail‐
1046 able.
1047 yes (historical behavior)
1049 Immediate termination: a daemon process logs a type "fatal" mes‐
1050 sage and terminates immediately. This option reduces the number
1051 of possible code paths through Postfix, and may therefore be
1052 slightly more secure than the default.
1053 For the sake of sanity, the number of type "error" messages is limited
1055 to 13 over the lifetime of a daemon process.
1056 This feature is available in Postfix 2.9 and later.
1058
1060 How much time a Postfix daemon process may take to handle a request be‐
1061 fore it is terminated by a built-in watchdog timer.
1062 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
1064 The default time unit is s (seconds).
1065
1067 The directory with Postfix-writable data files (for example: caches,
1068 pseudo-random numbers). This directory must be owned by the mail_owner
1069 account, and must not be shared with non-Postfix software.
1070 This feature is available in Postfix 2.5 and later.
1072
1074 The increment in verbose logging level when a nexthop destination, re‐
1075 mote client or server name or network address matches a pattern given
1076 with the debug_peer_list parameter.
1077 Per-nexthop debug logging is available in Postfix 3.6 and later.
1079
1081 Optional list of nexthop destination, remote client or server name or
1082 network address patterns that, if matched, cause the verbose logging
1083 level to increase by the amount specified in $debug_peer_level.
1084 Per-nexthop debug logging is available in Postfix 3.6 and later.
1086 Specify domain names, network/netmask patterns, "/file/name" patterns
1088 or "type:table" lookup tables. The right-hand side result from
1089 "type:table" lookups is ignored.
1090 Pattern matching of domain names is controlled by the presence or ab‐
1092 sence of "debug_peer_list" in the parent_domain_matches_subdomains pa‐
1093 rameter value.
1094 Examples:
1096 debug_peer_list = 127.0.0.1
1098 debug_peer_list = example.com
1099
1101 The external command to execute when a Postfix daemon program is in‐
1102 voked with the -D option.
1103 Use "command .. & sleep 5" so that the debugger can attach before the
1105 process marches on. If you use an X-based debugger, be sure to set up
1106 your XAUTHORITY environment variable before starting Postfix.
1107 Note: the command is subject to $name expansion, before it is passed to
1109 the default command interpreter. Specify "$$" to produce a single "$"
1110 character.
1111 Example:
1113 debugger_command =
1115 PATH=/usr/bin:/usr/X11R6/bin
1116 ddd $daemon_directory/$process_name $process_id & sleep 5
1117
1119 The default database type for use in newaliases(1), postalias(1) and
1120 postmap(1) commands. On many UNIX systems the default type is either
1121 dbm or hash. The default setting is frozen when the Postfix system is
1122 built.
1123 Examples:
1125 default_database_type = hash
1127 default_database_type = dbm
1128
1130 How often the Postfix queue manager's scheduler is allowed to preempt
1131 delivery of one message with another.
1132 Each transport maintains a so-called "available delivery slot counter"
1134 for each message. One message can be preempted by another one when the
1135 other message can be delivered using no more delivery slots (i.e., in‐
1136 vocations of delivery agents) than the current message counter has ac‐
1137 cumulated (or will eventually accumulate - see about slot loans below).
1138 This parameter controls how often is the counter incremented - it hap‐
1139 pens after each default_delivery_slot_cost recipients have been deliv‐
1140 ered.
1141 The cost of 0 is used to disable the preempting scheduling completely.
1143 The minimum value the scheduling algorithm can use is 2 - use it if you
1144 want to maximize the message throughput rate. Although there is no max‐
1145 imum, it doesn't make much sense to use values above say 50.
1146 The only reason why the value of 2 is not the default is the way this
1148 parameter affects the delivery of mailing-list mail. In the worst case,
1149 delivery can take somewhere between (cost+1/cost) and (cost/cost-1)
1150 times more than if the preemptive scheduler was disabled. The default
1151 value of 5 turns out to provide reasonable message response times while
1152 making sure the mailing-list deliveries are not extended by more than
1153 20-25 percent even in the worst case.
1154 Use transport_delivery_slot_cost to specify a transport-specific over‐
1156 ride, where transport is the master.cf name of the message delivery
1157 transport.
1158 Examples:
1160 default_delivery_slot_cost = 0
1162 default_delivery_slot_cost = 2
1163
1165 The default value for transport-specific _delivery_slot_discount set‐
1166 tings.
1167 This parameter speeds up the moment when a message preemption can hap‐
1169 pen. Instead of waiting until the full amount of delivery slots re‐
1170 quired is available, the preemption can happen when transport_deliv‐
1171 ery_slot_discount percent of the required amount plus transport_deliv‐
1172 ery_slot_loan still remains to be accumulated. Note that the full
1173 amount will still have to be accumulated before another preemption can
1174 take place later.
1175 Use transport_delivery_slot_discount to specify a transport-specific
1177 override, where transport is the master.cf name of the message delivery
1178 transport.
1179
1181 The default value for transport-specific _delivery_slot_loan settings.
1182 This parameter speeds up the moment when a message preemption can hap‐
1184 pen. Instead of waiting until the full amount of delivery slots re‐
1185 quired is available, the preemption can happen when transport_deliv‐
1186 ery_slot_discount percent of the required amount plus transport_deliv‐
1187 ery_slot_loan still remains to be accumulated. Note that the full
1188 amount will still have to be accumulated before another preemption can
1189 take place later.
1190 Use transport_delivery_slot_loan to specify a transport-specific over‐
1192 ride, where transport is the master.cf name of the message delivery
1193 transport.
1194
1196 Optional filter to replace the delivery status code or explanatory text
1197 of successful or unsuccessful deliveries. This does not allow the re‐
1198 placement of a successful status code (2.X.X) with an unsuccessful sta‐
1199 tus code (4.X.X or 5.X.X) or vice versa.
1200 Note: the (smtp|lmtp)_delivery_status_filter is applied only once per
1202 recipient: when delivery is successful, when delivery is rejected with
1203 5XX, or when there are no more alternate MX or A destinations. Use
1204 smtp_reply_filter or lmtp_reply_filter to inspect responses for all de‐
1205 livery attempts.
1206 The following parameters can be used to implement a filter for specific
1208 delivery agents: lmtp_delivery_status_filter, local_delivery_sta‐
1209 tus_filter, pipe_delivery_status_filter, smtp_delivery_status_filter or
1210 virtual_delivery_status_filter. These parameters support the same fil‐
1211 ter syntax as described here.
1212 Specify zero or more "type:table" lookup table names, separated by
1214 comma or whitespace. For each successful or unsuccessful delivery to a
1215 recipient, the tables are queried in the specified order with one line
1216 of text that is structured as follows:
1217 enhanced-status-code SPACE explanatory-text
1219 The first table match wins. The lookup result must have the same struc‐
1221 ture as the query, a successful status code (2.X.X) must be replaced
1222 with a successful status code, an unsuccessful status code (4.X.X or
1223 5.X.X) must be replaced with an unsuccessful status code, and the ex‐
1224 planatory text field must be non-empty. Other results will result in a
1225 warning.
1226 Example 1: convert specific soft TLS errors into hard errors, by over‐
1228 riding the first number in the enhanced status code.
1229 /etc/postfix/main.cf:
1231 smtp_delivery_status_filter = pcre:/etc/postfix/smtp_dsn_filter
1232 /etc/postfix/smtp_dsn_filter:
1234 /^4(\.\d+\.\d+ TLS is required, but host \S+ refused to start TLS: .+)/
1235 5$1
1236 /^4(\.\d+\.\d+ TLS is required, but was not offered by host .+)/
1237 5$1
1238 # Do not change the following into hard bounces. They may
1239 # result from a local configuration problem.
1240 # 4.\d+.\d+ TLS is required, but our TLS engine is unavailable
1241 # 4.\d+.\d+ TLS is required, but unavailable
1242 # 4.\d+.\d+ Cannot start TLS: handshake failure
1243 Example 2: censor the per-recipient delivery status text so that it
1245 does not reveal the destination command or filename when a remote
1246 sender requests confirmation of successful delivery.
1247 /etc/postfix/main.cf:
1249 local_delivery_status_filter = pcre:/etc/postfix/local_dsn_filter
1250 /etc/postfix/local_dsn_filter:
1252 /^(2\S+ delivered to file).+/ $1
1253 /^(2\S+ delivered to command).+/ $1
1254 Notes:
1256 • This feature will NOT override the soft_bounce safety net.
1258 • This feature will change the enhanced status code and text that
1260 is logged to the maillog file, and that is reported to the
1261 sender in delivery confirmation or non-delivery notifications.
1262 This feature is available in Postfix 3.0 and later.
1264
1266 How many pseudo-cohorts must suffer connection or handshake failure be‐
1267 fore a specific destination is considered unavailable (and further de‐
1268 livery is suspended). Specify zero to disable this feature. A destina‐
1269 tion's pseudo-cohort failure count is reset each time a delivery com‐
1270 pletes without connection or handshake failure for that specific desti‐
1271 nation.
1272 A pseudo-cohort is the number of deliveries equal to a destination's
1274 delivery concurrency.
1275 Use transport_destination_concurrency_failed_cohort_limit to specify a
1277 transport-specific override, where transport is the master.cf name of
1278 the message delivery transport.
1279 This feature is available in Postfix 2.5. The default setting is com‐
1281 patible with earlier Postfix versions.
1282
1284 The default maximal number of parallel deliveries to the same destina‐
1285 tion. This is the default limit for delivery via the lmtp(8), pipe(8),
1286 smtp(8) and virtual(8) delivery agents. With per-destination recipient
1287 limit > 1, a destination is a domain, otherwise it is a recipient.
1288 Use transport_destination_concurrency_limit to specify a transport-spe‐
1290 cific override, where transport is the master.cf name of the message
1291 delivery transport.
1292
1294 The per-destination amount of delivery concurrency negative feedback,
1295 after a delivery completes with a connection or handshake failure.
1296 Feedback values are in the range 0..1 inclusive. With negative feed‐
1297 back, concurrency is decremented at the beginning of a sequence of
1298 length 1/feedback. This is unlike positive feedback, where concurrency
1299 is incremented at the end of a sequence of length 1/feedback.
1300 As of Postfix version 2.5, negative feedback cannot reduce delivery
1302 concurrency to zero. Instead, a destination is marked dead (further
1303 delivery suspended) after the failed pseudo-cohort count reaches $de‐
1304 fault_destination_concurrency_failed_cohort_limit (or $transport_desti‐
1305 nation_concurrency_failed_cohort_limit). To make the scheduler com‐
1306 pletely immune to connection or handshake failures, specify a zero
1307 feedback value and a zero failed pseudo-cohort limit.
1308 Specify one of the following forms:
1310 number
1312 number / number
1314 Constant feedback. The value must be in the range 0..1 inclu‐
1315 sive. The default setting of "1" is compatible with Postfix
1316 versions before 2.5, where a destination's delivery concurrency
1317 is throttled down to zero (and further delivery suspended) after
1318 a single failed pseudo-cohort.
1319 number / concurrency
1321 Variable feedback of "number / (delivery concurrency)". The
1322 number must be in the range 0..1 inclusive. With number equal to
1323 "1", a destination's delivery concurrency is decremented by 1
1324 after each failed pseudo-cohort.
1325 A pseudo-cohort is the number of deliveries equal to a destination's
1327 delivery concurrency.
1328 Use transport_destination_concurrency_negative_feedback to specify a
1330 transport-specific override, where transport is the master.cf name of
1331 the message delivery transport.
1332 This feature is available in Postfix 2.5. The default setting is com‐
1334 patible with earlier Postfix versions.
1335
1337 The per-destination amount of delivery concurrency positive feedback,
1338 after a delivery completes without connection or handshake failure.
1339 Feedback values are in the range 0..1 inclusive. The concurrency in‐
1340 creases until it reaches the per-destination maximal concurrency limit.
1341 With positive feedback, concurrency is incremented at the end of a se‐
1342 quence with length 1/feedback. This is unlike negative feedback, where
1343 concurrency is decremented at the start of a sequence of length 1/feed‐
1344 back.
1345 Specify one of the following forms:
1347 number
1349 number / number
1351 Constant feedback. The value must be in the range 0..1 inclu‐
1352 sive. The default setting of "1" is compatible with Postfix ver‐
1353 sions before 2.5, where a destination's delivery concurrency
1354 doubles after each successful pseudo-cohort.
1355 number / concurrency
1357 Variable feedback of "number / (delivery concurrency)". The
1358 number must be in the range 0..1 inclusive. With number equal to
1359 "1", a destination's delivery concurrency is incremented by 1
1360 after each successful pseudo-cohort.
1361 A pseudo-cohort is the number of deliveries equal to a destination's
1363 delivery concurrency.
1364 Use transport_destination_concurrency_positive_feedback to specify a
1366 transport-specific override, where transport is the master.cf name of
1367 the message delivery transport.
1368 This feature is available in Postfix 2.5 and later.
1370
1372 The default amount of delay that is inserted between individual message
1373 deliveries to the same destination and over the same message delivery
1374 transport. Specify a non-zero value to rate-limit those message deliv‐
1375 eries to at most one per $default_destination_rate_delay.
1376 The resulting behavior depends on the value of the corresponding
1378 per-destination recipient limit.
1379 • With a corresponding per-destination recipient limit > 1, the
1381 rate delay specifies the time between deliveries to the same do‐
1382 main. Different domains are delivered in parallel, subject to
1383 the process limits specified in master.cf.
1384 • With a corresponding per-destination recipient limit equal to 1,
1386 the rate delay specifies the time between deliveries to the same
1387 recipient. Different recipients are delivered in parallel, sub‐
1388 ject to the process limits specified in master.cf.
1389 To enable the delay, specify a non-zero time value (an integral value
1391 plus an optional one-letter suffix that specifies the time unit).
1392 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
1394 The default time unit is s (seconds).
1395 NOTE: the delay is enforced by the queue manager. The delay timer state
1397 does not survive "postfix reload" or "postfix stop".
1398 Use transport_destination_rate_delay to specify a transport-specific
1400 override, where transport is the master.cf name of the message delivery
1401 transport.
1402 NOTE: with a non-zero _destination_rate_delay, specify a transport_des‐
1404 tination_concurrency_failed_cohort_limit of 10 or more to prevent Post‐
1405 fix from deferring all mail for the same destination after only one
1406 connection or handshake error.
1407 This feature is available in Postfix 2.5 and later.
1409
1411 The default maximal number of recipients per message delivery. This is
1412 the default limit for delivery via the lmtp(8), pipe(8), smtp(8) and
1413 virtual(8) delivery agents.
1414 Setting this parameter to a value of 1 affects email deliveries as fol‐
1416 lows:
1417 • It changes the meaning of the corresponding per-destination con‐
1419 currency limit, from concurrency of deliveries to the same do‐
1420 main into concurrency of deliveries to the same recipient. Dif‐
1421 ferent recipients are delivered in parallel, subject to the
1422 process limits specified in master.cf.
1423 • It changes the meaning of the corresponding per-destination rate
1425 delay, from the delay between deliveries to the same domain into
1426 the delay between deliveries to the same recipient. Again, dif‐
1427 ferent recipients are delivered in parallel, subject to the
1428 process limits specified in master.cf.
1429 • It changes the meaning of other corresponding per-destination
1431 settings in a similar manner, from settings for delivery to the
1432 same domain into settings for delivery to the same recipient.
1433 Use transport_destination_recipient_limit to specify a transport-spe‐
1435 cific override, where transport is the master.cf name of the message
1436 delivery transport.
1437
1439 The default value for the extra per-transport limit imposed on the num‐
1440 ber of in-memory recipients. This extra recipient space is reserved
1441 for the cases when the Postfix queue manager's scheduler preempts one
1442 message with another and suddenly needs some extra recipients slots for
1443 the chosen message in order to avoid performance degradation.
1444 Use transport_extra_recipient_limit to specify a transport-specific
1446 override, where transport is the master.cf name of the message delivery
1447 transport.
1448
1450 When a content_filter or FILTER request specifies no explicit next-hop
1451 destination, use $default_filter_nexthop instead; when that value is
1452 empty, use the domain in the recipient address. Specify "default_fil‐
1453 ter_nexthop = $myhostname" for compatibility with Postfix version 2.6
1454 and earlier, or specify an explicit next-hop destination with each con‐
1455 tent_filter value or FILTER action.
1456 This feature is available in Postfix 2.7 and later.
1458
1460 How many recipients a message must have in order to invoke the Postfix
1461 queue manager's scheduling algorithm at all. Messages which would
1462 never accumulate at least this many delivery slots (subject to slot
1463 cost parameter as well) are never preempted.
1464 Use transport_minimum_delivery_slots to specify a transport-specific
1466 override, where transport is the master.cf name of the message delivery
1467 transport.
1468
1470 The default rights used by the local(8) delivery agent for delivery to
1471 external file or command. These rights are used when delivery is re‐
1472 quested from an aliases(5) file that is owned by root, or when delivery
1473 is done on behalf of root. DO NOT SPECIFY A PRIVILEGED USER OR THE
1474 POSTFIX OWNER.
1475
1477 The default maximal number of Postfix child processes that provide a
1478 given service. This limit can be overruled for specific services in the
1479 master.cf file.
1480
1482 The default Postfix SMTP server response template for a request that is
1483 rejected by an RBL-based restriction. This template can be overruled by
1484 specific entries in the optional rbl_reply_maps lookup table.
1485 This feature is available in Postfix 2.0 and later.
1487 The template does not support Postfix configuration parameter $name
1489 substitution. Instead, it supports exactly one level of $name substitu‐
1490 tion for the following attributes:
1491 $client
1493 The client hostname and IP address, formatted as name[address].
1494 $client_address
1496 The client IP address.
1497 $client_name
1499 The client hostname or "unknown". See reject_un‐
1500 known_client_hostname for more details.
1501 $reverse_client_name
1503 The client hostname from address->name lookup, or "unknown".
1504 See reject_unknown_reverse_client_hostname for more details.
1505 $helo_name
1507 The hostname given in HELO or EHLO command or empty string.
1508 $rbl_class
1510 The denylisted entity type: Client host, Helo command, Sender
1511 address, or Recipient address.
1512 $rbl_code
1514 The numerical SMTP response code, as specified with the
1515 maps_rbl_reject_code configuration parameter. Note: The numeri‐
1516 cal SMTP response code is required, and must appear at the start
1517 of the reply. With Postfix version 2.3 and later this informa‐
1518 tion may be followed by an RFC 3463 enhanced status code.
1519 $rbl_domain
1521 The RBL domain where $rbl_what is denylisted.
1522 $rbl_reason
1524 The reason why $rbl_what is denylisted, or an empty string.
1525 $rbl_what
1527 The entity that is denylisted (an IP address, a hostname, a do‐
1528 main name, or an email address whose domain was denylisted).
1529 $recipient
1531 The recipient address or <> in case of the null address.
1532 $recipient_domain
1534 The recipient domain or empty string.
1535 $recipient_name
1537 The recipient address localpart or <> in case of null address.
1538 $sender
1540 The sender address or <> in case of the null address.
1541 $sender_domain
1543 The sender domain or empty string.
1544 $sender_name
1546 The sender address localpart or <> in case of the null address.
1547 ${name?text}
1549 Expands to `text' if $name is not empty.
1550 ${name:text}
1552 Expands to `text' if $name is empty.
1553 Instead of $name you can also specify ${name} or $(name).
1555 Note: when an enhanced status code is specified in an RBL reply tem‐
1557 plate, it is subject to modification. The following transformations
1558 are needed when the same RBL reply template is used for client, helo,
1559 sender, or recipient access restrictions.
1560 • When rejecting a sender address, the Postfix SMTP server will
1562 transform a recipient DSN status (e.g., 4.1.1-4.1.6) into the
1563 corresponding sender DSN status, and vice versa.
1564 • When rejecting non-address information (such as the HELO command
1566 argument or the client hostname/address), the Postfix SMTP
1567 server will transform a sender or recipient DSN status into a
1568 generic non-address DSN status (e.g., 4.0.0).
1569
1571 The default per-transport upper limit on the number of in-memory recip‐
1572 ients. These limits take priority over the global qmgr_message_recipi‐
1573 ent_limit after the message has been assigned to the respective trans‐
1574 ports. See also default_extra_recipient_limit and qmgr_message_recipi‐
1575 ent_minimum.
1576 Use transport_recipient_limit to specify a transport-specific override,
1578 where transport is the master.cf name of the message delivery trans‐
1579 port.
1580
1582 The default per-transport maximum delay between recipients refills.
1583 When not all message recipients fit into the memory at once, keep load‐
1584 ing more of them at least once every this many seconds. This is used
1585 to make sure the recipients are refilled in timely manner even when
1586 $default_recipient_refill_limit is too high for too slow deliveries.
1587 Use transport_recipient_refill_delay to specify a transport-specific
1589 override, where transport is the master.cf name of the message delivery
1590 transport.
1591 This feature is available in Postfix 2.4 and later.
1593
1595 The default per-transport limit on the number of recipients refilled at
1596 once. When not all message recipients fit into the memory at once,
1597 keep loading more of them in batches of at least this many at a time.
1598 See also $default_recipient_refill_delay, which may result in recipient
1599 batches lower than this when this limit is too high for too slow deliv‐
1600 eries.
1601 Use transport_recipient_refill_limit to specify a transport-specific
1603 override, where transport is the master.cf name of the message delivery
1604 transport.
1605 This feature is available in Postfix 2.4 and later.
1607
1609 The default mail delivery transport and next-hop destination for desti‐
1610 nations that do not match $mydestination, $inet_interfaces, $proxy_in‐
1611 terfaces, $virtual_alias_domains, $virtual_mailbox_domains, or $re‐
1612 lay_domains. This information can be overruled with the sender_depen‐
1613 dent_default_transport_maps parameter and with the transport(5) table.
1614 In order of decreasing precedence, the nexthop destination is taken
1616 from $sender_dependent_default_transport_maps, $default_transport,
1617 $sender_dependent_relayhost_maps, $relayhost, or from the recipient do‐
1618 main.
1619 Specify a string of the form transport:nexthop, where transport is the
1621 name of a mail delivery transport defined in master.cf. The :nexthop
1622 destination is optional; its syntax is documented in the manual page of
1623 the corresponding delivery agent. In the case of SMTP or LMTP, specify
1624 one or more destinations separated by comma or whitespace (with Postfix
1625 3.5 and later).
1626 Example:
1628 default_transport = uucp:relayhostname
1630
1632 The default amount of delay that is inserted between individual message
1633 deliveries over the same message delivery transport, regardless of des‐
1634 tination. Specify a non-zero value to rate-limit those message deliver‐
1635 ies to at most one per $default_transport_rate_delay.
1636 Use transport_transport_rate_delay to specify a transport-specific
1638 override, where the initial transport is the master.cf name of the mes‐
1639 sage delivery transport.
1640 Example: throttle outbound SMTP mail to at most 3 deliveries per
1642 minute.
1643 /etc/postfix/main.cf:
1645 smtp_transport_rate_delay = 20s
1646 To enable the delay, specify a non-zero time value (an integral value
1648 plus an optional one-letter suffix that specifies the time unit).
1649 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
1651 The default time unit is s (seconds).
1652 NOTE: the delay is enforced by the queue manager.
1654 This feature is available in Postfix 3.1 and later.
1656
1658 The two default VERP delimiter characters. These are used when no ex‐
1659 plicit delimiters are specified with the SMTP XVERP command or with the
1660 "sendmail -V" command-line option. Specify characters that are allowed
1661 by the verp_delimiter_filter setting.
1662 This feature is available in Postfix 1.1 and later.
1664
1666 The numerical Postfix SMTP server response code when a remote SMTP
1667 client request is rejected by the "defer" restriction.
1668 Do not change this unless you have a complete understanding of RFC
1670 5321.
1671
1673 The name of the defer service. This service is implemented by the
1674 bounce(8) daemon and maintains a record of failed delivery attempts and
1675 generates non-delivery notifications.
1676 This feature is available in Postfix 2.0 and later.
1678
1680 The names of message delivery transports that should not deliver mail
1681 unless someone issues "sendmail -q" or equivalent. Specify zero or more
1682 names of mail delivery transports names that appear in the first field
1683 of master.cf.
1684 Example:
1686 defer_transports = smtp
1688
1690 The maximal number of digits after the decimal point when logging
1691 sub-second delay values. Specify a number in the range 0..6.
1692 Large delay values are rounded off to an integral number seconds; delay
1694 values below the delay_logging_resolution_limit are logged as "0", and
1695 delay values under 100s are logged with at most two-digit precision.
1696 The format of the "delays=a/b/c/d" logging is as follows:
1698 • a = time from message arrival to last active queue entry
1700 • b = time from last active queue entry to connection setup
1702 • c = time in connection setup, including DNS, EHLO and STARTTLS
1704 • d = time in message transmission
1706 This feature is available in Postfix 2.3 and later.
1708
1710 The recipient of postmaster notifications with the message headers of
1711 mail that cannot be delivered within $delay_warning_time time units.
1712 See also: delay_warning_time, notify_classes.
1714
1716 The time after which the sender receives a copy of the message headers
1717 of mail that is still queued. The confirm_delay_cleared parameter con‐
1718 trols sender notification when the delay clears up.
1719 To enable this feature, specify a non-zero time value (an integral
1721 value plus an optional one-letter suffix that specifies the time unit).
1722 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
1724 The default time unit is h (hours).
1725 See also: delay_notice_recipient, notify_classes, confirm_de‐
1727 lay_cleared.
1728
1730 The maximal number of attempts to acquire an exclusive lock on a mail‐
1731 box file or bounce(8) logfile.
1732
1734 The time between attempts to acquire an exclusive lock on a mailbox
1735 file or bounce(8) logfile.
1736 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
1738 The default time unit is s (seconds).
1739
1741 Make the queue manager's feedback algorithm verbose for performance
1742 analysis purposes.
1743 This feature is available in Postfix 2.5 and later.
1745
1747 Automatically detect 8BITMIME body content by looking at Content-Trans‐
1748 fer-Encoding: message headers; historically, this behavior was
1749 hard-coded to be "always on".
1750 This feature is available in Postfix 2.5 and later.
1752
1754 Disable DNS lookups in the Postfix SMTP and LMTP clients. When dis‐
1755 abled, hosts are looked up with the getaddrinfo() system library rou‐
1756 tine which normally also looks in /etc/hosts. As of Postfix 2.11, this
1757 parameter is deprecated; use smtp_dns_support_level instead.
1758 DNS lookups are enabled by default.
1760
1762 Turn off MIME processing while receiving mail. This means that no spe‐
1763 cial treatment is given to Content-Type: message headers, and that all
1764 text after the initial message headers is considered to be part of the
1765 message body.
1766 This feature is available in Postfix 2.0 and later.
1768 Mime input processing is enabled by default, and is needed in order to
1770 recognize MIME headers in message content.
1771
1773 Disable the conversion of 8BITMIME format to 7BIT format. Mime output
1774 conversion is needed when the destination does not advertise 8BITMIME
1775 support.
1776 This feature is available in Postfix 2.0 and later.
1778
1780 Disable sending one bounce report per recipient.
1781 The default, one per recipient, is what ezmlm needs.
1783 This feature is available in Postfix 1.1 and later.
1785
1787 Disable the SMTP VRFY command. This stops some techniques used to har‐
1788 vest email addresses.
1789 Example:
1791 disable_vrfy_command = no
1793
1795 Enable a workaround for future libc incompatibility. The Postfix imple‐
1796 mentation of RFC 2308 negative reply caching relies on the promise that
1797 res_query() and res_search() invoke res_send(), which returns the
1798 server response in an application buffer even if the requested record
1799 does not exist. If this promise is broken, specify "yes" to enable a
1800 workaround for DNS reputation lookups.
1801 This feature is available in Postfix 3.1 and later.
1803
1805 A debugging aid to artificially delay DNS responses.
1806 This feature is available in Postfix 2.8.
1808
1810 The name of the dnsblog(8) service entry in master.cf. This service
1811 performs DNS allow/denylist lookups.
1812 This feature is available in Postfix 2.8 and later.
1814
1816 The DNS query type (default: "ns") and DNS query name (default: ".")
1817 that Postfix may use to determine whether DNSSEC validation is avail‐
1818 able.
1819 Background: DNSSEC validation is needed for Postfix DANE support; this
1821 ensures that Postfix receives TLSA records with secure TLS server cer‐
1822 tificate info. When DNSSEC validation is unavailable, mail deliveries
1823 using opportunistic DANE will not be protected by server certificate
1824 info in TLSA records, and mail deliveries using mandatory DANE will not
1825 be made at all.
1826 By default, a Postfix process will send a DNSSEC probe after 1) the
1828 process made a DNS query that requested DNSSEC validation, 2) the
1829 process did not receive a DNSSEC validated response to this query or to
1830 an earlier query, and 3) the process did not already send a DNSSEC
1831 probe.
1832 When the DNSSEC probe has no response, or when the response is not
1834 DNSSEC validated, Postfix logs a warning that DNSSEC validation may be
1835 unavailable.
1836 Example:
1838 warning: DNSSEC validation may be unavailable
1840 warning: reason: dnssec_probe 'ns:.' received a response that is not DNSSEC validated
1841 warning: reason: dnssec_probe 'ns:.' received no response: Server failure
1842 Possible reasons why DNSSEC validation may be unavailable:
1844 • The local /etc/resolv.conf file specifies a DNS resolver that
1846 does not validate DNSSEC signatures (that's $queue_direc‐
1847 tory/etc/resolv.conf when a Postfix daemon runs in a chroot
1848 jail).
1849 • The local system library does not pass on the "DNSSEC validated"
1851 bit to Postfix, or Postfix does not know how to ask the library
1852 to do that.
1853 By default, the DNSSEC probe asks for the DNS root zone NS records, be‐
1855 cause resolvers should always have that information cached. If Postfix
1856 runs on a network where the DNS root zone is not reachable, specify a
1857 different probe, or specify an empty dnssec_probe value to disable the
1858 feature.
1859 This feature is available in Postfix 3.6 and later. It was backported
1861 to Postfix versions 3.5.9, 3.4.19, 3.3.16. 3.2.21.
1862
1864 Don't remove queue files and save them to the "saved" mail queue. This
1865 is a debugging aid. To inspect the envelope information and content of
1866 a Postfix queue file, use the postcat(1) command.
1867
1869 The sender address of postmaster notifications that are generated by
1870 the mail system. All mail to this address is silently discarded, in or‐
1871 der to terminate mail bounce loops.
1872
1874 The maximal number of addresses remembered by the address duplicate
1875 filter for aliases(5) or virtual(5) alias expansion, or for showq(8)
1876 queue displays.
1877
1879 The sender_dependent_default_transport_maps search string that will be
1880 used instead of the null sender address.
1881 This feature is available in Postfix 2.7 and later.
1883
1885 The lookup key to be used in local_login_sender_maps tables, instead of
1886 the null sender address.
1887 This feature is available in Postfix 3.6 and later.
1889
1891 The recipient of mail addressed to the null address. Postfix does not
1892 accept such addresses in SMTP commands, but they may still be created
1893 locally as the result of configuration or software error.
1894
1896 The sender_dependent_relayhost_maps search string that will be used in‐
1897 stead of the null sender address.
1898 This feature is available in Postfix 2.5 and later. With earlier ver‐
1900 sions, sender_dependent_relayhost_maps lookups were skipped for the
1901 null sender address.
1902
1904 Report mail delivery errors to the address specified with the non-stan‐
1905 dard Errors-To: message header, instead of the envelope sender address
1906 (this feature is removed with Postfix version 2.2, is turned off by de‐
1907 fault with Postfix version 2.1, and is always turned on with older
1908 Postfix versions).
1909
1911 Enable 'transitional' compatibility between IDNA2003 and IDNA2008, when
1912 converting UTF-8 domain names to/from the ASCII form that is used for
1913 DNS lookups. Specify "yes" for compatibility with Postfix <= 3.1 (not
1914 recommended). This affects the conversion of domain names that contain
1915 for example the German sz and the Greek zeta. See http://uni‐
1916 code.org/cldr/utility/idna.jsp for more examples.
1917 This feature is available in Postfix 3.2 and later.
1919
1921 Enable long, non-repeating, queue IDs (queue file names). The benefit
1922 of non-repeating names is simpler logfile analysis and easier queue mi‐
1923 gration (there is no need to run "postsuper" to change queue file names
1924 that don't match their message file inode number).
1925 Note: see below for how to convert long queue file names to Postfix <=
1927 2.8.
1928 Changing the parameter value to "yes" has the following effects:
1930 • Existing queue file names are not affected.
1932 • New queue files are created with names such as 3Pt2mN2VXxznjll.
1934 These are encoded in a 52-character alphabet that contains dig‐
1935 its (0-9), upper-case letters (B-Z) and lower-case letters
1936 (b-z). For safety reasons the vowels (AEIOUaeiou) are excluded
1937 from the alphabet. The name format is: 6 or more characters for
1938 the time in seconds, 4 characters for the time in microseconds,
1939 the 'z'; the remainder is the file inode number encoded in the
1940 first 51 characters of the 52-character alphabet.
1941 • New messages have a Message-ID header with queueID@myhostname.
1943 • The mailq (postqueue -p) output has a wider Queue ID column.
1945 The number of whitespace-separated fields is not changed.
1946 • The hash_queue_depth algorithm uses the first characters of the
1948 queue file creation time in microseconds, after conversion into
1949 hexadecimal representation. This produces the same queue hashing
1950 behavior as if the queue file name was created with "en‐
1951 able_long_queue_ids = no".
1952 Changing the parameter value to "no" has the following effects:
1954 • Existing long queue file names are renamed to the short form
1956 (while running "postfix reload" or "postsuper").
1957 • New queue files are created with names such as C3CD21F3E90 from
1959 a hexadecimal alphabet that contains digits (0-9) and upper-case
1960 letters (A-F). The name format is: 5 characters for the time in
1961 microseconds; the remainder is the file inode number.
1962 • New messages have a Message-ID header with YYYYMMDDHH‐
1964 MMSS.queueid@myhostname, where YYYYMMDDHHMMSS are the year,
1965 month, day, hour, minute and second.
1966 • The mailq (postqueue -p) output has the same format as with
1968 Postfix <= 2.8.
1969 • The hash_queue_depth algorithm uses the first characters of the
1971 queue file name, with the hexadecimal representation of the file
1972 creation time in microseconds.
1973 Before migration to Postfix <= 2.8, the following commands are required
1975 to convert long queue file names into short names:
1976 # postfix stop
1978 # postconf enable_long_queue_ids=no
1979 # postsuper
1980 Repeat the postsuper command until it reports no more queue file name
1982 changes.
1983 This feature is available in Postfix 2.9 and later.
1985
1987 Enable support for the original recipient address after an address is
1988 rewritten to a different address (for example with aliasing or with
1989 canonical mapping).
1990 The original recipient address is used as follows:
1992 Final delivery
1994 With "enable_original_recipient = yes", the original recipient
1995 address is stored in the X-Original-To message header. This
1996 header may be used to distinguish between different recipients
1997 that share the same mailbox.
1998 Recipient deduplication
2000 With "enable_original_recipient = yes", the cleanup(8) daemon
2001 performs duplicate recipient elimination based on the content of
2002 (original recipient, maybe-rewritten recipient) pairs. Other‐
2003 wise, the cleanup(8) daemon performs duplicate recipient elimi‐
2004 nation based only on the maybe-rewritten recipient address.
2005 Note: with Postfix <= 3.2 the "setting enable_original_recipient = no"
2007 breaks address verification for addresses that are aliased or otherwise
2008 rewritten (Postfix is unable to store the address verification result
2009 under the original probe destination address; instead, it can store the
2010 result only under the rewritten address).
2011 This feature is available in Postfix 2.1 and later. Postfix version 2.0
2013 behaves as if this parameter is always set to yes. Postfix versions
2014 before 2.0 have no support for the original recipient address.
2015
2017 Enable non-delivery, success, and delay notifications that link to the
2018 original message by including a References: and In-Reply-To: header
2019 with the original Message-ID value. There are advantages and disadvan‐
2020 tages to consider.
2021 advantage
2023 This allows mail readers to present a delivery status notifica‐
2024 tion in the same email thread as the original message.
2025 disadvantage
2027 This makes it easy for users to mistakenly delete the whole
2028 email thread (all related messages), instead of deleting only
2029 the non-delivery notification.
2030 This feature is available in Postfix 3.6 and later.
2032
2034 The recipient of postmaster notifications about mail delivery problems
2035 that are caused by policy, resource, software or protocol errors.
2036 These notifications are enabled with the notify_classes parameter.
2037
2039 The name of the error(8) pseudo delivery agent. This service always re‐
2040 turns mail as undeliverable.
2041 This feature is available in Postfix 2.0 and later.
2043
2045 Restrict the characters that the local(8) delivery agent allows in
2046 $name expansions of $command_execution_directory. Characters outside
2047 the allowed set are replaced by underscores.
2048 This feature is available in Postfix 2.2 and later.
2050
2052 When delivering to an alias "aliasname" that has an "owner-aliasname"
2053 companion alias, set the envelope sender address to the expansion of
2054 the "owner-aliasname" alias. Normally, Postfix sets the envelope
2055 sender address to the name of the "owner-aliasname" alias.
2056
2058 The list of environment variables that a Postfix process will export to
2059 non-Postfix processes. The TZ variable is needed for sane time keeping
2060 on System-V-ish systems.
2061 Specify a list of names and/or name=value pairs, separated by white‐
2063 space or comma. Specify "{ name=value }" to protect whitespace or comma
2064 in parameter values (whitespace after the opening "{" and before the
2065 closing "}" is ignored). The form name=value is supported with Postfix
2066 version 2.1 and later; the use of {} is supported with Postfix 3.0 and
2067 later.
2068 Example:
2070 export_environment = TZ PATH=/bin:/usr/bin
2072
2074 The maximal number of recipient addresses that Postfix will extract
2075 from message headers when mail is submitted with "sendmail -t".
2076 This feature was removed in Postfix version 2.1.
2078
2080 Optional list of relay hosts for SMTP destinations that can't be found
2081 or that are unreachable. With Postfix 2.3 this parameter is renamed to
2082 smtp_fallback_relay.
2083 By default, mail is returned to the sender when a destination is not
2085 found, and delivery is deferred when a destination is unreachable.
2086 The fallback relays must be SMTP destinations. Specify a domain, host,
2088 host:port, [host]:port, [address] or [address]:port; the form [host]
2089 turns off MX lookups. If you specify multiple SMTP destinations, Post‐
2090 fix will try them in the specified order.
2091 Note: before Postfix 2.2, do not use the fallback_relay feature when
2093 relaying mail for a backup or primary MX domain. Mail would loop be‐
2094 tween the Postfix MX host and the fallback_relay host when the final
2095 destination is unavailable.
2096 • In main.cf specify "relay_transport = relay",
2098 • In master.cf specify "-o fallback_relay =" (i.e., empty) at the
2100 end of the relay entry.
2101 • In transport maps, specify "relay:nexthop..." as the right-hand
2103 side for backup or primary MX domain entries.
2104 Postfix version 2.2 and later will not use the fallback_relay feature
2106 for destinations that it is MX host for.
2107
2109 Optional message delivery transport that the local(8) delivery agent
2110 should use for names that are not found in the aliases(5) or UNIX pass‐
2111 word database.
2112 The precedence of local(8) delivery features from high to low is:
2114 aliases, .forward files, mailbox_transport_maps, mailbox_transport,
2115 mailbox_command_maps, mailbox_command, home_mailbox, mail_spool_direc‐
2116 tory, fallback_transport_maps, fallback_transport and luser_relay.
2117
2119 Optional lookup tables with per-recipient message delivery transports
2120 for recipients that the local(8) delivery agent could not find in the
2121 aliases(5) or UNIX password database.
2122 The precedence of local(8) delivery features from high to low is:
2124 aliases, .forward files, mailbox_transport_maps, mailbox_transport,
2125 mailbox_command_maps, mailbox_command, home_mailbox, mail_spool_direc‐
2126 tory, fallback_transport_maps, fallback_transport and luser_relay.
2127 For safety reasons, this feature does not allow $number substitutions
2129 in regular expression maps.
2130 This feature is available in Postfix 2.3 and later.
2132
2134 Optional list of destinations that are eligible for per-destination
2135 logfiles with mail that is queued to those destinations.
2136 By default, Postfix maintains "fast flush" logfiles only for destina‐
2138 tions that the Postfix SMTP server is willing to relay to (i.e. the de‐
2139 fault is: "fast_flush_domains = $relay_domains"; see the relay_domains
2140 parameter in the postconf(5) manual).
2141 Specify a list of hosts or domains, "/file/name" patterns or "type:ta‐
2143 ble" lookup tables, separated by commas and/or whitespace. Continue
2144 long lines by starting the next line with whitespace. A "/file/name"
2145 pattern is replaced by its contents; a "type:table" lookup table is
2146 matched when the domain or its parent domain appears as lookup key.
2147 Pattern matching of domain names is controlled by the presence or ab‐
2149 sence of "fast_flush_domains" in the parent_domain_matches_subdomains
2150 parameter value.
2151 Specify "fast_flush_domains =" (i.e., empty) to disable the feature al‐
2153 together.
2154
2156 The time after which an empty per-destination "fast flush" logfile is
2157 deleted.
2158 You can specify the time as a number, or as a number followed by a let‐
2160 ter that indicates the time unit: s=seconds, m=minutes, h=hours,
2161 d=days, w=weeks. The default time unit is days.
2162
2164 The time after which a non-empty but unread per-destination "fast
2165 flush" logfile needs to be refreshed. The contents of a logfile are
2166 refreshed by requesting delivery of all messages listed in the logfile.
2167 You can specify the time as a number, or as a number followed by a let‐
2169 ter that indicates the time unit: s=seconds, m=minutes, h=hours,
2170 d=days, w=weeks. The default time unit is hours.
2171
2173 Force specific internal tests to fail, to test the handling of errors
2174 that are difficult to reproduce otherwise.
2175
2177 The name of the flush(8) service. This service maintains per-destina‐
2178 tion logfiles with the queue file names of mail that is queued for
2179 those destinations.
2180 This feature is available in Postfix 2.0 and later.
2182
2184 The maximal number of attempts to fork() a child process.
2185
2187 The delay between attempts to fork() a child process.
2188 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
2190 The default time unit is s (seconds).
2191
2193 Restrict the characters that the local(8) delivery agent allows in
2194 $name expansions of $forward_path. Characters outside the allowed set
2195 are replaced by underscores.
2196
2198 The local(8) delivery agent search list for finding a .forward file
2199 with user-specified delivery methods. The first file that is found is
2200 used.
2201 The forward_path value is not subject to Postfix configuration parame‐
2203 ter $name expansion. Instead, the following $name expansions are done
2204 on forward_path before the search actually happens. The result of
2205 $name expansion is filtered with the character set that is specified
2206 with the forward_expansion_filter parameter.
2207 $user The recipient's username.
2209 $shell The recipient's login shell pathname.
2211 $home The recipient's home directory.
2213 $recipient
2215 The full recipient address.
2216 $extension
2218 The optional recipient address extension.
2219 $domain
2221 The recipient domain.
2222 $local The entire recipient localpart.
2224 $recipient_delimiter
2226 The address extension delimiter that was found in the recipient
2227 address (Postfix 2.11 and later), or the system-wide recipient
2228 address extension delimiter (Postfix 2.10 and earlier).
2229 ${name?value}
2231 Expands to value when $name is non-empty.
2232 ${name:value}
2234 Expands to value when $name is empty.
2235 Instead of $name you can also specify ${name} or $(name).
2237 Examples:
2239 forward_path = /var/forward/$user
2241 forward_path =
2242 /var/forward/$user/.forward$recipient_delimiter$extension,
2243 /var/forward/$user/.forward
2244
2246 Update the local(8) delivery agent's idea of the Delivered-To: address
2247 (see prepend_delivered_header) only once, at the start of a delivery
2248 attempt; do not update the Delivered-To: address while expanding
2249 aliases or .forward files.
2250 This feature is available in Postfix 2.3 and later. With older Postfix
2252 releases, the behavior is as if this parameter is set to "no". The old
2253 setting can be expensive with deeply nested aliases or .forward files.
2254 When an alias or .forward file changes the Delivered-To: address, it
2255 ties up one queue file and one cleanup process instance while mail is
2256 being forwarded.
2257
2259 The number of subdirectory levels for queue directories listed with the
2260 hash_queue_names parameter. Queue hashing is implemented by creating
2261 one or more levels of directories with one-character names. Origi‐
2262 nally, these directory names were equal to the first characters of the
2263 queue file name, with the hexadecimal representation of the file cre‐
2264 ation time in microseconds.
2265 With long queue file names, queue hashing produces the same results as
2267 with short names. The file creation time in microseconds is converted
2268 into hexadecimal form before the result is used for queue hashing. The
2269 base 16 encoding gives finer control over the number of subdirectories
2270 than is possible with the base 52 encoding of long queue file names.
2271 After changing the hash_queue_names or hash_queue_depth parameter, exe‐
2273 cute the command "postfix reload".
2274
2276 The names of queue directories that are split across multiple subdirec‐
2277 tory levels.
2278 Before Postfix version 2.2, the default list of hashed queues was sig‐
2280 nificantly larger. Claims about improvements in file system technology
2281 suggest that hashing of the incoming and active queues is no longer
2282 needed. Fewer hashed directories speed up the time needed to restart
2283 Postfix.
2284 After changing the hash_queue_names or hash_queue_depth parameter, exe‐
2286 cute the command "postfix reload".
2287
2289 The maximal number of address tokens are allowed in an address message
2290 header. Information that exceeds the limit is discarded. The limit is
2291 enforced by the cleanup(8) server.
2292
2294 Optional lookup tables for content inspection of primary non-MIME mes‐
2295 sage headers, as specified in the header_checks(5) manual page.
2296
2298 The format of the Postfix-generated From: header. This setting affects
2299 the appearance of 'full name' information when a local program such as
2300 /bin/mail submits a message without From: header through the Postfix
2301 sendmail(1) command.
2302 Specify one of the following:
2304 standard (default)
2306 Produce a header formatted as "From: name <address>". This is
2307 the default as of Postfix 3.3.
2308 obsolete
2310 Produce a header formatted as "From: address (name)". This is
2311 the behavior prior to Postfix 3.3.
2312 Notes:
2314 • Postfix generates the format "From: address" when name informa‐
2316 tion is unavailable or the envelope sender address is empty.
2317 This is the same behavior as prior to Postfix 3.3.
2318 • In the standard form, the name will be quoted if it contains
2320 specials as defined in RFC 5322, or the "!%" address operators.
2321 • The Postfix sendmail(1) command gets name information from the
2323 -F command-line option, from the NAME environment variable, or
2324 from the UNIX password file.
2325 This feature is available in Postfix 3.3 and later.
2327
2329 The maximal amount of memory in bytes for storing a message header. If
2330 a header is larger, the excess is discarded. The limit is enforced by
2331 the cleanup(8) server.
2332
2334 Log warnings about problematic configuration settings, and provide
2335 helpful suggestions.
2336 This feature is available in Postfix 2.0 and later.
2338
2340 Optional pathname of a mailbox file relative to a local(8) user's home
2341 directory.
2342 Specify a pathname ending in "/" for qmail-style delivery.
2344 The precedence of local(8) delivery features from high to low is:
2346 aliases, .forward files, mailbox_transport_maps, mailbox_transport,
2347 mailbox_command_maps, mailbox_command, home_mailbox, mail_spool_direc‐
2348 tory, fallback_transport_maps, fallback_transport and luser_relay.
2349 Examples:
2351 home_mailbox = Mailbox
2353 home_mailbox = Maildir/
2354
2356 The maximal number of Received: message headers that is allowed in the
2357 primary message headers. A message that exceeds the limit is bounced,
2358 in order to stop a mailer loop.
2359
2361 The location of Postfix HTML files that describe how to build, config‐
2362 ure or operate a specific Postfix subsystem or feature.
2363
2365 Ignore DNS MX lookups that produce no response. By default, the Post‐
2366 fix SMTP client defers delivery and tries again after some delay. This
2367 behavior is required by the SMTP standard.
2368 Specify "ignore_mx_lookup_error = yes" to force a DNS A record lookup
2370 instead. This violates the SMTP standard and can result in mis-delivery
2371 of mail.
2372
2374 The list of environment parameters that a privileged Postfix process
2375 will import from a non-Postfix parent process, or name=value environ‐
2376 ment overrides. Unprivileged utilities will enforce the name=value
2377 overrides, but otherwise will not change their process environment.
2378 Examples of relevant parameters:
2379 TZ May be needed for sane time keeping on most System-V-ish sys‐
2381 tems.
2382 DISPLAY
2384 Needed for debugging Postfix daemons with an X-windows debugger.
2385 XAUTHORITY
2387 Needed for debugging Postfix daemons with an X-windows debugger.
2388 MAIL_CONFIG
2390 Needed to make "postfix -c" work.
2391 Specify a list of names and/or name=value pairs, separated by white‐
2393 space or comma. Specify "{ name=value }" to protect whitespace or comma
2394 in parameter values (whitespace after the opening "{" and before the
2395 closing "}" is ignored). The form name=value is supported with Postfix
2396 version 2.1 and later; the use of {} is supported with Postfix 3.0 and
2397 later.
2398
2400 Time to pause before accepting a new message, when the message arrival
2401 rate exceeds the message delivery rate. This feature is turned on by
2402 default (it's disabled on SCO UNIX due to an SCO bug).
2403 With the default 100 Postfix SMTP server process limit, "in_flow_delay
2405 = 1s" limits the mail inflow to 100 messages per second above the num‐
2406 ber of messages delivered per second.
2407 Specify 0 to disable the feature. Valid delays are 0..10.
2409
2411 The network interface addresses that this mail system receives mail on.
2412 Specify "all" to receive mail on all network interfaces (default), and
2413 "loopback-only" to receive mail on loopback network interfaces only
2414 (Postfix version 2.2 and later). The parameter also controls delivery
2415 of mail to user@[ip.address].
2416 Note 1: you need to stop and start Postfix when this parameter changes.
2418 Note 2: address information may be enclosed inside [], but this form is
2420 not required here.
2421 When inet_interfaces specifies just one IPv4 and/or IPv6 address that
2423 is not a loopback address, the Postfix SMTP client will use this ad‐
2424 dress as the IP source address for outbound mail. Support for IPv6 is
2425 available in Postfix version 2.2 and later.
2426 On a multi-homed firewall with separate Postfix instances listening on
2428 the "inside" and "outside" interfaces, this can prevent each instance
2429 from being able to reach remote SMTP servers on the "other side" of the
2430 firewall. Setting smtp_bind_address to 0.0.0.0 avoids the potential
2431 problem for IPv4, and setting smtp_bind_address6 to :: solves the prob‐
2432 lem for IPv6.
2433 A better solution for multi-homed firewalls is to leave inet_interfaces
2435 at the default value and instead use explicit IP addresses in the mas‐
2436 ter.cf SMTP server definitions. This preserves the Postfix SMTP
2437 client's loop detection, by ensuring that each side of the firewall
2438 knows that the other IP address is still the same host. Setting
2439 $inet_interfaces to a single IPv4 and/or IPV6 address is primarily use‐
2440 ful with virtual hosting of domains on secondary IP addresses, when
2441 each IP address serves a different domain (and has a different $myhost‐
2442 name setting).
2443 See also the proxy_interfaces parameter, for network addresses that are
2445 forwarded to Postfix by way of a proxy or address translator.
2446 Examples:
2448 inet_interfaces = all (DEFAULT)
2450 inet_interfaces = loopback-only (Postfix version 2.2 and later)
2451 inet_interfaces = 127.0.0.1
2452 inet_interfaces = 127.0.0.1, [::1] (Postfix version 2.2 and later)
2453 inet_interfaces = 192.168.1.2, 127.0.0.1
2454
2456 The Internet protocols Postfix will attempt to use when making or ac‐
2457 cepting connections. Specify one or more of "ipv4" or "ipv6", separated
2458 by whitespace or commas. The form "all" is equivalent to "ipv4, ipv6"
2459 or "ipv4", depending on whether the operating system implements IPv6.
2460 With Postfix 2.8 and earlier the default is "ipv4". For backwards com‐
2462 patibility with these releases, the Postfix 2.9 and later upgrade pro‐
2463 cedure appends an explicit "inet_protocols = ipv4" setting to main.cf
2464 when no explicit setting is present. This compatibility workaround will
2465 be phased out as IPv6 deployment becomes more common.
2466 This feature is available in Postfix 2.2 and later.
2468 Note: you MUST stop and start Postfix after changing this parameter.
2470 On systems that pre-date IPV6_V6ONLY support (RFC 3493), an IPv6 server
2472 will also accept IPv4 connections, even when IPv4 is turned off with
2473 the inet_protocols parameter. On systems with IPV6_V6ONLY support,
2474 Postfix will use separate server sockets for IPv6 and IPv4, and each
2475 will accept only connections for the corresponding protocol.
2476 When IPv4 support is enabled via the inet_protocols parameter, Postfix
2478 will look up DNS type A records, and will convert IPv4-in-IPv6 client
2479 IP addresses (::ffff:1.2.3.4) to their original IPv4 form (1.2.3.4).
2480 The latter is needed on hosts that pre-date IPV6_V6ONLY support (RFC
2481 3493).
2482 When IPv6 support is enabled via the inet_protocols parameter, Postfix
2484 will do DNS type AAAA record lookups.
2485 When both IPv4 and IPv6 support are enabled, the Postfix SMTP client
2487 will choose the protocol as specified with the smtp_address_preference
2488 parameter. Postfix versions before 2.8 attempt to connect via IPv6 be‐
2489 fore attempting to use IPv4.
2490 Examples:
2492 inet_protocols = ipv4
2494 inet_protocols = all (DEFAULT)
2495 inet_protocols = ipv6
2496 inet_protocols = ipv4, ipv6
2497
2499 The email address form that will be used in non-debug logging (info,
2500 warning, etc.). As of Postfix 3.5 when an address localpart contains
2501 spaces or other special characters, the localpart will be quoted, for
2502 example:
2503 from=<"name with spaces"@example.com>
2505 Older Postfix versions would log the internal (unquoted) form:
2507 from=<name with spaces@example.com>
2509 The external and internal forms are identical for the vast majority of
2511 email addresses that contain no spaces or other special characters in
2512 the localpart.
2513 The logging in external form is consistent with the address form that
2515 Postfix 3.2 and later prefer for most table lookups. This is therefore
2516 the more useful form for non-debug logging.
2517 Specify "info_log_address_format = internal" for backwards compatibil‐
2519 ity.
2520 Postfix uses the unquoted form internally, because an attacker can
2522 specify an email address in different forms by playing games with
2523 quotes and backslashes. An attacker should not be able to use such
2524 games to circumvent Postfix access policies.
2525 This feature is available in Postfix 3.5 and later.
2527
2529 The initial per-destination concurrency level for parallel delivery to
2530 the same destination. With per-destination recipient limit > 1, a des‐
2531 tination is a domain, otherwise it is a recipient.
2532 Use transport_initial_destination_concurrency to specify a trans‐
2534 port-specific override, where transport is the master.cf name of the
2535 message delivery transport (Postfix 2.5 and later).
2536 Warning: with concurrency of 1, one bad message can be enough to block
2538 all mail to a site.
2539
2541 What categories of Postfix-generated mail are subject to before-queue
2542 content inspection by non_smtpd_milters, header_checks and body_checks.
2543 Specify zero or more of the following, separated by whitespace or
2544 comma.
2545 bounce Inspect the content of delivery status notifications.
2547 notify Inspect the content of postmaster notifications by the smtp(8)
2549 and smtpd(8) processes.
2550 NOTE: It's generally not safe to enable content inspection of Post‐
2552 fix-generated email messages. The user is warned.
2553 This feature is available in Postfix 2.3 and later.
2555
2557 The numerical Postfix SMTP server response code when the client HELO or
2558 EHLO command parameter is rejected by the reject_invalid_helo_hostname
2559 restriction.
2560 Do not change this unless you have a complete understanding of RFC
2562 5321.
2563
2565 The time after which a client closes an idle internal communication
2566 channel. The purpose is to allow Postfix daemon processes to terminate
2567 voluntarily after they become idle. This is used, for example, by the
2568 Postfix address resolving and rewriting clients.
2569 With Postfix 2.4 the default value was reduced from 100s to 5s.
2571 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
2573 The default time unit is s (seconds).
2574
2576 The time limit for sending or receiving information over an internal
2577 communication channel. The purpose is to break out of deadlock situa‐
2578 tions. If the time limit is exceeded the software aborts with a fatal
2579 error.
2580 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
2582 The default time unit is s (seconds).
2583
2585 The time after which a client closes an active internal communication
2586 channel. The purpose is to allow Postfix daemon processes to terminate
2587 voluntarily after reaching their client limit. This is used, for exam‐
2588 ple, by the Postfix address resolving and rewriting clients.
2589 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
2591 The default time unit is s (seconds).
2592 This feature is available in Postfix 2.1 and later.
2594
2596 sion=587)
2597 Optional setting that avoids lookups in the services(5) database. This
2598 feature was implemented to address inconsistencies in the name of the
2599 port "465" service. The ABNF is:
2600 known_tcp_ports = empty | name-to-port *("," name-to-port)
2602 name-to-port = 1*(service-name "=') port-number
2603 Whitespace is optional but it cannot appear inside a service name or
2605 port number.
2606 This feature is available in Postfix 3.6 and later.
2608
2610 Upon input, long lines are chopped up into pieces of at most this
2611 length; upon delivery, long lines are reconstructed.
2612
2614 The initial OpenLDAP LMDB database size limit in bytes. Each time a
2615 database becomes full, its size limit is doubled.
2616 This feature is available in Postfix 2.11 and later.
2618
2620 The LMTP-specific version of the smtp_address_preference configuration
2621 parameter. See there for details.
2622 This feature is available in Postfix 2.8 and later.
2624
2626 The LMTP-specific version of the smtp_address_verify_target configura‐
2627 tion parameter. See there for details.
2628 This feature is available in Postfix 3.0 and later.
2630
2632 When a remote LMTP server announces no DSN support, assume that the
2633 server performs final delivery, and send "delivered" delivery status
2634 notifications instead of "relayed". The default setting is backwards
2635 compatible to avoid the infinitesimal possibility of breaking existing
2636 LMTP-based content filters.
2637
2639 The LMTP-specific version of the smtp_balance_inet_protocols configura‐
2640 tion parameter. See there for details.
2641 This feature is available in Postfix 3.3 and later.
2643
2645 The LMTP-specific version of the smtp_bind_address configuration param‐
2646 eter. See there for details.
2647 This feature is available in Postfix 2.3 and later.
2649
2651 The LMTP-specific version of the smtp_bind_address6 configuration pa‐
2652 rameter. See there for details.
2653 This feature is available in Postfix 2.3 and later.
2655
2657 The LMTP-specific version of the smtp_body_checks configuration parame‐
2658 ter. See there for details.
2659 This feature is available in Postfix 2.5 and later.
2661
2663 Keep Postfix LMTP client connections open for up to $max_idle seconds.
2664 When the LMTP client receives a request for the same connection the
2665 connection is reused.
2666 This parameter is available in Postfix version 2.2 and earlier. With
2668 Postfix version 2.3 and later, see lmtp_connection_cache_on_demand,
2669 lmtp_connection_cache_destinations, or lmtp_connection_re‐
2670 use_time_limit.
2671 The effectiveness of cached connections will be determined by the num‐
2673 ber of remote LMTP servers in use, and the concurrency limit specified
2674 for the Postfix LMTP client. Cached connections are closed under any of
2675 the following conditions:
2676 • The Postfix LMTP client idle time limit is reached. This limit
2678 is specified with the Postfix max_idle configuration parameter.
2679 • A delivery request specifies a different destination than the
2681 one currently cached.
2682 • The per-process limit on the number of delivery requests is
2684 reached. This limit is specified with the Postfix max_use con‐
2685 figuration parameter.
2686 • Upon the onset of another delivery request, the remote LMTP
2688 server associated with the current session does not respond to
2689 the RSET command.
2690 Most of these limitations have been with the Postfix a connection cache
2692 that is shared among multiple LMTP client programs.
2693
2695 The LMTP-specific version of the smtp_cname_overrides_servername con‐
2696 figuration parameter. See there for details.
2697 This feature is available in Postfix 2.3 and later.
2699
2701 The Postfix LMTP client time limit for completing a TCP connection, or
2702 zero (use the operating system built-in time limit). When no connec‐
2703 tion can be made within the deadline, the LMTP client tries the next
2704 address on the mail exchanger list.
2705 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
2707 The default time unit is s (seconds).
2708 Example:
2710 lmtp_connect_timeout = 30s
2712
2714 The LMTP-specific version of the smtp_connection_cache_destinations
2715 configuration parameter. See there for details.
2716 This feature is available in Postfix 2.3 and later.
2718
2720 The LMTP-specific version of the smtp_connection_cache_on_demand con‐
2721 figuration parameter. See there for details.
2722 This feature is available in Postfix 2.3 and later.
2724
2726 The LMTP-specific version of the smtp_connection_cache_time_limit con‐
2727 figuration parameter. See there for details.
2728 This feature is available in Postfix 2.3 and later.
2730
2732 The LMTP-specific version of the smtp_connection_reuse_count_limit con‐
2733 figuration parameter. See there for details.
2734 This feature is available in Postfix 2.11 and later.
2736
2738 The LMTP-specific version of the smtp_connection_reuse_time_limit con‐
2739 figuration parameter. See there for details.
2740 This feature is available in Postfix 2.3 and later.
2742
2744 The Postfix LMTP client time limit for sending the LMTP ".", and for
2745 receiving the remote LMTP server response. When no response is re‐
2746 ceived within the deadline, a warning is logged that the mail may be
2747 delivered multiple times.
2748 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
2750 The default time unit is s (seconds).
2751
2753 The Postfix LMTP client time limit for sending the LMTP DATA command,
2754 and for receiving the remote LMTP server response.
2755 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
2757 The default time unit is s (seconds).
2758
2760 The Postfix LMTP client time limit for sending the LMTP message con‐
2761 tent. When the connection stalls for more than $lmtp_data_xfer_timeout
2762 the LMTP client terminates the transfer.
2763 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
2765 The default time unit is s (seconds).
2766
2768 The LMTP-specific version of the smtp_defer_if_no_mx_address_found con‐
2769 figuration parameter. See there for details.
2770 This feature is available in Postfix 2.3 and later.
2772
2774 The LMTP-specific version of the smtp_delivery_status_filter configura‐
2775 tion parameter. See there for details.
2776 This feature is available in Postfix 3.0 and later.
2778
2780 rency_limit)
2781 The maximal number of parallel deliveries to the same destination via
2782 the lmtp message delivery transport. This limit is enforced by the
2783 queue manager. The message delivery transport name is the first field
2784 in the entry in the master.cf file.
2785
2787 ent_limit)
2788 The maximal number of recipients per message for the lmtp message de‐
2789 livery transport. This limit is enforced by the queue manager. The mes‐
2790 sage delivery transport name is the first field in the entry in the
2791 master.cf file.
2792 Setting this parameter to a value of 1 changes the meaning of lmtp_des‐
2794 tination_concurrency_limit from concurrency per domain into concurrency
2795 per recipient.
2796
2798 Lookup tables, indexed by the remote LMTP server address, with case in‐
2799 sensitive lists of LHLO keywords (pipelining, starttls, auth, etc.)
2800 that the Postfix LMTP client will ignore in the LHLO response from a
2801 remote LMTP server. See lmtp_discard_lhlo_keywords for details. The ta‐
2802 ble is not indexed by hostname for consistency with smtpd_dis‐
2803 card_ehlo_keyword_address_maps.
2804 This feature is available in Postfix 2.3 and later.
2806
2808 A case insensitive list of LHLO keywords (pipelining, starttls, auth,
2809 etc.) that the Postfix LMTP client will ignore in the LHLO response
2810 from a remote LMTP server.
2811 This feature is available in Postfix 2.3 and later.
2813 Notes:
2815 • Specify the silent-discard pseudo keyword to prevent this action
2817 from being logged.
2818 • Use the lmtp_discard_lhlo_keyword_address_maps feature to dis‐
2820 card LHLO keywords selectively.
2821
2823 Optional filter for Postfix LMTP client DNS lookup results. See
2824 smtp_dns_reply_filter for details including an example.
2825 This feature is available in Postfix 3.0 and later.
2827
2829 The LMTP-specific version of the smtp_dns_resolver_options configura‐
2830 tion parameter. See there for details.
2831 This feature is available in Postfix 2.8 and later.
2833
2835 The LMTP-specific version of the smtp_dns_support_level configuration
2836 parameter. See there for details.
2837 This feature is available in Postfix 2.11 and later.
2839
2841 The LMTP-specific version of the smtp_enforce_tls configuration parame‐
2842 ter. See there for details.
2843 This feature is available in Postfix 2.3 and later.
2845
2847 Optional list of relay hosts for LMTP destinations that can't be found
2848 or that are unreachable. In main.cf elements are separated by white‐
2849 space or commas.
2850 By default, mail is returned to the sender when a destination is not
2852 found, and delivery is deferred when a destination is unreachable.
2853 The fallback relays must be TCP destinations, specified without a lead‐
2855 ing "inet:" prefix. Specify a host or host:port. Since MX lookups do
2856 not apply with LMTP, there is no need to use the "[host]" or
2857 "[host]:port" forms. If you specify multiple LMTP destinations, Post‐
2858 fix will try them in the specified order.
2859 This feature is available in Postfix 3.1 and later.
2861
2863 The LMTP-specific version of the smtp_generic_maps configuration param‐
2864 eter. See there for details.
2865 This feature is available in Postfix 2.3 and later.
2867
2869 The LMTP-specific version of the smtp_header_checks configuration pa‐
2870 rameter. See there for details.
2871 This feature is available in Postfix 2.5 and later.
2873
2875 The LMTP-specific version of the smtp_host_lookup configuration parame‐
2876 ter. See there for details.
2877 This feature is available in Postfix 2.3 and later.
2879
2881 The hostname to send in the LMTP LHLO command.
2882 The default value is the machine hostname. Specify a hostname or
2884 [ip.add.re.ss].
2885 This information can be specified in the main.cf file for all LMTP
2887 clients, or it can be specified in the master.cf file for a specific
2888 client, for example:
2889 /etc/postfix/master.cf:
2891 mylmtp ... lmtp -o lmtp_lhlo_name=foo.bar.com
2892 This feature is available in Postfix 2.3 and later.
2894
2896 The Postfix LMTP client time limit for sending the LHLO command, and
2897 for receiving the initial remote LMTP server response.
2898 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
2900 The default time unit is s (seconds).
2901
2903 The LMTP-specific version of the smtp_line_length_limit configuration
2904 parameter. See there for details.
2905 This feature is available in Postfix 2.3 and later.
2907
2909 The Postfix LMTP client time limit for sending the MAIL FROM command,
2910 and for receiving the remote LMTP server response.
2911 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
2913 The default time unit is s (seconds).
2914
2916 The LMTP-specific version of the smtp_mime_header_checks configuration
2917 parameter. See there for details.
2918 This feature is available in Postfix 2.5 and later.
2920
2922 The LMTP-specific version of the smtp_mx_address_limit configuration
2923 parameter. See there for details.
2924 This feature is available in Postfix 2.3 and later.
2926
2928 The LMTP-specific version of the smtp_mx_session_limit configuration
2929 parameter. See there for details.
2930 This feature is available in Postfix 2.3 and later.
2932
2934 The LMTP-specific version of the smtp_nested_header_checks configura‐
2935 tion parameter. See there for details.
2936 This feature is available in Postfix 2.5 and later.
2938
2940 The LMTP-specific version of the smtp_per_record_deadline configuration
2941 parameter. See there for details.
2942 This feature is available in Postfix 2.9 and later.
2944
2946 The LMTP-specific version of the smtp_pix_workaround_delay_time config‐
2947 uration parameter. See there for details.
2948 This feature is available in Postfix 2.3 and later.
2950
2952 The LMTP-specific version of the smtp_pix_workaround_maps configuration
2953 parameter. See there for details.
2954 This feature is available in Postfix 2.4 and later.
2956
2958 The LMTP-specific version of the smtp_pix_workaround_threshold_time
2959 configuration parameter. See there for details.
2960 This feature is available in Postfix 2.3 and later.
2962
2964 The LMTP-specific version of the smtp_pix_workaround configuration pa‐
2965 rameter. See there for details.
2966 This feature is available in Postfix 2.4 and later.
2968
2970 The Postfix LMTP client time limit for sending the QUIT command, and
2971 for receiving the remote LMTP server response.
2972 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
2974 The default time unit is s (seconds).
2975
2977 The LMTP-specific version of the smtp_quote_rfc821_envelope configura‐
2978 tion parameter. See there for details.
2979 This feature is available in Postfix 2.3 and later.
2981
2983 The LMTP-specific version of the smtp_randomize_addresses configuration
2984 parameter. See there for details.
2985 This feature is available in Postfix 2.3 and later.
2987
2989 The Postfix LMTP client time limit for sending the RCPT TO command, and
2990 for receiving the remote LMTP server response.
2991 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
2993 The default time unit is s (seconds).
2994
2996 The LMTP-specific version of the smtp_reply_filter configuration param‐
2997 eter. See there for details.
2998 This feature is available in Postfix 2.7 and later.
3000
3002 The Postfix LMTP client time limit for sending the RSET command, and
3003 for receiving the remote LMTP server response. The LMTP client sends
3004 RSET in order to finish a recipient address probe, or to verify that a
3005 cached connection is still alive.
3006 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
3008 The default time unit is s (seconds).
3009
3011 The LMTP-specific version of the smtp_sasl_auth_cache_name configura‐
3012 tion parameter. See there for details.
3013 This feature is available in Postfix 2.5 and later.
3015
3017 The LMTP-specific version of the smtp_sasl_auth_cache_time configura‐
3018 tion parameter. See there for details.
3019 This feature is available in Postfix 2.5 and later.
3021
3023 Enable SASL authentication in the Postfix LMTP client.
3024
3026 The LMTP-specific version of the smtp_sasl_auth_soft_bounce configura‐
3027 tion parameter. See there for details.
3028 This feature is available in Postfix 2.5 and later.
3030
3032 The LMTP-specific version of the smtp_sasl_mechanism_filter configura‐
3033 tion parameter. See there for details.
3034 This feature is available in Postfix 2.3 and later.
3036
3038 Optional Postfix LMTP client lookup tables with one username:password
3039 entry per host or domain. If a remote host or domain has no user‐
3040 name:password entry, then the Postfix LMTP client will not attempt to
3041 authenticate to the remote host.
3042
3044 Implementation-specific information that is passed through to the SASL
3045 plug-in implementation that is selected with lmtp_sasl_type. Typically
3046 this specifies the name of a configuration file or rendezvous point.
3047 This feature is available in Postfix 2.3 and later.
3049
3051 SASL security options; as of Postfix 2.3 the list of available features
3052 depends on the SASL client implementation that is selected with
3053 lmtp_sasl_type.
3054 The following security features are defined for the cyrus client SASL
3056 implementation:
3057 noplaintext
3059 Disallow authentication methods that use plaintext passwords.
3060 noactive
3062 Disallow authentication methods that are vulnerable to non-dic‐
3063 tionary active attacks.
3064 nodictionary
3066 Disallow authentication methods that are vulnerable to passive
3067 dictionary attack.
3068 noanonymous
3070 Disallow anonymous logins.
3071 Example:
3073 lmtp_sasl_security_options = noplaintext
3075
3077 The LMTP-specific version of the smtp_sasl_tls_security_options config‐
3078 uration parameter. See there for details.
3079 This feature is available in Postfix 2.3 and later.
3081
3083 tions)
3084 The LMTP-specific version of the smtp_sasl_tls_verified_security_op‐
3085 tions configuration parameter. See there for details.
3086 This feature is available in Postfix 2.3 and later.
3088
3090 The SASL plug-in type that the Postfix LMTP client should use for au‐
3091 thentication. The available types are listed with the "postconf -A"
3092 command.
3093 This feature is available in Postfix 2.3 and later.
3095
3097 The LMTP-specific version of the smtp_send_dummy_mail_auth configura‐
3098 tion parameter. See there for details.
3099 This feature is available in Postfix 2.9 and later.
3101
3103 Send an XFORWARD command to the remote LMTP server when the LMTP LHLO
3104 server response announces XFORWARD support. This allows an lmtp(8) de‐
3105 livery agent, used for content filter message injection, to forward the
3106 name, address, protocol and HELO name of the original client to the
3107 content filter and downstream queuing LMTP server. Before you change
3108 the value to yes, it is best to make sure that your content filter sup‐
3109 ports this command.
3110 This feature is available in Postfix 2.1 and later.
3112
3114 The LMTP-specific version of the smtp_sender_dependent_authentication
3115 configuration parameter. See there for details.
3116 This feature is available in Postfix 2.3 and later.
3118
3120 The LMTP-specific version of the smtp_skip_5xx_greeting configuration
3121 parameter. See there for details.
3122 This feature is available in Postfix 2.3 and later.
3124
3126 Wait for the response to the LMTP QUIT command.
3127
3129 The LMTP-specific version of the smtp_starttls_timeout configuration
3130 parameter. See there for details.
3131 This feature is available in Postfix 2.3 and later.
3133
3135 The default TCP port that the Postfix LMTP client connects to. Specify
3136 a symbolic name (see services(5)) or a numeric port.
3137
3139 The LMTP-specific version of the smtp_tls_CAfile configuration parame‐
3140 ter. See there for details.
3141 This feature is available in Postfix 2.3 and later.
3143
3145 The LMTP-specific version of the smtp_tls_CApath configuration parame‐
3146 ter. See there for details.
3147 This feature is available in Postfix 2.3 and later.
3149
3151 The LMTP-specific version of the smtp_tls_block_early_mail_reply con‐
3152 figuration parameter. See there for details.
3153 This feature is available in Postfix 2.7 and later.
3155
3157 The LMTP-specific version of the smtp_tls_cert_file configuration pa‐
3158 rameter. See there for details.
3159 This feature is available in Postfix 2.3 and later.
3161
3163 The LMTP-specific version of the smtp_tls_chain_files configuration pa‐
3164 rameter. See there for details.
3165 This feature is available in Postfix 3.4 and later.
3167
3169 The LMTP-specific version of the smtp_tls_ciphers configuration parame‐
3170 ter. See there for details.
3171 This feature is available in Postfix 2.6 and later.
3173
3175 The LMTP-specific version of the smtp_tls_connection_reuse configura‐
3176 tion parameter. See there for details.
3177 This feature is available in Postfix 3.4 and later.
3179
3181 The LMTP-specific version of the smtp_tls_dcert_file configuration pa‐
3182 rameter. See there for details.
3183 This feature is available in Postfix 2.3 and later.
3185
3187 The LMTP-specific version of the smtp_tls_dkey_file configuration pa‐
3188 rameter. See there for details.
3189 This feature is available in Postfix 2.3 and later.
3191
3193 The LMTP-specific version of the smtp_tls_eccert_file configuration pa‐
3194 rameter. See there for details.
3195 This feature is available in Postfix 2.6 and later, when Postfix is
3197 compiled and linked with OpenSSL 1.0.0 or later.
3198
3200 The LMTP-specific version of the smtp_tls_eckey_file configuration pa‐
3201 rameter. See there for details.
3202 This feature is available in Postfix 2.6 and later, when Postfix is
3204 compiled and linked with OpenSSL 1.0.0 or later.
3205
3207 The LMTP-specific version of the smtp_tls_enforce_peername configura‐
3208 tion parameter. See there for details.
3209 This feature is available in Postfix 2.3 and later.
3211
3213 The LMTP-specific version of the smtp_tls_exclude_ciphers configuration
3214 parameter. See there for details.
3215 This feature is available in Postfix 2.3 and later.
3217
3219 The LMTP-specific version of the smtp_tls_fingerprint_cert_match con‐
3220 figuration parameter. See there for details.
3221 This feature is available in Postfix 2.5 and later.
3223
3225 The LMTP-specific version of the smtp_tls_fingerprint_digest configura‐
3226 tion parameter. See there for details.
3227 This feature is available in Postfix 2.5 and later.
3229
3231 The LMTP-specific version of the smtp_tls_force_inse‐
3232 cure_host_tlsa_lookup configuration parameter. See there for details.
3233 This feature is available in Postfix 2.11 and later.
3235
3237 The LMTP-specific version of the smtp_tls_key_file configuration param‐
3238 eter. See there for details.
3239 This feature is available in Postfix 2.3 and later.
3241
3243 The LMTP-specific version of the smtp_tls_loglevel configuration param‐
3244 eter. See there for details.
3245 This feature is available in Postfix 2.3 and later.
3247
3249 The LMTP-specific version of the smtp_tls_mandatory_ciphers configura‐
3250 tion parameter. See there for details.
3251 This feature is available in Postfix 2.3 and later.
3253
3255 The LMTP-specific version of the smtp_tls_mandatory_exclude_ciphers
3256 configuration parameter. See there for details.
3257 This feature is available in Postfix 2.3 and later.
3259
3261 The LMTP-specific version of the smtp_tls_mandatory_protocols configu‐
3262 ration parameter. See there for details.
3263 This feature is available in Postfix 2.3 and later.
3265
3267 The LMTP-specific version of the smtp_tls_note_starttls_offer configu‐
3268 ration parameter. See there for details.
3269 This feature is available in Postfix 2.3 and later.
3271
3273 The LMTP-specific version of the smtp_tls_per_site configuration param‐
3274 eter. See there for details.
3275 This feature is available in Postfix 2.3 and later.
3277
3279 The LMTP-specific version of the smtp_tls_policy_maps configuration pa‐
3280 rameter. See there for details.
3281 This feature is available in Postfix 2.3 and later.
3283
3285 The LMTP-specific version of the smtp_tls_protocols configuration pa‐
3286 rameter. See there for details.
3287 This feature is available in Postfix 2.6 and later.
3289
3291 The LMTP-specific version of the smtp_tls_scert_verifydepth configura‐
3292 tion parameter. See there for details.
3293 This feature is available in Postfix 2.3 and later.
3295
3297 The LMTP-specific version of the smtp_tls_secure_cert_match configura‐
3298 tion parameter. See there for details.
3299 This feature is available in Postfix 2.3 and later.
3301
3303 The LMTP-specific version of the smtp_tls_security_level configuration
3304 parameter. See there for details.
3305 This feature is available in Postfix 2.3 and later.
3307
3309 The LMTP-specific version of the smtp_tls_servername configuration pa‐
3310 rameter. See there for details.
3311 This feature is available in Postfix 3.4 and later.
3313
3315 The LMTP-specific version of the smtp_tls_session_cache_database con‐
3316 figuration parameter. See there for details.
3317 This feature is available in Postfix 2.3 and later.
3319
3321 The LMTP-specific version of the smtp_tls_session_cache_timeout config‐
3322 uration parameter. See there for details.
3323 This feature is available in Postfix 2.3 and later.
3325
3327 The LMTP-specific version of the smtp_tls_trust_anchor_file configura‐
3328 tion parameter. See there for details.
3329 This feature is available in Postfix 2.11 and later.
3331
3333 The LMTP-specific version of the smtp_tls_verify_cert_match configura‐
3334 tion parameter. See there for details.
3335 This feature is available in Postfix 2.3 and later.
3337
3339 The LMTP-specific version of the smtp_use_tls configuration parameter.
3340 See there for details.
3341 This feature is available in Postfix 2.3 and later.
3343
3345 The Postfix LMTP client time limit for sending the XFORWARD command,
3346 and for receiving the remote LMTP server response.
3347 In case of problems the client does NOT try the next address on the
3349 mail exchanger list.
3350 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
3352 The default time unit is s (seconds).
3353 This feature is available in Postfix 2.1 and later.
3355
3357 Optional shell program for local(8) delivery to non-Postfix command.
3358 By default, non-Postfix commands are executed directly; commands are
3359 given to given to the default shell (typically, /bin/sh) only when they
3360 contain shell meta characters or shell built-in commands.
3361 "sendmail's restricted shell" (smrsh) is what most people will use in
3363 order to restrict what programs can be run from e.g. .forward files
3364 (smrsh is part of the Sendmail distribution).
3365 Note: when a shell program is specified, it is invoked even when the
3367 command contains no shell built-in commands or meta characters.
3368 Example:
3370 local_command_shell = /some/where/smrsh -c
3372 local_command_shell = /bin/bash -c
3373
3375 Optional filter for the local(8) delivery agent to change the status
3376 code or explanatory text of successful or unsuccessful deliveries. See
3377 default_delivery_status_filter for details.
3378 This feature is available in Postfix 3.0 and later.
3380
3382 The maximal number of parallel deliveries via the local mail delivery
3383 transport to the same recipient (when "local_destination_recipi‐
3384 ent_limit = 1") or the maximal number of parallel deliveries to the
3385 same local domain (when "local_destination_recipient_limit > 1"). This
3386 limit is enforced by the queue manager. The message delivery transport
3387 name is the first field in the entry in the master.cf file.
3388 A low limit of 2 is recommended, just in case someone has an expensive
3390 shell command in a .forward file or in an alias (e.g., a mailing list
3391 manager). You don't want to run lots of those at the same time.
3392
3394 The maximal number of recipients per message delivery via the local
3395 mail delivery transport. This limit is enforced by the queue manager.
3396 The message delivery transport name is the first field in the entry in
3397 the master.cf file.
3398 Setting this parameter to a value > 1 changes the meaning of local_des‐
3400 tination_concurrency_limit from concurrency per recipient into concur‐
3401 rency per domain.
3402
3404 Rewrite message header addresses in mail from these clients and update
3405 incomplete addresses with the domain name in $myorigin or $mydomain;
3406 either don't rewrite message headers from other clients at all, or re‐
3407 write message headers and update incomplete addresses with the domain
3408 specified in the remote_header_rewrite_domain parameter.
3409 See the append_at_myorigin and append_dot_mydomain parameters for de‐
3411 tails of how domain names are appended to incomplete addresses.
3412 Specify a list of zero or more of the following:
3414 permit_inet_interfaces
3416 Append the domain name in $myorigin or $mydomain when the client
3417 IP address matches $inet_interfaces. This is enabled by default.
3418 permit_mynetworks
3420 Append the domain name in $myorigin or $mydomain when the client
3421 IP address matches any network or network address listed in
3422 $mynetworks. This setting will not prevent remote mail header
3423 address rewriting when mail from a remote client is forwarded by
3424 a neighboring system.
3425 permit_sasl_authenticated
3427 Append the domain name in $myorigin or $mydomain when the client
3428 is successfully authenticated via the RFC 4954 (AUTH) protocol.
3429 permit_tls_clientcerts
3431 Append the domain name in $myorigin or $mydomain when the remote
3432 SMTP client TLS certificate fingerprint or public key finger‐
3433 print (Postfix 2.9 and later) is listed in $relay_clientcerts.
3434 The fingerprint digest algorithm is configurable via the
3435 smtpd_tls_fingerprint_digest parameter (hard-coded as md5 prior
3436 to Postfix version 2.5).
3437 The default algorithm is sha256 with Postfix >= 3.6 and the com‐
3438 patibility_level set to 3.6 or higher. With Postfix <= 3.5, the
3439 default algorithm is md5. The best-practice algorithm is now
3440 sha256. Recent advances in hash function cryptanalysis have led
3441 to md5 and sha1 being deprecated in favor of sha256. However,
3442 as long as there are no known "second pre-image" attacks against
3443 the older algorithms, their use in this context, though not rec‐
3444 ommended, is still likely safe.
3445 permit_tls_all_clientcerts
3447 Append the domain name in $myorigin or $mydomain when the remote
3448 SMTP client TLS certificate is successfully verified, regardless
3449 of whether it is listed on the server, and regardless of the
3450 certifying authority.
3451 check_address_map type:table
3453 type:table
3455 Append the domain name in $myorigin or $mydomain when the client
3456 IP address matches the specified lookup table. The lookup re‐
3457 sult is ignored, and no subnet lookup is done. This is suitable
3458 for, e.g., pop-before-smtp lookup tables.
3459 Examples:
3461 The Postfix < 2.2 backwards compatible setting: always rewrite message
3463 headers, and always append my own domain to incomplete header ad‐
3464 dresses.
3465 local_header_rewrite_clients = static:all
3467 The purist (and default) setting: rewrite headers only in mail from
3469 Postfix sendmail and in SMTP mail from this machine.
3470 local_header_rewrite_clients = permit_inet_interfaces
3472 The intermediate setting: rewrite header addresses and append $myorigin
3474 or $mydomain information only with mail from Postfix sendmail, from lo‐
3475 cal clients, or from authorized SMTP clients.
3476 Note: this setting will not prevent remote mail header address rewrit‐
3478 ing when mail from a remote client is forwarded by a neighboring sys‐
3479 tem.
3480 local_header_rewrite_clients = permit_mynetworks,
3482 permit_sasl_authenticated permit_tls_clientcerts
3483 check_address_map hash:/etc/postfix/pop-before-smtp
3484
3486 A list of lookup tables that are searched by the UNIX login name, and
3487 that return a list of allowed envelope sender patterns separated by
3488 space or comma. These sender patterns are enforced by the Postfix post‐
3489 drop(1) command. The default is backwards-compatible: every user may
3490 specify any sender envelope address.
3491 When no UNIX login name is available, the postdrop(1) command will
3493 prepend "uid:" to the numerical UID and use that instead.
3494 This feature ignores address extensions in the user-specified envelope
3496 sender address.
3497 The following sender patterns are special; these cannot be used as part
3499 of a longer pattern.
3500 * This pattern allows any envelope sender address.
3502 <> This pattern allows the empty envelope sender address. See the
3504 empty_address_local_login_sender_maps_lookup_key configuration
3505 parameter.
3506 @domain
3508 This pattern allows an envelope sender address when the '@' and
3509 domain part match.
3510 Examples:
3512 /etc/postfix/main.cf:
3514 # Allow root and postfix full control, anyone else can only
3515 # send mail as themselves. Use "uid:" followed by the numerical
3516 # UID when the UID has no entry in the UNIX password file.
3517 local_login_sender_maps =
3518 inline:{ { root = *}, { postfix = * } },
3519 pcre:/etc/postfix/login_senders
3520 /etc/postfix/login_senders:
3522 # Allow both the bare username and the user@domain forms.
3523 /(.+)/ $1 $1@example.com/
3524 This feature is available in Postfix 3.6 and later.
3526
3528 Lookup tables with all names or addresses of local recipients: a recip‐
3529 ient address is local when its domain matches $mydestination, $inet_in‐
3530 terfaces or $proxy_interfaces. Specify @domain as a wild-card for do‐
3531 mains that do not have a valid recipient list. Technically, tables
3532 listed with $local_recipient_maps are used as lists: Postfix needs to
3533 know only if a lookup string is found or not, but it does not use the
3534 result from table lookup.
3535 Specify zero or more "type:name" lookup tables, separated by whitespace
3537 or comma. Tables will be searched in the specified order until a match
3538 is found.
3539 If this parameter is non-empty (the default), then the Postfix SMTP
3541 server will reject mail for unknown local users.
3542 To turn off local recipient checking in the Postfix SMTP server, spec‐
3544 ify "local_recipient_maps =" (i.e. empty).
3545 The default setting assumes that you use the default Postfix local de‐
3547 livery agent for local delivery. You need to update the local_recipi‐
3548 ent_maps setting if:
3549 • You redefine the local delivery agent in master.cf.
3551 • You redefine the "local_transport" setting in main.cf.
3553 • You use the "luser_relay", "mailbox_transport", or "fall‐
3555 back_transport" feature of the Postfix local(8) delivery agent.
3556 Details are described in the LOCAL_RECIPIENT_README file.
3558 Beware: if the Postfix SMTP server runs chrooted, you need to access
3560 the passwd file via the proxymap(8) service, in order to overcome ch‐
3561 root access restrictions. The alternative, maintaining a copy of the
3562 system password file in the chroot jail is not practical.
3563 Examples:
3565 local_recipient_maps =
3567
3569 The default mail delivery transport and next-hop destination for final
3570 delivery to domains listed with mydestination, and for [ipaddress] des‐
3571 tinations that match $inet_interfaces or $proxy_interfaces. This in‐
3572 formation can be overruled with the transport(5) table.
3573 By default, local mail is delivered to the transport called "local",
3575 which is just the name of a service that is defined the master.cf file.
3576 Specify a string of the form transport:nexthop, where transport is the
3578 name of a mail delivery transport defined in master.cf. The :nexthop
3579 destination is optional; its syntax is documented in the manual page of
3580 the corresponding delivery agent.
3581 Beware: if you override the default local delivery agent then you need
3583 to review the LOCAL_RECIPIENT_README document, otherwise the SMTP
3584 server may reject mail for local recipients.
3585
3587 Optional catch-all destination for unknown local(8) recipients. By de‐
3588 fault, mail for unknown recipients in domains that match $mydestina‐
3589 tion, $inet_interfaces or $proxy_interfaces is returned as undeliver‐
3590 able.
3591 The luser_relay value is not subject to Postfix configuration parameter
3593 $name expansion. Instead, the following $name expansions are done:
3594 $domain
3596 The recipient domain.
3597 $extension
3599 The recipient address extension.
3600 $home The recipient's home directory.
3602 $local The entire recipient address localpart.
3604 $recipient
3606 The full recipient address.
3607 $recipient_delimiter
3609 The address extension delimiter that was found in the recipient
3610 address (Postfix 2.11 and later), or the system-wide recipient
3611 address extension delimiter (Postfix 2.10 and earlier).
3612 $shell The recipient's login shell.
3614 $user The recipient username.
3616 ${name?value}
3618 Expands to value when $name has a non-empty value.
3619 ${name:value}
3621 Expands to value when $name has an empty value.
3622 Instead of $name you can also specify ${name} or $(name).
3624 Note: luser_relay works only for the Postfix local(8) delivery agent.
3626 Note: if you use this feature for accounts not in the UNIX password
3628 file, then you must specify "local_recipient_maps =" (i.e. empty) in
3629 the main.cf file, otherwise the Postfix SMTP server will reject mail
3630 for non-UNIX accounts with "User unknown in local recipient table".
3631 Examples:
3633 luser_relay = $user@other.host
3635 luser_relay = $local@other.host
3636 luser_relay = admin+$local
3637
3639 The mail system name that is displayed in Received: headers, in the
3640 SMTP greeting banner, and in bounced mail.
3641
3643 The UNIX system account that owns the Postfix queue and most Postfix
3644 daemon processes. Specify the name of an unprivileged user account
3645 that does not share a user or group ID with other accounts, and that
3646 owns no other files or processes on the system. In particular, don't
3647 specify nobody or daemon. PLEASE USE A DEDICATED USER ID AND GROUP ID.
3648 When this parameter value is changed you need to re-run "postfix
3650 set-permissions" (with Postfix version 2.0 and earlier: "/etc/post‐
3651 fix/post-install set-permissions".
3652
3654 The Postfix release date, in "YYYYMMDD" format.
3655
3657 The directory where local(8) UNIX-style mailboxes are kept. The default
3658 setting depends on the system type. Specify a name ending in / for
3659 maildir-style delivery.
3660 Note: maildir delivery is done with the privileges of the recipient.
3662 If you use the mail_spool_directory setting for maildir style delivery,
3663 then you must create the top-level maildir directory in advance. Post‐
3664 fix will not create it.
3665 Examples:
3667 mail_spool_directory = /var/mail
3669 mail_spool_directory = /var/spool/mail
3670
3672 The version of the mail system. Stable releases are named major.mi‐
3673 nor.patchlevel. Experimental releases also include the release date.
3674 The version string can be used in, for example, the SMTP greeting ban‐
3675 ner.
3676
3678 Optional external command that the local(8) delivery agent should use
3679 for mailbox delivery. The command is run with the user ID and the pri‐
3680 mary group ID privileges of the recipient. Exception: command delivery
3681 for root executes with $default_privs privileges. This is not a prob‐
3682 lem, because 1) mail for root should always be aliased to a real user
3683 and 2) don't log in as root, use "su" instead.
3684 The following environment variables are exported to the command:
3686 CLIENT_ADDRESS
3688 Remote client network address. Available in Postfix version 2.2
3689 and later.
3690 CLIENT_HELO
3692 Remote client EHLO command parameter. Available in Postfix ver‐
3693 sion 2.2 and later.
3694 CLIENT_HOSTNAME
3696 Remote client hostname. Available in Postfix version 2.2 and
3697 later.
3698 CLIENT_PROTOCOL
3700 Remote client protocol. Available in Postfix version 2.2 and
3701 later.
3702 DOMAIN The domain part of the recipient address.
3704 EXTENSION
3706 The optional address extension.
3707 HOME The recipient home directory.
3709 LOCAL The recipient address localpart.
3711 LOGNAME
3713 The recipient's username.
3714 ORIGINAL_RECIPIENT
3716 The entire recipient address, before any address rewriting or
3717 aliasing.
3718 RECIPIENT
3720 The full recipient address.
3721 SASL_METHOD
3723 SASL authentication method specified in the remote client AUTH
3724 command. Available in Postfix version 2.2 and later.
3725 SASL_SENDER
3727 SASL sender address specified in the remote client MAIL FROM
3728 command. Available in Postfix version 2.2 and later.
3729 SASL_USER
3731 SASL username specified in the remote client AUTH command.
3732 Available in Postfix version 2.2 and later.
3733 SENDER The full sender address.
3735 SHELL The recipient's login shell.
3737 USER The recipient username.
3739 Unlike other Postfix configuration parameters, the mailbox_command pa‐
3741 rameter is not subjected to $name substitutions. This is to make it
3742 easier to specify shell syntax (see example below).
3743 If you can, avoid shell meta characters because they will force Postfix
3745 to run an expensive shell process. If you're delivering via "procmail"
3746 then running a shell won't make a noticeable difference in the total
3747 cost.
3748 Note: if you use the mailbox_command feature to deliver mail sys‐
3750 tem-wide, you must set up an alias that forwards mail for root to a
3751 real user.
3752 The precedence of local(8) delivery features from high to low is:
3754 aliases, .forward files, mailbox_transport_maps, mailbox_transport,
3755 mailbox_command_maps, mailbox_command, home_mailbox, mail_spool_direc‐
3756 tory, fallback_transport_maps, fallback_transport and luser_relay.
3757 Examples:
3759 mailbox_command = /some/where/procmail
3761 mailbox_command = /some/where/procmail -a "$EXTENSION"
3762 mailbox_command = /some/where/maildrop -d "$USER"
3763 -f "$SENDER" "$EXTENSION"
3764
3766 Optional lookup tables with per-recipient external commands to use for
3767 local(8) mailbox delivery. Behavior is as with mailbox_command.
3768 The precedence of local(8) delivery features from high to low is:
3770 aliases, .forward files, mailbox_transport_maps, mailbox_transport,
3771 mailbox_command_maps, mailbox_command, home_mailbox, mail_spool_direc‐
3772 tory, fallback_transport_maps, fallback_transport and luser_relay.
3773 Specify zero or more "type:name" lookup tables, separated by whitespace
3775 or comma. Tables will be searched in the specified order until a match
3776 is found.
3777
3779 How to lock a UNIX-style local(8) mailbox before attempting delivery.
3780 For a list of available file locking methods, use the "postconf -l"
3781 command.
3782 This setting is ignored with maildir style delivery, because such de‐
3784 liveries are safe without explicit locks.
3785 Note: The dotlock method requires that the recipient UID or GID has
3787 write access to the parent directory of the mailbox file.
3788 Note: the default setting of this parameter is system dependent.
3790
3792 The maximal size of any local(8) individual mailbox or maildir file, or
3793 zero (no limit). In fact, this limits the size of any file that is
3794 written to upon local delivery, including files written by external
3795 commands that are executed by the local(8) delivery agent.
3796 This limit must not be smaller than the message size limit.
3798
3800 Optional message delivery transport that the local(8) delivery agent
3801 should use for mailbox delivery to all local recipients, whether or not
3802 they are found in the UNIX passwd database.
3803 The precedence of local(8) delivery features from high to low is:
3805 aliases, .forward files, mailbox_transport_maps, mailbox_transport,
3806 mailbox_command_maps, mailbox_command, home_mailbox, mail_spool_direc‐
3807 tory, fallback_transport_maps, fallback_transport and luser_relay.
3808
3810 Optional lookup tables with per-recipient message delivery transports
3811 to use for local(8) mailbox delivery, whether or not the recipients are
3812 found in the UNIX passwd database.
3813 The precedence of local(8) delivery features from high to low is:
3815 aliases, .forward files, mailbox_transport_maps, mailbox_transport,
3816 mailbox_command_maps, mailbox_command, home_mailbox, mail_spool_direc‐
3817 tory, fallback_transport_maps, fallback_transport and luser_relay.
3818 Specify zero or more "type:name" lookup tables, separated by whitespace
3820 or comma. Tables will be searched in the specified order until a match
3821 is found.
3822 For safety reasons, this feature does not allow $number substitutions
3824 in regular expression maps.
3825 This feature is available in Postfix 2.3 and later.
3827
3829 The name of an optional logfile that is written by the Postfix post‐
3830 logd(8) service. An empty value selects logging to syslogd(8). Specify
3831 "/dev/stdout" to select logging to standard output. Stdout logging re‐
3832 quires that Postfix is started with "postfix start-fg".
3833 Note 1: The maillog_file parameter value must contain a prefix that is
3835 specified with the maillog_file_prefixes parameter.
3836 Note 2: Some Postfix non-daemon programs may still log information to
3838 syslogd(8), before they have processed their configuration parameters
3839 and command-line options.
3840 This feature is available in Postfix 3.4 and later.
3842
3844 The program to run after rotating $maillog_file with "postfix logro‐
3845 tate". The command is run with the rotated logfile name as its first
3846 argument.
3847 This feature is available in Postfix 3.4 and later.
3849
3851 A list of allowed prefixes for a maillog_file value. This is a safety
3852 feature to contain the damage from a single configuration mistake.
3853 Specify one or more prefix strings, separated by comma or whitespace.
3854 This feature is available in Postfix 3.4 and later.
3856
3858 The format of the suffix to append to $maillog_file while rotating the
3859 file with "postfix logrotate". See strftime(3) for syntax. The default
3860 suffix, YYYYMMDD-HHMMSS, allows logs to be rotated frequently.
3861 This feature is available in Postfix 3.4 and later.
3863
3865 Sendmail compatibility feature that specifies where the Postfix
3866 mailq(1) command is installed. This command can be used to list the
3867 Postfix mail queue.
3868
3870 Where the Postfix manual pages are installed.
3871
3873 Obsolete feature: use the reject_rbl_client feature instead.
3874
3876 The numerical Postfix SMTP server response code when a remote SMTP
3877 client request is blocked by the reject_rbl_client, re‐
3878 ject_rhsbl_client, reject_rhsbl_reverse_client, reject_rhsbl_sender or
3879 reject_rhsbl_recipient restriction.
3880 Do not change this unless you have a complete understanding of RFC
3882 5321.
3883
3885 What addresses are subject to address masquerading.
3887 By default, address masquerading is limited to envelope sender ad‐
3889 dresses, and to header sender and header recipient addresses. This al‐
3890 lows you to use address masquerading on a mail gateway while still be‐
3891 ing able to forward mail to users on individual machines.
3892 Specify zero or more of: envelope_sender, envelope_recipient,
3894 header_sender, header_recipient
3895
3897 Optional list of domains whose subdomain structure will be stripped off
3898 in email addresses.
3899 The list is processed left to right, and processing stops at the first
3901 match. Thus,
3902 masquerade_domains = foo.example.com example.com
3904 strips "user@any.thing.foo.example.com" to "user@foo.example.com", but
3906 strips "user@any.thing.else.example.com" to "user@example.com".
3907 A domain name prefixed with ! means do not masquerade this domain or
3909 its subdomains. Thus,
3910 masquerade_domains = !foo.example.com example.com
3912 does not change "user@any.thing.foo.example.com" or "user@foo.exam‐
3914 ple.com", but strips "user@any.thing.else.example.com" to "user@exam‐
3915 ple.com".
3916 Note: with Postfix version 2.2, message header address masquerading
3918 happens only when message header address rewriting is enabled:
3919 • The message is received with the Postfix sendmail(1) command,
3921 • The message is received from a network client that matches $lo‐
3923 cal_header_rewrite_clients,
3924 • The message is received from the network, and the re‐
3926 mote_header_rewrite_domain parameter specifies a non-empty
3927 value.
3928 To get the behavior before Postfix version 2.2, specify "lo‐
3930 cal_header_rewrite_clients = static:all".
3931 Example:
3933 masquerade_domains = $mydomain
3935
3937 Optional list of user names that are not subjected to address mas‐
3938 querading, even when their addresses match $masquerade_domains.
3939 By default, address masquerading makes no exceptions.
3941 Specify a list of user names, "/file/name" or "type:table" patterns,
3943 separated by commas and/or whitespace. The list is matched left to
3944 right, and the search stops on the first match. A "/file/name" pattern
3945 is replaced by its contents; a "type:table" lookup table is matched
3946 when a name matches a lookup key (the lookup result is ignored). Con‐
3947 tinue long lines by starting the next line with whitespace. Specify
3948 "!pattern" to exclude a name from the list. The form "!/file/name" is
3949 supported only in Postfix version 2.4 and later.
3950 Examples:
3952 masquerade_exceptions = root, mailer-daemon
3954 masquerade_exceptions = root
3955
3957 Selectively disable master(8) listener ports by service type or by ser‐
3958 vice name and type. Specify a list of service types ("inet", "unix",
3959 "fifo", or "pass") or "name/type" tuples, where "name" is the first
3960 field of a master.cf entry and "type" is a service type. As with other
3961 Postfix matchlists, a search stops at the first match. Specify "!pat‐
3962 tern" to exclude a service from the list. By default, all master(8)
3963 listener ports are enabled.
3964 Note: this feature does not support "/file/name" or "type:table" pat‐
3966 terns, nor does it support wildcards such as "*" or "all". This is in‐
3967 tentional.
3968 Examples:
3970 # With Postfix 2.6..2.10 use '.' instead of '/'.
3972 # Turn on all master(8) listener ports (the default).
3973 master_service_disable =
3974 # Turn off only the main SMTP listener port.
3975 master_service_disable = smtp/inet
3976 # Turn off all TCP/IP listener ports.
3977 master_service_disable = inet
3978 # Turn off all TCP/IP listener ports except "foo".
3979 master_service_disable = !foo/inet, inet
3980 This feature is available in Postfix 2.6 and later.
3982
3984 The maximum amount of time that an idle Postfix daemon process waits
3985 for an incoming connection before terminating voluntarily. This param‐
3986 eter is ignored by the Postfix queue manager and by other long-lived
3987 Postfix daemon processes.
3988 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
3990 The default time unit is s (seconds).
3991
3993 The maximal number of incoming connections that a Postfix daemon
3994 process will service before terminating voluntarily. This parameter is
3995 ignored by the Postfix queue manager and by other long-lived Postfix
3996 daemon processes.
3997
3999 The maximal time between attempts to deliver a deferred message.
4000 This parameter should be set to a value greater than or equal to $mini‐
4002 mal_backoff_time. See also $queue_run_delay.
4003 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
4005 The default time unit is s (seconds).
4006
4008 Consider a message as undeliverable, when delivery fails with a tempo‐
4009 rary error, and the time in the queue has reached the maxi‐
4010 mal_queue_lifetime limit.
4011 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
4013 The default time unit is d (days).
4014 Specify 0 when mail delivery should be tried only once.
4016
4018 Names of message headers that the cleanup(8) daemon will remove after
4019 applying header_checks(5) and before invoking Milter applications. The
4020 default setting is compatible with Postfix < 3.0.
4021 Specify a list of header names, separated by comma or space. Names are
4023 matched in a case-insensitive manner. The list of supported header
4024 names is limited only by available memory.
4025 This feature is available in Postfix 3.0 and later.
4027
4029 The set of characters that Postfix will reject in message content. The
4030 usual C-like escape sequences are recognized: \a \b \f \n \r \t \v \ddd
4031 (up to three octal digits) and \\.
4032 Note 1: this feature does not recognize text that requires MIME decod‐
4034 ing. It inspects raw message content, just like header_checks and
4035 body_checks.
4036 Note 2: this feature is disabled with "receive_override_options =
4038 no_header_body_checks".
4039 Example:
4041 message_reject_characters = \0
4043 This feature is available in Postfix 2.3 and later.
4045
4047 The maximal size in bytes of a message, including envelope information.
4048 Note: be careful when making changes. Excessively small values will
4050 result in the loss of non-delivery notifications, when a bounce message
4051 size exceeds the local or remote MTA's message size limit.
4052
4054 The set of characters that Postfix will remove from message content.
4055 The usual C-like escape sequences are recognized: \a \b \f \n \r \t \v
4056 \ddd (up to three octal digits) and \\.
4057 Note 1: this feature does not recognize text that requires MIME decod‐
4059 ing. It inspects raw message content, just like header_checks and
4060 body_checks.
4061 Note 2: this feature is disabled with "receive_override_options =
4063 no_header_body_checks".
4064 Example:
4066 message_strip_characters = \0
4068 This feature is available in Postfix 2.3 and later.
4070
4072 The location of non-executable files that are shared among multiple
4073 Postfix instances, such as postfix-files, dynamicmaps.cf, and the
4074 multi-instance template files main.cf.proto and master.cf.proto. This
4075 directory should contain only Postfix-related files. Typically, the
4076 meta_directory parameter has the same default as the config_directory
4077 parameter (/etc/postfix or /usr/local/etc/postfix).
4078 For backwards compatibility with Postfix versions 2.6..2.11, specify
4080 "meta_directory = $daemon_directory" in main.cf before installing or
4081 upgrading Postfix, or specify "meta_directory = /path/name" on the
4082 "make makefiles", "make install" or "make upgrade" command line.
4083 This feature is available in Postfix 3.0 and later.
4085
4087 The time limit for sending an SMTP command to a Milter (mail filter)
4088 application, and for receiving the response.
4089 Specify a non-zero time value (an integral value plus an optional
4091 one-letter suffix that specifies the time unit).
4092 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
4094 The default time unit is s (seconds).
4095 This feature is available in Postfix 2.3 and later.
4097
4099 The macros that are sent to Milter (mail filter) applications after
4100 completion of an SMTP connection. See MILTER_README for a list of
4101 available macro names and their meanings.
4102 This feature is available in Postfix 2.3 and later.
4104
4106 The time limit for connecting to a Milter (mail filter) application,
4107 and for negotiating protocol options.
4108 Specify a non-zero time value (an integral value plus an optional
4110 one-letter suffix that specifies the time unit).
4111 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
4113 The default time unit is s (seconds).
4114 This feature is available in Postfix 2.3 and later.
4116
4118 The time limit for sending message content to a Milter (mail filter)
4119 application, and for receiving the response.
4120 Specify a non-zero time value (an integral value plus an optional
4122 one-letter suffix that specifies the time unit).
4123 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
4125 The default time unit is s (seconds).
4126 This feature is available in Postfix 2.3 and later.
4128
4130 The macros that are sent to version 4 or higher Milter (mail filter)
4131 applications after the SMTP DATA command. See MILTER_README for a list
4132 of available macro names and their meanings.
4133 This feature is available in Postfix 2.3 and later.
4135
4137 The default action when a Milter (mail filter) response is unavailable
4138 (for example, bad Postfix configuration or Milter failure). Specify one
4139 of the following:
4140 accept Proceed as if the mail filter was not present.
4142 reject Reject all further commands in this session with a permanent
4144 status code.
4145 tempfail
4147 Reject all further commands in this session with a temporary
4148 status code.
4149 quarantine
4151 Like "accept", but freeze the message in the "hold" queue.
4152 Available with Postfix 2.6 and later.
4153 This feature is available in Postfix 2.3 and later.
4155
4157 The macros that are sent to Milter (mail filter) applications after the
4158 message end-of-data. See MILTER_README for a list of available macro
4159 names and their meanings.
4160 This feature is available in Postfix 2.3 and later.
4162
4164 The macros that are sent to Milter (mail filter) applications after the
4165 end of the message header. See MILTER_README for a list of available
4166 macro names and their meanings.
4167 This feature is available in Postfix 2.5 and later.
4169
4171 Optional lookup tables for content inspection of message headers that
4172 are produced by Milter applications. See the header_checks(5) manual
4173 page available actions. Currently, PREPEND is not implemented.
4174 The following example sends all mail that is marked as SPAM to a spam
4176 handling machine. Note that matches are case-insensitive by default.
4177 /etc/postfix/main.cf:
4179 milter_header_checks = pcre:/etc/postfix/milter_header_checks
4180 /etc/postfix/milter_header_checks:
4182 /^X-SPAM-FLAG:\s+YES/ FILTER mysmtp:sanitizer.example.com:25
4183 The milter_header_checks mechanism could also be used for allowlisting.
4185 For example it could be used to skip heavy content inspection for
4186 DKIM-signed mail from known friendly domains.
4187 This feature is available in Postfix 2.7, and as an optional patch for
4189 Postfix 2.6.
4190
4192 The macros that are sent to Milter (mail filter) applications after the
4193 SMTP HELO or EHLO command. See MILTER_README for a list of available
4194 macro names and their meanings.
4195 This feature is available in Postfix 2.3 and later.
4197
4199 The {daemon_name} macro value for Milter (mail filter) applications.
4200 See MILTER_README for a list of available macro names and their mean‐
4201 ings.
4202 This feature is available in Postfix 2.3 and later.
4204
4206 Optional list of name=value pairs that specify default values for arbi‐
4207 trary macros that Postfix may send to Milter applications. These de‐
4208 faults are used when there is no corresponding information from the
4209 message delivery context.
4210 Specify name=value or {name}=value pairs separated by comma or white‐
4212 space. Enclose a pair in "{}" when a value contains comma or white‐
4213 space (this form ignores whitespace after the enclosing "{", around the
4214 "=", and before the enclosing "}").
4215 This feature is available in Postfix 3.1 and later.
4217
4219 The {v} macro value for Milter (mail filter) applications. See MIL‐
4220 TER_README for a list of available macro names and their meanings.
4221 This feature is available in Postfix 2.3 and later.
4223
4225 The macros that are sent to Milter (mail filter) applications after the
4226 SMTP MAIL FROM command. See MILTER_README for a list of available macro
4227 names and their meanings.
4228 This feature is available in Postfix 2.3 and later.
4230
4232 The mail filter protocol version and optional protocol extensions for
4233 communication with a Milter application; prior to Postfix 2.6 the de‐
4234 fault protocol is 2. Postfix sends this version number during the ini‐
4235 tial protocol handshake. It should match the version number that is
4236 expected by the mail filter application (or by its Milter library).
4237 Protocol versions:
4239 2 Use Sendmail 8 mail filter protocol version 2 (default with
4241 Sendmail version 8.11 .. 8.13 and Postfix version 2.3 .. 2.5).
4242 3 Use Sendmail 8 mail filter protocol version 3.
4244 4 Use Sendmail 8 mail filter protocol version 4.
4246 6 Use Sendmail 8 mail filter protocol version 6 (default with
4248 Sendmail version 8.14 and Postfix version 2.6).
4249 Protocol extensions:
4251 no_header_reply
4253 Specify this when the Milter application will not reply for each
4254 individual message header.
4255 This feature is available in Postfix 2.3 and later.
4257
4259 The macros that are sent to Milter (mail filter) applications after the
4260 SMTP RCPT TO command. See MILTER_README for a list of available macro
4261 names and their meanings.
4262 This feature is available in Postfix 2.3 and later.
4264
4266 The macros that are sent to version 3 or higher Milter (mail filter)
4267 applications after an unknown SMTP command. See MILTER_README for a
4268 list of available macro names and their meanings.
4269 This feature is available in Postfix 2.3 and later.
4271
4273 The maximal length of MIME multipart boundary strings. The MIME proces‐
4274 sor is unable to distinguish between boundary strings that do not dif‐
4275 fer in the first $mime_boundary_length_limit characters.
4276 This feature is available in Postfix 2.0 and later.
4278
4280 Optional lookup tables for content inspection of MIME related message
4281 headers, as described in the header_checks(5) manual page.
4282 This feature is available in Postfix 2.0 and later.
4284
4286 The maximal recursion level that the MIME processor will handle. Post‐
4287 fix refuses mail that is nested deeper than the specified limit.
4288 This feature is available in Postfix 2.0 and later.
4290
4292 The minimal time between attempts to deliver a deferred message; prior
4293 to Postfix 2.4 the default value was 1000s.
4294 This parameter also limits the time an unreachable destination is kept
4296 in the short-term, in-memory, destination status cache.
4297 This parameter should be set greater than or equal to $queue_run_delay.
4299 See also $maximal_backoff_time.
4300 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
4302 The default time unit is s (seconds).
4303
4305 An optional list of non-default Postfix configuration directories;
4306 these directories belong to additional Postfix instances that share the
4307 Postfix executable files and documentation with the default Postfix in‐
4308 stance, and that are started, stopped, etc., together with the default
4309 Postfix instance. Specify a list of pathnames separated by comma or
4310 whitespace.
4311 When $multi_instance_directories is empty, the postfix(1) command runs
4313 in single-instance mode and operates on a single Postfix instance only.
4314 Otherwise, the postfix(1) command runs in multi-instance mode and in‐
4315 vokes the multi-instance manager specified with the multi_in‐
4316 stance_wrapper parameter. The multi-instance manager in turn executes
4317 postfix(1) commands for the default instance and for all Postfix in‐
4318 stances in $multi_instance_directories.
4319 Currently, this parameter setting is ignored except for the default
4321 main.cf file.
4322 This feature is available in Postfix 2.6 and later.
4324
4326 Allow this Postfix instance to be started, stopped, etc., by a
4327 multi-instance manager. By default, new instances are created in a
4328 safe state that prevents them from being started inadvertently. This
4329 parameter is reserved for the multi-instance manager.
4330 This feature is available in Postfix 2.6 and later.
4332
4334 The optional instance group name of this Postfix instance. A group
4335 identifies closely-related Postfix instances that the multi-instance
4336 manager can start, stop, etc., as a unit. This parameter is reserved
4337 for the multi-instance manager.
4338 This feature is available in Postfix 2.6 and later.
4340
4342 The optional instance name of this Postfix instance. This name becomes
4343 also the default value for the syslog_name parameter.
4344 This feature is available in Postfix 2.6 and later.
4346
4348 The pathname of a multi-instance manager command that the postfix(1)
4349 command invokes when the multi_instance_directories parameter value is
4350 non-empty. The pathname may be followed by initial command arguments
4351 separated by whitespace; shell metacharacters such as quotes are not
4352 supported in this context.
4353 The postfix(1) command invokes the manager command with the postfix(1)
4355 non-option command arguments on the manager command line, and with all
4356 installation configuration parameters exported into the manager command
4357 process environment. The manager command in turn invokes the postfix(1)
4358 command for individual Postfix instances as "postfix -c config_direc‐
4359 tory command".
4360 This feature is available in Postfix 2.6 and later.
4362
4364 The numerical Postfix SMTP server response code when a remote SMTP
4365 client request is blocked by the reject_multi_recipient_bounce restric‐
4366 tion.
4367 Do not change this unless you have a complete understanding of RFC
4369 5321.
4370 This feature is available in Postfix 2.1 and later.
4372
4374 The list of domains that are delivered via the $local_transport mail
4375 delivery transport. By default this is the Postfix local(8) delivery
4376 agent which looks up all recipients in /etc/passwd and /etc/aliases.
4377 The SMTP server validates recipient addresses with $local_recipi‐
4378 ent_maps and rejects non-existent recipients. See also the local domain
4379 class in the ADDRESS_CLASS_README file.
4380 The default mydestination value specifies names for the local machine
4382 only. On a mail domain gateway, you should also include $mydomain.
4383 The $local_transport delivery method is also selected for mail ad‐
4385 dressed to user@[the.net.work.address] of the mail system (the IP ad‐
4386 dresses specified with the inet_interfaces and proxy_interfaces parame‐
4387 ters).
4388 Warnings:
4390 • Do not specify the names of virtual domains - those domains are
4392 specified elsewhere. See VIRTUAL_README for more information.
4393 • Do not specify the names of domains that this machine is backup
4395 MX host for. See STANDARD_CONFIGURATION_README for how to set up
4396 backup MX hosts.
4397 • By default, the Postfix SMTP server rejects mail for recipients
4399 not listed with the local_recipient_maps parameter. See the
4400 postconf(5) manual for a description of the local_recipient_maps
4401 and unknown_local_recipient_reject_code parameters.
4402 Specify a list of host or domain names, "/file/name" or "type:table"
4404 patterns, separated by commas and/or whitespace. A "/file/name" pattern
4405 is replaced by its contents; a "type:table" lookup table is matched
4406 when a name matches a lookup key (the lookup result is ignored). Con‐
4407 tinue long lines by starting the next line with whitespace.
4408 Examples:
4410 mydestination = $myhostname, localhost.$mydomain $mydomain
4412 mydestination = $myhostname, localhost.$mydomain www.$mydomain, ftp.$mydomain
4413
4415 The internet domain name of this mail system. The default is to use
4416 $myhostname minus the first component, or "localdomain" (Postfix 2.3
4417 and later). $mydomain is used as a default value for many other con‐
4418 figuration parameters.
4419 Example:
4421 mydomain = domain.tld
4423
4425 The internet hostname of this mail system. The default is to use the
4426 fully-qualified domain name (FQDN) from gethostname(), or to use the
4427 non-FQDN result from gethostname() and append ".$mydomain". $myhost‐
4428 name is used as a default value for many other configuration parame‐
4429 ters.
4430 Example:
4432 myhostname = host.example.com
4434
4436 The list of "trusted" remote SMTP clients that have more privileges
4437 than "strangers".
4438 In particular, "trusted" SMTP clients are allowed to relay mail through
4440 Postfix. See the smtpd_relay_restrictions parameter description in the
4441 postconf(5) manual.
4442 You can specify the list of "trusted" network addresses by hand or you
4444 can let Postfix do it for you (which is the default). See the descrip‐
4445 tion of the mynetworks_style parameter for more information.
4446 If you specify the mynetworks list by hand, Postfix ignores the mynet‐
4448 works_style setting.
4449 Specify a list of network addresses or network/netmask patterns, sepa‐
4451 rated by commas and/or whitespace. Continue long lines by starting the
4452 next line with whitespace.
4453 The netmask specifies the number of bits in the network part of a host
4455 address. You can also specify "/file/name" or "type:table" patterns.
4456 A "/file/name" pattern is replaced by its contents; a "type:table"
4457 lookup table is matched when a table entry matches a lookup string (the
4458 lookup result is ignored).
4459 The list is matched left to right, and the search stops on the first
4461 match. Specify "!pattern" to exclude an address or network block from
4462 the list. The form "!/file/name" is supported only in Postfix version
4463 2.4 and later.
4464 Note 1: Pattern matching of domain names is controlled by the or ab‐
4466 sence of "mynetworks" in the parent_domain_matches_subdomains parameter
4467 value.
4468 Note 2: IP version 6 address information must be specified inside [] in
4470 the mynetworks value, and in files specified with "/file/name". IP
4471 version 6 addresses contain the ":" character, and would otherwise be
4472 confused with a "type:table" pattern.
4473 Examples:
4475 mynetworks = 127.0.0.0/8 168.100.189.0/28
4477 mynetworks = !192.168.0.1, 192.168.0.0/28
4478 mynetworks = 127.0.0.0/8 168.100.189.0/28 [::1]/128 [2001:240:587::]/64
4479 mynetworks = $config_directory/mynetworks
4480 mynetworks = hash:/etc/postfix/network_table
4481
4483 The method to generate the default value for the mynetworks parameter.
4484 This is the list of trusted networks for relay access control etc.
4485 • Specify "mynetworks_style = host" when Postfix should "trust"
4487 only the local machine.
4488 • Specify "mynetworks_style = subnet" when Postfix should "trust"
4490 remote SMTP clients in the same IP subnetworks as the local ma‐
4491 chine. On Linux, this works correctly only with interfaces
4492 specified with the "ifconfig" command.
4493 • Specify "mynetworks_style = class" when Postfix should "trust"
4495 remote SMTP clients in the same IP class A/B/C networks as the
4496 local machine. Caution: this may cause Postfix to "trust" your
4497 entire provider's network. Instead, specify an explicit mynet‐
4498 works list by hand, as described with the mynetworks configura‐
4499 tion parameter.
4500
4502 The domain name that locally-posted mail appears to come from, and that
4503 locally posted mail is delivered to. The default, $myhostname, is ade‐
4504 quate for small sites. If you run a domain with multiple machines, you
4505 should (1) change this to $mydomain and (2) set up a domain-wide alias
4506 database that aliases each user to user@that.users.mailhost.
4507 Example:
4509 myorigin = $mydomain
4511
4513 Optional lookup tables for content inspection of non-MIME message head‐
4514 ers in attached messages, as described in the header_checks(5) manual
4515 page.
4516 This feature is available in Postfix 2.0 and later.
4518
4520 Sendmail compatibility feature that specifies the location of the
4521 newaliases(1) command. This command can be used to rebuild the local(8)
4522 aliases(5) database.
4523
4525 The numerical Postfix SMTP server reply code when a client request is
4526 rejected by the reject_non_fqdn_helo_hostname, reject_non_fqdn_sender
4527 or reject_non_fqdn_recipient restriction.
4528
4530 A list of Milter (mail filter) applications for new mail that does not
4531 arrive via the Postfix smtpd(8) server. This includes local submission
4532 via the sendmail(1) command line, new mail that arrives via the Postfix
4533 qmqpd(8) server, and old mail that is re-injected into the queue with
4534 "postsuper -r". Specify space or comma as separator. See the MIL‐
4535 TER_README document for details.
4536 This feature is available in Postfix 2.3 and later.
4538
4540 The list of error classes that are reported to the postmaster. The de‐
4541 fault is to report only the most serious problems. The paranoid may
4542 wish to turn on the policy (UCE and mail relaying) and protocol error
4543 (broken mail software) reports.
4544 NOTE: postmaster notifications may contain confidential information
4546 such as SASL passwords or message content. It is the system adminis‐
4547 trator's responsibility to treat such information with care.
4548 The error classes are:
4550 bounce (also implies 2bounce)
4552 Send the postmaster copies of the headers of bounced mail, and
4553 send transcripts of SMTP sessions when Postfix rejects mail. The
4554 notification is sent to the address specified with the
4555 bounce_notice_recipient configuration parameter (default: post‐
4556 master).
4557 2bounce
4559 Send undeliverable bounced mail to the postmaster. The notifica‐
4560 tion is sent to the address specified with the 2bounce_no‐
4561 tice_recipient configuration parameter (default: postmaster).
4562 data Send the postmaster a transcript of the SMTP session with an er‐
4564 ror because a critical data file was unavailable. The notifica‐
4565 tion is sent to the address specified with the error_notice_re‐
4566 cipient configuration parameter (default: postmaster).
4567 This feature is available in Postfix 2.9 and later.
4568 delay Send the postmaster copies of the headers of delayed mail (see
4570 delay_warning_time). The notification is sent to the address
4571 specified with the delay_notice_recipient configuration parame‐
4572 ter (default: postmaster).
4573 policy Send the postmaster a transcript of the SMTP session when a
4575 client request was rejected because of (UCE) policy. The notifi‐
4576 cation is sent to the address specified with the error_no‐
4577 tice_recipient configuration parameter (default: postmaster).
4578 protocol
4580 Send the postmaster a transcript of the SMTP session in case of
4581 client or server protocol errors. The notification is sent to
4582 the address specified with the error_notice_recipient configura‐
4583 tion parameter (default: postmaster).
4584 resource
4586 Inform the postmaster of mail not delivered due to resource
4587 problems. The notification is sent to the address specified
4588 with the error_notice_recipient configuration parameter (de‐
4589 fault: postmaster).
4590 software
4592 Inform the postmaster of mail not delivered due to software
4593 problems. The notification is sent to the address specified
4594 with the error_notice_recipient configuration parameter (de‐
4595 fault: postmaster).
4596 Examples:
4598 notify_classes = bounce, delay, policy, protocol, resource, software
4600 notify_classes = 2bounce, resource, software
4601
4603 The numerical reply code when the Postfix SMTP server rejects a sender
4604 or recipient address because its domain has a nullmx DNS record (an MX
4605 record with an empty hostname). This is one of the possible replies
4606 from the restrictions reject_unknown_sender_domain and reject_un‐
4607 known_recipient_domain.
4608 This feature is available in Postfix 3.0 and later.
4610
4612 The location of the OpenSSL command line program openssl(1). This is
4613 used by the "postfix tls" command to create private keys, certificate
4614 signing requests, self-signed certificates, and to compute public key
4615 digests for DANE TLSA records. In multi-instance environments, this
4616 parameter is always determined from the configuration of the default
4617 Postfix instance.
4618 Example:
4620 /etc/postfix/main.cf:
4622 # NetBSD pkgsrc:
4623 openssl_path = /usr/pkg/bin/openssl
4624 # Local build:
4625 openssl_path = /usr/local/bin/openssl
4626 This feature is available in Postfix 3.1 and later.
4628
4630 Enable special treatment for owner-listname entries in the aliases(5)
4631 file, and don't split owner-listname and listname-request address lo‐
4632 calparts when the recipient_delimiter is set to "-". This feature is
4633 useful for mailing lists.
4634
4636 A list of Postfix features where the pattern "example.com" also matches
4637 subdomains of example.com, instead of requiring an explicit ".exam‐
4638 ple.com" pattern. This is planned backwards compatibility: eventu‐
4639 ally, all Postfix features are expected to require explicit ".exam‐
4640 ple.com" style patterns when you really want to match subdomains.
4641 The following Postfix feature names are supported.
4643 Postfix version 1.0 and later
4645 debug_peer_list, fast_flush_domains, mynetworks, per‐
4646 mit_mx_backup_networks, relay_domains, transport_maps
4647 Postfix version 1.1 and later
4649 qmqpd_authorized_clients, smtpd_access_maps,
4650 Postfix version 2.8 and later
4652 postscreen_access_list
4653 Postfix version 3.0 and later
4655 smtpd_client_event_limit_exceptions
4656
4658 Restrict the use of the permit_mx_backup SMTP access feature to only
4659 domains whose primary MX hosts match the listed networks. The parame‐
4660 ter value syntax is the same as with the mynetworks parameter; note,
4661 however, that the default value is empty.
4662 Pattern matching of domain names is controlled by the presence or ab‐
4664 sence of "permit_mx_backup_networks" in the parent_domain_matches_sub‐
4665 domains parameter value.
4666
4668 The name of the pickup(8) service. This service picks up local mail
4669 submissions from the Postfix maildrop queue.
4670 This feature is available in Postfix 2.0 and later.
4672
4674 Optional filter for the pipe(8) delivery agent to change the delivery
4675 status code or explanatory text of successful or unsuccessful deliver‐
4676 ies. See default_delivery_status_filter for details.
4677 This feature is available in Postfix 3.0 and later.
4679
4681 The numerical Postfix SMTP server response code when a request is re‐
4682 jected by the reject_plaintext_session restriction.
4683 This feature is available in Postfix 2.3 and later.
4685
4687 The name of the postlogd(8) service entry in master.cf. This service
4688 appends logfile records to the file specified with the maillog_file pa‐
4689 rameter.
4690 This feature is available in Postfix 3.4 and later.
4692
4694 How much time a postlogd(8) process may take to process a request be‐
4695 fore it is terminated by a built-in watchdog timer. This is a safety
4696 mechanism that prevents postlogd(8) from becoming non-responsive due to
4697 a bug in Postfix itself or in system software. This limit cannot be set
4698 under 10s.
4699 Specify a non-zero time value (an integral value plus an optional
4701 one-letter suffix that specifies the time unit). Time units: s (sec‐
4702 onds), m (minutes), h (hours), d (days), w (weeks).
4703 This feature is available in Postfix 3.4 and later.
4705
4707 The postfix(1) commands that the postmulti(1) instance manager treats
4708 as "control" commands, that operate on running instances. For these
4709 commands, disabled instances are skipped.
4710 This feature is available in Postfix 2.6 and later.
4712
4714 The postfix(1) commands that the postmulti(1) instance manager treats
4715 as "start" commands. For these commands, disabled instances are
4716 "checked" rather than "started", and failure to "start" a member in‐
4717 stance of an instance group will abort the start-up of later instances.
4718 This feature is available in Postfix 2.6 and later.
4720
4722 The postfix(1) commands that the postmulti(1) instance manager treats
4723 as "stop" commands. For these commands, disabled instances are skipped,
4724 and enabled instances are processed in reverse order.
4725 This feature is available in Postfix 2.6 and later.
4727
4729 Permanent allow/denylist for remote SMTP client IP addresses.
4730 postscreen(8) searches this list immediately after a remote SMTP client
4731 connects. Specify a comma- or whitespace-separated list of commands
4732 (in upper or lower case) or lookup tables. The search stops upon the
4733 first command that fires for the client IP address.
4734 permit_mynetworks
4736 Allowlist the client and terminate the search if the client IP
4737 address matches $mynetworks. Do not subject the client to any
4738 before/after 220 greeting tests. Pass the connection immedi‐
4739 ately to a Postfix SMTP server process.
4740 Pattern matching of domain names is controlled by the presence
4741 or absence of "postscreen_access_list" in the parent_do‐
4742 main_matches_subdomains parameter value.
4743 type:table
4745 Query the specified lookup table. Each table lookup result is an
4746 access list, except that access lists inside a table cannot
4747 specify type:table entries.
4748 To discourage the use of hash, btree, etc. tables, there is no
4749 support for substring matching like smtpd(8). Use CIDR tables
4750 instead.
4751 permit
4753 Allowlist the client and terminate the search. Do not subject
4754 the client to any before/after 220 greeting tests. Pass the con‐
4755 nection immediately to a Postfix SMTP server process.
4756 reject
4758 Denylist the client and terminate the search. Subject the client
4759 to the action configured with the postscreen_denylist_action
4760 configuration parameter.
4761 dunno All postscreen(8) access lists implicitly have this command at
4763 the end.
4764 When dunno is executed inside a lookup table, return from the
4765 lookup table and evaluate the next command.
4766 When dunno is executed outside a lookup table, terminate the
4767 search, and subject the client to the configured before/after
4768 220 greeting tests.
4769 Example:
4771 /etc/postfix/main.cf:
4773 postscreen_access_list = permit_mynetworks,
4774 cidr:/etc/postfix/postscreen_access.cidr
4775 # Postfix < 3.6 use postscreen_blacklist_action.
4776 postscreen_denylist_action = enforce
4777 /etc/postfix/postscreen_access.cidr:
4779 # Rules are evaluated in the order as specified.
4780 # Denylist 192.168.* except 192.168.0.1.
4781 192.168.0.1 dunno
4782 192.168.0.0/16 reject
4783 This feature is available in Postfix 2.8.
4785
4787 A list of local postscreen(8) server IP addresses where a non-al‐
4788 lowlisted remote SMTP client can obtain postscreen(8)'s temporary al‐
4789 lowlist status. This status is required before the client can talk to a
4790 Postfix SMTP server process. By default, a client can obtain
4791 postscreen(8)'s allowlist status on any local postscreen(8) server IP
4792 address.
4793 When postscreen(8) listens on both primary and backup MX addresses, the
4795 postscreen_allowlist_interfaces parameter can be configured to give the
4796 temporary allowlist status only when a client connects to a primary MX
4797 address. Once a client is allowlisted it can talk to a Postfix SMTP
4798 server on any address. Thus, clients that connect only to backup MX ad‐
4799 dresses will never become allowlisted, and will never be allowed to
4800 talk to a Postfix SMTP server process.
4801 Specify a list of network addresses or network/netmask patterns, sepa‐
4803 rated by commas and/or whitespace. The netmask specifies the number of
4804 bits in the network part of a host address. Continue long lines by
4805 starting the next line with whitespace.
4806 You can also specify "/file/name" or "type:table" patterns. A
4808 "/file/name" pattern is replaced by its contents; a "type:table" lookup
4809 table is matched when a table entry matches a lookup string (the lookup
4810 result is ignored).
4811 The list is matched left to right, and the search stops on the first
4813 match. Specify "!pattern" to exclude an address or network block from
4814 the list.
4815 Note: IP version 6 address information must be specified inside [] in
4817 the postscreen_allowlist_interfaces value, and in files specified with
4818 "/file/name". IP version 6 addresses contain the ":" character, and
4819 would otherwise be confused with a "type:table" pattern.
4820 Example:
4822 /etc/postfix/main.cf:
4824 # Don't allowlist connections to the backup IP address.
4825 # Postfix < 3.6 use postscreen_whitelist_interfaces.
4826 postscreen_allowlist_interfaces = !168.100.189.8, static:all
4827 This feature is available in Postfix 3.6 and later.
4829 Available as postscreen_whitelist_interfaces in Postfix 2.9 - 3.5.
4831
4833 The action that postscreen(8) takes when a remote SMTP client sends a
4834 bare newline character, that is, a newline not preceded by carriage re‐
4835 turn. Specify one of the following:
4836 ignore Ignore the failure of this test. Allow other tests to complete.
4838 Do not repeat this test before some the result from some other
4839 test expires. This option is useful for testing and collecting
4840 statistics without blocking mail permanently.
4841 enforce
4843 Allow other tests to complete. Reject attempts to deliver mail
4844 with a 550 SMTP reply, and log the helo/sender/recipient infor‐
4845 mation. Repeat this test the next time the client connects.
4846 drop Drop the connection immediately with a 521 SMTP reply. Repeat
4848 this test the next time the client connects.
4849 This feature is available in Postfix 2.8.
4851
4853 Enable "bare newline" SMTP protocol tests in the postscreen(8) server.
4854 These tests are expensive: a remote SMTP client must disconnect after
4855 it passes the test, before it can talk to a real Postfix SMTP server.
4856 This feature is available in Postfix 2.8.
4858
4860 The amount of time that postscreen(8) will use the result from a suc‐
4861 cessful "bare newline" SMTP protocol test. During this time, the client
4862 IP address is excluded from this test. The default is long because a
4863 remote SMTP client must disconnect after it passes the test, before it
4864 can talk to a real Postfix SMTP server.
4865 Specify a non-zero time value (an integral value plus an optional
4867 one-letter suffix that specifies the time unit). Time units: s (sec‐
4868 onds), m (minutes), h (hours), d (days), w (weeks).
4869 This feature is available in Postfix 2.8.
4871
4873 Renamed to postscreen_denylist_action in Postfix 3.6.
4874 This feature is available in Postfix 2.8 - 3.5.
4876
4878 The amount of time between postscreen(8) cache cleanup runs. Cache
4879 cleanup increases the load on the cache database and should therefore
4880 not be run frequently. This feature requires that the cache database
4881 supports the "delete" and "sequence" operators. Specify a zero inter‐
4882 val to disable cache cleanup.
4883 After each cache cleanup run, the postscreen(8) daemon logs the number
4885 of entries that were retained and dropped. A cleanup run is logged as
4886 "partial" when the daemon terminates early after "postfix reload",
4887 "postfix stop", or no requests for $max_idle seconds.
4888 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
4890 This feature is available in Postfix 2.8.
4892
4894 Persistent storage for the postscreen(8) server decisions.
4895 To share a postscreen(8) cache between multiple postscreen(8) in‐
4897 stances, use "postscreen_cache_map = proxy:btree:/path/to/file". This
4898 requires Postfix version 2.9 or later; earlier proxymap(8) implementa‐
4899 tions don't support cache cleanup. For an alternative approach see the
4900 memcache_table(5) manpage.
4901 This feature is available in Postfix 2.8.
4903
4905 The amount of time that postscreen(8) will cache an expired temporary
4906 allowlist entry before it is removed. This prevents clients from being
4907 logged as "NEW" just because their cache entry expired an hour ago. It
4908 also prevents the cache from filling up with clients that passed some
4909 deep protocol test once and never came back.
4910 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
4912 This feature is available in Postfix 2.8.
4914
4916 tion_count_limit)
4917 How many simultaneous connections any remote SMTP client is allowed to
4918 have with the postscreen(8) daemon. By default, this limit is the same
4919 as with the Postfix SMTP server. Note that the triage process can take
4920 several seconds, with the time spent in postscreen_greet_wait delay,
4921 and with the time spent talking to the postscreen(8) built-in dummy
4922 SMTP protocol engine.
4923 This feature is available in Postfix 2.8.
4925
4927 The limit on the total number of commands per SMTP session for
4928 postscreen(8)'s built-in SMTP protocol engine. This SMTP engine defers
4929 or rejects all attempts to deliver mail, therefore there is no need to
4930 enforce separate limits on the number of junk commands and error com‐
4931 mands.
4932 This feature is available in Postfix 2.8.
4934
4936 A mechanism to transform commands from remote SMTP clients. See
4937 smtpd_command_filter for further details.
4938 This feature is available in Postfix 2.8 and later.
4940
4942 The time limit to read an entire command line with postscreen(8)'s
4943 built-in SMTP protocol engine.
4944 This feature is available in Postfix 2.8.
4946
4948 The action that postscreen(8) takes when a remote SMTP client is perma‐
4949 nently denylisted with the postscreen_access_list parameter. Specify
4950 one of the following:
4951 ignore (default)
4953 Ignore this result. Allow other tests to complete. Repeat this
4954 test the next time the client connects. This option is useful
4955 for testing and collecting statistics without blocking mail.
4956 enforce
4958 Allow other tests to complete. Reject attempts to deliver mail
4959 with a 550 SMTP reply, and log the helo/sender/recipient infor‐
4960 mation. Repeat this test the next time the client connects.
4961 drop Drop the connection immediately with a 521 SMTP reply. Repeat
4963 this test the next time the client connects.
4964 This feature is available in Postfix 3.6 and later.
4966 Available as postscreen_blacklist_action in Postfix 2.8 - 3.5.
4968
4970 Disable the SMTP VRFY command in the postscreen(8) daemon. See dis‐
4971 able_vrfy_command for details.
4972 This feature is available in Postfix 2.8.
4974
4976 card_ehlo_keyword_address_maps)
4977 Lookup tables, indexed by the remote SMTP client address, with case in‐
4978 sensitive lists of EHLO keywords (pipelining, starttls, auth, etc.)
4979 that the postscreen(8) server will not send in the EHLO response to a
4980 remote SMTP client. See smtpd_discard_ehlo_keywords for details. The
4981 table is not searched by hostname for robustness reasons.
4982 This feature is available in Postfix 2.8 and later.
4984
4986 A case insensitive list of EHLO keywords (pipelining, starttls, auth,
4987 etc.) that the postscreen(8) server will not send in the EHLO response
4988 to a remote SMTP client. See smtpd_discard_ehlo_keywords for details.
4989 This feature is available in Postfix 2.8 and later.
4991
4993 The action that postscreen(8) takes when a remote SMTP client's com‐
4994 bined DNSBL score is equal to or greater than a threshold (as defined
4995 with the postscreen_dnsbl_sites and postscreen_dnsbl_threshold parame‐
4996 ters). Specify one of the following:
4997 ignore (default)
4999 Ignore the failure of this test. Allow other tests to complete.
5000 Repeat this test the next time the client connects. This option
5001 is useful for testing and collecting statistics without blocking
5002 mail.
5003 enforce
5005 Allow other tests to complete. Reject attempts to deliver mail
5006 with a 550 SMTP reply, and log the helo/sender/recipient infor‐
5007 mation. Repeat this test the next time the client connects.
5008 drop Drop the connection immediately with a 521 SMTP reply. Repeat
5010 this test the next time the client connects.
5011 This feature is available in Postfix 2.8.
5013
5015 Allow a remote SMTP client to skip "before" and "after 220 greeting"
5016 protocol tests, based on its combined DNSBL score as defined with the
5017 postscreen_dnsbl_sites parameter.
5018 Specify a negative value to enable this feature. When a client passes
5020 the postscreen_dnsbl_allowlist_threshold without having failed other
5021 tests, all pending or disabled tests are flagged as completed with a
5022 time-to-live value equal to postscreen_dnsbl_ttl. When a test was al‐
5023 ready completed, its time-to-live value is updated if it was less than
5024 postscreen_dnsbl_ttl.
5025 This feature is available in Postfix 3.6 and later.
5027 Available as postscreen_dnsbl_whitelist_threshold in Postfix 2.11 -
5029 3.5.
5030
5032 ${postscreen_dnsbl_ttl?{$postscreen_dnsbl_ttl}:{1}}h)
5033 The maximum amount of time that postscreen(8) will use the result from
5034 a successful DNS-based reputation test before a client IP address is
5035 required to pass that test again. If the DNS reply specifies a shorter
5036 TTL value, that value will be used unless it would be smaller than
5037 postscreen_dnsbl_min_ttl.
5038 Specify a non-zero time value (an integral value plus an optional
5040 one-letter suffix that specifies the time unit). Time units: s (sec‐
5041 onds), m (minutes), h (hours), d (days), w (weeks).
5042 This feature is available in Postfix 3.1. The default setting is back‐
5044 wards-compatible with older Postfix versions.
5045
5047 The minimum amount of time that postscreen(8) will use the result from
5048 a successful DNS-based reputation test before a client IP address is
5049 required to pass that test again. If the DNS reply specifies a larger
5050 TTL value, that value will be used unless it would be larger than
5051 postscreen_dnsbl_max_ttl.
5052 Specify a non-zero time value (an integral value plus an optional
5054 one-letter suffix that specifies the time unit). Time units: s (sec‐
5055 onds), m (minutes), h (hours), d (days), w (weeks).
5056 This feature is available in Postfix 3.1.
5058
5060 A mapping from actual DNSBL domain name which includes a secret pass‐
5061 word, to the DNSBL domain name that postscreen will reply with when it
5062 rejects mail. When no mapping is found, the actual DNSBL domain will
5063 be used.
5064 For maximal stability it is best to use a file that is read into memory
5066 such as pcre:, regexp: or texthash: (texthash: is similar to hash:, ex‐
5067 cept a) there is no need to run postmap(1) before the file can be used,
5068 and b) texthash: does not detect changes after the file is read).
5069 Example:
5071 /etc/postfix/main.cf:
5073 postscreen_dnsbl_reply_map = texthash:/etc/postfix/dnsbl_reply
5074 /etc/postfix/dnsbl_reply:
5076 secret.zen.spamhaus.org zen.spamhaus.org
5077 This feature is available in Postfix 2.8.
5079
5081 Optional list of DNS allow/denylist domains, filters and weight fac‐
5082 tors. When the list is non-empty, the dnsblog(8) daemon will query
5083 these domains with the IP addresses of remote SMTP clients, and
5084 postscreen(8) will update an SMTP client's DNSBL score with each
5085 non-error reply.
5086 Caution: when postscreen rejects mail, it replies with the DNSBL domain
5088 name. Use the postscreen_dnsbl_reply_map feature to hide "password" in‐
5089 formation in DNSBL domain names.
5090 When a client's score is equal to or greater than the threshold speci‐
5092 fied with postscreen_dnsbl_threshold, postscreen(8) can drop the con‐
5093 nection with the remote SMTP client.
5094 Specify a list of domain=filter*weight entries, separated by comma or
5096 whitespace.
5097 • When no "=filter" is specified, postscreen(8) will use any
5099 non-error DNSBL reply. Otherwise, postscreen(8) uses only DNSBL
5100 replies that match the filter. The filter has the form d.d.d.d,
5101 where each d is a number, or a pattern inside [] that contains
5102 one or more ";"-separated numbers or number..number ranges.
5103 • When no "*weight" is specified, postscreen(8) increments the re‐
5105 mote SMTP client's DNSBL score by 1. Otherwise, the weight must
5106 be an integral number, and postscreen(8) adds the specified
5107 weight to the remote SMTP client's DNSBL score. Specify a nega‐
5108 tive number for allowlisting.
5109 • When one postscreen_dnsbl_sites entry produces multiple DNSBL
5111 responses, postscreen(8) applies the weight at most once.
5112 Examples:
5114 To use example.com as a high-confidence blocklist, and to block mail
5116 with example.net and example.org only when both agree:
5117 postscreen_dnsbl_threshold = 2
5119 postscreen_dnsbl_sites = example.com*2, example.net, example.org
5120 To filter only DNSBL replies containing 127.0.0.4:
5122 postscreen_dnsbl_sites = example.com=127.0.0.4
5124 This feature is available in Postfix 2.8.
5126
5128 The inclusive lower bound for blocking a remote SMTP client, based on
5129 its combined DNSBL score as defined with the postscreen_dnsbl_sites pa‐
5130 rameter.
5131 This feature is available in Postfix 2.8.
5133
5135 The time limit for DNSBL or DNSWL lookups. This is separate from the
5136 timeouts in the dnsblog(8) daemon which are defined by system re‐
5137 solver(3) routines.
5138 This feature is available in Postfix 3.0.
5140
5142 The amount of time that postscreen(8) will use the result from a suc‐
5143 cessful DNS-based reputation test before a client IP address is re‐
5144 quired to pass that test again.
5145 Specify a non-zero time value (an integral value plus an optional
5147 one-letter suffix that specifies the time unit). Time units: s (sec‐
5148 onds), m (minutes), h (hours), d (days), w (weeks).
5149 This feature is available in Postfix 2.8-3.0. It was replaced by
5151 postscreen_dnsbl_max_ttl in Postfix 3.1.
5152
5154 Renamed to postscreen_dnsbl_allowlist_threshold in Postfix 3.6.
5155 This feature is available in Postfix 2.11 - 3.5.
5157
5159 Mandatory TLS: announce STARTTLS support to remote SMTP clients, and
5160 require that clients use TLS encryption. See smtpd_postscreen_en‐
5161 force_tls for details.
5162 This feature is available in Postfix 2.8 and later. Preferably, use
5164 postscreen_tls_security_level instead.
5165
5167 List of characters that are permitted in postscreen_reject_footer at‐
5168 tribute expansions. See smtpd_expansion_filter for further details.
5169 This feature is available in Postfix 2.8 and later.
5171
5173 List of commands that the postscreen(8) server considers in violation
5174 of the SMTP protocol. See smtpd_forbidden_commands for syntax, and
5175 postscreen_non_smtp_command_action for possible actions.
5176 This feature is available in Postfix 2.8.
5178
5180 The action that postscreen(8) takes when a remote SMTP client speaks
5181 before its turn within the time specified with the
5182 postscreen_greet_wait parameter. Specify one of the following:
5183 ignore (default)
5185 Ignore the failure of this test. Allow other tests to complete.
5186 Repeat this test the next time the client connects. This option
5187 is useful for testing and collecting statistics without blocking
5188 mail.
5189 enforce
5191 Allow other tests to complete. Reject attempts to deliver mail
5192 with a 550 SMTP reply, and log the helo/sender/recipient infor‐
5193 mation. Repeat this test the next time the client connects.
5194 drop Drop the connection immediately with a 521 SMTP reply. Repeat
5196 this test the next time the client connects.
5197 In either case, postscreen(8) will not allowlist the remote SMTP client
5199 IP address.
5200 This feature is available in Postfix 2.8.
5202
5204 The text in the optional "220-text..." server response that
5205 postscreen(8) sends ahead of the real Postfix SMTP server's "220
5206 text..." response, in an attempt to confuse bad SMTP clients so that
5207 they speak before their turn (pre-greet). Specify an empty value to
5208 disable this feature.
5209 This feature is available in Postfix 2.8.
5211
5213 The amount of time that postscreen(8) will use the result from a suc‐
5214 cessful PREGREET test. During this time, the client IP address is ex‐
5215 cluded from this test. The default is relatively short, because a good
5216 client can immediately talk to a real Postfix SMTP server.
5217 Specify a non-zero time value (an integral value plus an optional
5219 one-letter suffix that specifies the time unit). Time units: s (sec‐
5220 onds), m (minutes), h (hours), d (days), w (weeks).
5221 This feature is available in Postfix 2.8.
5223
5225 The amount of time that postscreen(8) will wait for an SMTP client to
5226 send a command before its turn, and for DNS blocklist lookup results to
5227 arrive (default: up to 2 seconds under stress, up to 6 seconds other‐
5228 wise).
5229 Specify a non-zero time value (an integral value plus an optional
5231 one-letter suffix that specifies the time unit).
5232 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
5234 This feature is available in Postfix 2.8.
5236
5238 Require that a remote SMTP client sends HELO or EHLO before commencing
5239 a MAIL transaction.
5240 This feature is available in Postfix 2.8.
5242
5244 The action that postscreen(8) takes when a remote SMTP client sends
5245 non-SMTP commands as specified with the postscreen_forbidden_commands
5246 parameter. Specify one of the following:
5247 ignore Ignore the failure of this test. Allow other tests to complete.
5249 Do not repeat this test before some the result from some other
5250 test expires. This option is useful for testing and collecting
5251 statistics without blocking mail permanently.
5252 enforce
5254 Allow other tests to complete. Reject attempts to deliver mail
5255 with a 550 SMTP reply, and log the helo/sender/recipient infor‐
5256 mation. Repeat this test the next time the client connects.
5257 drop Drop the connection immediately with a 521 SMTP reply. Repeat
5259 this test the next time the client connects. This action is the
5260 same as with the Postfix SMTP server's smtpd_forbidden_commands
5261 feature.
5262 This feature is available in Postfix 2.8.
5264
5266 Enable "non-SMTP command" tests in the postscreen(8) server. These
5267 tests are expensive: a client must disconnect after it passes the test,
5268 before it can talk to a real Postfix SMTP server.
5269 This feature is available in Postfix 2.8.
5271
5273 The amount of time that postscreen(8) will use the result from a suc‐
5274 cessful "non_smtp_command" SMTP protocol test. During this time, the
5275 client IP address is excluded from this test. The default is long be‐
5276 cause a client must disconnect after it passes the test, before it can
5277 talk to a real Postfix SMTP server.
5278 Specify a non-zero time value (an integral value plus an optional
5280 one-letter suffix that specifies the time unit). Time units: s (sec‐
5281 onds), m (minutes), h (hours), d (days), w (weeks).
5282 This feature is available in Postfix 2.8.
5284
5286 The action that postscreen(8) takes when a remote SMTP client sends
5287 multiple commands instead of sending one command and waiting for the
5288 server to respond. Specify one of the following:
5289 ignore Ignore the failure of this test. Allow other tests to complete.
5291 Do not repeat this test before some the result from some other
5292 test expires. This option is useful for testing and collecting
5293 statistics without blocking mail permanently.
5294 enforce
5296 Allow other tests to complete. Reject attempts to deliver mail
5297 with a 550 SMTP reply, and log the helo/sender/recipient infor‐
5298 mation. Repeat this test the next time the client connects.
5299 drop Drop the connection immediately with a 521 SMTP reply. Repeat
5301 this test the next time the client connects.
5302 This feature is available in Postfix 2.8.
5304
5306 Enable "pipelining" SMTP protocol tests in the postscreen(8) server.
5307 These tests are expensive: a good client must disconnect after it
5308 passes the test, before it can talk to a real Postfix SMTP server.
5309 This feature is available in Postfix 2.8.
5311
5313 The amount of time that postscreen(8) will use the result from a suc‐
5314 cessful "pipelining" SMTP protocol test. During this time, the client
5315 IP address is excluded from this test. The default is long because a
5316 good client must disconnect after it passes the test, before it can
5317 talk to a real Postfix SMTP server.
5318 Specify a non-zero time value (an integral value plus an optional
5320 one-letter suffix that specifies the time unit). Time units: s (sec‐
5321 onds), m (minutes), h (hours), d (days), w (weeks).
5322 This feature is available in Postfix 2.8.
5324
5326 The number of clients that can be waiting for service from a real Post‐
5327 fix SMTP server process. When this queue is full, all clients will re‐
5328 ceive a 421 response.
5329 This feature is available in Postfix 2.8.
5331
5333 The number of non-allowlisted clients that can be waiting for a deci‐
5334 sion whether they will receive service from a real Postfix SMTP server
5335 process. When this queue is full, all non-allowlisted clients will re‐
5336 ceive a 421 response.
5337 This feature is available in Postfix 2.8.
5339
5341 Optional information that is appended after a 4XX or 5XX postscreen(8)
5342 server response. See smtpd_reject_footer for further details.
5343 This feature is available in Postfix 2.8 and later.
5345
5347 Optional lookup table for information that is appended after a 4XX or
5348 5XX postscreen(8) server response. See smtpd_reject_footer_maps for
5349 further details.
5350 This feature is available in Postfix 3.4 and later.
5352
5354 The SMTP TLS security level for the postscreen(8) server; when a
5355 non-empty value is specified, this overrides the obsolete parameters
5356 postscreen_use_tls and postscreen_enforce_tls. See smtpd_tls_secu‐
5357 rity_level for details.
5358 This feature is available in Postfix 2.8 and later.
5360
5362 The name of the proxy protocol used by an optional before-postscreen
5363 proxy agent. When a proxy agent is used, this protocol conveys local
5364 and remote address and port information. Specify "postscreen_up‐
5365 stream_proxy_protocol = haproxy" to enable the haproxy protocol; ver‐
5366 sion 2 is supported with Postfix 3.5 and later.
5367 This feature is available in Postfix 2.10 and later.
5369
5371 The time limit for the proxy protocol specified with the postscreen_up‐
5372 stream_proxy_protocol parameter.
5373 This feature is available in Postfix 2.10 and later.
5375
5377 Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
5378 but do not require that clients use TLS encryption.
5379 This feature is available in Postfix 2.8 and later. Preferably, use
5381 postscreen_tls_security_level instead.
5382
5384 How much time a postscreen(8) process may take to respond to a remote
5385 SMTP client command or to perform a cache operation before it is termi‐
5386 nated by a built-in watchdog timer. This is a safety mechanism that
5387 prevents postscreen(8) from becoming non-responsive due to a bug in
5388 Postfix itself or in system software. To avoid false alarms and unnec‐
5389 essary cache corruption this limit cannot be set under 10s.
5390 Specify a non-zero time value (an integral value plus an optional
5392 one-letter suffix that specifies the time unit). Time units: s (sec‐
5393 onds), m (minutes), h (hours), d (days), w (weeks).
5394 This feature is available in Postfix 2.8.
5396
5398 Renamed to postscreen_allowlist_interfaces in Postfix 3.6.
5399 This feature is available in Postfix 2.9 - 3.5.
5401
5403 The message delivery contexts where the Postfix local(8) delivery agent
5404 prepends a Delivered-To: message header with the address that the mail
5405 was delivered to. This information is used for mail delivery loop de‐
5406 tection.
5407 By default, the Postfix local delivery agent prepends a Delivered-To:
5409 header when forwarding mail and when delivering to file (mailbox) and
5410 command. Turning off the Delivered-To: header when forwarding mail is
5411 not recommended.
5412 Specify zero or more of forward, file, or command.
5414 Example:
5416 prepend_delivered_header = forward
5418
5420 The process ID of a Postfix command or daemon process.
5421
5423 The location of Postfix PID files relative to $queue_directory. This
5424 is a read-only parameter.
5425
5427 The process name of a Postfix command or daemon process.
5428
5430 What address lookup tables copy an address extension from the lookup
5431 key to the lookup result.
5432 For example, with a virtual(5) mapping of "joe@example.com =>
5434 joe.user@example.net", the address "joe+foo@example.com" would rewrite
5435 to "joe.user+foo@example.net".
5436 Specify zero or more of canonical, virtual, alias, forward, include or
5438 generic. These cause address extension propagation with canonical(5),
5439 virtual(5), and aliases(5) maps, with local(8) .forward and :include:
5440 file lookups, and with smtp(8) generic maps, respectively.
5441 Note: enabling this feature for types other than canonical and virtual
5443 is likely to cause problems when mail is forwarded to other sites, es‐
5444 pecially with mail that is sent to a mailing list exploder address.
5445 Examples:
5447 propagate_unmatched_extensions = canonical, virtual, alias,
5449 forward, include
5450 propagate_unmatched_extensions = canonical, virtual
5451
5453 The network interface addresses that this mail system receives mail on
5454 by way of a proxy or network address translation unit.
5455 This feature is available in Postfix 2.0 and later.
5457 You must specify your "outside" proxy/NAT addresses when your system is
5459 a backup MX host for other domains, otherwise mail delivery loops will
5460 happen when the primary MX host is down.
5461 Example:
5463 proxy_interfaces = 1.2.3.4
5465
5467 The lookup tables that the proxymap(8) server is allowed to access for
5468 the read-only service.
5469 Specify zero or more "type:name" lookup tables, separated by whitespace
5471 or comma. Table references that don't begin with proxy: are ignored.
5472 This feature is available in Postfix 2.0 and later.
5474
5476 The lookup tables that the proxymap(8) server is allowed to access for
5477 the read-write service. Postfix-owned local database files should be
5478 stored under the Postfix-owned data_directory. Table references that
5479 don't begin with proxy: are ignored.
5480 This feature is available in Postfix 2.5 and later.
5482
5484 The name of the proxymap read-only table lookup service. This service
5485 is normally implemented by the proxymap(8) daemon.
5486 This feature is available in Postfix 2.6 and later.
5488
5490 The name of the proxywrite read-write table lookup service. This ser‐
5491 vice is normally implemented by the proxymap(8) daemon.
5492 This feature is available in Postfix 2.6 and later.
5494
5496 The minimal delay between warnings that a specific destination is clog‐
5497 ging up the Postfix active queue. Specify 0 to disable.
5498 This feature is enabled with the helpful_warnings parameter.
5500 This feature is available in Postfix 2.0 and later.
5502
5504 How much time a Postfix queue manager process may take to handle a re‐
5505 quest before it is terminated by a built-in watchdog timer.
5506 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
5508 The default time unit is s (seconds).
5509 This feature is available in Postfix 2.8 and later.
5511
5513 Obsolete feature: the percentage of delivery resources that a busy mail
5514 system will use up for delivery of a large mailing list message.
5515 This feature exists only in the oqmgr(8) old queue manager. The current
5517 queue manager solves the problem in a better way.
5518
5520 The time limit for the queue manager to send or receive information
5521 over an internal communication channel. The purpose is to break out of
5522 deadlock situations. If the time limit is exceeded the software either
5523 retries or aborts the operation.
5524 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
5526 The default time unit is s (seconds).
5527 This feature is available in Postfix 2.8 and later.
5529
5531 The maximal number of messages in the active queue.
5532
5534 The maximal number of recipients held in memory by the Postfix queue
5535 manager, and the maximal size of the short-term, in-memory "dead" des‐
5536 tination status cache.
5537
5539 The minimal number of in-memory recipients for any message. This takes
5540 priority over any other in-memory recipient limits (i.e., the global
5541 qmgr_message_recipient_limit and the per transport _recipient_limit) if
5542 necessary. The minimum value allowed for this parameter is 1.
5543
5545 What remote QMQP clients are allowed to connect to the Postfix QMQP
5546 server port.
5547 By default, no client is allowed to use the service. This is because
5549 the QMQP server will relay mail to any destination.
5550 Specify a list of client patterns. A list pattern specifies a host
5552 name, a domain name, an internet address, or a network/mask pattern,
5553 where the mask specifies the number of bits in the network part. When
5554 a pattern specifies a file name, its contents are substituted for the
5555 file name; when a pattern is a "type:table" table specification, table
5556 lookup is used instead.
5557 Patterns are separated by whitespace and/or commas. In order to reverse
5559 the result, precede a pattern with an exclamation point (!). The form
5560 "!/file/name" is supported only in Postfix version 2.4 and later.
5561 Pattern matching of domain names is controlled by the presence or ab‐
5563 sence of "qmqpd_authorized_clients" in the parent_domain_matches_subdo‐
5564 mains parameter value.
5565 Example:
5567 qmqpd_authorized_clients = !192.168.0.1, 192.168.0.0/24
5569
5571 Enable logging of the remote QMQP client port in addition to the host‐
5572 name and IP address. The logging format is "host[address]:port".
5573 This feature is available in Postfix 2.5 and later.
5575
5577 How long the Postfix QMQP server will pause before sending a negative
5578 reply to the remote QMQP client. The purpose is to slow down confused
5579 or malicious clients.
5580 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
5582 The default time unit is s (seconds).
5583
5585 The time limit for sending or receiving information over the network.
5586 If a read or write operation blocks for more than $qmqpd_timeout sec‐
5587 onds the Postfix QMQP server gives up and disconnects.
5588 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
5590 The default time unit is s (seconds).
5591
5593 The location of the Postfix top-level queue directory. This is the root
5594 directory of Postfix daemon processes that run chrooted.
5595
5597 The maximal number of (name=value) attributes that may be stored in a
5598 Postfix queue file. The limit is enforced by the cleanup(8) server.
5599 This feature is available in Postfix 2.0 and later.
5601
5603 The minimal amount of free space in bytes in the queue file system that
5604 is needed to receive mail. This is currently used by the Postfix SMTP
5605 server to decide if it will accept any mail at all.
5606 By default, the Postfix SMTP server rejects MAIL FROM commands when the
5608 amount of free space is less than 1.5*$message_size_limit (Postfix ver‐
5609 sion 2.1 and later). To specify a higher minimum free space limit,
5610 specify a queue_minfree value that is at least 1.5*$message_size_limit.
5611 With Postfix versions 2.0 and earlier, a queue_minfree value of zero
5613 means there is no minimum required amount of free space.
5614
5616 The time between deferred queue scans by the queue manager; prior to
5617 Postfix 2.4 the default value was 1000s.
5618 This parameter should be set less than or equal to $minimal_back‐
5620 off_time. See also $maximal_backoff_time.
5621 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
5623 The default time unit is s (seconds).
5624
5626 The name of the qmgr(8) service. This service manages the Postfix queue
5627 and schedules delivery requests.
5628 This feature is available in Postfix 2.0 and later.
5630
5632 Optional lookup tables with RBL response templates. The tables are in‐
5633 dexed by the RBL domain name. By default, Postfix uses the default tem‐
5634 plate as specified with the default_rbl_reply configuration parameter.
5635 See there for a discussion of the syntax of RBL reply templates.
5636 This feature is available in Postfix 2.0 and later.
5638
5640 The location of Postfix README files that describe how to build, con‐
5641 figure or operate a specific Postfix subsystem or feature.
5642
5644 Enable or disable recipient validation, built-in content filtering, or
5645 address mapping. Typically, these are specified in master.cf as com‐
5646 mand-line arguments for the smtpd(8), qmqpd(8) or pickup(8) daemons.
5647 Specify zero or more of the following options. The options override
5649 main.cf settings and are either implemented by smtpd(8), qmqpd(8), or
5650 pickup(8) themselves, or they are forwarded to the cleanup server.
5651 no_unknown_recipient_checks
5653 Do not try to reject unknown recipients (SMTP server only).
5654 This is typically specified AFTER an external content filter.
5655 no_address_mappings
5657 Disable canonical address mapping, virtual alias map expansion,
5658 address masquerading, and automatic BCC (blind carbon-copy) re‐
5659 cipients. This is typically specified BEFORE an external content
5660 filter.
5661 no_header_body_checks
5663 Disable header/body_checks. This is typically specified AFTER an
5664 external content filter.
5665 no_milters
5667 Disable Milter (mail filter) applications. This is typically
5668 specified AFTER an external content filter.
5669 Note: when the "BEFORE content filter" receive_override_options setting
5671 is specified in the main.cf file, specify the "AFTER content filter"
5672 receive_override_options setting in master.cf (and vice versa).
5673 Examples:
5675 receive_override_options =
5677 no_unknown_recipient_checks, no_header_body_checks
5678 receive_override_options = no_address_mappings
5679 This feature is available in Postfix 2.1 and later.
5681
5683 Optional BCC (blind carbon-copy) address lookup tables, indexed by re‐
5684 cipient address. The BCC address (multiple results are not supported)
5685 is added when mail enters from outside of Postfix.
5686 Specify zero or more "type:name" lookup tables, separated by whitespace
5688 or comma. Tables will be searched in the specified order until a match
5689 is found.
5690 The table search order is as follows:
5692 • Look up the "user+extension@domain.tld" address including the
5694 optional address extension.
5695 • Look up the "user@domain.tld" address without the optional ad‐
5697 dress extension.
5698 • Look up the "user+extension" address local part when the recipi‐
5700 ent domain equals $myorigin, $mydestination, $inet_interfaces or
5701 $proxy_interfaces.
5702 • Look up the "user" address local part when the recipient domain
5704 equals $myorigin, $mydestination, $inet_interfaces or $proxy_in‐
5705 terfaces.
5706 • Look up the "@domain.tld" part.
5708 Note: with Postfix 2.3 and later the BCC address is added as if it was
5710 specified with NOTIFY=NONE. The sender will not be notified when the
5711 BCC address is undeliverable, as long as all down-stream software im‐
5712 plements RFC 3461.
5713 Note: with Postfix 2.2 and earlier the sender will unconditionally be
5715 notified when the BCC address is undeliverable.
5716 Note: automatic BCC recipients are produced only for new mail. To
5718 avoid mailer loops, automatic BCC recipients are not generated after
5719 Postfix forwards mail internally, or after Postfix generates mail it‐
5720 self.
5721 Example:
5723 recipient_bcc_maps = hash:/etc/postfix/recipient_bcc
5725 After a change, run "postmap /etc/postfix/recipient_bcc".
5727 This feature is available in Postfix 2.1 and later.
5729
5731 What addresses are subject to recipient_canonical_maps address mapping.
5732 By default, recipient_canonical_maps address mapping is applied to en‐
5733 velope recipient addresses, and to header recipient addresses.
5734 Specify one or more of: envelope_recipient, header_recipient
5736 This feature is available in Postfix 2.2 and later.
5738
5740 Optional address mapping lookup tables for envelope and header recipi‐
5741 ent addresses. The table format and lookups are documented in canoni‐
5742 cal(5).
5743 Note: $recipient_canonical_maps is processed before $canonical_maps.
5745 Example:
5747 recipient_canonical_maps = hash:/etc/postfix/recipient_canonical
5749
5751 The set of characters that can separate an email address localpart,
5752 user name, or a .forward file name from its extension. For example,
5753 with "recipient_delimiter = +", the software tries user+foo@example.com
5754 before trying user@example.com, user+foo before trying user, and .for‐
5755 ward+foo before trying .forward.
5756 More formally, an email address localpart or user name is separated
5758 from its extension by the first character that matches the recipi‐
5759 ent_delimiter set. The delimiter character and extension may then be
5760 used to generate an extended .forward file name. This implementation
5761 recognizes one delimiter character and one extension per email address
5762 localpart or email address. With Postfix 2.10 and earler, the recipi‐
5763 ent_delimiter specifies a single character.
5764 See canonical(5), local(8), relocated(5) and virtual(5) for the effects
5766 of recipient_delimiter on lookups in aliases, canonical, virtual, and
5767 relocated maps, and see the propagate_unmatched_extensions parameter
5768 for propagating an extension from one email address to another.
5769 When used in command_execution_directory, forward_path, or luser_relay,
5771 ${recipient_delimiter} is replaced with the actual recipient delimiter
5772 that was found in the recipient email address (Postfix 2.11 and later),
5773 or it is replaced with the main.cf recipient_delimiter parameter value
5774 (Postfix 2.10 and earlier).
5775 The recipient_delimiter is not applied to the mailer-daemon address,
5777 the postmaster address, or the double-bounce address. With the default
5778 "owner_request_special = yes" setting, the recipient_delimiter is also
5779 not applied to addresses with the special "owner-" prefix or the spe‐
5780 cial "-request" suffix.
5781 Examples:
5783 # Handle Postfix-style extensions.
5785 recipient_delimiter = +
5786 # Handle both Postfix and qmail extensions (Postfix 2.11 and later).
5788 recipient_delimiter = +-
5789 # Use .forward for mail without address extension, and for mail with
5791 # an unrecognized address extension.
5792 forward_path = $home/.forward${recipient_delimiter}${extension},
5793 $home/.forward
5794
5796 The numerical Postfix SMTP server response code when a remote SMTP
5797 client request is rejected by the "reject" restriction.
5798 Do not change this unless you have a complete understanding of RFC
5800 5321.
5801
5803 The Postfix SMTP server's action when a reject-type restriction fails
5804 due to a temporary error condition. Specify "defer" to defer the remote
5805 SMTP client request immediately. With the default "defer_if_permit" ac‐
5806 tion, the Postfix SMTP server continues to look for opportunities to
5807 reject mail, and defers the client request only if it would otherwise
5808 be accepted.
5809 For finer control, see: unverified_recipient_tempfail_action, unveri‐
5811 fied_sender_tempfail_action, unknown_address_tempfail_action, and un‐
5812 known_helo_hostname_tempfail_action.
5813 This feature is available in Postfix 2.6 and later.
5815
5817 List of tables with remote SMTP client-certificate fingerprints or pub‐
5818 lic key fingerprints (Postfix 2.9 and later) for which the Postfix SMTP
5819 server will allow access with the permit_tls_clientcerts feature. The
5820 fingerprint digest algorithm is configurable via the smtpd_tls_finger‐
5821 print_digest parameter (hard-coded as md5 prior to Postfix version
5822 2.5).
5823 The default algorithm is sha256 with Postfix >= 3.6 and the compatibil‐
5825 ity_level set to 3.6 or higher. With Postfix <= 3.5, the default algo‐
5826 rithm is md5. The best-practice algorithm is now sha256. Recent ad‐
5827 vances in hash function cryptanalysis have led to md5 and sha1 being
5828 deprecated in favor of sha256. However, as long as there are no known
5829 "second pre-image" attacks against the older algorithms, their use in
5830 this context, though not recommended, is still likely safe.
5831 Postfix lookup tables are in the form of (key, value) pairs. Since we
5833 only need the key, the value can be chosen freely, e.g. the name of
5834 the user or host: D7:04:2F:A7:0B:8C:A5:21:FA:31:77:E1:41:8A:EE:80
5835 lutzpc.at.home
5836 Example:
5838 relay_clientcerts = hash:/etc/postfix/relay_clientcerts
5840 For more fine-grained control, use check_ccert_access to select an ap‐
5842 propriate access(5) policy for each client. See RESTRIC‐
5843 TION_CLASS_README.
5844 This feature is available with Postfix version 2.2.
5846
5848 rency_limit)
5849 The maximal number of parallel deliveries to the same destination via
5850 the relay message delivery transport. This limit is enforced by the
5851 queue manager. The message delivery transport name is the first field
5852 in the entry in the master.cf file.
5853 This feature is available in Postfix 2.0 and later.
5855
5857 ent_limit)
5858 The maximal number of recipients per message for the relay message de‐
5859 livery transport. This limit is enforced by the queue manager. The mes‐
5860 sage delivery transport name is the first field in the entry in the
5861 master.cf file.
5862 Setting this parameter to a value of 1 changes the meaning of re‐
5864 lay_destination_concurrency_limit from concurrency per domain into con‐
5865 currency per recipient.
5866 This feature is available in Postfix 2.0 and later.
5868
5870 What destination domains (and subdomains thereof) this system will re‐
5871 lay mail to. For details about how the relay_domains value is used, see
5872 the description of the permit_auth_destination and reject_unauth_desti‐
5873 nation SMTP recipient restrictions.
5874 Domains that match $relay_domains are delivered with the $relay_trans‐
5876 port mail delivery transport. The SMTP server validates recipient ad‐
5877 dresses with $relay_recipient_maps and rejects non-existent recipients.
5878 See also the relay domains address class in the ADDRESS_CLASS_README
5879 file.
5880 Note: Postfix will not automatically forward mail for domains that list
5882 this system as their primary or backup MX host. See the per‐
5883 mit_mx_backup restriction in the postconf(5) manual page.
5884 Specify a list of host or domain names, "/file/name" patterns or
5886 "type:table" lookup tables, separated by commas and/or whitespace.
5887 Continue long lines by starting the next line with whitespace. A
5888 "/file/name" pattern is replaced by its contents; a "type:table" lookup
5889 table is matched when a (parent) domain appears as lookup key. Specify
5890 "!pattern" to exclude a domain from the list. The form "!/file/name" is
5891 supported only in Postfix version 2.4 and later.
5892 Pattern matching of domain names is controlled by the presence or ab‐
5894 sence of "relay_domains" in the parent_domain_matches_subdomains param‐
5895 eter value.
5896
5898 The numerical Postfix SMTP server response code when a client request
5899 is rejected by the reject_unauth_destination recipient restriction.
5900 Do not change this unless you have a complete understanding of RFC
5902 5321.
5903
5905 Optional lookup tables with all valid addresses in the domains that
5906 match $relay_domains. Specify @domain as a wild-card for domains that
5907 have no valid recipient list, and become a source of backscatter mail:
5908 Postfix accepts spam for non-existent recipients and then floods inno‐
5909 cent people with undeliverable mail. Technically, tables listed with
5910 $relay_recipient_maps are used as lists: Postfix needs to know only if
5911 a lookup string is found or not, but it does not use the result from
5912 table lookup.
5913 Specify zero or more "type:name" lookup tables, separated by whitespace
5915 or comma. Tables will be searched in the specified order until a match
5916 is found.
5917 If this parameter is non-empty, then the Postfix SMTP server will re‐
5919 ject mail to unknown relay users. This feature is off by default.
5920 See also the relay domains address class in the ADDRESS_CLASS_README
5922 file.
5923 Example:
5925 relay_recipient_maps = hash:/etc/postfix/relay_recipients
5927 This feature is available in Postfix 2.0 and later.
5929
5931 The default mail delivery transport and next-hop destination for remote
5932 delivery to domains listed with $relay_domains. In order of decreasing
5933 precedence, the nexthop destination is taken from $relay_transport,
5934 $sender_dependent_relayhost_maps, $relayhost, or from the recipient do‐
5935 main. This information can be overruled with the transport(5) table.
5936 Specify a string of the form transport:nexthop, where transport is the
5938 name of a mail delivery transport defined in master.cf. The :nexthop
5939 destination is optional; its syntax is documented in the manual page of
5940 the corresponding delivery agent.
5941 See also the relay domains address class in the ADDRESS_CLASS_README
5943 file.
5944 This feature is available in Postfix 2.0 and later.
5946
5948 The next-hop destination(s) for non-local mail; overrides non-local do‐
5949 mains in recipient addresses. This information is overruled with re‐
5950 lay_transport, sender_dependent_default_transport_maps, default_trans‐
5951 port, sender_dependent_relayhost_maps and with the transport(5) table.
5952 On an intranet, specify the organizational domain name. If your inter‐
5954 nal DNS uses no MX records, specify the name of the intranet gateway
5955 host instead.
5956 In the case of SMTP or LMTP delivery, specify one or more destinations
5958 in the form of a domain name, hostname, hostname:port, [hostname]:port,
5959 [hostaddress] or [hostaddress]:port, separated by comma or whitespace.
5960 The form [hostname] turns off MX lookups. Multiple destinations are
5961 supported in Postfix 3.5 and later.
5962 If you're connected via UUCP, see the UUCP_README file for useful in‐
5964 formation.
5965 Examples:
5967 relayhost = $mydomain
5969 relayhost = [gateway.example.com]
5970 relayhost = mail1.example:587, mail2.example:587
5971 relayhost = [an.ip.add.ress]
5972
5974 Optional lookup tables with new contact information for users or do‐
5975 mains that no longer exist. The table format and lookups are docu‐
5976 mented in relocated(5).
5977 Specify zero or more "type:name" lookup tables, separated by whitespace
5979 or comma. Tables will be searched in the specified order until a match
5980 is found.
5981 If you use this feature, run "postmap /etc/postfix/relocated" to build
5983 the necessary DBM or DB file after change, then "postfix reload" to
5984 make the changes visible.
5985 Examples:
5987 relocated_maps = dbm:/etc/postfix/relocated
5989 relocated_maps = hash:/etc/postfix/relocated
5990
5992 Don't rewrite message headers from remote clients at all when this pa‐
5993 rameter is empty; otherwise, rewrite message headers and append the
5994 specified domain name to incomplete addresses. The local_header_re‐
5995 write_clients parameter controls what clients Postfix considers local.
5996 Examples:
5998 The safe setting: append "domain.invalid" to incomplete header ad‐
6000 dresses from remote SMTP clients, so that those addresses cannot be
6001 confused with local addresses.
6002 remote_header_rewrite_domain = domain.invalid
6004 The default, purist, setting: don't rewrite headers from remote clients
6006 at all.
6007 remote_header_rewrite_domain =
6009
6011 Require that a local(8) recipient's home directory exists before mail
6012 delivery is attempted. By default this test is disabled. It can be
6013 useful for environments that import home directories to the mail server
6014 (IMPORTING HOME DIRECTORIES IS NOT RECOMMENDED).
6015
6017 Reset the local(8) delivery agent's idea of the owner-alias attribute,
6018 when delivering mail to a child alias that does not have its own owner
6019 alias.
6020 This feature is available in Postfix 2.8 and later. With older Postfix
6022 releases, the behavior is as if this parameter is set to "yes".
6023 As documented in aliases(5), when an alias name has a companion alias
6025 named owner-name, this will replace the envelope sender address, so
6026 that delivery errors will be reported to the owner alias instead of the
6027 sender. This configuration is recommended for mailing lists.
6028 A less known property of the owner alias is that it also forces the lo‐
6030 cal(8) delivery agent to write local and remote addresses from alias
6031 expansion to a new queue file, instead of attempting to deliver mail to
6032 local addresses as soon as they come out of alias expansion.
6033 Writing local addresses from alias expansion to a new queue file allows
6035 for robust handling of temporary delivery errors: errors with one local
6036 member have no effect on deliveries to other members of the list. On
6037 the other hand, delivery to local addresses as soon as they come out of
6038 alias expansion is fragile: a temporary error with one local address
6039 from alias expansion will cause the entire alias to be expanded repeat‐
6040 edly until the error goes away, or until the message expires in the
6041 queue. In that case, a problem with one list member results in multi‐
6042 ple message deliveries to other list members.
6043 The default behavior of Postfix 2.8 and later is to keep the
6045 owner-alias attribute of the parent alias, when delivering mail to a
6046 child alias that does not have its own owner alias. Then, local ad‐
6047 dresses from that child alias will be written to a new queue file, and
6048 a temporary error with one local address will not affect delivery to
6049 other mailing list members.
6050 Unfortunately, older Postfix releases reset the owner-alias attribute
6052 when delivering mail to a child alias that does not have its own owner
6053 alias. To be precise, this resets only the decision to create a new
6054 queue file, not the decision to override the envelope sender address.
6055 The local(8) delivery agent then attempts to deliver local addresses as
6056 soon as they come out of child alias expansion. If delivery to any ad‐
6057 dress from child alias expansion fails with a temporary error condi‐
6058 tion, the entire mailing list may be expanded repeatedly until the mail
6059 expires in the queue, resulting in multiple deliveries of the same mes‐
6060 sage to mailing list members.
6061
6063 Resolve a recipient address safely instead of correctly, by looking in‐
6064 side quotes.
6065 By default, the Postfix address resolver does not quote the address lo‐
6067 calpart as per RFC 822, so that additional @ or % or ! operators re‐
6068 main visible. This behavior is safe but it is also technically incor‐
6069 rect.
6070 If you specify "resolve_dequoted_address = no", then the Postfix re‐
6072 solver will not know about additional @ etc. operators in the address
6073 localpart. This opens opportunities for obscure mail relay attacks with
6074 user@domain@domain addresses when Postfix provides backup MX service
6075 for Sendmail systems.
6076
6078 Resolve an address that ends in the "@" null domain as if the local
6079 hostname were specified, instead of rejecting the address as invalid.
6080 This feature is available in Postfix 2.1 and later. Earlier versions
6082 always resolve the null domain as the local hostname.
6083 The Postfix SMTP server uses this feature to reject mail from or to ad‐
6085 dresses that end in the "@" null domain, and from addresses that re‐
6086 write into a form that ends in the "@" null domain.
6087
6089 Resolve "user@ipaddress" as "user@[ipaddress]", instead of rejecting
6090 the address as invalid.
6091 This feature is available in Postfix 2.3 and later.
6093
6095 Avoid logging that implies white is better than black. Instead use 'al‐
6096 lowlist', 'denylist', and variations of those words.
6097 This feature is available in Postfix 3.6 and later.
6099
6101 The name of the address rewriting service. This service rewrites ad‐
6102 dresses to standard form and resolves them to a (delivery method,
6103 next-hop host, recipient) triple.
6104 This feature is available in Postfix 2.0 and later.
6106
6108 The name of the directory with example Postfix configuration files.
6109 Starting with Postfix 2.1, these files have been replaced with the
6110 postconf(5) manual page.
6111
6113 When authenticating to a remote SMTP or LMTP server with the default
6114 setting "no", send no SASL authoriZation ID (authzid); send only the
6115 SASL authentiCation ID (authcid) plus the authcid's password.
6116 The non-default setting "yes" enables the behavior of older Postfix
6118 versions. These always send a SASL authzid that is equal to the SASL
6119 authcid, but this causes interoperability problems with some SMTP
6120 servers.
6121 This feature is available in Postfix 2.4.4 and later.
6123
6125 This parameter should not be used. It was replaced by sender_depen‐
6126 dent_relayhost_maps in Postfix version 2.3.
6127
6129 Optional BCC (blind carbon-copy) address lookup tables, indexed by
6130 sender address. The BCC address (multiple results are not supported)
6131 is added when mail enters from outside of Postfix.
6132 Specify zero or more "type:name" lookup tables, separated by whitespace
6134 or comma. Tables will be searched in the specified order until a match
6135 is found.
6136 The table search order is as follows:
6138 • Look up the "user+extension@domain.tld" address including the
6140 optional address extension.
6141 • Look up the "user@domain.tld" address without the optional ad‐
6143 dress extension.
6144 • Look up the "user+extension" address local part when the sender
6146 domain equals $myorigin, $mydestination, $inet_interfaces or
6147 $proxy_interfaces.
6148 • Look up the "user" address local part when the sender domain
6150 equals $myorigin, $mydestination, $inet_interfaces or $proxy_in‐
6151 terfaces.
6152 • Look up the "@domain.tld" part.
6154 Note: with Postfix 2.3 and later the BCC address is added as if it was
6156 specified with NOTIFY=NONE. The sender will not be notified when the
6157 BCC address is undeliverable, as long as all down-stream software im‐
6158 plements RFC 3461.
6159 Note: with Postfix 2.2 and earlier the sender will be notified when the
6161 BCC address is undeliverable.
6162 Note: automatic BCC recipients are produced only for new mail. To
6164 avoid mailer loops, automatic BCC recipients are not generated after
6165 Postfix forwards mail internally, or after Postfix generates mail it‐
6166 self.
6167 Example:
6169 sender_bcc_maps = hash:/etc/postfix/sender_bcc
6171 After a change, run "postmap /etc/postfix/sender_bcc".
6173 This feature is available in Postfix 2.1 and later.
6175
6177 What addresses are subject to sender_canonical_maps address mapping.
6178 By default, sender_canonical_maps address mapping is applied to enve‐
6179 lope sender addresses, and to header sender addresses.
6180 Specify one or more of: envelope_sender, header_sender
6182 This feature is available in Postfix 2.2 and later.
6184
6186 Optional address mapping lookup tables for envelope and header sender
6187 addresses. The table format and lookups are documented in canoni‐
6188 cal(5).
6189 Example: you want to rewrite the SENDER address "user@ugly.domain" to
6191 "user@pretty.domain", while still being able to send mail to the RECIP‐
6192 IENT address "user@ugly.domain".
6193 Note: $sender_canonical_maps is processed before $canonical_maps.
6195 Example:
6197 sender_canonical_maps = hash:/etc/postfix/sender_canonical
6199
6201 A sender-dependent override for the global default_transport parameter
6202 setting. The tables are searched by the envelope sender address and
6203 @domain. A lookup result of DUNNO terminates the search without over‐
6204 riding the global default_transport parameter setting. This informa‐
6205 tion is overruled with the transport(5) table.
6206 Specify zero or more "type:name" lookup tables, separated by whitespace
6208 or comma. Tables will be searched in the specified order until a match
6209 is found.
6210 Note: this overrides default_transport, not transport_maps, and there‐
6212 fore the expected syntax is that of default_transport, not the syntax
6213 of transport_maps. Specifically, this does not support the trans‐
6214 port_maps syntax for null transport, null nexthop, or null email ad‐
6215 dresses.
6216 For safety reasons, this feature does not allow $number substitutions
6218 in regular expression maps.
6219 This feature is available in Postfix 2.7 and later.
6221
6223 A sender-dependent override for the global relayhost parameter setting.
6224 The tables are searched by the envelope sender address and @domain. A
6225 lookup result of DUNNO terminates the search without overriding the
6226 global relayhost parameter setting (Postfix 2.6 and later). This infor‐
6227 mation is overruled with relay_transport, sender_dependent_de‐
6228 fault_transport_maps, default_transport and with the transport(5) ta‐
6229 ble.
6230 Specify zero or more "type:name" lookup tables, separated by whitespace
6232 or comma. Tables will be searched in the specified order until a match
6233 is found.
6234 For safety reasons, this feature does not allow $number substitutions
6236 in regular expression maps.
6237 This feature is available in Postfix 2.3 and later.
6239
6241 Controls how the Postfix sendmail command converts email message line
6242 endings from <CR><LF> into UNIX format (<LF>).
6243 always Always convert message lines ending in <CR><LF>. This setting is
6245 the default with Postfix 2.9 and later.
6246 strict Convert message lines ending in <CR><LF> only if the first input
6248 line ends in <CR><LF>. This setting is backwards-compatible with
6249 Postfix 2.8 and earlier.
6250 never Never convert message lines ending in <CR><LF>. This setting ex‐
6252 ists for completeness only.
6253 This feature is available in Postfix 2.9 and later.
6255
6257 A Sendmail compatibility feature that specifies the location of the
6258 Postfix sendmail(1) command. This command can be used to submit mail
6259 into the Postfix queue.
6260
6262 The master.cf service name of a Postfix daemon process. This can be
6263 used to distinguish the logging from different services that use the
6264 same program name.
6265 Example master.cf entries:
6267 # Distinguish inbound MTA logging from submission and smtps logging.
6269 smtp inet n - n - - smtpd
6270 submission inet n - n - - smtpd
6271 -o syslog_name=postfix/$service_name
6272 smtps inet n - n - - smtpd
6273 -o syslog_name=postfix/$service_name
6274 # Distinguish outbound MTA logging from inbound relay logging.
6276 smtp unix - - n - - smtp
6277 relay unix - - n - - smtp
6278 -o syslog_name=postfix/$service_name
6279
6281 How long the Postfix master(8) waits before forking a server that ap‐
6282 pears to be malfunctioning.
6283 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
6285 The default time unit is s (seconds).
6286
6288 The group ownership of set-gid Postfix commands and of group-writable
6289 Postfix directories. When this parameter value is changed you need to
6290 re-run "postfix set-permissions" (with Postfix version 2.0 and earlier:
6291 "/etc/postfix/post-install set-permissions".
6292
6294 The location of Postfix dynamically-linked libraries (libpostfix-*.so),
6295 and the default location of Postfix database plugins (postfix-*.so)
6296 that have a relative pathname in the dynamicmaps.cf file. The
6297 shlib_directory parameter defaults to "no" when Postfix dynami‐
6298 cally-linked libraries and database plugins are disabled at compile
6299 time, otherwise it typically defaults to /usr/lib/postfix or /usr/lo‐
6300 cal/lib/postfix.
6301 Notes:
6303 • The directory specified with shlib_directory should contain only
6305 Postfix-related files. Postfix dynamically-linked libraries and
6306 database plugins should not be installed in a "public" system
6307 directory such as /usr/lib or /usr/local/lib. Linking Postfix
6308 dynamically-linked library files or database plugins into
6309 non-Postfix programs is not supported. Postfix dynami‐
6310 cally-linked libraries and database plugins implement a Post‐
6311 fix-internal API that changes without maintaining compatibility.
6312 • You can change the shlib_directory value after Postfix is built.
6314 However, you may have to run ldconfig or equivalent to prevent
6315 Postfix programs from failing because the libpostfix-*.so files
6316 are not found. No ldconfig command is needed if you keep the
6317 libpostfix-*.so files in the compiled-in default $shlib_direc‐
6318 tory location.
6319 This feature is available in Postfix 3.0 and later.
6321
6323 Display the name of the recipient table in the "User unknown" re‐
6324 sponses. The extra detail makes troubleshooting easier but also re‐
6325 veals information that is nobody else's business.
6326 This feature is available in Postfix 2.0 and later.
6328
6330 The name of the showq(8) service. This service produces mail queue sta‐
6331 tus reports.
6332 This feature is available in Postfix 2.0 and later.
6334
6336 The address type ("ipv6", "ipv4" or "any") that the Postfix SMTP client
6337 will try first, when a destination has IPv6 and IPv4 addresses with
6338 equal MX preference. This feature has no effect unless the inet_proto‐
6339 cols setting enables both IPv4 and IPv6.
6340 Postfix SMTP client address preference has evolved. With Postfix 2.8
6342 the default is "ipv6"; earlier implementations are hard-coded to prefer
6343 IPv6 over IPv4.
6344 Notes for mail delivery between sites that have both IPv4 and IPv6 con‐
6346 nectivity:
6347 • The setting "smtp_address_preference = ipv6" is unsafe. It can
6349 fail to deliver mail when there is an outage that affects IPv6,
6350 while the destination is still reachable over IPv4.
6351 • The setting "smtp_address_preference = any" is safe. With this,
6353 mail will eventually be delivered even if there is an outage
6354 that affects IPv6 or IPv4, as long as it does not affect both.
6355 This feature is available in Postfix 2.8 and later.
6357
6359 In the context of email address verification, the SMTP protocol stage
6360 that determines whether an email address is deliverable. Specify one
6361 of "rcpt" or "data". The latter is needed with remote SMTP servers
6362 that reject recipients after the DATA command. Use transport_maps to
6363 apply this feature selectively:
6364 /etc/postfix/main.cf:
6366 transport_maps = hash:/etc/postfix/transport
6367 /etc/postfix/transport:
6369 smtp-domain-that-verifies-after-data smtp-data-target:
6370 lmtp-domain-that-verifies-after-data lmtp-data-target:
6371 /etc/postfix/master.cf:
6373 smtp-data-target unix - - n - - smtp
6374 -o smtp_address_verify_target=data
6375 lmtp-data-target unix - - n - - lmtp
6376 -o lmtp_address_verify_target=data
6377 Unselective use of the "data" target does no harm, but will result in
6379 unnecessary "lost connection after DATA" events at remote SMTP/LMTP
6380 servers.
6381 This feature is available in Postfix 3.0 and later.
6383
6385 Always send EHLO at the start of an SMTP session.
6386 With "smtp_always_send_ehlo = no", the Postfix SMTP client sends EHLO
6388 only when the word "ESMTP" appears in the server greeting banner (exam‐
6389 ple: 220 spike.porcupine.org ESMTP Postfix).
6390
6392 When a remote destination resolves to a combination of IPv4 and IPv6
6393 addresses, ensure that the Postfix SMTP client can try both address
6394 types before it runs into the smtp_mx_address_limit.
6395 This avoids an interoperability problem when a destination resolves to
6397 primarily IPv6 addresses, the smtp_address_limit feature eliminates
6398 most or all IPv4 addresses, and the destination is not reachable over
6399 IPv6.
6400 This feature is available in Postfix 3.3 and later.
6402
6404 An optional numerical network address that the Postfix SMTP client
6405 should bind to when making an IPv4 connection.
6406 This can be specified in the main.cf file for all SMTP clients, or it
6408 can be specified in the master.cf file for a specific client, for exam‐
6409 ple:
6410 /etc/postfix/master.cf:
6412 smtp ... smtp -o smtp_bind_address=11.22.33.44
6413 Note 1: when inet_interfaces specifies no more than one IPv4 address,
6415 and that address is a non-loopback address, it is automatically used as
6416 the smtp_bind_address. This supports virtual IP hosting, but can be a
6417 problem on multi-homed firewalls. See the inet_interfaces documentation
6418 for more detail.
6419 Note 2: address information may be enclosed inside [], but this form is
6421 not required here.
6422
6424 An optional numerical network address that the Postfix SMTP client
6425 should bind to when making an IPv6 connection.
6426 This feature is available in Postfix 2.2 and later.
6428 This can be specified in the main.cf file for all SMTP clients, or it
6430 can be specified in the master.cf file for a specific client, for exam‐
6431 ple:
6432 /etc/postfix/master.cf:
6434 smtp ... smtp -o smtp_bind_address6=1:2:3:4:5:6:7:8
6435 Note 1: when inet_interfaces specifies no more than one IPv6 address,
6437 and that address is a non-loopback address, it is automatically used as
6438 the smtp_bind_address6. This supports virtual IP hosting, but can be a
6439 problem on multi-homed firewalls. See the inet_interfaces documentation
6440 for more detail.
6441 Note 2: address information may be enclosed inside [], but this form is
6443 not recommended here.
6444
6446 Restricted body_checks(5) tables for the Postfix SMTP client. These
6447 tables are searched while mail is being delivered. Actions that change
6448 the delivery time or destination are not available.
6449 This feature is available in Postfix 2.5 and later.
6451
6453 When the remote SMTP servername is a DNS CNAME, replace the servername
6454 with the result from CNAME expansion for the purpose of logging, SASL
6455 password lookup, TLS policy decisions, or TLS certificate verification.
6456 The value "no" hardens Postfix smtp_tls_per_site hostname-based poli‐
6457 cies against false hostname information in DNS CNAME records, and makes
6458 SASL password file lookups more predictable. This is the default set‐
6459 ting as of Postfix 2.3.
6460 When DNS CNAME records are validated with secure DNS lookups
6462 (smtp_dns_support_level = dnssec), they are always allowed to override
6463 the above servername (Postfix 2.11 and later).
6464 This feature is available in Postfix 2.2.9 and later.
6466
6468 The Postfix SMTP client time limit for completing a TCP connection, or
6469 zero (use the operating system built-in time limit).
6470 When no connection can be made within the deadline, the Postfix SMTP
6472 client tries the next address on the mail exchanger list. Specify 0 to
6473 disable the time limit (i.e. use whatever timeout is implemented by the
6474 operating system).
6475 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
6477 The default time unit is s (seconds).
6478
6480 Permanently enable SMTP connection caching for the specified destina‐
6481 tions. With SMTP connection caching, a connection is not closed imme‐
6482 diately after completion of a mail transaction. Instead, the connec‐
6483 tion is kept open for up to $smtp_connection_cache_time_limit seconds.
6484 This allows connections to be reused for other deliveries, and can im‐
6485 prove mail delivery performance.
6486 Specify a comma or white space separated list of destinations or
6488 pseudo-destinations:
6489 • if mail is sent without a relay host: a domain name (the
6491 right-hand side of an email address, without the [] around a nu‐
6492 meric IP address),
6493 • if mail is sent via a relay host: a relay host name (without []
6495 or non-default TCP port), as specified in main.cf or in the
6496 transport map,
6497 • if mail is sent via a UNIX-domain socket: a pathname (without
6499 the unix: prefix),
6500 • a /file/name with domain names and/or relay host names as de‐
6502 fined above,
6503 • a "type:table" with domain names and/or relay host names on the
6505 left-hand side. The right-hand side result from "type:table"
6506 lookups is ignored.
6507 This feature is available in Postfix 2.2 and later.
6509
6511 Temporarily enable SMTP connection caching while a destination has a
6512 high volume of mail in the active queue. With SMTP connection caching,
6513 a connection is not closed immediately after completion of a mail
6514 transaction. Instead, the connection is kept open for up to $smtp_con‐
6515 nection_cache_time_limit seconds. This allows connections to be reused
6516 for other deliveries, and can improve mail delivery performance.
6517 This feature is available in Postfix 2.2 and later.
6519
6521 When SMTP connection caching is enabled, the amount of time that an un‐
6522 used SMTP client socket is kept open before it is closed. Do not spec‐
6523 ify larger values without permission from the remote sites.
6524 This feature is available in Postfix 2.2 and later.
6526
6528 When SMTP connection caching is enabled, the number of times that an
6529 SMTP session may be reused before it is closed, or zero (no limit).
6530 With a reuse count limit of N, a connection is used up to N+1 times.
6531 NOTE: This feature is unsafe. When a high-volume destination has multi‐
6533 ple inbound MTAs, then the slowest inbound MTA will attract the most
6534 connections to that destination. This limitation does not exist with
6535 the smtp_connection_reuse_time_limit feature.
6536 This feature is available in Postfix 2.11.
6538
6540 The amount of time during which Postfix will use an SMTP connection re‐
6541 peatedly. The timer starts when the connection is initiated (i.e. it
6542 includes the connect, greeting and helo latency, in addition to the la‐
6543 tencies of subsequent mail delivery transactions).
6544 This feature addresses a performance stability problem with remote SMTP
6546 servers. This problem is not specific to Postfix: it can happen when
6547 any MTA sends large amounts of SMTP email to a site that has multiple
6548 MX hosts.
6549 The problem starts when one of a set of MX hosts becomes slower than
6551 the rest. Even though SMTP clients connect to fast and slow MX hosts
6552 with equal probability, the slow MX host ends up with more simultaneous
6553 inbound connections than the faster MX hosts, because the slow MX host
6554 needs more time to serve each client request.
6555 The slow MX host becomes a connection attractor. If one MX host be‐
6557 comes N times slower than the rest, it dominates mail delivery latency
6558 unless there are more than N fast MX hosts to counter the effect. And
6559 if the number of MX hosts is smaller than N, the mail delivery latency
6560 becomes effectively that of the slowest MX host divided by the total
6561 number of MX hosts.
6562 The solution uses connection caching in a way that differs from Postfix
6564 version 2.2. By limiting the amount of time during which a connection
6565 can be used repeatedly (instead of limiting the number of deliveries
6566 over that connection), Postfix not only restores fairness in the dis‐
6567 tribution of simultaneous connections across a set of MX hosts, it also
6568 favors deliveries over connections that perform well, which is exactly
6569 what we want.
6570 The default reuse time limit, 300s, is comparable to the various smtp
6572 transaction timeouts which are fair estimates of maximum excess latency
6573 for a slow delivery. Note that hosts may accept thousands of messages
6574 over a single connection within the default connection reuse time
6575 limit. This number is much larger than the default Postfix version 2.2
6576 limit of 10 messages per cached connection. It may prove necessary to
6577 lower the limit to avoid interoperability issues with MTAs that exhibit
6578 bugs when many messages are delivered via a single connection. A lower
6579 reuse time limit risks losing the benefit of connection reuse when the
6580 average connection and mail delivery latency exceeds the reuse time
6581 limit.
6582 This feature is available in Postfix 2.3 and later.
6584
6586 The Postfix SMTP client time limit for sending the SMTP ".", and for
6587 receiving the remote SMTP server response.
6588 When no response is received within the deadline, a warning is logged
6590 that the mail may be delivered multiple times.
6591 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
6593 The default time unit is s (seconds).
6594
6596 The Postfix SMTP client time limit for sending the SMTP DATA command,
6597 and for receiving the remote SMTP server response.
6598 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
6600 The default time unit is s (seconds).
6601
6603 The Postfix SMTP client time limit for sending the SMTP message con‐
6604 tent. When the connection makes no progress for more than
6605 $smtp_data_xfer_timeout seconds the Postfix SMTP client terminates the
6606 transfer.
6607 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
6609 The default time unit is s (seconds).
6610
6612 Defer mail delivery when no MX record resolves to an IP address.
6613 The default (no) is to return the mail as undeliverable. With older
6615 Postfix versions the default was to keep trying to deliver the mail un‐
6616 til someone fixed the MX record or until the mail was too old.
6617 Note: the Postfix SMTP client always ignores MX records with equal or
6619 worse preference than the local MTA itself.
6620 This feature is available in Postfix 2.1 and later.
6622
6624 Optional filter for the smtp(8) delivery agent to change the delivery
6625 status code or explanatory text of successful or unsuccessful deliver‐
6626 ies. See default_delivery_status_filter for details.
6627 NOTE: This feature modifies Postfix SMTP client error or non-error mes‐
6629 sages that may or may not be derived from remote SMTP server responses.
6630 In contrast, the smtp_reply_filter feature modifies remote SMTP server
6631 responses only.
6632
6634 rency_limit)
6635 The maximal number of parallel deliveries to the same destination via
6636 the smtp message delivery transport. This limit is enforced by the
6637 queue manager. The message delivery transport name is the first field
6638 in the entry in the master.cf file.
6639
6641 ent_limit)
6642 The maximal number of recipients per message for the smtp message de‐
6643 livery transport. This limit is enforced by the queue manager. The mes‐
6644 sage delivery transport name is the first field in the entry in the
6645 master.cf file.
6646 Setting this parameter to a value of 1 changes the meaning of smtp_des‐
6648 tination_concurrency_limit from concurrency per domain into concurrency
6649 per recipient.
6650
6652 Lookup tables, indexed by the remote SMTP server address, with case in‐
6653 sensitive lists of EHLO keywords (pipelining, starttls, auth, etc.)
6654 that the Postfix SMTP client will ignore in the EHLO response from a
6655 remote SMTP server. See smtp_discard_ehlo_keywords for details. The ta‐
6656 ble is not indexed by hostname for consistency with smtpd_dis‐
6657 card_ehlo_keyword_address_maps.
6658 Specify zero or more "type:name" lookup tables, separated by whitespace
6660 or comma. Tables will be searched in the specified order until a match
6661 is found.
6662 This feature is available in Postfix 2.2 and later.
6664
6666 A case insensitive list of EHLO keywords (pipelining, starttls, auth,
6667 etc.) that the Postfix SMTP client will ignore in the EHLO response
6668 from a remote SMTP server.
6669 This feature is available in Postfix 2.2 and later.
6671 Notes:
6673 • Specify the silent-discard pseudo keyword to prevent this action
6675 from being logged.
6676 • Use the smtp_discard_ehlo_keyword_address_maps feature to dis‐
6678 card EHLO keywords selectively.
6679
6681 Optional filter for Postfix SMTP client DNS lookup results. Specify
6682 zero or more lookup tables. The lookup tables are searched in the
6683 given order for a match with the DNS lookup result, converted to the
6684 following form:
6685 name ttl class type preference value
6687 The class field is always "IN", the preference field exists only for MX
6689 records, the names of hosts, domains, etc. end in ".", and those names
6690 are in ASCII form (xn--mumble form in the case of UTF8 names).
6691 When a match is found, the table lookup result specifies an action. By
6693 default, the table query and the action name are case-insensitive.
6694 Currently, only the IGNORE action is implemented.
6695 Notes:
6697 • Postfix DNS reply filters have no effect on implicit DNS lookups
6699 through nsswitch.conf or equivalent mechanisms.
6700 • The Postfix SMTP/LMTP client uses smtp_dns_reply_filter and
6702 lmtp_dns_reply_filter only to discover a remote SMTP or LMTP
6703 service (record types MX, A, AAAA, and TLSA). These lookups are
6704 also made to implement the features reject_unverified_sender and
6705 reject_unverified_recipient.
6706 • The Postfix SMTP/LMTP client defers mail delivery when a filter
6708 removes all lookup results from a successful query.
6709 • Postfix SMTP server uses smtpd_dns_reply_filter only to look up
6711 MX, A, AAAA, and TXT records to implement the features re‐
6712 ject_unknown_helo_hostname, reject_unknown_sender_domain, re‐
6713 ject_unknown_recipient_domain, reject_rbl_*, and reject_rhsbl_*.
6714 • The Postfix SMTP server logs a warning or defers mail delivery
6716 when a filter removes all lookup results from a successful
6717 query.
6718 Example: ignore Google AAAA records in Postfix SMTP client DNS lookups,
6720 because Google sometimes hard-rejects mail from IPv6 clients with valid
6721 PTR etc. records.
6722 /etc/postfix/main.cf:
6724 smtp_dns_reply_filter = pcre:/etc/postfix/smtp_dns_reply_filter
6725 /etc/postfix/smtp_dns_reply_filter:
6727 # /domain ttl IN AAAA address/ action, all case-insensitive.
6728 # Note: the domain name ends in ".".
6729 /^\S+\.google\.com\.\s+\S+\s+\S+\s+AAAA\s+/ IGNORE
6730 This feature is available in Postfix 3.0 and later.
6732
6734 DNS Resolver options for the Postfix SMTP client. Specify zero or more
6735 of the following options, separated by comma or whitespace. Option
6736 names are case-sensitive. Some options refer to domain names that are
6737 specified in the file /etc/resolv.conf or equivalent.
6738 res_defnames
6740 Append the current domain name to single-component names (those
6741 that do not contain a "." character). This can produce incorrect
6742 results, and is the hard-coded behavior prior to Postfix 2.8.
6743 res_dnsrch
6745 Search for host names in the current domain and in parent do‐
6746 mains. This can produce incorrect results and is therefore not
6747 recommended.
6748 This feature is available in Postfix 2.8 and later.
6750
6752 Level of DNS support in the Postfix SMTP client. With "smtp_dns_sup‐
6753 port_level" left at its empty default value, the legacy "dis‐
6754 able_dns_lookups" parameter controls whether DNS is enabled in the
6755 Postfix SMTP client, otherwise the legacy parameter is ignored.
6756 Specify one of the following:
6758 disabled
6760 Disable DNS lookups. No MX lookups are performed and hostname
6761 to address lookups are unconditionally "native". This setting
6762 is not appropriate for hosts that deliver mail to the public In‐
6763 ternet. Some obsolete how-to documents recommend disabling DNS
6764 lookups in some configurations with content_filters. This is no
6765 longer required and strongly discouraged.
6766 enabled
6768 Enable DNS lookups. Nexthop destination domains not enclosed in
6769 "[]" will be subject to MX lookups. If "dns" and "native" are
6770 included in the "smtp_host_lookup" parameter value, DNS will be
6771 queried first to resolve MX-host A records, followed by "native"
6772 lookups if no answer is found in DNS.
6773 dnssec Enable DNSSEC lookups. The "dnssec" setting differs from the
6775 "enabled" setting above in the following ways:
6776 • Any MX lookups will set RES_USE_DNSSEC and RES_USE_EDNS0 to re‐
6778 quest DNSSEC-validated responses. If the MX response is
6779 DNSSEC-validated the corresponding hostnames are considered val‐
6780 idated.
6781 • The address lookups of validated hostnames are also validated,
6783 (provided of course "smtp_host_lookup" includes "dns", see be‐
6784 low).
6785 • Temporary failures in DNSSEC-enabled hostname-to-address resolu‐
6787 tion block any "native" lookups. Additional "native" lookups
6788 only happen when DNSSEC lookups hard-fail (NODATA or NXDOMAIN).
6789 The Postfix SMTP client considers non-MX "[nexthop]" and "[nex‐
6791 thop]:port" destinations equivalent to statically-validated MX records
6792 of the form "nexthop. IN MX 0 nexthop." Therefore, with "dnssec" sup‐
6793 port turned on, validated hostname-to-address lookups apply to the nex‐
6794 thop domain of any "[nexthop]" or "[nexthop]:port" destination. This
6795 is also true for LMTP "inet:host" and "inet:host:port" destinations, as
6796 LMTP hostnames are never subject to MX lookups.
6797 The "dnssec" setting is recommended only if you plan to use the dane or
6799 dane-only TLS security level, otherwise enabling DNSSEC support in
6800 Postfix offers no additional security. Postfix DNSSEC support relies
6801 on an upstream recursive nameserver that validates DNSSEC signatures.
6802 Such a DNS server will always filter out forged DNS responses, even
6803 when Postfix itself is not configured to use DNSSEC.
6804 When using Postfix DANE support the "smtp_host_lookup" parameter should
6806 include "dns", as DANE is not applicable to hosts resolved via "native"
6807 lookups.
6808 As mentioned above, Postfix is not a validating stub resolver; it re‐
6810 lies on the system's configured DNSSEC-validating recursive nameserver
6811 to perform all DNSSEC validation. Since this nameserver's DNSSEC-vali‐
6812 dated responses will be fully trusted, it is strongly recommended that
6813 the MTA host have a local DNSSEC-validating recursive caching name‐
6814 server listening on a loopback address, and be configured to use only
6815 this nameserver for all lookups. Otherwise, Postfix may remain subject
6816 to man-in-the-middle attacks that forge responses from the recursive
6817 nameserver
6818 DNSSEC support requires a version of Postfix compiled against a reason‐
6820 ably-modern DNS resolver(3) library that implements the RES_USE_DNSSEC
6821 and RES_USE_EDNS0 resolver options.
6822 This feature is available in Postfix 2.11 and later.
6824
6826 Enforcement mode: require that remote SMTP servers use TLS encryption,
6827 and never send mail in the clear. This also requires that the remote
6828 SMTP server hostname matches the information in the remote server cer‐
6829 tificate, and that the remote SMTP server certificate was issued by a
6830 CA that is trusted by the Postfix SMTP client. If the certificate
6831 doesn't verify or the hostname doesn't match, delivery is deferred and
6832 mail stays in the queue.
6833 The server hostname is matched against all names provided as dNSNames
6835 in the SubjectAlternativeName. If no dNSNames are specified, the Com‐
6836 monName is checked. The behavior may be changed with the smtp_tls_en‐
6837 force_peername option.
6838 This option is useful only if you are definitely sure that you will
6840 only connect to servers that support RFC 2487 _and_ that provide valid
6841 server certificates. Typical use is for clients that send all their
6842 email to a dedicated mailhub.
6843 This feature is available in Postfix 2.2 and later. With Postfix 2.3
6845 and later use smtp_tls_security_level instead.
6846
6848 Optional list of relay hosts for SMTP destinations that can't be found
6849 or that are unreachable. With Postfix 2.2 and earlier this parameter is
6850 called fallback_relay.
6851 By default, mail is returned to the sender when a destination is not
6853 found, and delivery is deferred when a destination is unreachable.
6854 With bulk email deliveries, it can be beneficial to run the fallback
6856 relay MTA on the same host, so that it can reuse the sender IP address.
6857 This speeds up deliveries that are delayed by IP-based reputation sys‐
6858 tems (greylist, etc.).
6859 The fallback relays must be SMTP destinations. Specify a domain, host,
6861 host:port, [host]:port, [address] or [address]:port; the form [host]
6862 turns off MX lookups. If you specify multiple SMTP destinations, Post‐
6863 fix will try them in the specified order.
6864 To prevent mailer loops between MX hosts and fall-back hosts, Postfix
6866 version 2.2 and later will not use the fallback relays for destinations
6867 that it is MX host for (assuming DNS lookup is turned on).
6868
6870 Optional lookup tables that perform address rewriting in the Postfix
6871 SMTP client, typically to transform a locally valid address into a
6872 globally valid address when sending mail across the Internet. This is
6873 needed when the local machine does not have its own Internet domain
6874 name, but uses something like localdomain.local instead.
6875 Specify zero or more "type:name" lookup tables, separated by whitespace
6877 or comma. Tables will be searched in the specified order until a match
6878 is found.
6879 The table format and lookups are documented in generic(5); examples are
6881 shown in the ADDRESS_REWRITING_README and STANDARD_CONFIGURATION_README
6882 documents.
6883 This feature is available in Postfix 2.2 and later.
6885
6887 Restricted header_checks(5) tables for the Postfix SMTP client. These
6888 tables are searched while mail is being delivered. Actions that change
6889 the delivery time or destination are not available.
6890 This feature is available in Postfix 2.5 and later.
6892
6894 The hostname to send in the SMTP HELO or EHLO command.
6895 The default value is the machine hostname. Specify a hostname or
6897 [ip.add.re.ss].
6898 This information can be specified in the main.cf file for all SMTP
6900 clients, or it can be specified in the master.cf file for a specific
6901 client, for example:
6902 /etc/postfix/master.cf:
6904 mysmtp ... smtp -o smtp_helo_name=foo.bar.com
6905 This feature is available in Postfix 2.0 and later.
6907
6909 The Postfix SMTP client time limit for sending the HELO or EHLO com‐
6910 mand, and for receiving the initial remote SMTP server response.
6911 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
6913 The default time unit is s (seconds).
6914
6916 What mechanisms the Postfix SMTP client uses to look up a host's IP ad‐
6917 dress. This parameter is ignored when DNS lookups are disabled (see:
6918 disable_dns_lookups and smtp_dns_support_level). The "dns" mechanism
6919 is always tried before "native" if both are listed.
6920 Specify one of the following:
6922 dns Hosts can be found in the DNS (preferred).
6924 native Use the native naming service only (nsswitch.conf, or equivalent
6926 mechanism).
6927 dns, native
6929 Use the native service for hosts not found in the DNS.
6930 This feature is available in Postfix 2.1 and later.
6932
6934 The maximal length of message header and body lines that Postfix will
6935 send via SMTP. This limit does not include the <CR><LF> at the end of
6936 each line. Longer lines are broken by inserting "<CR><LF><SPACE>", to
6937 minimize the damage to MIME formatted mail. Specify zero to disable
6938 this limit.
6939 The Postfix limit of 998 characters not including <CR><LF> is consis‐
6941 tent with the SMTP limit of 1000 characters including <CR><LF>. The
6942 Postfix limit was 990 with Postfix 2.8 and earlier.
6943
6945 The Postfix SMTP client time limit for sending the MAIL FROM command,
6946 and for receiving the remote SMTP server response.
6947 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
6949 The default time unit is s (seconds).
6950
6952 Restricted mime_header_checks(5) tables for the Postfix SMTP client.
6953 These tables are searched while mail is being delivered. Actions that
6954 change the delivery time or destination are not available.
6955 This feature is available in Postfix 2.5 and later.
6957
6959 The maximal number of MX (mail exchanger) IP addresses that can result
6960 from Postfix SMTP client mail exchanger lookups, or zero (no limit).
6961 Prior to Postfix version 2.3, this limit was disabled by default.
6962 This feature is available in Postfix 2.1 and later.
6964
6966 The maximal number of SMTP sessions per delivery request before the
6967 Postfix SMTP client gives up or delivers to a fall-back relay host, or
6968 zero (no limit). This restriction ignores sessions that fail to com‐
6969 plete the SMTP initial handshake (Postfix version 2.2 and earlier) or
6970 that fail to complete the EHLO and TLS handshake (Postfix version 2.3
6971 and later).
6972 This feature is available in Postfix 2.1 and later.
6974
6976 Restricted nested_header_checks(5) tables for the Postfix SMTP client.
6977 These tables are searched while mail is being delivered. Actions that
6978 change the delivery time or destination are not available.
6979 This feature is available in Postfix 2.5 and later.
6981
6983 Never send EHLO at the start of an SMTP session. See also the smtp_al‐
6984 ways_send_ehlo parameter.
6985
6987 Change the behavior of the smtp_*_timeout time limits, from a time
6988 limit per read or write system call, to a time limit to send or receive
6989 a complete record (an SMTP command line, SMTP response line, SMTP mes‐
6990 sage content line, or TLS protocol message). This limits the impact
6991 from hostile peers that trickle data one byte at a time.
6992 Note: when per-record deadlines are enabled, a short timeout may cause
6994 problems with TLS over very slow network connections. The reasons are
6995 that a TLS protocol message can be up to 16 kbytes long (with TLSv1),
6996 and that an entire TLS protocol message must be sent or received within
6997 the per-record deadline.
6998 This feature is available in Postfix 2.9 and later. With older Postfix
7000 releases, the behavior is as if this parameter is set to "no".
7001
7003 How long the Postfix SMTP client pauses before sending ".<CR><LF>" in
7004 order to work around the PIX firewall "<CR><LF>.<CR><LF>" bug.
7005 Choosing a too short time makes this workaround ineffective when send‐
7007 ing large messages over slow network connections.
7008
7010 Lookup tables, indexed by the remote SMTP server address, with per-des‐
7011 tination workarounds for CISCO PIX firewall bugs. The table is not in‐
7012 dexed by hostname for consistency with smtp_discard_ehlo_keyword_ad‐
7013 dress_maps.
7014 Specify zero or more "type:name" lookup tables, separated by whitespace
7016 or comma. Tables will be searched in the specified order until a match
7017 is found.
7018 This feature is available in Postfix 2.4 and later.
7020
7022 How long a message must be queued before the Postfix SMTP client turns
7023 on the PIX firewall "<CR><LF>.<CR><LF>" bug workaround for delivery
7024 through firewalls with "smtp fixup" mode turned on.
7025 By default, the workaround is turned off for mail that is queued for
7027 less than 500 seconds. In other words, the workaround is normally
7028 turned off for the first delivery attempt.
7029 Specify 0 to enable the PIX firewall "<CR><LF>.<CR><LF>" bug workaround
7031 upon the first delivery attempt.
7032
7034 A list that specifies zero or more workarounds for CISCO PIX firewall
7035 bugs. These workarounds are implemented by the Postfix SMTP client.
7036 Workaround names are separated by comma or space, and are case insensi‐
7037 tive. This parameter setting can be overruled with per-destination
7038 smtp_pix_workaround_maps settings.
7039 delay_dotcrlf
7041 Insert a delay before sending ".<CR><LF>" after the end of the
7042 message content. The delay is subject to the smtp_pix_work‐
7043 around_delay_time and smtp_pix_workaround_threshold_time parame‐
7044 ter settings.
7045 disable_esmtp
7047 Disable all extended SMTP commands: send HELO instead of EHLO.
7048 This feature is available in Postfix 2.4 and later. The default set‐
7050 tings are backwards compatible with earlier Postfix versions.
7051
7053 The Postfix SMTP client time limit for sending the QUIT command, and
7054 for receiving the remote SMTP server response.
7055 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
7057 The default time unit is s (seconds).
7058
7060 Quote addresses in Postfix SMTP client MAIL FROM and RCPT TO commands
7061 as required by RFC 5321. This includes putting quotes around an address
7062 localpart that ends in ".".
7063 The default is to comply with RFC 5321. If you have to send mail to a
7065 broken SMTP server, configure a special SMTP client in master.cf:
7066 /etc/postfix/master.cf:
7068 broken-smtp . . . smtp -o smtp_quote_rfc821_envelope=no
7069 and route mail for the destination in question to the "broken-smtp"
7071 message delivery with a transport(5) table.
7072 This feature is available in Postfix 2.1 and later.
7074
7076 Randomize the order of equal-preference MX host addresses. This is a
7077 performance feature of the Postfix SMTP client.
7078
7080 The Postfix SMTP client time limit for sending the SMTP RCPT TO com‐
7081 mand, and for receiving the remote SMTP server response.
7082 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
7084 The default time unit is s (seconds).
7085
7087 A mechanism to transform replies from remote SMTP servers one line at a
7088 time. This is a last-resort tool to work around server replies that
7089 break interoperability with the Postfix SMTP client. Other uses in‐
7090 volve fault injection to test Postfix's handling of invalid responses.
7091 Notes:
7093 • In the case of a multi-line reply, the Postfix SMTP client uses
7095 the final reply line's numerical SMTP reply code and enhanced
7096 status code.
7097 • The numerical SMTP reply code (XYZ) takes precedence over the
7099 enhanced status code (X.Y.Z). When the enhanced status code
7100 initial digit differs from the SMTP reply code initial digit, or
7101 when no enhanced status code is present, the Postfix SMTP client
7102 uses a generic enhanced status code (X.0.0) instead.
7103 Specify the name of a "type:table" lookup table. The search string is a
7105 single SMTP reply line as received from the remote SMTP server, except
7106 that the trailing <CR><LF> are removed. When the lookup succeeds, the
7107 result replaces the single SMTP reply line.
7108 Examples:
7110 /etc/postfix/main.cf:
7112 smtp_reply_filter = pcre:/etc/postfix/reply_filter
7113 /etc/postfix/reply_filter:
7115 # Transform garbage into "250-filler..." so that it looks like
7116 # one line from a multi-line reply. It does not matter what we
7117 # substitute here as long it has the right syntax. The Postfix
7118 # SMTP client will use the final line's numerical SMTP reply
7119 # code and enhanced status code.
7120 !/^([2-5][0-9][0-9]($|[- ]))/ 250-filler for garbage
7121 This feature is available in Postfix 2.7.
7123
7125 The Postfix SMTP client time limit for sending the RSET command, and
7126 for receiving the remote SMTP server response. The SMTP client sends
7127 RSET in order to finish a recipient address probe, or to verify that a
7128 cached session is still usable.
7129 This feature is available in Postfix 2.1 and later.
7131
7133 An optional table to prevent repeated SASL authentication failures with
7134 the same remote SMTP server hostname, username and password. Each table
7135 (key, value) pair contains a server name, a username and password, and
7136 the full server response. This information is stored when a remote SMTP
7137 server rejects an authentication attempt with a 535 reply code. As
7138 long as the smtp_sasl_password_maps information does no change, and as
7139 long as the smtp_sasl_auth_cache_name information does not expire (see
7140 smtp_sasl_auth_cache_time) the Postfix SMTP client avoids SASL authen‐
7141 tication attempts with the same server, username and password, and in‐
7142 stead bounces or defers mail as controlled with the
7143 smtp_sasl_auth_soft_bounce configuration parameter.
7144 Use a per-destination delivery concurrency of 1 (for example,
7146 "smtp_destination_concurrency_limit = 1", "relay_destination_concur‐
7147 rency_limit = 1", etc.), otherwise multiple delivery agents may experi‐
7148 ence a login failure at the same time.
7149 The table must be accessed via the proxywrite service, i.e. the map
7151 name must start with "proxy:". The table should be stored under the di‐
7152 rectory specified with the data_directory parameter.
7153 This feature uses cryptographic hashing to protect plain-text pass‐
7155 words, and requires that Postfix is compiled with TLS support.
7156 Example:
7158 smtp_sasl_auth_cache_name = proxy:btree:/var/lib/postfix/sasl_auth_cache
7160 This feature is available in Postfix 2.5 and later.
7162
7164 The maximal age of an smtp_sasl_auth_cache_name entry before it is re‐
7165 moved.
7166 This feature is available in Postfix 2.5 and later.
7168
7170 Enable SASL authentication in the Postfix SMTP client. By default, the
7171 Postfix SMTP client uses no authentication.
7172 Example:
7174 smtp_sasl_auth_enable = yes
7176
7178 When a remote SMTP server rejects a SASL authentication request with a
7179 535 reply code, defer mail delivery instead of returning mail as unde‐
7180 liverable. The latter behavior was hard-coded prior to Postfix version
7181 2.5.
7182 Note: the setting "yes" overrides the global soft_bounce parameter, but
7184 the setting "no" does not.
7185 Example:
7187 # Default as of Postfix 2.5
7189 smtp_sasl_auth_soft_bounce = yes
7190 # The old hard-coded default
7191 smtp_sasl_auth_soft_bounce = no
7192 This feature is available in Postfix 2.5 and later.
7194
7196 If non-empty, a Postfix SMTP client filter for the remote SMTP server's
7197 list of offered SASL mechanisms. Different client and server implemen‐
7198 tations may support different mechanism lists; by default, the Postfix
7199 SMTP client will use the intersection of the two. smtp_sasl_mecha‐
7200 nism_filter specifies an optional third mechanism list to intersect
7201 with.
7202 Specify mechanism names, "/file/name" patterns or "type:table" lookup
7204 tables. The right-hand side result from "type:table" lookups is ig‐
7205 nored. Specify "!pattern" to exclude a mechanism name from the list.
7206 The form "!/file/name" is supported only in Postfix version 2.4 and
7207 later.
7208 This feature is available in Postfix 2.2 and later.
7210 Examples:
7212 smtp_sasl_mechanism_filter = plain, login
7214 smtp_sasl_mechanism_filter = /etc/postfix/smtp_mechs
7215 smtp_sasl_mechanism_filter = !gssapi, !login, static:rest
7216
7218 Optional Postfix SMTP client lookup tables with one username:password
7219 entry per sender, remote hostname or next-hop domain. Per-sender lookup
7220 is done only when sender-dependent authentication is enabled. If no
7221 username:password entry is found, then the Postfix SMTP client will not
7222 attempt to authenticate to the remote host.
7223 The Postfix SMTP client opens the lookup table before going to chroot
7225 jail, so you can leave the password file in /etc/postfix.
7226 Specify zero or more "type:name" lookup tables, separated by whitespace
7228 or comma. Tables will be searched in the specified order until a match
7229 is found.
7230
7232 Implementation-specific information that the Postfix SMTP client passes
7233 through to the SASL plug-in implementation that is selected with
7234 smtp_sasl_type. Typically this specifies the name of a configuration
7235 file or rendezvous point.
7236 This feature is available in Postfix 2.3 and later.
7238
7240 Postfix SMTP client SASL security options; as of Postfix 2.3 the list
7241 of available features depends on the SASL client implementation that is
7242 selected with smtp_sasl_type.
7243 The following security features are defined for the cyrus client SASL
7245 implementation:
7246 Specify zero or more of the following:
7248 noplaintext
7250 Disallow methods that use plaintext passwords.
7251 noactive
7253 Disallow methods subject to active (non-dictionary) attack.
7254 nodictionary
7256 Disallow methods subject to passive (dictionary) attack.
7257 noanonymous
7259 Disallow methods that allow anonymous authentication.
7260 mutual_auth
7262 Only allow methods that provide mutual authentication (not
7263 available with SASL version 1).
7264 Example:
7266 smtp_sasl_security_options = noplaintext
7268
7270 The SASL authentication security options that the Postfix SMTP client
7271 uses for TLS encrypted SMTP sessions.
7272 This feature is available in Postfix 2.2 and later.
7274
7276 tions)
7277 The SASL authentication security options that the Postfix SMTP client
7278 uses for TLS encrypted SMTP sessions with a verified server certifi‐
7279 cate.
7280 When mail is sent to the public MX host for the recipient's domain,
7282 server certificates are by default optional, and delivery proceeds even
7283 if certificate verification fails. For delivery via a submission ser‐
7284 vice that requires SASL authentication, it may be appropriate to send
7285 plaintext passwords only when the connection to the server is strongly
7286 encrypted and the server identity is verified.
7287 The smtp_sasl_tls_verified_security_options parameter makes it possible
7289 to only enable plaintext mechanisms when a secure connection to the
7290 server is available. Submission servers subject to this policy must ei‐
7291 ther have verifiable certificates or offer suitable non-plaintext SASL
7292 mechanisms.
7293 This feature is available in Postfix 2.6 and later.
7295
7297 The SASL plug-in type that the Postfix SMTP client should use for au‐
7298 thentication. The available types are listed with the "postconf -A"
7299 command.
7300 This feature is available in Postfix 2.3 and later.
7302
7304 Whether or not to append the "AUTH=<>" option to the MAIL FROM command
7305 in SASL-authenticated SMTP sessions. The default is not to send this,
7306 to avoid problems with broken remote SMTP servers. Before Postfix 2.9
7307 the behavior is as if "smtp_send_dummy_mail_auth = yes".
7308 This feature is available in Postfix 2.9 and later.
7310
7312 Send the non-standard XFORWARD command when the Postfix SMTP server
7313 EHLO response announces XFORWARD support.
7314 This allows a Postfix SMTP delivery agent, used for injecting mail into
7316 a content filter, to forward the name, address, protocol and HELO name
7317 of the original client to the content filter and downstream queuing
7318 SMTP server. This can produce more useful logging than local‐
7319 host[127.0.0.1] etc.
7320 This feature is available in Postfix 2.1 and later.
7322
7324 Enable sender-dependent authentication in the Postfix SMTP client; this
7325 is available only with SASL authentication, and disables SMTP connec‐
7326 tion caching to ensure that mail from different senders will use the
7327 appropriate credentials.
7328 This feature is available in Postfix 2.3 and later.
7330
7332 Skip SMTP servers that greet with a 4XX status code (go away, try again
7333 later).
7334 By default, the Postfix SMTP client moves on the next mail exchanger.
7336 Specify "smtp_skip_4xx_greeting = no" if Postfix should defer delivery
7337 immediately.
7338 This feature is available in Postfix 2.0 and earlier. Later Postfix
7340 versions always skip remote SMTP servers that greet with a 4XX status
7341 code.
7342
7344 Skip remote SMTP servers that greet with a 5XX status code.
7345 By default, the Postfix SMTP client moves on the next mail exchanger.
7347 Specify "smtp_skip_5xx_greeting = no" if Postfix should bounce the mail
7348 immediately. Caution: the latter behavior appears to contradict RFC
7349 2821.
7350
7352 Do not wait for the response to the SMTP QUIT command.
7353
7355 Time limit for Postfix SMTP client write and read operations during TLS
7356 startup and shutdown handshake procedures.
7357 This feature is available in Postfix 2.2 and later.
7359
7361 The default TCP port that the Postfix SMTP client connects to. Specify
7362 a symbolic name (see services(5)) or a numeric port.
7363
7365 A file containing CA certificates of root CAs trusted to sign either
7366 remote SMTP server certificates or intermediate CA certificates. These
7367 are loaded into memory before the smtp(8) client enters the chroot
7368 jail. If the number of trusted roots is large, consider using
7369 smtp_tls_CApath instead, but note that the latter directory must be
7370 present in the chroot jail if the smtp(8) client is chrooted. This file
7371 may also be used to augment the client certificate trust chain, but it
7372 is best to include all the required certificates directly in
7373 $smtp_tls_cert_file (or, Postfix >= 3.4 $smtp_tls_chain_files).
7374 Specify "smtp_tls_CAfile = /path/to/system_CA_file" to use ONLY the
7376 system-supplied default Certification Authority certificates.
7377 Specify "tls_append_default_CA = no" to prevent Postfix from appending
7379 the system-supplied default CAs and trusting third-party certificates.
7380 Example:
7382 smtp_tls_CAfile = /etc/postfix/CAcert.pem
7384 This feature is available in Postfix 2.2 and later.
7386
7388 Directory with PEM format Certification Authority certificates that the
7389 Postfix SMTP client uses to verify a remote SMTP server certificate.
7390 Don't forget to create the necessary "hash" links with, for example,
7391 "$OPENSSL_HOME/bin/c_rehash /etc/postfix/certs".
7392 To use this option in chroot mode, this directory (or a copy) must be
7394 inside the chroot jail.
7395 Specify "smtp_tls_CApath = /path/to/system_CA_directory" to use ONLY
7397 the system-supplied default Certification Authority certificates.
7398 Specify "tls_append_default_CA = no" to prevent Postfix from appending
7400 the system-supplied default CAs and trusting third-party certificates.
7401 Example:
7403 smtp_tls_CApath = /etc/postfix/certs
7405 This feature is available in Postfix 2.2 and later.
7407
7409 Try to detect a mail hijacking attack based on a TLS protocol vulnera‐
7410 bility (CVE-2009-3555), where an attacker prepends malicious HELO,
7411 MAIL, RCPT, DATA commands to a Postfix SMTP client TLS session. The
7412 attack would succeed with non-Postfix SMTP servers that reply to the
7413 malicious HELO, MAIL, RCPT, DATA commands after negotiating the Postfix
7414 SMTP client TLS session.
7415 This feature is available in Postfix 2.7.
7417
7419 File with the Postfix SMTP client RSA certificate in PEM format. This
7420 file may also contain the Postfix SMTP client private RSA key, and
7421 these may be the same as the Postfix SMTP server RSA certificate and
7422 key file. With Postfix >= 3.4 the preferred way to configure client
7423 keys and certificates is via the "smtp_tls_chain_files" parameter.
7424 Do not configure client certificates unless you must present client TLS
7426 certificates to one or more servers. Client certificates are not usu‐
7427 ally needed, and can cause problems in configurations that work well
7428 without them. The recommended setting is to let the defaults stand:
7429 smtp_tls_cert_file =
7431 smtp_tls_key_file =
7432 smtp_tls_eccert_file =
7433 smtp_tls_eckey_file =
7434 # Obsolete DSA parameters
7435 smtp_tls_dcert_file =
7436 smtp_tls_dkey_file =
7437 # Postfix >= 3.4 interface
7438 smtp_tls_chain_files =
7439 The best way to use the default settings is to comment out the above
7441 parameters in main.cf if present.
7442 To enable remote SMTP servers to verify the Postfix SMTP client cer‐
7444 tificate, the issuing CA certificates must be made available to the
7445 server. You should include the required certificates in the client cer‐
7446 tificate file, the client certificate first, then the issuing CA(s)
7447 (bottom-up order).
7448 Example: the certificate for "client.example.com" was issued by "inter‐
7450 mediate CA" which itself has a certificate issued by "root CA". As the
7451 "root" super-user create the client.pem file with:
7452 # umask 077
7454 # cat client_key.pem client_cert.pem intermediate_CA.pem > chain.pem
7455 If you also want to verify remote SMTP server certificates issued by
7457 these CAs, you can add the CA certificates to the smtp_tls_CAfile, in
7458 which case it is not necessary to have them in the smtp_tls_cert_file,
7459 smtp_tls_dcert_file (obsolete) or smtp_tls_eccert_file.
7460 A certificate supplied here must be usable as an SSL client certificate
7462 and hence pass the "openssl verify -purpose sslclient ..." test.
7463 Example:
7465 smtp_tls_cert_file = /etc/postfix/chain.pem
7467 This feature is available in Postfix 2.2 and later.
7469
7471 List of one or more PEM files, each holding one or more private keys
7472 directly followed by a corresponding certificate chain. The file names
7473 are separated by commas and/or whitespace. This parameter obsoletes
7474 the legacy algorithm-specific key and certificate file settings. When
7475 this parameter is non-empty, the legacy parameters are ignored, and a
7476 warning is logged if any are also non-empty.
7477 With the proliferation of multiple private key algorithms-which, as of
7479 OpenSSL 1.1.1, include DSA (obsolete), RSA, ECDSA, Ed25519 and Ed448-it
7480 is increasingly impractical to use separate parameters to configure the
7481 key and certificate chain for each algorithm. Therefore, Postfix now
7482 supports storing multiple keys and corresponding certificate chains in
7483 a single file or in a set of files.
7484 Each key must appear immediately before the corresponding certificate,
7486 optionally followed by additional issuer certificates that complete the
7487 certificate chain for that key. When multiple files are specified,
7488 they are equivalent to a single file that is concatenated from those
7489 files in the given order. Thus, while a key must always precede its
7490 certificate and issuer chain, it can be in a separate file, so long as
7491 that file is listed immediately before the file that holds the corre‐
7492 sponding certificate chain. Once all the files are concatenated, the
7493 sequence of PEM objects must be: key1, cert1, [chain1], key2, cert2,
7494 [chain2], ..., keyN, certN, [chainN].
7495 Storing the private key in the same file as the corresponding certifi‐
7497 cate is more reliable. With the key and certificate in separate files,
7498 there is a chance that during key rollover a Postfix process might load
7499 a private key and certificate from separate files that don't match.
7500 Various operational errors may even result in a persistent broken con‐
7501 figuration in which the certificate does not match the private key.
7502 The file or files must contain at most one key of each type. If, for
7504 example, two or more RSA keys and corresponding chains are listed, de‐
7505 pending on the version of OpenSSL either only the last one will be used
7506 or an configuration error may be detected. Note that while "Ed25519"
7507 and "Ed448" are considered separate algorithms, the various ECDSA
7508 curves (typically one of prime256v1, secp384r1 or secp521r1) are con‐
7509 sidered as different parameters of a single "ECDSA" algorithm, so it is
7510 not presently possible to configure keys for more than one ECDSA curve.
7511 Example (separate files for each key and corresponding certificate
7513 chain):
7514 /etc/postfix/main.cf:
7516 smtp_tls_chain_files =
7517 ${config_directory}/ed25519.pem,
7518 ${config_directory}/ed448.pem,
7519 ${config_directory}/rsa.pem
7520 /etc/postfix/ed25519.pem:
7522 -----BEGIN PRIVATE KEY-----
7523 MC4CAQAwBQYDK2VwBCIEIEJfbbO4BgBQGBg9NAbIJaDBqZb4bC4cOkjtAH+Efbz3
7524 -----END PRIVATE KEY-----
7525 -----BEGIN CERTIFICATE-----
7526 MIIBKzCB3qADAgECAhQaw+rflRreYuUZBp0HuNn/e5rMZDAFBgMrZXAwFDESMBAG
7527 ...
7528 nC0egv51YPDWxEHom4QA
7529 -----END CERTIFICATE-----
7530 /etc/postfix/ed448.pem:
7532 -----BEGIN PRIVATE KEY-----
7533 MEcCAQAwBQYDK2VxBDsEOQf+m0P+G0qi+NZ0RolyeiE5zdlPQR8h8y4jByBifpIe
7534 LNler7nzHQJ1SLcOiXFHXlxp/84VZuh32A==
7535 -----END PRIVATE KEY-----
7536 -----BEGIN CERTIFICATE-----
7537 MIIBdjCB96ADAgECAhQSv4oP972KypOZPNPF4fmsiQoRHzAFBgMrZXEwFDESMBAG
7538 ...
7539 pQcWsx+4J29e6YWH3Cy/CdUaexKP4RPCZDrPX7bk5C2BQ+eeYOxyThMA
7540 -----END CERTIFICATE-----
7541 /etc/postfix/rsa.pem:
7543 -----BEGIN PRIVATE KEY-----
7544 MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDc4QusgkahH9rL
7545 ...
7546 ahQkZ3+krcaJvDSMgvu0tDc=
7547 -----END PRIVATE KEY-----
7548 -----BEGIN CERTIFICATE-----
7549 MIIC+DCCAeCgAwIBAgIUIUkrbk1GAemPCT8i9wKsTGDH7HswDQYJKoZIhvcNAQEL
7550 ...
7551 Rirz15HGVNTK8wzFd+nulPzwUo6dH2IU8KazmyRi7OGvpyrMlm15TRE2oyE=
7552 -----END CERTIFICATE-----
7553 Example (all keys and certificates in a single file):
7555 /etc/postfix/main.cf:
7557 smtp_tls_chain_files = ${config_directory}/chains.pem
7558 /etc/postfix/chains.pem:
7560 -----BEGIN PRIVATE KEY-----
7561 MC4CAQAwBQYDK2VwBCIEIEJfbbO4BgBQGBg9NAbIJaDBqZb4bC4cOkjtAH+Efbz3
7562 -----END PRIVATE KEY-----
7563 -----BEGIN CERTIFICATE-----
7564 MIIBKzCB3qADAgECAhQaw+rflRreYuUZBp0HuNn/e5rMZDAFBgMrZXAwFDESMBAG
7565 ...
7566 nC0egv51YPDWxEHom4QA
7567 -----END CERTIFICATE-----
7568 -----BEGIN PRIVATE KEY-----
7569 MEcCAQAwBQYDK2VxBDsEOQf+m0P+G0qi+NZ0RolyeiE5zdlPQR8h8y4jByBifpIe
7570 LNler7nzHQJ1SLcOiXFHXlxp/84VZuh32A==
7571 -----END PRIVATE KEY-----
7572 -----BEGIN CERTIFICATE-----
7573 MIIBdjCB96ADAgECAhQSv4oP972KypOZPNPF4fmsiQoRHzAFBgMrZXEwFDESMBAG
7574 ...
7575 pQcWsx+4J29e6YWH3Cy/CdUaexKP4RPCZDrPX7bk5C2BQ+eeYOxyThMA
7576 -----END CERTIFICATE-----
7577 -----BEGIN PRIVATE KEY-----
7578 MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDc4QusgkahH9rL
7579 ...
7580 ahQkZ3+krcaJvDSMgvu0tDc=
7581 -----END PRIVATE KEY-----
7582 -----BEGIN CERTIFICATE-----
7583 MIIC+DCCAeCgAwIBAgIUIUkrbk1GAemPCT8i9wKsTGDH7HswDQYJKoZIhvcNAQEL
7584 ...
7585 Rirz15HGVNTK8wzFd+nulPzwUo6dH2IU8KazmyRi7OGvpyrMlm15TRE2oyE=
7586 -----END CERTIFICATE-----
7587 This feature is available in Postfix 3.4 and later.
7589
7591 Obsolete Postfix < 2.3 control for the Postfix SMTP client TLS cipher
7592 list. As this feature applies to all TLS security levels, it is easy to
7593 create interoperability problems by choosing a non-default cipher list.
7594 Do not use a non-default TLS cipher list on hosts that deliver email to
7595 the public Internet: you will be unable to send email to servers that
7596 only support the ciphers you exclude. Using a restricted cipher list
7597 may be more appropriate for an internal MTA, where one can exert some
7598 control over the TLS software and settings of the peer servers.
7599 Note: do not use "" quotes around the parameter value.
7601 This feature is available in Postfix version 2.2. It is not used with
7603 Postfix 2.3 and later; use smtp_tls_mandatory_ciphers instead.
7604
7606 The minimum TLS cipher grade that the Postfix SMTP client will use with
7607 opportunistic TLS encryption. Cipher types listed in smtp_tls_ex‐
7608 clude_ciphers are excluded from the base definition of the selected ci‐
7609 pher grade. The default value is "medium" for Postfix releases after
7610 the middle of 2015, "export" for older releases.
7611 When TLS is mandatory the cipher grade is chosen via the
7613 smtp_tls_mandatory_ciphers configuration parameter, see there for syn‐
7614 tax details. See smtp_tls_policy_maps for information on how to config‐
7615 ure ciphers on a per-destination basis.
7616 This feature is available in Postfix 2.6 and later. With earlier Post‐
7618 fix releases only the smtp_tls_mandatory_ciphers parameter is imple‐
7619 mented, and opportunistic TLS always uses "export" or better (i.e. all)
7620 ciphers.
7621
7623 Try to make multiple deliveries per TLS-encrypted connection. This
7624 uses the tlsproxy(8) service to encrypt an SMTP connection, uses the
7625 scache(8) service to save that connection, and relies on hints from the
7626 qmgr(8) daemon.
7627 See "Client-side TLS connection reuse" for background details.
7629 This feature is available in Postfix 3.4 and later.
7631
7633 The TLS policy for MX hosts with "secure" TLSA records when the nexthop
7634 destination security level is dane, but the MX record was found via an
7635 "insecure" MX lookup. The choices are:
7636 may The TLSA records will be ignored and TLS will be optional. If
7638 the MX host does not appear to support STARTTLS, or the STARTTLS
7639 handshake fails, mail may be sent in the clear.
7640 encrypt
7642 The TLSA records will signal a requirement to use TLS. While
7643 TLS encryption will be required, authentication will not be per‐
7644 formed.
7645 dane The TLSA records will be used just as with "secure" MX records.
7647 TLS encryption will be required, and, if at least one of the
7648 TLSA records is "usable", authentication will be required. When
7649 authentication succeeds, it will be logged only as "Trusted",
7650 not "Verified", because the MX host name could have been forged.
7651 The default setting for Postfix >= 3.6 is "dane" with
7652 "smtp_tls_security_level = dane", otherwise "may". This behavior
7653 was backported to Postfix versions 3.5.9, 3.4.19, 3.3.16.
7654 3.2.21. With earlier Postfix versions the default setting was
7655 always "dane".
7656 Though with "insecure" MX records an active attacker can compromise
7658 SMTP transport security by returning forged MX records, such attacks
7659 are "tamper-evident" since any forged MX hostnames will be recorded in
7660 the mail logs. Attackers who place a high value staying hidden may be
7661 deterred from forging MX records.
7662 This feature is available in Postfix 3.1 and later. The may policy is
7664 backwards-compatible with earlier Postfix versions.
7665
7667 File with the Postfix SMTP client DSA certificate in PEM format. This
7668 file may also contain the Postfix SMTP client private DSA key. The DSA
7669 algorithm is obsolete and should not be used.
7670 See the discussion under smtp_tls_cert_file for more details.
7672 Example:
7674 smtp_tls_dcert_file = /etc/postfix/client-dsa.pem
7676 This feature is available in Postfix 2.2 and later.
7678
7680 File with the Postfix SMTP client DSA private key in PEM format. This
7681 file may be combined with the Postfix SMTP client DSA certificate file
7682 specified with $smtp_tls_dcert_file. The DSA algorithm is obsolete and
7683 should not be used.
7684 The private key must be accessible without a pass-phrase, i.e. it must
7686 not be encrypted. File permissions should grant read-only access to the
7687 system superuser account ("root"), and no access to anyone else.
7688 This feature is available in Postfix 2.2 and later.
7690
7692 File with the Postfix SMTP client ECDSA certificate in PEM format.
7693 This file may also contain the Postfix SMTP client ECDSA private key.
7694 With Postfix >= 3.4 the preferred way to configure client keys and cer‐
7695 tificates is via the "smtp_tls_chain_files" parameter.
7696 See the discussion under smtp_tls_cert_file for more details.
7698 Example:
7700 smtp_tls_eccert_file = /etc/postfix/ecdsa-ccert.pem
7702 This feature is available in Postfix 2.6 and later, when Postfix is
7704 compiled and linked with OpenSSL 1.0.0 or later.
7705
7707 File with the Postfix SMTP client ECDSA private key in PEM format.
7708 This file may be combined with the Postfix SMTP client ECDSA certifi‐
7709 cate file specified with $smtp_tls_eccert_file. With Postfix >= 3.4
7710 the preferred way to configure client keys and certificates is via the
7711 "smtp_tls_chain_files" parameter.
7712 The private key must be accessible without a pass-phrase, i.e. it must
7714 not be encrypted. File permissions should grant read-only access to the
7715 system superuser account ("root"), and no access to anyone else.
7716 This feature is available in Postfix 2.6 and later, when Postfix is
7718 compiled and linked with OpenSSL 1.0.0 or later.
7719
7721 With mandatory TLS encryption, require that the remote SMTP server
7722 hostname matches the information in the remote SMTP server certificate.
7723 As of RFC 2487 the requirements for hostname checking for MTA clients
7724 are not specified.
7725 This option can be set to "no" to disable strict peer name checking.
7727 This setting has no effect on sessions that are controlled via the
7728 smtp_tls_per_site table.
7729 Disabling the hostname verification can make sense in closed environ‐
7731 ment where special CAs are created. If not used carefully, this option
7732 opens the danger of a "man-in-the-middle" attack (the CommonName of
7733 this attacker will be logged).
7734 This feature is available in Postfix 2.2 and later. With Postfix 2.3
7736 and later use smtp_tls_security_level instead.
7737
7739 List of ciphers or cipher types to exclude from the Postfix SMTP client
7740 cipher list at all TLS security levels. This is not an OpenSSL ci‐
7741 pherlist, it is a simple list separated by whitespace and/or commas.
7742 The elements are a single cipher, or one or more "+" separated cipher
7743 properties, in which case only ciphers matching all the properties are
7744 excluded.
7745 Examples (some of these will cause problems):
7747 smtp_tls_exclude_ciphers = aNULL
7749 smtp_tls_exclude_ciphers = MD5, DES
7750 smtp_tls_exclude_ciphers = DES+MD5
7751 smtp_tls_exclude_ciphers = AES256-SHA, DES-CBC3-MD5
7752 smtp_tls_exclude_ciphers = kEDH+aRSA
7753 The first setting, disables anonymous ciphers. The next setting dis‐
7755 ables ciphers that use the MD5 digest algorithm or the (single) DES en‐
7756 cryption algorithm. The next setting disables ciphers that use MD5 and
7757 DES together. The next setting disables the two ciphers "AES256-SHA"
7758 and "DES-CBC3-MD5". The last setting disables ciphers that use "EDH"
7759 key exchange with RSA authentication.
7760 This feature is available in Postfix 2.3 and later.
7762
7764 List of acceptable remote SMTP server certificate fingerprints for the
7765 "fingerprint" TLS security level (smtp_tls_security_level = finger‐
7766 print). At this security level, Certification Authorities are not used,
7767 and certificate expiration times are ignored. Instead, server certifi‐
7768 cates are verified directly via their certificate fingerprint or public
7769 key fingerprint (Postfix 2.9 and later). The fingerprint is a message
7770 digest of the server certificate (or public key). The digest algorithm
7771 is selected via the smtp_tls_fingerprint_digest parameter.
7772 The colons between each pair of nibbles in the fingerprint value are
7774 optional (Postfix >= 3.6). These were required in earlier Postfix re‐
7775 leases.
7776 When an smtp_tls_policy_maps table entry specifies the "fingerprint"
7778 security level, any "match" attributes in that entry specify the list
7779 of valid fingerprints for the corresponding destination. Multiple fin‐
7780 gerprints can be combined with a "|" delimiter in a single match attri‐
7781 bute, or multiple match attributes can be employed.
7782 Example: Certificate fingerprint verification with internal mailhub.
7784 Two matching fingerprints are listed. The relayhost may be multiple
7785 physical hosts behind a load-balancer, each with its own private/public
7786 key and self-signed certificate. Alternatively, a single relayhost may
7787 be in the process of switching from one set of private/public keys to
7788 another, and both keys are trusted just prior to the transition.
7789 relayhost = [mailhub.example.com]
7791 smtp_tls_security_level = fingerprint
7792 smtp_tls_fingerprint_digest = sha256
7793 smtp_tls_fingerprint_cert_match =
7794 cd:fc:d8:db:f8:c4:82:96:6c:...:28:71:e8:f5:8d:a5:0d:9b:d4:a6
7795 dd:5c:ef:f5:c3:bc:64:25:36:...:99:36:06:ce:40:ef:de:2e:ad:a4
7796 Example: Certificate fingerprint verification with selected destina‐
7798 tions. As in the example above, we show two matching fingerprints:
7799 /etc/postfix/main.cf:
7801 smtp_tls_policy_maps = hash:/etc/postfix/tls_policy
7802 smtp_tls_fingerprint_digest = sha256
7803 /etc/postfix/tls_policy:
7805 example.com fingerprint
7806 match=51:e9:af:2e:1e:40:1f:...:64:0a:30:35:2d:09:16:31:5a:eb:82:76
7807 match=b6:b4:72:34:e2:59:cd:...:c2:ca:63:0d:4d:cc:2c:7d:84:de:e6:2f
7808 This feature is available in Postfix 2.5 and later.
7810
7812 The message digest algorithm used to construct remote SMTP server cer‐
7813 tificate fingerprints. At the "fingerprint" TLS security level
7814 (smtp_tls_security_level = fingerprint), the server certificate is ver‐
7815 ified by directly matching its certificate fingerprint or its public
7816 key fingerprint (Postfix 2.9 and later). The fingerprint is the message
7817 digest of the server certificate (or its public key) using the selected
7818 algorithm. With a digest algorithm resistant to "second pre-image" at‐
7819 tacks, it is not feasible to create a new public key and a matching
7820 certificate (or public/private key-pair) that has the same fingerprint.
7821 The default algorithm is sha256 with Postfix >= 3.6 and the compatibil‐
7823 ity_level set to 3.6 or higher. With Postfix <= 3.5, the default algo‐
7824 rithm is md5.
7825 The best-practice algorithm is now sha256. Recent advances in hash
7827 function cryptanalysis have led to md5 and sha1 being deprecated in fa‐
7828 vor of sha256. However, as long as there are no known "second pre-im‐
7829 age" attacks against the older algorithms, their use in this context,
7830 though not recommended, is still likely safe.
7831 While additional digest algorithms are often available with OpenSSL's
7833 libcrypto, only those used by libssl in SSL cipher suites are available
7834 to Postfix. You'll likely find support for md5, sha1, sha256 and
7835 sha512.
7836 To find the fingerprint of a specific certificate file, with a specific
7838 digest algorithm, run:
7839 $ openssl x509 -noout -fingerprint -digest -in certfile.pem
7841 The text to the right of "=" sign is the desired fingerprint. For ex‐
7843 ample:
7844 $ openssl x509 -noout -fingerprint -sha256 -in cert.pem
7846 SHA256 Fingerprint=D4:6A:AB:19:24:...:BB:A6:CB:66:82:C0:8E:9B:EE:29:A8:1A
7847 To extract the public key fingerprint from an X.509 certificate, you
7849 need to extract the public key from the certificate and compute the ap‐
7850 propriate digest of its DER (ASN.1) encoding. With OpenSSL the "-pub‐
7851 key" option of the "x509" command extracts the public key always in
7852 "PEM" format. We pipe the result to another OpenSSL command that con‐
7853 verts the key to DER and then to the "dgst" command to compute the fin‐
7854 gerprint.
7855 The actual command to transform the key to DER format depends on the
7857 version of OpenSSL used. As of OpenSSL 1.0.0, the "pkey" command sup‐
7858 ports all key types.
7859 # OpenSSL >= 1.0 with SHA-256 fingerprints.
7861 $ openssl x509 -in cert.pem -noout -pubkey |
7862 openssl pkey -pubin -outform DER |
7863 openssl dgst -sha256 -c
7864 (stdin)= 64:3f:1f:f6:e5:1e:d4:2a:56:...:fc:09:1a:61:98:b5:bc:7c:60:58
7865 The Postfix SMTP server and client log the peer (leaf) certificate fin‐
7867 gerprint and public key fingerprint when the TLS loglevel is 2 or
7868 higher.
7869 This feature is available in Postfix 2.5 and later.
7871
7873 Lookup the associated DANE TLSA RRset even when a hostname is not an
7874 alias and its address records lie in an unsigned zone. This is un‐
7875 likely to ever yield DNSSEC validated results, since child zones of un‐
7876 signed zones are also unsigned in the absence of DLV or locally config‐
7877 ured non-root trust-anchors. We anticipate that such mechanisms will
7878 not be used for just the "_tcp" subdomain of a host. Suppressing the
7879 TLSA RRset lookup reduces latency and avoids potential interoperability
7880 problems with nameservers for unsigned zones that are not prepared to
7881 handle the new TLSA RRset.
7882 This feature is available in Postfix 2.11.
7884
7886 File with the Postfix SMTP client RSA private key in PEM format. This
7887 file may be combined with the Postfix SMTP client RSA certificate file
7888 specified with $smtp_tls_cert_file. With Postfix >= 3.4 the preferred
7889 way to configure client keys and certificates is via the
7890 "smtp_tls_chain_files" parameter.
7891 The private key must be accessible without a pass-phrase, i.e. it must
7893 not be encrypted. File permissions should grant read-only access to the
7894 system superuser account ("root"), and no access to anyone else.
7895 Example:
7897 smtp_tls_key_file = $smtp_tls_cert_file
7899 This feature is available in Postfix 2.2 and later.
7901
7903 Enable additional Postfix SMTP client logging of TLS activity. Each
7904 logging level also includes the information that is logged at a lower
7905 logging level.
7906 0 Disable logging of TLS activity.
7908 1 Log only a summary message on TLS handshake completion - no
7910 logging of remote SMTP server certificate trust-chain verifica‐
7911 tion errors if server certificate verification is not required.
7912 With Postfix 2.8 and earlier, log the summary message and uncon‐
7913 ditionally log trust-chain verification errors.
7914 2 Also log levels during TLS negotiation.
7916 3 Also log hexadecimal and ASCII dump of TLS negotiation
7918 process.
7919 4 Also log hexadecimal and ASCII dump of complete transmission
7921 after STARTTLS.
7922 Do not use "smtp_tls_loglevel = 2" or higher except in case of prob‐
7924 lems. Use of loglevel 4 is strongly discouraged.
7925 This feature is available in Postfix 2.2 and later.
7927
7929 The minimum TLS cipher grade that the Postfix SMTP client will use with
7930 mandatory TLS encryption. The default value "medium" is suitable for
7931 most destinations with which you may want to enforce TLS, and is beyond
7932 the reach of today's cryptanalytic methods. See smtp_tls_policy_maps
7933 for information on how to configure ciphers on a per-destination basis.
7934 The following cipher grades are supported:
7936 export Enable "EXPORT" grade or better OpenSSL ciphers. The underlying
7938 cipherlist is specified via the tls_export_cipherlist configura‐
7939 tion parameter, which you are strongly encouraged to not change.
7940 This choice is insecure and SHOULD NOT be used.
7941 low Enable "LOW" grade or better OpenSSL ciphers. The underlying
7943 cipherlist is specified via the tls_low_cipherlist configuration
7944 parameter, which you are strongly encouraged to not change.
7945 This choice is insecure and SHOULD NOT be used.
7946 medium Enable "MEDIUM" grade or better OpenSSL ciphers. The underlying
7948 cipherlist is specified via the tls_medium_cipherlist configura‐
7949 tion parameter, which you are strongly encouraged to not change.
7950 high Enable only "HIGH" grade OpenSSL ciphers. This setting may be
7952 appropriate when all mandatory TLS destinations (e.g. when all
7953 mail is routed to a suitably capable relayhost) support at least
7954 one "HIGH" grade cipher. The underlying cipherlist is specified
7955 via the tls_high_cipherlist configuration parameter, which you
7956 are strongly encouraged to not change.
7957 null Enable only the "NULL" OpenSSL ciphers, these provide authenti‐
7959 cation without encryption. This setting is only appropriate in
7960 the rare case that all servers are prepared to use NULL ciphers
7961 (not normally enabled in TLS servers). A plausible use-case is
7962 an LMTP server listening on a UNIX-domain socket that is config‐
7963 ured to support "NULL" ciphers. The underlying cipherlist is
7964 specified via the tls_null_cipherlist configuration parameter,
7965 which you are strongly encouraged to not change.
7966 The underlying cipherlists for grades other than "null" include anony‐
7968 mous ciphers, but these are automatically filtered out if the Postfix
7969 SMTP client is configured to verify server certificates. You are very
7970 unlikely to need to take any steps to exclude anonymous ciphers, they
7971 are excluded automatically as necessary. If you must exclude anonymous
7972 ciphers at the "may" or "encrypt" security levels, when the Postfix
7973 SMTP client does not need or use peer certificates, set "smtp_tls_ex‐
7974 clude_ciphers = aNULL". To exclude anonymous ciphers only when TLS is
7975 enforced, set "smtp_tls_mandatory_exclude_ciphers = aNULL".
7976 This feature is available in Postfix 2.3 and later.
7978
7980 Additional list of ciphers or cipher types to exclude from the Postfix
7981 SMTP client cipher list at mandatory TLS security levels. This list
7982 works in addition to the exclusions listed with smtp_tls_exclude_ci‐
7983 phers (see there for syntax details).
7984 Starting with Postfix 2.6, the mandatory cipher exclusions can be spec‐
7986 ified on a per-destination basis via the TLS policy "exclude" attri‐
7987 bute. See smtp_tls_policy_maps for notes and examples.
7988 This feature is available in Postfix 2.3 and later.
7990
7992 TLS protocols that the Postfix SMTP client will use with mandatory TLS
7993 encryption. In main.cf the values are separated by whitespace, commas
7994 or colons. In the policy table "protocols" attribute (see smtp_tls_pol‐
7995 icy_maps) the only valid separator is colon. An empty value means allow
7996 all protocols.
7997 The valid protocol names (see SSL_get_version(3)) are "SSLv2", "SSLv3",
7999 "TLSv1", "TLSv1.1", "TLSv1.2" and "TLSv1.3". Starting with Postfix
8000 3.6, the default value is ">=TLSv1", which sets TLS 1.0 as the lowest
8001 supported TLS protocol version (see below). Older releases use the "!"
8002 exclusion syntax, also described below.
8003 As of Postfix 3.6, the preferred way to limit the range of acceptable
8005 protocols is to set a lowest acceptable TLS protocol version and/or a
8006 highest acceptable TLS protocol version. To set the lower bound in‐
8007 clude an element of the form: ">=version" where version is a either one
8008 of the TLS protocol names listed above, or a hexadecimal number corre‐
8009 sponding to the desired TLS protocol version (0301 for TLS 1.0, 0302
8010 for TLS 1.1, etc.). For the upper bound, use "<=version". There must
8011 be no whitespace between the ">=" or "<=" symbols and the protocol name
8012 or number.
8013 Hexadecimal protocol numbers make it possible to specify protocol
8015 bounds for TLS versions that are known to OpenSSL, but might not be
8016 known to Postfix. They cannot be used with the legacy exclusion syn‐
8017 tax. Leading "0" or "0x" prefixes are supported, but not required.
8018 Therefore, "301", "0301", "0x301" and "0x0301" are all equivalent to
8019 "TLSv1". Hexadecimal versions unknown to OpenSSL will fail to set the
8020 upper or lower bound, and a warning will be logged. Hexadecimal ver‐
8021 sions should only be used when Postfix is linked with some future ver‐
8022 sion of OpenSSL that supports TLS 1.4 or later, but Postfix does not
8023 yet support a symbolic name for that protocol version.
8024 Hexadecimal example (Postfix >= 3.6):
8026 # Allow only TLS 1.2 through (hypothetical) TLS 1.4, once supported
8028 # in some future version of OpenSSL (presently a warning is logged).
8029 smtp_tls_mandatory_protocols = >=TLSv1.2, <=0305
8030 # Allow only TLS 1.2 and up:
8031 smtp_tls_mandatory_protocols = >=0x0303
8032 With Postfix < 3.6 there is no support for a minimum or maximum ver‐
8034 sion, and the protocol range is configured via protocol exclusions. To
8035 require at least TLS 1.0, set "smtp_tls_mandatory_protocols = !SSLv2,
8036 !SSLv3". Listing the protocols to include, rather than protocols to ex‐
8037 clude, is supported, but not recommended. The exclusion syntax more
8038 accurately matches the underlying OpenSSL interface.
8039 When using the exclusion syntax, take care to ensure that the range of
8041 protocols supported by the Postfix SMTP client is contiguous. When a
8042 protocol version is enabled, disabling any higher version implicitly
8043 disables all versions above that higher version. Thus, for example:
8044 smtp_tls_mandatory_protocols = !SSLv2, !SSLv3, !TLSv1.1
8046 also disables any protocols version higher than TLSv1.1 leaving only
8048 "TLSv1" enabled.
8049 Support for "TLSv1.3" was introduced in OpenSSL 1.1.1. Disabling this
8051 protocol via "!TLSv1.3" is supported since Postfix 3.4 (or patch re‐
8052 leases >= 3.0.14, 3.1.10, 3.2.7 and 3.3.2).
8053 While the vast majority of SMTP servers with DANE TLSA records now sup‐
8055 port at least TLS 1.2, a few still only support TLS 1.0. If you use
8056 "dane" or "dane-only" it is best to not disable TLSv1, except perhaps
8057 via the policy table for destinations which you are sure will support
8058 "TLSv1.2".
8059 See the documentation of the smtp_tls_policy_maps parameter and
8061 TLS_README for more information about security levels.
8062 Example:
8064 # Preferred syntax with Postfix >= 3.6:
8065 smtp_tls_mandatory_protocols = >=TLSv1.2, <=TLSv1.3
8066 # Legacy syntax:
8067 smtp_tls_mandatory_protocols = !SSLv2, !SSLv3, !TLSv1, !TLSv1.1
8068 This feature is available in Postfix 2.3 and later.
8070
8072 Log the hostname of a remote SMTP server that offers STARTTLS, when TLS
8073 is not already enabled for that server.
8074 The logfile record looks like:
8076 postfix/smtp[pid]: Host offered STARTTLS: [name.of.host]
8078 This feature is available in Postfix 2.2 and later.
8080
8082 Optional lookup tables with the Postfix SMTP client TLS usage policy by
8083 next-hop destination and by remote SMTP server hostname. When both
8084 lookups succeed, the more specific per-site policy (NONE, MUST, etc)
8085 overrides the less specific one (MAY), and the more secure per-site
8086 policy (MUST, etc) overrides the less secure one (NONE). With Postfix
8087 2.3 and later smtp_tls_per_site is strongly discouraged: use
8088 smtp_tls_policy_maps instead.
8089 Use of the bare hostname as the per-site table lookup key is discour‐
8091 aged. Always use the full destination nexthop (enclosed in [] with a
8092 possible ":port" suffix). A recipient domain or MX-enabled transport
8093 next-hop with no port suffix may look like a bare hostname, but is
8094 still a suitable destination.
8095 Specify a next-hop destination or server hostname on the left-hand
8097 side; no wildcards are allowed. The next-hop destination is either the
8098 recipient domain, or the destination specified with a transport(5) ta‐
8099 ble, the relayhost parameter, or the relay_transport parameter. On the
8100 right hand side specify one of the following keywords:
8101 NONE Don't use TLS at all. This overrides a less specific MAY lookup
8103 result from the alternate host or next-hop lookup key, and over‐
8104 rides the global smtp_use_tls, smtp_enforce_tls, and
8105 smtp_tls_enforce_peername settings.
8106 MAY Try to use TLS if the server announces support, otherwise use
8108 the unencrypted connection. This has less precedence than a more
8109 specific result (including NONE) from the alternate host or
8110 next-hop lookup key, and has less precedence than the more spe‐
8111 cific global "smtp_enforce_tls = yes" or "smtp_tls_enforce_peer‐
8112 name = yes".
8113 MUST_NOPEERMATCH
8115 Require TLS encryption, but do not require that the remote SMTP
8116 server hostname matches the information in the remote SMTP
8117 server certificate, or that the server certificate was issued by
8118 a trusted CA. This overrides a less secure NONE or a less spe‐
8119 cific MAY lookup result from the alternate host or next-hop
8120 lookup key, and overrides the global smtp_use_tls, smtp_en‐
8121 force_tls and smtp_tls_enforce_peername settings.
8122 MUST Require TLS encryption, require that the remote SMTP server
8124 hostname matches the information in the remote SMTP server cer‐
8125 tificate, and require that the remote SMTP server certificate
8126 was issued by a trusted CA. This overrides a less secure NONE
8127 and MUST_NOPEERMATCH or a less specific MAY lookup result from
8128 the alternate host or next-hop lookup key, and overrides the
8129 global smtp_use_tls, smtp_enforce_tls and smtp_tls_enforce_peer‐
8130 name settings.
8131 The above keywords correspond to the "none", "may", "encrypt" and "ver‐
8133 ify" security levels for the new smtp_tls_security_level parameter in‐
8134 troduced in Postfix 2.3. Starting with Postfix 2.3, and independently
8135 of how the policy is specified, the smtp_tls_mandatory_ciphers and
8136 smtp_tls_mandatory_protocols parameters apply when TLS encryption is
8137 mandatory. Connections for which encryption is optional typically en‐
8138 able all "export" grade and better ciphers (see smtp_tls_ciphers and
8139 smtp_tls_protocols).
8140 As long as no secure DNS lookup mechanism is available, false hostnames
8142 in MX or CNAME responses can change the server hostname that Postfix
8143 uses for TLS policy lookup and server certificate verification. Even
8144 with a perfect match between the server hostname and the server cer‐
8145 tificate, there is no guarantee that Postfix is connected to the right
8146 server. See TLS_README (Closing a DNS loophole with obsolete per-site
8147 TLS policies) for a possible work-around.
8148 This feature is available in Postfix 2.2 and later. With Postfix 2.3
8150 and later use smtp_tls_policy_maps instead.
8151
8153 Optional lookup tables with the Postfix SMTP client TLS security policy
8154 by next-hop destination; when a non-empty value is specified, this
8155 overrides the obsolete smtp_tls_per_site parameter. See TLS_README for
8156 a more detailed discussion of TLS security levels.
8157 Specify zero or more "type:name" lookup tables, separated by whitespace
8159 or comma. Tables will be searched in the specified order until a match
8160 is found.
8161 The TLS policy table is indexed by the full next-hop destination, which
8163 is either the recipient domain, or the verbatim next-hop specified in
8164 the transport table, $local_transport, $virtual_transport, $re‐
8165 lay_transport or $default_transport. This includes any enclosing square
8166 brackets and any non-default destination server port suffix. The LMTP
8167 socket type prefix (inet: or unix:) is not included in the lookup key.
8168 Only the next-hop domain, or $myhostname with LMTP over UNIX-domain
8170 sockets, is used as the nexthop name for certificate verification. The
8171 port and any enclosing square brackets are used in the table lookup
8172 key, but are not used for server name verification.
8173 When the lookup key is a domain name without enclosing square brackets
8175 or any :port suffix (typically the recipient domain), and the full do‐
8176 main is not found in the table, just as with the transport(5) table,
8177 the parent domain starting with a leading "." is matched recursively.
8178 This allows one to specify a security policy for a recipient domain and
8179 all its sub-domains.
8180 The lookup result is a security level, followed by an optional list of
8182 whitespace and/or comma separated name=value attributes that override
8183 related main.cf settings. The TLS security levels in order of increas‐
8184 ing security are:
8185 none No TLS. No additional attributes are supported at this level.
8187 may Opportunistic TLS. Since sending in the clear is acceptable, de‐
8189 manding stronger than default TLS security merely reduces inter‐
8190 operability. The optional "ciphers", "exclude", and "protocols"
8191 attributes (available for opportunistic TLS with Postfix >= 2.6)
8192 and "connection_reuse" attribute (Postfix >= 3.4) override the
8193 "smtp_tls_ciphers", "smtp_tls_exclude_ciphers", "smtp_tls_proto‐
8194 cols", and "smtp_tls_connection_reuse" configuration parameters.
8195 When opportunistic TLS handshakes fail, Postfix retries the con‐
8196 nection with TLS disabled. This allows mail delivery to sites
8197 with non-interoperable TLS implementations.
8198 encrypt
8200 Mandatory TLS encryption. At this level and higher, the optional
8201 "protocols" attribute overrides the main.cf smtp_tls_manda‐
8202 tory_protocols parameter, the optional "ciphers" attribute over‐
8203 rides the main.cf smtp_tls_mandatory_ciphers parameter, the op‐
8204 tional "exclude" attribute (Postfix >= 2.6) overrides the
8205 main.cf smtp_tls_mandatory_exclude_ciphers parameter, and the
8206 optional "connection_reuse" attribute (Postfix >= 3.4) overrides
8207 the main.cf smtp_tls_connection_reuse parameter. In the policy
8208 table, multiple protocols or excluded ciphers must be separated
8209 by colons, as attribute values may not contain whitespace or
8210 commas.
8211 dane Opportunistic DANE TLS. The TLS policy for the destination is
8213 obtained via TLSA records in DNSSEC. If no TLSA records are
8214 found, the effective security level used is may. If TLSA
8215 records are found, but none are usable, the effective security
8216 level is encrypt. When usable TLSA records are obtained for the
8217 remote SMTP server, the server certificate must match the TLSA
8218 records. RFC 7672 (DANE) TLS authentication and DNSSEC support
8219 is available with Postfix 2.11 and later. The optional "connec‐
8220 tion_reuse" attribute (Postfix >= 3.4) overrides the main.cf
8221 smtp_tls_connection_reuse parameter.
8222 dane-only
8224 Mandatory DANE TLS. The TLS policy for the destination is ob‐
8225 tained via TLSA records in DNSSEC. If no TLSA records are
8226 found, or none are usable, no connection is made to the server.
8227 When usable TLSA records are obtained for the remote SMTP
8228 server, the server certificate must match the TLSA records. RFC
8229 7672 (DANE) TLS authentication and DNSSEC support is available
8230 with Postfix 2.11 and later. The optional "connection_reuse" at‐
8231 tribute (Postfix >= 3.4) overrides the main.cf smtp_tls_connec‐
8232 tion_reuse parameter.
8233 fingerprint
8235 Certificate fingerprint verification. Available with Postfix 2.5
8236 and later. At this security level, there are no trusted Certifi‐
8237 cation Authorities. The certificate trust chain, expiration
8238 date, ... are not checked. Instead, the optional match attri‐
8239 bute, or else the main.cf smtp_tls_fingerprint_cert_match param‐
8240 eter, lists the certificate fingerprints or the public key fin‐
8241 gerprint (Postfix 2.9 and later) of the valid server certifi‐
8242 cate. The digest algorithm used to calculate the fingerprint is
8243 selected by the smtp_tls_fingerprint_digest parameter. Multiple
8244 fingerprints can be combined with a "|" delimiter in a single
8245 match attribute, or multiple match attributes can be employed.
8246 The ":" character is not used as a delimiter as it occurs be‐
8247 tween each pair of fingerprint (hexadecimal) digits. The op‐
8248 tional "connection_reuse" attribute (Postfix >= 3.4) overrides
8249 the main.cf smtp_tls_connection_reuse parameter.
8250 verify Mandatory TLS verification. At this security level, DNS MX
8252 lookups are trusted to be secure enough, and the name verified
8253 in the server certificate is usually obtained indirectly via
8254 unauthenticated DNS MX lookups. The optional "match" attribute
8255 overrides the main.cf smtp_tls_verify_cert_match parameter. In
8256 the policy table, multiple match patterns and strategies must be
8257 separated by colons. In practice explicit control over matching
8258 is more common with the "secure" policy, described below. The
8259 optional "connection_reuse" attribute (Postfix >= 3.4) overrides
8260 the main.cf smtp_tls_connection_reuse parameter.
8261 secure Secure-channel TLS. At this security level, DNS MX lookups,
8263 though potentially used to determine the candidate next-hop
8264 gateway IP addresses, are not trusted to be secure enough for
8265 TLS peername verification. Instead, the default name verified in
8266 the server certificate is obtained directly from the next-hop,
8267 or is explicitly specified via the optional match attribute
8268 which overrides the main.cf smtp_tls_secure_cert_match parame‐
8269 ter. In the policy table, multiple match patterns and strategies
8270 must be separated by colons. The match attribute is most useful
8271 when multiple domains are supported by common server, the policy
8272 entries for additional domains specify matching rules for the
8273 primary domain certificate. While transport table overrides
8274 routing the secondary domains to the primary nexthop also allow
8275 secure verification, they risk delivery to the wrong destination
8276 when domains change hands or are re-assigned to new gateways.
8277 With the "match" attribute approach, routing is not perturbed,
8278 and mail is deferred if verification of a new MX host fails. The
8279 optional "connection_reuse" attribute (Postfix >= 3.4) overrides
8280 the main.cf smtp_tls_connection_reuse parameter.
8281 Example:
8283 /etc/postfix/main.cf:
8285 smtp_tls_policy_maps = hash:/etc/postfix/tls_policy
8286 # Postfix 2.5 and later.
8287 #
8288 # The default digest is sha256 with Postfix >= 3.6 and
8289 # compatibility level >= 3.
8290 #
8291 smtp_tls_fingerprint_digest = sha256
8292 /etc/postfix/tls_policy:
8294 example.edu none
8295 example.mil may
8296 example.gov encrypt protocols=TLSv1
8297 example.com verify ciphers=high
8298 example.net secure
8299 .example.net secure match=.example.net:example.net
8300 [mail.example.org]:587 secure match=nexthop
8301 # Postfix 2.5 and later
8302 [thumb.example.org] fingerprint
8303 match=b6:b4:72:34:e2:59:cd:...:c2:ca:63:0d:4d:cc:2c:7d:84:de:e6:2f
8304 match=51:e9:af:2e:1e:40:1f:...:64:0a:30:35:2d:09:16:31:5a:eb:82:76
8305 Note: The hostname strategy if listed in a non-default setting of
8307 smtp_tls_secure_cert_match or in the match attribute in the policy ta‐
8308 ble can render the secure level vulnerable to DNS forgery. Do not use
8309 the hostname strategy for secure-channel configurations in environments
8310 where DNS security is not assured.
8311 This feature is available in Postfix 2.3 and later.
8313
8315 TLS protocols that the Postfix SMTP client will use with opportunistic
8316 TLS encryption. In main.cf the values are separated by whitespace,
8317 commas or colons. In the policy table "protocols" attribute (see
8318 smtp_tls_policy_maps) the only valid separator is colon. An empty
8319 value means allow all protocols.
8320 The valid protocol names (see SSL_get_version(3)) are "SSLv2", "SSLv3",
8322 "TLSv1", "TLSv1.1", "TLSv1.2" and "TLSv1.3". Starting with Postfix
8323 3.6, the default value is ">=TLSv1", which sets TLS 1.0 as the lowest
8324 supported TLS protocol version (see below). Older releases use the "!"
8325 exclusion syntax, also described below.
8326 As of Postfix 3.6, the preferred way to limit the range of acceptable
8328 protocols is to set the lowest acceptable TLS protocol version and/or
8329 the highest acceptable TLS protocol version. To set the lower bound
8330 include an element of the form: ">=version" where version is a either
8331 one of the TLS protocol names listed above, or a hexadecimal number
8332 corresponding to the desired TLS protocol version (0301 for TLS 1.0,
8333 0302 for TLS 1.1, etc.). For the upper bound, use "<=version". There
8334 must be no whitespace between the ">=" or "<=" symbols and the protocol
8335 name or number.
8336 Hexadecimal protocol numbers make it possible to specify protocol
8338 bounds for TLS versions that are known to OpenSSL, but might not be
8339 known to Postfix. They cannot be used with the legacy exclusion syn‐
8340 tax. Leading "0" or "0x" prefixes are supported, but not required.
8341 Therefore, "301", "0301", "0x301" and "0x0301" are all equivalent to
8342 "TLSv1". Hexadecimal versions unknown to OpenSSL will fail to set the
8343 upper or lower bound, and a warning will be logged. Hexadecimal ver‐
8344 sions should only be used when Postfix is linked with some future ver‐
8345 sion of OpenSSL that supports TLS 1.4 or later, but Postfix does not
8346 yet support a symbolic name for that protocol version.
8347 Hexadecimal example (Postfix >= 3.6):
8349 # Allow only TLS 1.0 through (hypothetical) TLS 1.4, once supported
8351 # in some future version of OpenSSL (presently a warning is logged).
8352 smtp_tls_protocols = >=TLSv1, <=0305
8353 # Allow only TLS 1.0 and up:
8354 smtp_tls_protocols = >=0x0301
8355 With Postfix < 3.6 there is no support for a minimum or maximum ver‐
8357 sion, and the protocol range is configured via protocol exclusions. To
8358 require at least TLS 1.0, set "smtp_tls_protocols = !SSLv2, !SSLv3".
8359 Listing the protocols to include, rather than protocols to exclude, is
8360 supported, but not recommended. The exclusion form more accurately
8361 matches the underlying OpenSSL interface.
8362 When using the exclusion syntax, take care to ensure that the range of
8364 protocols advertised by an SSL/TLS client is contiguous. When a proto‐
8365 col version is enabled, disabling any higher version implicitly dis‐
8366 ables all versions above that higher version. Thus, for example:
8367 smtp_tls_protocols = !SSLv2, !SSLv3, !TLSv1.1
8369 also disables any protocols version higher than TLSv1.1 leaving only
8370 "TLSv1" enabled.
8371 Support for "TLSv1.3" was introduced in OpenSSL 1.1.1. Disabling this
8373 protocol via "!TLSv1.3" is supported since Postfix 3.4 (or patch re‐
8374 leases >= 3.0.14, 3.1.10, 3.2.7 and 3.3.2).
8375 Example:
8377 # Preferred syntax with Postfix >= 3.6:
8378 smtp_tls_protocols = >=TLSv1, <=TLSv1.3
8379 # Legacy syntax:
8380 smtp_tls_protocols = !SSLv2, !SSLv3
8381 This feature is available in Postfix 2.6 and later.
8383
8385 The verification depth for remote SMTP server certificates. A depth of
8386 1 is sufficient if the issuing CA is listed in a local CA file.
8387 The default verification depth is 9 (the OpenSSL default) for compati‐
8389 bility with earlier Postfix behavior. Prior to Postfix 2.5, the default
8390 value was 5, but the limit was not actually enforced. If you have set
8391 this to a lower non-default value, certificates with longer trust
8392 chains may now fail to verify. Certificate chains with 1 or 2 CAs are
8393 common, deeper chains are more rare and any number between 5 and 9
8394 should suffice in practice. You can choose a lower number if, for exam‐
8395 ple, you trust certificates directly signed by an issuing CA but not
8396 any CAs it delegates to.
8397 This feature is available in Postfix 2.2 and later.
8399
8401 How the Postfix SMTP client verifies the server certificate peername
8402 for the "secure" TLS security level. In a "secure" TLS policy table
8403 ($smtp_tls_policy_maps) entry the optional "match" attribute overrides
8404 this main.cf setting.
8405 This parameter specifies one or more patterns or strategies separated
8407 by commas, whitespace or colons. In the policy table the only valid
8408 separator is the colon character.
8409 For a description of the pattern and strategy syntax see the
8411 smtp_tls_verify_cert_match parameter. The "hostname" strategy should be
8412 avoided in this context, as in the absence of a secure global DNS, us‐
8413 ing the results of MX lookups in certificate verification is not immune
8414 to active (man-in-the-middle) attacks on DNS.
8415 Sample main.cf setting:
8417 smtp_tls_secure_cert_match = nexthop
8419 Sample policy table override:
8421 example.net secure match=example.com:.example.com
8423 .example.net secure match=example.com:.example.com
8424 This feature is available in Postfix 2.3 and later.
8426
8428 The default SMTP TLS security level for the Postfix SMTP client; when a
8429 non-empty value is specified, this overrides the obsolete parameters
8430 smtp_use_tls, smtp_enforce_tls, and smtp_tls_enforce_peername.
8431 Specify one of the following security levels:
8433 none No TLS. TLS will not be used unless enabled for specific desti‐
8435 nations via smtp_tls_policy_maps.
8436 may Opportunistic TLS. Use TLS if this is supported by the remote
8438 SMTP server, otherwise use plaintext. Since sending in the clear
8439 is acceptable, demanding stronger than default TLS security
8440 merely reduces interoperability. The "smtp_tls_ciphers" and
8441 "smtp_tls_protocols" (Postfix >= 2.6) configuration parameters
8442 provide control over the protocols and cipher grade used with
8443 opportunistic TLS. With earlier releases the opportunistic TLS
8444 cipher grade is always "export" and no protocols are disabled.
8445 When TLS handshakes fail, the connection is retried with TLS
8446 disabled. This allows mail delivery to sites with non-interop‐
8447 erable TLS implementations.
8448 encrypt
8450 Mandatory TLS encryption. Since a minimum level of security is
8451 intended, it is reasonable to be specific about sufficiently se‐
8452 cure protocol versions and ciphers. At this security level and
8453 higher, the main.cf parameters smtp_tls_mandatory_protocols and
8454 smtp_tls_mandatory_ciphers specify the TLS protocols and minimum
8455 cipher grade which the administrator considers secure enough for
8456 mandatory encrypted sessions. This security level is not an ap‐
8457 propriate default for systems delivering mail to the Internet.
8458 dane Opportunistic DANE TLS. At this security level, the TLS policy
8460 for the destination is obtained via DNSSEC. For TLSA policy to
8461 be in effect, the destination domain's containing DNS zone must
8462 be signed and the Postfix SMTP client's operating system must be
8463 configured to send its DNS queries to a recursive DNS nameserver
8464 that is able to validate the signed records. Each MX host's DNS
8465 zone should also be signed, and should publish DANE TLSA (RFC
8466 7672) records that specify how that MX host's TLS certificate is
8467 to be verified. TLSA records do not preempt the normal SMTP MX
8468 host selection algorithm, if some MX hosts support TLSA and oth‐
8469 ers do not, TLS security will vary from delivery to delivery.
8470 It is up to the domain owner to configure their MX hosts and
8471 their DNS sensibly. To configure the Postfix SMTP client for
8472 DNSSEC lookups see the documentation for the smtp_dns_sup‐
8473 port_level main.cf parameter. When DNSSEC-validated TLSA
8474 records are not found the effective tls security level is "may".
8475 When TLSA records are found, but are all unusable the effective
8476 security level is "encrypt". For purposes of protocol and ci‐
8477 pher selection, the "dane" security level is treated like a
8478 "mandatory" TLS security level, and weak ciphers and protocols
8479 are disabled. Since DANE authenticates server certificates the
8480 "aNULL" cipher-suites are transparently excluded at this level,
8481 no need to configure this manually. RFC 7672 (DANE) TLS authen‐
8482 tication is available with Postfix 2.11 and later.
8483 dane-only
8485 Mandatory DANE TLS. This is just like "dane" above, but DANE
8486 TLSA authentication is required. There is no fallback to "may"
8487 or "encrypt" when TLSA records are missing or unusable. RFC
8488 7672 (DANE) TLS authentication is available with Postfix 2.11
8489 and later.
8490 fingerprint
8492 Certificate fingerprint verification. At this security level,
8493 there are no trusted Certification Authorities. The certificate
8494 trust chain, expiration date, etc., are not checked. Instead,
8495 the smtp_tls_fingerprint_cert_match parameter lists the certifi‐
8496 cate fingerprint or public key fingerprint (Postfix 2.9 and
8497 later) of the valid server certificate. The digest algorithm
8498 used to calculate the fingerprint is selected by the
8499 smtp_tls_fingerprint_digest parameter. Available with Postfix
8500 2.5 and later.
8501 verify Mandatory TLS verification. At this security level, DNS MX
8503 lookups are trusted to be secure enough, and the name verified
8504 in the server certificate is usually obtained indirectly via
8505 unauthenticated DNS MX lookups. The smtp_tls_verify_cert_match
8506 parameter controls how the server name is verified. In practice
8507 explicit control over matching is more common at the "secure"
8508 level, described below. This security level is not an appropri‐
8509 ate default for systems delivering mail to the Internet.
8510 secure Secure-channel TLS. At this security level, DNS MX lookups,
8512 though potentially used to determine the candidate next-hop
8513 gateway IP addresses, are not trusted to be secure enough for
8514 TLS peername verification. Instead, the default name verified in
8515 the server certificate is obtained from the next-hop domain as
8516 specified in the smtp_tls_secure_cert_match configuration param‐
8517 eter. The default matching rule is that a server certificate
8518 matches when its name is equal to or is a sub-domain of the nex‐
8519 thop domain. This security level is not an appropriate default
8520 for systems delivering mail to the Internet.
8521 Examples:
8523 # No TLS. Formerly: smtp_use_tls=no and smtp_enforce_tls=no.
8525 smtp_tls_security_level = none
8526 # Opportunistic TLS.
8528 smtp_tls_security_level = may
8529 # Do not tweak opportunistic ciphers or protocol unless it is essential
8530 # to do so (if a security vulnerability is found in the SSL library that
8531 # can be mitigated by disabling a particular protocol or raising the
8532 # cipher grade).
8533 smtp_tls_ciphers = medium
8534 smtp_tls_protocols = >=TLSv1
8535 # Legacy (Postfix < 3.6) syntax:
8536 smtp_tls_protocols = !SSLv2, !SSLv3
8537 # Mandatory (high-grade) TLS encryption.
8539 smtp_tls_security_level = encrypt
8540 smtp_tls_mandatory_ciphers = high
8541 # Authenticated TLS 1.2 or better matching the nexthop domain or a
8543 # subdomain.
8544 smtp_tls_security_level = secure
8545 smtp_tls_mandatory_ciphers = high
8546 smtp_tls_mandatory_protocols = >=TLSv1.2
8547 smtp_tls_secure_cert_match = nexthop, dot-nexthop
8548 # Certificate fingerprint verification (Postfix >= 2.5).
8550 # The CA-less "fingerprint" security level only scales to a limited
8551 # number of destinations. As a global default rather than a per-site
8552 # setting, this is practical only when mail for all recipients is sent
8553 # to a central mail hub.
8554 relayhost = [mailhub.example.com]
8555 smtp_tls_security_level = fingerprint
8556 smtp_tls_mandatory_protocols = >=TLSv1.2
8557 smtp_tls_mandatory_ciphers = high
8558 smtp_tls_fingerprint_cert_match =
8559 3D:95:34:51:...:40:99:C0:C1
8560 EC:3B:2D:B0:...:A3:9D:72:F6
8561 This feature is available in Postfix 2.3 and later.
8563
8565 Optional name to send to the remote SMTP server in the TLS Server Name
8566 Indication (SNI) extension. The SNI extension is always on when DANE
8567 is used to authenticate the server, and in that case the SNI name sent
8568 is the one required by RFC7672 and this parameter is ignored.
8569 Some SMTP servers use the received SNI name to select an appropriate
8571 certificate chain to present to the client. While this may improve in‐
8572 teroperability with such servers, it may reduce interoperability with
8573 other servers that choose to abort the connection when they don't have
8574 a certificate chain configured for the requested name. Such servers
8575 should select a default certificate chain and continue the handshake,
8576 but some may not. Therefore, absent DANE, no SNI name is sent by de‐
8577 fault.
8578 The SNI name must be either a valid DNS hostname, or else one of the
8580 special values hostname or nexthop, which select either the remote
8581 hostname or the nexthop domain respectively. DNS names for SNI must be
8582 in A-label (punycode) form. Invalid DNS names log a configuration er‐
8583 ror warning and mail delivery is deferred.
8584 Except when using a relayhost to forward all email, the only sensible
8586 non-empty main.cf setting for this parameter is hostname. Other
8587 non-empty values are only practical on a per-destination basis via the
8588 servername attribute of the Postfix TLS policy table. When in doubt,
8589 leave this parameter empty, and configure per-destination SNI as
8590 needed.
8591 This feature is available in Postfix 3.4 and later.
8593
8595 Name of the file containing the optional Postfix SMTP client TLS ses‐
8596 sion cache. Specify a database type that supports enumeration, such as
8597 btree or sdbm; there is no need to support concurrent access. The file
8598 is created if it does not exist. The smtp(8) daemon does not use this
8599 parameter directly, rather the cache is implemented indirectly in the
8600 tlsmgr(8) daemon. This means that per-smtp-instance master.cf overrides
8601 of this parameter are not effective. Note, that each of the cache
8602 databases supported by tlsmgr(8) daemon: $smtpd_tls_session_cache_data‐
8603 base, $smtp_tls_session_cache_database (and with Postfix 2.3 and later
8604 $lmtp_tls_session_cache_database), needs to be stored separately. It is
8605 not at this time possible to store multiple caches in a single data‐
8606 base.
8607 Note: dbm databases are not suitable. TLS session objects are too
8609 large.
8610 As of version 2.5, Postfix no longer uses root privileges when opening
8612 this file. The file should now be stored under the Postfix-owned
8613 data_directory. As a migration aid, an attempt to open the file under a
8614 non-Postfix directory is redirected to the Postfix-owned data_direc‐
8615 tory, and a warning is logged.
8616 Example:
8618 smtp_tls_session_cache_database = btree:/var/lib/postfix/smtp_scache
8620 This feature is available in Postfix 2.2 and later.
8622
8624 The expiration time of Postfix SMTP client TLS session cache informa‐
8625 tion. A cache cleanup is performed periodically every $smtp_tls_ses‐
8626 sion_cache_timeout seconds. As with $smtp_tls_session_cache_database,
8627 this parameter is implemented in the tlsmgr(8) daemon and therefore
8628 per-smtp-instance master.cf overrides are not possible.
8629 As of Postfix 2.11 this setting cannot exceed 100 days. If set <= 0,
8631 session caching is disabled. If set to a positive value less than 2
8632 minutes, the minimum value of 2 minutes is used instead.
8633 This feature is available in Postfix 2.2 and later.
8635
8637 Zero or more PEM-format files with trust-anchor certificates and/or
8638 public keys. If the parameter is not empty the root CAs in CAfile and
8639 CApath are no longer trusted. Rather, the Postfix SMTP client will
8640 only trust certificate-chains signed by one of the trust-anchors con‐
8641 tained in the chosen files. The specified trust-anchor certificates
8642 and public keys are not subject to expiration, and need not be
8643 (self-signed) root CAs. They may, if desired, be intermediate certifi‐
8644 cates. Therefore, these certificates also may be found "in the middle"
8645 of the trust chain presented by the remote SMTP server, and any un‐
8646 trusted issuing parent certificates will be ignored. Specify a list of
8647 pathnames separated by comma or whitespace.
8648 Whether specified in main.cf, or on a per-destination basis, the
8650 trust-anchor PEM file must be accessible to the Postfix SMTP client in
8651 the chroot jail if applicable. The trust-anchor file should contain
8652 only certificates and public keys, no private key material, and must be
8653 readable by the non-privileged $mail_owner user. This allows destina‐
8654 tions to be bound to a set of specific CAs or public keys without
8655 trusting the same CAs for all destinations.
8656 The main.cf parameter supports single-purpose Postfix installations
8658 that send mail to a fixed set of SMTP peers. At most sites, if
8659 trust-anchor files are used at all, they will be specified on a
8660 per-destination basis via the "tafile" attribute of the "verify" and
8661 "secure" levels in smtp_tls_policy_maps.
8662 The underlying mechanism is in support of RFC 7672 (DANE TLSA), which
8664 defines mechanisms for an SMTP client MTA to securely determine server
8665 TLS certificates via DNS.
8666 If you want your trust anchors to be public keys, with OpenSSL you can
8668 extract a single PEM public key from a PEM X.509 file containing a sin‐
8669 gle certificate, as follows:
8670 $ openssl x509 -in cert.pem -out ta-key.pem -noout -pubkey
8672 This feature is available in Postfix 2.11 and later.
8674
8676 How the Postfix SMTP client verifies the server certificate peername
8677 for the "verify" TLS security level. In a "verify" TLS policy table
8678 ($smtp_tls_policy_maps) entry the optional "match" attribute overrides
8679 this main.cf setting.
8680 This parameter specifies one or more patterns or strategies separated
8682 by commas, whitespace or colons. In the policy table the only valid
8683 separator is the colon character.
8684 Patterns specify domain names, or domain name suffixes:
8686 example.com
8688 Match the example.com domain, i.e. one of the names in the
8689 server certificate must be example.com. Upper and lower case
8690 distinctions are ignored.
8691 .example.com
8693 Match subdomains of the example.com domain, i.e. match a name in
8694 the server certificate that consists of a non-zero number of la‐
8695 bels followed by a .example.com suffix. Case distinctions are
8696 ignored.
8697 Strategies specify a transformation from the next-hop domain to the ex‐
8699 pected name in the server certificate:
8700 nexthop
8702 Match against the next-hop domain, which is either the recipient
8703 domain, or the transport next-hop configured for the domain
8704 stripped of any optional socket type prefix, enclosing square
8705 brackets and trailing port. When MX lookups are not suppressed,
8706 this is the original nexthop domain prior to the MX lookup, not
8707 the result of the MX lookup. For LMTP delivery via UNIX-domain
8708 sockets, the verified next-hop name is $myhostname. This strat‐
8709 egy is suitable for use with the "secure" policy. Case is ig‐
8710 nored.
8711 dot-nexthop
8713 As above, but match server certificate names that are subdomains
8714 of the next-hop domain. Case is ignored.
8715 hostname
8717 Match against the hostname of the server, often obtained via an
8718 unauthenticated DNS MX lookup. For LMTP delivery via UNIX-domain
8719 sockets, the verified name is $myhostname. This matches the ver‐
8720 ification strategy of the "MUST" keyword in the obsolete
8721 smtp_tls_per_site table, and is suitable for use with the "ver‐
8722 ify" security level. When the next-hop name is enclosed in
8723 square brackets to suppress MX lookups, the "hostname" strategy
8724 is the same as the "nexthop" strategy. Case is ignored.
8725 Sample main.cf setting:
8727 smtp_tls_verify_cert_match = hostname, nexthop, dot-nexthop
8729 Sample policy table override:
8731 example.com verify match=hostname:nexthop
8733 .example.com verify match=example.com:.example.com:hostname
8734 This feature is available in Postfix 2.3 and later.
8736
8738 Request that the Postfix SMTP client connects using the legacy SMTPS
8739 protocol instead of using the STARTTLS command.
8740 This mode requires "smtp_tls_security_level = encrypt" or stronger.
8742 Example: deliver all remote mail via a provider's server "mail.exam‐
8744 ple.com".
8745 /etc/postfix/main.cf:
8747 # Client-side SMTPS requires "encrypt" or stronger.
8748 smtp_tls_security_level = encrypt
8749 smtp_tls_wrappermode = yes
8750 # The [] suppress MX lookups.
8751 relayhost = [mail.example.com]:465
8752 More examples are in TLS_README, including examples for older Postfix
8754 versions.
8755 This feature is available in Postfix 3.0 and later.
8757
8759 Opportunistic mode: use TLS when a remote SMTP server announces START‐
8760 TLS support, otherwise send the mail in the clear. Beware: some SMTP
8761 servers offer STARTTLS even if it is not configured. With Postfix <
8762 2.3, if the TLS handshake fails, and no other server is available, de‐
8763 livery is deferred and mail stays in the queue. If this is a concern
8764 for you, use the smtp_tls_per_site feature instead.
8765 This feature is available in Postfix 2.2 and later. With Postfix 2.3
8767 and later use smtp_tls_security_level instead.
8768
8770 The Postfix SMTP client time limit for sending the XFORWARD command,
8771 and for receiving the remote SMTP server response.
8772 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
8774 The default time unit is s (seconds).
8775 This feature is available in Postfix 2.1 and later.
8777
8779 What remote SMTP clients are allowed to specify the XVERP command.
8780 This command requests that mail be delivered one recipient at a time
8781 with a per recipient return address.
8782 By default, no clients are allowed to specify XVERP.
8784 This parameter was renamed with Postfix version 2.1. The default value
8786 is backwards compatible with Postfix version 2.0.
8787 Specify a list of network/netmask patterns, separated by commas and/or
8789 whitespace. The mask specifies the number of bits in the network part
8790 of a host address. You can also specify hostnames or .domain names (the
8791 initial dot causes the domain to match any name below it),
8792 "/file/name" or "type:table" patterns. A "/file/name" pattern is re‐
8793 placed by its contents; a "type:table" lookup table is matched when a
8794 table entry matches a lookup string (the lookup result is ignored).
8795 Continue long lines by starting the next line with whitespace. Specify
8796 "!pattern" to exclude an address or network block from the list. The
8797 form "!/file/name" is supported only in Postfix version 2.4 and later.
8798 Note: IP version 6 address information must be specified inside [] in
8800 the smtpd_authorized_verp_clients value, and in files specified with
8801 "/file/name". IP version 6 addresses contain the ":" character, and
8802 would otherwise be confused with a "type:table" pattern.
8803
8805 What remote SMTP clients are allowed to use the XCLIENT feature. This
8806 command overrides remote SMTP client information that is used for ac‐
8807 cess control. Typical use is for SMTP-based content filters, fetch‐
8808 mail-like programs, or SMTP server access rule testing. See the
8809 XCLIENT_README document for details.
8810 This feature is available in Postfix 2.1 and later.
8812 By default, no clients are allowed to specify XCLIENT.
8814 Specify a list of network/netmask patterns, separated by commas and/or
8816 whitespace. The mask specifies the number of bits in the network part
8817 of a host address. You can also specify hostnames or .domain names (the
8818 initial dot causes the domain to match any name below it),
8819 "/file/name" or "type:table" patterns. A "/file/name" pattern is re‐
8820 placed by its contents; a "type:table" lookup table is matched when a
8821 table entry matches a lookup string (the lookup result is ignored).
8822 Continue long lines by starting the next line with whitespace. Specify
8823 "!pattern" to exclude an address or network block from the list. The
8824 form "!/file/name" is supported only in Postfix version 2.4 and later.
8825 Note: IP version 6 address information must be specified inside [] in
8827 the smtpd_authorized_xclient_hosts value, and in files specified with
8828 "/file/name". IP version 6 addresses contain the ":" character, and
8829 would otherwise be confused with a "type:table" pattern.
8830
8832 What remote SMTP clients are allowed to use the XFORWARD feature. This
8833 command forwards information that is used to improve logging after
8834 SMTP-based content filters. See the XFORWARD_README document for de‐
8835 tails.
8836 This feature is available in Postfix 2.1 and later.
8838 By default, no clients are allowed to specify XFORWARD.
8840 Specify a list of network/netmask patterns, separated by commas and/or
8842 whitespace. The mask specifies the number of bits in the network part
8843 of a host address. You can also specify hostnames or .domain names (the
8844 initial dot causes the domain to match any name below it),
8845 "/file/name" or "type:table" patterns. A "/file/name" pattern is re‐
8846 placed by its contents; a "type:table" lookup table is matched when a
8847 table entry matches a lookup string (the lookup result is ignored).
8848 Continue long lines by starting the next line with whitespace. Specify
8849 "!pattern" to exclude an address or network block from the list. The
8850 form "!/file/name" is supported only in Postfix version 2.4 and later.
8851 Note: IP version 6 address information must be specified inside [] in
8853 the smtpd_authorized_xforward_hosts value, and in files specified with
8854 "/file/name". IP version 6 addresses contain the ":" character, and
8855 would otherwise be confused with a "type:table" pattern.
8856
8858 The text that follows the 220 status code in the SMTP greeting banner.
8859 Some people like to see the mail version advertised. By default, Post‐
8860 fix shows no version.
8861 You MUST specify $myhostname at the start of the text. This is required
8863 by the SMTP protocol.
8864 Example:
8866 smtpd_banner = $myhostname ESMTP $mail_name ($mail_version)
8868
8870 The maximal number of AUTH commands that any client is allowed to send
8871 to this service per time unit, regardless of whether or not Postfix ac‐
8872 tually accepts those commands. The time unit is specified with the
8873 anvil_rate_time_unit configuration parameter.
8874 By default, there is no limit on the number AUTH commands that a client
8876 may send.
8877 To disable this feature, specify a limit of 0.
8879 WARNING: The purpose of this feature is to limit abuse. It must not be
8881 used to regulate legitimate mail traffic.
8882 This feature is available in Postfix 3.1 and later.
8884
8886 How many simultaneous connections any client is allowed to make to this
8887 service. By default, the limit is set to half the default process
8888 limit value.
8889 To disable this feature, specify a limit of 0.
8891 WARNING: The purpose of this feature is to limit abuse. It must not be
8893 used to regulate legitimate mail traffic.
8894 This feature is available in Postfix 2.2 and later.
8896
8898 The maximal number of connection attempts any client is allowed to make
8899 to this service per time unit. The time unit is specified with the
8900 anvil_rate_time_unit configuration parameter.
8901 By default, a client can make as many connections per time unit as
8903 Postfix can accept.
8904 To disable this feature, specify a limit of 0.
8906 WARNING: The purpose of this feature is to limit abuse. It must not be
8908 used to regulate legitimate mail traffic.
8909 This feature is available in Postfix 2.2 and later.
8911 Example:
8913 smtpd_client_connection_rate_limit = 1000
8915
8917 Clients that are excluded from smtpd_client_*_count/rate_limit restric‐
8918 tions. See the mynetworks parameter description for the parameter value
8919 syntax.
8920 By default, clients in trusted networks are excluded. Specify a list of
8922 network blocks, hostnames or .domain names (the initial dot causes the
8923 domain to match any name below it).
8924 Note: IP version 6 address information must be specified inside [] in
8926 the smtpd_client_event_limit_exceptions value, and in files specified
8927 with "/file/name". IP version 6 addresses contain the ":" character,
8928 and would otherwise be confused with a "type:table" pattern.
8929 Pattern matching of domain names is controlled by the presence or ab‐
8931 sence of "smtpd_client_event_limit_exceptions" in the parent_do‐
8932 main_matches_subdomains parameter value (postfix 3.0 and later).
8933 This feature is available in Postfix 2.2 and later.
8935
8937 The maximal number of message delivery requests that any client is al‐
8938 lowed to make to this service per time unit, regardless of whether or
8939 not Postfix actually accepts those messages. The time unit is speci‐
8940 fied with the anvil_rate_time_unit configuration parameter.
8941 By default, a client can send as many message delivery requests per
8943 time unit as Postfix can accept.
8944 To disable this feature, specify a limit of 0.
8946 WARNING: The purpose of this feature is to limit abuse. It must not be
8948 used to regulate legitimate mail traffic.
8949 This feature is available in Postfix 2.2 and later.
8951 Example:
8953 smtpd_client_message_rate_limit = 1000
8955
8957 The maximal number of new (i.e., uncached) TLS sessions that a remote
8958 SMTP client is allowed to negotiate with this service per time unit.
8959 The time unit is specified with the anvil_rate_time_unit configuration
8960 parameter.
8961 By default, a remote SMTP client can negotiate as many new TLS sessions
8963 per time unit as Postfix can accept.
8964 To disable this feature, specify a limit of 0. Otherwise, specify a
8966 limit that is at least the per-client concurrent session limit, or else
8967 legitimate client sessions may be rejected.
8968 WARNING: The purpose of this feature is to limit abuse. It must not be
8970 used to regulate legitimate mail traffic.
8971 This feature is available in Postfix 2.3 and later.
8973 Example:
8975 smtpd_client_new_tls_session_rate_limit = 100
8977
8979 Enable logging of the remote SMTP client port in addition to the host‐
8980 name and IP address. The logging format is "host[address]:port".
8981 This feature is available in Postfix 2.5 and later.
8983
8985 The maximal number of recipient addresses that any client is allowed to
8986 send to this service per time unit, regardless of whether or not Post‐
8987 fix actually accepts those recipients. The time unit is specified with
8988 the anvil_rate_time_unit configuration parameter.
8989 By default, a client can send as many recipient addresses per time unit
8991 as Postfix can accept.
8992 To disable this feature, specify a limit of 0.
8994 WARNING: The purpose of this feature is to limit abuse. It must not be
8996 used to regulate legitimate mail traffic.
8997 This feature is available in Postfix 2.2 and later.
8999 Example:
9001 smtpd_client_recipient_rate_limit = 1000
9003
9005 Optional restrictions that the Postfix SMTP server applies in the con‐
9006 text of a client connection request. See SMTPD_ACCESS_README, section
9007 "Delayed evaluation of SMTP access restriction lists" for a discussion
9008 of evaluation context and time.
9009 The default is to allow all connection requests.
9011 Specify a list of restrictions, separated by commas and/or whitespace.
9013 Continue long lines by starting the next line with whitespace. Re‐
9014 strictions are applied in the order as specified; the first restriction
9015 that matches wins.
9016 The following restrictions are specific to client hostname or client
9018 network address information.
9019 check_ccert_access type:table
9021 By default use the remote SMTP client certificate fingerprint or
9022 the public key fingerprint (Postfix 2.9 and later) as lookup key
9023 for the specified access(5) database; with Postfix version 2.2,
9024 also require that the remote SMTP client certificate is verified
9025 successfully. The fingerprint digest algorithm is configurable
9026 via the smtpd_tls_fingerprint_digest parameter (hard-coded as
9027 md5 prior to Postfix version 2.5). This feature requires
9028 "smtpd_tls_ask_ccert = yes" and is available with Postfix ver‐
9029 sion 2.2 and later.
9030 The default algorithm is sha256 with Postfix >= 3.6 and the com‐
9031 patibility_level set to 3.6 or higher. With Postfix <= 3.5, the
9032 default algorithm is md5. The best-practice algorithm is now
9033 sha256. Recent advances in hash function cryptanalysis have led
9034 to md5 and sha1 being deprecated in favor of sha256. However,
9035 as long as there are no known "second pre-image" attacks against
9036 the older algorithms, their use in this context, though not rec‐
9037 ommended, is still likely safe.
9038 Alternatively, check_ccert_access accepts an explicit search or‐
9039 der (Postfix 3.5 and later). The default search order as de‐
9040 scribed above corresponds with:
9041 check_ccert_access { type:table, { search_order = cert_finger‐
9042 print, pubkey_fingerprint } }
9043 The commas are optional.
9044 check_client_access type:table
9046 Search the specified access database for the client hostname,
9047 parent domains, client IP address, or networks obtained by
9048 stripping least significant octets. See the access(5) manual
9049 page for details.
9050 check_client_a_access type:table
9052 Search the specified access(5) database for the IP addresses for
9053 the client hostname, and execute the corresponding action.
9054 Note: a result of "OK" is not allowed for safety reasons. In‐
9055 stead, use DUNNO in order to exclude specific hosts from
9056 denylists. This feature is available in Postfix 3.0 and later.
9057 check_client_mx_access type:table
9059 Search the specified access(5) database for the MX hosts for the
9060 client hostname, and execute the corresponding action. If no MX
9061 record is found, look up A or AAAA records, just like the Post‐
9062 fix SMTP client would. Note: a result of "OK" is not allowed for
9063 safety reasons. Instead, use DUNNO in order to exclude specific
9064 hosts from denylists. This feature is available in Postfix 2.7
9065 and later.
9066 check_client_ns_access type:table
9068 Search the specified access(5) database for the DNS servers for
9069 the client hostname, and execute the corresponding action.
9070 Note: a result of "OK" is not allowed for safety reasons. In‐
9071 stead, use DUNNO in order to exclude specific hosts from
9072 denylists. This feature is available in Postfix 2.7 and later.
9073 check_reverse_client_hostname_access type:table
9075 Search the specified access database for the unverified reverse
9076 client hostname, parent domains, client IP address, or networks
9077 obtained by stripping least significant octets. See the ac‐
9078 cess(5) manual page for details. Note: a result of "OK" is not
9079 allowed for safety reasons. Instead, use DUNNO in order to ex‐
9080 clude specific hosts from denylists. This feature is available
9081 in Postfix 2.6 and later.
9082 check_reverse_client_hostname_a_access type:table
9084 Search the specified access(5) database for the IP addresses for
9085 the unverified reverse client hostname, and execute the corre‐
9086 sponding action. Note: a result of "OK" is not allowed for
9087 safety reasons. Instead, use DUNNO in order to exclude specific
9088 hosts from denylists. This feature is available in Postfix 3.0
9089 and later.
9090 check_reverse_client_hostname_mx_access type:table
9092 Search the specified access(5) database for the MX hosts for the
9093 unverified reverse client hostname, and execute the correspond‐
9094 ing action. If no MX record is found, look up A or AAAA
9095 records, just like the Postfix SMTP client would. Note: a re‐
9096 sult of "OK" is not allowed for safety reasons. Instead, use
9097 DUNNO in order to exclude specific hosts from denylists. This
9098 feature is available in Postfix 2.7 and later.
9099 check_reverse_client_hostname_ns_access type:table
9101 Search the specified access(5) database for the DNS servers for
9102 the unverified reverse client hostname, and execute the corre‐
9103 sponding action. Note: a result of "OK" is not allowed for
9104 safety reasons. Instead, use DUNNO in order to exclude specific
9105 hosts from denylists. This feature is available in Postfix 2.7
9106 and later.
9107 check_sasl_access type:table
9109 Use the remote SMTP client SASL user name as lookup key for the
9110 specified access(5) database. The lookup key has the form "user‐
9111 name@domainname" when the smtpd_sasl_local_domain parameter
9112 value is non-empty. Unlike the check_client_access feature,
9113 check_sasl_access does not perform matches of parent domains or
9114 IP subnet ranges. This feature is available with Postfix ver‐
9115 sion 2.11 and later.
9116 permit_inet_interfaces
9118 Permit the request when the client IP address matches $inet_in‐
9119 terfaces.
9120 permit_mynetworks
9122 Permit the request when the client IP address matches any net‐
9123 work or network address listed in $mynetworks.
9124 permit_sasl_authenticated
9126 Permit the request when the client is successfully authenticated
9127 via the RFC 4954 (AUTH) protocol.
9128 permit_tls_all_clientcerts
9130 Permit the request when the remote SMTP client certificate is
9131 verified successfully. This option must be used only if a spe‐
9132 cial CA issues the certificates and only this CA is listed as
9133 trusted CA. Otherwise, clients with a third-party certificate
9134 would also be allowed to relay. Specify "tls_append_default_CA
9135 = no" when the trusted CA is specified with smtpd_tls_CAfile or
9136 smtpd_tls_CApath, to prevent Postfix from appending the sys‐
9137 tem-supplied default CAs. This feature requires
9138 "smtpd_tls_ask_ccert = yes" and is available with Postfix ver‐
9139 sion 2.2 and later.
9140 permit_tls_clientcerts
9142 Permit the request when the remote SMTP client certificate fin‐
9143 gerprint or public key fingerprint (Postfix 2.9 and later) is
9144 listed in $relay_clientcerts. The fingerprint digest algorithm
9145 is configurable via the smtpd_tls_fingerprint_digest parameter
9146 (hard-coded as md5 prior to Postfix version 2.5). This feature
9147 requires "smtpd_tls_ask_ccert = yes" and is available with Post‐
9148 fix version 2.2 and later.
9149 The default algorithm is sha256 with Postfix >= 3.6 and the com‐
9150 patibility_level set to 3.6 or higher. With Postfix <= 3.5, the
9151 default algorithm is md5. The best-practice algorithm is now
9152 sha256. Recent advances in hash function cryptanalysis have led
9153 to md5 and sha1 being deprecated in favor of sha256. However,
9154 as long as there are no known "second pre-image" attacks against
9155 the older algorithms, their use in this context, though not rec‐
9156 ommended, is still likely safe.
9157 reject_rbl_client rbl_domain=d.d.d.d
9159 Reject the request when the reversed client network address is
9160 listed with the A record "d.d.d.d" under rbl_domain (Postfix
9161 version 2.1 and later only). Each "d" is a number, or a pattern
9162 inside "[]" that contains one or more ";"-separated numbers or
9163 number..number ranges (Postfix version 2.8 and later). If no
9164 "=d.d.d.d" is specified, reject the request when the reversed
9165 client network address is listed with any A record under rbl_do‐
9166 main.
9167 The maps_rbl_reject_code parameter specifies the response code
9168 for rejected requests (default: 554), the default_rbl_reply
9169 parameter specifies the default server reply, and the rbl_re‐
9170 ply_maps parameter specifies tables with server replies indexed
9171 by rbl_domain. This feature is available in Postfix 2.0 and
9172 later.
9173 permit_dnswl_client dnswl_domain=d.d.d.d
9175 Accept the request when the reversed client network address is
9176 listed with the A record "d.d.d.d" under dnswl_domain. Each "d"
9177 is a number, or a pattern inside "[]" that contains one or more
9178 ";"-separated numbers or number..number ranges. If no
9179 "=d.d.d.d" is specified, accept the request when the reversed
9180 client network address is listed with any A record under
9181 dnswl_domain.
9182 For safety, permit_dnswl_client is silently ignored when it
9183 would override reject_unauth_destination. The result is DE‐
9184 FER_IF_REJECT when allowlist lookup fails. This feature is
9185 available in Postfix 2.8 and later.
9186 reject_rhsbl_client rbl_domain=d.d.d.d
9188 Reject the request when the client hostname is listed with the A
9189 record "d.d.d.d" under rbl_domain (Postfix version 2.1 and later
9190 only). Each "d" is a number, or a pattern inside "[]" that con‐
9191 tains one or more ";"-separated numbers or number..number ranges
9192 (Postfix version 2.8 and later). If no "=d.d.d.d" is specified,
9193 reject the request when the client hostname is listed with any A
9194 record under rbl_domain. See the reject_rbl_client description
9195 above for additional RBL related configuration parameters. This
9196 feature is available in Postfix 2.0 and later; with Postfix ver‐
9197 sion 2.8 and later, reject_rhsbl_reverse_client will usually
9198 produce better results.
9199 permit_rhswl_client rhswl_domain=d.d.d.d
9201 Accept the request when the client hostname is listed with the A
9202 record "d.d.d.d" under rhswl_domain. Each "d" is a number, or a
9203 pattern inside "[]" that contains one or more ";"-separated num‐
9204 bers or number..number ranges. If no "=d.d.d.d" is specified,
9205 accept the request when the client hostname is listed with any A
9206 record under rhswl_domain.
9207 Caution: client name allowlisting is fragile, since the client
9208 name lookup can fail due to temporary outages. Client name al‐
9209 lowlisting should be used only to reduce false positives in e.g.
9210 DNS-based blocklists, and not for making access rule exceptions.
9211 For safety, permit_rhswl_client is silently ignored when it
9212 would override reject_unauth_destination. The result is DE‐
9213 FER_IF_REJECT when allowlist lookup fails. This feature is
9214 available in Postfix 2.8 and later.
9215 reject_rhsbl_reverse_client rbl_domain=d.d.d.d
9217 Reject the request when the unverified reverse client hostname
9218 is listed with the A record "d.d.d.d" under rbl_domain. Each
9219 "d" is a number, or a pattern inside "[]" that contains one or
9220 more ";"-separated numbers or number..number ranges. If no
9221 "=d.d.d.d" is specified, reject the request when the unverified
9222 reverse client hostname is listed with any A record under
9223 rbl_domain. See the reject_rbl_client description above for ad‐
9224 ditional RBL related configuration parameters. This feature is
9225 available in Postfix 2.8 and later.
9226 reject_unknown_client_hostname (with Postfix < 2.3: reject_un‐
9228 known_client)
9229 Reject the request when 1) the client IP address->name mapping
9230 fails, or 2) the name->address mapping fails, or 3) the
9231 name->address mapping does not match the client IP address.
9232 This is a stronger restriction than the reject_unknown_re‐
9233 verse_client_hostname feature, which triggers only under condi‐
9234 tion 1) above.
9235 The unknown_client_reject_code parameter specifies the response
9236 code for rejected requests (default: 450). The reply is always
9237 450 in case the address->name or name->address lookup failed due
9238 to a temporary problem.
9239 reject_unknown_reverse_client_hostname
9241 Reject the request when the client IP address has no ad‐
9242 dress->name mapping.
9243 This is a weaker restriction than the reject_un‐
9244 known_client_hostname feature, which requires not only that the
9245 address->name and name->address mappings exist, but also that
9246 the two mappings reproduce the client IP address.
9247 The unknown_client_reject_code parameter specifies the response
9248 code for rejected requests (default: 450). The reply is always
9249 450 in case the address->name lookup failed due to a temporary
9250 problem.
9251 This feature is available in Postfix 2.3 and later.
9252 In addition, you can use any of the following generic restrictions.
9254 These restrictions are applicable in any SMTP command context.
9255 check_policy_service servername
9257 Query the specified policy server. See the SMTPD_POLICY_README
9258 document for details. This feature is available in Postfix 2.1
9259 and later.
9260 defer Defer the request. The client is told to try again later. This
9262 restriction is useful at the end of a restriction list, to make
9263 the default policy explicit.
9264 The defer_code parameter specifies the SMTP server reply code
9265 (default: 450).
9266 defer_if_permit
9268 Defer the request if some later restriction would result in an
9269 explicit or implicit PERMIT action. This is useful when a
9270 denylisting feature fails due to a temporary problem. This fea‐
9271 ture is available in Postfix version 2.1 and later.
9272 defer_if_reject
9274 Defer the request if some later restriction would result in a
9275 REJECT action. This is useful when an allowlisting feature
9276 fails due to a temporary problem. This feature is available in
9277 Postfix version 2.1 and later.
9278 permit Permit the request. This restriction is useful at the end of a
9280 restriction list, to make the default policy explicit.
9281 reject_multi_recipient_bounce
9283 Reject the request when the envelope sender is the null address,
9284 and the message has multiple envelope recipients. This usage has
9285 rare but legitimate applications: under certain conditions,
9286 multi-recipient mail that was posted with the DSN option NO‐
9287 TIFY=NEVER may be forwarded with the null sender address.
9288 Note: this restriction can only work reliably when used in
9289 smtpd_data_restrictions or smtpd_end_of_data_restrictions, be‐
9290 cause the total number of recipients is not known at an earlier
9291 stage of the SMTP conversation. Use at the RCPT stage will only
9292 reject the second etc. recipient.
9293 The multi_recipient_bounce_reject_code parameter specifies the
9294 response code for rejected requests (default: 550). This fea‐
9295 ture is available in Postfix 2.1 and later.
9296 reject_plaintext_session
9298 Reject the request when the connection is not encrypted. This
9299 restriction should not be used before the client has had a
9300 chance to negotiate encryption with the AUTH or STARTTLS com‐
9301 mands.
9302 The plaintext_reject_code parameter specifies the response code
9303 for rejected requests (default: 450). This feature is avail‐
9304 able in Postfix 2.3 and later.
9305 reject_unauth_pipelining
9307 Reject the request when the client sends SMTP commands ahead of
9308 time where it is not allowed, or when the client sends SMTP com‐
9309 mands ahead of time without knowing that Postfix actually sup‐
9310 ports ESMTP command pipelining. This stops mail from bulk mail
9311 software that improperly uses ESMTP command pipelining in order
9312 to speed up deliveries.
9313 With Postfix 2.6 and later, the SMTP server sets a per-session
9314 flag whenever it detects illegal pipelining, including pipelined
9315 HELO or EHLO commands. The reject_unauth_pipelining feature sim‐
9316 ply tests whether the flag was set at any point in time during
9317 the session.
9318 With older Postfix versions, reject_unauth_pipelining checks the
9319 current status of the input read queue, and its usage is not
9320 recommended in contexts other than smtpd_data_restrictions.
9321 reject Reject the request. This restriction is useful at the end of a
9323 restriction list, to make the default policy explicit. The re‐
9324 ject_code configuration parameter specifies the response code
9325 for rejected requests (default: 554).
9326 sleep seconds
9328 Pause for the specified number of seconds and proceed with the
9329 next restriction in the list, if any. This may stop zombie mail
9330 when used as:
9331 /etc/postfix/main.cf:
9332 smtpd_client_restrictions =
9333 sleep 1, reject_unauth_pipelining
9334 smtpd_delay_reject = no
9335 This feature is available in Postfix 2.3.
9336 warn_if_reject
9338 A safety net for testing. When "warn_if_reject" is placed before
9339 a reject-type restriction, access table query, or check_pol‐
9340 icy_service query, this logs a "reject_warning" message instead
9341 of rejecting a request (when a reject-type restriction fails due
9342 to a temporary error, this logs a "reject_warning" message for
9343 any implicit "defer_if_permit" actions that would normally pre‐
9344 vent mail from being accepted by some later access restriction).
9345 This feature has no effect on defer_if_reject restrictions.
9346 Other restrictions that are valid in this context:
9348 • SMTP command specific restrictions that are described under the
9350 smtpd_helo_restrictions, smtpd_sender_restrictions or smtpd_re‐
9351 cipient_restrictions parameters. When helo, sender or recipient
9352 restrictions are listed under smtpd_client_restrictions, they
9353 have effect only with "smtpd_delay_reject = yes", so that
9354 $smtpd_client_restrictions is evaluated at the time of the RCPT
9355 TO command.
9356 Example:
9358 smtpd_client_restrictions = permit_mynetworks, reject_unknown_client_hostname
9360
9362 A mechanism to transform commands from remote SMTP clients. This is a
9363 last-resort tool to work around client commands that break interoper‐
9364 ability with the Postfix SMTP server. Other uses involve fault injec‐
9365 tion to test Postfix's handling of invalid commands.
9366 Specify the name of a "type:table" lookup table. The search string is
9368 the SMTP command as received from the remote SMTP client, except that
9369 initial whitespace and the trailing <CR><LF> are removed. The result
9370 value is executed by the Postfix SMTP server.
9371 There is no need to use smtpd_command_filter for the following cases:
9373 • Use "resolve_numeric_domain = yes" to accept "user@ipaddress".
9375 • Postfix already accepts the correct form "user@[ipaddress]". Use
9377 virtual_alias_maps or canonical_maps to translate these into do‐
9378 main names if necessary.
9379 • Use "strict_rfc821_envelopes = no" to accept "RCPT TO:<User Name
9381 <user@example.com>>". Postfix will ignore the "User Name" part
9382 and deliver to the <user@example.com> address.
9383 Examples of problems that can be solved with the smtpd_command_filter
9385 feature:
9386 /etc/postfix/main.cf:
9388 smtpd_command_filter = pcre:/etc/postfix/command_filter
9389 /etc/postfix/command_filter:
9391 # Work around clients that send malformed HELO commands.
9392 /^HELO\s*$/ HELO domain.invalid
9393 # Work around clients that send empty lines.
9395 /^\s*$/ NOOP
9396 # Work around clients that send RCPT TO:<'user@domain'>.
9398 # WARNING: do not lose the parameters that follow the address.
9399 /^(RCPT\s+TO:\s*<)'([^[:space:]]+)'(>.*)/ $1$2$3
9400 # Append XVERP to MAIL FROM commands to request VERP-style delivery.
9402 # See VERP_README for more information on how to use Postfix VERP.
9403 /^(MAIL FROM:\s*<listname@example\.com>.*)/ $1 XVERP
9404 # Bounce-never mail sink. Use notify_classes=bounce,resource,software
9406 # to send bounced mail to the postmaster (with message body removed).
9407 /^(RCPT\s+TO:\s*<.*>.*)\s+NOTIFY=\S+(.*)/ $1 NOTIFY=NEVER$2
9408 /^(RCPT\s+TO:.*)/ $1 NOTIFY=NEVER
9409 This feature is available in Postfix 2.7.
9411
9413 Optional access restrictions that the Postfix SMTP server applies in
9414 the context of the SMTP DATA command. See SMTPD_ACCESS_README, section
9415 "Delayed evaluation of SMTP access restriction lists" for a discussion
9416 of evaluation context and time.
9417 This feature is available in Postfix 2.0 and later.
9419 Specify a list of restrictions, separated by commas and/or whitespace.
9421 Continue long lines by starting the next line with whitespace. Re‐
9422 strictions are applied in the order as specified; the first restriction
9423 that matches wins.
9424 The following restrictions are valid in this context:
9426 • Generic restrictions that can be used in any SMTP command con‐
9428 text, described under smtpd_client_restrictions.
9429 • SMTP command specific restrictions described under
9431 smtpd_client_restrictions, smtpd_helo_restrictions,
9432 smtpd_sender_restrictions or smtpd_recipient_restrictions.
9433 • However, no recipient information is available in the case of
9435 multi-recipient mail. Acting on only one recipient would be mis‐
9436 leading, because any decision will affect all recipients
9437 equally. Acting on all recipients would require a possibly very
9438 large amount of memory, and would also be misleading for the
9439 reasons mentioned before.
9440 Examples:
9442 smtpd_data_restrictions = reject_unauth_pipelining
9444 smtpd_data_restrictions = reject_multi_recipient_bounce
9445
9447 Postpone the start of an SMTP mail transaction until a valid RCPT TO
9448 command is received. Specify "no" to create a mail transaction as soon
9449 as the Postfix SMTP server receives a valid MAIL FROM command.
9450 With sites that reject lots of mail, the default setting reduces the
9452 use of disk, CPU and memory resources. The downside is that rejected
9453 recipients are logged with NOQUEUE instead of a mail transaction ID.
9454 This complicates the logfile analysis of multi-recipient mail.
9455 This feature is available in Postfix 2.3 and later.
9457
9459 Wait until the RCPT TO command before evaluating $smtpd_client_restric‐
9460 tions, $smtpd_helo_restrictions and $smtpd_sender_restrictions, or wait
9461 until the ETRN command before evaluating $smtpd_client_restrictions and
9462 $smtpd_helo_restrictions.
9463 This feature is turned on by default because some clients apparently
9465 mis-behave when the Postfix SMTP server rejects commands before RCPT
9466 TO.
9467 The default setting has one major benefit: it allows Postfix to log re‐
9469 cipient address information when rejecting a client name/address or
9470 sender address, so that it is possible to find out whose mail is being
9471 rejected.
9472
9474 Lookup tables, indexed by the remote SMTP client address, with case in‐
9475 sensitive lists of EHLO keywords (pipelining, starttls, auth, etc.)
9476 that the Postfix SMTP server will not send in the EHLO response to a
9477 remote SMTP client. See smtpd_discard_ehlo_keywords for details. The
9478 tables are not searched by hostname for robustness reasons.
9479 Specify zero or more "type:name" lookup tables, separated by whitespace
9481 or comma. Tables will be searched in the specified order until a match
9482 is found.
9483 This feature is available in Postfix 2.2 and later.
9485
9487 A case insensitive list of EHLO keywords (pipelining, starttls, auth,
9488 etc.) that the Postfix SMTP server will not send in the EHLO response
9489 to a remote SMTP client.
9490 This feature is available in Postfix 2.2 and later.
9492 Notes:
9494 • Specify the silent-discard pseudo keyword to prevent this action
9496 from being logged.
9497 • Use the smtpd_discard_ehlo_keyword_address_maps feature to dis‐
9499 card EHLO keywords selectively.
9500
9502 Optional filter for Postfix SMTP server DNS lookup results. See
9503 smtp_dns_reply_filter for details including an example.
9504 This feature is available in Postfix 3.0 and later.
9506
9508 Optional access restrictions that the Postfix SMTP server applies in
9509 the context of the SMTP END-OF-DATA command. See SMTPD_ACCESS_README,
9510 section "Delayed evaluation of SMTP access restriction lists" for a
9511 discussion of evaluation context and time.
9512 This feature is available in Postfix 2.2 and later.
9514 See smtpd_data_restrictions for details and limitations.
9516
9518 Mandatory TLS: announce STARTTLS support to remote SMTP clients, and
9519 require that clients use TLS encryption. According to RFC 2487 this
9520 MUST NOT be applied in case of a publicly-referenced SMTP server. This
9521 option is therefore off by default.
9522 Note 1: "smtpd_enforce_tls = yes" implies "smtpd_tls_auth_only = yes".
9524 Note 2: when invoked via "sendmail -bs", Postfix will never offer
9526 STARTTLS due to insufficient privileges to access the server private
9527 key. This is intended behavior.
9528 This feature is available in Postfix 2.2 and later. With Postfix 2.3
9530 and later use smtpd_tls_security_level instead.
9531
9533 With Postfix version 2.1 and later: the SMTP server response delay af‐
9534 ter a client has made more than $smtpd_soft_error_limit errors, and
9535 fewer than $smtpd_hard_error_limit errors, without delivering mail.
9536 With Postfix version 2.0 and earlier: the SMTP server delay before
9538 sending a reject (4xx or 5xx) response, when the client has made fewer
9539 than $smtpd_soft_error_limit errors without delivering mail.
9540
9542 Optional restrictions that the Postfix SMTP server applies in the con‐
9543 text of a client ETRN command. See SMTPD_ACCESS_README, section "De‐
9544 layed evaluation of SMTP access restriction lists" for a discussion of
9545 evaluation context and time.
9546 The Postfix ETRN implementation accepts only destinations that are eli‐
9548 gible for the Postfix "fast flush" service. See the ETRN_README file
9549 for details.
9550 Specify a list of restrictions, separated by commas and/or whitespace.
9552 Continue long lines by starting the next line with whitespace. Re‐
9553 strictions are applied in the order as specified; the first restriction
9554 that matches wins.
9555 The following restrictions are specific to the domain name information
9557 received with the ETRN command.
9558 check_etrn_access type:table
9560 Search the specified access database for the ETRN domain name or
9561 its parent domains. See the access(5) manual page for details.
9562 Other restrictions that are valid in this context:
9564 • Generic restrictions that can be used in any SMTP command con‐
9566 text, described under smtpd_client_restrictions.
9567 • SMTP command specific restrictions described under
9569 smtpd_client_restrictions and smtpd_helo_restrictions.
9570 Example:
9572 smtpd_etrn_restrictions = permit_mynetworks, reject
9574
9576 What characters are allowed in $name expansions of RBL reply templates.
9577 Characters not in the allowed set are replaced by "_". Use C like es‐
9578 capes to specify special characters such as whitespace.
9579 The smtpd_expansion_filter value is not subject to Postfix configura‐
9581 tion parameter $name expansion.
9582 This feature is available in Postfix 2.0 and later.
9584
9586 List of commands that cause the Postfix SMTP server to immediately ter‐
9587 minate the session with a 221 code. This can be used to disconnect
9588 clients that obviously attempt to abuse the system. In addition to the
9589 commands listed in this parameter, commands that follow the "Label:"
9590 format of message headers will also cause a disconnect.
9591 This feature is available in Postfix 2.2 and later.
9593
9595 The maximal number of errors a remote SMTP client is allowed to make
9596 without delivering mail. The Postfix SMTP server disconnects when the
9597 limit is exceeded. Normally the default limit is 20, but it changes un‐
9598 der overload to just 1. With Postfix 2.5 and earlier, the SMTP server
9599 always allows up to 20 errors by default.
9600
9602 Require that a remote SMTP client introduces itself with the HELO or
9603 EHLO command before sending the MAIL command or other commands that re‐
9604 quire EHLO negotiation.
9605 Example:
9607 smtpd_helo_required = yes
9609
9611 Optional restrictions that the Postfix SMTP server applies in the con‐
9612 text of a client HELO command. See SMTPD_ACCESS_README, section "De‐
9613 layed evaluation of SMTP access restriction lists" for a discussion of
9614 evaluation context and time.
9615 The default is to permit everything.
9617 Note: specify "smtpd_helo_required = yes" to fully enforce this re‐
9619 striction (without "smtpd_helo_required = yes", a client can simply
9620 skip smtpd_helo_restrictions by not sending HELO or EHLO).
9621 Specify a list of restrictions, separated by commas and/or whitespace.
9623 Continue long lines by starting the next line with whitespace. Re‐
9624 strictions are applied in the order as specified; the first restriction
9625 that matches wins.
9626 The following restrictions are specific to the hostname information re‐
9628 ceived with the HELO or EHLO command.
9629 check_helo_access type:table
9631 Search the specified access(5) database for the HELO or EHLO
9632 hostname or parent domains, and execute the corresponding ac‐
9633 tion. Note: specify "smtpd_helo_required = yes" to fully en‐
9634 force this restriction (without "smtpd_helo_required = yes", a
9635 client can simply skip check_helo_access by not sending HELO or
9636 EHLO).
9637 check_helo_a_access type:table
9639 Search the specified access(5) database for the IP addresses for
9640 the HELO or EHLO hostname, and execute the corresponding action.
9641 Note 1: a result of "OK" is not allowed for safety reasons. In‐
9642 stead, use DUNNO in order to exclude specific hosts from
9643 denylists. Note 2: specify "smtpd_helo_required = yes" to fully
9644 enforce this restriction (without "smtpd_helo_required = yes", a
9645 client can simply skip check_helo_a_access by not sending HELO
9646 or EHLO). This feature is available in Postfix 3.0 and later.
9647 check_helo_mx_access type:table
9649 Search the specified access(5) database for the MX hosts for the
9650 HELO or EHLO hostname, and execute the corresponding action. If
9651 no MX record is found, look up A or AAAA records, just like the
9652 Postfix SMTP client would. Note 1: a result of "OK" is not al‐
9653 lowed for safety reasons. Instead, use DUNNO in order to exclude
9654 specific hosts from denylists. Note 2: specify "smtpd_helo_re‐
9655 quired = yes" to fully enforce this restriction (without
9656 "smtpd_helo_required = yes", a client can simply skip
9657 check_helo_mx_access by not sending HELO or EHLO). This feature
9658 is available in Postfix 2.1 and later.
9659 check_helo_ns_access type:table
9661 Search the specified access(5) database for the DNS servers for
9662 the HELO or EHLO hostname, and execute the corresponding action.
9663 Note 1: a result of "OK" is not allowed for safety reasons. In‐
9664 stead, use DUNNO in order to exclude specific hosts from
9665 denylists. Note 2: specify "smtpd_helo_required = yes" to fully
9666 enforce this restriction (without "smtpd_helo_required = yes", a
9667 client can simply skip check_helo_ns_access by not sending HELO
9668 or EHLO). This feature is available in Postfix 2.1 and later.
9669 reject_invalid_helo_hostname (with Postfix < 2.3: reject_invalid_host‐
9671 name)
9672 Reject the request when the HELO or EHLO hostname is malformed.
9673 Note: specify "smtpd_helo_required = yes" to fully enforce this
9674 restriction (without "smtpd_helo_required = yes", a client can
9675 simply skip reject_invalid_helo_hostname by not sending HELO or
9676 EHLO).
9677 The invalid_hostname_reject_code specifies the response code for
9678 rejected requests (default: 501).
9679 reject_non_fqdn_helo_hostname (with Postfix < 2.3: re‐
9681 ject_non_fqdn_hostname)
9682 Reject the request when the HELO or EHLO hostname is not in
9683 fully-qualified domain or address literal form, as required by
9684 the RFC. Note: specify "smtpd_helo_required = yes" to fully en‐
9685 force this restriction (without "smtpd_helo_required = yes", a
9686 client can simply skip reject_non_fqdn_helo_hostname by not
9687 sending HELO or EHLO).
9688 The non_fqdn_reject_code parameter specifies the response code
9689 for rejected requests (default: 504).
9690 reject_rhsbl_helo rbl_domain=d.d.d.d
9692 Reject the request when the HELO or EHLO hostname is listed with
9693 the A record "d.d.d.d" under rbl_domain (Postfix version 2.1 and
9694 later only). Each "d" is a number, or a pattern inside "[]"
9695 that contains one or more ";"-separated numbers or number..num‐
9696 ber ranges (Postfix version 2.8 and later). If no "=d.d.d.d" is
9697 specified, reject the request when the HELO or EHLO hostname is
9698 listed with any A record under rbl_domain. See the re‐
9699 ject_rbl_client description for additional RBL related configu‐
9700 ration parameters. Note: specify "smtpd_helo_required = yes" to
9701 fully enforce this restriction (without "smtpd_helo_required =
9702 yes", a client can simply skip reject_rhsbl_helo by not sending
9703 HELO or EHLO). This feature is available in Postfix 2.0 and
9704 later.
9705 reject_unknown_helo_hostname (with Postfix < 2.3: reject_unknown_host‐
9707 name)
9708 Reject the request when the HELO or EHLO hostname has no DNS A
9709 or MX record.
9710 The reply is specified with the unknown_hostname_reject_code pa‐
9711 rameter (default: 450) or unknown_helo_hostname_tempfail_action
9712 (default: defer_if_permit). See the respective parameter de‐
9713 scriptions for details.
9714 Note: specify "smtpd_helo_required = yes" to fully enforce this
9715 restriction (without "smtpd_helo_required = yes", a client can
9716 simply skip reject_unknown_helo_hostname by not sending HELO or
9717 EHLO).
9718 Other restrictions that are valid in this context:
9720 • Generic restrictions that can be used in any SMTP command con‐
9722 text, described under smtpd_client_restrictions.
9723 • Client hostname or network address specific restrictions de‐
9725 scribed under smtpd_client_restrictions.
9726 • SMTP command specific restrictions described under
9728 smtpd_sender_restrictions or smtpd_recipient_restrictions. When
9729 sender or recipient restrictions are listed under smtpd_helo_re‐
9730 strictions, they have effect only with "smtpd_delay_reject =
9731 yes", so that $smtpd_helo_restrictions is evaluated at the time
9732 of the RCPT TO command.
9733 Examples:
9735 smtpd_helo_restrictions = permit_mynetworks, reject_invalid_helo_hostname
9737 smtpd_helo_restrictions = permit_mynetworks, reject_unknown_helo_hostname
9738
9740 The maximal number of lines in the Postfix SMTP server command history
9741 before it is flushed upon receipt of EHLO, RSET, or end of DATA.
9742
9744 The number of junk commands (NOOP, VRFY, ETRN or RSET) that a remote
9745 SMTP client can send before the Postfix SMTP server starts to increment
9746 the error counter with each junk command. The junk command count is
9747 reset after mail is delivered. See also the smtpd_error_sleep_time and
9748 smtpd_soft_error_limit configuration parameters. Normally the default
9749 limit is 100, but it changes under overload to just 1. With Postfix 2.5
9750 and earlier, the SMTP server always allows up to 100 junk commands by
9751 default.
9752
9754 Enable logging of the named "permit" actions in SMTP server access
9755 lists (by default, the SMTP server logs "reject" actions but not "per‐
9756 mit" actions). This feature does not affect conditional actions such
9757 as "defer_if_permit".
9758 Specify a list of "permit" action names, "/file/name" or "type:table"
9760 patterns, separated by commas and/or whitespace. The list is matched
9761 left to right, and the search stops on the first match. A "/file/name"
9762 pattern is replaced by its contents; a "type:table" lookup table is
9763 matched when a name matches a lookup key (the lookup result is ig‐
9764 nored). Continue long lines by starting the next line with whitespace.
9765 Specify "!pattern" to exclude a name from the list.
9766 Examples:
9768 /etc/postfix/main.cf:
9770 # Log all "permit" actions.
9771 smtpd_log_access_permit_actions = static:all
9772 /etc/postfix/main.cf:
9774 # Log "permit_dnswl_client" only.
9775 smtpd_log_access_permit_actions = permit_dnswl_client
9776 This feature is available in Postfix 2.10 and later.
9778
9780 Lookup tables with Milter settings per remote SMTP client IP address.
9781 The lookup result overrides the smtpd_milters setting, and has the same
9782 syntax.
9783 Note: lookup tables cannot return empty responses. Specify a lookup re‐
9785 sult of DISABLE (case does not matter) to indicate that Milter support
9786 should be disabled.
9787 Example to disable Milters for local clients:
9789 /etc/postfix/main.cf:
9791 smtpd_milter_maps = cidr:/etc/postfix/smtpd_milter_map
9792 smtpd_milters = inet:host:port, { inet:host:port, ... }, ...
9793 /etc/postfix/smtpd_milter_map:
9795 # Disable Milters for local clients.
9796 127.0.0.0/8 DISABLE
9797 192.168.0.0/16 DISABLE
9798 ::/64 DISABLE
9799 2001:db8::/32 DISABLE
9800 This feature is available in Postfix 3.2 and later.
9802
9804 A list of Milter (mail filter) applications for new mail that arrives
9805 via the Postfix smtpd(8) server. Specify space or comma as separator.
9806 See the MILTER_README document for details.
9807 This feature is available in Postfix 2.3 and later.
9809
9811 List of commands that the Postfix SMTP server replies to with "250 Ok",
9812 without doing any syntax checks and without changing state. This list
9813 overrides any commands built into the Postfix SMTP server.
9814
9816 The lookup key to be used in SMTP access(5) tables instead of the null
9817 sender address.
9818
9820 Attempt to look up the remote SMTP client hostname, and verify that the
9821 name matches the client IP address. A client name is set to "unknown"
9822 when it cannot be looked up or verified, or when name lookup is dis‐
9823 abled. Turning off name lookup reduces delays due to DNS lookup and
9824 increases the maximal inbound delivery rate.
9825 This feature is available in Postfix 2.3 and later.
9827
9829 Change the behavior of the smtpd_timeout and smtpd_starttls_timeout
9830 time limits, from a time limit per read or write system call, to a time
9831 limit to send or receive a complete record (an SMTP command line, SMTP
9832 response line, SMTP message content line, or TLS protocol message).
9833 This limits the impact from hostile peers that trickle data one byte at
9834 a time.
9835 Note: when per-record deadlines are enabled, a short timeout may cause
9837 problems with TLS over very slow network connections. The reasons are
9838 that a TLS protocol message can be up to 16 kbytes long (with TLSv1),
9839 and that an entire TLS protocol message must be sent or received within
9840 the per-record deadline.
9841 This feature is available in Postfix 2.9 and later. With older Postfix
9843 releases, the behavior is as if this parameter is set to "no".
9844
9846 problem)
9847 The default action when an SMTPD policy service request fails. Specify
9848 "DUNNO" to behave as if the failed SMTPD policy service request was
9849 not sent, and to continue processing other access restrictions, if any.
9850 Limitations:
9852 • This parameter may specify any value that would be a valid SMTPD
9854 policy server response (or access(5) map lookup result). An ac‐
9855 cess(5) map or policy server in this parameter value may need to
9856 be declared in advance with a restriction_class setting.
9857 • If the specified action invokes another check_policy_service re‐
9859 quest, that request will have the built-in default action.
9860 This feature is available in Postfix 3.0 and later.
9862
9864 The time after which an idle SMTPD policy service connection is closed.
9865 This feature is available in Postfix 2.1 and later.
9867
9869 The time after which an active SMTPD policy service connection is
9870 closed.
9871 This feature is available in Postfix 2.1 and later.
9873
9875 Optional information that the Postfix SMTP server specifies in the
9876 "policy_context" attribute of a policy service request (originally, to
9877 share the same service endpoint among multiple check_policy_service
9878 clients).
9879 This feature is available in Postfix 3.1 and later.
9881
9883 The maximal number of requests per SMTPD policy service connection, or
9884 zero (no limit). Once a connection reaches this limit, the connection
9885 is closed and the next request will be sent over a new connection. This
9886 is a workaround to avoid error-recovery delays with policy servers that
9887 cannot maintain a persistent connection.
9888 This feature is available in Postfix 3.0 and later.
9890
9892 The delay between attempts to resend a failed SMTPD policy service re‐
9893 quest. Specify a value greater than zero.
9894 This feature is available in Postfix 3.0 and later.
9896
9898 The time limit for connecting to, writing to, or receiving from a dele‐
9899 gated SMTPD policy server.
9900 This feature is available in Postfix 2.1 and later.
9902
9904 The maximal number of attempts to send an SMTPD policy service request
9905 before giving up. Specify a value greater than zero.
9906 This feature is available in Postfix 3.0 and later.
9908
9910 How the Postfix SMTP server announces itself to the proxy filter. By
9911 default, the Postfix hostname is used.
9912 This feature is available in Postfix 2.1 and later.
9914
9916 The hostname and TCP port of the mail filtering proxy server. The
9917 proxy receives all mail from the Postfix SMTP server, and is supposed
9918 to give the result to another Postfix SMTP server process.
9919 Specify "host:port" or "inet:host:port" for a TCP endpoint, or
9921 "unix:pathname" for a UNIX-domain endpoint. The host can be specified
9922 as an IP address or as a symbolic name; no MX lookups are done. When
9923 no "host" or "host:" are specified, the local machine is assumed.
9924 Pathname interpretation is relative to the Postfix queue directory.
9925 This feature is available in Postfix 2.1 and later.
9927 The "inet:" and "unix:" prefixes are available in Postfix 2.3 and
9929 later.
9930
9932 List of options that control how the Postfix SMTP server communicates
9933 with a before-queue content filter. Specify zero or more of the follow‐
9934 ing, separated by comma or whitespace.
9935 speed_adjust
9937 Do not connect to a before-queue content filter until an entire
9938 message has been received. This reduces the number of simultane‐
9939 ous before-queue content filter processes.
9940 NOTE 1: A filter must not selectively reject recipients of a multi-re‐
9942 cipient message. Rejecting all recipients is OK, as is accepting all
9943 recipients.
9944 NOTE 2: This feature increases the minimum amount of free queue space
9946 by $message_size_limit. The extra space is needed to save the message
9947 to a temporary file.
9948 This feature is available in Postfix 2.7 and later.
9950
9952 The time limit for connecting to a proxy filter and for sending or re‐
9953 ceiving information. When a connection fails the client gets a generic
9954 error message while more detailed information is logged to the maillog
9955 file.
9956 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
9958 The default time unit is s (seconds).
9959 This feature is available in Postfix 2.1 and later.
9961
9963 The maximal number of recipients that the Postfix SMTP server accepts
9964 per message delivery request.
9965
9967 The number of recipients that a remote SMTP client can send in excess
9968 of the limit specified with $smtpd_recipient_limit, before the Postfix
9969 SMTP server increments the per-session error count for each excess re‐
9970 cipient.
9971
9973 Optional restrictions that the Postfix SMTP server applies in the con‐
9974 text of a client RCPT TO command, after smtpd_relay_restrictions. See
9975 SMTPD_ACCESS_README, section "Delayed evaluation of SMTP access re‐
9976 striction lists" for a discussion of evaluation context and time.
9977 With Postfix versions before 2.10, the rules for relay permission and
9979 spam blocking were combined under smtpd_recipient_restrictions, result‐
9980 ing in error-prone configuration. As of Postfix 2.10, relay permission
9981 rules are preferably implemented with smtpd_relay_restrictions, so that
9982 a permissive spam blocking policy under smtpd_recipient_restrictions
9983 will no longer result in a permissive mail relay policy.
9984 For backwards compatibility, sites that migrate from Postfix versions
9986 before 2.10 can set smtpd_relay_restrictions to the empty value, and
9987 use smtpd_recipient_restrictions exactly as before.
9988 IMPORTANT: Either the smtpd_relay_restrictions or the smtpd_recipi‐
9990 ent_restrictions parameter must specify at least one of the following
9991 restrictions. Otherwise Postfix will refuse to receive mail:
9992 reject, reject_unauth_destination
9994 defer, defer_if_permit, defer_unauth_destination
9996 Specify a list of restrictions, separated by commas and/or whitespace.
9998 Continue long lines by starting the next line with whitespace. Re‐
9999 strictions are applied in the order as specified; the first restriction
10000 that matches wins.
10001 The following restrictions are specific to the recipient address that
10003 is received with the RCPT TO command.
10004 check_recipient_access type:table
10006 Search the specified access(5) database for the resolved RCPT TO
10007 address, domain, parent domains, or localpart@, and execute the
10008 corresponding action.
10009 check_recipient_a_access type:table
10011 Search the specified access(5) database for the IP addresses for
10012 the RCPT TO domain, and execute the corresponding action. Note:
10013 a result of "OK" is not allowed for safety reasons. Instead, use
10014 DUNNO in order to exclude specific hosts from denylists. This
10015 feature is available in Postfix 3.0 and later.
10016 check_recipient_mx_access type:table
10018 Search the specified access(5) database for the MX hosts for the
10019 RCPT TO domain, and execute the corresponding action. If no MX
10020 record is found, look up A or AAAA records, just like the Post‐
10021 fix SMTP client would. Note: a result of "OK" is not allowed for
10022 safety reasons. Instead, use DUNNO in order to exclude specific
10023 hosts from denylists. This feature is available in Postfix 2.1
10024 and later.
10025 check_recipient_ns_access type:table
10027 Search the specified access(5) database for the DNS servers for
10028 the RCPT TO domain, and execute the corresponding action. Note:
10029 a result of "OK" is not allowed for safety reasons. Instead, use
10030 DUNNO in order to exclude specific hosts from denylists. This
10031 feature is available in Postfix 2.1 and later.
10032 permit_auth_destination
10034 Permit the request when one of the following is true:
10035 • Postfix is mail forwarder: the resolved RCPT TO domain matches
10037 $relay_domains or a subdomain thereof, and the address contains
10038 no sender-specified routing (user@elsewhere@domain),
10039 • Postfix is the final destination: the resolved RCPT TO domain
10041 matches $mydestination, $inet_interfaces, $proxy_interfaces,
10042 $virtual_alias_domains, or $virtual_mailbox_domains, and the ad‐
10043 dress contains no sender-specified routing (user@elsewhere@do‐
10044 main).
10045 permit_mx_backup
10047 Permit the request when the local mail system is backup MX for
10048 the RCPT TO domain, or when the domain is an authorized destina‐
10049 tion (see permit_auth_destination for definition).
10050 • Safety: permit_mx_backup does not accept addresses that have
10052 sender-specified routing information (example: user@else‐
10053 where@domain).
10054 • Safety: permit_mx_backup can be vulnerable to mis-use when ac‐
10056 cess is not restricted with permit_mx_backup_networks.
10057 • Safety: as of Postfix version 2.3, permit_mx_backup no longer
10059 accepts the address when the local mail system is primary MX for
10060 the recipient domain. Exception: permit_mx_backup accepts the
10061 address when it specifies an authorized destination (see per‐
10062 mit_auth_destination for definition).
10063 • Limitation: mail may be rejected in case of a temporary DNS
10065 lookup problem with Postfix prior to version 2.0.
10066 reject_non_fqdn_recipient
10068 Reject the request when the RCPT TO address specifies a domain
10069 that is not in fully-qualified domain form, as required by the
10070 RFC.
10071 The non_fqdn_reject_code parameter specifies the response code
10072 for rejected requests (default: 504).
10073 reject_rhsbl_recipient rbl_domain=d.d.d.d
10075 Reject the request when the RCPT TO domain is listed with the A
10076 record "d.d.d.d" under rbl_domain (Postfix version 2.1 and later
10077 only). Each "d" is a number, or a pattern inside "[]" that con‐
10078 tains one or more ";"-separated numbers or number..number ranges
10079 (Postfix version 2.8 and later). If no "=d.d.d.d" is specified,
10080 reject the request when the RCPT TO domain is listed with any A
10081 record under rbl_domain.
10082 The maps_rbl_reject_code parameter specifies the response code
10083 for rejected requests (default: 554); the default_rbl_reply pa‐
10084 rameter specifies the default server reply; and the rbl_re‐
10085 ply_maps parameter specifies tables with server replies indexed
10086 by rbl_domain. This feature is available in Postfix version 2.0
10087 and later.
10088 reject_unauth_destination
10090 Reject the request unless one of the following is true:
10091 • Postfix is mail forwarder: the resolved RCPT TO domain matches
10093 $relay_domains or a subdomain thereof, and contains no
10094 sender-specified routing (user@elsewhere@domain),
10095 • Postfix is the final destination: the resolved RCPT TO domain
10097 matches $mydestination, $inet_interfaces, $proxy_interfaces,
10098 $virtual_alias_domains, or $virtual_mailbox_domains, and con‐
10099 tains no sender-specified routing (user@elsewhere@domain).
10100 The relay_domains_reject_code parameter specifies the response
10101 code for rejected requests (default: 554).
10102 defer_unauth_destination
10104 Reject the same requests as reject_unauth_destination, with a
10105 non-permanent error code. This feature is available in Postfix
10106 2.10 and later.
10107 reject_unknown_recipient_domain
10109 Reject the request when Postfix is not final destination for the
10110 recipient domain, and the RCPT TO domain has 1) no DNS MX and no
10111 DNS A record or 2) a malformed MX record such as a record with a
10112 zero-length MX hostname (Postfix version 2.3 and later).
10113 The reply is specified with the unknown_address_reject_code pa‐
10114 rameter (default: 450), unknown_address_tempfail_action (de‐
10115 fault: defer_if_permit), or 556 (nullmx, Postfix 3.0 and later).
10116 See the respective parameter descriptions for details.
10117 reject_unlisted_recipient (with Postfix version 2.0: check_recipi‐
10119 ent_maps)
10120 Reject the request when the RCPT TO address is not listed in the
10121 list of valid recipients for its domain class. See the smtpd_re‐
10122 ject_unlisted_recipient parameter description for details. This
10123 feature is available in Postfix 2.1 and later.
10124 reject_unverified_recipient
10126 Reject the request when mail to the RCPT TO address is known to
10127 bounce, or when the recipient address destination is not reach‐
10128 able. Address verification information is managed by the ver‐
10129 ify(8) server; see the ADDRESS_VERIFICATION_README file for de‐
10130 tails.
10131 The unverified_recipient_reject_code parameter specifies the nu‐
10132 merical response code when an address is known to bounce (de‐
10133 fault: 450, change into 550 when you are confident that it is
10134 safe to do so).
10135 The unverified_recipient_defer_code parameter specifies the nu‐
10136 merical response code when an address probe failed due to a tem‐
10137 porary problem (default: 450).
10138 The unverified_recipient_tempfail_action parameter specifies the
10139 action after address probe failure due to a temporary problem
10140 (default: defer_if_permit).
10141 This feature breaks for aliased addresses with "enable_origi‐
10142 nal_recipient = no" (Postfix <= 3.2).
10143 This feature is available in Postfix 2.1 and later.
10144 Other restrictions that are valid in this context:
10146 • Generic restrictions that can be used in any SMTP command con‐
10148 text, described under smtpd_client_restrictions.
10149 • SMTP command specific restrictions described under
10151 smtpd_client_restrictions, smtpd_helo_restrictions and
10152 smtpd_sender_restrictions.
10153 Example:
10155 # The Postfix before 2.10 default mail relay policy. Later Postfix
10157 # versions implement this preferably with smtpd_relay_restrictions.
10158 smtpd_recipient_restrictions = permit_mynetworks, reject_unauth_destination
10159
10161 Optional information that is appended after each Postfix SMTP server
10162 4XX or 5XX response.
10163 The following example uses "\c" at the start of the template (supported
10165 in Postfix 2.10 and later) to suppress the line break between the reply
10166 text and the footer text. With earlier Postfix versions, the footer
10167 text always begins on a new line, and the "\c" is output literally.
10168 /etc/postfix/main.cf:
10170 smtpd_reject_footer = \c. For assistance, call 800-555-0101.
10171 Please provide the following information in your problem report:
10172 time ($localtime), client ($client_address) and server
10173 ($server_name).
10174 Server response:
10176 550-5.5.1 <user@example> Recipient address rejected: User
10178 unknown. For assistance, call 800-555-0101. Please provide the
10179 following information in your problem report: time (Jan 4 15:42:00),
10180 client (192.168.1.248) and server (mail1.example.com).
10181 Note: the above text is meant to make it easier to find the Postfix
10183 logfile records for a failed SMTP session. The text itself is not
10184 logged to the Postfix SMTP server's maillog file.
10185 Be sure to keep the text as short as possible. Long text may be trun‐
10187 cated before it is logged to the remote SMTP client's maillog file, or
10188 before it is returned to the sender in a delivery status notification.
10189 The template text is not subject to Postfix configuration parameter
10191 $name expansion. Instead, this feature supports a limited number of
10192 $name attributes in the footer text. These attributes are replaced with
10193 their current value for the SMTP session.
10194 Note: specify $$name in footer text that is looked up from regexp: or
10196 pcre:-based smtpd_reject_footer_maps, otherwise the Postfix server will
10197 not use the footer text and will log a warning instead.
10198 client_address
10200 The Client IP address that is logged in the maillog file.
10201 client_port
10203 The client TCP port that is logged in the maillog file.
10204 localtime
10206 The server local time (Mmm dd hh:mm:ss) that is logged in the
10207 maillog file.
10208 server_name
10210 The server's myhostname value. This attribute is made available
10211 for sites with multiple MTAs (perhaps behind a load-balancer),
10212 where the server name can help the server support team to
10213 quickly find the right log files.
10214 Notes:
10216 • NOT SUPPORTED are other attributes such as sender, recipient, or
10218 main.cf parameters.
10219 • For safety reasons, text that does not match $smtpd_expan‐
10221 sion_filter is censored.
10222 This feature supports the two-character sequence \n as a request for a
10224 line break in the footer text. Postfix automatically inserts after each
10225 line break the three-digit SMTP reply code (and optional enhanced sta‐
10226 tus code) from the original Postfix reject message.
10227 To work around mail software that mis-handles multi-line replies, spec‐
10229 ify the two-character sequence \c at the start of the template. This
10230 suppresses the line break between the reply text and the footer text
10231 (Postfix 2.10 and later).
10232 This feature is available in Postfix 2.8 and later.
10234
10236 Lookup tables, indexed by the complete Postfix SMTP server 4xx or 5xx
10237 response, with reject footer templates. See smtpd_reject_footer for de‐
10238 tails.
10239 Specify zero or more "type:name" lookup tables, separated by whitespace
10241 or comma. Tables will be searched in the specified order until a match
10242 is found.
10243 This feature is available in Postfix 3.4 and later.
10245
10247 Request that the Postfix SMTP server rejects mail for unknown recipient
10248 addresses, even when no explicit reject_unlisted_recipient access re‐
10249 striction is specified. This prevents the Postfix queue from filling up
10250 with undeliverable MAILER-DAEMON messages.
10251 An address is always considered "known" when it matches a virtual(5)
10253 alias or a canonical(5) mapping.
10254 • The recipient domain matches $mydestination, $inet_interfaces or
10256 $proxy_interfaces, but the recipient is not listed in $local_re‐
10257 cipient_maps, and $local_recipient_maps is not null.
10258 • The recipient domain matches $virtual_alias_domains but the re‐
10260 cipient is not listed in $virtual_alias_maps.
10261 • The recipient domain matches $virtual_mailbox_domains but the
10263 recipient is not listed in $virtual_mailbox_maps, and $vir‐
10264 tual_mailbox_maps is not null.
10265 • The recipient domain matches $relay_domains but the recipient is
10267 not listed in $relay_recipient_maps, and $relay_recipient_maps
10268 is not null.
10269 This feature is available in Postfix 2.1 and later.
10271
10273 Request that the Postfix SMTP server rejects mail from unknown sender
10274 addresses, even when no explicit reject_unlisted_sender access restric‐
10275 tion is specified. This can slow down an explosion of forged mail from
10276 worms or viruses.
10277 An address is always considered "known" when it matches a virtual(5)
10279 alias or a canonical(5) mapping.
10280 • The sender domain matches $mydestination, $inet_interfaces or
10282 $proxy_interfaces, but the sender is not listed in $local_recip‐
10283 ient_maps, and $local_recipient_maps is not null.
10284 • The sender domain matches $virtual_alias_domains but the sender
10286 is not listed in $virtual_alias_maps.
10287 • The sender domain matches $virtual_mailbox_domains but the
10289 sender is not listed in $virtual_mailbox_maps, and $vir‐
10290 tual_mailbox_maps is not null.
10291 • The sender domain matches $relay_domains but the sender is not
10293 listed in $relay_recipient_maps, and $relay_recipient_maps is
10294 not null.
10295 This feature is available in Postfix 2.1 and later.
10297
10299 Evaluate smtpd_relay_restrictions before smtpd_recipient_restrictions.
10300 Historically, smtpd_relay_restrictions was evaluated after smtpd_recip‐
10301 ient_restrictions, contradicting documented behavior.
10302 Background: the smtpd_relay_restrictions feature is primarily designed
10304 to enforce a mail relaying policy, while smtpd_recipient_restrictions
10305 is primarily designed to enforce spam blocking policy. Both are evalu‐
10306 ated while replying to the RCPT TO command, and both support the same
10307 features.
10308 This feature is available in Postfix 3.6 and later.
10310
10312 cated, defer_unauth_destination)
10313 Access restrictions for mail relay control that the Postfix SMTP server
10314 applies in the context of the RCPT TO command, before smtpd_recipi‐
10315 ent_restrictions. See SMTPD_ACCESS_README, section "Delayed evaluation
10316 of SMTP access restriction lists" for a discussion of evaluation con‐
10317 text and time.
10318 With Postfix versions before 2.10, the rules for relay permission and
10320 spam blocking were combined under smtpd_recipient_restrictions, result‐
10321 ing in error-prone configuration. As of Postfix 2.10, relay permission
10322 rules are preferably implemented with smtpd_relay_restrictions, so that
10323 a permissive spam blocking policy under smtpd_recipient_restrictions
10324 will no longer result in a permissive mail relay policy.
10325 For backwards compatibility, sites that migrate from Postfix versions
10327 before 2.10 can set smtpd_relay_restrictions to the empty value, and
10328 use smtpd_recipient_restrictions exactly as before.
10329 By default, the Postfix SMTP server accepts:
10331 • Mail from clients whose IP address matches $mynetworks, or:
10333 • Mail to remote destinations that match $relay_domains, except
10335 for addresses that contain sender-specified routing (user@else‐
10336 where@domain), or:
10337 • Mail to local destinations that match $inet_interfaces or
10339 $proxy_interfaces, $mydestination, $virtual_alias_domains, or
10340 $virtual_mailbox_domains.
10341 IMPORTANT: Either the smtpd_relay_restrictions or the smtpd_recipi‐
10343 ent_restrictions parameter must specify at least one of the following
10344 restrictions. Otherwise Postfix will refuse to receive mail:
10345 reject, reject_unauth_destination
10347 defer, defer_if_permit, defer_unauth_destination
10349 Specify a list of restrictions, separated by commas and/or whitespace.
10351 Continue long lines by starting the next line with whitespace. The
10352 same restrictions are available as documented under smtpd_recipient_re‐
10353 strictions.
10354 This feature is available in Postix 2.10 and later.
10356
10358 User-defined aliases for groups of access restrictions. The aliases can
10359 be specified in smtpd_recipient_restrictions etc., and on the
10360 right-hand side of a Postfix access(5) table.
10361 One major application is for implementing per-recipient UCE control.
10363 See the RESTRICTION_CLASS_README document for other examples.
10364
10366 The application name that the Postfix SMTP server uses for SASL server
10367 initialization. This controls the name of the SASL configuration file.
10368 The default value is smtpd, corresponding to a SASL configuration file
10369 named smtpd.conf.
10370 This feature is available in Postfix 2.1 and 2.2. With Postfix 2.3 it
10372 was renamed to smtpd_sasl_path.
10373
10375 Enable SASL authentication in the Postfix SMTP server. By default, the
10376 Postfix SMTP server does not use authentication.
10377 If a remote SMTP client is authenticated, the permit_sasl_authenticated
10379 access restriction can be used to permit relay access, like this:
10380 # With Postfix 2.10 and later, the mail relay policy is
10382 # preferably specified under smtpd_relay_restrictions.
10383 smtpd_relay_restrictions =
10384 permit_mynetworks, permit_sasl_authenticated, ...
10385 # With Postfix before 2.10, the relay policy can be
10387 # specified only under smtpd_recipient_restrictions.
10388 smtpd_recipient_restrictions =
10389 permit_mynetworks, permit_sasl_authenticated, ...
10390 To reject all SMTP connections from unauthenticated clients, specify
10392 "smtpd_delay_reject = yes" (which is the default) and use:
10393 smtpd_client_restrictions = permit_sasl_authenticated, reject
10395 See the SASL_README file for SASL configuration and operation details.
10397
10399 Report the SASL authenticated user name in the smtpd(8) Received mes‐
10400 sage header.
10401 This feature is available in Postfix 2.3 and later.
10403
10405 What remote SMTP clients the Postfix SMTP server will not offer AUTH
10406 support to.
10407 Some clients (Netscape 4 at least) have a bug that causes them to re‐
10409 quire a login and password whenever AUTH is offered, whether it's nec‐
10410 essary or not. To work around this, specify, for example, $mynetworks
10411 to prevent Postfix from offering AUTH to local clients.
10412 Specify a list of network/netmask patterns, separated by commas and/or
10414 whitespace. The mask specifies the number of bits in the network part
10415 of a host address. You can also "/file/name" or "type:table" patterns.
10416 A "/file/name" pattern is replaced by its contents; a "type:table"
10417 lookup table is matched when a table entry matches a lookup string (the
10418 lookup result is ignored). Continue long lines by starting the next
10419 line with whitespace. Specify "!pattern" to exclude an address or net‐
10420 work block from the list. The form "!/file/name" is supported only in
10421 Postfix version 2.4 and later.
10422 Note: IP version 6 address information must be specified inside [] in
10424 the smtpd_sasl_exceptions_networks value, and in files specified with
10425 "/file/name". IP version 6 addresses contain the ":" character, and
10426 would otherwise be confused with a "type:table" pattern.
10427 Example:
10429 smtpd_sasl_exceptions_networks = $mynetworks
10431 This feature is available in Postfix 2.1 and later.
10433
10435 The name of the Postfix SMTP server's local SASL authentication realm.
10436 By default, the local authentication realm name is the null string.
10438 Examples:
10440 smtpd_sasl_local_domain = $mydomain
10442 smtpd_sasl_local_domain = $myhostname
10443
10445 If non-empty, a filter for the SASL mechanism names that the Postfix
10446 SMTP server will announce in the EHLO response. By default, the Postfix
10447 SMTP server will not announce the EXTERNAL mechanism, because Postfix
10448 support for that is not implemented.
10449 Specify mechanism names, "/file/name" patterns, or "type:table" lookup
10451 tables, separated by comma or whitespace. The right-hand side result
10452 from "type:table" lookups is ignored. Specify "!pattern" to exclude a
10453 mechanism name from the list.
10454 Examples:
10456 smtpd_sasl_mechanism_filter = !external, !gssapi, static:rest
10458 smtpd_sasl_mechanism_filter = login, plain
10459 smtpd_sasl_mechanism_filter = /etc/postfix/smtpd_mechs
10460 This feature is available in Postfix 3.6 and later.
10462
10464 Implementation-specific information that the Postfix SMTP server passes
10465 through to the SASL plug-in implementation that is selected with
10466 smtpd_sasl_type. Typically this specifies the name of a configuration
10467 file or rendezvous point.
10468 This feature is available in Postfix 2.3 and later. In earlier releases
10470 it was called smtpd_sasl_application_name.
10471
10473 The maximum length of a SASL client's response to a server challenge.
10474 When the client's "initial response" is longer than the normal limit
10475 for SMTP commands, the client must omit its initial response, and wait
10476 for an empty server challenge; it can then send what would have been
10477 its "initial response" as a response to the empty server challenge.
10478 RFC4954 requires the server to accept client responses up to at least
10479 12288 octets of base64-encoded text. The default value is therefore
10480 also the minimum value accepted for this parameter.
10481 This feature is available in Postfix 3.4 and later. Prior versions use
10483 "line_length_limit", which may need to be raised to accommodate larger
10484 client responses, as may be needed with GSSAPI authentication of Win‐
10485 dows AD users who are members of many groups.
10486
10488 Postfix SMTP server SASL security options; as of Postfix 2.3 the list
10489 of available features depends on the SASL server implementation that is
10490 selected with smtpd_sasl_type.
10491 The following security features are defined for the cyrus server SASL
10493 implementation:
10494 Restrict what authentication mechanisms the Postfix SMTP server will
10496 offer to the client. The list of available authentication mechanisms
10497 is system dependent.
10498 Specify zero or more of the following:
10500 noplaintext
10502 Disallow methods that use plaintext passwords.
10503 noactive
10505 Disallow methods subject to active (non-dictionary) attack.
10506 nodictionary
10508 Disallow methods subject to passive (dictionary) attack.
10509 noanonymous
10511 Disallow methods that allow anonymous authentication.
10512 forward_secrecy
10514 Only allow methods that support forward secrecy (Dovecot only).
10515 mutual_auth
10517 Only allow methods that provide mutual authentication (not
10518 available with Cyrus SASL version 1).
10519 By default, the Postfix SMTP server accepts plaintext passwords but not
10521 anonymous logins.
10522 Warning: it appears that clients try authentication methods in the or‐
10524 der as advertised by the server (e.g., PLAIN ANONYMOUS CRAM-MD5) which
10525 means that if you disable plaintext passwords, clients will log in
10526 anonymously, even when they should be able to use CRAM-MD5. So, if you
10527 disable plaintext logins, disable anonymous logins too. Postfix treats
10528 anonymous login as no authentication.
10529 Example:
10531 smtpd_sasl_security_options = noanonymous, noplaintext
10533
10535 The service name that is passed to the SASL plug-in that is selected
10536 with smtpd_sasl_type and smtpd_sasl_path.
10537 This feature is available in Postfix 2.11 and later. Prior versions be‐
10539 have as if "smtp" is specified.
10540
10542 The SASL authentication security options that the Postfix SMTP server
10543 uses for TLS encrypted SMTP sessions.
10544 This feature is available in Postfix 2.2 and later.
10546
10548 The SASL plug-in type that the Postfix SMTP server should use for au‐
10549 thentication. The available types are listed with the "postconf -a"
10550 command.
10551 This feature is available in Postfix 2.3 and later.
10553
10555 Optional lookup table with the SASL login names that own the sender
10556 (MAIL FROM) addresses.
10557 Specify zero or more "type:name" lookup tables, separated by whitespace
10559 or comma. Tables will be searched in the specified order until a match
10560 is found. With lookups from indexed files such as DB or DBM, or from
10561 networked tables such as NIS, LDAP or SQL, the following search opera‐
10562 tions are done with a sender address of user@domain:
10563 1) user@domain
10565 This table lookup is always done and has the highest precedence.
10566 2) user
10568 This table lookup is done only when the domain part of the
10569 sender address matches $myorigin, $mydestination, $inet_inter‐
10570 faces or $proxy_interfaces.
10571 3) @domain
10573 This table lookup is done last and has the lowest precedence.
10574 In all cases the result of table lookup must be either "not found" or a
10576 list of SASL login names separated by comma and/or whitespace.
10577
10579 Optional restrictions that the Postfix SMTP server applies in the con‐
10580 text of a client MAIL FROM command. See SMTPD_ACCESS_README, section
10581 "Delayed evaluation of SMTP access restriction lists" for a discussion
10582 of evaluation context and time.
10583 The default is to permit everything.
10585 Specify a list of restrictions, separated by commas and/or whitespace.
10587 Continue long lines by starting the next line with whitespace. Re‐
10588 strictions are applied in the order as specified; the first restriction
10589 that matches wins.
10590 The following restrictions are specific to the sender address received
10592 with the MAIL FROM command.
10593 check_sender_access type:table
10595 Search the specified access(5) database for the MAIL FROM ad‐
10596 dress, domain, parent domains, or localpart@, and execute the
10597 corresponding action.
10598 check_sender_a_access type:table
10600 Search the specified access(5) database for the IP addresses for
10601 the MAIL FROM domain, and execute the corresponding action.
10602 Note: a result of "OK" is not allowed for safety reasons. In‐
10603 stead, use DUNNO in order to exclude specific hosts from
10604 denylists. This feature is available in Postfix 3.0 and later.
10605 check_sender_mx_access type:table
10607 Search the specified access(5) database for the MX hosts for the
10608 MAIL FROM domain, and execute the corresponding action. If no
10609 MX record is found, look up A or AAAA records, just like the
10610 Postfix SMTP client would. Note: a result of "OK" is not allowed
10611 for safety reasons. Instead, use DUNNO in order to exclude spe‐
10612 cific hosts from denylists. This feature is available in Post‐
10613 fix 2.1 and later.
10614 check_sender_ns_access type:table
10616 Search the specified access(5) database for the DNS servers for
10617 the MAIL FROM domain, and execute the corresponding action.
10618 Note: a result of "OK" is not allowed for safety reasons. In‐
10619 stead, use DUNNO in order to exclude specific hosts from
10620 denylists. This feature is available in Postfix 2.1 and later.
10621 reject_authenticated_sender_login_mismatch
10623 Enforces the reject_sender_login_mismatch restriction for au‐
10624 thenticated clients only. This feature is available in Postfix
10625 version 2.1 and later.
10626 reject_known_sender_login_mismatch
10628 Apply the reject_sender_login_mismatch restriction only to MAIL
10629 FROM addresses that are known in $smtpd_sender_login_maps. This
10630 feature is available in Postfix version 2.11 and later.
10631 reject_non_fqdn_sender
10633 Reject the request when the MAIL FROM address specifies a domain
10634 that is not in fully-qualified domain form as required by the
10635 RFC.
10636 The non_fqdn_reject_code parameter specifies the response code
10637 for rejected requests (default: 504).
10638 reject_rhsbl_sender rbl_domain=d.d.d.d
10640 Reject the request when the MAIL FROM domain is listed with the
10641 A record "d.d.d.d" under rbl_domain (Postfix version 2.1 and
10642 later only). Each "d" is a number, or a pattern inside "[]"
10643 that contains one or more ";"-separated numbers or number..num‐
10644 ber ranges (Postfix version 2.8 and later). If no "=d.d.d.d" is
10645 specified, reject the request when the MAIL FROM domain is
10646 listed with any A record under rbl_domain.
10647 The maps_rbl_reject_code parameter specifies the response code
10648 for rejected requests (default: 554); the default_rbl_reply pa‐
10649 rameter specifies the default server reply; and the rbl_re‐
10650 ply_maps parameter specifies tables with server replies indexed
10651 by rbl_domain. This feature is available in Postfix 2.0 and
10652 later.
10653 reject_sender_login_mismatch
10655 Reject the request when $smtpd_sender_login_maps specifies an
10656 owner for the MAIL FROM address, but the client is not (SASL)
10657 logged in as that MAIL FROM address owner; or when the client is
10658 (SASL) logged in, but the client login name doesn't own the MAIL
10659 FROM address according to $smtpd_sender_login_maps.
10660 reject_unauthenticated_sender_login_mismatch
10662 Enforces the reject_sender_login_mismatch restriction for unau‐
10663 thenticated clients only. This feature is available in Postfix
10664 version 2.1 and later.
10665 reject_unknown_sender_domain
10667 Reject the request when Postfix is not final destination for the
10668 sender address, and the MAIL FROM domain has 1) no DNS MX and no
10669 DNS A record, or 2) a malformed MX record such as a record with
10670 a zero-length MX hostname (Postfix version 2.3 and later).
10671 The reply is specified with the unknown_address_reject_code pa‐
10672 rameter (default: 450), unknown_address_tempfail_action (de‐
10673 fault: defer_if_permit), or 550 (nullmx, Postfix 3.0 and later).
10674 See the respective parameter descriptions for details.
10675 reject_unlisted_sender
10677 Reject the request when the MAIL FROM address is not listed in
10678 the list of valid recipients for its domain class. See the
10679 smtpd_reject_unlisted_sender parameter description for details.
10680 This feature is available in Postfix 2.1 and later.
10681 reject_unverified_sender
10683 Reject the request when mail to the MAIL FROM address is known
10684 to bounce, or when the sender address destination is not reach‐
10685 able. Address verification information is managed by the ver‐
10686 ify(8) server; see the ADDRESS_VERIFICATION_README file for de‐
10687 tails.
10688 The unverified_sender_reject_code parameter specifies the numer‐
10689 ical response code when an address is known to bounce (default:
10690 450, change into 550 when you are confident that it is safe to
10691 do so).
10692 The unverified_sender_defer_code specifies the numerical re‐
10693 sponse code when an address probe failed due to a temporary
10694 problem (default: 450).
10695 The unverified_sender_tempfail_action parameter specifies the
10696 action after address probe failure due to a temporary problem
10697 (default: defer_if_permit).
10698 This feature breaks for aliased addresses with "enable_origi‐
10699 nal_recipient = no" (Postfix <= 3.2).
10700 This feature is available in Postfix 2.1 and later.
10701 Other restrictions that are valid in this context:
10703 • Generic restrictions that can be used in any SMTP command con‐
10705 text, described under smtpd_client_restrictions.
10706 • SMTP command specific restrictions described under
10708 smtpd_client_restrictions and smtpd_helo_restrictions.
10709 • SMTP command specific restrictions described under smtpd_recipi‐
10711 ent_restrictions. When recipient restrictions are listed under
10712 smtpd_sender_restrictions, they have effect only with "smtpd_de‐
10713 lay_reject = yes", so that $smtpd_sender_restrictions is evalu‐
10714 ated at the time of the RCPT TO command.
10715 Examples:
10717 smtpd_sender_restrictions = reject_unknown_sender_domain
10719 smtpd_sender_restrictions = reject_unknown_sender_domain,
10720 check_sender_access hash:/etc/postfix/access
10721
10723 The internal service that postscreen(8) hands off allowed connections
10724 to. In a future version there may be different classes of SMTP service.
10725 This feature is available in Postfix 2.8.
10727
10729 The number of errors a remote SMTP client is allowed to make without
10730 delivering mail before the Postfix SMTP server slows down all its re‐
10731 sponses.
10732 • With Postfix version 2.1 and later, the Postfix SMTP server de‐
10734 lays all responses by $smtpd_error_sleep_time seconds.
10735 • With Postfix versions 2.0 and earlier, the Postfix SMTP server
10737 delays all responses by (number of errors) seconds.
10738
10740 The time limit for Postfix SMTP server write and read operations during
10741 TLS startup and shutdown handshake procedures. The current default
10742 value is stress-dependent. Before Postfix version 2.8, it was fixed at
10743 300s.
10744 This feature is available in Postfix 2.2 and later.
10746
10748 The time limit for sending a Postfix SMTP server response and for re‐
10749 ceiving a remote SMTP client request. Normally the default limit is
10750 300s, but it changes under overload to just 10s. With Postfix 2.5 and
10751 earlier, the SMTP server always uses a time limit of 300s by default.
10752 Note: if you set SMTP time limits to very large values you may have to
10754 update the global ipc_timeout parameter.
10755 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
10757 The default time unit is s (seconds).
10758
10760 A file containing (PEM format) CA certificates of root CAs trusted to
10761 sign either remote SMTP client certificates or intermediate CA certifi‐
10762 cates. These are loaded into memory before the smtpd(8) server enters
10763 the chroot jail. If the number of trusted roots is large, consider us‐
10764 ing smtpd_tls_CApath instead, but note that the latter directory must
10765 be present in the chroot jail if the smtpd(8) server is chrooted. This
10766 file may also be used to augment the server certificate trust chain,
10767 but it is best to include all the required certificates directly in the
10768 server certificate file.
10769 Specify "smtpd_tls_CAfile = /path/to/system_CA_file" to use ONLY the
10771 system-supplied default Certification Authority certificates.
10772 Specify "tls_append_default_CA = no" to prevent Postfix from appending
10774 the system-supplied default CAs and trusting third-party certificates.
10775 By default (see smtpd_tls_ask_ccert), client certificates are not re‐
10777 quested, and smtpd_tls_CAfile should remain empty. If you do make use
10778 of client certificates, the distinguished names (DNs) of the Certifica‐
10779 tion Authorities listed in smtpd_tls_CAfile are sent to the remote SMTP
10780 client in the client certificate request message. MUAs with multiple
10781 client certificates may use the list of preferred Certification Author‐
10782 ities to select the correct client certificate. You may want to put
10783 your "preferred" CA or CAs in this file, and install other trusted CAs
10784 in $smtpd_tls_CApath.
10785 Example:
10787 smtpd_tls_CAfile = /etc/postfix/CAcert.pem
10789 This feature is available in Postfix 2.2 and later.
10791
10793 A directory containing (PEM format) CA certificates of root CAs trusted
10794 to sign either remote SMTP client certificates or intermediate CA cer‐
10795 tificates. Do not forget to create the necessary "hash" links with, for
10796 example, "$OPENSSL_HOME/bin/c_rehash /etc/postfix/certs". To use
10797 smtpd_tls_CApath in chroot mode, this directory (or a copy) must be in‐
10798 side the chroot jail.
10799 Specify "smtpd_tls_CApath = /path/to/system_CA_directory" to use ONLY
10801 the system-supplied default Certification Authority certificates.
10802 Specify "tls_append_default_CA = no" to prevent Postfix from appending
10804 the system-supplied default CAs and trusting third-party certificates.
10805 By default (see smtpd_tls_ask_ccert), client certificates are not re‐
10807 quested, and smtpd_tls_CApath should remain empty. In contrast to
10808 smtpd_tls_CAfile, DNs of Certification Authorities installed in
10809 $smtpd_tls_CApath are not included in the client certificate request
10810 message. MUAs with multiple client certificates may use the list of
10811 preferred Certification Authorities to select the correct client cer‐
10812 tificate. You may want to put your "preferred" CA or CAs in
10813 $smtpd_tls_CAfile, and install the remaining trusted CAs in
10814 $smtpd_tls_CApath.
10815 Example:
10817 smtpd_tls_CApath = /etc/postfix/certs
10819 This feature is available in Postfix 2.2 and later.
10821
10823 Force the Postfix SMTP server to issue a TLS session id, even when TLS
10824 session caching is turned off (smtpd_tls_session_cache_database is
10825 empty). This behavior is compatible with Postfix < 2.3.
10826 With Postfix 2.3 and later the Postfix SMTP server can disable session
10828 id generation when TLS session caching is turned off. This keeps remote
10829 SMTP clients from caching sessions that almost certainly cannot be
10830 re-used.
10831 By default, the Postfix SMTP server always generates TLS session ids.
10833 This works around a known defect in mail client applications such as MS
10834 Outlook, and may also prevent interoperability issues with other MTAs.
10835 Example:
10837 smtpd_tls_always_issue_session_ids = no
10839 This feature is available in Postfix 2.3 and later.
10841
10843 Ask a remote SMTP client for a client certificate. This information is
10844 needed for certificate based mail relaying with, for example, the per‐
10845 mit_tls_clientcerts feature.
10846 Some clients such as Netscape will either complain if no certificate is
10848 available (for the list of CAs in $smtpd_tls_CAfile) or will offer mul‐
10849 tiple client certificates to choose from. This may be annoying, so this
10850 option is "off" by default.
10851 This feature is available in Postfix 2.2 and later.
10853
10855 When TLS encryption is optional in the Postfix SMTP server, do not an‐
10856 nounce or accept SASL authentication over unencrypted connections.
10857 This feature is available in Postfix 2.2 and later.
10859
10861 The verification depth for remote SMTP client certificates. A depth of
10862 1 is sufficient if the issuing CA is listed in a local CA file.
10863 The default verification depth is 9 (the OpenSSL default) for compati‐
10865 bility with earlier Postfix behavior. Prior to Postfix 2.5, the default
10866 value was 5, but the limit was not actually enforced. If you have set
10867 this to a lower non-default value, certificates with longer trust
10868 chains may now fail to verify. Certificate chains with 1 or 2 CAs are
10869 common, deeper chains are more rare and any number between 5 and 9
10870 should suffice in practice. You can choose a lower number if, for exam‐
10871 ple, you trust certificates directly signed by an issuing CA but not
10872 any CAs it delegates to.
10873 This feature is available in Postfix 2.2 and later.
10875
10877 File with the Postfix SMTP server RSA certificate in PEM format. This
10878 file may also contain the Postfix SMTP server private RSA key. With
10879 Postfix >= 3.4 the preferred way to configure server keys and certifi‐
10880 cates is via the "smtpd_tls_chain_files" parameter.
10881 Public Internet MX hosts without certificates signed by a "reputable"
10883 CA must generate, and be prepared to present to most clients, a
10884 self-signed or private-CA signed certificate. The client will not be
10885 able to authenticate the server, but unless it is running Postfix 2.3
10886 or similar software, it will still insist on a server certificate.
10887 For servers that are not public Internet MX hosts, Postfix supports
10889 configurations with no certificates. This entails the use of just the
10890 anonymous TLS ciphers, which are not supported by typical SMTP clients.
10891 Since some clients may not fall back to plain text after a TLS hand‐
10892 shake failure, a certificate-less Postfix SMTP server will be unable to
10893 receive email from some TLS-enabled clients. To avoid accidental con‐
10894 figurations with no certificates, Postfix enables certificate-less op‐
10895 eration only when the administrator explicitly sets
10896 "smtpd_tls_cert_file = none". This ensures that new Postfix SMTP server
10897 configurations will not accidentally enable TLS without certificates.
10898 Note that server certificates are not optional in TLS 1.3. To run with‐
10900 out certificates you'd have to disable the TLS 1.3 protocol by includ‐
10901 ing '!TLSv1.3' in "smtpd_tls_protocols" and perhaps also
10902 "smtpd_tls_mandatory_protocols". It is simpler instead to just config‐
10903 ure a certificate chain. Certificate-less operation is not recom‐
10904 mended.
10905 Both RSA and DSA certificates are supported. When both types are
10907 present, the cipher used determines which certificate will be presented
10908 to the client. For Netscape and OpenSSL clients without special cipher
10909 choices the RSA certificate is preferred.
10910 To enable a remote SMTP client to verify the Postfix SMTP server cer‐
10912 tificate, the issuing CA certificates must be made available to the
10913 client. You should include the required certificates in the server cer‐
10914 tificate file, the server certificate first, then the issuing CA(s)
10915 (bottom-up order).
10916 Example: the certificate for "server.example.com" was issued by "inter‐
10918 mediate CA" which itself has a certificate of "root CA". Create the
10919 server.pem file with "cat server_cert.pem intermediate_CA.pem
10920 root_CA.pem > server.pem".
10921 If you also want to verify client certificates issued by these CAs, you
10923 can add the CA certificates to the smtpd_tls_CAfile, in which case it
10924 is not necessary to have them in the smtpd_tls_cert_file,
10925 smtpd_tls_dcert_file (obsolete) or smtpd_tls_eccert_file.
10926 A certificate supplied here must be usable as an SSL server certificate
10928 and hence pass the "openssl verify -purpose sslserver ..." test.
10929 Example:
10931 smtpd_tls_cert_file = /etc/postfix/server.pem
10933 This feature is available in Postfix 2.2 and later.
10935
10937 List of one or more PEM files, each holding one or more private keys
10938 directly followed by a corresponding certificate chain. The file names
10939 are separated by commas and/or whitespace. This parameter obsoletes
10940 the legacy algorithm-specific key and certificate file settings. When
10941 this parameter is non-empty, the legacy parameters are ignored, and a
10942 warning is logged if any are also non-empty.
10943 With the proliferation of multiple private key algorithms-which, as of
10945 OpenSSL 1.1.1, include DSA (obsolete), RSA, ECDSA, Ed25519 and Ed448-it
10946 is increasingly impractical to use separate parameters to configure the
10947 key and certificate chain for each algorithm. Therefore, Postfix now
10948 supports storing multiple keys and corresponding certificate chains in
10949 a single file or in a set of files.
10950 Each key must appear immediately before the corresponding certificate,
10952 optionally followed by additional issuer certificates that complete the
10953 certificate chain for that key. When multiple files are specified,
10954 they are equivalent to a single file that is concatenated from those
10955 files in the given order. Thus, while a key must always precede its
10956 certificate and issuer chain, it can be in a separate file, so long as
10957 that file is listed immediately before the file that holds the corre‐
10958 sponding certificate chain. Once all the files are concatenated, the
10959 sequence of PEM objects must be: key1, cert1, [chain1], key2, cert2,
10960 [chain2], ..., keyN, certN, [chainN].
10961 Storing the private key in the same file as the corresponding certifi‐
10963 cate is more reliable. With the key and certificate in separate files,
10964 there is a chance that during key rollover a Postfix process might load
10965 a private key and certificate from separate files that don't match.
10966 Various operational errors may even result in a persistent broken con‐
10967 figuration in which the certificate does not match the private key.
10968 The file or files must contain at most one key of each type. If, for
10970 example, two or more RSA keys and corresponding chains are listed, de‐
10971 pending on the version of OpenSSL either only the last one will be used
10972 or an configuration error may be detected. Note that while "Ed25519"
10973 and "Ed448" are considered separate algorithms, the various ECDSA
10974 curves (typically one of prime256v1, secp384r1 or secp521r1) are con‐
10975 sidered as different parameters of a single "ECDSA" algorithm, so it is
10976 not presently possible to configure keys for more than one ECDSA curve.
10977 RSA is still the most widely supported algorithm. Presently (late
10979 2018), ECDSA support is common, but not yet universal, and Ed25519 and
10980 Ed448 support is mostly absent. Therefore, an RSA key should generally
10981 be configured, along with any additional keys for the other algorithms
10982 when desired.
10983 Example (separate files for each key and corresponding certificate
10985 chain):
10986 /etc/postfix/main.cf:
10988 smtpd_tls_chain_files =
10989 ${config_directory}/ed25519.pem,
10990 ${config_directory}/ed448.pem,
10991 ${config_directory}/rsa.pem
10992 /etc/postfix/ed25519.pem:
10994 -----BEGIN PRIVATE KEY-----
10995 MC4CAQAwBQYDK2VwBCIEIEJfbbO4BgBQGBg9NAbIJaDBqZb4bC4cOkjtAH+Efbz3
10996 -----END PRIVATE KEY-----
10997 -----BEGIN CERTIFICATE-----
10998 MIIBKzCB3qADAgECAhQaw+rflRreYuUZBp0HuNn/e5rMZDAFBgMrZXAwFDESMBAG
10999 ...
11000 nC0egv51YPDWxEHom4QA
11001 -----END CERTIFICATE-----
11002 /etc/postfix/ed448.pem:
11004 -----BEGIN PRIVATE KEY-----
11005 MEcCAQAwBQYDK2VxBDsEOQf+m0P+G0qi+NZ0RolyeiE5zdlPQR8h8y4jByBifpIe
11006 LNler7nzHQJ1SLcOiXFHXlxp/84VZuh32A==
11007 -----END PRIVATE KEY-----
11008 -----BEGIN CERTIFICATE-----
11009 MIIBdjCB96ADAgECAhQSv4oP972KypOZPNPF4fmsiQoRHzAFBgMrZXEwFDESMBAG
11010 ...
11011 pQcWsx+4J29e6YWH3Cy/CdUaexKP4RPCZDrPX7bk5C2BQ+eeYOxyThMA
11012 -----END CERTIFICATE-----
11013 /etc/postfix/rsa.pem:
11015 -----BEGIN PRIVATE KEY-----
11016 MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDc4QusgkahH9rL
11017 ...
11018 ahQkZ3+krcaJvDSMgvu0tDc=
11019 -----END PRIVATE KEY-----
11020 -----BEGIN CERTIFICATE-----
11021 MIIC+DCCAeCgAwIBAgIUIUkrbk1GAemPCT8i9wKsTGDH7HswDQYJKoZIhvcNAQEL
11022 ...
11023 Rirz15HGVNTK8wzFd+nulPzwUo6dH2IU8KazmyRi7OGvpyrMlm15TRE2oyE=
11024 -----END CERTIFICATE-----
11025 Example (all keys and certificates in a single file):
11027 /etc/postfix/main.cf:
11029 smtpd_tls_chain_files = ${config_directory}/chains.pem
11030 /etc/postfix/chains.pem:
11032 -----BEGIN PRIVATE KEY-----
11033 MC4CAQAwBQYDK2VwBCIEIEJfbbO4BgBQGBg9NAbIJaDBqZb4bC4cOkjtAH+Efbz3
11034 -----END PRIVATE KEY-----
11035 -----BEGIN CERTIFICATE-----
11036 MIIBKzCB3qADAgECAhQaw+rflRreYuUZBp0HuNn/e5rMZDAFBgMrZXAwFDESMBAG
11037 ...
11038 nC0egv51YPDWxEHom4QA
11039 -----END CERTIFICATE-----
11040 -----BEGIN PRIVATE KEY-----
11041 MEcCAQAwBQYDK2VxBDsEOQf+m0P+G0qi+NZ0RolyeiE5zdlPQR8h8y4jByBifpIe
11042 LNler7nzHQJ1SLcOiXFHXlxp/84VZuh32A==
11043 -----END PRIVATE KEY-----
11044 -----BEGIN CERTIFICATE-----
11045 MIIBdjCB96ADAgECAhQSv4oP972KypOZPNPF4fmsiQoRHzAFBgMrZXEwFDESMBAG
11046 ...
11047 pQcWsx+4J29e6YWH3Cy/CdUaexKP4RPCZDrPX7bk5C2BQ+eeYOxyThMA
11048 -----END CERTIFICATE-----
11049 -----BEGIN PRIVATE KEY-----
11050 MIIEvQIBADANBgkqhkiG9w0BAQEFAASCBKcwggSjAgEAAoIBAQDc4QusgkahH9rL
11051 ...
11052 ahQkZ3+krcaJvDSMgvu0tDc=
11053 -----END PRIVATE KEY-----
11054 -----BEGIN CERTIFICATE-----
11055 MIIC+DCCAeCgAwIBAgIUIUkrbk1GAemPCT8i9wKsTGDH7HswDQYJKoZIhvcNAQEL
11056 ...
11057 Rirz15HGVNTK8wzFd+nulPzwUo6dH2IU8KazmyRi7OGvpyrMlm15TRE2oyE=
11058 -----END CERTIFICATE-----
11059 This feature is available in Postfix 3.4 and later.
11061
11063 Obsolete Postfix < 2.3 control for the Postfix SMTP server TLS cipher
11064 list. It is easy to create interoperability problems by choosing a
11065 non-default cipher list. Do not use a non-default TLS cipherlist for MX
11066 hosts on the public Internet. Clients that begin the TLS handshake, but
11067 are unable to agree on a common cipher, may not be able to send any
11068 email to the SMTP server. Using a restricted cipher list may be more
11069 appropriate for a dedicated MSA or an internal mailhub, where one can
11070 exert some control over the TLS software and settings of the connecting
11071 clients.
11072 Note: do not use "" quotes around the parameter value.
11074 This feature is available with Postfix version 2.2. It is not used with
11076 Postfix 2.3 and later; use smtpd_tls_mandatory_ciphers instead.
11077
11079 The minimum TLS cipher grade that the Postfix SMTP server will use with
11080 opportunistic TLS encryption. Cipher types listed in smtpd_tls_ex‐
11081 clude_ciphers are excluded from the base definition of the selected ci‐
11082 pher grade. The default value is "medium" for Postfix releases after
11083 the middle of 2015, "export" for older releases.
11084 When TLS is mandatory the cipher grade is chosen via the
11086 smtpd_tls_mandatory_ciphers configuration parameter, see there for syn‐
11087 tax details.
11088 This feature is available in Postfix 2.6 and later. With earlier Post‐
11090 fix releases only the smtpd_tls_mandatory_ciphers parameter is imple‐
11091 mented, and opportunistic TLS always uses "export" or better (i.e. all)
11092 ciphers.
11093
11095 File with the Postfix SMTP server DSA certificate in PEM format. This
11096 file may also contain the Postfix SMTP server private DSA key. The DSA
11097 algorithm is obsolete and should not be used.
11098 See the discussion under smtpd_tls_cert_file for more details.
11100 Example:
11102 smtpd_tls_dcert_file = /etc/postfix/server-dsa.pem
11104 This feature is available in Postfix 2.2 and later.
11106
11108 File with DH parameters that the Postfix SMTP server should use with
11109 non-export EDH ciphers.
11110 The best-practice choice of parameters uses a 2048-bit prime. This is
11112 fine, despite the historical "1024" in the parameter name. Do not be
11113 tempted to use much larger values, performance degrades quickly, and
11114 you may also cease to interoperate with some mainstream SMTP clients.
11115 As of Postfix 3.1, the compiled-in default prime is 2048-bits, and it
11116 is not strictly necessary, though perhaps somewhat beneficial to gener‐
11117 ate custom DH parameters.
11118 Instead of using the exact same parameter sets as distributed with
11120 other TLS packages, it is more secure to generate your own set of pa‐
11121 rameters with something like the following commands:
11122 openssl dhparam -out /etc/postfix/dh2048.pem 2048
11124 openssl dhparam -out /etc/postfix/dh1024.pem 1024
11125 # As of Postfix 3.6, export-grade 512-bit DH parameters are no longer
11126 # supported or needed.
11127 openssl dhparam -out /etc/postfix/dh512.pem 512
11128 It is safe to share the same DH parameters between multiple Postfix in‐
11130 stances. If you prefer, you can generate separate parameters for each
11131 instance.
11132 If you want to take maximal advantage of ciphers that offer forward se‐
11134 crecy see the Getting started section of FORWARD_SECRECY_README. The
11135 full document conveniently presents all information about Postfix "per‐
11136 fect" forward secrecy support in one place: what forward secrecy is,
11137 how to tweak settings, and what you can expect to see when Postfix uses
11138 ciphers with forward secrecy.
11139 Example:
11141 smtpd_tls_dh1024_param_file = /etc/postfix/dh2048.pem
11143 This feature is available with Postfix version 2.2.
11145
11147 File with DH parameters that the Postfix SMTP server should use with
11148 export-grade EDH ciphers. The default SMTP server cipher grade is
11149 "medium" with Postfix releases after the middle of 2015, and as a re‐
11150 sult export-grade cipher suites are by default not used.
11151 With Postfix >= 3.6 export-grade Diffie-Hellman key exchange is no
11153 longer supported, and this parameter is silently ignored.
11154 See also the discussion under the smtpd_tls_dh1024_param_file configu‐
11156 ration parameter.
11157 Example:
11159 smtpd_tls_dh512_param_file = /etc/postfix/dh_512.pem
11161 This feature is available with Postfix version 2.2.
11163
11165 File with the Postfix SMTP server DSA private key in PEM format. This
11166 file may be combined with the Postfix SMTP server DSA certificate file
11167 specified with $smtpd_tls_dcert_file. The DSA algorithm is obsolete and
11168 should not be used.
11169 The private key must be accessible without a pass-phrase, i.e. it must
11171 not be encrypted. File permissions should grant read-only access to the
11172 system superuser account ("root"), and no access to anyone else.
11173 This feature is available in Postfix 2.2 and later.
11175
11177 File with the Postfix SMTP server ECDSA certificate in PEM format.
11178 This file may also contain the Postfix SMTP server private ECDSA key.
11179 With Postfix >= 3.4 the preferred way to configure server keys and cer‐
11180 tificates is via the "smtpd_tls_chain_files" parameter.
11181 See the discussion under smtpd_tls_cert_file for more details.
11183 Example:
11185 smtpd_tls_eccert_file = /etc/postfix/ecdsa-scert.pem
11187 This feature is available in Postfix 2.6 and later, when Postfix is
11189 compiled and linked with OpenSSL 1.0.0 or later.
11190
11192 File with the Postfix SMTP server ECDSA private key in PEM format.
11193 This file may be combined with the Postfix SMTP server ECDSA certifi‐
11194 cate file specified with $smtpd_tls_eccert_file. With Postfix >= 3.4
11195 the preferred way to configure server keys and certificates is via the
11196 "smtpd_tls_chain_files" parameter.
11197 The private key must be accessible without a pass-phrase, i.e. it must
11199 not be encrypted. File permissions should grant read-only access to the
11200 system superuser account ("root"), and no access to anyone else.
11201 This feature is available in Postfix 2.6 and later, when Postfix is
11203 compiled and linked with OpenSSL 1.0.0 or later.
11204
11206 The Postfix SMTP server security grade for ephemeral elliptic-curve
11207 Diffie-Hellman (EECDH) key exchange. As of Postfix 3.6, the value of
11208 this parameter is always ignored, and Postfix behaves as though the
11209 auto value (described below) was chosen.
11210 The available choices are:
11212 auto Use the most preferred curve that is supported by both the
11214 client and the server. This setting requires Postfix >= 3.2
11215 compiled and linked with OpenSSL >= 1.0.2. This is the default
11216 setting under the above conditions (and the only setting used
11217 with Postfix >= 3.6).
11218 none Don't use EECDH. Ciphers based on EECDH key exchange will be
11220 disabled. This is the default in Postfix versions 2.6 and 2.7.
11221 strong Use EECDH with approximately 128 bits of security at a reason‐
11223 able computational cost. This is the default in Postfix versions
11224 2.8-3.5.
11225 ultra Use EECDH with approximately 192 bits of security at computa‐
11227 tional cost that is approximately twice as high as 128 bit
11228 strength ECC.
11229 If you want to take maximal advantage of ciphers that offer forward se‐
11231 crecy see the Getting started section of FORWARD_SECRECY_README. The
11232 full document conveniently presents all information about Postfix "per‐
11233 fect" forward secrecy support in one place: what forward secrecy is,
11234 how to tweak settings, and what you can expect to see when Postfix uses
11235 ciphers with forward secrecy.
11236 This feature is available in Postfix 2.6 and later, when it is compiled
11238 and linked with OpenSSL 1.0.0 or later on platforms where EC algorithms
11239 have not been disabled by the vendor.
11240
11242 List of ciphers or cipher types to exclude from the SMTP server cipher
11243 list at all TLS security levels. Excluding valid ciphers can create in‐
11244 teroperability problems. DO NOT exclude ciphers unless it is essential
11245 to do so. This is not an OpenSSL cipherlist; it is a simple list sepa‐
11246 rated by whitespace and/or commas. The elements are a single cipher, or
11247 one or more "+" separated cipher properties, in which case only ciphers
11248 matching all the properties are excluded.
11249 Examples (some of these will cause problems):
11251 smtpd_tls_exclude_ciphers = aNULL
11253 smtpd_tls_exclude_ciphers = MD5, DES
11254 smtpd_tls_exclude_ciphers = DES+MD5
11255 smtpd_tls_exclude_ciphers = AES256-SHA, DES-CBC3-MD5
11256 smtpd_tls_exclude_ciphers = kEDH+aRSA
11257 The first setting disables anonymous ciphers. The next setting disables
11259 ciphers that use the MD5 digest algorithm or the (single) DES encryp‐
11260 tion algorithm. The next setting disables ciphers that use MD5 and DES
11261 together. The next setting disables the two ciphers "AES256-SHA" and
11262 "DES-CBC3-MD5". The last setting disables ciphers that use "EDH" key
11263 exchange with RSA authentication.
11264 This feature is available in Postfix 2.3 and later.
11266
11268 The message digest algorithm to construct remote SMTP client-certifi‐
11269 cate fingerprints or public key fingerprints (Postfix 2.9 and later)
11270 for check_ccert_access and permit_tls_clientcerts.
11271 The default algorithm is sha256 with Postfix >= 3.6 and the compatibil‐
11273 ity_level set to 3.6 or higher. With Postfix <= 3.5, the default algo‐
11274 rithm is md5.
11275 The best-practice algorithm is now sha256. Recent advances in hash
11277 function cryptanalysis have led to md5 and sha1 being deprecated in fa‐
11278 vor of sha256. However, as long as there are no known "second pre-im‐
11279 age" attacks against the older algorithms, their use in this context,
11280 though not recommended, is still likely safe.
11281 While additional digest algorithms are often available with OpenSSL's
11283 libcrypto, only those used by libssl in SSL cipher suites are available
11284 to Postfix. You'll likely find support for md5, sha1, sha256 and
11285 sha512.
11286 To find the fingerprint of a specific certificate file, with a specific
11288 digest algorithm, run:
11289 $ openssl x509 -noout -fingerprint -digest -in certfile.pem
11291 The text to the right of "=" sign is the desired fingerprint. For ex‐
11293 ample:
11294 $ openssl x509 -noout -fingerprint -sha256 -in cert.pem
11296 SHA256 Fingerprint=D4:6A:AB:19:24:...:A6:CB:66:82:C0:8E:9B:EE:29:A8:1A
11297 To extract the public key fingerprint from an X.509 certificate, you
11299 need to extract the public key from the certificate and compute the ap‐
11300 propriate digest of its DER (ASN.1) encoding. With OpenSSL the "-pub‐
11301 key" option of the "x509" command extracts the public key always in
11302 "PEM" format. We pipe the result to another OpenSSL command that con‐
11303 verts the key to DER and then to the "dgst" command to compute the fin‐
11304 gerprint.
11305 Example:
11307 $ openssl x509 -in cert.pem -noout -pubkey |
11309 openssl pkey -pubin -outform DER |
11310 openssl dgst -sha256 -c
11311 (stdin)= 64:3f:1f:f6:e5:1e:d4:2a:56:8b:fc:09:1a:61:98:b5:bc:7c:60:58
11312 The Postfix SMTP server and client log the peer (leaf) certificate fin‐
11314 gerprint and public key fingerprint when the TLS loglevel is 2 or
11315 higher.
11316 Example: client-certificate access table, with sha256 fingerprints:
11318 /etc/postfix/main.cf:
11320 smtpd_tls_fingerprint_digest = sha256
11321 smtpd_client_restrictions =
11322 check_ccert_access hash:/etc/postfix/access,
11323 reject
11324 /etc/postfix/access:
11325 # Action folded to next line...
11326 AF:88:7C:AD:51:95:6F:36:96:...:01:FB:2E:48:CD:AB:49:25:A2:3B
11327 OK
11328 85:16:78:FD:73:6E:CE:70:E0:...:5F:0D:3C:C8:6D:C4:2C:24:59:E1
11329 permit_auth_destination
11330 This feature is available in Postfix 2.5 and later.
11332
11334 File with the Postfix SMTP server RSA private key in PEM format. This
11335 file may be combined with the Postfix SMTP server RSA certificate file
11336 specified with $smtpd_tls_cert_file. With Postfix >= 3.4 the preferred
11337 way to configure server keys and certificates is via the
11338 "smtpd_tls_chain_files" parameter.
11339 The private key must be accessible without a pass-phrase, i.e. it must
11341 not be encrypted. File permissions should grant read-only access to the
11342 system superuser account ("root"), and no access to anyone else.
11343
11345 Enable additional Postfix SMTP server logging of TLS activity. Each
11346 logging level also includes the information that is logged at a lower
11347 logging level.
11348 0 Disable logging of TLS activity.
11350 1 Log only a summary message on TLS handshake completion - no
11352 logging of client certificate trust-chain verification errors if
11353 client certificate verification is not required. With Postfix
11354 2.8 and earlier, log the summary message, peer certificate sum‐
11355 mary information and unconditionally log trust-chain verifica‐
11356 tion errors.
11357 2 Also log levels during TLS negotiation.
11359 3 Also log hexadecimal and ASCII dump of TLS negotiation
11361 process.
11362 4 Also log hexadecimal and ASCII dump of complete transmission
11364 after STARTTLS.
11365 Do not use "smtpd_tls_loglevel = 2" or higher except in case of prob‐
11367 lems. Use of loglevel 4 is strongly discouraged.
11368 This feature is available in Postfix 2.2 and later.
11370
11372 The minimum TLS cipher grade that the Postfix SMTP server will use with
11373 mandatory TLS encryption. The default grade ("medium") is sufficiently
11374 strong that any benefit from globally restricting TLS sessions to a
11375 more stringent grade is likely negligible, especially given the fact
11376 that many implementations still do not offer any stronger ("high"
11377 grade) ciphers, while those that do, will always use "high" grade ci‐
11378 phers. So insisting on "high" grade ciphers is generally counter-pro‐
11379 ductive. Allowing "export" or "low" ciphers is typically not a good
11380 idea, as systems limited to just these are limited to obsolete
11381 browsers. No known SMTP clients fail to support at least one "medium"
11382 or "high" grade cipher.
11383 The following cipher grades are supported:
11385 export Enable "EXPORT" grade or stronger OpenSSL ciphers. The underly‐
11387 ing cipherlist is specified via the tls_export_cipherlist con‐
11388 figuration parameter, which you are strongly encouraged to not
11389 change. This choice is insecure and SHOULD NOT be used.
11390 low Enable "LOW" grade or stronger OpenSSL ciphers. The underlying
11392 cipherlist is specified via the tls_low_cipherlist configuration
11393 parameter, which you are strongly encouraged to not change.
11394 This choice is insecure and SHOULD NOT be used.
11395 medium Enable "MEDIUM" grade or stronger OpenSSL ciphers. These use
11397 128-bit or longer symmetric bulk-encryption keys. This is the
11398 default minimum strength for mandatory TLS encryption. The un‐
11399 derlying cipherlist is specified via the tls_medium_cipherlist
11400 configuration parameter, which you are strongly encouraged to
11401 not change.
11402 high Enable only "HIGH" grade OpenSSL ciphers. The underlying ci‐
11404 pherlist is specified via the tls_high_cipherlist configuration
11405 parameter, which you are strongly encouraged to not change.
11406 null Enable only the "NULL" OpenSSL ciphers, these provide authenti‐
11408 cation without encryption. This setting is only appropriate in
11409 the rare case that all clients are prepared to use NULL ciphers
11410 (not normally enabled in TLS clients). The underlying cipherlist
11411 is specified via the tls_null_cipherlist configuration parame‐
11412 ter, which you are strongly encouraged to not change.
11413 Cipher types listed in smtpd_tls_mandatory_exclude_ciphers or
11415 smtpd_tls_exclude_ciphers are excluded from the base definition of the
11416 selected cipher grade. See smtpd_tls_ciphers for cipher controls that
11417 apply to opportunistic TLS.
11418 The underlying cipherlists for grades other than "null" include anony‐
11420 mous ciphers, but these are automatically filtered out if the server is
11421 configured to ask for remote SMTP client certificates. You are very
11422 unlikely to need to take any steps to exclude anonymous ciphers, they
11423 are excluded automatically as required. If you must exclude anonymous
11424 ciphers even when Postfix does not need or use peer certificates, set
11425 "smtpd_tls_exclude_ciphers = aNULL". To exclude anonymous ciphers only
11426 when TLS is enforced, set "smtpd_tls_mandatory_exclude_ciphers = aN‐
11427 ULL".
11428 This feature is available in Postfix 2.3 and later.
11430
11432 Additional list of ciphers or cipher types to exclude from the Postfix
11433 SMTP server cipher list at mandatory TLS security levels. This list
11434 works in addition to the exclusions listed with smtpd_tls_exclude_ci‐
11435 phers (see there for syntax details).
11436 This feature is available in Postfix 2.3 and later.
11438
11440 TLS protocols accepted by the Postfix SMTP server with mandatory TLS
11441 encryption. If the list is empty, the server supports all available
11442 TLS protocol versions. A non-empty value is a list of protocol names
11443 to include or exclude, separated by whitespace, commas or colons.
11444 The valid protocol names (see SSL_get_version(3)) are "SSLv2", "SSLv3",
11446 "TLSv1", "TLSv1.1", "TLSv1.2" and "TLSv1.3". Starting with Postfix
11447 3.6, the default value is ">=TLSv1", which sets TLS 1.0 as the lowest
11448 supported TLS protocol version (see below). Older releases use the "!"
11449 exclusion syntax, also described below.
11450 As of Postfix 3.6, the preferred way to limit the range of acceptable
11452 protocols is to set the lowest acceptable TLS protocol version and/or
11453 the highest acceptable TLS protocol version. To set the lower bound
11454 include an element of the form: ">=version" where version is a either
11455 one of the TLS protocol names listed above, or a hexadecimal number
11456 corresponding to the desired TLS protocol version (0301 for TLS 1.0,
11457 0302 for TLS 1.1, etc.). For the upper bound, use "<=version". There
11458 must be no whitespace between the ">=" or "<=" symbols and the protocol
11459 name or number.
11460 Hexadecimal protocol numbers make it possible to specify protocol
11462 bounds for TLS versions that are known to OpenSSL, but might not be
11463 known to Postfix. They cannot be used with the legacy exclusion syn‐
11464 tax. Leading "0" or "0x" prefixes are supported, but not required.
11465 Therefore, "301", "0301", "0x301" and "0x0301" are all equivalent to
11466 "TLSv1". Hexadecimal versions unknown to OpenSSL will fail to set the
11467 upper or lower bound, and a warning will be logged. Hexadecimal ver‐
11468 sions should only be used when Postfix is linked with some future ver‐
11469 sion of OpenSSL that supports TLS 1.4 or later, but Postfix does not
11470 yet support a symbolic name for that protocol version.
11471 Hexadecimal example (Postfix >= 3.6):
11473 # Allow only TLS 1.2 through (hypothetical) TLS 1.4, once supported
11475 # in some future version of OpenSSL (presently a warning is logged).
11476 smtpd_tls_mandatory_protocols = >=TLSv1.2, <=0305
11477 # Allow only TLS 1.2 and up:
11478 smtpd_tls_mandatory_protocols = >=0x0303
11479 With Postfix < 3.6 there is no support for a minimum or maximum ver‐
11481 sion, and the protocol range is configured via protocol exclusions. To
11482 require at least TLS 1.0, set "smtpd_tls_mandatory_protocols = !SSLv2,
11483 !SSLv3". Listing the protocols to include, rather than protocols to
11484 exclude, is supported, but not recommended. The exclusion form more
11485 accurately matches the underlying OpenSSL interface.
11486 Support for "TLSv1.3" was introduced in OpenSSL 1.1.1. Disabling this
11488 protocol via "!TLSv1.3" is supported since Postfix 3.4 (or patch re‐
11489 leases >= 3.0.14, 3.1.10, 3.2.7 and 3.3.2).
11490 Example:
11492 # Preferred syntax with Postfix >= 3.6:
11494 smtpd_tls_mandatory_protocols = >=TLSv1.2, <=TLSv1.3
11495 # Legacy syntax:
11496 smtpd_tls_mandatory_protocols = !SSLv2, !SSLv3, !TLSv1, !TLSv1.1
11497 This feature is available in Postfix 2.3 and later.
11499
11501 TLS protocols accepted by the Postfix SMTP server with opportunistic
11502 TLS encryption. If the list is empty, the server supports all available
11503 TLS protocol versions. A non-empty value is a list of protocol names
11504 to include or exclude, separated by whitespace, commas or colons.
11505 The valid protocol names (see SSL_get_version(3)) are "SSLv2", "SSLv3",
11507 "TLSv1", "TLSv1.1", "TLSv1.2" and "TLSv1.3". Starting with Postfix
11508 3.6, the default value is ">=TLSv1", which sets TLS 1.0 as the lowest
11509 supported TLS protocol version (see below). Older releases use the "!"
11510 exclusion syntax, also described below.
11511 As of Postfix 3.6, the preferred way to limit the range of acceptable
11513 protocols is to set the lowest acceptable TLS protocol version and/or
11514 the highest acceptable TLS protocol version. To set the lower bound
11515 include an element of the form: ">=version" where version is a either
11516 one of the TLS protocol names listed above, or a hexadecimal number
11517 corresponding to the desired TLS protocol version (0301 for TLS 1.0,
11518 0302 for TLS 1.1, etc.). For the upper bound, use "<=version". There
11519 must be no whitespace between the ">=" or "<=" symbols and the protocol
11520 name or number.
11521 Hexadecimal protocol numbers make it possible to specify protocol
11523 bounds for TLS versions that are known to OpenSSL, but might not be
11524 known to Postfix. They cannot be used with the legacy exclusion syn‐
11525 tax. Leading "0" or "0x" prefixes are supported, but not required.
11526 Therefore, "301", "0301", "0x301" and "0x0301" are all equivalent to
11527 "TLSv1". Hexadecimal versions unknown to OpenSSL will fail to set the
11528 upper or lower bound, and a warning will be logged. Hexadecimal ver‐
11529 sions should only be used when Postfix is linked with some future ver‐
11530 sion of OpenSSL that supports TLS 1.4 or later, but Postfix does not
11531 yet support a symbolic name for that protocol version.
11532 Hexadecimal example (Postfix >= 3.6):
11534 # Allow only TLS 1.0 through (hypothetical) TLS 1.4, once supported
11536 # in some future version of OpenSSL (presently a warning is logged).
11537 smtpd_tls_protocols = >=TLSv1, <=0305
11538 # Allow only TLS 1.0 and up:
11539 smtpd_tls_protocols = >=0x0301
11540 With Postfix < 3.6 there is no support for a minimum or maximum ver‐
11542 sion, and the protocol range is configured via protocol exclusions. To
11543 require at least TLS 1.0, set "smtpd_tls_protocols = !SSLv2, !SSLv3".
11544 Listing the protocols to include, rather than protocols to exclude, is
11545 supported, but not recommended. The exclusion form more accurately
11546 matches the underlying OpenSSL interface.
11547 Support for "TLSv1.3" was introduced in OpenSSL 1.1.1. Disabling this
11549 protocol via "!TLSv1.3" is supported since Postfix 3.4 (or patch re‐
11550 leases >= 3.0.14, 3.1.10, 3.2.7 and 3.3.2).
11551 Example:
11553 # Preferred syntax with Postfix >= 3.6:
11554 smtpd_tls_protocols = >=TLSv1, <=TLSv1.3
11555 # Legacy syntax:
11556 smtpd_tls_protocols = !SSLv2, !SSLv3
11557 This feature is available in Postfix 2.6 and later.
11559
11561 Request that the Postfix SMTP server produces Received: message head‐
11562 ers that include information about the protocol and cipher used, as
11563 well as the remote SMTP client CommonName and client certificate issuer
11564 CommonName. This is disabled by default, as the information may be
11565 modified in transit through other mail servers. Only information that
11566 was recorded by the final destination can be trusted.
11567 This feature is available in Postfix 2.2 and later.
11569
11571 With mandatory TLS encryption, require a trusted remote SMTP client
11572 certificate in order to allow TLS connections to proceed. This option
11573 implies "smtpd_tls_ask_ccert = yes".
11574 When TLS encryption is optional, this setting is ignored with a warning
11576 written to the mail log.
11577 This feature is available in Postfix 2.2 and later.
11579
11581 The SMTP TLS security level for the Postfix SMTP server; when a
11582 non-empty value is specified, this overrides the obsolete parameters
11583 smtpd_use_tls and smtpd_enforce_tls. This parameter is ignored with
11584 "smtpd_tls_wrappermode = yes".
11585 Specify one of the following security levels:
11587 none TLS will not be used.
11589 may Opportunistic TLS: announce STARTTLS support to remote SMTP
11591 clients, but do not require that clients use TLS encryption.
11592 encrypt
11594 Mandatory TLS encryption: announce STARTTLS support to remote
11595 SMTP clients, and require that clients use TLS encryption. Ac‐
11596 cording to RFC 2487 this MUST NOT be applied in case of a pub‐
11597 licly-referenced SMTP server. Instead, this option should be
11598 used only on dedicated servers.
11599 Note 1: the "fingerprint", "verify" and "secure" levels are not sup‐
11601 ported here. The Postfix SMTP server logs a warning and uses "encrypt"
11602 instead. To verify remote SMTP client certificates, see TLS_README for
11603 a discussion of the smtpd_tls_ask_ccert, smtpd_tls_req_ccert, and per‐
11604 mit_tls_clientcerts features.
11605 Note 2: The parameter setting "smtpd_tls_security_level = encrypt" im‐
11607 plies "smtpd_tls_auth_only = yes".
11608 Note 3: when invoked via "sendmail -bs", Postfix will never offer
11610 STARTTLS due to insufficient privileges to access the server private
11611 key. This is intended behavior.
11612 This feature is available in Postfix 2.3 and later.
11614
11616 Name of the file containing the optional Postfix SMTP server TLS ses‐
11617 sion cache. Specify a database type that supports enumeration, such as
11618 btree or sdbm; there is no need to support concurrent access. The file
11619 is created if it does not exist. The smtpd(8) daemon does not use this
11620 parameter directly, rather the cache is implemented indirectly in the
11621 tlsmgr(8) daemon. This means that per-smtpd-instance master.cf over‐
11622 rides of this parameter are not effective. Note, that each of the cache
11623 databases supported by tlsmgr(8) daemon: $smtpd_tls_session_cache_data‐
11624 base, $smtp_tls_session_cache_database (and with Postfix 2.3 and later
11625 $lmtp_tls_session_cache_database), needs to be stored separately. It is
11626 not at this time possible to store multiple caches in a single data‐
11627 base.
11628 Note: dbm databases are not suitable. TLS session objects are too
11630 large.
11631 As of version 2.5, Postfix no longer uses root privileges when opening
11633 this file. The file should now be stored under the Postfix-owned
11634 data_directory. As a migration aid, an attempt to open the file under a
11635 non-Postfix directory is redirected to the Postfix-owned data_direc‐
11636 tory, and a warning is logged.
11637 As of Postfix 2.11 the preferred mechanism for session resumption is
11639 RFC 5077 TLS session tickets, which don't require server-side storage.
11640 Consequently, for Postfix >= 2.11 this parameter should generally be
11641 left empty. TLS session tickets require an OpenSSL library (at least
11642 version 0.9.8h) that provides full support for this TLS extension. See
11643 also smtpd_tls_session_cache_timeout.
11644 Example:
11646 smtpd_tls_session_cache_database = btree:/var/lib/postfix/smtpd_scache
11648 This feature is available in Postfix 2.2 and later.
11650
11652 The expiration time of Postfix SMTP server TLS session cache informa‐
11653 tion. A cache cleanup is performed periodically every $smtpd_tls_ses‐
11654 sion_cache_timeout seconds. As with $smtpd_tls_session_cache_database,
11655 this parameter is implemented in the tlsmgr(8) daemon and therefore
11656 per-smtpd-instance master.cf overrides are not possible.
11657 As of Postfix 2.11 this setting cannot exceed 100 days. If set <= 0,
11659 session caching is disabled, not just via the database, but also via
11660 RFC 5077 TLS session tickets, which don't require server-side storage.
11661 If set to a positive value less than 2 minutes, the minimum value of 2
11662 minutes is used instead. TLS session tickets require an OpenSSL li‐
11663 brary (at least version 0.9.8h) that provides full support for this TLS
11664 extension.
11665 This feature is available in Postfix 2.2 and later, and updated for TLS
11667 session ticket support in Postfix 2.11.
11668
11670 Run the Postfix SMTP server in the non-standard "wrapper" mode, instead
11671 of using the STARTTLS command.
11672 If you want to support this service, enable a special port in mas‐
11674 ter.cf, and specify "-o smtpd_tls_wrappermode=yes" on the SMTP server's
11675 command line. Port 465 (smtps) was once chosen for this purpose.
11676 This feature is available in Postfix 2.2 and later.
11678
11680 The name of the proxy protocol used by an optional before-smtpd proxy
11681 agent. When a proxy agent is used, this protocol conveys local and re‐
11682 mote address and port information. Specify "smtpd_upstream_proxy_pro‐
11683 tocol = haproxy" to enable the haproxy protocol; version 2 is supported
11684 with Postfix 3.5 and later.
11685 NOTE: To use the nginx proxy with smtpd(8), enable the XCLIENT protocol
11687 with smtpd_authorized_xclient_hosts. This supports SASL authentication
11688 in the proxy agent (Postfix 2.9 and later).
11689 This feature is available in Postfix 2.10 and later.
11691
11693 The time limit for the proxy protocol specified with the smtpd_up‐
11694 stream_proxy_protocol parameter.
11695 This feature is available in Postfix 2.10 and later.
11697
11699 Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
11700 but do not require that clients use TLS encryption.
11701 Note: when invoked via "sendmail -bs", Postfix will never offer START‐
11703 TLS due to insufficient privileges to access the server private key.
11704 This is intended behavior.
11705 This feature is available in Postfix 2.2 and later. With Postfix 2.3
11707 and later use smtpd_tls_security_level instead.
11708
11710 Detect that a message requires SMTPUTF8 support for the specified mail
11711 origin classes. This is a workaround to avoid chicken-and-egg problems
11712 during the initial SMTPUTF8 roll-out in environments with pre-existing
11713 mail flows that contain UTF8. Those mail flows should not break because
11714 Postfix suddenly refuses to deliver such mail to down-stream MTAs that
11715 don't announce SMTPUTF8 support.
11716 The problem is that Postfix cannot rely solely on the sender's declara‐
11718 tion that a message requires SMTPUTF8 support, because UTF8 may be in‐
11719 troduced during local processing (for example, the client hostname in
11720 Postfix's Received: header, adding @$myorigin or .$mydomain to an in‐
11721 complete address, address rewriting, alias expansion, automatic BCC re‐
11722 cipients, local forwarding, and changes made by header checks or Milter
11723 applications).
11724 For now, the default is to enable "SMTPUTF8 required" autodetection
11726 only for Postfix sendmail command-line submissions and address verifi‐
11727 cation probes. This may change once SMTPUTF8 support achieves world
11728 domination. However, sites that add UTF8 content via local processing
11729 (see above) should autodetect the need for SMTPUTF8 support for all
11730 email.
11731 Specify one or more of the following:
11733 sendmail
11735 Submission with the Postfix sendmail(1) command.
11736 smtpd Mail received with the smtpd(8) daemon.
11738 qmqpd Mail received with the qmqpd(8) daemon.
11740 forward
11742 Local forwarding or aliasing. When a message is received with
11743 "SMTPUTF8 required", then the forwarded (aliased) message always
11744 has "SMTPUTF8 required".
11745 bounce
11747 Submission by the bounce(8) daemon. When a message is received
11748 with "SMTPUTF8 required", then the delivery status notification
11749 always has "SMTPUTF8 required".
11750 notify
11752 Postmaster notification from the smtp(8) or smtpd(8) daemon.
11753 verify
11755 Address verification probe from the verify(8) daemon.
11756 all Enable SMTPUTF8 autodetection for all mail.
11758 This feature is available in Postfix 3.0 and later.
11760
11762 Enable preliminary SMTPUTF8 support for the protocols described in RFC
11763 6531..6533. This requires that Postfix is built to support these proto‐
11764 cols.
11765 This feature is available in Postfix 3.0 and later.
11767
11769 Safety net to keep mail queued that would otherwise be returned to the
11770 sender. This parameter disables locally-generated bounces, changes the
11771 handling of negative responses from remote servers, content filters or
11772 plugins, and prevents the Postfix SMTP server from rejecting mail per‐
11773 manently by changing 5xx reply codes into 4xx. However, soft_bounce is
11774 no cure for address rewriting mistakes or mail routing mistakes.
11775 Note: "soft_bounce = yes" is in some cases implemented by modifying
11777 server responses. Therefore, the response that Postfix logs may differ
11778 from the response that Postfix actually sends or receives.
11779 Example:
11781 soft_bounce = yes
11783
11785 The time after which a stale exclusive mailbox lockfile is removed.
11786 This is used for delivery to file or mailbox.
11787 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
11789 The default time unit is s (seconds).
11790
11792 This feature is documented in the STRESS_README document.
11793 This feature is available in Postfix 2.5 and later.
11795
11797 Reject mail with 8-bit text in message headers. This blocks mail from
11798 poorly written applications.
11799 This feature should not be enabled on a general purpose mail server,
11801 because it is likely to reject legitimate email.
11802 This feature is available in Postfix 2.0 and later.
11804
11806 Enable both strict_7bit_headers and strict_8bitmime_body.
11807 This feature should not be enabled on a general purpose mail server,
11809 because it is likely to reject legitimate email.
11810 This feature is available in Postfix 2.0 and later.
11812
11814 Reject 8-bit message body text without 8-bit MIME content encoding in‐
11815 formation. This blocks mail from poorly written applications.
11816 Unfortunately, this also rejects majordomo approval requests when the
11818 included request contains valid 8-bit MIME mail, and it rejects bounces
11819 from mailers that do not MIME encapsulate 8-bit content (for example,
11820 bounces from qmail or from old versions of Postfix).
11821 This feature should not be enabled on a general purpose mail server,
11823 because it is likely to reject legitimate email.
11824 This feature is available in Postfix 2.0 and later.
11826
11828 Defer delivery when a mailbox file is not owned by its recipient. The
11829 default setting is not backwards compatible.
11830 This feature is available in Postfix 2.5.3 and later.
11832
11834 Reject mail with invalid Content-Transfer-Encoding: information for the
11835 message/* or multipart/* MIME content types. This blocks mail from
11836 poorly written software.
11837 This feature should not be enabled on a general purpose mail server,
11839 because it will reject mail after a single violation.
11840 This feature is available in Postfix 2.0 and later.
11842
11844 Require that addresses received in SMTP MAIL FROM and RCPT TO commands
11845 are enclosed with <>, and that those addresses do not contain RFC 822
11846 style comments or phrases. This stops mail from poorly written soft‐
11847 ware.
11848 By default, the Postfix SMTP server accepts RFC 822 syntax in MAIL FROM
11850 and RCPT TO addresses.
11851
11853 Enable stricter enforcement of the SMTPUTF8 protocol. The Postfix SMTP
11854 server accepts UTF8 sender or recipient addresses only when the client
11855 requests an SMTPUTF8 mail transaction.
11856 This feature is available in Postfix 3.0 and later.
11858
11860 Obsolete SUN mailtool compatibility feature. Instead, use "mailbox_de‐
11861 livery_lock = dotlock".
11862
11864 Enable the rewriting of "site!user" into "user@site". This is neces‐
11865 sary if your machine is connected to UUCP networks. It is enabled by
11866 default.
11867 Note: with Postfix version 2.2, message header address rewriting hap‐
11869 pens only when one of the following conditions is true:
11870 • The message is received with the Postfix sendmail(1) command,
11872 • The message is received from a network client that matches $lo‐
11874 cal_header_rewrite_clients,
11875 • The message is received from the network, and the re‐
11877 mote_header_rewrite_domain parameter specifies a non-empty
11878 value.
11879 To get the behavior before Postfix version 2.2, specify "lo‐
11881 cal_header_rewrite_clients = static:all".
11882 Example:
11884 swap_bangpath = no
11886
11888 The syslog facility of Postfix logging. Specify a facility as defined
11889 in syslog.conf(5). The default facility is "mail".
11890 Warning: a non-default syslog_facility setting takes effect only after
11892 a Postfix process has completed initialization. Errors during process
11893 initialization will be logged with the default facility. Examples are
11894 errors while parsing the command line arguments, and errors while ac‐
11895 cessing the Postfix main.cf configuration file.
11896
11898 A prefix that is prepended to the process name in syslog records, so
11899 that, for example, "smtpd" becomes "prefix/smtpd".
11900 Warning: a non-default syslog_name setting takes effect only after a
11902 Postfix process has completed initialization. Errors during process
11903 initialization will be logged with the default name. Examples are er‐
11904 rors while parsing the command line arguments, and errors while access‐
11905 ing the Postfix main.cf configuration file.
11906
11908 An optional workaround for routers that break TCP window scaling.
11909 Specify a value > 0 and < 65536 to enable this feature. With Postfix
11910 TCP servers (smtpd(8), qmqpd(8)), this feature is implemented by the
11911 Postfix master(8) daemon.
11912 To change this parameter without stopping Postfix, you need to first
11914 terminate all Postfix TCP servers:
11915 # postconf -e master_service_disable=inet
11917 # postfix reload
11918 This immediately terminates all processes that accept network connec‐
11920 tions. Next, you enable Postfix TCP servers with the updated tcp_win‐
11921 dowsize setting:
11922 # postconf -e tcp_windowsize=65535 master_service_disable=
11924 # postfix reload
11925 If you skip these steps with a running Postfix system, then the
11927 tcp_windowsize change will work only for Postfix TCP clients (smtp(8),
11928 lmtp(8)).
11929 This feature is available in Postfix 2.6 and later.
11931
11933 Append the system-supplied default Certification Authority certificates
11934 to the ones specified with *_tls_CApath or *_tls_CAfile. The default
11935 is "no"; this prevents Postfix from trusting third-party certificates
11936 and giving them relay permission with permit_tls_all_clientcerts.
11937 This feature is available in Postfix 2.4.15, 2.5.11, 2.6.8, 2.7.2 and
11939 later versions. Specify "tls_append_default_CA = yes" for backwards
11940 compatibility, to avoid breaking certificate verification with sites
11941 that don't use permit_tls_all_clientcerts.
11942
11944 The number of pseudo-random bytes that an smtp(8) or smtpd(8) process
11945 requests from the tlsmgr(8) server in order to seed its internal pseudo
11946 random number generator (PRNG). The default of 32 bytes (equivalent to
11947 256 bits) is sufficient to generate a 128bit (or 168bit) session key.
11948 This feature is available in Postfix 2.2 and later.
11950
11952 Configure RFC7671 DANE TLSA digest algorithm agility. Do not change
11953 this setting from its default value.
11954 See Section 8 of RFC7671 for correct key rotation procedures.
11956 This feature is available in Postfix 2.11 through 3.1. Postfix 3.2 and
11958 later ignore this configuration parameter and behave as though it were
11959 set to "on".
11960
11962 DANE TLSA (RFC 6698, RFC 7671, RFC 7672) resource-record "matching
11963 type" digest algorithms in descending preference order. All the speci‐
11964 fied algorithms must be supported by the underlying OpenSSL library,
11965 otherwise the Postfix SMTP client will not support DANE TLSA security.
11966 Specify a list of digest names separated by commas and/or whitespace.
11968 Each digest name may be followed by an optional "=<number>" suffix.
11969 For example, "sha512" may instead be specified as "sha512=2" and
11970 "sha256" may instead be specified as "sha256=1". The optional number
11971 must match the <a href="https://www.iana.org/assignments/dane-parame‐
11972 ters/dane-parameters.xhtml#matching-types" >IANA assigned TLSA matching
11973 type number the algorithm in question. Postfix will check this con‐
11974 straint for the algorithms it knows about. Additional matching type
11975 algorithms registered with IANA can be added with explicit numbers pro‐
11976 vided they are supported by OpenSSL.
11977 Invalid list elements are logged with a warning and disable DANE sup‐
11979 port. TLSA RRs that specify digests not included in the list are ig‐
11980 nored with a warning.
11981 Note: It is unwise to omit sha256 from the digest list. This digest
11983 algorithm is the only mandatory to implement digest algorithm in RFC
11984 6698, and many servers are expected publish TLSA records with just
11985 sha256 digests. Unless one of the standard digests is seriously com‐
11986 promised and servers have had ample time to update their TLSA records
11987 you should not omit any standard digests, just arrange them in order
11988 from strongest to weakest.
11989 This feature is available in Postfix 2.11 and later.
11991
11993 Enable support for RFC 6698 (DANE TLSA) DNS records that contain di‐
11994 gests of trust-anchors with certificate usage "2". Do not change this
11995 setting from its default value.
11996 This feature is available in Postfix 2.11 through 3.1. It has been
11998 withdrawn in Postfix 3.2, as trust-anchor TLSA records are now widely
11999 used and have proved sufficiently reliable. Postfix 3.2 and later ig‐
12000 nore this configuration parameter and behaves as though it were set to
12001 "yes".
12002
12004 List or bit-mask of OpenSSL bug work-arounds to disable.
12005 The OpenSSL toolkit includes a set of work-arounds for buggy SSL/TLS
12007 implementations. Applications, such as Postfix, that want to maximize
12008 interoperability ask the OpenSSL library to enable the full set of rec‐
12009 ommended work-arounds.
12010 From time to time, it is discovered that a work-around creates a secu‐
12012 rity issue, and should no longer be used. If upgrading OpenSSL to a
12013 fixed version is not an option or an upgrade is not available in a
12014 timely manner, or in closed environments where no buggy clients or
12015 servers exist, it may be appropriate to disable some or all of the
12016 OpenSSL interoperability work-arounds. This parameter specifies which
12017 bug work-arounds to disable.
12018 If the value of the parameter is a hexadecimal long integer starting
12020 with "0x", the bug work-arounds corresponding to the bits specified in
12021 its value are removed from the SSL_OP_ALL work-around bit-mask (see
12022 openssl/ssl.h and SSL_CTX_set_options(3)). You can specify more bits
12023 than are present in SSL_OP_ALL, excess bits are ignored. Specifying
12024 0xFFFFFFFF disables all bug-workarounds on a 32-bit system. This should
12025 also be sufficient on 64-bit systems, until OpenSSL abandons support
12026 for 32-bit systems and starts using the high 32 bits of a 64-bit
12027 bug-workaround mask.
12028 Otherwise, the parameter is a white-space or comma separated list of
12030 specific named bug work-arounds chosen from the list below. It is pos‐
12031 sible that your OpenSSL version includes new bug work-arounds added af‐
12032 ter your Postfix source code was last updated, in that case you can
12033 only disable one of these via the hexadecimal syntax above.
12034 CRYPTOPRO_TLSEXT_BUG
12036 New with GOST support in OpenSSL 1.0.0.
12037 DONT_INSERT_EMPTY_FRAGMENTS
12039 See SSL_CTX_set_options(3)
12040 LEGACY_SERVER_CONNECT
12042 See SSL_CTX_set_options(3)
12043 MICROSOFT_BIG_SSLV3_BUFFER
12045 See SSL_CTX_set_options(3)
12046 MICROSOFT_SESS_ID_BUG
12048 See SSL_CTX_set_options(3)
12049 MSIE_SSLV2_RSA_PADDING
12051 also aliased as CVE-2005-2969. Postfix 2.8 disables this
12052 work-around by default with OpenSSL versions that may predate
12053 the fix. Fixed in OpenSSL 0.9.7h and OpenSSL 0.9.8a.
12054 NETSCAPE_CHALLENGE_BUG
12056 See SSL_CTX_set_options(3)
12057 NETSCAPE_REUSE_CIPHER_CHANGE_BUG
12059 also aliased as CVE-2010-4180. Postfix 2.8 disables this
12060 work-around by default with OpenSSL versions that may predate
12061 the fix. Fixed in OpenSSL 0.9.8q and OpenSSL 1.0.0c.
12062 SSLEAY_080_CLIENT_DH_BUG
12064 See SSL_CTX_set_options(3)
12065 SSLREF2_REUSE_CERT_TYPE_BUG
12067 See SSL_CTX_set_options(3)
12068 TLS_BLOCK_PADDING_BUG
12070 See SSL_CTX_set_options(3)
12071 TLS_D5_BUG
12073 See SSL_CTX_set_options(3)
12074 TLS_ROLLBACK_BUG
12076 See SSL_CTX_set_options(3). This is disabled in OpenSSL 0.9.7
12077 and later. Nobody should still be using 0.9.6!
12078 TLSEXT_PADDING
12080 Postfix >= 3.4. See SSL_CTX_set_options(3).
12081 This feature is available in Postfix 2.8 and later.
12083
12085 The prioritized list of elliptic curves supported by the Postfix SMTP
12086 client and server. These curves are used by the Postfix SMTP server
12087 when "smtpd_tls_eecdh_grade = auto". The selected curves must be im‐
12088 plemented by OpenSSL and be standardized for use in TLS (RFC 4492 or
12089 its imminent successor). It is unwise to list only "bleeding-edge"
12090 curves supported by a small subset of clients. The default list is
12091 suitable for most users.
12092 Postfix skips curve names that are unknown to OpenSSL, or that are
12094 known but not yet implemented. This makes it possible to "anticipate"
12095 support for curves that should be used once they become available. In
12096 particular, in some OpenSSL versions, the new RFC 8031 curves "X25519"
12097 and "X448" may be known by name, but ECDH support for either or both
12098 may be missing. These curves may appear in the default value of this
12099 parameter, even though they'll only be usable with later versions of
12100 OpenSSL.
12101 This feature is available in Postfix 3.2 and later, when it is compiled
12103 and linked with OpenSSL 1.0.2 or later on platforms where EC algorithms
12104 have not been disabled by the vendor.
12105
12107 The elliptic curve used by the Postfix SMTP server for sensibly strong
12108 ephemeral ECDH key exchange. This curve is used by the Postfix SMTP
12109 server when "smtpd_tls_eecdh_grade = strong". The phrase "sensibly
12110 strong" means approximately 128-bit security based on best known at‐
12111 tacks. The selected curve must be implemented by OpenSSL (as reported
12112 by ecparam(1) with the "-list_curves" option) and be one of the curves
12113 listed in Section 5.1.1 of RFC 4492. You should not generally change
12114 this setting. Remote SMTP client implementations must support this
12115 curve for EECDH key exchange to take place. It is unwise to choose an
12116 "bleeding-edge" curve supported by only a small subset of clients.
12117 The default "strong" curve is rated in NSA Suite B for information
12119 classified up to SECRET.
12120 Note: elliptic curve names are poorly standardized; different standards
12122 groups are assigning different names to the same underlying curves.
12123 The curve with the X9.62 name "prime256v1" is also known under the SECG
12124 name "secp256r1", but OpenSSL does not recognize the latter name.
12125 If you want to take maximal advantage of ciphers that offer forward se‐
12127 crecy see the Getting started section of FORWARD_SECRECY_README. The
12128 full document conveniently presents all information about Postfix "per‐
12129 fect" forward secrecy support in one place: what forward secrecy is,
12130 how to tweak settings, and what you can expect to see when Postfix uses
12131 ciphers with forward secrecy.
12132 This feature is available in Postfix 2.6 and later, when it is compiled
12134 and linked with OpenSSL 1.0.0 or later on platforms where EC algorithms
12135 have not been disabled by the vendor.
12136
12138 The elliptic curve used by the Postfix SMTP server for maximally strong
12139 ephemeral ECDH key exchange. This curve is used by the Postfix SMTP
12140 server when "smtpd_tls_eecdh_grade = ultra". The phrase "maximally
12141 strong" means approximately 192-bit security based on best known at‐
12142 tacks. This additional strength comes at a significant computational
12143 cost, most users should instead set "smtpd_tls_eecdh_grade = strong".
12144 The selected curve must be implemented by OpenSSL (as reported by ec‐
12145 param(1) with the "-list_curves" option) and be one of the curves
12146 listed in Section 5.1.1 of RFC 4492. You should not generally change
12147 this setting.
12148 This default "ultra" curve is rated in NSA Suite B for information
12150 classified up to TOP SECRET.
12151 If you want to take maximal advantage of ciphers that offer forward se‐
12153 crecy see the Getting started section of FORWARD_SECRECY_README. The
12154 full document conveniently presents all information about Postfix "per‐
12155 fect" forward secrecy support in one place: what forward secrecy is,
12156 how to tweak settings, and what you can expect to see when Postfix uses
12157 ciphers with forward secrecy.
12158 This feature is available in Postfix 2.6 and later, when it is compiled
12160 and linked with OpenSSL 1.0.0 or later on platforms where EC algorithms
12161 have not been disabled by the vendor.
12162
12164 The OpenSSL cipherlist for "export" or higher grade ciphers. This de‐
12165 fines the meaning of the "export" setting in smtpd_tls_ciphers,
12166 smtpd_tls_mandatory_ciphers, smtp_tls_ciphers, smtp_tls_mandatory_ci‐
12167 phers, lmtp_tls_ciphers, and lmtp_tls_mandatory_ciphers. With Postfix
12168 releases before the middle of 2015 this is the default cipherlist for
12169 the opportunistic ("may") TLS client security level and also the de‐
12170 fault cipherlist for the SMTP server. You are strongly encouraged to
12171 not change this setting.
12172 This feature is available in Postfix 2.3 and later.
12174
12176 A workaround for implementations that hang Postfix while shutting down
12177 a TLS session, until Postfix times out. With this enabled, Postfix will
12178 not wait for the remote TLS peer to respond to a TLS later.
12179
12181 The OpenSSL cipherlist for "high" grade ciphers. This defines the mean‐
12182 ing of the "high" setting in smtpd_tls_ciphers, smtpd_tls_mandatory_ci‐
12183 phers, smtp_tls_ciphers, smtp_tls_mandatory_ciphers, lmtp_tls_ciphers,
12184 and lmtp_tls_mandatory_ciphers. You are strongly encouraged to not
12185 change this setting.
12186 This feature is available in Postfix 2.3 and later.
12188
12190 A temporary migration aid for sites that use certificate public-key
12191 fingerprints with Postfix 2.9.0..2.9.5, which use an incorrect algo‐
12192 rithm. This parameter has no effect on the certificate fingerprint sup‐
12193 port that is available since Postfix 2.2.
12194 Specify "tls_legacy_public_key_fingerprints = yes" temporarily, pending
12196 a migration from configuration files with incorrect Postfix
12197 2.9.0..2.9.5 certificate public-key finger prints, to the correct fin‐
12198 gerprints used by Postfix 2.9.6 and later. To compute the correct cer‐
12199 tificate public-key fingerprints, see TLS_README.
12200 This feature is available in Postfix 2.9.6 and later.
12202
12204 The OpenSSL cipherlist for "low" or higher grade ciphers. This defines
12205 the meaning of the "low" setting in smtpd_tls_ciphers, smtpd_tls_manda‐
12206 tory_ciphers, smtp_tls_ciphers, smtp_tls_mandatory_ciphers,
12207 lmtp_tls_ciphers, and lmtp_tls_mandatory_ciphers. You are strongly en‐
12208 couraged to not change this setting.
12209 This feature is available in Postfix 2.3 and later.
12211
12213 The OpenSSL cipherlist for "medium" or higher grade ciphers. This de‐
12214 fines the meaning of the "medium" setting in smtpd_tls_ciphers,
12215 smtpd_tls_mandatory_ciphers, smtp_tls_ciphers, smtp_tls_mandatory_ci‐
12216 phers, lmtp_tls_ciphers, and lmtp_tls_mandatory_ciphers. This is the
12217 default cipherlist for mandatory TLS encryption in the TLS client (with
12218 anonymous ciphers disabled when verifying server certificates). This
12219 is the default cipherlist for opportunistic TLS with Postfix releases
12220 after the middle of 2015. You are strongly encouraged to not change
12221 this setting.
12222 This feature is available in Postfix 2.3 and later.
12224
12226 The OpenSSL cipherlist for "NULL" grade ciphers that provide authenti‐
12227 cation without encryption. This defines the meaning of the "null" set‐
12228 ting in smtpd_mandatory_tls_ciphers, smtp_tls_mandatory_ciphers and
12229 lmtp_tls_mandatory_ciphers. You are strongly encouraged to not change
12230 this setting.
12231 This feature is available in Postfix 2.3 and later.
12233
12235 With SSLv3 and later, use the Postfix SMTP server's cipher preference
12236 order instead of the remote client's cipher preference order.
12237 By default, the OpenSSL server selects the client's most preferred ci‐
12239 pher that the server supports. With SSLv3 and later, the server may
12240 choose its own most preferred cipher that is supported (offered) by the
12241 client. Setting "tls_preempt_cipherlist = yes" enables server cipher
12242 preferences.
12243 While server cipher selection may in some cases lead to a more secure
12245 or performant cipher choice, there is some risk of interoperability is‐
12246 sues. In the past, some SSL clients have listed lower priority ciphers
12247 that they did not implement correctly. If the server chooses a cipher
12248 that the client prefers less, it may select a cipher whose client im‐
12249 plementation is flawed. Most notably Windows 2003 Microsoft Exchange
12250 servers have flawed implementations of DES-CBC3-SHA, which OpenSSL con‐
12251 siders stronger than RC4-SHA. Enabling server cipher-suite selection
12252 may create interoperability issues with Windows 2003 Microsoft Exchange
12253 clients.
12254 This feature is available in Postfix 2.8 and later, in combination with
12256 OpenSSL 0.9.7 and later.
12257
12259 The number of bytes that tlsmgr(8) reads from $tls_random_source when
12260 (re)seeding the in-memory pseudo random number generator (PRNG) pool.
12261 The default of 32 bytes (256 bits) is good enough for 128bit symmetric
12262 keys. If using EGD or a device file, a maximum of 255 bytes is read.
12263 This feature is available in Postfix 2.2 and later.
12265
12267 Name of the pseudo random number generator (PRNG) state file that is
12268 maintained by tlsmgr(8). The file is created when it does not exist,
12269 and its length is fixed at 1024 bytes.
12270 As of version 2.5, Postfix no longer uses root privileges when opening
12272 this file, and the default file location was changed from ${config_di‐
12273 rectory}/prng_exch to ${data_directory}/prng_exch. As a migration aid,
12274 an attempt to open the file under a non-Postfix directory is redirected
12275 to the Postfix-owned data_directory, and a warning is logged.
12276 This feature is available in Postfix 2.2 and later.
12278
12280 The time between attempts by tlsmgr(8) to save the state of the pseudo
12281 random number generator (PRNG) to the file specified with $tls_ran‐
12282 dom_exchange_name.
12283 This feature is available in Postfix 2.2 and later.
12285
12287 The maximal time between attempts by tlsmgr(8) to re-seed the in-memory
12288 pseudo random number generator (PRNG) pool from external sources. The
12289 actual time between re-seeding attempts is calculated using the PRNG,
12290 and is between 0 and the time specified.
12291 This feature is available in Postfix 2.2 and later.
12293
12295 The external entropy source for the in-memory tlsmgr(8) pseudo random
12296 number generator (PRNG) pool. Be sure to specify a non-blocking source.
12297 If this source is not a regular file, the entropy source type must be
12298 prepended: egd:/path/to/egd_socket for a source with EGD compatible
12299 socket interface, or dev:/path/to/device for a device file.
12300 Note: on OpenBSD systems specify /dev/arandom when /dev/urandom gives
12302 timeout errors.
12303 This feature is available in Postfix 2.2 and later.
12305
12307 Optional lookup tables that map names received from remote SMTP clients
12308 via the TLS Server Name Indication (SNI) extension to the appropriate
12309 keys and certificate chains. This parameter is implemented in the
12310 Postfix TLS library, and applies to both smtpd(8) and the SMTP server
12311 mode of tlsproxy(8).
12312 When this parameter is non-empty, the Postfix SMTP server enables SNI
12314 extension processing, and logs SNI values that are invalid or don't
12315 match an entry in the the specified tables. When an entry does match,
12316 the SNI name is logged as part of the connection summary at log levels
12317 1 and higher.
12318 The lookup key is either the verbatim SNI domain name or an ancestor
12320 domain prefixed with a leading dot. For internationalized domains, the
12321 lookup key must be in IDNA 2008 A-label form (as required in the TLS
12322 SNI extension).
12323 The syntax of the lookup value is the same as with the
12325 smtp_tls_chain_files parameter (see there for additional details), but
12326 here scoped to just TLS connections in which the client sends a match‐
12327 ing SNI domain name.
12328 Example:
12330 /etc/postfix/main.cf:
12332 #
12333 # The indexed SNI table must be created with "postmap -F"
12334 #
12335 indexed = ${default_database_type}:${config_directory}/
12336 tls_server_sni_maps = ${indexed}sni
12337 /etc/postfix/sni:
12339 #
12340 # The example.com domain has both an RSA and ECDSA certificate
12341 # chain. The chain files MUST start with the private key,
12342 # with the certificate chain next, starting with the leaf
12343 # (server) certificate, and then the issuer certificates.
12344 #
12345 example.com /etc/postfix/sni-chains/rsa2048.example.com.pem,
12346 /etc/postfix/sni-chains/ecdsa-p256.example.com.pem
12347 #
12348 # The example.net domain has a wildcard certificate, and two
12349 # additional DNS names. So its certificate chain is also used
12350 # with any subdomain, plus the additional names.
12351 #
12352 example.net /etc/postfix/sni-chains/example.net.pem
12353 .example.net /etc/postfix/sni-chains/example.net.pem
12354 example.info /etc/postfix/sni-chains/example.net.pem
12355 example.org /etc/postfix/sni-chains/example.net.pem
12356 Note that the SNI lookup tables should also have entries for the do‐
12358 mains that correspond to the Postfix SMTP server's default certifi‐
12359 cate(s). This ensures that the remote SMTP client's TLS SNI extension
12360 gets a positive response when it specifies one of the Postfix SMTP
12361 server's default domains, and ensures that the Postfix SMTP server will
12362 not log an SNI name mismatch for such a domain. The Postfix SMTP
12363 server's default certificates are then only used when the client sends
12364 no SNI or when it sends SNI with a domain that the server knows no cer‐
12365 tificate(s) for.
12366 The mapping from an SNI domain name to a certificate chain is indirect.
12368 In the input source files for "cdb", "hash", "btree" or other tables
12369 that are converted to on-disk indexed files via postmap(1), the value
12370 specified for each key is a list of filenames. When postmap(1) is used
12371 with the -F option, the generated table stores for each lookup key the
12372 base64-encoded contents of the associated files. When querying tables
12373 via postmap -Fq, the table value is decoded from base64, yielding the
12374 original file content, plus a new line.
12375 With "regexp", "pcre", "inline", "texthash", "static" and similar ta‐
12377 bles that are interpreted at run-time, and don't have a separate source
12378 format, the table value is again a list files, that are loaded into
12379 memory when the table is opened.
12380 With tables whose content is managed outside of Postfix, such as LDAP,
12382 MySQL, PostgreSQL, socketmap and tcp, the value must be a concatenation
12383 of the desired PEM keys and certificate chains, that is then further
12384 encoded to yield a single-line base64 string. Creation of such tables
12385 and secure storage (the value includes private key material) are out‐
12386 side the responsibility of Postfix.
12387 With "socketmap" and "tcp" the data will be transmitted in the clear,
12389 and there is no query access control, so these are generally unsuitable
12390 for storing SNI chains. With LDAP and SQL, you should restrict read
12391 access and use TLS to protect the sensitive data in transit.
12392 Typically there is only one private key and its chain of certificates
12394 starting with the "leaf" certificate corresponding to that key, and
12395 continuing with the appropriate intermediate issuer CA certificates,
12396 with each certificate ideally followed by its issuer. Servers that
12397 have keys and certificates for more than one algorithm (e.g. both an
12398 RSA key and an ECDSA key, or even RSA, ECDSA and Ed25519) can use mul‐
12399 tiple chains concatenated together, with the key always listed before
12400 the corresponding certificates.
12401 This feature is available in Postfix 3.4 and later.
12403
12405 3.0: aes-128-cbc)
12406 Algorithm used to encrypt RFC5077 TLS session tickets. This algorithm
12407 must use CBC mode, have a 128-bit block size, and must have a key
12408 length between 128 and 256 bits. The default is aes-256-cbc. Overrid‐
12409 ing the default to choose a different algorithm is discouraged.
12410 Setting this parameter empty disables session ticket support in the
12412 Postfix SMTP server. Another way to disable session ticket support is
12413 via the tls_ssl_options parameter.
12414 This feature is available in Postfix 3.0 and later.
12416
12418 List or bit-mask of OpenSSL options to enable.
12419 The OpenSSL toolkit provides a set of options that applications can en‐
12421 able to tune the OpenSSL behavior. Some of these work around bugs in
12422 other implementations and are on by default. You can use the tls_dis‐
12423 able_workarounds parameter to selectively disable some or all of the
12424 bug work-arounds, making OpenSSL more strict at the cost of non-inter‐
12425 operability with SSL clients or servers that exhibit the bugs.
12426 Other options are off by default, and typically enable or disable fea‐
12428 tures rather than bug work-arounds. These may be turned on (with care)
12429 via the tls_ssl_options parameter. The value is a white-space or comma
12430 separated list of named options chosen from the list below. The names
12431 are not case-sensitive, you can use lower-case if you prefer. The up‐
12432 per case values below match the corresponding macro name in the ssl.h
12433 header file with the SSL_OP_ prefix removed. It is possible that your
12434 OpenSSL version includes new options added after your Postfix source
12435 code was last updated, in that case you can only enable one of these
12436 via the hexadecimal syntax below.
12437 You should only enable features via the hexadecimal mask when the need
12439 to control the feature is critical (to deal with a new vulnerability or
12440 a serious interoperability problem). Postfix DOES NOT promise back‐
12441 wards compatible behavior with respect to the mask bits. A feature en‐
12442 abled via the mask in one release may be enabled by other means in a
12443 later release, and the mask bit will then be ignored. Therefore, use
12444 of the hexadecimal mask is only a temporary measure until a new Postfix
12445 or OpenSSL release provides a better solution.
12446 If the value of the parameter is a hexadecimal long integer starting
12448 with "0x", the options corresponding to the bits specified in its value
12449 are enabled (see openssl/ssl.h and SSL_CTX_set_options(3)). You can
12450 only enable options not already controlled by other Postfix settings.
12451 For example, you cannot disable protocols or enable server cipher pref‐
12452 erence. Do not attempt to turn all features by specifying 0xFFFFFFFF,
12453 this is unlikely to be a good idea. Some bug work-arounds are also
12454 valid here, allowing them to be re-enabled if/when they're no longer
12455 enabled by default. The supported values include:
12456 ENABLE_MIDDLEBOX_COMPAT
12458 Postfix >= 3.4. See SSL_CTX_set_options(3).
12459 LEGACY_SERVER_CONNECT
12461 See SSL_CTX_set_options(3).
12462 NO_TICKET
12464 Enabled by default when needed in fully-patched Postfix >= 2.7.
12465 Not needed at all for Postfix >= 2.11, unless for some reason
12466 you do not want to support TLS session resumption. Best not set
12467 explicitly. See SSL_CTX_set_options(3).
12468 NO_COMPRESSION
12470 Disable SSL compression even if supported by the OpenSSL li‐
12471 brary. Compression is CPU-intensive, and compression before en‐
12472 cryption does not always improve security.
12473 NO_RENEGOTIATION
12475 Postfix >= 3.4. This can reduce opportunities for a potential
12476 CPU exhaustion attack. See SSL_CTX_set_options(3).
12477 NO_SESSION_RESUMPTION_ON_RENEGOTIATION
12479 Postfix >= 3.4. See SSL_CTX_set_options(3).
12480 PRIORITIZE_CHACHA
12482 Postfix >= 3.4. See SSL_CTX_set_options(3).
12483 This feature is available in Postfix 2.11 and later.
12485
12487 Match multiple DNS labels with "*" in wildcard certificates.
12488 Some mail service providers prepend the customer domain name to a base
12490 domain for which they have a wildcard TLS certificate. For example,
12491 the MX records for example.com hosted by example.net may be:
12492 example.com. IN MX 0 example.com.mx1.example.net.
12494 example.com. IN MX 0 example.com.mx2.example.net.
12495 and the TLS certificate may be for "*.example.net". The "*" then corre‐
12497 sponds with multiple labels in the mail server domain name. While
12498 multi-label wildcards are not widely supported, and are not blessed by
12499 any standard, there is little to be gained by disallowing their use in
12500 this context.
12501 Notes:
12503 • In a certificate name, the "*" is special only when it is used
12505 as the first label.
12506 • While Postfix (2.11 or later) can match "*" with multiple domain
12508 name labels, other implementations likely will not.
12509 • Earlier Postfix implementations behave as if "tls_wild‐
12511 card_matches_multiple_labels = no".
12512 This feature is available in Postfix 2.11 and later.
12514
12516 The name of the tlsmgr(8) service entry in master.cf. This service
12517 maintains TLS session caches and other information in support of TLS.
12518 This feature is available in Postfix 2.11 and later.
12520
12522 A file containing CA certificates of root CAs trusted to sign either
12523 remote TLS server certificates or intermediate CA certificates. See
12524 smtp_tls_CAfile for further details.
12525 This feature is available in Postfix 3.4 and later.
12527
12529 Directory with PEM format Certification Authority certificates that the
12530 Postfix tlsproxy(8) client uses to verify a remote TLS server certifi‐
12531 cate. See smtp_tls_CApath for further details.
12532 This feature is available in Postfix 3.4 and later.
12534
12536 File with the Postfix tlsproxy(8) client RSA certificate in PEM format.
12537 See smtp_tls_cert_file for further details. The preferred way to con‐
12538 figure tlsproxy client keys and certificates is via the "tl‐
12539 sproxy_client_chain_files" parameter.
12540 This feature is available in Postfix 3.4 and later.
12542
12544 Files with the Postfix tlsproxy(8) client keys and certificate chains
12545 in PEM format. See smtp_tls_chain_files for further details.
12546 This feature is available in Postfix 3.4 and later.
12548
12550 File with the Postfix tlsproxy(8) client DSA certificate in PEM format.
12551 See smtp_tls_dcert_file for further details. DSA is obsolete and should
12552 not be used.
12553 This feature is available in Postfix 3.4 and later.
12555
12557 File with the Postfix tlsproxy(8) client DSA private key in PEM format.
12558 See smtp_tls_dkey_file for further details. DSA is obsolete and should
12559 not be used.
12560 This feature is available in Postfix 3.4 and later.
12562
12564 File with the Postfix tlsproxy(8) client ECDSA certificate in PEM for‐
12565 mat. See smtp_tls_eccert_file for further details. The preferred way to
12566 configure tlsproxy client keys and certificates is via the "tl‐
12567 sproxy_client_chain_files" parameter.
12568 This feature is available in Postfix 3.4 and later.
12570
12572 File with the Postfix tlsproxy(8) client ECDSA private key in PEM for‐
12573 mat. See smtp_tls_eckey_file for further details. The preferred way to
12574 configure tlsproxy client keys and certificates is via the "tl‐
12575 sproxy_client_chain_files" parameter.
12576 This feature is available in Postfix 3.4 and later.
12578
12580 Enforcement mode: require that SMTP servers use TLS encryption. See
12581 smtp_enforce_tls for further details.
12582 This feature is available in Postfix 3.4 and later.
12584
12586 The message digest algorithm used to construct remote TLS server cer‐
12587 tificate fingerprints. See smtp_tls_fingerprint_digest for further de‐
12588 tails.
12589 This feature is available in Postfix 3.4 and later.
12591
12593 File with the Postfix tlsproxy(8) client RSA private key in PEM format.
12594 See smtp_tls_key_file for further details. The preferred way to config‐
12595 ure tlsproxy client keys and certificates is via the "tl‐
12596 sproxy_client_chain_files" parameter.
12597 This feature is available in Postfix 3.4 and later.
12599
12601 Enable additional Postfix tlsproxy(8) client logging of TLS activity.
12602 See smtp_tls_loglevel for further details.
12603 This feature is available in Postfix 3.4 and later.
12605
12607 The name of the parameter that provides the tlsproxy_client_loglevel
12608 value.
12609 This feature is available in Postfix 3.4 and later.
12611
12613 Optional lookup tables with the Postfix tlsproxy(8) client TLS usage
12614 policy by next-hop destination and by remote TLS server hostname. See
12615 smtp_tls_per_site for further details.
12616 This feature is available in Postfix 3.4 and later.
12618
12620 Optional lookup tables with the Postfix tlsproxy(8) client TLS security
12621 policy by next-hop destination. See smtp_tls_policy_maps for further
12622 details.
12623 This feature is available in Postfix 3.4 and later.
12625
12627 The verification depth for remote TLS server certificates. See
12628 smtp_tls_scert_verifydepth for further details.
12629 This feature is available in Postfix 3.4 and later.
12631
12633 The default TLS security level for the Postfix tlsproxy(8) client. See
12634 smtp_tls_security_level for further details.
12635 This feature is available in Postfix 3.4 and later.
12637
12639 Opportunistic mode: use TLS when a remote server announces TLS support.
12640 See smtp_use_tls for further details.
12641 This feature is available in Postfix 3.4 and later.
12643
12645 Mandatory TLS: announce STARTTLS support to remote SMTP clients, and
12646 require that clients use TLS encryption. See smtpd_enforce_tls for fur‐
12647 ther details.
12648 This feature is available in Postfix 2.8 and later.
12650
12652 The name of the tlsproxy(8) service entry in master.cf. This service
12653 performs plaintext <=> TLS ciphertext conversion.
12654 This feature is available in Postfix 2.8 and later.
12656
12658 A file containing (PEM format) CA certificates of root CAs trusted to
12659 sign either remote SMTP client certificates or intermediate CA certifi‐
12660 cates. See smtpd_tls_CAfile for further details.
12661 This feature is available in Postfix 2.8 and later.
12663
12665 A directory containing (PEM format) CA certificates of root CAs trusted
12666 to sign either remote SMTP client certificates or intermediate CA cer‐
12667 tificates. See smtpd_tls_CApath for further details.
12668 This feature is available in Postfix 2.8 and later.
12670
12672 sion_ids)
12673 Force the Postfix tlsproxy(8) server to issue a TLS session id, even
12674 when TLS session caching is turned off. See smtpd_tls_always_issue_ses‐
12675 sion_ids for further details.
12676 This feature is available in Postfix 2.8 and later.
12678
12680 Ask a remote SMTP client for a client certificate. See
12681 smtpd_tls_ask_ccert for further details.
12682 This feature is available in Postfix 2.8 and later.
12684
12686 The verification depth for remote SMTP client certificates. A depth of
12687 1 is sufficient if the issuing CA is listed in a local CA file. See
12688 smtpd_tls_ccert_verifydepth for further details.
12689 This feature is available in Postfix 2.8 and later.
12691
12693 File with the Postfix tlsproxy(8) server RSA certificate in PEM format.
12694 This file may also contain the Postfix tlsproxy(8) server private RSA
12695 key. See smtpd_tls_cert_file for further details. With Postfix >= 3.4
12696 the preferred way to configure tlsproxy server keys and certificates is
12697 via the "tlsproxy_tls_chain_files" parameter.
12698 This feature is available in Postfix 2.8 and later.
12700
12702 Files with the Postfix tlsproxy(8) server keys and certificate chains
12703 in PEM format. See smtpd_tls_chain_files for further details.
12704 This feature is available in Postfix 3.4 and later.
12706
12708 The minimum TLS cipher grade that the Postfix tlsproxy(8) server will
12709 use with opportunistic TLS encryption. See smtpd_tls_ciphers for fur‐
12710 ther details.
12711 This feature is available in Postfix 2.8 and later.
12713
12715 File with the Postfix tlsproxy(8) server DSA certificate in PEM format.
12716 This file may also contain the Postfix tlsproxy(8) server private DSA
12717 key. DSA is obsolete and should not be used. See smtpd_tls_dcert_file
12718 for further details.
12719 This feature is available in Postfix 2.8 and later.
12721
12723 File with DH parameters that the Postfix tlsproxy(8) server should use
12724 with non-export EDH ciphers. See smtpd_tls_dh1024_param_file for fur‐
12725 ther details.
12726 This feature is available in Postfix 2.8 and later.
12728
12730 File with DH parameters that the Postfix tlsproxy(8) server should use
12731 with export-grade EDH ciphers. See smtpd_tls_dh512_param_file for fur‐
12732 ther details. The default SMTP server cipher grade is "medium" with
12733 Postfix releases after the middle of 2015, and as a result export-grade
12734 cipher suites are by default not used.
12735 With Postfix >= 3.6 export-grade Diffie-Hellman key exchange is no
12737 longer supported, and this parameter is silently ignored.
12738 This feature is available in Postfix 2.8 and later.
12740
12742 File with the Postfix tlsproxy(8) server DSA private key in PEM format.
12743 This file may be combined with the Postfix tlsproxy(8) server DSA cer‐
12744 tificate file specified with $smtpd_tls_dcert_file. DSA is obsolete
12745 and should not be used. See smtpd_tls_dkey_file for further details.
12746 This feature is available in Postfix 2.8 and later.
12748
12750 File with the Postfix tlsproxy(8) server ECDSA certificate in PEM for‐
12751 mat. This file may also contain the Postfix tlsproxy(8) server private
12752 ECDSA key. See smtpd_tls_eccert_file for further details. With Post‐
12753 fix >= 3.4 the preferred way to configure tlsproxy server keys and cer‐
12754 tificates is via the "tlsproxy_tls_chain_files" parameter.
12755 This feature is available in Postfix 2.8 and later.
12757
12759 File with the Postfix tlsproxy(8) server ECDSA private key in PEM for‐
12760 mat. This file may be combined with the Postfix tlsproxy(8) server
12761 ECDSA certificate file specified with $smtpd_tls_eccert_file. See
12762 smtpd_tls_eckey_file for further details. With Postfix >= 3.4 the pre‐
12763 ferred way to configure tlsproxy server keys and certificates is via
12764 the "tlsproxy_tls_chain_files" parameter.
12765 This feature is available in Postfix 2.8 and later.
12767
12769 The Postfix tlsproxy(8) server security grade for ephemeral ellip‐
12770 tic-curve Diffie-Hellman (EECDH) key exchange. See
12771 smtpd_tls_eecdh_grade for further details.
12772 This feature is available in Postfix 2.8 and later.
12774
12776 List of ciphers or cipher types to exclude from the tlsproxy(8) server
12777 cipher list at all TLS security levels. See smtpd_tls_exclude_ciphers
12778 for further details.
12779 This feature is available in Postfix 2.8 and later.
12781
12783 The message digest algorithm to construct remote SMTP client-certifi‐
12784 cate fingerprints. See smtpd_tls_fingerprint_digest for further de‐
12785 tails.
12786 This feature is available in Postfix 2.8 and later.
12788
12790 File with the Postfix tlsproxy(8) server RSA private key in PEM format.
12791 This file may be combined with the Postfix tlsproxy(8) server RSA cer‐
12792 tificate file specified with $smtpd_tls_cert_file. See
12793 smtpd_tls_key_file for further details. With Postfix >= 3.4 the pre‐
12794 ferred way to configure tlsproxy server keys and certificates is via
12795 the "tlsproxy_tls_chain_files" parameter.
12796 This feature is available in Postfix 2.8 and later.
12798
12800 Enable additional Postfix tlsproxy(8) server logging of TLS activity.
12801 Each logging level also includes the information that is logged at a
12802 lower logging level. See smtpd_tls_loglevel for further details.
12803 This feature is available in Postfix 2.8 and later.
12805
12807 The minimum TLS cipher grade that the Postfix tlsproxy(8) server will
12808 use with mandatory TLS encryption. See smtpd_tls_mandatory_ciphers for
12809 further details.
12810 This feature is available in Postfix 2.8 and later.
12812
12814 clude_ciphers)
12815 Additional list of ciphers or cipher types to exclude from the tl‐
12816 sproxy(8) server cipher list at mandatory TLS security levels. See
12817 smtpd_tls_mandatory_exclude_ciphers for further details.
12818 This feature is available in Postfix 2.8 and later.
12820
12822 The SSL/TLS protocols accepted by the Postfix tlsproxy(8) server with
12823 mandatory TLS encryption. If the list is empty, the server supports all
12824 available SSL/TLS protocol versions. See smtpd_tls_mandatory_protocols
12825 for further details.
12826 This feature is available in Postfix 2.8 and later.
12828
12830 List of TLS protocols that the Postfix tlsproxy(8) server will exclude
12831 or include with opportunistic TLS encryption. See smtpd_tls_protocols
12832 for further details.
12833 This feature is available in Postfix 2.8 and later.
12835
12837 With mandatory TLS encryption, require a trusted remote SMTP client
12838 certificate in order to allow TLS connections to proceed. See
12839 smtpd_tls_req_ccert for further details.
12840 This feature is available in Postfix 2.8 and later.
12842
12844 The SMTP TLS security level for the Postfix tlsproxy(8) server; when a
12845 non-empty value is specified, this overrides the obsolete parameters
12846 smtpd_use_tls and smtpd_enforce_tls. See smtpd_tls_security_level for
12847 further details.
12848 This feature is available in Postfix 2.8 and later.
12850
12852 Obsolete expiration time of Postfix tlsproxy(8) server TLS session
12854 cache information. Since the cache is shared with smtpd(8) and managed
12855 by tlsmgr(8), there is only one expiration time for the SMTP server
12856 cache shared by all three services, namely smtpd_tls_ses‐
12857 sion_cache_timeout.
12858 This feature is available in Postfix 2.8 and later.
12860
12862 Opportunistic TLS: announce STARTTLS support to remote SMTP clients,
12863 but do not require that clients use TLS encryption. See smtpd_use_tls
12864 for further details.
12865 This feature is available in Postfix 2.8 and later.
12867
12869 How much time a tlsproxy(8) process may take to process local or remote
12870 I/O before it is terminated by a built-in watchdog timer. This is a
12871 safety mechanism that prevents tlsproxy(8) from becoming non-responsive
12872 due to a bug in Postfix itself or in system software. To avoid false
12873 alarms and unnecessary cache corruption this limit cannot be set under
12874 10s.
12875 Specify a non-zero time value (an integral value plus an optional
12877 one-letter suffix that specifies the time unit). Time units: s (sec‐
12878 onds), m (minutes), h (hours), d (days), w (weeks).
12879 This feature is available in Postfix 2.8 and later
12881
12883 The name of the trace service. This service is implemented by the
12884 bounce(8) daemon and maintains a record of mail deliveries and produces
12885 a mail delivery report when verbose delivery is requested with "send‐
12886 mail -v".
12887 This feature is available in Postfix 2.1 and later.
12889
12891 A transport-specific override for the default_delivery_slot_cost param‐
12892 eter value, where transport is the master.cf name of the message deliv‐
12893 ery transport.
12894 Note: transport_delivery_slot_cost parameters will not show up in
12896 "postconf" command output before Postfix version 2.9. This limitation
12897 applies to many parameters whose name is a combination of a master.cf
12898 service name and a built-in suffix (in this case: "_deliv‐
12899 ery_slot_cost").
12900
12902 A transport-specific override for the default_delivery_slot_discount
12903 parameter value, where transport is the master.cf name of the message
12904 delivery transport.
12905 Note: transport_delivery_slot_discount parameters will not show up in
12907 "postconf" command output before Postfix version 2.9. This limitation
12908 applies to many parameters whose name is a combination of a master.cf
12909 service name and a built-in suffix (in this case: "_delivery_slot_dis‐
12910 count").
12911
12913 A transport-specific override for the default_delivery_slot_loan param‐
12914 eter value, where transport is the master.cf name of the message deliv‐
12915 ery transport.
12916 Note: transport_delivery_slot_loan parameters will not show up in
12918 "postconf" command output before Postfix version 2.9. This limitation
12919 applies to many parameters whose name is a combination of a master.cf
12920 service name and a built-in suffix (in this case: "_deliv‐
12921 ery_slot_loan").
12922
12924 tination_concurrency_failed_cohort_limit)
12925 A transport-specific override for the default_destination_concur‐
12926 rency_failed_cohort_limit parameter value, where transport is the mas‐
12927 ter.cf name of the message delivery transport.
12928 Note: some transport_destination_concurrency_failed_cohort_limit param‐
12930 eters will not show up in "postconf" command output before Postfix ver‐
12931 sion 2.9. This limitation applies to many parameters whose name is a
12932 combination of a master.cf service name and a built-in suffix (in this
12933 case: "_destination_concurrency_failed_cohort_limit").
12934 This feature is available in Postfix 2.5 and later.
12936
12938 rency_limit)
12939 A transport-specific override for the default_destination_concur‐
12940 rency_limit parameter value, where transport is the master.cf name of
12941 the message delivery transport.
12942 Note: some transport_destination_concurrency_limit parameters will not
12944 show up in "postconf" command output before Postfix version 2.9. This
12945 limitation applies to many parameters whose name is a combination of a
12946 master.cf service name and a built-in suffix (in this case: "_destina‐
12947 tion_concurrency_limit").
12948
12950 nation_concurrency_negative_feedback)
12951 A transport-specific override for the default_destination_concur‐
12952 rency_negative_feedback parameter value, where transport is the mas‐
12953 ter.cf name of the message delivery transport.
12954 Note: some transport_destination_concurrency_negative_feedback parame‐
12956 ters will not show up in "postconf" command output before Postfix ver‐
12957 sion 2.9. This limitation applies to many parameters whose name is a
12958 combination of a master.cf service name and a built-in suffix (in this
12959 case: "_destination_concurrency_negative_feedback").
12960 This feature is available in Postfix 2.5 and later.
12962
12964 nation_concurrency_positive_feedback)
12965 A transport-specific override for the default_destination_concur‐
12966 rency_positive_feedback parameter value, where transport is the mas‐
12967 ter.cf name of the message delivery transport.
12968 Note: some transport_destination_concurrency_positive_feedback parame‐
12970 ters will not show up in "postconf" command output before Postfix ver‐
12971 sion 2.9. This limitation applies to many parameters whose name is a
12972 combination of a master.cf service name and a built-in suffix (in this
12973 case: "_destination_concurrency_positive_feedback").
12974 This feature is available in Postfix 2.5 and later.
12976
12978 A transport-specific override for the default_destination_rate_delay
12979 parameter value, where transport is the master.cf name of the message
12980 delivery transport.
12981 Note: some transport_destination_rate_delay parameters will not show up
12983 in "postconf" command output before Postfix version 2.9. This limita‐
12984 tion applies to many parameters whose name is a combination of a mas‐
12985 ter.cf service name and a built-in suffix (in this case: "_destina‐
12986 tion_rate_delay").
12987 This feature is available in Postfix 2.5 and later.
12989
12991 ent_limit)
12992 A transport-specific override for the default_destination_recipi‐
12993 ent_limit parameter value, where transport is the master.cf name of the
12994 message delivery transport.
12995 Note: some transport_destination_recipient_limit parameters will not
12997 show up in "postconf" command output before Postfix version 2.9. This
12998 limitation applies to many parameters whose name is a combination of a
12999 master.cf service name and a built-in suffix (in this case: "_destina‐
13000 tion_recipient_limit").
13001
13003 A transport-specific override for the default_extra_recipient_limit pa‐
13004 rameter value, where transport is the master.cf name of the message de‐
13005 livery transport.
13006 Note: transport_extra_recipient_limit parameters will not show up in
13008 "postconf" command output before Postfix version 2.9. This limitation
13009 applies to many parameters whose name is a combination of a master.cf
13010 service name and a built-in suffix (in this case: "_extra_recipi‐
13011 ent_limit").
13012
13014 currency)
13015 A transport-specific override for the initial_destination_concurrency
13016 parameter value, where transport is the master.cf name of the message
13017 delivery transport.
13018 Note: some transport_initial_destination_concurrency parameters will
13020 not show up in "postconf" command output before Postfix version 2.9.
13021 This limitation applies to many parameters whose name is a combination
13022 of a master.cf service name and a built-in suffix (in this case: "_ini‐
13023 tial_destination_concurrency").
13024 This feature is available in Postfix 2.5 and later.
13026
13028 Optional lookup tables with mappings from recipient address to (message
13029 delivery transport, next-hop destination). See transport(5) for de‐
13030 tails.
13031 Specify zero or more "type:table" lookup tables, separated by white‐
13033 space or comma. Tables will be searched in the specified order until a
13034 match is found. If you use this feature with local files, run "postmap
13035 /etc/postfix/transport" after making a change.
13036 Pattern matching of domain names is controlled by the presence or ab‐
13038 sence of "transport_maps" in the parent_domain_matches_subdomains pa‐
13039 rameter value.
13040 For safety reasons, as of Postfix 2.3 this feature does not allow $num‐
13042 ber substitutions in regular expression maps.
13043 Examples:
13045 transport_maps = dbm:/etc/postfix/transport
13047 transport_maps = hash:/etc/postfix/transport
13048
13050 A transport-specific override for the default_minimum_delivery_slots
13051 parameter value, where transport is the master.cf name of the message
13052 delivery transport.
13053 Note: transport_minimum_delivery_slots parameters will not show up in
13055 "postconf" command output before Postfix version 2.9. This limitation
13056 applies to many parameters whose name is a combination of a master.cf
13057 service name and a built-in suffix (in this case: "_minimum_deliv‐
13058 ery_slots").
13059
13061 A transport-specific override for the default_recipient_limit parameter
13062 value, where transport is the master.cf name of the message delivery
13063 transport.
13064 Note: some transport_recipient_limit parameters will not show up in
13066 "postconf" command output before Postfix version 2.9. This limitation
13067 applies to many parameters whose name is a combination of a master.cf
13068 service name and a built-in suffix (in this case: "_recipient_limit").
13069
13071 A transport-specific override for the default_recipient_refill_delay
13072 parameter value, where transport is the master.cf name of the message
13073 delivery transport.
13074 Note: transport_recipient_refill_delay parameters will not show up in
13076 "postconf" command output before Postfix version 2.9. This limitation
13077 applies to many parameters whose name is a combination of a master.cf
13078 service name and a built-in suffix (in this case: "_recipient_re‐
13079 fill_delay").
13080 This feature is available in Postfix 2.4 and later.
13082
13084 A transport-specific override for the default_recipient_refill_limit
13085 parameter value, where transport is the master.cf name of the message
13086 delivery transport.
13087 Note: transport_recipient_refill_limit parameters will not show up in
13089 "postconf" command output before Postfix version 2.9. This limitation
13090 applies to many parameters whose name is a combination of a master.cf
13091 service name and a built-in suffix (in this case: "_recipient_re‐
13092 fill_limit").
13093 This feature is available in Postfix 2.4 and later.
13095
13097 The time between attempts by the Postfix queue manager to contact a
13098 malfunctioning message delivery transport.
13099 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
13101 The default time unit is s (seconds).
13102
13104 A transport-specific override for the command_time_limit parameter
13105 value, where transport is the master.cf name of the message delivery
13106 transport.
13107 Note: transport_time_limit parameters will not show up in "postconf"
13109 command output before Postfix version 2.9. This limitation applies to
13110 many parameters whose name is a combination of a master.cf service name
13111 and a built-in suffix (in this case: "_time_limit").
13112
13114 A transport-specific override for the default_transport_rate_delay pa‐
13115 rameter value, where the initial transport in the parameter name is the
13116 master.cf name of the message delivery transport.
13117
13119 The time limit for sending a trigger to a Postfix daemon (for example,
13120 the pickup(8) or qmgr(8) daemon). This time limit prevents programs
13121 from getting stuck when the mail system is under heavy load.
13122 Time units: s (seconds), m (minutes), h (hours), d (days), w (weeks).
13124 The default time unit is s (seconds).
13125
13127 Message header that the Postfix cleanup(8) server inserts when a mes‐
13128 sage contains no To: or Cc: message header. With Postfix 2.8 and later,
13129 the default value is empty. With Postfix 2.4-2.7, specify an empty
13130 value to disable this feature.
13131 Example:
13133 # Default value before Postfix 2.8.
13135 # Note: the ":" and ";" are both required.
13136 undisclosed_recipients_header = To: undisclosed-recipients:;
13137
13139 The numerical response code when the Postfix SMTP server rejects a
13140 sender or recipient address because its domain is unknown. This is one
13141 of the possible replies from the restrictions reject_unknown_sender_do‐
13142 main and reject_unknown_recipient_domain.
13143 Do not change this unless you have a complete understanding of RFC
13145 5321.
13146
13148 The Postfix SMTP server's action when reject_unknown_sender_domain or
13149 reject_unknown_recipient_domain fail due to a temporary error condi‐
13150 tion. Specify "defer" to defer the remote SMTP client request immedi‐
13151 ately. With the default "defer_if_permit" action, the Postfix SMTP
13152 server continues to look for opportunities to reject mail, and defers
13153 the client request only if it would otherwise be accepted.
13154 This feature is available in Postfix 2.6 and later.
13156
13158 The numerical Postfix SMTP server response code when a client without
13159 valid address <=> name mapping is rejected by the reject_un‐
13160 known_client_hostname restriction. The SMTP server always replies with
13161 450 when the mapping failed due to a temporary error condition.
13162 Do not change this unless you have a complete understanding of RFC
13164 5321.
13165
13167 The Postfix SMTP server's action when reject_unknown_helo_hostname
13168 fails due to a temporary error condition. Specify "defer" to defer the
13169 remote SMTP client request immediately. With the default "defer_if_per‐
13170 mit" action, the Postfix SMTP server continues to look for opportuni‐
13171 ties to reject mail, and defers the client request only if it would
13172 otherwise be accepted.
13173 This feature is available in Postfix 2.6 and later.
13175
13177 The numerical Postfix SMTP server response code when the hostname spec‐
13178 ified with the HELO or EHLO command is rejected by the reject_un‐
13179 known_helo_hostname restriction.
13180 Do not change this unless you have a complete understanding of RFC
13182 5321.
13183
13185 The numerical Postfix SMTP server response code when a recipient ad‐
13186 dress is local, and $local_recipient_maps specifies a list of lookup
13187 tables that does not match the recipient. A recipient address is local
13188 when its domain matches $mydestination, $proxy_interfaces or $inet_in‐
13189 terfaces.
13190 The default setting is 550 (reject mail) but it is safer to initially
13192 use 450 (try again later) so you have time to find out if your lo‐
13193 cal_recipient_maps settings are OK.
13194 Example:
13196 unknown_local_recipient_reject_code = 450
13198 This feature is available in Postfix 2.0 and later.
13200
13202 The numerical Postfix SMTP server reply code when a recipient address
13203 matches $relay_domains, and relay_recipient_maps specifies a list of
13204 lookup tables that does not match the recipient address.
13205 This feature is available in Postfix 2.0 and later.
13207
13209 The Postfix SMTP server reply code when a recipient address matches
13210 $virtual_alias_domains, and $virtual_alias_maps specifies a list of
13211 lookup tables that does not match the recipient address.
13212 This feature is available in Postfix 2.0 and later.
13214
13216 The Postfix SMTP server reply code when a recipient address matches
13217 $virtual_mailbox_domains, and $virtual_mailbox_maps specifies a list of
13218 lookup tables that does not match the recipient address.
13219 This feature is available in Postfix 2.0 and later.
13221
13223 The numerical Postfix SMTP server response when a recipient address
13224 probe fails due to a temporary error condition.
13225 Unlike elsewhere in Postfix, you can specify 250 in order to accept the
13227 address anyway.
13228 Do not change this unless you have a complete understanding of RFC
13230 5321.
13231 This feature is available in Postfix 2.6 and later.
13233
13235 The numerical Postfix SMTP server response when a recipient address is
13236 rejected by the reject_unverified_recipient restriction.
13237 Unlike elsewhere in Postfix, you can specify 250 in order to accept the
13239 address anyway.
13240 Do not change this unless you have a complete understanding of RFC
13242 5321.
13243 This feature is available in Postfix 2.1 and later.
13245
13247 The Postfix SMTP server's reply when rejecting mail with reject_unveri‐
13248 fied_recipient. Do not include the numeric SMTP reply code or the en‐
13249 hanced status code. By default, the response includes actual address
13250 verification details.
13251 Example:
13253 unverified_recipient_reject_reason = Recipient address lookup failed
13255 This feature is available in Postfix 2.6 and later.
13257
13259 The Postfix SMTP server's action when reject_unverified_recipient fails
13260 due to a temporary error condition. Specify "defer" to defer the remote
13261 SMTP client request immediately. With the default "defer_if_permit" ac‐
13262 tion, the Postfix SMTP server continues to look for opportunities to
13263 reject mail, and defers the client request only if it would otherwise
13264 be accepted.
13265 This feature is available in Postfix 2.6 and later.
13267
13269 The numerical Postfix SMTP server response code when a sender address
13270 probe fails due to a temporary error condition.
13271 Unlike elsewhere in Postfix, you can specify 250 in order to accept the
13273 address anyway.
13274 Do not change this unless you have a complete understanding of RFC
13276 5321.
13277 This feature is available in Postfix 2.6 and later.
13279
13281 The numerical Postfix SMTP server response code when a recipient ad‐
13282 dress is rejected by the reject_unverified_sender restriction.
13283 Unlike elsewhere in Postfix, you can specify 250 in order to accept the
13285 address anyway.
13286 Do not change this unless you have a complete understanding of RFC
13288 5321.
13289 This feature is available in Postfix 2.1 and later.
13291
13293 The Postfix SMTP server's reply when rejecting mail with reject_unveri‐
13294 fied_sender. Do not include the numeric SMTP reply code or the enhanced
13295 status code. By default, the response includes actual address verifica‐
13296 tion details.
13297 Example:
13299 unverified_sender_reject_reason = Sender address lookup failed
13301 This feature is available in Postfix 2.6 and later.
13303
13305 The Postfix SMTP server's action when reject_unverified_sender fails
13306 due to a temporary error condition. Specify "defer" to defer the remote
13307 SMTP client request immediately. With the default "defer_if_permit" ac‐
13308 tion, the Postfix SMTP server continues to look for opportunities to
13309 reject mail, and defers the client request only if it would otherwise
13310 be accepted.
13311 This feature is available in Postfix 2.6 and later.
13313
13315 The characters Postfix accepts as VERP delimiter characters on the
13316 Postfix sendmail(1) command line and in SMTP commands.
13317 This feature is available in Postfix 1.1 and later.
13319
13321 The maximal length of an email address after virtual alias expansion.
13322 This stops virtual aliasing loops that increase the address length ex‐
13323 ponentially.
13324 This feature is available in Postfix 3.0 and later.
13326
13328 Postfix is final destination for the specified list of virtual alias
13329 domains, that is, domains for which all addresses are aliased to ad‐
13330 dresses in other local or remote domains. The SMTP server validates re‐
13331 cipient addresses with $virtual_alias_maps and rejects non-existent re‐
13332 cipients. See also the virtual alias domain class in the AD‐
13333 DRESS_CLASS_README file
13334 This feature is available in Postfix 2.0 and later. The default value
13336 is backwards compatible with Postfix version 1.1.
13337 The default value is $virtual_alias_maps so that you can keep all in‐
13339 formation about virtual alias domains in one place. If you have many
13340 users, it is better to separate information that changes more fre‐
13341 quently (virtual address -> local or remote address mapping) from in‐
13342 formation that changes less frequently (the list of virtual domain
13343 names).
13344 Specify a list of host or domain names, "/file/name" or "type:table"
13346 patterns, separated by commas and/or whitespace. A "/file/name" pattern
13347 is replaced by its contents; a "type:table" lookup table is matched
13348 when a table entry matches a lookup string (the lookup result is ig‐
13349 nored). Continue long lines by starting the next line with whitespace.
13350 Specify "!pattern" to exclude a host or domain name from the list. The
13351 form "!/file/name" is supported only in Postfix version 2.4 and later.
13352 See also the VIRTUAL_README and ADDRESS_CLASS_README documents for fur‐
13354 ther information.
13355 Example:
13357 virtual_alias_domains = virtual1.tld virtual2.tld
13359
13361 The maximal number of addresses that virtual alias expansion produces
13362 from each original recipient.
13363 This feature is available in Postfix 2.1 and later.
13365
13367 Optional lookup tables that alias specific mail addresses or domains to
13368 other local or remote address. The table format and lookups are docu‐
13369 mented in virtual(5). For an overview of Postfix address manipulations
13370 see the ADDRESS_REWRITING_README document.
13371 This feature is available in Postfix 2.0 and later. The default value
13373 is backwards compatible with Postfix version 1.1.
13374 Specify zero or more "type:name" lookup tables, separated by whitespace
13376 or comma. Tables will be searched in the specified order until a match
13377 is found. Note: these lookups are recursive.
13378 If you use this feature with indexed files, run "postmap /etc/post‐
13380 fix/virtual" after changing the file.
13381 Examples:
13383 virtual_alias_maps = dbm:/etc/postfix/virtual
13385 virtual_alias_maps = hash:/etc/postfix/virtual
13386
13388 The maximal nesting depth of virtual alias expansion. Currently the
13389 recursion limit is applied only to the left branch of the expansion
13390 graph, so the depth of the tree can in the worst case reach the sum of
13391 the expansion and recursion limits. This may change in the future.
13392 This feature is available in Postfix 2.1 and later.
13394
13396 Optional filter for the virtual(8) delivery agent to change the deliv‐
13397 ery status code or explanatory text of successful or unsuccessful de‐
13398 liveries. See default_delivery_status_filter for details.
13399 This feature is available in Postfix 3.0 and later.
13401
13403 rency_limit)
13404 The maximal number of parallel deliveries to the same destination via
13405 the virtual message delivery transport. This limit is enforced by the
13406 queue manager. The message delivery transport name is the first field
13407 in the entry in the master.cf file.
13408
13410 ent_limit)
13411 The maximal number of recipients per message for the virtual message
13412 delivery transport. This limit is enforced by the queue manager. The
13413 message delivery transport name is the first field in the entry in the
13414 master.cf file.
13415 Setting this parameter to a value of 1 changes the meaning of vir‐
13417 tual_destination_concurrency_limit from concurrency per domain into
13418 concurrency per recipient.
13419
13421 Lookup tables with the per-recipient group ID for virtual(8) mailbox
13422 delivery.
13423 This parameter is specific to the virtual(8) delivery agent. It does
13425 not apply when mail is delivered with a different mail delivery pro‐
13426 gram.
13427 Specify zero or more "type:name" lookup tables, separated by whitespace
13429 or comma. Tables will be searched in the specified order until a match
13430 is found.
13431 In a lookup table, specify a left-hand side of "@domain.tld" to match
13433 any user in the specified domain that does not have a specific
13434 "user@domain.tld" entry.
13435 When a recipient address has an optional address extension
13437 (user+foo@domain.tld), the virtual(8) delivery agent looks up the full
13438 address first, and when the lookup fails, it looks up the unextended
13439 address (user@domain.tld).
13440 Note 1: for security reasons, the virtual(8) delivery agent disallows
13442 regular expression substitution of $1 etc. in regular expression lookup
13443 tables, because that would open a security hole.
13444 Note 2: for security reasons, the virtual(8) delivery agent will
13446 silently ignore requests to use the proxymap(8) server. Instead it will
13447 open the table directly. Before Postfix version 2.2, the virtual(8) de‐
13448 livery agent will terminate with a fatal error.
13449
13451 A prefix that the virtual(8) delivery agent prepends to all pathname
13452 results from $virtual_mailbox_maps table lookups. This is a safety
13453 measure to ensure that an out of control map doesn't litter the file
13454 system with mailboxes. While virtual_mailbox_base could be set to "/",
13455 this setting isn't recommended.
13456 This parameter is specific to the virtual(8) delivery agent. It does
13458 not apply when mail is delivered with a different mail delivery pro‐
13459 gram.
13460 Example:
13462 virtual_mailbox_base = /var/mail
13464
13466 Postfix is final destination for the specified list of domains; mail is
13467 delivered via the $virtual_transport mail delivery transport. By de‐
13468 fault this is the Postfix virtual(8) delivery agent. The SMTP server
13469 validates recipient addresses with $virtual_mailbox_maps and rejects
13470 mail for non-existent recipients. See also the virtual mailbox domain
13471 class in the ADDRESS_CLASS_README file.
13472 This parameter expects the same syntax as the mydestination configura‐
13474 tion parameter.
13475 This feature is available in Postfix 2.0 and later. The default value
13477 is backwards compatible with Postfix version 1.1.
13478
13480 The maximal size in bytes of an individual virtual(8) mailbox or
13481 maildir file, or zero (no limit).
13482 This parameter is specific to the virtual(8) delivery agent. It does
13484 not apply when mail is delivered with a different mail delivery pro‐
13485 gram.
13486
13488 How to lock a UNIX-style virtual(8) mailbox before attempting delivery.
13489 For a list of available file locking methods, use the "postconf -l"
13490 command.
13491 This parameter is specific to the virtual(8) delivery agent. It does
13493 not apply when mail is delivered with a different mail delivery pro‐
13494 gram.
13495 This setting is ignored with maildir style delivery, because such de‐
13497 liveries are safe without application-level locks.
13498 Note 1: the dotlock method requires that the recipient UID or GID has
13500 write access to the parent directory of the recipient's mailbox file.
13501 Note 2: the default setting of this parameter is system dependent.
13503
13505 Optional lookup tables with all valid addresses in the domains that
13506 match $virtual_mailbox_domains.
13507 Specify zero or more "type:name" lookup tables, separated by whitespace
13509 or comma. Tables will be searched in the specified order until a match
13510 is found.
13511 In a lookup table, specify a left-hand side of "@domain.tld" to match
13513 any user in the specified domain that does not have a specific
13514 "user@domain.tld" entry.
13515 The remainder of this text is specific to the virtual(8) delivery
13517 agent. It does not apply when mail is delivered with a different mail
13518 delivery program.
13519 The virtual(8) delivery agent uses this table to look up the per-recip‐
13521 ient mailbox or maildir pathname. If the lookup result ends in a slash
13522 ("/"), maildir-style delivery is carried out, otherwise the path is as‐
13523 sumed to specify a UNIX-style mailbox file. Note that $virtual_mail‐
13524 box_base is unconditionally prepended to this path.
13525 When a recipient address has an optional address extension
13527 (user+foo@domain.tld), the virtual(8) delivery agent looks up the full
13528 address first, and when the lookup fails, it looks up the unextended
13529 address (user@domain.tld).
13530 Note 1: for security reasons, the virtual(8) delivery agent disallows
13532 regular expression substitution of $1 etc. in regular expression lookup
13533 tables, because that would open a security hole.
13534 Note 2: for security reasons, the virtual(8) delivery agent will
13536 silently ignore requests to use the proxymap(8) server. Instead it will
13537 open the table directly. Before Postfix version 2.2, the virtual(8) de‐
13538 livery agent will terminate with a fatal error.
13539
13541 Optional lookup tables with a) names of domains for which all addresses
13542 are aliased to addresses in other local or remote domains, and b) ad‐
13543 dresses that are aliased to addresses in other local or remote domains.
13544 Available before Postfix version 2.0. With Postfix version 2.0 and
13545 later, this is replaced by separate controls: virtual_alias_domains and
13546 virtual_alias_maps.
13547
13549 The minimum user ID value that the virtual(8) delivery agent accepts as
13550 a result from $virtual_uid_maps table lookup. Returned values less
13551 than this will be rejected, and the message will be deferred.
13552 This parameter is specific to the virtual(8) delivery agent. It does
13554 not apply when mail is delivered with a different mail delivery pro‐
13555 gram.
13556
13558 The default mail delivery transport and next-hop destination for final
13559 delivery to domains listed with $virtual_mailbox_domains. This infor‐
13560 mation can be overruled with the transport(5) table.
13561 Specify a string of the form transport:nexthop, where transport is the
13563 name of a mail delivery transport defined in master.cf. The :nexthop
13564 destination is optional; its syntax is documented in the manual page of
13565 the corresponding delivery agent.
13566 This feature is available in Postfix 2.0 and later.
13568
13570 Lookup tables with the per-recipient user ID that the virtual(8) deliv‐
13571 ery agent uses while writing to the recipient's mailbox.
13572 This parameter is specific to the virtual(8) delivery agent. It does
13574 not apply when mail is delivered with a different mail delivery pro‐
13575 gram.
13576 Specify zero or more "type:name" lookup tables, separated by whitespace
13578 or comma. Tables will be searched in the specified order until a match
13579 is found.
13580 In a lookup table, specify a left-hand side of "@domain.tld" to match
13582 any user in the specified domain that does not have a specific
13583 "user@domain.tld" entry.
13584 When a recipient address has an optional address extension
13586 (user+foo@domain.tld), the virtual(8) delivery agent looks up the full
13587 address first, and when the lookup fails, it looks up the unextended
13588 address (user@domain.tld).
13589 Note 1: for security reasons, the virtual(8) delivery agent disallows
13591 regular expression substitution of $1 etc. in regular expression lookup
13592 tables, because that would open a security hole.
13593 Note 2: for security reasons, the virtual(8) delivery agent will
13595 silently ignore requests to use the proxymap(8) server. Instead it will
13596 open the table directly. Before Postfix version 2.2, the virtual(8) de‐
13597 livery agent will terminate with a fatal error.
13598
13600 postconf(1), Postfix configuration parameter maintenance
13601 master(5), Postfix daemon configuration maintenance
13602
13604 The Secure Mailer license must be distributed with this software.
13605
13607 Wietse Venema
13608 IBM T.J. Watson Research
13609 P.O. Box 704
13610 Yorktown Heights, NY 10598, USA
13611 Wietse Venema
13613 Google, Inc.
13614 111 8th Avenue
13615 New York, NY 10011, USA
13616 Viktor Dukhovni
13618 POSTCONF(5)