1SMTP(8) System Manager's Manual SMTP(8)
2
6 smtp - Postfix SMTP+LMTP client
7
9 smtp [generic Postfix daemon options]
10
12 The Postfix SMTP+LMTP client implements the SMTP and LMTP mail delivery
13 protocols. It processes message delivery requests from the queue man‐
14 ager. Each request specifies a queue file, a sender address, a domain
15 or host to deliver to, and recipient information. This program expects
16 to be run from the master(8) process manager.
17 The SMTP+LMTP client updates the queue file and marks recipients as
19 finished, or it informs the queue manager that delivery should be tried
20 again at a later time. Delivery status reports are sent to the
21 bounce(8), defer(8) or trace(8) daemon as appropriate.
22 The SMTP+LMTP client looks up a list of mail exchanger addresses for
24 the destination host, sorts the list by preference, and connects to
25 each listed address until it finds a server that responds.
26 When a server is not reachable, or when mail delivery fails due to a
28 recoverable error condition, the SMTP+LMTP client will try to deliver
29 the mail to an alternate host.
30 After a successful mail transaction, a connection may be saved to the
32 scache(8) connection cache server, so that it may be used by any
33 SMTP+LMTP client for a subsequent transaction.
34 By default, connection caching is enabled temporarily for destinations
36 that have a high volume of mail in the active queue. Connection caching
37 can be enabled permanently for specific destinations.
38
40 SMTP destinations have the following form:
41 domainname
43 domainname:port
45 Look up the mail exchangers for the specified domain, and con‐
46 nect to the specified port (default: smtp).
47 [hostname]
49 [hostname]:port
51 Look up the address(es) of the specified host, and connect to
52 the specified port (default: smtp).
53 [address]
55 [address]:port
57 Connect to the host at the specified address, and connect to the
58 specified port (default: smtp). An IPv6 address must be format‐
59 ted as [ipv6:address].
60
62 LMTP destinations have the following form:
63 unix:pathname
65 Connect to the local UNIX-domain server that is bound to the
66 specified pathname. If the process runs chrooted, an absolute
67 pathname is interpreted relative to the Postfix queue directory.
68 inet:hostname
70 inet:hostname:port
72 inet:[address]
74 inet:[address]:port
76 Connect to the specified TCP port on the specified local or
77 remote host. If no port is specified, connect to the port
78 defined as lmtp in services(4). If no such service is found,
79 the lmtp_tcp_port configuration parameter (default value of 24)
80 will be used. An IPv6 address must be formatted as
81 [ipv6:address].
82
84 The SMTP+LMTP client is moderately security-sensitive. It talks to SMTP
85 or LMTP servers and to DNS servers on the network. The SMTP+LMTP client
86 can be run chrooted at fixed low privilege.
87
89 RFC 821 (SMTP protocol)
90 RFC 822 (ARPA Internet Text Messages)
91 RFC 1651 (SMTP service extensions)
92 RFC 1652 (8bit-MIME transport)
93 RFC 1870 (Message Size Declaration)
94 RFC 2033 (LMTP protocol)
95 RFC 2034 (SMTP Enhanced Error Codes)
96 RFC 2045 (MIME: Format of Internet Message Bodies)
97 RFC 2046 (MIME: Media Types)
98 RFC 2554 (AUTH command)
99 RFC 2821 (SMTP protocol)
100 RFC 2920 (SMTP Pipelining)
101 RFC 3207 (STARTTLS command)
102 RFC 3461 (SMTP DSN Extension)
103 RFC 3463 (Enhanced Status Codes)
104
106 Problems and transactions are logged to syslogd(8). Corrupted message
107 files are marked so that the queue manager can move them to the corrupt
108 queue for further inspection.
109 Depending on the setting of the notify_classes parameter, the postmas‐
111 ter is notified of bounces, protocol problems, and of other trouble.
112
114 SMTP and LMTP connection caching does not work with TLS. The necessary
115 support for TLS object passivation and re-activation does not exist
116 without closing the session, which defeats the purpose.
117 SMTP and LMTP connection caching assumes that SASL credentials are
119 valid for all destinations that map onto the same IP address and TCP
120 port.
121
123 Before Postfix version 2.3, the LMTP client is a separate program that
124 implements only a subset of the functionality available with SMTP:
125 there is no support for TLS, and connections are cached in-process,
126 making it ineffective when the client is used for multiple domains.
127 Most smtp_xxx configuration parameters have an lmtp_xxx "mirror" param‐
129 eter for the equivalent LMTP feature. This document describes only
130 those LMTP-related parameters that aren't simply "mirror" parameters.
131 Changes to main.cf are picked up automatically, as smtp(8) processes
133 run for only a limited amount of time. Use the command "postfix reload"
134 to speed up a change.
135 The text below provides only a parameter summary. See postconf(5) for
137 more details including examples.
138
140 ignore_mx_lookup_error (no)
141 Ignore DNS MX lookups that produce no response.
142 smtp_always_send_ehlo (yes)
144 Always send EHLO at the start of an SMTP session.
145 smtp_never_send_ehlo (no)
147 Never send EHLO at the start of an SMTP session.
148 smtp_defer_if_no_mx_address_found (no)
150 Defer mail delivery when no MX record resolves to an IP address.
151 smtp_line_length_limit (990)
153 The maximal length of message header and body lines that Postfix
154 will send via SMTP.
155 smtp_pix_workaround_delay_time (10s)
157 How long the Postfix SMTP client pauses before sending
158 ".<CR><LF>" in order to work around the PIX firewall
159 "<CR><LF>.<CR><LF>" bug.
160 smtp_pix_workaround_threshold_time (500s)
162 How long a message must be queued before the Postfix SMTP client
163 turns on the PIX firewall "<CR><LF>.<CR><LF>" bug workaround for
164 delivery through firewalls with "smtp fixup" mode turned on.
165 smtp_pix_workarounds (disable_esmtp, delay_dotcrlf)
167 A list that specifies zero or more workarounds for CISCO PIX
168 firewall bugs.
169 smtp_pix_workaround_maps (empty)
171 Lookup tables, indexed by the remote SMTP server address, with
172 per-destination workarounds for CISCO PIX firewall bugs.
173 smtp_quote_rfc821_envelope (yes)
175 Quote addresses in SMTP MAIL FROM and RCPT TO commands as
176 required by RFC 821.
177 smtp_skip_5xx_greeting (yes)
179 Skip SMTP servers that greet with a 5XX status code (go away, do
180 not try again later).
181 smtp_skip_quit_response (yes)
183 Do not wait for the response to the SMTP QUIT command.
184 Available in Postfix version 2.0 and earlier:
186 smtp_skip_4xx_greeting (yes)
188 Skip SMTP servers that greet with a 4XX status code (go away,
189 try again later).
190 Available in Postfix version 2.2 and later:
192 smtp_discard_ehlo_keyword_address_maps (empty)
194 Lookup tables, indexed by the remote SMTP server address, with
195 case insensitive lists of EHLO keywords (pipelining, starttls,
196 auth, etc.) that the Postfix SMTP client will ignore in the EHLO
197 response from a remote SMTP server.
198 smtp_discard_ehlo_keywords (empty)
200 A case insensitive list of EHLO keywords (pipelining, starttls,
201 auth, etc.) that the Postfix SMTP client will ignore in the EHLO
202 response from a remote SMTP server.
203 smtp_generic_maps (empty)
205 Optional lookup tables that perform address rewriting in the
206 SMTP client, typically to transform a locally valid address into
207 a globally valid address when sending mail across the Internet.
208 Available in Postfix version 2.2.9 and later:
210 smtp_cname_overrides_servername (version dependent)
212 Allow DNS CNAME records to override the servername that the
213 Postfix SMTP client uses for logging, SASL password lookup, TLS
214 policy decisions, or TLS certificate verification.
215 Available in Postfix version 2.3 and later:
217 lmtp_discard_lhlo_keyword_address_maps (empty)
219 Lookup tables, indexed by the remote LMTP server address, with
220 case insensitive lists of LHLO keywords (pipelining, starttls,
221 auth, etc.) that the LMTP client will ignore in the LHLO
222 response from a remote LMTP server.
223 lmtp_discard_lhlo_keywords (empty)
225 A case insensitive list of LHLO keywords (pipelining, starttls,
226 auth, etc.) that the LMTP client will ignore in the LHLO
227 response from a remote LMTP server.
228 Available in Postfix version 2.4.4 and later:
230 send_cyrus_sasl_authzid (no)
232 When authenticating to a remote SMTP or LMTP server with the
233 default setting "no", send no SASL authoriZation ID (authzid);
234 send only the SASL authentiCation ID (authcid) plus the auth‐
235 cid's password.
236
238 Available in Postfix version 2.0 and later:
239 disable_mime_output_conversion (no)
241 Disable the conversion of 8BITMIME format to 7BIT format.
242 mime_boundary_length_limit (2048)
244 The maximal length of MIME multipart boundary strings.
245 mime_nesting_limit (100)
247 The maximal recursion level that the MIME processor will handle.
248
250 Available in Postfix version 2.1 and later:
251 smtp_send_xforward_command (no)
253 Send the non-standard XFORWARD command when the Postfix SMTP
254 server EHLO response announces XFORWARD support.
255
257 smtp_sasl_auth_enable (no)
258 Enable SASL authentication in the Postfix SMTP client.
259 smtp_sasl_password_maps (empty)
261 Optional SMTP client lookup tables with one username:password
262 entry per remote hostname or domain, or sender address when
263 sender-dependent authentication is enabled.
264 smtp_sasl_security_options (noplaintext, noanonymous)
266 SASL security options; as of Postfix 2.3 the list of available
267 features depends on the SASL client implementation that is
268 selected with smtp_sasl_type.
269 Available in Postfix version 2.2 and later:
271 smtp_sasl_mechanism_filter (empty)
273 If non-empty, a Postfix SMTP client filter for the remote SMTP
274 server's list of offered SASL mechanisms.
275 Available in Postfix version 2.3 and later:
277 smtp_sender_dependent_authentication (no)
279 Enable sender-dependent authentication in the Postfix SMTP
280 client; this is available only with SASL authentication, and
281 disables SMTP connection caching to ensure that mail from dif‐
282 ferent senders will use the appropriate credentials.
283 smtp_sasl_path (empty)
285 Implementation-specific information that is passed through to
286 the SASL plug-in implementation that is selected with
287 smtp_sasl_type.
288 smtp_sasl_type (cyrus)
290 The SASL plug-in type that the Postfix SMTP client should use
291 for authentication.
292
294 Detailed information about STARTTLS configuration may be found in the
295 TLS_README document.
296 smtp_tls_security_level (empty)
298 The default SMTP TLS security level for the Postfix SMTP client;
299 when a non-empty value is specified, this overrides the obsolete
300 parameters smtp_use_tls, smtp_enforce_tls, and
301 smtp_tls_enforce_peername.
302 smtp_sasl_tls_security_options ($smtp_sasl_security_options)
304 The SASL authentication security options that the Postfix SMTP
305 client uses for TLS encrypted SMTP sessions.
306 smtp_starttls_timeout (300s)
308 Time limit for Postfix SMTP client write and read operations
309 during TLS startup and shutdown handshake procedures.
310 smtp_tls_CAfile (empty)
312 The file with the certificate of the certification authority
313 (CA) that issued the Postfix SMTP client certificate.
314 smtp_tls_CApath (empty)
316 Directory with PEM format certificate authority certificates
317 that the Postfix SMTP client uses to verify a remote SMTP server
318 certificate.
319 smtp_tls_cert_file (empty)
321 File with the Postfix SMTP client RSA certificate in PEM format.
322 smtp_tls_mandatory_ciphers (medium)
324 The minimum TLS cipher grade that the Postfix SMTP client will
325 use with mandatory TLS encryption.
326 smtp_tls_exclude_ciphers (empty)
328 List of ciphers or cipher types to exclude from the Postfix SMTP
329 client cipher list at all TLS security levels.
330 smtp_tls_mandatory_exclude_ciphers (empty)
332 Additional list of ciphers or cipher types to exclude from the
333 SMTP client cipher list at mandatory TLS security levels.
334 smtp_tls_dcert_file (empty)
336 File with the Postfix SMTP client DSA certificate in PEM format.
337 smtp_tls_dkey_file ($smtp_tls_dcert_file)
339 File with the Postfix SMTP client DSA private key in PEM format.
340 smtp_tls_key_file ($smtp_tls_cert_file)
342 File with the Postfix SMTP client RSA private key in PEM format.
343 smtp_tls_loglevel (0)
345 Enable additional Postfix SMTP client logging of TLS activity.
346 smtp_tls_note_starttls_offer (no)
348 Log the hostname of a remote SMTP server that offers STARTTLS,
349 when TLS is not already enabled for that server.
350 smtp_tls_policy_maps (empty)
352 Optional lookup tables with the Postfix SMTP client TLS security
353 policy by next-hop destination; when a non-empty value is speci‐
354 fied, this overrides the obsolete smtp_tls_per_site parameter.
355 smtp_tls_mandatory_protocols (SSLv3, TLSv1)
357 List of TLS protocols that the Postfix SMTP client will use with
358 mandatory TLS encryption.
359 smtp_tls_scert_verifydepth (5)
361 The verification depth for remote SMTP server certificates.
362 smtp_tls_secure_cert_match (nexthop, dot-nexthop)
364 The server certificate peername verification method for the
365 "secure" TLS security level.
366 smtp_tls_session_cache_database (empty)
368 Name of the file containing the optional Postfix SMTP client TLS
369 session cache.
370 smtp_tls_session_cache_timeout (3600s)
372 The expiration time of Postfix SMTP client TLS session cache
373 information.
374 smtp_tls_verify_cert_match (hostname)
376 The server certificate peername verification method for the
377 "verify" TLS security level.
378 tls_daemon_random_bytes (32)
380 The number of pseudo-random bytes that an smtp(8) or smtpd(8)
381 process requests from the tlsmgr(8) server in order to seed its
382 internal pseudo random number generator (PRNG).
383 tls_high_cipherlist (ALL:!EXPORT:!LOW:!MEDIUM:+RC4:@STRENGTH)
385 The OpenSSL cipherlist for "HIGH" grade ciphers.
386 tls_medium_cipherlist (ALL:!EXPORT:!LOW:+RC4:@STRENGTH)
388 The OpenSSL cipherlist for "MEDIUM" or higher grade ciphers.
389 tls_low_cipherlist (ALL:!EXPORT:+RC4:@STRENGTH)
391 The OpenSSL cipherlist for "LOW" or higher grade ciphers.
392 tls_export_cipherlist (ALL:+RC4:@STRENGTH)
394 The OpenSSL cipherlist for "EXPORT" or higher grade ciphers.
395 tls_null_cipherlist (eNULL:!aNULL)
397 The OpenSSL cipherlist for "NULL" grade ciphers that provide
398 authentication without encryption.
399 Available in Postfix version 2.4 and later:
401 smtp_sasl_tls_verified_security_options ($smtp_sasl_tls_secu‐
403 rity_options)
404 The SASL authentication security options that the Postfix SMTP
405 client uses for TLS encrypted SMTP sessions with a verified
406 server certificate.
407
409 The following configuration parameters exist for compatibility with
410 Postfix versions before 2.3. Support for these will be removed in a
411 future release.
412 smtp_use_tls (no)
414 Opportunistic mode: use TLS when a remote SMTP server announces
415 STARTTLS support, otherwise send the mail in the clear.
416 smtp_enforce_tls (no)
418 Enforcement mode: require that remote SMTP servers use TLS
419 encryption, and never send mail in the clear.
420 smtp_tls_enforce_peername (yes)
422 With mandatory TLS encryption, require that the remote SMTP
423 server hostname matches the information in the remote SMTP
424 server certificate.
425 smtp_tls_per_site (empty)
427 Optional lookup tables with the Postfix SMTP client TLS usage
428 policy by next-hop destination and by remote SMTP server host‐
429 name.
430 smtp_tls_cipherlist (empty)
432 Obsolete Postfix < 2.3 control for the Postfix SMTP client TLS
433 cipher list.
434
436 smtp_destination_concurrency_limit ($default_destination_concur‐
437 rency_limit)
438 The maximal number of parallel deliveries to the same destina‐
439 tion via the smtp message delivery transport.
440 smtp_destination_recipient_limit ($default_destination_recipient_limit)
442 The maximal number of recipients per delivery via the smtp mes‐
443 sage delivery transport.
444 smtp_connect_timeout (30s)
446 The SMTP client time limit for completing a TCP connection, or
447 zero (use the operating system built-in time limit).
448 smtp_helo_timeout (300s)
450 The SMTP client time limit for sending the HELO or EHLO command,
451 and for receiving the initial server response.
452 lmtp_lhlo_timeout (300s)
454 The LMTP client time limit for sending the LHLO command, and for
455 receiving the initial server response.
456 smtp_xforward_timeout (300s)
458 The SMTP client time limit for sending the XFORWARD command, and
459 for receiving the server response.
460 smtp_mail_timeout (300s)
462 The SMTP client time limit for sending the MAIL FROM command,
463 and for receiving the server response.
464 smtp_rcpt_timeout (300s)
466 The SMTP client time limit for sending the SMTP RCPT TO command,
467 and for receiving the server response.
468 smtp_data_init_timeout (120s)
470 The SMTP client time limit for sending the SMTP DATA command,
471 and for receiving the server response.
472 smtp_data_xfer_timeout (180s)
474 The SMTP client time limit for sending the SMTP message content.
475 smtp_data_done_timeout (600s)
477 The SMTP client time limit for sending the SMTP ".", and for
478 receiving the server response.
479 smtp_quit_timeout (300s)
481 The SMTP client time limit for sending the QUIT command, and for
482 receiving the server response.
483 Available in Postfix version 2.1 and later:
485 smtp_mx_address_limit (5)
487 The maximal number of MX (mail exchanger) IP addresses that can
488 result from mail exchanger lookups, or zero (no limit).
489 smtp_mx_session_limit (2)
491 The maximal number of SMTP sessions per delivery request before
492 giving up or delivering to a fall-back relay host, or zero (no
493 limit).
494 smtp_rset_timeout (20s)
496 The SMTP client time limit for sending the RSET command, and for
497 receiving the server response.
498 Available in Postfix version 2.2 and earlier:
500 lmtp_cache_connection (yes)
502 Keep Postfix LMTP client connections open for up to $max_idle
503 seconds.
504 Available in Postfix version 2.2 and later:
506 smtp_connection_cache_destinations (empty)
508 Permanently enable SMTP connection caching for the specified
509 destinations.
510 smtp_connection_cache_on_demand (yes)
512 Temporarily enable SMTP connection caching while a destination
513 has a high volume of mail in the active queue.
514 smtp_connection_reuse_time_limit (300s)
516 The amount of time during which Postfix will use an SMTP connec‐
517 tion repeatedly.
518 smtp_connection_cache_time_limit (2s)
520 When SMTP connection caching is enabled, the amount of time that
521 an unused SMTP client socket is kept open before it is closed.
522 Available in Postfix version 2.3 and later:
524 connection_cache_protocol_timeout (5s)
526 Time limit for connection cache connect, send or receive opera‐
527 tions.
528
530 debug_peer_level (2)
531 The increment in verbose logging level when a remote client or
532 server matches a pattern in the debug_peer_list parameter.
533 debug_peer_list (empty)
535 Optional list of remote client or server hostname or network
536 address patterns that cause the verbose logging level to
537 increase by the amount specified in $debug_peer_level.
538 error_notice_recipient (postmaster)
540 The recipient of postmaster notifications about mail delivery
541 problems that are caused by policy, resource, software or proto‐
542 col errors.
543 internal_mail_filter_classes (empty)
545 What categories of Postfix-generated mail are subject to before-
546 queue content inspection by non_smtpd_milters, header_checks and
547 body_checks.
548 notify_classes (resource, software)
550 The list of error classes that are reported to the postmaster.
551
553 best_mx_transport (empty)
554 Where the Postfix SMTP client should deliver mail when it
555 detects a "mail loops back to myself" error condition.
556 config_directory (see 'postconf -d' output)
558 The default location of the Postfix main.cf and master.cf con‐
559 figuration files.
560 daemon_timeout (18000s)
562 How much time a Postfix daemon process may take to handle a
563 request before it is terminated by a built-in watchdog timer.
564 delay_logging_resolution_limit (2)
566 The maximal number of digits after the decimal point when log‐
567 ging sub-second delay values.
568 disable_dns_lookups (no)
570 Disable DNS lookups in the Postfix SMTP and LMTP clients.
571 inet_interfaces (all)
573 The network interface addresses that this mail system receives
574 mail on.
575 inet_protocols (ipv4)
577 The Internet protocols Postfix will attempt to use when making
578 or accepting connections.
579 ipc_timeout (3600s)
581 The time limit for sending or receiving information over an
582 internal communication channel.
583 lmtp_tcp_port (24)
585 The default TCP port that the Postfix LMTP client connects to.
586 max_idle (100s)
588 The maximum amount of time that an idle Postfix daemon process
589 waits for an incoming connection before terminating voluntarily.
590 max_use (100)
592 The maximal number of incoming connections that a Postfix daemon
593 process will service before terminating voluntarily.
594 process_id (read-only)
596 The process ID of a Postfix command or daemon process.
597 process_name (read-only)
599 The process name of a Postfix command or daemon process.
600 proxy_interfaces (empty)
602 The network interface addresses that this mail system receives
603 mail on by way of a proxy or network address translation unit.
604 smtp_bind_address (empty)
606 An optional numerical network address that the Postfix SMTP
607 client should bind to when making an IPv4 connection.
608 smtp_bind_address6 (empty)
610 An optional numerical network address that the Postfix SMTP
611 client should bind to when making an IPv6 connection.
612 smtp_helo_name ($myhostname)
614 The hostname to send in the SMTP EHLO or HELO command.
615 lmtp_lhlo_name ($myhostname)
617 The hostname to send in the LMTP LHLO command.
618 smtp_host_lookup (dns)
620 What mechanisms when the Postfix SMTP client uses to look up a
621 host's IP address.
622 smtp_randomize_addresses (yes)
624 Randomize the order of equal-preference MX host addresses.
625 syslog_facility (mail)
627 The syslog facility of Postfix logging.
628 syslog_name (postfix)
630 The mail system name that is prepended to the process name in
631 syslog records, so that "smtpd" becomes, for example, "post‐
632 fix/smtpd".
633 Available with Postfix 2.2 and earlier:
635 fallback_relay (empty)
637 Optional list of relay hosts for SMTP destinations that can't be
638 found or that are unreachable.
639 Available with Postfix 2.3 and later:
641 smtp_fallback_relay ($fallback_relay)
643 Optional list of relay hosts for SMTP destinations that can't be
644 found or that are unreachable.
645
647 qmgr(8), queue manager
648 bounce(8), delivery status reports
649 scache(8), connection cache server
650 postconf(5), configuration parameters
651 master(5), generic daemon options
652 master(8), process manager
653 tlsmgr(8), TLS session and PRNG management
654 syslogd(8), system logging
655
657 Use "postconf readme_directory" or "postconf html_directory" to locate
658 this information.
659 SASL_README, Postfix SASL howto
660 TLS_README, Postfix STARTTLS howto
661
663 The Secure Mailer license must be distributed with this software.
664
666 Wietse Venema
667 IBM T.J. Watson Research
668 P.O. Box 704
669 Yorktown Heights, NY 10598, USA
670 Command pipelining in cooperation with:
672 Jon Ribbens
673 Oaktree Internet Solutions Ltd.,
674 Internet House,
675 Canal Basin,
676 Coventry,
677 CV1 4LY, United Kingdom.
678 SASL support originally by:
680 Till Franke
681 SuSE Rhein/Main AG
682 65760 Eschborn, Germany
683 Connection caching in cooperation with:
685 Victor Duchovni
686 Morgan Stanley
687 TLS support originally by:
689 Lutz Jaenicke
690 BTU Cottbus
691 Allgemeine Elektrotechnik
692 Universitaetsplatz 3-4
693 D-03044 Cottbus, Germany
694 SMTP(8)