with Postfix 2.6 and earlier, or specify a non-empty next-hop
filter destination. Files: *qmgr/qmgr_message.c proto/access,
proto/header_checks, proto/postconf.proto, proto/FILTER_README.
+
+20100120
+
+ Cleanup: detect illegal pipelining after HELO, EHLO. File:
+ smtpd/smtpd.c.
+
+20100128
+
+ Documentation: streamlined the decriptions of protocol and
+ cipher tweaks. Victor Duchovni. Files: proto/TLS_README,
+ proto/postconf.proto.
+
+20100131
+
+ Documentation: the address verification database is now
+ persistent by default. This, combined with the now default
+ stress-dependent configuration, improves the performance
+ limits and simplifies database maintenance. Files:
+ proto/ADDRESS_VERIFICATION_README, verify/verify.c.
+
+ Cleanup: undo the proxymap and trivial-rewrite max_idle=1s
+ override that was introduced with Postfix 2.3. It did not
+ help to retire long-lived proxymap or trivial-rewrite
+ processes on busy servers, and worsened performance on
+ low-traffic servers. The reduced ipc_ttl value (introduced
+ with Postfix 2.4) already solves the problem of retiring
+ long-lived proxymap or trivial-rewrite processes. Files:
+ proxymap/proxymap.c, trivial-rewrite/trivial-rewrite.c.
+
+20100202
+
+ Documentation: major revision of SASL_README with many
+ details on how to configure Cyrus SASL internals. Patrick
+ Koetter. File: proto/SASL_README.html
W\bWA\bAR\bRN\bNI\bIN\bNG\bG
-The sender/recipient address verification feature described in this document is
-suitable only for low-traffic sites. It performs poorly under high load;
-excessive sender address verification activity may even cause your site to be
-blacklisted by some providers. See the "Limitations" section below for details.
+Recipient address verification may cause an increased load on down-stream
+servers in the case of a dictionary attack or a flood of backscatter bounces.
+Sender address verification may cause your site to be blacklisted by some
+providers. See also the "Limitations" section below for more.
W\bWh\bha\bat\bt P\bPo\bos\bst\btf\bfi\bix\bx a\bad\bdd\bdr\bre\bes\bss\bs v\bve\ber\bri\bif\bfi\bic\bca\bat\bti\bio\bon\bn c\bca\ban\bn d\bdo\bo f\bfo\bor\br y\byo\bou\bu
The technique has obvious uses to reject junk mail with an unreplyable sender
address.
-The technique may also be useful to block mail for undeliverable recipients,
-for example on a mail relay host that does not have a list of all the valid
+The technique is also useful to block mail for undeliverable recipients, for
+example on a mail relay host that does not have a list of all the valid
recipient addresses. This prevents undeliverable junk mail from entering the
queue, so that Postfix doesn't have to waste resources trying to send MAILER-
DAEMON messages back.
messages are like normal mail, except that they are never delivered, deferred
or bounced; probe messages are always discarded.
- Postfix Postfix Address
- Internet -> SMTP <-> verify <-> verification
- server server database
-
- | ^
- probe delivery
- messages status
- v |
-
- Postfix Postfix
- queue -> delivery
- agents
+
+ probe Postfix
+ message -> mail
+ queue
+ Postfix Postfix ->
+ Internet -> SMTP <-> verify
+ server server |
+ v
+
+ <- Postfix
+ probe <- delivery -> Local
+ status agents -> Remote
+ ^
+ |
+ v
+
+
+ Address
+ verification
+ database
With Postfix address verification turned on, normal mail will suffer only a
short delay of up to 6 seconds while an address is being verified for the first
address, without actually delivering mail to it. If the nearest MTA accepts
the address, then Postfix assumes that the address is deliverable. In
reality, mail for a remote address can bounce AFTER the nearest MTA accepts
- the recipient address.
+ the recipient address, or AFTER the nearest MTA accepts the message
+ content.
* Some sites may blacklist you when you are probing them too often (a probe
is an SMTP session that does not deliver mail), or when you are probing
* Postfix assumes that an address is undeliverable when the nearest MTA for
the address rejects the probe, regardless of the reason for rejection
(client rejected, HELO rejected, MAIL FROM rejected, etc.). Thus, Postfix
- rejects mail when the sender's MTA rejects mail from your machine. This is
- a good thing.
+ rejects an address when the nearest MTA for that address rejects mail from
+ your machine for any reason. This is not a limitation, but it is mentioned
+ here just in case people believe that it is a limitation.
- * Unfortunately, some major sites such as YAHOO do not reject unknown
- addresses in reply to the RCPT TO command, but report a delivery failure in
- response to end of DATA after a message is transferred. Postfix address
- verification does not work with such sites.
+ * Unfortunately, some sites do not reject unknown addresses in reply to the
+ RCPT TO command, but report a delivery failure in response to end of DATA
+ after a message is transferred. Postfix address verification does not work
+ with such sites.
- * By default, Postfix probe messages have "double-bounce@$myorigin" as the
- sender address (with Postfix versions before 2.5, the default is
+ * By default, Postfix probe messages have a sender address "double-
+ bounce@$myorigin" (with Postfix versions before 2.5, the default is
"postmaster@$myorigin"). This is SAFE because the Postfix SMTP server does
not reject mail for this address.
- You can change this into the null address ("address_verify_sender ="). This
- is UNSAFE because address probes will fail with mis-configured sites that
- reject MAIL FROM: <>, while probes from "postmaster@$myorigin" would
- succeed.
+ You can change the probe sender address into the null address
+ ("address_verify_sender ="). This is UNSAFE because address probes will
+ fail with mis-configured sites that reject MAIL FROM: <>, while probes from
+ "postmaster@$myorigin" would succeed.
R\bRe\bec\bci\bip\bpi\bie\ben\bnt\bt a\bad\bdd\bdr\bre\bes\bss\bs v\bve\ber\bri\bif\bfi\bic\bca\bat\bti\bio\bon\bn
-As mentioned earlier, recipient address verification may be useful to block
-mail for undeliverable recipients on a mail relay host that does not have a
-list of all valid recipient addresses. This can help to prevent the mail queue
-from filling up with MAILER-DAEMON messages.
+As mentioned earlier, recipient address verification is useful to block mail
+for undeliverable recipients on a mail relay host that does not have a list of
+all valid recipient addresses. This can help to prevent the mail queue from
+filling up with MAILER-DAEMON messages.
Recipient address verification is relatively straightforward and there are no
surprises. If a recipient probe fails, then Postfix rejects mail for the
increase the load on down-stream MTAs when you're being flooded by backscatter
bounces, or when some spammer is mounting a dictionary attack.
-By default, address verification results are not saved. To avoid probing the
-same address repeatedly, you can store the result in a persistent database as
-described later.
+By default, address verification results are saved in a persistent database
+(Postfix version 2.7 and later; with earlier versions, specify the database in
+main.cf as described later). The persistent database helps to avoid probing the
+same address repeatedly.
/etc/postfix/main.cf:
smtpd_recipient_restrictions =
# Postfix 2.6 and later.
# unverified_sender_defer_code = 250
+ # Default setting for Postfix 2.7 and later.
# Note 1: Be sure to read the "Caching" section below!
# Note 2: Avoid hash files here. Use btree instead.
address_verify_map = btree:/var/lib/postfix/verify
/etc/postfix/sender_access:
+ # Don't do this when you handle lots of email.
aol.com reject_unverified_sender
hotmail.com reject_unverified_sender
bigfoot.com reject_unverified_sender
# Postfix 2.6 and later.
# unverified_sender_reject_reason = Address verification failed
+ # Default setting for Postfix 2.7 and later.
# Note 1: Be sure to read the "Caching" section below!
# Note 2: Avoid hash files here. Use btree instead.
address_verify_map = btree:/var/lib/postfix/verify
A\bAd\bdd\bdr\bre\bes\bss\bs v\bve\ber\bri\bif\bfi\bic\bca\bat\bti\bio\bon\bn d\bda\bat\bta\bab\bba\bas\bse\be
To improve performance, the Postfix verify(8) daemon can save address
-verification results to a persistent database. The address_verify_map (NOTE:
-singular) configuration parameter specifies persistent storage for sender or
-recipient address verification results. If you specify an empty value, all
-address verification results are lost after "postfix reload" or "postfix stop".
+verification results to a persistent database. This is enabled by default with
+Postfix 2.7 and later. The address_verify_map (NOTE: singular) configuration
+parameter specifies persistent storage for sender or recipient address
+verification results. If you specify an empty value, all address verification
+results are lost after "postfix reload" or "postfix stop".
/etc/postfix/main.cf:
# Default setting for Postfix 2.7 and later.
* The verify(8) server verifies that a sender or recipient address is
deliverable before the smtpd(8) server accepts it. The verify(8) server
- injects probe messages into the Postfix queue and processes status updates
- from delivery agents and/or queue manager. This process is described in the
- ADDRESS_VERIFICATION_README document. The verify(8) service is available
- with Postfix version 2.1 and later.
-
- qmgr(8) Delivery
- Network -> smtpd(8) <-> verify(8) -> cleanup(8) -> Postfix -> agents
- queue
-
- \ | /
- v
- \ /
- <- <-
+ queries a cache with address verification results. If a result is not
+ found, the verify(8) server injects a probe message into the Postfix queue
+ and processes the status update from a delivery agent or queue manager.
+ This process is described in the ADDRESS_VERIFICATION_README document. The
+ verify(8) service is available with Postfix version 2.1 and later.
+
+
+ probe Postfix
+ message -> mail
+ queue
+ Network -> smtpd(8) <-> verify(8) ->
+
+ |
+ v
+
+ <- probe Postfix -> Local
+ status <- delivery -> Network
+ ^ agents
+ |
+ v
+
+
+ Address
+ verification
+ cache
+
+ * The postscreen(8) server can be put "in front" of Postfix smtpd(8)
+ processes. Its purpose is to accept connections from the network and to
+ decide what SMTP clients are allowed to talk to Postfix. According to the
+ 2008 MessageLabs annual report, 81% of all email was spam, and 90% of that
+ was sent by botnets. While postscreen(8) keeps the zombies away, more smtpd
+ (8) processes remain available for legitimate clients.
+
+ The postscreen(8) server is still evolving, and is likely to undergo
+ changes that break compatibility with earlier versions. For this reason the
+ postscreen(8) server is not installed with the stable Postfix release.
+
+ zombie
+
+ \
+
+ zombie - - smtpd(8)
+
+ \ /
+
+ other --- postscreen(8)
+
+ / \
+
+ other - - smtpd(8)
+
+ /
+
+ zombie
P\bPo\bos\bst\btf\bfi\bix\bx s\bsu\bup\bpp\bpo\bor\brt\bt c\bco\bom\bmm\bma\ban\bnd\bds\bs
-------------------------------------------------------------------------------
-W\bWA\bAR\bRN\bNI\bIN\bNG\bG
+W\bWa\bar\brn\bni\bin\bng\bg
People who go to the trouble of installing Postfix may have the expectation
-that Postfix is more secure than some other mailers. The Cyrus SASL library is
-a lot of code. With this, Postfix becomes as secure as other mail systems that
-use the Cyrus SASL library. Dovecot provides an alternative that may be worth
-considering.
-
-H\bHo\bow\bw P\bPo\bos\bst\btf\bfi\bix\bx u\bus\bse\bes\bs S\bSA\bAS\bSL\bL a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn i\bin\bnf\bfo\bor\brm\bma\bat\bti\bio\bon\bn
-
-Postfix SASL support (RFC 4954, formerly RFC 2554) can be used to authenticate
-remote SMTP clients to the Postfix SMTP server, and to authenticate the Postfix
-SMTP client to a remote SMTP server.
-
-When receiving mail, the Postfix SMTP server logs the client-provided username,
-authentication method, and sender address to the maillog file, and optionally
-grants mail access via the permit_sasl_authenticated UCE restriction.
-
-When sending mail, the Postfix SMTP client can look up the remote SMTP server
-hostname or destination domain (the address right-hand part) in a SASL password
-table, and if a username/password is found, it will use that username and
-password to authenticate to the remote SMTP server. And as of version 2.3,
-Postfix can be configured to search its SASL password table by the sender email
-address.
-
-This document covers the following topics:
-
- * What SASL implementations are supported
- * Building Postfix with Dovecot SASL support
- * Building the Cyrus SASL library
- * Building Postfix with Cyrus SASL support
- * Enabling SASL authentication in the Postfix SMTP server
- * Dovecot SASL configuration for the Postfix SMTP server
- * Cyrus SASL configuration for the Postfix SMTP server
- * Testing SASL authentication in the Postfix SMTP server
- * Trouble shooting the SASL internals
- * Enabling SASL authentication in the Postfix SMTP client
- * Supporting multiple ISP accounts in the Postfix SMTP client
+that Postfix is more secure than some other mailers. The Cyrus SASL library
+contains a lot of code. With this, Postfix becomes as secure as other mail
+systems that use the Cyrus SASL library. Dovecot provides an alternative that
+may be worth considering.
+
+H\bHo\bow\bw P\bPo\bos\bst\btf\bfi\bix\bx u\bus\bse\bes\bs S\bSA\bAS\bSL\bL a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn
+
+When an SMTP client connects to an SMTP server, the server needs to decide
+whether that client is authorized to send mail to remote destinations, or
+whether the client can send mail only to the destinations that the server
+itself is responsible for. Usually, the SMTP server will allow mail to remote
+destinations only if the client's IP address is in the "same network" as the
+server's IP address.
+
+Sometimes the SMTP client and server are in different networks, but the client
+still needs "same network" privileges. To address this problem, Postfix
+supports SASL authentication (RFC 4954, formerly RFC 2554). With this a remote
+SMTP client can authenticate to the Postfix SMTP server, and the Postfix SMTP
+client can authenticate to a remote SMTP server. Once the client is
+authenticated the server can give it "same network" privileges.
+
+Postfix does not implement SASL itself, but instead uses existing
+implementations as building blocks. This means that some SASL-related
+configuration will involve files that belong to Postfix, while other
+configuration will involve files that belong to the specific SASL
+implementation that Postfix will use. This document covers both the Postfix and
+non-Postfix configuration.
+
+You can read more about the following topics:
+
+ * Configuring SASL authentication in the Postfix SMTP server
+ * Configuring SASL authentication in the Postfix SMTP/LMTP client
+ * Building Postfix with SASL support
+ * Using Cyrus SASL version 1.5.x
* Credits
-W\bWh\bha\bat\bt S\bSA\bAS\bSL\bL i\bim\bmp\bpl\ble\bem\bme\ben\bnt\bta\bat\bti\bio\bon\bns\bs a\bar\bre\be s\bsu\bup\bpp\bpo\bor\brt\bte\bed\bd
+C\bCo\bon\bnf\bfi\big\bgu\bur\bri\bin\bng\bg S\bSA\bAS\bSL\bL a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn i\bin\bn t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP s\bse\ber\brv\bve\ber\br
-This document describes Postfix with the following SASL implementations:
+As mentioned earlier, SASL is implemented separately from Postfix. For this
+reason, configuring SASL authentication in the Postfix SMTP server involves two
+different steps:
- * Cyrus SASL version 1 (client and server).
+ * Configuring the SASL implementation to offer a list of mechanisms that are
+ suitable for SASL authentication and, depending on the SASL implementation
+ used, configuring authentication backends that verify the remote SMTP
+ client's authentication data against the system password file or some other
+ database.
- * Cyrus SASL version 2 (client and server).
+ * Configuring the Postfix SMTP server to enable SASL authentication, and to
+ authorize clients to relay mail or to control what envelope sender
+ addresses the client may use.
- * Dovecot protocol version 1 (server only, Postfix version 2.3 and later)
+Successful authentication in the Postfix SMTP server requires a functional SASL
+framework. Configuring SASL should therefore always be the first step.
-Postfix version 2.3 introduces a plug-in mechanism that provides support for
-multiple SASL implementations. To find out what implementations are built into
-Postfix, use the following commands:
+You can read more about the following topics:
- % postconf -a (SASL support in the SMTP server)
- % postconf -A (SASL support in the SMTP+LMTP client)
+ * Which SASL Implementations are supported?
+ * Configuring Dovecot SASL
-Needless to say, these commands are not available in earlier Postfix versions.
+ o Postfix to Dovecot SASL communication
-B\bBu\bui\bil\bld\bdi\bin\bng\bg P\bPo\bos\bst\btf\bfi\bix\bx w\bwi\bit\bth\bh D\bDo\bov\bve\bec\bco\bot\bt S\bSA\bAS\bSL\bL s\bsu\bup\bpp\bpo\bor\brt\bt
+ * Configuring Cyrus SASL
-These instructions assume that you build Postfix from source code as described
-in the INSTALL document. Some modification may be required if you build Postfix
-from a vendor-specific source package.
+ o Cyrus SASL configuration file name
+ o Cyrus SASL configuration file location
+ o Postfix to Cyrus SASL communication
-Support for the Dovecot version 1 SASL protocol is available in Postfix 2.3 and
-later. At the time of writing, only server-side SASL support is available, so
-you can't use it to authenticate to your network provider's server. Dovecot
-uses its own daemon process for authentication. This keeps the Postfix build
-process simple, because there is no need to link extra libraries into Postfix.
+ * Enabling SASL authentication and authorization in the Postfix SMTP server
-To generate the necessary Makefiles, execute the following in the Postfix top-
-level directory:
+ o Enabling SASL authentication in the Postfix SMTP server
+ o Postfix SMTP Server Authentication Policy
+ o Enabling SASL authorization in the Postfix SMTP server
+ o Additional SMTP Server SASL options
- % make makefiles CCARGS='-DUSE_SASL_AUTH -
- DDEF_SERVER_SASL_TYPE=\"dovecot\"'
+ * Testing SASL authentication in the Postfix SMTP server
-After this, proceed with "make" as described in the INSTALL document.
+W\bWh\bhi\bic\bch\bh S\bSA\bAS\bSL\bL I\bIm\bmp\bpl\ble\bem\bme\ben\bnt\bta\bat\bti\bio\bon\bns\bs a\bar\bre\be s\bsu\bup\bpp\bpo\bor\brt\bte\bed\bd?\b?
-Notes:
+Currently the Postfix SMTP server supports the Cyrus SASL and Dovecot SASL
+implementations.
- * The "-DDEF_SERVER_SASL_TYPE" stuff is not necessary; it just makes Postfix
- configuration a little more convenient because you don't have to specify
- the SASL plug-in type in the Postfix main.cf file.
+ N\bNo\bot\bte\be
- * If you also want support for LDAP or TLS, you will have to merge their
- CCARGS and AUXLIBS into the above command line.
+ Before Postfix version 2.3, Postfix had support only for Cyrus SASL.
+ Current Postfix versions have a plug-in architecture that can support
+ multiple SASL implementations.
-B\bBu\bui\bil\bld\bdi\bin\bng\bg t\bth\bhe\be C\bCy\byr\bru\bus\bs S\bSA\bAS\bSL\bL l\bli\bib\bbr\bra\bar\bry\by
+To find out what SASL implementations are compiled into Postfix, use the
+following commands:
-Postfix appears to work with cyrus-sasl-1.5.x or cyrus-sasl-2.1.x, which are
-available from:
+ % p\bpo\bos\bst\btc\bco\bon\bnf\bf -\b-a\ba (SASL support in the SMTP server)
+ % p\bpo\bos\bst\btc\bco\bon\bnf\bf -\b-A\bA (SASL support in the SMTP+LMTP client)
- ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/
+These commands are available only with Postfix version 2.3 and later.
-IMPORTANT: if you install the Cyrus SASL libraries as per the default, you will
-have to symlink /usr/lib/sasl -> /usr/local/lib/sasl for version 1.5.x or /usr/
-lib/sasl2 -> /usr/local/lib/sasl2 for version 2.1.x.
+C\bCo\bon\bnf\bfi\big\bgu\bur\bri\bin\bng\bg D\bDo\bov\bve\bec\bco\bot\bt S\bSA\bAS\bSL\bL
-Reportedly, Microsoft Outlook (Express) requires the non-standard LOGIN
-authentication method. To enable this authentication method, specify ``./
-configure --enable-login''.
+Dovecot is a POP/IMAP server that must be configured to authenticate POP/IMAP
+clients. When the Postfix SMTP server uses Dovecot SASL, it also reuses this
+configuration. Consult the Dovecot documentation for how to configure and
+operate the Dovecot authentication server.
-B\bBu\bui\bil\bld\bdi\bin\bng\bg P\bPo\bos\bst\btf\bfi\bix\bx w\bwi\bit\bth\bh C\bCy\byr\bru\bus\bs S\bSA\bAS\bSL\bL s\bsu\bup\bpp\bpo\bor\brt\bt
+P\bPo\bos\bst\btf\bfi\bix\bx t\bto\bo D\bDo\bov\bve\bec\bco\bot\bt S\bSA\bAS\bSL\bL c\bco\bom\bmm\bmu\bun\bni\bic\bca\bat\bti\bio\bon\bn
-These instructions assume that you build Postfix from source code as described
-in the INSTALL document. Some modification may be required if you build Postfix
-from a vendor-specific source package.
+Communication between the Postfix SMTP server and Dovecot SASL happens via a
+UNIX-domain socket. The socket pathname and the list of mechanisms offered to
+Postfix need to be specified on the Dovecot server side in dovecot.conf.
-The following assumes that the Cyrus SASL include files are in /usr/local/
-include, and that the Cyrus SASL libraries are in /usr/local/lib.
+The following example assumes that the Postfix queue is under /var/spool/
+postfix/.
-On some systems this generates the necessary Makefile definitions:
+ 1 /etc/dovecot.conf:
+ 2 auth default {
+ 3 mechanisms = plain login
+ 4 passdb pam {
+ 5 }
+ 6 userdb passwd {
+ 7 }
+ 8 socket listen {
+ 9 client {
+ 10 path = /var/spool/postfix/private/auth
+ 11 mode = 0660
+ 12 user = postfix
+ 13 group = postfix
+ 14 }
+ 15 }
+ 16 }
-(for Cyrus SASL version 1.5.x):
+Line 3 provides plain and login as mechanisms for the Postfix SMTP server, line
+10 places the Dovecot SASL socket in /var/spool/postfix/private/auth, and lines
+11-13 limit read+write permissions to user and group postfix only.
- % make tidy # if you have left-over files from a previous build
- % make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
- -I/usr/local/include" AUXLIBS="-L/usr/local/lib -lsasl"
+Proceed with the section "Enabling SASL authentication and authorization in the
+Postfix SMTP server" to turn on and use SASL in the Postfix SMTP server.
-(for Cyrus SASL version 2.1.x):
+C\bCo\bon\bnf\bfi\big\bgu\bur\bri\bin\bng\bg C\bCy\byr\bru\bus\bs S\bSA\bAS\bSL\bL
- % make tidy # if you have left-over files from a previous build
- % make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
- -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib -lsasl2"
+The Cyrus SASL framework was supports a wide variety of applications. Different
+applications may require different configurations. As a consequence each
+application may have its own configuration file.
-On Solaris 2.x you need to specify run-time link information, otherwise ld.so
-will not find the SASL shared library:
+The first step configuring Cyrus SASL is to determine name and location of a
+configuration file that describes how the Postfix SMTP server will use the SASL
+framework.
-(for Cyrus SASL version 1.5.x):
+C\bCy\byr\bru\bus\bs S\bSA\bAS\bSL\bL c\bco\bon\bnf\bfi\big\bgu\bur\bra\bat\bti\bio\bon\bn f\bfi\bil\ble\be n\bna\bam\bme\be
- % make tidy # if you have left-over files from a previous build
- % make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
- -I/usr/local/include" AUXLIBS="-L/usr/local/lib \
- -R/usr/local/lib -lsasl"
+The name of the configuration file (default: smtpd.conf) is configurable. It is
+a concatenation from a value that the Postfix SMTP server sends to the Cyrus
+SASL library, and the suffix .conf, added by Cyrus SASL.
-(for Cyrus SASL version 2.1.x):
+The value sent by Postfix is the name of the server component that will use
+Cyrus SASL. It defaults to smtpd and is configured with one of the following
+variables:
- % make tidy # if you have left-over files from a previous build
- % make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
- -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib \
- -R/usr/local/lib -lsasl2"
+ /etc/postfix/main.cf:
+ # Postfix 2.3 and later
+ smtpd_sasl_path = smtpd
-E\bEn\bna\bab\bbl\bli\bin\bng\bg S\bSA\bAS\bSL\bL a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn i\bin\bn t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP s\bse\ber\brv\bve\ber\br
+ # Postfix < 2.3
+ smtpd_sasl_application_name = smtpd
+
+C\bCy\byr\bru\bus\bs S\bSA\bAS\bSL\bL c\bco\bon\bnf\bfi\big\bgu\bur\bra\bat\bti\bio\bon\bn f\bfi\bil\ble\be l\blo\boc\bca\bat\bti\bio\bon\bn
+
+The location where Cyrus SASL searches for the named file depends on the Cyrus
+SASL version and the OS/distribution used.
+
+You can read more about the following topics:
+
+ * Cyrus SASL version 2.x searches for the configuration file in /usr/lib/
+ sasl2/.
+
+ * Cyrus SASL version 2.1.22 and newer additionally search in /etc/sasl2/.
+
+ * Some Postfix distributions are modified and look for the Cyrus SASL
+ configuration file in /etc/postfix/sasl/, /var/lib/sasl2/ etc. See the
+ distribution-specific documentation to determine the expected location.
+
+ N\bNo\bot\bte\be
+
+ Cyrus SASL searches /usr/lib/sasl2/ first. If it finds the specified
+ configuration file there, it will not examine other locations.
+
+P\bPo\bos\bst\btf\bfi\bix\bx t\bto\bo C\bCy\byr\bru\bus\bs S\bSA\bAS\bSL\bL c\bco\bom\bmm\bmu\bun\bni\bic\bca\bat\bti\bio\bon\bn
+
+As the Postfix SMTP server is linked with the Cyrus SASL library libsasl,
+communication between Postfix and Cyrus SASL takes place by calling functions
+in the SASL library.
+
+The SASL library may use an external password verification service, or an
+internal plugin to connect to authentication backends and verify the SMTP
+client's authentication data against the system password file or other
+databases.
+
+The following table shows typical combinations discussed in this document:
+
+ _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b
+ | a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn b\bba\bac\bck\bke\ben\bnd\bd |p\bpa\bas\bss\bsw\bwo\bor\brd\bd v\bve\ber\bri\bif\bfi\bic\bca\bat\bti\bio\bon\bn s\bse\ber\brv\bvi\bic\bce\be /\b/ p\bpl\blu\bug\bgi\bin\bn|
+ |_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+ |/etc/shadow |saslauthd |
+ |_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+ |PAM |saslauthd |
+ |_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+ |IMAP server |saslauthd |
+ |_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+ |sasldb |sasldb |
+ |_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+ |MySQL, PostgreSQL, SQLite|sql |
+ |_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+ |LDAP |ldapdb |
+ |_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b|_\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b _\b |
+
+ N\bNo\bot\bte\be
+
+ Read the Cyrus SASL documentation for other backends it can use.
+
+s\bsa\bas\bsl\bla\bau\but\bth\bhd\bd -\b- C\bCy\byr\bru\bus\bs S\bSA\bAS\bSL\bL p\bpa\bas\bss\bsw\bwo\bor\brd\bd v\bve\ber\bri\bif\bfi\bic\bca\bat\bti\bio\bon\bn s\bse\ber\brv\bvi\bic\bce\be
+
+Communication between the Postfix SMTP server (read: Cyrus SASL's libsasl) and
+the saslauthd server takes place over a UNIX-domain socket.
+
+saslauthd usually establishes the UNIX domain socket in /var/run/saslauthd/ and
+waits for authentication requests. The Postfix SMTP server must have
+read+execute permission to this directory or authentication attempts will fail.
+
+ I\bIm\bmp\bpo\bor\brt\bta\ban\bnt\bt
+
+ Some distributions require the user postfix to be member of a special group
+ e.g. sasl, otherwise it will not be able to access the saslauthd socket
+ directory.
+
+The following example configures the Cyrus SASL library to contact saslauthd as
+its password verification service:
+
+ /etc/sasl2/smtpd.conf:
+ pwcheck_method: saslauthd
+ mech_list: PLAIN LOGIN
+
+ I\bIm\bmp\bpo\bor\brt\bta\ban\bnt\bt
+
+ Do not specify any other mechanisms in mech_list than PLAIN or LOGIN when
+ using saslauthd! It can only handle these two mechanisms, and
+ authentication will fail if clients are allowed to choose other mechanisms.
+
+ I\bIm\bmp\bpo\bor\brt\bta\ban\bnt\bt
+
+ Plaintext mechanisms (PLAIN, LOGIN) send credentials unencrypted. This
+ information should be protected by an additional security layer such as a
+ TLS-encrypted SMTP session (see: TLS_README).
+
+Additionally the saslauthd server itself must be configured. It must be told
+which authentication backend to turn to for password verification. The backend
+is choosen as a command line option when saslauthd is started and will be shown
+in the following examples.
+
+ N\bNo\bot\bte\be
+
+ Some distributions use a configuration file to provide saslauthd command
+ line options to set e.g. the authentication backend. Typical locations are
+ /etc/sysconfig/saslauthd or /etc/default/saslauthd.
+
+U\bUs\bsi\bin\bng\bg s\bsa\bas\bsl\bla\bau\but\bth\bhd\bd w\bwi\bit\bth\bh /\b/e\bet\btc\bc/\b/s\bsh\bha\bad\bdo\bow\bw
+
+Access to the /etc/shadow system password file requires root privileges. The
+Postfix SMTP server (and in consequence libsasl linked to the server) runs with
+the least privilege possible. Direct access to /etc/shadow would not be
+possible without breaking the Postfix security architecture.
+
+The saslauthd socket builds a safe bridge. Postfix, running as limited user
+postfix, can access the UNIX-domain socket that saslauthd receives commands on;
+saslauthd, running as privileged user root, has the privileges required to
+access the shadow file.
+
+The saslauthd server verifies passwords against the authentication backend /
+etc/shadow if started like this:
+
+ % s\bsa\bas\bsl\bla\bau\but\bth\bhd\bd -\b-a\ba s\bsh\bha\bad\bdo\bow\bw
+
+See section "Testing saslauthd authentication" for test instructions.
+
+U\bUs\bsi\bin\bng\bg s\bsa\bas\bsl\bla\bau\but\bth\bhd\bd w\bwi\bit\bth\bh P\bPA\bAM\bM
+
+Cyrus SASL can use the PAM framework to authenticate credentials. saslauthd
+uses the PAM framework when started like this:
+
+ % s\bsa\bas\bsl\bla\bau\but\bth\bhd\bd -\b-a\ba p\bpa\bam\bm
+
+ N\bNo\bot\bte\be
+
+ PAM configuration for the Postfix SMTP server is usually given in /etc/
+ pam.d/smtp and is beyond the scope of this document.
+
+See section "Testing saslauthd authentication" for test instructions.
+
+U\bUs\bsi\bin\bng\bg s\bsa\bas\bsl\bla\bau\but\bth\bhd\bd w\bwi\bit\bth\bh a\ban\bn I\bIM\bMA\bAP\bP s\bse\ber\brv\bve\ber\br
+
+saslauthd can verify the SMTP client credentials by using them to log into an
+IMAP server. If the login succeeds, SASL authentication also succeeds.
+saslauthd contacts an IMAP server when started like this:
+
+ % s\bsa\bas\bsl\bla\bau\but\bth\bhd\bd -\b-a\ba r\bri\bim\bma\bap\bp -\b-O\bO i\bim\bma\bap\bp.\b.e\bex\bxa\bam\bmp\bpl\ble\be.\b.c\bco\bom\bm
+
+ N\bNo\bot\bte\be
+
+ The option "-O imap.example.com" specifies the IMAP server saslauthd should
+ contact when it verifies credentials.
+
+ I\bIm\bmp\bpo\bor\brt\bta\ban\bnt\bt
+
+ saslauthd sends IMAP login information unencrypted. Any IMAP session
+ leaving the local host should be protected by an additional security layer
+ such as an SSL tunnel.
+
+See section "Testing saslauthd authentication" for test instructions.
+
+T\bTe\bes\bst\bti\bin\bng\bg s\bsa\bas\bsl\bla\bau\but\bth\bhd\bd a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn
+
+Cyrus SASL provides the testsaslauthd utility to test saslauthd authentication.
+The username and password are given as command line arguments. The example
+shows the response when authentication is successful:
+
+ % t\bte\bes\bst\bts\bsa\bas\bsl\bla\bau\but\bth\bhd\bd -\b-u\bu u\bus\bse\ber\brn\bna\bam\bme\be -\b-p\bp p\bpa\bas\bss\bsw\bwo\bor\brd\bd
+ 0: OK "Success."
+
+ N\bNo\bot\bte\be
+
+ Sometimes the testsaslauthd program is not distributed with a the Cyrus
+ SASL main package. In that case, it may be distributed with -devel, -dev or
+ -debug packages.
+
+Specify an additional "-s smtp" if saslauthd was configured to contact the PAM
+authentication framework and an additional "-f /\b/p\bpa\bat\bth\bh/\b/t\bto\bo/\b/s\bso\boc\bck\bke\bet\btd\bdi\bir\br/\b/m\bmu\bux\bx" if
+saslauthd establishes the UNIX-domain socket in a non-default location.
+
+If authentication succeeds, proceed with the section "Enabling SASL
+authentication and authorization in the Postfix SMTP server".
+
+C\bCy\byr\bru\bus\bs S\bSA\bAS\bSL\bL P\bPl\blu\bug\bgi\bin\bns\bs -\b- a\bau\bux\bxi\bil\bli\bia\bar\bry\by p\bpr\bro\bop\bpe\ber\brt\bty\by p\bpl\blu\bug\bgi\bin\bns\bs
+
+Cyrus SASL uses a plugin infrastructure (called auxprop) to expand libsasl's
+capabilities. Currently Cyrus SASL sources provide three authentication
+plugins.
+
+ sasldb
+ Accounts are stored stored in a Cyrus SASL Berkeley DB database
+
+ sql
+ Accounts are stored in a SQL database
+
+ ldapdb
+ Accounts are stored stored in an LDAP database
-In order to enable SASL support in the Postfix SMTP server:
+ I\bIm\bmp\bpo\bor\brt\bta\ban\bnt\bt
+
+ These three plugins support shared-secret mechanisms i.e. CRAM-MD5, DIGEST-
+ MD5 and NTLM. These mechanisms send credentials encrypted but their
+ verification process requires the password to be available in plaintext.
+ Consequently passwords cannot (!) be stored in encrypted form.
+
+T\bTh\bhe\be s\bsa\bas\bsl\bld\bdb\bb p\bpl\blu\bug\bgi\bin\bn
+
+The sasldb auxprop plugin authenticates credentials stored in a Berkeley DB
+database. The database schema is specific to Cyrus SASL. The database is
+usually located at /etc/sasldb2.
+
+ N\bNo\bot\bte\be
+
+ The sasldb2 file contains passwords in plaintext, and should have
+ read+write access only to user postfix or a group that postfix is member
+ of.
+
+The saslpasswd2 command-line utility creates and maintains the database:
+
+ % s\bsa\bas\bsl\blp\bpa\bas\bss\bsw\bwd\bd2\b2 -\b-c\bc -\b-u\bu e\bex\bxa\bam\bmp\bpl\ble\be.\b.c\bco\bom\bm u\bus\bse\ber\brn\bna\bam\bme\be
+ Password:
+ Again (for verification):
+
+This command creates an account u\bus\bse\ber\brn\bna\bam\bme\be@\b@e\bex\bxa\bam\bmp\bpl\ble\be.\b.c\bco\bom\bm.
+
+ I\bIm\bmp\bpo\bor\brt\bta\ban\bnt\bt
+
+ users must specify u\bus\bse\ber\brn\bna\bam\bme\be@\b@e\bex\bxa\bam\bmp\bpl\ble\be.\b.c\bco\bom\bm as login name, not u\bus\bse\ber\brn\bna\bam\bme\be.
+
+Run the following command to reuse the Postfix mydomain parameter value as the
+login domain:
+
+ % s\bsa\bas\bsl\blp\bpa\bas\bss\bsw\bwd\bd2\b2 -\b-c\bc -\b-u\bu `\b`p\bpo\bos\bst\btc\bco\bon\bnf\bf -\b-h\bh m\bmy\byd\bdo\bom\bma\bai\bin\bn`\b` u\bus\bse\ber\brn\bna\bam\bme\be
+ Password:
+ Again (for verification):
+
+ N\bNo\bot\bte\be
+
+ Run saslpasswd2 without any options for further help on how to use the
+ command.
+
+The sasldblistusers2 command lists all existing users in the sasldb database:
+
+ % s\bsa\bas\bsl\bld\bdb\bbl\bli\bis\bst\btu\bus\bse\ber\brs\bs2\b2
+ username1@example.com: password1
+ username2@example.com: password2
+
+Configure libsasl to use sasldb with the following instructions:
+
+ /etc/sasl2/smtpd.conf:
+ pwcheck_method: auxprop
+ auxprop_plugin: sasldb
+ mech_list: PLAIN LOGIN CRAM-MD5 DIGEST-MD5 NTLM
+
+ N\bNo\bot\bte\be
+
+ In the above example adjust mech_list to the mechanisms that are applicable
+ for your environment.
+
+T\bTh\bhe\be s\bsq\bql\bl p\bpl\blu\bug\bgi\bin\bn
+
+The sql auxprop plugin is a generic SQL plugin. It provides access to
+credentials stored in a MySQL, a PostgreSQL or a SQLite database.
+
+ N\bNo\bot\bte\be
+
+ The shared-secret mechanisms (CRAM-MD5, etc.) require that the SASL client
+ passwords are stored as plaintext.
+
+ T\bTi\bip\bp
+
+ Use "saslauthd > pam > (pam database module)" to verify encrypted passwords
+ in an SQL database.
+
+The following example configures libsasl to use the sql plugin and connects it
+to a PostgreSQL server:
+
+ /etc/sasl2/smtpd.conf:
+ pwcheck_method: auxprop
+ auxprop_plugin: sql
+ mech_list: PLAIN LOGIN CRAM-MD5 DIGEST-MD5 NTLM
+ sql_engine: pgsql
+ sql_hostnames: 127.0.0.1, 192.0.2.1 sql_user: username
+ sql_passwd: secret
+ sql_database: dbname
+ sql_select: SELECT password FROM users WHERE user = '%u'@'%r'
+
+ N\bNo\bot\bte\be
+
+ Set appropriate permissions if smtpd.conf contains a password. The file
+ should be readable by the postfix user.
+
+ N\bNo\bot\bte\be
+
+ In the above example, adjust mech_list to the mechanisms that are
+ applicable for your environment.
+
+The sql plugin has the following configuration options:
+
+ sql_engine
+ Specify mysql to connect to a MySQL server, pgsql for a PostgreSQL
+ server or sqlite for an SQLite database
+
+ sql_hostnames
+ Specify one or more servers (hostname or hostname:port) separated by
+ commas.
+
+ N\bNo\bot\bte\be
+
+ With MySQL servers, specify localhost to connect over a UNIX-domain
+ socket, and specify 127.0.0.1 to connect over a TCP socket.
+
+ sql_user
+ The login name to gain access to the database.
+
+ sql_passwd
+ The password to gain access to the database.
+
+ sql_database
+ The name of the database to connect to.
+
+ sql_select
+ The SELECT statement that should retrieve the plaintext password from a
+ database table.
+
+ I\bIm\bmp\bpo\bor\brt\bta\ban\bnt\bt
+
+ Do not enclose the statement in quotes! Use single quotes to escape
+ macros!
+
+The sql plugin provides macros to build sql_select statements. They will be
+replaced with arguments sent from the client. The following macros are
+available:
+
+ %u
+ The name of the user whose properties are being selected.
+
+ %p
+ The name of the property being selected. While this could technically
+ be anything, Cyrus SASL will try userPassword and cmusaslsecretMECHNAME
+ (where MECHNAME is the name of a SASL mechanism).
+
+ %r
+ The name of the realm to which the user belongs. This could be the
+ KERBEROS realm, the fully-qualified domain name of the computer the
+ SASL application is running on, or the domain after the "@" in a
+ username.
+
+T\bTh\bhe\be l\bld\bda\bap\bpd\bdb\bb p\bpl\blu\bug\bgi\bin\bn
+
+The ldapdb auxprop plugin provides access to credentials stored in an OpenLDAP
+LDAP server. It is the only plugin that implements proxy authorization.
+
+Proxy authorization in this context means: The ldapdb plugin must SASL
+authenticate with the OpenLDAP server. The server then decides if the ldapdb
+plugin should be authorized to read the authenticating user's password. Once
+the ldapdb plugin has gone through proxy authorization it may proceed and
+authenticate the remote SMTP client's credentials.
+
+In a nutshell: Configuring ldapdb means authentication and authorization must
+be configured twice - once in the Postfix SMTP server to authenticate and
+authorize the remote SMTP client, and once in the OpenLDAP slapd server to
+authenticate and authorize the ldapdb plugin.
+
+This example configures libsasl to use the ldapdb plugin and the plugin to
+connect to an OpenLDAP server:
+
+ /etc/sasl2/smtpd.conf:
+ pwcheck_method: auxprop
+ auxprop_plugin: ldapdb
+ mech_list: PLAIN LOGIN NTLM CRAM-MD5 DIGEST-MD5
+ ldapdb_uri: ldap://localhost
+ ldapdb_id: proxyuser
+ ldapdb_pw: password
+ ldapdb_mech: DIGEST-MD5
+
+ I\bIm\bmp\bpo\bor\brt\bta\ban\bnt\bt
+
+ Set appropriate permissions if smtpd.conf contains a password. The file
+ should be readable by the postfix user.
+
+ N\bNo\bot\bte\be
+
+ The shared-secret mechanisms (CRAM-MD5, etc.) require that the SASL client
+ passwords are stored as plaintext.
+
+The following is a summary of applicable smtpd.conf file entries:
+
+ auxprop_plugin
+ Specify ldapdb to enable the plugin.
+
+ ldapdb_uri
+ Specify either ldapi:// for to connect over a UNIX-domain socket, ldap:
+ // for an unencrypted TCP connection or ldaps:// for an encrypted TCP
+ connection.
+
+ ldapdb_id
+ The login name to authenticate the ldapdb plugin to the LDAP server
+ (proxy authorization).
+
+ ldapdb_pw
+ The password (in plaintext) to authenticate the ldapdb plugin to the
+ LDAP server (proxy authorization).
+
+ ldapdb_mech
+ The mechanism to authenticate the ldapdb plugin to the OpenLDAP slapd
+ server.
+
+ N\bNo\bot\bte\be
+
+ Specify a mechanism here that is supported by the OpenLDAP slapd
+ server.
+
+ ldapdb_rc (optional)
+ The path to a file containing individual configuration options for the
+ ldapdb LDAP client (libldap). This allows to specify a TLS client
+ certificate which in turn can be used to use the SASL EXTERNAL
+ mechanism.
+
+ N\bNo\bot\bte\be
+
+ This mechanism supports authentication over an encrypted transport
+ layer, which is recommended if the plugin must connect to an
+ OpenLDAP server on a remote machine.
+
+ ldapdb_starttls (optional)
+ The TLS policy for connecting to the LDAP server. Specify either try or
+ demand. If the option is try the plugin will attempt to establish a
+ TLS-encrypted connection with the LDAP server, and will fallback to an
+ unencrypted connection if TLS fails. If the policy is demand and a TLS-
+ encrypted connection cannot be established, the connection fails
+ immediately.
+
+When the ldapdb plugin connects to the OpenLDAP server and successfully
+authenticates, the OpenLDAP server decides if the plugin user is authorized to
+read SASL account information.
+
+The following configuration gives an example of authorization configuration in
+the OpenLDAP slapd server:
+
+ /etc/openldap/slapd.conf:
+ authz-regexp
+ uid=(.*),cn=.*,cn=auth
+ ldap:///dc=example,dc=com??sub?cn=$1
+ authz-policy to
+
+Here, the authz-regexp option serves for authentication of the ldapdb user. It
+maps its login name to a DN in the LDAP directory tree where slapd can look up
+the SASL account information. The authz-policy options defines the
+authentication policy. In this case it grants authentication privileges "to"
+the ldapdb plugin.
+
+The last configuration step is to tell the OpenLDAP slapd server where ldapdb
+may search for usernames matching the one given by the mail client. The example
+below adds an additional attribute ldapdb user object (here: authzTo because
+the authz-policy is "to") and configures the scope where the login name
+"proxyuser" may search:
+
+ dn: cn=proxyuser,dc=example,dc=com
+ changetype: modify
+ add: authzTo
+ authzTo: dn.regex:uniqueIdentifier=(.*),ou=people,dc=example,dc=com
+
+Use the ldapmodify or ldapadd command to add the above attribute.
+
+ N\bNo\bot\bte\be
+
+ Read the chapter "Using SASL" in the OpenLDAP Admin Guide for more detailed
+ instructions to set up SASL authentication in OpenLDAP.
+
+E\bEn\bna\bab\bbl\bli\bin\bng\bg S\bSA\bAS\bSL\bL a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn a\ban\bnd\bd a\bau\but\bth\bho\bor\bri\biz\bza\bat\bti\bio\bon\bn i\bin\bn t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP s\bse\ber\brv\bve\ber\br
+
+By default the Postfix SMTP server uses the Cyrus SASL implementation. If the
+Dovecot SASL implementation should be used, specify an smtpd_sasl_type value of
+dovecot instead of cyrus:
/etc/postfix/main.cf:
- smtpd_sasl_auth_enable = yes
+ smtpd_sasl_type = dovecot
-In order to allow mail relaying by authenticated remote SMTP clients:
+Additionally set the path where the Postfix SMTP server can find the Dovecot
+SASL socket:
/etc/postfix/main.cf:
- smtpd_recipient_restrictions =
- permit_mynetworks
- permit_sasl_authenticated
- reject_unauth_destination
+ smtpd_sasl_path = private/auth
-To report SASL login names in Received: message headers (Postfix version 2.3
-and later):
+ N\bNo\bot\bte\be
+
+ This example uses a pathname relative to the Postfix queue directory, so
+ that it will work whether or not the Postfix SMTP server runs chrooted.
+
+E\bEn\bna\bab\bbl\bli\bin\bng\bg S\bSA\bAS\bSL\bL a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn i\bin\bn t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP s\bse\ber\brv\bve\ber\br
+
+Regardless of the SASL implementation type, enabling SMTP authentication in the
+Postfix SMTP server always requires seting the smtpd_sasl_auth_enable option:
/etc/postfix/main.cf:
- smtpd_sasl_authenticated_header = yes
+ smtpd_sasl_auth_enable = yes
+
+After a "postfix reload", SMTP clients will see the additional capability AUTH
+in an SMTP session, followed by a list of authentication mechanisms the server
+supports:
+
+ % t\bte\bel\bln\bne\bet\bt s\bse\ber\brv\bve\ber\br.\b.e\bex\bxa\bam\bmp\bpl\ble\be.\b.c\bco\bom\bm 2\b25\b5
+ ...
+ 220 server.example.com ESMTP Postfix
+ E\bEH\bHL\bLO\bO c\bcl\bli\bie\ben\bnt\bt.\b.e\bex\bxa\bam\bmp\bpl\ble\be.\b.c\bco\bom\bm
+ 250-server.example.com
+ 250-PIPELINING
+ 250-SIZE 10240000
+ 250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
+ ...
-Note: the SASL login names will be shared with the entire world.
+However not all clients recognize the AUTH capability as defined by the SASL
+authentication RFC. Some historical implementations expect the server to send
+an "=" as separator between the AUTH verb and the list of mechanisms that
+follows it.
-Older Microsoft SMTP client software implements a non-standard version of the
-AUTH protocol syntax, and expects that the SMTP server replies to EHLO with
-"250 AUTH=mechanism-list" instead of "250 AUTH mechanism-list". To accommodate
-such clients (in addition to conformant clients) use the following:
+The broken_sasl_auth_clients configuration option lets Postfix repeat the AUTH
+statement in a form that these broken clients understand:
/etc/postfix/main.cf:
broken_sasl_auth_clients = yes
-D\bDo\bov\bve\bec\bco\bot\bt S\bSA\bAS\bSL\bL c\bco\bon\bnf\bfi\big\bgu\bur\bra\bat\bti\bio\bon\bn f\bfo\bor\br t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP s\bse\ber\brv\bve\ber\br
+ N\bNo\bot\bte\be
-Dovecot SASL support is available in Postfix 2.3 and later. On the Postfix side
-you need to specify the location of the Dovecot authentication daemon socket.
-We use a pathname relative to the Postfix queue directory, so that it will work
-whether or not the Postfix SMTP server runs chrooted:
+ Enable this option for Outlook up to and including version 2003 and Outlook
+ Express up to version 6. This option does not hurt other clients.
- /etc/postfix/main.cf:
- smtpd_sasl_type = dovecot
- smtpd_sasl_path = private/auth
+After "postfix reload", the Postfix SMTP server will propagate the AUTH
+capability twice - once for compliant and once for broken clients:
-On the Dovecot side you also need to specify the Dovecot authentication daemon
-socket. In this case we specify an absolute pathname. In the example we assume
-that the Postfix queue is under /var/spool/postfix/.
-
- /some/where/dovecot.conf:
- auth default {
- mechanisms = plain login
- passdb pam {
- }
- userdb passwd {
- }
- socket listen {
- client {
- path = /var/spool/postfix/private/auth
- mode = 0660
- user = postfix
- group = postfix
- }
- }
- }
-
-See the Dovecot documentation for how to configure and operate the Dovecot
-authentication server.
-
-C\bCy\byr\bru\bus\bs S\bSA\bAS\bSL\bL c\bco\bon\bnf\bfi\big\bgu\bur\bra\bat\bti\bio\bon\bn f\bfo\bor\br t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP s\bse\ber\brv\bve\ber\br
-
-You need to configure how the Cyrus SASL library should authenticate a remote
-SMTP client's username and password. These settings must be stored in a
-separate configuration file.
-
-The name of the configuration file (default: smtpd.conf) will be constructed
-from a value that the Postfix SMTP server sends to the Cyrus SASL library,
-which adds the suffix .conf. The value is configured using one of the following
-variables:
+ % t\bte\bel\bln\bne\bet\bt s\bse\ber\brv\bve\ber\br.\b.e\bex\bxa\bam\bmp\bpl\ble\be.\b.c\bco\bom\bm 2\b25\b5
+ ...
+ E\bEH\bHL\bLO\bO c\bcl\bli\bie\ben\bnt\bt.\b.e\bex\bxa\bam\bmp\bpl\ble\be.\b.c\bco\bom\bm
+ 250-server.example.com
+ 250-PIPELINING
+ 250-SIZE 10240000
+ 250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
+ 250-AUTH=DIGEST-MD5 PLAIN CRAM-MD5
+ ...
+
+P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP S\bSe\ber\brv\bve\ber\br A\bAu\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn P\bPo\bol\bli\bic\bcy\by
+
+The Postfix SMTP server provides a way to specify the properties of SASL
+mechanisms that can be made available to the remote SMTP client.
+
+U\bUn\bne\ben\bnc\bcr\bry\byp\bpt\bte\bed\bd S\bSM\bMT\bTP\bP s\bse\bes\bss\bsi\bio\bon\bn
+
+The default policy is to allow any mechanism in the Postfix SMTP server except
+for those based on anonymous authentication:
/etc/postfix/main.cf:
- # Postfix 2.3 and later
- smtpd_sasl_path = smtpd
- # Postfix < 2.3
- smtpd_sasl_application_name = smtpd
+ # Specify a list of properties separated by comma or whitespace
+ smtpd_sasl_security_options = noanonymous
+
+ I\bIm\bmp\bpo\bor\brt\bta\ban\bnt\bt
+
+ Always set at least the noanonymous option. Otherwise, the Postfix SMTP
+ server can give strangers the same authorization as a properly-
+ authenticated client.
+
+Postfix can enforce the following policies on SASL authentication mechanisms:
+
+ noanonymous
+ Don't use mechanisms that permit anonymous authentication.
-Cyrus SASL searches for the configuration file in /usr/local/lib/sasl/ (Cyrus
-SASL version 1.5.5) or /usr/local/lib/sasl2/ (Cyrus SASL version 2.1.x).
+ noplaintext
+ Don't use mechanisms that transmit unencrypted username and password
+ information.
-Note: some Postfix distributions are modified and look for the smtpd.conf file
-in /etc/postfix/sasl.
+ nodictionary
+ Don't use mechanisms that are vulnerable to dictionary attacks.
-Note: some Cyrus SASL distributions look for the smtpd.conf file in /etc/sasl2.
+ forward_secrecy
+ Use only mechanisms that support forward secrecy (Dovecot SASL only).
+
+ mutual_auth
+ Use only mechanisms that authenticate both the client and the server to
+ each other.
+
+E\bEn\bnc\bcr\bry\byp\bpt\bte\bed\bd S\bSM\bMT\bTP\bP s\bse\bes\bss\bsi\bio\bon\bn (\b(T\bTL\bLS\bS)\b)
+
+A separate parameter controls Postfix SASL mechanism policy during a TLS-
+encrypted SMTP session. The default is to copy the settings from the
+unencrypted session:
+
+ /etc/postfix/main.cf:
+ smtpd_sasl_tls_security_options = $smtpd_sasl_security_options
- * To authenticate against the UNIX password database, use:
+A more sophisticated policy allows plaintext mechanisms, but only over a TLS-
+encrypted connection:
- (Cyrus SASL version 1.5.x)
+ /etc/postfix/main.cf:
+ smtpd_sasl_security_options = noanonymous, noplaintext
+ smtpd_sasl_tls_security_options = noanonymous
- /usr/local/lib/sasl/smtpd.conf:
- pwcheck_method: pwcheck
+To offer SASL authentication only after a TLS-encrypted session has been
+established specify this:
- IMPORTANT: pwcheck establishes a UNIX domain socket in /var/pwcheck and
- waits for authentication requests. The Postfix SMTP server must have
- read+execute permission to this directory or authentication attempts
- will fail.
+ /etc/postfix/main.cf:
+ smtpd_tls_auth_only = yes
- The pwcheck daemon is contained in the cyrus-sasl source tarball.
+E\bEn\bna\bab\bbl\bli\bin\bng\bg S\bSA\bAS\bSL\bL a\bau\but\bth\bho\bor\bri\biz\bza\bat\bti\bio\bon\bn i\bin\bn t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP s\bse\ber\brv\bve\ber\br
- (Cyrus SASL version 1.5.26)
+After the client has authenticated with SASL, the Postfix SMTP server decides
+what the remote SMTP client will be authorized for. Examples of possible SMTP
+clients authorizations are:
- /usr/local/lib/sasl/smtpd.conf:
- pwcheck_method: saslauthd
+ * Send a message to a remote recipient.
- (Cyrus SASL version 2.1.x)
+ * Use a specific envelope sender in the MAIL FROM command.
- /usr/local/lib/sasl2/smtpd.conf:
- pwcheck_method: saslauthd
- mech_list: PLAIN LOGIN
+These permissions are not enabled by default.
- The saslauthd daemon is also contained in the cyrus-sasl source tarball. It
- is more flexible than the pwcheck daemon, in that it can authenticate
- against PAM and various other sources. To use PAM, start saslauthd with "-
- a pam".
+M\bMa\bai\bil\bl r\bre\bel\bla\bay\by a\bau\but\bth\bho\bor\bri\biz\bza\bat\bti\bio\bon\bn
- IMPORTANT: saslauthd usually establishes a UNIX domain socket in /var/run/
- saslauthd and waits for authentication requests. The Postfix SMTP server
- must have read+execute permission to this directory or authentication
- attempts will fail.
+The permit_sasl_authenticated restriction allows SASL-authenticated SMTP
+clients to send mail to remote destinations. Add it to the list of
+smtpd_recipient_restrictions as follows:
- Note: The directory where saslauthd puts the socket is configurable. See
- the command-line option "-m /path/to/socket" in the saslauthd --help
- listing.
+ /etc/postfix/main.cf:
+ smtpd_recipient_restrictions =
+ ...
+ permit_mynetworks
+ p\bpe\ber\brm\bmi\bit\bt_\b_s\bsa\bas\bsl\bl_\b_a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bte\bed\bd
+ reject_unauth_destination
+ ...
- * To authenticate against Cyrus SASL's own password database:
+E\bEn\bnv\bve\bel\blo\bop\bpe\be s\bse\ben\bnd\bde\ber\br a\bad\bdd\bdr\bre\bes\bss\bs a\bau\but\bth\bho\bor\bri\biz\bza\bat\bti\bio\bon\bn
- (Cyrus SASL version 1.5.x)
+By default an SMTP client may specify any envelope sender address in the MAIL
+FROM command. That is because the Postfix SMTP server only knows the remte SMTP
+client hostname and IP address, but not the user who controls the remote SMTP
+client.
- /usr/local/lib/sasl/smtpd.conf:
- pwcheck_method: sasldb
+This changes the moment an SMTP client uses SASL authentication. Now, the
+Postfix SMTP server knows who the sender is. Given a table of envelope sender
+addresses and SASL login names, the Postfix SMTP server can decide if the SASL
+authenticated client is allowed to use a particular envelope sender address:
- (Cyrus SASL version 2.1.x)
+ /etc/postfix/main.cf:
+ s\bsm\bmt\btp\bpd\bd_\b_s\bse\ben\bnd\bde\ber\br_\b_l\blo\bog\bgi\bin\bn_\b_m\bma\bap\bps\bs =\b= h\bha\bas\bsh\bh:\b:/\b/e\bet\btc\bc/\b/p\bpo\bos\bst\btf\bfi\bix\bx/\b/c\bco\bon\bnt\btr\bro\bol\bll\ble\bed\bd_\b_e\ben\bnv\bve\bel\blo\bop\bpe\be_\b_s\bse\ben\bnd\bde\ber\brs\bs
- /usr/local/lib/sasl2/smtpd.conf:
- pwcheck_method: auxprop
- auxprop_plugin: sasldb
- mech_list: PLAIN LOGIN CRAM-MD5 DIGEST-MD5
+ smtpd_recipient_restrictions =
+ ...
+ r\bre\bej\bje\bec\bct\bt_\b_s\bse\ben\bnd\bde\ber\br_\b_l\blo\bog\bgi\bin\bn_\b_m\bmi\bis\bsm\bma\bat\btc\bch\bh
+ permit_sasl_authenticated
+ permit_mynetworks
+ reject_unauth_destination
+ ...
- This will use the Cyrus SASL password file (default: /etc/sasldb in version
- 1.5.x, or /etc/sasldb2 in version 2.1.x), which is maintained with the
- saslpasswd or saslpasswd2 command (part of the Cyrus SASL software). On
- some poorly-supported systems the saslpasswd command needs to be run
- multiple times before it stops complaining. The Postfix SMTP server needs
- read access to the sasldb file - you may have to play games with group
- access permissions. With the OTP authentication mechanism, the Postfix SMTP
- server also needs WRITE access to /etc/sasldb2 or /etc/sasldb (or the back
- end SQL database, if used).
+The controlled_envelope_senders table specifies the binding between the sender
+envelope addresses and its their SASL login names:
- IMPORTANT: To get sasldb running, make sure that you set the SASL domain
- (realm) to a fully qualified domain name.
+ /etc/postfix/controlled_envelope_senders
+ # envelope sender owners (SASL login names)
+ john@example.com john@example.com
+ helpdesk@example.com john@example.com, mary@example.com
+ postmaster admin@example.com
+ @example.net barney, fred, john@example.com,
+ mary@example.com
- EXAMPLE:
+With this, the reject_sender_login_mismatch restriction above will reject the
+sender address in the MAIL FROM command if smtpd_sender_login_maps does not
+specify the SMTP client's login name as an owner of that address.
- (Cyrus SASL version 1.5.x)
+See also reject_authenticated_sender_login_mismatch and
+reject_unauthenticated_sender_login_mismatch for additional control over the
+SASL login name and the envelope sender.
- % saslpasswd -c -u `postconf -h myhostname` exampleuser
+A\bAd\bdd\bdi\bit\bti\bio\bon\bna\bal\bl S\bSM\bMT\bTP\bP S\bSe\ber\brv\bve\ber\br S\bSA\bAS\bSL\bL o\bop\bpt\bti\bio\bon\bns\bs
- (Cyrus SASL version 2.1.x)
+Postfix provides a wide range of SASL authentication configuration options. The
+next section lists a few that are discussed frequently. See postconf(5) for a
+complete list.
- % saslpasswd2 -c -u `postconf -h myhostname` exampleuser
+D\bDe\bef\bfa\bau\bul\blt\bt a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn d\bdo\bom\bma\bai\bin\bn
- You can find out SASL's idea about the realms of the users in sasldb with
- sasldblistusers (Cyrus SASL version 1.5.x) or sasldblistusers2 (Cyrus SASL
- version 2.1.x).
+Postfix can append a domain name (or any other string) to a SASL login name
+that does not have a domain part, e.g. "john" instead of "john@example.com":
- On the Postfix side, you can have only one realm per smtpd(8) instance, and
- only the users belonging to that realm would be able to authenticate. The
- Postfix variable smtpd_sasl_local_domain controls the realm used by smtpd
- (8):
+ /etc/postfix/main.cf:
+ smtpd_sasl_local_domain = example.com
- /etc/postfix/main.cf:
- smtpd_sasl_local_domain = $myhostname
+This is useful as a default setting and safety net for misconfigured clients,
+or during a migration to an authentication method/backend that requires an
+authentication REALM or domain name, before all SMTP clients are configured to
+send such information.
-IMPORTANT: The Cyrus SASL password verification services pwcheck and saslauthd
-can only support the plaintext mechanisms PLAIN or LOGIN. However, the Cyrus
-SASL library doesn't know this, and will happily advertise other authentication
-mechanisms that the SASL library implements, such as DIGEST-MD5. As a result,
-if a remote SMTP client chooses any mechanism other than PLAIN or LOGIN while
-pwcheck or saslauthd are used, authentication will fail. Thus you may need to
-limit the list of mechanisms advertised by the Postfix SMTP server.
+H\bHi\bid\bdi\bin\bng\bg S\bSA\bAS\bSL\bL a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn f\bfr\bro\bom\bm c\bcl\bli\bie\ben\bnt\bts\bs o\bor\br n\bne\bet\btw\bwo\bor\brk\bks\bs
- * With older Cyrus SASL versions you remove the corresponding library files
- from the SASL plug-in directory (and again whenever the system is updated).
+Some clients insist on using SASL authentication if it is offered, even when
+they are not configured to send credentials - and therefore they will always
+fail and disconnect.
- * With Cyrus SASL version 2.1.x or later the mech_list variable can specify a
- list of authentication mechanisms that Cyrus SASL may offer:
+Postfix can hide the AUTH capability from these clients/networks:
- /usr/local/lib/sasl2/smtpd.conf:
- mech_list: plain login
+ /etc/postfix/main.cf:
+ smtpd_sasl_exceptions_networks = !192.0.2.171/32, 192.0.2.0/24
-For the same reasons you might want to limit the list of plugins used for
-authentication.
+A\bAd\bdd\bdi\bin\bng\bg t\bth\bhe\be S\bSA\bAS\bSL\bL l\blo\bog\bgi\bin\bn n\bna\bam\bme\be t\bto\bo m\bma\bai\bil\bl h\bhe\bea\bad\bde\ber\brs\bs
- * With Cyrus SASL version 1.5.x your only choice is to delete the
- corresponding library files from the SASL plug-in directory.
+To report SASL login names in Received: message headers (Postfix version 2.3
+and later):
- * With SASL version 2.1.x:
+ /etc/postfix/main.cf:
+ smtpd_sasl_authenticated_header = yes
- /usr/local/lib/sasl2/smtpd.conf:
- pwcheck_method: auxprop
- auxprop_plugin: sql
+ N\bNo\bot\bte\be
-To run software chrooted with SASL support is an interesting exercise. It
-probably is not worth the trouble.
+ The SASL login names will be shared with the entire world.
-T\bTe\bes\bst\bti\bin\bng\bg S\bSA\bAS\bSL\bL a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn i\bin\bn t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP s\bse\ber\brv\bve\ber\br
+T\bTe\bes\bst\bti\bin\bng\bg S\bSA\bAS\bSL\bL a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn i\bin\bn t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP S\bSe\ber\brv\bve\ber\br
To test the server side, connect (for example, with telnet) to the Postfix SMTP
server port and you should be able to have a conversation as shown below.
Information sent by the client (that is, you) is shown in bold font.
- $ t\bte\bel\bln\bne\bet\bt s\bse\ber\brv\bve\ber\br.\b.e\bex\bxa\bam\bmp\bpl\ble\be.\b.c\bco\bom\bm 2\b25\b5
- . . .
+ % t\bte\bel\bln\bne\bet\bt s\bse\ber\brv\bve\ber\br.\b.e\bex\bxa\bam\bmp\bpl\ble\be.\b.c\bco\bom\bm 2\b25\b5
+ ...
220 server.example.com ESMTP Postfix
E\bEH\bHL\bLO\bO c\bcl\bli\bie\ben\bnt\bt.\b.e\bex\bxa\bam\bmp\bpl\ble\be.\b.c\bco\bom\bm
250-server.example.com
A\bAU\bUT\bTH\bH P\bPL\bLA\bAI\bIN\bN A\bAH\bHR\bRl\blc\bc3\b3Q\bQA\bAd\bdG\bGV\bVz\bzd\bdH\bHB\bBh\bhc\bc3\b3M\bM=\b=
235 Authentication successful
-Instead of AHRlc3QAdGVzdHBhc3M=, specify the base64 encoded form of
+Instead of AHRlc3QAdGVzdHBhc3M=, specify the base64-encoded form of
\0username\0password (the \0 is a null byte). The example above is for a user
named `test' with password `testpass'.
-In order to generate base64 encoded authentication information you can use one
-of the following commands:
+ C\bCa\bau\but\bti\bio\bon\bn
+
+ When posting logs of the SASL negotiations to public lists, please keep in
+ mind that username/password information is trivial to recover from the
+ base64-encoded form.
+
+You can use one of the following commands to generate base64 encoded
+authentication information:
- % printf '\0username\0password' | mmencode
+ % g\bge\ben\bn-\b-a\bau\but\bth\bh p\bpl\bla\bai\bin\bn
+ username: u\bus\bse\ber\brn\bna\bam\bme\be
+ password:
- % perl -MMIME::Base64 -e \
- 'print encode_base64("\0username\0password");'
+The g\bge\ben\bn-\b-a\bau\but\bth\bh Perl script was written by John Jetmore and can be found at http:/
+/jetmore.org/john/code/gen-auth.
-The mmencode command is part of the metamail software. MIME::Base64 is
-available from http://www.cpan.org/.
+ % p\bpr\bri\bin\bnt\btf\bf '\b'\\b\0\b0u\bus\bse\ber\brn\bna\bam\bme\be\\b\0\b0p\bpa\bas\bss\bsw\bwo\bor\brd\bd'\b' |\b| m\bmm\bme\ben\bnc\bco\bod\bde\be
-Caution: when posting logs of the SASL negotiations to public lists, please
-keep in mind that username/password information is trivial to recover from the
-base64-encoded form.
+The m\bmm\bme\ben\bnc\bco\bod\bde\be command is part of the metamail software.
-T\bTr\bro\bou\bub\bbl\ble\be s\bsh\bho\boo\bot\bti\bin\bng\bg t\bth\bhe\be S\bSA\bAS\bSL\bL i\bin\bnt\bte\ber\brn\bna\bal\bls\bs
+ % p\bpe\ber\brl\bl -\b-M\bMM\bMI\bIM\bME\bE:\b::\b:B\bBa\bas\bse\be6\b64\b4 -\b-e\be \\b\
+ '\b'p\bpr\bri\bin\bnt\bt e\ben\bnc\bco\bod\bde\be_\b_b\bba\bas\bse\be6\b64\b4(\b("\b"\\b\0\b0u\bus\bse\ber\brn\bna\bam\bme\be\\b\0\b0p\bpa\bas\bss\bsw\bwo\bor\brd\bd"\b")\b);\b;'\b'
-In the Cyrus SASL sources you'll find a subdirectory named "sample". Run make
-there, then create a symbolic link from sample.conf to smtpd.conf in your Cyrus
-SASL library directory /usr/local/lib/sasl2. "su" to the user postfix (or
-whatever your mail_owner directive is set to):
+MIME::Base64 is available from http://www.cpan.org/.
- % su postfix
+C\bCo\bon\bnf\bfi\big\bgu\bur\bri\bin\bng\bg S\bSA\bAS\bSL\bL a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn i\bin\bn t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP/\b/L\bLM\bMT\bTP\bP c\bcl\bli\bie\ben\bnt\bt
-then run the resulting sample Cyrus SASL server and client in separate
-terminals. The sample applications send log messages to the syslog facility
-auth. Check the log to fix the problem or run strace / ktrace / truss on the
-server to see what makes it unhappy. Repeat the previous step until you can
-successfully authenticate with the sample Cyrus SASL client. Only then get back
-to Postfix.
+The Postfix SMTP and the LMTP client can authenticate with a remote SMTP server
+via the Cyrus SASL framework. At this time, the Dovecot SASL implementation
+does not provide client functionality.
-E\bEn\bna\bab\bbl\bli\bin\bng\bg S\bSA\bAS\bSL\bL a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn i\bin\bn t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP c\bcl\bli\bie\ben\bnt\bt
+ N\bNo\bot\bte\be
-Turn on client-side SASL authentication, and specify a table with per-host or
-per-destination username and password information. The Postfix SMTP client
-first searches the table for an entry with the remote SMTP server hostname; if
-no entry is found, then the Postfix SMTP client searches the table for an entry
-with the next-hop destination. Usually, that is the right-hand part of an email
-address, but it can also be the information that is specified with the
-relayhost parameter or with a transport(5) table.
+ The examples in this section discuss only the SMTP client. Replace smtp_
+ with lmtp_ to get the corresponding LMTP client configuration.
+
+You can read more about the following topics:
+
+ * Enabling SASL authentication in the Postfix SMTP/LMTP client
+ * Configuring sender-dependent SASL authentication
+ * Postfix SMTP/LMTP client authentication policy
+ * Filtering server mechanism names in the Postfix SMTP/LMTP client
+
+E\bEn\bna\bab\bbl\bli\bin\bng\bg S\bSA\bAS\bSL\bL a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn i\bin\bn t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP/\b/L\bLM\bMT\bTP\bP c\bcl\bli\bie\ben\bnt\bt
+
+This section shows a typical scenario where the Postfix SMTP client sends all
+messages via a mail gateway server that requires SASL authentication. To make
+the example more readable we introduce it in two parts.
/etc/postfix/main.cf:
smtp_sasl_auth_enable = yes
- smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
- smtp_sasl_type = cyrus
- relayhost = [mail.myisp.net]
+ relayhost = [mail.isp.example]
# Alternative form:
- # relayhost = [mail.myisp.net]:submission
-
- /etc/postfix/sasl_passwd:
- [mail.myisp.net] username:password
- [mail.myisp.net]:submission username:password
+ # relayhost = [mail.isp.example]:submission
+ smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
-Notes:
+ * The smtp_sasl_auth_enable setting enables client-side authentication. We
+ will configure the client's username and password information in the second
+ part of the example.
- * The "submission" destination port tells Postfix to send mail via TCP
- network port 587, which is normally reserved for email clients. The default
- is to send mail to the "smtp" destination port (TCP port 25), which is used
- for receiving mail across the internet. If you use an explicit destination
- port in main.cf, then you must use the same form also in the
- smtp_sasl_password_maps file.
+ * The relayhost setting forces the Postfix SMTP to send all remote messages
+ to the specified mail server instead of trying to deliver them directly to
+ their destination.
- * Postfix does not deliver mail via TCP port 465 (the obsolete "wrappermode"
- protocol). See TLS_README for a solution that uses the "stunnel" command.
+ * In the relayhost setting, the "[" and "]" prevent the Postfix SMTP client
+ from looking up MX (mail exchanger) records for the enclosed name.
- * The "[" and "]" prevent Postfix from looking up the MX (mail exchanger)
- records for the enclosed name. If you use this form in main.cf, then you
- must use the same form also in the smtp_sasl_password_maps file.
+ * The relayhost destination may also specify a non-default TCP port. For
+ example, the alternative form [mail.isp.example]:submission tells Postfix
+ to connect to TCP network port 587, which is reserved for email client
+ applications.
- * The Postfix SMTP client opens the SASL client password file before entering
- the optional chroot jail, so you can keep the file in /etc/postfix and set
- permissions read / write only for root to keep the username:password
- combinations away from other system users.
+ * The Postfix SMTP client is compatible with SMTP servers that use the non-
+ standard "AUTH=m\bme\bet\bth\bho\bod\bd.\b...." syntax in response to the EHLO command; this
+ requires no additional Postfix client configuration.
- * Specify d\bdb\bbm\bm instead of h\bha\bas\bsh\bh if your system uses d\bdb\bbm\bm files instead of d\bdb\bb
- files. To find out what lookup tables Postfix supports, use the command
- "p\bpo\bos\bst\btc\bco\bon\bnf\bf -\b-m\bm".
+ * The Postfix SMTP client does not support the obsolete "wrappermode"
+ protocol, which uses TCP port 465 on the SMTP server. See TLS_README for a
+ solution that uses the stunnel command.
- * Execute the command "p\bpo\bos\bst\btm\bma\bap\bp /\b/e\bet\btc\bc/\b/p\bpo\bos\bst\btf\bfi\bix\bx/\b/s\bsa\bas\bsl\bl_\b_p\bpa\bas\bss\bsw\bwd\bd" whenever you change
- the sasl_passwd table.
+ * With the smtp_sasl_password_maps parameter, we configure the Postfix SMTP
+ client to send username and password information to the mail gateway
+ server. As discussed in the next section, the Postfix SMTP client supports
+ multiple ISP accounts. For this reason the username and password are stored
+ in a table that contains one username/password combination for each mail
+ gateway server.
-Workarounds:
+ /etc/postfix/sasl_passwd:
+ # destination credentials
+ [mail.isp.example] username:password
+ # Alternative form:
+ # [mail.isp.example]:submission username:password
- * Some remote SMTP servers support PLAIN or LOGIN authentication only. By
- default, the Postfix SMTP client does not use authentication methods that
- send plaintext passwords, and defers delivery with the following error
- message: "Authentication failed: cannot SASL authenticate to server". To
- enable plaintext authentication specify, for example:
+ I\bIm\bmp\bpo\bor\brt\bta\ban\bnt\bt
- /etc/postfix/main.cf:
- smtp_sasl_security_options = noanonymous
+ Keep the SASL client password file in /etc/postfix, and make the file
+ read+write only for root to protect the username/password combinations
+ against other users. The Postfix SMTP client will still be able to read the
+ SASL client passwords. It opens the file as user root before it drops
+ privileges, and before entering an optional chroot jail.
- * Some remote SMTP servers announce authentication mechanisms that don't
- actually work. It is possible via the smtp_sasl_mechanism_filter parameter
- to restrict the list of server mechanisms that the Postfix SMTP client will
- take into consideration:
+ * Use the postmap command whenever you change the /etc/postfix/sasl_passwd
+ file.
- /etc/postfix/main.cf:
- smtp_sasl_mechanism_filter = !gssapi, !external, static:all
+ * If you specify the "[" and "]" in the relayhost destination, then you must
+ use the same form in the smtp_sasl_password_maps file.
- In the above example, the Postfix SMTP client will decline to use
- mechanisms that require special infrastructure such as Kerberos or TLS.
+ * If you specify a non-default TCP Port (such as ":submission" or ":587") in
+ the relayhost destination, then you must use the same form in the
+ smtp_sasl_password_maps file.
- * The Postfix SMTP client is backwards compatible with SMTP servers that use
- the non-standard "AUTH=method..." syntax in response to the EHLO command;
- there is no Postfix client configuration needed to work around it.
+C\bCo\bon\bnf\bfi\big\bgu\bur\bri\bin\bng\bg S\bSe\ben\bnd\bde\ber\br-\b-D\bDe\bep\bpe\ben\bnd\bde\ben\bnt\bt S\bSA\bAS\bSL\bL a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn
-S\bSu\bup\bpp\bpo\bor\brt\bti\bin\bng\bg m\bmu\bul\blt\bti\bip\bpl\ble\be I\bIS\bSP\bP a\bac\bcc\bco\bou\bun\bnt\bts\bs i\bin\bn t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP c\bcl\bli\bie\ben\bnt\bt
+Postfix supports different ISP accounts for different sender addresses (version
+2.3 and later). This can be useful when one person uses the same machine for
+work and for personal use, or when people with different ISP accounts share the
+same Postfix server.
-Postfix version 2.3 supports multiple ISP accounts. This can be useful when one
-person uses the same machine for work and for personal use, or when people with
-different ISP accounts share the same Postfix server. To make this possible,
-Postfix 2.3 supports per-sender SASL passwords and per-sender relay hosts. In
-the example below, Postfix will search the SASL password file by sender before
-it searches that same file by destination. Likewise, Postfix will search the
-per-sender relayhost file, and use the default relayhost only as a final
-resort.
+To make this possible, Postfix supports per-sender SASL passwords and per-
+sender relay hosts. In the example below, the Postfix SMTP client will search
+the SASL password file by sender address before it searches that same file by
+destination. Likewise, the Postfix trivial-rewrite(8) daemon will search the
+per-sender relayhost file, and use the default relayhost setting only as a
+final resort.
/etc/postfix/main.cf:
smtp_sender_dependent_authentication = yes
sender_dependent_relayhost_maps = hash:/etc/postfix/sender_relay
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
- relayhost = [mail.myisp.net]
+ relayhost = [mail.isp.example]
# Alternative form:
- # relayhost = [mail.myisp.net]:submission
+ # relayhost = [mail.isp.example]:submission
/etc/postfix/sasl_passwd:
# Per-sender authentication; see also /etc/postfix/sender_relay.
- user1@example.com username2:password2
- user2@example.net username2:password2
+ user1@example.com username2:password2
+ user2@example.net username2:password2
# Login information for the default relayhost.
- [mail.myisp.net] username:password
- [mail.myisp.net]:submission username:password
+ [mail.isp.example] username:password
+ # Alternative form:
+ # [mail.isp.example]:submission username:password
/etc/postfix/sender_relay:
# Per-sender provider; see also /etc/postfix/sasl_passwd.
- user1@example.com [mail.example.com]:submission
- user2@example.net [mail.example.net]
-
-Notes:
+ user1@example.com [mail.example.com]:submission
+ user2@example.net [mail.example.net]
* If you are creative, then you can try to combine the two tables into one
single MySQL database, and configure different Postfix queries to extract
the appropriate information.
- * Specify d\bdb\bbm\bm instead of h\bha\bas\bsh\bh if your system uses d\bdb\bbm\bm files instead of d\bdb\bb
+ * Specify dbm instead of hash if your system uses dbm files instead of db
files. To find out what lookup tables Postfix supports, use the command
- "p\bpo\bos\bst\btc\bco\bon\bnf\bf -\b-m\bm".
+ "postconf -m".
- * Execute the command "p\bpo\bos\bst\btm\bma\bap\bp /\b/e\bet\btc\bc/\b/p\bpo\bos\bst\btf\bfi\bix\bx/\b/s\bsa\bas\bsl\bl_\b_p\bpa\bas\bss\bsw\bwd\bd" whenever you change
+ * Execute the command "postmap /etc/postfix/sasl_passwd" whenever you change
the sasl_passwd table.
- * Execute the command "p\bpo\bos\bst\btm\bma\bap\bp /\b/e\bet\btc\bc/\b/p\bpo\bos\bst\btf\bfi\bix\bx/\b/s\bse\ben\bnd\bde\ber\br_\b_r\bre\bel\bla\bay\by" whenever you change
+ * Execute the command "postmap /etc/postfix/sender_relay" whenever you change
the sender_relay table.
+P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP/\b/L\bLM\bMT\bTP\bP c\bcl\bli\bie\ben\bnt\bt a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn p\bpo\bol\bli\bic\bcy\by
+
+Just like the Postfix SMTP server, the SMTP client has a policy that determines
+which SASL mechanisms are acceptable and which are not.
+
+U\bUn\bne\ben\bnc\bcr\bry\byp\bpt\bte\bed\bd S\bSM\bMT\bTP\bP s\bse\bes\bss\bsi\bio\bon\bn
+
+The default policy is stricter than that of the Postfix SMTP server - plaintext
+mechanisms are not allowed (nor is any anonymous mechanism):
+
+ /etc/postfix/main.cf:
+ smtp_sasl_security_options = noplaintext, noanonymous
+
+Postfix can enforce the following policies on SASL authentication mechanisms:
+
+ noanonymous
+ Don't use mechanisms that permit anonymous authentication.
+
+ noplaintext
+ Don't use mechanisms that transmit unencrypted username and password
+ information.
+
+ nodictionary
+ Don't use mechanisms that are vulnerable to dictionary attacks.
+
+ mutual_auth
+ Use only mechanisms that authenticate both the client and the server to
+ each other.
+
+With the default policy shown above, the Postfix SMTP client will not send its
+password over an unencrypted connection. This sometimes leads to authentication
+failures if the remote server only offers plaintext authentication mechanisms.
+In such cases the SMTP client will log the following error message:
+
+ SASL authentication failure: No worthy mechs found
+
+The less secure approach to deal with this is to lower the security standards
+and permit plaintext authentication mechanisms:
+
+ /etc/postfix/main.cf:
+ smtp_sasl_security_options = noanonymous
+
+Needless to say, sending a username and password over an insecure channel is
+undesirable.
+
+If the remote server supports TLS, you can protect the plaintext username and
+password by turning on TLS in the Postfix SMTP client (see: TLS_README), and
+configuring the client as discussed next.
+
+E\bEn\bnc\bcr\bry\byp\bpt\bte\bed\bd S\bSM\bMT\bTP\bP s\bse\bes\bss\bsi\bio\bon\bn (\b(T\bTL\bLS\bS)\b)
+
+A separate parameter controls Postfix SASL mechanism policy during a TLS-
+encrypted SMTP session. The default is to copy the settings from the
+unencrypted session:
+
+ /etc/postfix/main.cf:
+ smtp_sasl_tls_security_options = $smtp_sasl_security_options
+
+A more sophisticated policy allows plaintext mechanisms, but only over a TLS-
+encrypted connection:
+
+ /etc/postfix/main.cf:
+ smtpd_sasl_security_options = noanonymous, noplaintext
+ smtpd_sasl_tls_security_options = noanonymous
+
+F\bFi\bil\blt\bte\ber\bri\bin\bng\bg s\bse\ber\brv\bve\ber\br m\bme\bec\bch\bha\ban\bni\bis\bsm\bm n\bna\bam\bme\bes\bs i\bin\bn t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP/\b/L\bLM\bMT\bTP\bP c\bcl\bli\bie\ben\bnt\bt
+
+Cyrus SASL always attempts to use the most secure authentication mechanism that
+the remote SMTP server offers - even if the client side was not configured to
+handle it! In such cases authentication will definitely fail.
+
+To prevent this, the Postfix SMTP client can filter the list of authentication
+mechanism names from the remote SMTP server. Used correctly, the filter hides
+unwanted mechanisms from the Cyrus SASL library, forcing the library to choose
+from the mechanisms the Postfix filter passes through.
+
+The following example filters out everything but the mechanisms PLAIN and
+LOGIN:
+
+ /etc/postfix/main.cf:
+ smtp_sasl_mechanism_filter = plain, login
+
+ N\bNo\bot\bte\be
+
+ If the remote server does not offer any of the mechanisms on the filter
+ list, authentication will fail.
+
+We close this section with an example that passes every mechanism except for
+GSSAPI and LOGIN:
+
+ /etc/postfix/main.cf:
+ smtp_sasl_mechanism_filter = !gssapi, !login, static:all
+
+B\bBu\bui\bil\bld\bdi\bin\bng\bg P\bPo\bos\bst\btf\bfi\bix\bx w\bwi\bit\bth\bh S\bSA\bAS\bSL\bL s\bsu\bup\bpp\bpo\bor\brt\bt
+
+As mentioned elsewhere, Postfix supports two SASL implementations: Cyrus SASL
+(SMTP client and server) and Dovecot SASL (SMTP server only). Both
+implementations can be built into Postfix simultaneously.
+
+ * Building Dovecot SASL support
+ * Building Cyrus SASL support
+
+B\bBu\bui\bil\bld\bdi\bin\bng\bg D\bDo\bov\bve\bec\bco\bot\bt S\bSA\bAS\bSL\bL s\bsu\bup\bpp\bpo\bor\brt\bt
+
+These instructions assume that you build Postfix from source code as described
+in the INSTALL document. Some modification may be required if you build Postfix
+from a vendor-specific source package.
+
+Support for the Dovecot version 1 SASL protocol is available in Postfix 2.3 and
+later. At the time of writing, only server-side SASL support is available, so
+you can't use it to authenticate the Postfix SMTP client to your network
+provider's server.
+
+Dovecot uses its own daemon process for authentication. This keeps the Postfix
+build process simple, because there is no need to link extra libraries into
+Postfix.
+
+To generate the necessary Makefiles, execute the following in the Postfix top-
+level directory:
+
+ % m\bma\bak\bke\be t\bti\bid\bdy\by # if you have left-over files from a previous build
+ % m\bma\bak\bke\be m\bma\bak\bke\bef\bfi\bil\ble\bes\bs C\bCC\bCA\bAR\bRG\bGS\bS=\b='\b'-\b-D\bDU\bUS\bSE\bE_\b_S\bSA\bAS\bSL\bL_\b_A\bAU\bUT\bTH\bH \\b\
+ -\b-D\bDD\bDE\bEF\bF_\b_S\bSE\bER\bRV\bVE\bER\bR_\b_S\bSA\bAS\bSL\bL_\b_T\bTY\bYP\bPE\bE=\b=\\b\"\b"d\bdo\bov\bve\bec\bco\bot\bt\\b\"\b"'\b'
+
+After this, proceed with "make" as described in the INSTALL document.
+
+N\bNo\bot\bte\be
+
+ * The -DDEF_SERVER_SASL_TYPE=\"dovecot\" is not necessary; it just makes
+ Postfix configuration a little more convenient because you don't have to
+ specify the SASL plug-in type in the Postfix main.cf file (but this may
+ cause surprises when you switch to a later Postfix version that is built
+ with the default SASL type of sasl).
+
+ * If you also want support for LDAP or TLS (or for Cyrus SASL), you need to
+ merge their CCARGS and AUXLIBS options into the above command line; see the
+ LDAP_README and TLS_README for details.
+
+ % m\bma\bak\bke\be t\bti\bid\bdy\by # if you have left-over files from a previous build
+ % m\bma\bak\bke\be m\bma\bak\bke\bef\bfi\bil\ble\bes\bs C\bCC\bCA\bAR\bRG\bGS\bS=\b='\b'-\b-D\bDU\bUS\bSE\bE_\b_S\bSA\bAS\bSL\bL_\b_A\bAU\bUT\bTH\bH \\b\
+ -\b-D\bDD\bDE\bEF\bF_\b_S\bSE\bER\bRV\bVE\bER\bR_\b_S\bSA\bAS\bSL\bL_\b_T\bTY\bYP\bPE\bE=\b=\\b\"\b"d\bdo\bov\bve\bec\bco\bot\bt\\b\"\b" \\b\
+ .\b..\b..\b.C\bCC\bCA\bAR\bRG\bGS\bS o\bop\bpt\bti\bio\bon\bns\bs f\bfo\bor\br L\bLD\bDA\bAP\bP o\bor\br T\bTL\bLS\bS e\bet\btc\bc.\b..\b..\b..\b.'\b' \\b\
+ A\bAU\bUX\bXL\bLI\bIB\bBS\bS=\b='\b'.\b..\b..\b.A\bAU\bUX\bXL\bLI\bIB\bBS\bS o\bop\bpt\bti\bio\bon\bns\bs f\bfo\bor\br L\bLD\bDA\bAP\bP o\bor\br T\bTL\bLS\bS e\bet\btc\bc.\b..\b..\b..\b.'\b'
+
+B\bBu\bui\bil\bld\bdi\bin\bng\bg C\bCy\byr\bru\bus\bs S\bSA\bAS\bSL\bL s\bsu\bup\bpp\bpo\bor\brt\bt
+
+B\bBu\bui\bil\bld\bdi\bin\bng\bg t\bth\bhe\be C\bCy\byr\bru\bus\bs S\bSA\bAS\bSL\bL l\bli\bib\bbr\bra\bar\bry\by
+
+Postfix works with cyrus-sasl-1.5.x or cyrus-sasl-2.1.x, which are available
+from ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/.
+
+ I\bIm\bmp\bpo\bor\brt\bta\ban\bnt\bt
+
+ If you install the Cyrus SASL libraries as per the default, you will have
+ to create a symlink /usr/lib/sasl -> /usr/local/lib/sasl for version 1.5.x
+ or /usr/lib/sasl2 -> /usr/local/lib/sasl2 for version 2.1.x.
+
+Reportedly, Microsoft Outlook (Express) requires the non-standard LOGIN and/or
+NTLM authentication mechanism. To enable these authentication mechanisms, build
+the Cyrus SASL libraries with:
+
+ % .\b./\b/c\bco\bon\bnf\bfi\big\bgu\bur\bre\be -\b--\b-e\ben\bna\bab\bbl\ble\be-\b-l\blo\bog\bgi\bin\bn -\b--\b-e\ben\bna\bab\bbl\ble\be-\b-n\bnt\btl\blm\bm
+
+B\bBu\bui\bil\bld\bdi\bin\bng\bg P\bPo\bos\bst\btf\bfi\bix\bx w\bwi\bit\bth\bh C\bCy\byr\bru\bus\bs S\bSA\bAS\bSL\bL s\bsu\bup\bpp\bpo\bor\brt\bt
+
+These instructions assume that you build Postfix from source code as described
+in the INSTALL document. Some modification may be required if you build Postfix
+from a vendor-specific source package.
+
+The following assumes that the Cyrus SASL include files are in /usr/local/
+include, and that the Cyrus SASL libraries are in /usr/local/lib.
+
+On some systems this generates the necessary Makefile definitions:
+
+Cyrus SASL version 2.1.x
+
+ % m\bma\bak\bke\be t\bti\bid\bdy\by # if you have left-over files from a previous build
+ % m\bma\bak\bke\be m\bma\bak\bke\bef\bfi\bil\ble\bes\bs C\bCC\bCA\bAR\bRG\bGS\bS=\b="\b"-\b-D\bDU\bUS\bSE\bE_\b_S\bSA\bAS\bSL\bL_\b_A\bAU\bUT\bTH\bH -\b-D\bDU\bUS\bSE\bE_\b_C\bCY\bYR\bRU\bUS\bS_\b_S\bSA\bAS\bSL\bL \\b\
+ -\b-I\bI/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/i\bin\bnc\bcl\blu\bud\bde\be/\b/s\bsa\bas\bsl\bl"\b" A\bAU\bUX\bXL\bLI\bIB\bBS\bS=\b="\b"-\b-L\bL/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/l\bli\bib\bb -\b-l\bls\bsa\bas\bsl\bl2\b2"\b"
+
+Cyrus SASL version 1.5.x
+
+ % m\bma\bak\bke\be t\bti\bid\bdy\by # if you have left-over files from a previous build
+ % m\bma\bak\bke\be m\bma\bak\bke\bef\bfi\bil\ble\bes\bs C\bCC\bCA\bAR\bRG\bGS\bS=\b="\b"-\b-D\bDU\bUS\bSE\bE_\b_S\bSA\bAS\bSL\bL_\b_A\bAU\bUT\bTH\bH -\b-D\bDU\bUS\bSE\bE_\b_C\bCY\bYR\bRU\bUS\bS_\b_S\bSA\bAS\bSL\bL \\b\
+ -\b-I\bI/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/i\bin\bnc\bcl\blu\bud\bde\be"\b" A\bAU\bUX\bXL\bLI\bIB\bBS\bS=\b="\b"-\b-L\bL/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/l\bli\bib\bb -\b-l\bls\bsa\bas\bsl\bl"\b"
+
+On Solaris 2.x you need to specify run-time link information, otherwise the
+ld.so run-time linker will not find the SASL shared library:
+
+Cyrus SASL version 2.1.x
+
+ % m\bma\bak\bke\be t\bti\bid\bdy\by # remove left-over files from a previous build
+ % m\bma\bak\bke\be m\bma\bak\bke\bef\bfi\bil\ble\bes\bs C\bCC\bCA\bAR\bRG\bGS\bS=\b="\b"-\b-D\bDU\bUS\bSE\bE_\b_S\bSA\bAS\bSL\bL_\b_A\bAU\bUT\bTH\bH -\b-D\bDU\bUS\bSE\bE_\b_C\bCY\bYR\bRU\bUS\bS_\b_S\bSA\bAS\bSL\bL \\b\
+ -\b-I\bI/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/i\bin\bnc\bcl\blu\bud\bde\be/\b/s\bsa\bas\bsl\bl"\b" A\bAU\bUX\bXL\bLI\bIB\bBS\bS=\b="\b"-\b-L\bL/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/l\bli\bib\bb \\b\
+ -\b-R\bR/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/l\bli\bib\bb -\b-l\bls\bsa\bas\bsl\bl2\b2"\b"
+
+Cyrus SASL version 1.5.x
+
+ % m\bma\bak\bke\be t\bti\bid\bdy\by # if you have left-over files from a previous build
+ % m\bma\bak\bke\be m\bma\bak\bke\bef\bfi\bil\ble\bes\bs C\bCC\bCA\bAR\bRG\bGS\bS=\b="\b"-\b-D\bDU\bUS\bSE\bE_\b_S\bSA\bAS\bSL\bL_\b_A\bAU\bUT\bTH\bH -\b-D\bDU\bUS\bSE\bE_\b_C\bCY\bYR\bRU\bUS\bS_\b_S\bSA\bAS\bSL\bL \\b\
+ -\b-I\bI/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/i\bin\bnc\bcl\blu\bud\bde\be"\b" A\bAU\bUX\bXL\bLI\bIB\bBS\bS=\b="\b"-\b-L\bL/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/l\bli\bib\bb \\b\
+ -\b-R\bR/\b/u\bus\bsr\br/\b/l\blo\boc\bca\bal\bl/\b/l\bli\bib\bb -\b-l\bls\bsa\bas\bsl\bl"\b"
+
+U\bUs\bsi\bin\bng\bg C\bCy\byr\bru\bus\bs S\bSA\bAS\bSL\bL v\bve\ber\brs\bsi\bio\bon\bn 1\b1.\b.5\b5.\b.x\bx
+
+Postfix supports Cyrus SASL version 1.x, but you shouldn't use it unless you
+are forced to. The makers of Cyrus SASL write:
+
+ This library is being deprecated and applications should transition to
+ using the SASLv2 library (source: Project Cyrus: Downloads).
+
+If you still need to set it up, here's a quick rundown:
+
+Read the regular section on SMTP server configurations for the Cyrus SASL
+framework. The differences are:
+
+ * Cyrus SASL version 1.5.x searches for configuration (smtpd.conf) in /usr/
+ lib/sasl/ only. You must place the configuration in that directory. Some
+ systems may have modified Cyrus SASL and put the files into e.g. /var/lib/
+ sasl/.
+
+ * Use the saslpasswd command instead of saslpasswd2 to create users in
+ sasldb.
+
+ * Use the sasldblistusers command instead of sasldblistusers2 to find users
+ in sasldb.
+
+ * In the smtpd.conf file you can't use mech_list to limit the range of
+ mechanisms offered. Instead, remove their libraries from /usr/lib/sasl/
+ (and remember remove those files again when a system update re-installs new
+ versions).
+
C\bCr\bre\bed\bdi\bit\bts\bs
* Postfix SASL support was originally implemented by Till Franke of SuSE
Rhein/Main AG.
* Wietse trimmed down the code to only the bare necessities.
* Support for Cyrus SASL version 2 was contributed by Jason Hoos.
- * Liviu Daia added smtpd_sasl_application_name, split
+ * Liviu Daia added smtpd_sasl_application_name, separated
reject_sender_login_mismatch into
reject_authenticated_sender_login_mismatch and
reject_unauthenticated_sender_login_mismatch, and revised the docs.
* Wietse made another iteration through the code to add plug-in support for
- multiple SASL implementations, and changed smtpd_sasl_application_name into
- smtpd_sasl_path.
+ multiple SASL implementations, and for reasons that have been lost, also
+ changed smtpd_sasl_application_name into smtpd_sasl_path.
* The Dovecot SMTP server-only plug-in was originally implemented by Timo
Sirainen of Procontrol, Finland.
* Patrick Ben Koetter revised this document for Postfix 2.4 and made much
needed updates.
+ * Patrick Ben Koetter revised this document again for Postfix 2.7 and made
+ much needed updates.
Selected topics from the SASL_README document:
o Enabling SASL authentication in the Postfix SMTP client
- o Supporting multiple ISP accounts in the Postfix SMTP client
+ o Configuring Sender-Dependent SASL authentication
See the SASL_README and STANDARD_CONFIGURATION_README documents for further
information on these topics.
Execute the command "p\bpo\bos\bst\btm\bma\bap\bp /\b/e\bet\btc\bc/\b/p\bpo\bos\bst\btf\bfi\bix\bx/\b/v\bvi\bir\brt\btu\bua\bal\bl" whenever you change the
virtual table.
-E\bEn\bna\bab\bbl\bli\bin\bng\bg S\bSA\bAS\bSL\bL a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn i\bin\bn t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP c\bcl\bli\bie\ben\bnt\bt
+E\bEn\bna\bab\bbl\bli\bin\bng\bg S\bSA\bAS\bSL\bL a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn i\bin\bn t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP/\b/L\bLM\bMT\bTP\bP c\bcl\bli\bie\ben\bnt\bt
-Turn on client-side SASL authentication, and specify a table with per-host or
-per-destination username and password information. The Postfix SMTP client
-first searches the table for an entry with the remote SMTP server hostname; if
-no entry is found, then the Postfix SMTP client searches the table for an entry
-with the next-hop destination. Usually, that is the right-hand part of an email
-address, but it can also be the information that is specified with the
-relayhost parameter or with a transport(5) table.
+This section shows a typical scenario where the Postfix SMTP client sends all
+messages via a mail gateway server that requires SASL authentication. To make
+the example more readable we introduce it in two parts.
/etc/postfix/main.cf:
smtp_sasl_auth_enable = yes
- smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
- smtp_sasl_type = cyrus
- relayhost = [mail.myisp.net]
+ relayhost = [mail.isp.example]
# Alternative form:
- # relayhost = [mail.myisp.net]:submission
-
- /etc/postfix/sasl_passwd:
- [mail.myisp.net] username:password
- [mail.myisp.net]:submission username:password
+ # relayhost = [mail.isp.example]:submission
+ smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
-Notes:
+ * The smtp_sasl_auth_enable setting enables client-side authentication. We
+ will configure the client's username and password information in the second
+ part of the example.
- * The "submission" destination port tells Postfix to send mail via TCP
- network port 587, which is normally reserved for email clients. The default
- is to send mail to the "smtp" destination port (TCP port 25), which is used
- for receiving mail across the internet. If you use an explicit destination
- port in main.cf, then you must use the same form also in the
- smtp_sasl_password_maps file.
+ * The relayhost setting forces the Postfix SMTP to send all remote messages
+ to the specified mail server instead of trying to deliver them directly to
+ their destination.
- * Postfix does not deliver mail via TCP port 465 (the obsolete "wrappermode"
- protocol). See TLS_README for a solution that uses the "stunnel" command.
+ * In the relayhost setting, the "[" and "]" prevent the Postfix SMTP client
+ from looking up MX (mail exchanger) records for the enclosed name.
- * The "[" and "]" prevent Postfix from looking up the MX (mail exchanger)
- records for the enclosed name. If you use this form in main.cf, then you
- must use the same form also in the smtp_sasl_password_maps file.
+ * The relayhost destination may also specify a non-default TCP port. For
+ example, the alternative form [mail.isp.example]:submission tells Postfix
+ to connect to TCP network port 587, which is reserved for email client
+ applications.
- * The Postfix SMTP client opens the SASL client password file before entering
- the optional chroot jail, so you can keep the file in /etc/postfix and set
- permissions read / write only for root to keep the username:password
- combinations away from other system users.
+ * The Postfix SMTP client is compatible with SMTP servers that use the non-
+ standard "AUTH=m\bme\bet\bth\bho\bod\bd.\b...." syntax in response to the EHLO command; this
+ requires no additional Postfix client configuration.
- * Specify d\bdb\bbm\bm instead of h\bha\bas\bsh\bh if your system uses d\bdb\bbm\bm files instead of d\bdb\bb
- files. To find out what lookup tables Postfix supports, use the command
- "p\bpo\bos\bst\btc\bco\bon\bnf\bf -\b-m\bm".
+ * The Postfix SMTP client does not support the obsolete "wrappermode"
+ protocol, which uses TCP port 465 on the SMTP server. See TLS_README for a
+ solution that uses the stunnel command.
- * Execute the command "p\bpo\bos\bst\btm\bma\bap\bp /\b/e\bet\btc\bc/\b/p\bpo\bos\bst\btf\bfi\bix\bx/\b/s\bsa\bas\bsl\bl_\b_p\bpa\bas\bss\bsw\bwd\bd" whenever you change
- the sasl_passwd table.
+ * With the smtp_sasl_password_maps parameter, we configure the Postfix SMTP
+ client to send username and password information to the mail gateway
+ server. As discussed in the next section, the Postfix SMTP client supports
+ multiple ISP accounts. For this reason the username and password are stored
+ in a table that contains one username/password combination for each mail
+ gateway server.
-Workarounds:
+ /etc/postfix/sasl_passwd:
+ # destination credentials
+ [mail.isp.example] username:password
+ # Alternative form:
+ # [mail.isp.example]:submission username:password
- * Some remote SMTP servers support PLAIN or LOGIN authentication only. By
- default, the Postfix SMTP client does not use authentication methods that
- send plaintext passwords, and defers delivery with the following error
- message: "Authentication failed: cannot SASL authenticate to server". To
- enable plaintext authentication specify, for example:
+ I\bIm\bmp\bpo\bor\brt\bta\ban\bnt\bt
- /etc/postfix/main.cf:
- smtp_sasl_security_options = noanonymous
+ Keep the SASL client password file in /etc/postfix, and make the file
+ read+write only for root to protect the username/password combinations
+ against other users. The Postfix SMTP client will still be able to read the
+ SASL client passwords. It opens the file as user root before it drops
+ privileges, and before entering an optional chroot jail.
- * Some remote SMTP servers announce authentication mechanisms that don't
- actually work. It is possible via the smtp_sasl_mechanism_filter parameter
- to restrict the list of server mechanisms that the Postfix SMTP client will
- take into consideration:
+ * Use the postmap command whenever you change the /etc/postfix/sasl_passwd
+ file.
- /etc/postfix/main.cf:
- smtp_sasl_mechanism_filter = !gssapi, !external, static:all
+ * If you specify the "[" and "]" in the relayhost destination, then you must
+ use the same form in the smtp_sasl_password_maps file.
- In the above example, the Postfix SMTP client will decline to use
- mechanisms that require special infrastructure such as Kerberos or TLS.
+ * If you specify a non-default TCP Port (such as ":submission" or ":587") in
+ the relayhost destination, then you must use the same form in the
+ smtp_sasl_password_maps file.
- * The Postfix SMTP client is backwards compatible with SMTP servers that use
- the non-standard "AUTH=method..." syntax in response to the EHLO command;
- there is no Postfix client configuration needed to work around it.
+C\bCo\bon\bnf\bfi\big\bgu\bur\bri\bin\bng\bg S\bSe\ben\bnd\bde\ber\br-\b-D\bDe\bep\bpe\ben\bnd\bde\ben\bnt\bt S\bSA\bAS\bSL\bL a\bau\but\bth\bhe\ben\bnt\bti\bic\bca\bat\bti\bio\bon\bn
-S\bSu\bup\bpp\bpo\bor\brt\bti\bin\bng\bg m\bmu\bul\blt\bti\bip\bpl\ble\be I\bIS\bSP\bP a\bac\bcc\bco\bou\bun\bnt\bts\bs i\bin\bn t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP c\bcl\bli\bie\ben\bnt\bt
+Postfix supports different ISP accounts for different sender addresses (version
+2.3 and later). This can be useful when one person uses the same machine for
+work and for personal use, or when people with different ISP accounts share the
+same Postfix server.
-Postfix version 2.3 supports multiple ISP accounts. This can be useful when one
-person uses the same machine for work and for personal use, or when people with
-different ISP accounts share the same Postfix server. To make this possible,
-Postfix 2.3 supports per-sender SASL passwords and per-sender relay hosts. In
-the example below, Postfix will search the SASL password file by sender before
-it searches that same file by destination. Likewise, Postfix will search the
-per-sender relayhost file, and use the default relayhost only as a final
-resort.
+To make this possible, Postfix supports per-sender SASL passwords and per-
+sender relay hosts. In the example below, the Postfix SMTP client will search
+the SASL password file by sender address before it searches that same file by
+destination. Likewise, the Postfix trivial-rewrite(8) daemon will search the
+per-sender relayhost file, and use the default relayhost setting only as a
+final resort.
/etc/postfix/main.cf:
smtp_sender_dependent_authentication = yes
sender_dependent_relayhost_maps = hash:/etc/postfix/sender_relay
smtp_sasl_auth_enable = yes
smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
- relayhost = [mail.myisp.net]
+ relayhost = [mail.isp.example]
# Alternative form:
- # relayhost = [mail.myisp.net]:submission
+ # relayhost = [mail.isp.example]:submission
/etc/postfix/sasl_passwd:
# Per-sender authentication; see also /etc/postfix/sender_relay.
- user1@example.com username2:password2
- user2@example.net username2:password2
+ user1@example.com username2:password2
+ user2@example.net username2:password2
# Login information for the default relayhost.
- [mail.myisp.net] username:password
- [mail.myisp.net]:submission username:password
+ [mail.isp.example] username:password
+ # Alternative form:
+ # [mail.isp.example]:submission username:password
/etc/postfix/sender_relay:
# Per-sender provider; see also /etc/postfix/sasl_passwd.
- user1@example.com [mail.example.com]:submission
- user2@example.net [mail.example.net]
-
-Notes:
+ user1@example.com [mail.example.com]:submission
+ user2@example.net [mail.example.net]
* If you are creative, then you can try to combine the two tables into one
single MySQL database, and configure different Postfix queries to extract
the appropriate information.
- * Specify d\bdb\bbm\bm instead of h\bha\bas\bsh\bh if your system uses d\bdb\bbm\bm files instead of d\bdb\bb
+ * Specify dbm instead of hash if your system uses dbm files instead of db
files. To find out what lookup tables Postfix supports, use the command
- "p\bpo\bos\bst\btc\bco\bon\bnf\bf -\b-m\bm".
+ "postconf -m".
- * Execute the command "p\bpo\bos\bst\btm\bma\bap\bp /\b/e\bet\btc\bc/\b/p\bpo\bos\bst\btf\bfi\bix\bx/\b/s\bsa\bas\bsl\bl_\b_p\bpa\bas\bss\bsw\bwd\bd" whenever you change
+ * Execute the command "postmap /etc/postfix/sasl_passwd" whenever you change
the sasl_passwd table.
- * Execute the command "p\bpo\bos\bst\btm\bma\bap\bp /\b/e\bet\btc\bc/\b/p\bpo\bos\bst\btf\bfi\bix\bx/\b/s\bse\ben\bnd\bde\ber\br_\b_r\bre\bel\bla\bay\by" whenever you change
+ * Execute the command "postmap /etc/postfix/sender_relay" whenever you change
the sender_relay table.
controls the minimum acceptable SMTP client TLS cipher grade for use with
mandatory TLS encryption. The default value "medium" is suitable for most
destinations with which you may want to enforce TLS, and is beyond the reach of
-today's crypt-analytic methods. See smtp_tls_policy_maps for information on how
+today's cryptanalytic methods. See smtp_tls_policy_maps for information on how
to configure ciphers on a per-destination basis.
By default anonymous ciphers are allowed, and automatically disabled when
-The stable Postfix release is called postfix-2.6.x where 2=major
-release number, 6=minor release number, x=patchlevel. The stable
+The stable Postfix release is called postfix-2.7.x where 2=major
+release number, 7=minor release number, x=patchlevel. The stable
release never changes except for patches that address bugs or
emergencies. Patches change the patchlevel and the release date.
New features are developed in snapshot releases. These are called
-postfix-2.7-yyyymmdd where yyyymmdd is the release date (yyyy=year,
+postfix-2.8-yyyymmdd where yyyymmdd is the release date (yyyy=year,
mm=month, dd=day). Patches are never issued for snapshot releases;
instead, a new snapshot is released.
The mail_release_date configuration parameter (format: yyyymmdd)
specifies the release date of a stable release or snapshot release.
-If you upgrade from Postfix 2.5 or earlier, read RELEASE_NOTES-2.6
+If you upgrade from Postfix 2.6 or earlier, read RELEASE_NOTES-2.7
before proceeding.
-Incompatibility with snapshot 20100117
-======================================
-
-The meaning of an empty content filter next-hop destination has
-changed. Postfix now uses the recipient domain, instead of using
-$myhostname as in Postfix 2.6 and earlier. To get the old behavior
-use "default_filter_nexthop = $myhostname", or specify a non-empty
-next-hop content filter destination.
-
-Major changes with snapshot 20100117
-====================================
-
-The FILTER action in access maps or header/body_checks now supports
-sender reputation schemes that dynamically choose the SMTP source
-IP address.
-
-This is implemented by specifying FILTER actions with empty next-hop
-destinations in access maps or header/body_checks, and by configuring
-in master.cf one Postfix SMTP client for each SMTP source IP address,
-where each client has its own "-o myhostname" and "-o smtp_bind_address"
-settings.
-
Incompatibility with snapshot 20100101
======================================
-The verify(8) service now uses a persistent cache by default
-(address_verify_map = btree:$data_directory/verify_cache). To
-disable, specify "address_verify_map =" in main.cf.
-
When periodic cache cleanup is enabled (the default), the postscreen(8)
-and verify(8) servers now require that their cache databases support
-the "delete" and "sequence" operations. To disable periodic cache
-cleanup specify a zero xxx_cache_cleanup_interval value.
+server now requires that the cache database supports the "delete"
+and "sequence" operations. To disable periodic cache cleanup specify
+a zero postscreen_cache_cleanup_interval value.
Major changes with snapshot 20100101
====================================
-Periodic cache cleanup for the postscreen(8) and verify(8) cache
-databases. The time between cache cleanup runs is controlled with
-the address_verify_cache_cleanup_interval (default: 12h) and
-postscreen_cache_cleanup_interval (default: 12h) parameters. Cache
+Periodic cache cleanup for the postscreen(8) cache database. The
+time between cache cleanup runs is controlled with the
+postscreen_cache_cleanup_interval (default: 12h) parameter. Cache
cleanup increases the database access latency, so this should not
be run more often than necessary.
the permanent blacklist. This makes the whitelist easier to use
for its intended purpose, which is to receive mail.
-Major changes with snapshot 20091209
-====================================
-
-sender_dependent_default_transport_maps, a per-sender override for
-default_transport. It's original motivation is to use different
-output channels (with different source IP addresses) for different
-sender addresses, in order to keep their IP-based reputations
-separate from each other.
-
-The result value syntax is that of default_transport, not transport_maps.
-Thus, sender_dependent_default_transport_maps does not support the
-special transport_maps result value syntax for null transport, null
-nexthop, or null email address.
-
-This feature makes sender_dependent_relayhost_maps pretty much
-redundant (though sender_dependent_relayhost_maps will often be
-easier to use because that is the only thing people want to override).
-
-Major changes with snapshot 20091109
-====================================
-
-Improved before-queue filter performance. With "smtpd_proxy_options
-= speed_adjust", the Postfix SMTP server receives the entire message
-before it connects to a before-queue content filter. This means you
-can run more SMTP server processes with the same number of running
-content filter processes, and thus, handle more mail. This feature
-is off by default until it is proven to create no new problems.
-
-This addresses a concern of people in Europe who want to reject all
-bad mail with a before-queue filter. The alternative, an after-queue
-filter, means they would have to discard bad mail (which is illegal)
-or bounce bad mail (which violates good network citizenship).
-
-NOTE 1: When this feature is turned on, a filter cannot selectively
-reject recipients of a multi-recipient message. It is OK to reject
-all recipients of the same multi-recipient message, as is deferring
-or accepting all recipients of the same multi-recipient message.
-
-NOTE 2: This feature increases the minimum amount of free queue
-space by $message_size_limit. The extra space is needed to save the
-message to a temporary file.
-
-To keep the performance overhead low, the same temporary file is
-reused with successive mail transactions (the file is of course
-truncated before reuse, so there is no information leakage).
-
Incompatibility with snapshot 20091008
======================================
implementation, the connection may instead be passed to a dummy
SMTP protocol engine that logs sender and recipient information
before dropping the connection.
-
-Incompatibility with snapshot 20090606
-======================================
-
-The "postmulti -e destroy" command no longer attempts to remove
-files that are created AFTER "postmulti -e create". It still works
-as expected immediately after creating an instance by mistake.
-Trying to automatically remove other files is too risky because
-Postfix-owned directories are by design not trusted.
-
-Major changes with snapshot 20090606
-====================================
-
-Support for header checks on Milter-generated message headers. This
-can be used, for example, to control mail flow with Milter-generated
-headers with indicators for badness or goodness. For details, see
-the postconf(5) section for "milter_header_checks". Currently, all
-header_checks features are implemented except PREPEND.
--- /dev/null
+The stable Postfix release is called postfix-2.7.x where 2=major
+release number, 7=minor release number, x=patchlevel. The stable
+release never changes except for patches that address bugs or
+emergencies. Patches change the patchlevel and the release date.
+
+New features are developed in snapshot releases. These are called
+postfix-2.8-yyyymmdd where yyyymmdd is the release date (yyyy=year,
+mm=month, dd=day). Patches are never issued for snapshot releases;
+instead, a new snapshot is released.
+
+The mail_release_date configuration parameter (format: yyyymmdd)
+specifies the release date of a stable release or snapshot release.
+
+If you upgrade from Postfix 2.5 or earlier, read RELEASE_NOTES-2.6
+before proceeding.
+
+Major changes - performance
+---------------------------
+
+[Feature 20100101] Periodic cache cleanup for the verify(8) cache
+database. The time between cache cleanup runs is controlled with
+the address_verify_cache_cleanup_interval (default: 12h) parameter.
+Cache cleanup increases the database access latency, so this should
+not be run more often than necessary.
+
+[Feature 20091109] Improved before-queue filter performance. With
+"smtpd_proxy_options = speed_adjust", the Postfix SMTP server
+receives the entire message before it connects to a before-queue
+content filter. This means you can run more SMTP server processes
+with the same number of running content filter processes, and thus,
+handle more mail. This feature is off by default until it is proven
+to create no new problems.
+
+This addresses a concern of people in Europe who want to reject all
+bad mail with a before-queue filter. The alternative, an after-queue
+filter, means they would have to discard bad mail (which is illegal)
+or bounce bad mail (which violates good network citizenship).
+
+NOTE 1: When this feature is turned on, a filter cannot selectively
+reject recipients of a multi-recipient message. It is OK to reject
+all recipients of the same multi-recipient message, as is deferring
+or accepting all recipients of the same multi-recipient message.
+
+NOTE 2: This feature increases the minimum amount of free queue
+space by $message_size_limit. The extra space is needed to save the
+message to a temporary file.
+
+To keep the performance overhead low, the same temporary file is
+reused with successive mail transactions (the file is of course
+truncated before reuse, so there is no information leakage).
+
+Major changes - sender reputation
+---------------------------------
+
+[Feature 20100117] The FILTER action in access maps or header/body_checks
+now supports sender reputation schemes that dynamically choose the
+SMTP source IP address. Typically, mail is split into classes, and
+all mail in class X is sent out from an SMTP client IP address that
+is reserved for class X.
+
+This is implemented by specifying FILTER actions with empty next-hop
+destinations in access maps or header/body_checks, and by configuring
+in master.cf one Postfix SMTP client for each SMTP source IP address,
+where each client has its own "-o myhostname" and "-o smtp_bind_address"
+settings.
+
+[Feature 20091209] sender_dependent_default_transport_maps, a
+per-sender override for default_transport. The original motivation
+is to use different output channels (with different source IP
+addresses) for different sender addresses, in order to keep their
+IP-based reputations separate from each other.
+
+The result value syntax is that of default_transport, not transport_maps.
+Thus, sender_dependent_default_transport_maps does not support the
+special transport_maps result value syntax for null transport, null
+nexthop, or null email address.
+
+This feature makes sender_dependent_relayhost_maps pretty much
+redundant (though sender_dependent_relayhost_maps will often be
+easier to use because that is the only thing people want to override).
+
+Major changes - address verification
+------------------------------------
+
+[Incompat 20100101] The verify(8) service now uses a persistent
+cache by default (address_verify_map = btree:$data_directory/verify_cache).
+To disable, specify "address_verify_map =" in main.cf.
+
+When periodic cache cleanup is enabled (the default), the verify(8)
+server now requires that the cache database supports the "delete"
+and "sequence" operations. To disable periodic cache cleanup specify
+a zero address_verify_cache_cleanup_interval value.
+
+[Feature 20100101] Periodic cache cleanup for the verify(8) cache
+database. The time between cache cleanup runs is controlled with
+the address_verify_cache_cleanup_interval (default: 12h) parameter.
+Cache cleanup increases the database access latency, so this should
+not be run more often than necessary.
+
+Major changes - content filter
+------------------------------
+
+[Incompat 20100117] The meaning of an empty filter next-hop destination
+has changed (for example, "content_filter = foo:" or "FILTER foo:").
+Postfix now uses the recipient domain, instead of using $myhostname
+as in Postfix 2.6 and earlier. To restore the old behavior specify
+"default_filter_nexthop = $myhostname", or specify a non-empty
+next-hop content filter destination.
+
+This compatibility option is not needed with SMTP-based content
+filters, because these always have an explicit next-hop destination.
+
+With pipe-based filters that specify no next-hop destination, the
+compatibility option restores the FIFO order of deliveries. Without
+the compatibility option, the delivery order for filters without
+next-hop destination changes to round-robin domain selection.
+
+[Feature 20100117] The FILTER action in access maps or header/body_checks
+now supports sender reputation schemes that dynamically choose the
+SMTP source IP address. Typically, mail is split into classes, and
+all mail in class X is sent out from an SMTP client IP address that
+is reserved for class X.
+
+This is implemented by specifying FILTER actions with empty next-hop
+destinations in access maps or header/body_checks, and by configuring
+in master.cf one Postfix SMTP client for each SMTP source IP address,
+where each client has its own "-o myhostname" and "-o smtp_bind_address"
+settings.
+
+[Feature 20091109] Improved before-queue filter performance. With
+"smtpd_proxy_options = speed_adjust", the Postfix SMTP server
+receives the entire message before it connects to a before-queue
+content filter. This means you can run more SMTP server processes
+with the same number of running content filter processes, and thus,
+handle more mail. This feature is off by default until it is proven
+to create no new problems.
+
+This addresses a concern of people in Europe who want to reject all
+bad mail with a before-queue filter. The alternative, an after-queue
+filter, means they would have to discard bad mail (which is illegal)
+or bounce bad mail (which violates good network citizenship).
+
+NOTE 1: When this feature is turned on, a filter cannot selectively
+reject recipients of a multi-recipient message. It is OK to reject
+all recipients of the same multi-recipient message, as is deferring
+or accepting all recipients of the same multi-recipient message.
+
+NOTE 2: This feature increases the minimum amount of free queue
+space by $message_size_limit. The extra space is needed to save the
+message to a temporary file.
+
+To keep the performance overhead low, the same temporary file is
+reused with successive mail transactions (the file is of course
+truncated before reuse, so there is no information leakage).
+
+Major changes - milter
+----------------------
+
+[Feature 20090606] Support for header checks on Milter-generated
+message headers. This can be used, for example, to control mail
+flow with Milter-generated headers that carry indicators for badness
+or goodness. For details, see the postconf(5) section for
+"milter_header_checks". Currently, all header_checks features are
+implemented except PREPEND.
+
+Major changes - multi-instance support
+--------------------------------------
+
+[Incompat 20090606] The "postmulti -e destroy" command no longer
+attempts to remove files that are created AFTER "postmulti -e
+create". It still works as expected immediately after creating an
+instance by mistake. Trying to automatically remove other files
+is too risky because Postfix-owned directories are by design not
+trusted.
+
Remove this file from the stable release.
- Should the postscreen temporary cache remember hosts that
- are listed in the permanent white/black lists, and be queried
- first? Skipping white/black list lookups will speed up the
- handling of "good" clients without a permanent whitelist
- entry. Of course, this means that updates to the white/black
- lists do not immediately take effect. Workarounds: 1) ignore
- cached white/black list lookup results after "postfix
- reload"; 2) use a short temporary cache TTL for clients on
- the permanent black/white lists; 3) adjust the logging, for
- example "WHITELISTED address (cached)" and "BLACKLISTED
- address (cached)" to eliminate surprises. Comparing the
- cache entry time with the white/blacklist file modification
- time is not foolproof: for example, pcre or CIDR tables are
- read only once.
+ The cleanup virtual alias expansion limit does not really
+ deliver on its promises. 1) It promises to truncate the
+ result without aborting delivery, which would be undesirable
+ anyway, but that is not what it does, so that is good. 2)
+ It keeps all the recipients from multi-recipient database
+ lookup, then terminates further recursion when the result
+ exceeds the expansion limit. This behavior achieves the
+ original goal that all things shall have a finite size (even
+ though but we don'really care how large they are) but may
+ result in surprises when recipients are listed in virtual
+ alias domains or need expansion for other reasons. In a
+ phone call with Victor, a reasonable way out is to set the
+ limit to some large number (100000) and abort delivery when
+ the result exceeds the limit.
+
+ Should the postscreen save permanent white/black list lookup
+ results int the temporary cache, and query the temporary
+ cache first? Skipping white/black list lookups will speed
+ up the handling of "good" clients without a permanent
+ whitelist entry. Of course, this means that updates to the
+ white/black lists do not immediately take effect. Workarounds:
+ 1) use a shorter temporary cache TTL for clients on the
+ permanent black/white lists; 2) ignore cached white/black
+ list lookup results after "postfix reload"; 2) adjust the
+ logging, for example "WHITELISTED address (cached)" and
+ "BLACKLISTED address (cached)" to eliminate surprises.
+ Comparing the cache entry time with the white/blacklist
+ file modification time is not foolproof: for example, pcre
+ or CIDR tables are read only once.
It would be nice if the generic dict_cache(3) cache manager
could postpone process suicide until cache cleanup is
<h2>WARNING </h2>
-<p> The sender/recipient address verification feature described in this
-document is suitable only for low-traffic sites. It performs poorly
-under high load; excessive sender address verification activity may
-even cause your site to be blacklisted by some
-providers. See the "<a href="#limitations">Limitations</a>" section
-below for details. </p>
+<p> Recipient address verification may cause an increased load on
+down-stream servers in the case of a dictionary attack or a flood
+of backscatter bounces. Sender address verification may cause your
+site to be blacklisted by some providers. See also the "<a
+href="#limitations">Limitations</a>" section below for more. </p>
<h2><a name="summary">What Postfix address verification can do for you</a></h2>
<p> The technique has obvious uses to reject junk mail
with an unreplyable sender address. </p>
-<p> The technique may also be useful to block mail for undeliverable
+<p> The technique is also useful to block mail for undeliverable
recipients, for example on a mail <a href="postconf.5.html#relayhost">relay host</a> that does not have a
list of all the valid recipient addresses. This prevents undeliverable
junk mail from entering the queue, so that Postfix doesn't have to
<blockquote>
-<table>
+<table border="0">
<tr>
- <td bgcolor="#f0f0ff" align="center" valign="middle"> Internet
+ <td rowspan="2" colspan="5" align="center" valign="middle">
+ </td>
+
+ <td rowspan="3" align="center" valign="bottom"> <tt> -> </tt>
</td>
- <td align="center" valign="middle"> <tt> -> </tt> </td>
+ <td rowspan="3" align="center" valign="middle"> probe<br>
+ message </td>
- <td bgcolor="#f0f0ff" align="center" valign="middle"> <a
- href="smtpd.8.html">Postfix<br> SMTP<br> server</a> </td>
+ <td rowspan="3" align="center" valign="middle"> <tt> -> </tt>
+ </td>
- <td colspan="2" align="center" valign="middle"> <tt> <->
- </tt> </td>
+ <td rowspan="3" bgcolor="#f0f0ff" align="center" valign="middle">
+ Postfix<br> mail<br> queue </td>
- <td bgcolor="#f0f0ff" colspan="3" align="center" valign="middle">
- <a href="verify.8.html">Postfix<br> verify<br> server</a>
- </td>
+</tr>
+
+<tr> </tr>
+
+<tr>
+
+ <td rowspan="3" align="center" valign="middle"> Internet </td>
+
+ <td rowspan="3" align="center" valign="middle"> <tt> -> </tt>
+ </td>
+
+ <td rowspan="3" bgcolor="#f0f0ff" align="center" valign="middle">
+ <a href="smtpd.8.html">Postfix<br> SMTP<br> server</a> </td>
- <td colspan="2" align="center" valign="middle"> <tt> <->
+ <td rowspan="3" align="center" valign="middle"> <tt> <->
</tt> </td>
- <td bgcolor="#f0f0ff" align="center" valign="middle"> Address<br>
- verification<br> database </td>
+ <td rowspan="3" bgcolor="#f0f0ff" align="center" valign="middle">
+ <a href="verify.8.html">Postfix<br> verify<br> server</a>
+ </td>
</tr>
<tr>
- <td colspan="3"> </td>
+ <td rowspan="1" colspan="3"> </td>
- <td> </td>
+ <td rowspan="1" align="center" valign="middle"> <tt> |</tt><br>
+ <tt> v</tt> </td>
- <td colspan="2" align="right" valign="middle"> <tt> |</tt><br>
- probe<br> messages<br> <tt> v </tt> </td>
+</tr>
- <td> </td>
+<tr>
- <td colspan="2" align="left" valign="middle"> ^<br> delivery<br>
- status<br> <tt> | </tt> </td>
+ <td rowspan="3" align="center" valign="top"> <tt> <- </tt>
+ </td>
+
+ <td rowspan="3" align="center" valign="middle"> probe<br>
+ status </td>
- <td> </td>
+ <td rowspan="3" align="center" valign="middle"> <tt> <- </tt>
+ </td>
- <td> </td>
+ <td rowspan="3" bgcolor="#f0f0ff" align="center" valign="middle">
+ Postfix<br> delivery<br> agents </td>
+
+ <td rowspan="3" align="left" valign="middle"> <tt>-></tt>
+ Local<br> <tt>-></tt> Remote</td>
</tr>
<tr>
- <td> </td>
-
- <td> </td>
+ <td rowspan="3" colspan="4" align="center" valign="middle">
+ </td>
- <td> </td>
+ <td rowspan="3" align="center" valign="middle"> <tt>
+ ^</tt><br> <tt> |</tt><br> <tt> v</tt> </td>
- <td> </td>
+</tr>
- <td colspan="2" bgcolor="#f0f0ff" align="center" valign="middle">
- Postfix<br> queue </td>
+<tr> </tr>
- <td align="center" valign="middle"> <tt> -> </tt> </td>
+<tr> <td colspan="4"> </td> </tr>
- <td colspan="2" bgcolor="#f0f0ff" align="center" valign="middle">
- Postfix<br> delivery<br> agents </td>
+<tr>
- <td> </td>
+ <td colspan="4" align="center" valign="middle"> </td>
- <td> </td>
+ <td bgcolor="#f0f0ff" align="center" valign="middle">
+ Address<br> verification<br> database </td>
</tr>
MTA for that address, without actually delivering mail to it. If
the nearest MTA accepts the address, then Postfix assumes that the
address is deliverable. In reality, mail for a remote address can
-bounce AFTER the nearest MTA accepts the recipient address. </p>
+bounce AFTER the nearest MTA accepts the recipient address, or AFTER
+the nearest MTA accepts the message content. </p>
<li> <p> Some sites may blacklist you when you are probing them
too often (a probe is an SMTP session that does not deliver mail),
<li> <p> Postfix assumes that an address is undeliverable when the
nearest MTA for the address rejects the probe, regardless of the
reason for rejection (client rejected, HELO rejected, MAIL FROM
-rejected, etc.). Thus, Postfix rejects mail when the sender's MTA
-rejects mail from your machine. This is a good thing. </p>
+rejected, etc.). Thus, Postfix rejects an address when the nearest
+MTA for that address rejects mail from your machine for any reason.
+This is not a limitation, but it is mentioned here just in case
+people believe that it is a limitation. </p>
-<li> <p> Unfortunately, some major sites such as YAHOO do not reject
+<li> <p> Unfortunately, some sites do not reject
unknown addresses in reply to the RCPT TO command, but report a
delivery failure in response to end of DATA after a message is
transferred. Postfix address verification does not work with such
sites. </p>
-<li> <p> By default, Postfix probe messages have "double-bounce@$<a href="postconf.5.html#myorigin">myorigin</a>"
-as the sender address (with Postfix versions before 2.5, the default
+<li> <p> By default, Postfix probe messages have a sender address
+"double-bounce@$<a href="postconf.5.html#myorigin">myorigin</a>" (with Postfix versions before 2.5, the
+default
is "postmaster@$<a href="postconf.5.html#myorigin">myorigin</a>"). This is SAFE because the Postfix SMTP
server does not reject mail for this address. </p>
-<p> You can change this into the null address ("<a href="postconf.5.html#address_verify_sender">address_verify_sender</a>
+<p> You can change the probe sender address into the null address
+("<a href="postconf.5.html#address_verify_sender">address_verify_sender</a>
="). This is UNSAFE because address probes will fail with
mis-configured sites that reject MAIL FROM: <>, while
probes from "postmaster@$<a href="postconf.5.html#myorigin">myorigin</a>" would succeed. </p>
<h2><a name="recipient">Recipient address verification</a></h2>
-<p> As mentioned earlier, recipient address verification may be
+<p> As mentioned earlier, recipient address verification is
useful to block mail for undeliverable recipients on a mail relay
host that does not have a list of all valid recipient addresses.
This can help to prevent the mail queue from filling up with
load on down-stream MTAs when you're being flooded by backscatter
bounces, or when some spammer is mounting a dictionary attack. </p>
-<p> By default, address verification results are not saved. To avoid
-probing the same address repeatedly, you can store the result in a
-<a href="#caching">persistent database</a> as described later. </p>
+<p> By default, address verification results are saved in a <a
+href="#caching">persistent database</a> (Postfix version 2.7 and
+later; with earlier versions, specify the database in <a href="postconf.5.html">main.cf</a> as
+described later). The persistent database helps to avoid probing
+the same address repeatedly. </p>
<blockquote>
<pre>
# Postfix 2.6 and later.
# <a href="postconf.5.html#unverified_sender_defer_code">unverified_sender_defer_code</a> = 250
+ # Default setting for Postfix 2.7 and later.
# Note 1: Be sure to read the "<a href="#caching">Caching</a>" section below!
# Note 2: Avoid hash files here. Use btree instead.
<a href="postconf.5.html#address_verify_map">address_verify_map</a> = btree:/var/lib/postfix/verify
/etc/postfix/sender_access:
+ # Don't do this when you handle lots of email.
aol.com <a href="postconf.5.html#reject_unverified_sender">reject_unverified_sender</a>
hotmail.com <a href="postconf.5.html#reject_unverified_sender">reject_unverified_sender</a>
bigfoot.com <a href="postconf.5.html#reject_unverified_sender">reject_unverified_sender</a>
# Postfix 2.6 and later.
# <a href="postconf.5.html#unverified_sender_reject_reason">unverified_sender_reject_reason</a> = Address verification failed
+ # Default setting for Postfix 2.7 and later.
# Note 1: Be sure to read the "<a href="#caching">Caching</a>" section below!
# Note 2: Avoid hash files here. Use btree instead.
<a href="postconf.5.html#address_verify_map">address_verify_map</a> = btree:/var/lib/postfix/verify
<h2><a name="caching">Address verification database</a></h2>
<p> To improve performance, the Postfix <a href="verify.8.html">verify(8)</a> daemon can save
-address verification results to a persistent database. The
+address verification results to a persistent database. This is
+enabled by default with Postfix 2.7 and later. The
<a href="postconf.5.html#address_verify_map">address_verify_map</a> (NOTE: singular) configuration parameter specifies
persistent storage for sender or recipient address verification
results. If you specify an empty value, all address verification
<li> <p> The <a href="verify.8.html">verify(8)</a> server verifies that a sender or recipient
address is deliverable before the <a href="smtpd.8.html">smtpd(8)</a> server accepts it. The
-<a href="verify.8.html">verify(8)</a> server injects probe messages into the Postfix queue and
-processes status updates from delivery agents and/or queue manager.
+<a href="verify.8.html">verify(8)</a> server queries a cache with address verification results.
+If a result is not found, the <a href="verify.8.html">verify(8)</a> server injects a probe
+message into the Postfix queue and processes the status update from
+a delivery agent or queue manager.
This process is described in the <a href="ADDRESS_VERIFICATION_README.html">ADDRESS_VERIFICATION_README</a>
document. The <a href="verify.8.html">verify(8)</a> service is available with Postfix version
2.1 and later. </p>
<table>
-<tr> <td> Network </td> <td> <tt> -> </tt> </td> <td align="center"
-bgcolor="#f0f0ff"> <a href="smtpd.8.html">smtpd(8)</a> </td> <td> <tt> <-> </tt> </td>
-<td align="center" bgcolor="#f0f0ff"> <a href="verify.8.html">verify(8)</a> </td> <td> <tt>
--> </tt> </td> <td align="center" bgcolor="#f0f0ff"> <a href="cleanup.8.html">cleanup(8)</a>
-</td> <td> <tt> -> </tt> </td> <td align="center" bgcolor="#f0f0ff">
-<a href="qmgr.8.html">qmgr(8)</a><br> Postfix <br>queue </td> <td> <tt> -> </tt> </td>
-<td align="center" bgcolor="#f0f0ff"> Delivery<br> agents</td>
+<tr>
+
+ <td rowspan="2" colspan="5" align="center" valign="middle">
+ </td> <td rowspan="3" align="center" valign="bottom">
+ <tt> -> </tt> </td> <td rowspan="3" align="center"
+ valign="middle"> probe<br> message </td> <td rowspan="3"
+ align="center" valign="middle"> <tt> -> </tt> </td> <td
+ rowspan="3" bgcolor="#f0f0ff" align="center" valign="middle">
+ Postfix<br> mail<br> queue </td>
+
</tr>
-<tr> <td colspan="5"> </td> <td align="right"> <table> <tr> <td>
-\ </td> <td> </td> </tr> <tr> <td> </td> <td> \ </td> </tr> </table>
-</td> <td align="center" valign="bottom"> <tt> <- </tt> </td>
-<td valign="bottom"> <tt> <- </tt> </td> <td align="center">
-<tt> |<br> v </tt> </td> <td align="center"> <table> <tr> <td>
-</td> <td> / </td> </tr> <tr> <td> / </td> <td> </td> </tr> </table>
+<tr> </tr>
+
+<tr>
+
+ <td rowspan="3" align="center" valign="middle"> Network </td>
+ <td rowspan="3" align="center" valign="middle"> <tt> -> </tt>
+ </td> <td rowspan="3" bgcolor="#f0f0ff" align="center"
+ valign="middle"> <a href="smtpd.8.html">smtpd(8)</a> </td> <td rowspan="3" align="center"
+ valign="middle"> <tt> <-> </tt> </td> <td rowspan="3"
+ bgcolor="#f0f0ff" align="center" valign="middle"> <a href="verify.8.html">verify(8)</a>
+ </td>
+
+</tr>
+
+<tr>
+
+ <td rowspan="1" colspan="3"> </td> <td rowspan="1" align="center"
+ valign="middle"> <tt> |</tt><br> <tt> v</tt> </td>
+
+</tr>
+
+<tr>
+
+ <td rowspan="3" align="center" valign="top"> <tt> <- </tt>
+ </td> <td rowspan="3" align="center" valign="middle"> probe<br>
+ status </td> <td rowspan="3" align="center" valign="middle">
+ <tt> <- </tt> </td> <td rowspan="3" bgcolor="#f0f0ff"
+ align="center" valign="middle"> Postfix<br> delivery<br> agents
+ </td> <td rowspan="3" align="left" valign="middle"> <tt>-></tt>
+ Local<br> <tt>-></tt> Network</td>
+
+</tr>
+
+<tr>
+
+ <td rowspan="3" colspan="4" align="center" valign="middle">
+ </td> <td rowspan="3" align="center" valign="middle">
+ <tt> ^</tt><br> <tt> |</tt><br> <tt> v</tt> </td>
+
+</tr>
+
+<tr> </tr>
+
+<tr> <td colspan="4"> </td> </tr>
+
+<tr>
+
+ <td colspan="4" align="center" valign="middle"> </td>
+ <td bgcolor="#f0f0ff" align="center" valign="middle"> Address<br>
+ verification<br> cache </td>
+
+</tr>
+
+</table>
+
+<li> <p> The <a href="postscreen.8.html">postscreen(8)</a> server can be put "in front" of Postfix
+<a href="smtpd.8.html">smtpd(8)</a> processes. Its purpose is to accept connections from the
+network and to decide what SMTP clients are allowed to talk to
+Postfix. According to the 2008 MessageLabs annual report, 81% of
+all email was spam, and 90% of that was sent by botnets. While
+<a href="postscreen.8.html">postscreen(8)</a> keeps the zombies away, more <a href="smtpd.8.html">smtpd(8)</a> processes remain
+available for legitimate clients. </p>
+
+<p> The <a href="postscreen.8.html">postscreen(8)</a> server is still evolving, and is likely to
+undergo changes that break compatibility with earlier versions.
+For this reason the <a href="postscreen.8.html">postscreen(8)</a> server is not installed with the
+stable Postfix release. </p>
+
+<table>
+
+<tr> <td> zombie </td> </tr>
+
+<tr> <td> </td> <td align="left"> <tt> \ </tt> </td> </tr>
+
+<tr> <td> zombie </td> <td align="left"> <tt> - </tt> </td> <td>
+</td> <td> </td> <td> </td> <td align="right"> <tt> - </tt> </td>
+<td bgcolor="#f0f0ff" align="center"> <a href="smtpd.8.html">smtpd(8)</a> </td> </tr>
+
+<tr> <td> </td> <td align="right"> <tt> \ </tt> </td> <td> </td>
+<td align="left"> <tt> / </tt> </td> </tr>
+
+<tr> <td bgcolor="#f0f0ff" align="center"> other </td> <td> <tt>
+--- </tt> </td> <td bgcolor="#f0f0ff" align="center" valign="middle">
+<a href="postscreen.8.html">postscreen(8)</a> </td> </tr>
+
+<tr> <td> </td> <td align="right"> <tt> / </tt> </td> <td> </td>
+<td align="right"> <tt> \ </tt> </td> </tr>
+
+<tr> <td bgcolor="#f0f0ff" align="center"> other </td> <td align="left">
+<tt> - </tt> </td> <td> </td> <td> </td> <td> </td> <td align="right">
+<tt> - </tt> </td> <td bgcolor="#f0f0ff" align="center"> <a href="smtpd.8.html">smtpd(8)</a>
</td> </tr>
+<tr> <td> </td> <td align="left"> <tt> / </tt> </td> </tr>
+
+<tr> <td> zombie </td> </tr>
+
+
</table>
</ul>
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
-<html>
-
<head>
<title>Postfix SASL Howto</title>
<hr>
-<h2>WARNING</h2>
+<h2>Warning</h2>
<p> People who go to the trouble of installing Postfix may have the
expectation that Postfix is more secure than some other mailers.
-The Cyrus SASL library is a lot of code. With this, Postfix becomes
-as secure as other mail systems that use the Cyrus SASL library.
-Dovecot provides an alternative that may be worth considering.
-</p>
+The Cyrus SASL library contains a lot of code. With this, Postfix
+becomes as secure as other mail systems that use the Cyrus SASL
+library. Dovecot provides an alternative that may be worth
+considering. </p>
+
+<h2><a name="intro">How Postfix uses SASL authentication</a></h2>
+
+<p> When an SMTP client connects to an SMTP server, the server needs
+to decide whether that client is authorized to send mail to remote
+destinations, or whether the client can send mail only to the
+destinations that the server itself is responsible for. Usually,
+the SMTP server will allow mail to remote destinations only if the
+client's IP address is in the "same network" as the server's IP
+address. </p>
+
+<p> Sometimes the SMTP client and server are in different networks,
+but the client still needs "same network" privileges. To address
+this problem, Postfix supports SASL authentication (<a href="http://tools.ietf.org/html/rfc4954">RFC 4954</a>,
+formerly <a href="http://tools.ietf.org/html/rfc2554">RFC 2554</a>). With this a remote SMTP client can authenticate
+to the Postfix SMTP server, and the Postfix SMTP client can
+authenticate to a remote SMTP server. Once the client is authenticated
+the server can give it "same network" privileges. </p>
+
+<p> Postfix does not implement SASL itself, but instead uses existing
+implementations as building blocks. This means that some SASL-related
+configuration will involve files that belong to Postfix, while other
+configuration will involve files that belong to the specific SASL
+implementation that Postfix will use. This document covers both the
+Postfix and non-Postfix configuration. </p>
+
+<p> You can read more about the following topics: </p>
-<h2><a name="intro">How Postfix uses SASL authentication information</a></h2>
+<ul>
-<p> Postfix SASL support (<a href="http://tools.ietf.org/html/rfc4954">RFC 4954</a>, formerly RFC 2554) can be used
-to authenticate
-remote SMTP clients to the Postfix SMTP server, and to authenticate
-the Postfix SMTP client to a remote SMTP server. </p>
+<li><a href="#server_sasl">Configuring SASL authentication in the
+Postfix SMTP server</a></li>
-<p> When receiving mail, the Postfix SMTP server logs the client-provided
-username,
-authentication method, and sender address to the maillog file, and
-optionally grants mail access via the <a href="postconf.5.html#permit_sasl_authenticated">permit_sasl_authenticated</a>
-UCE restriction. </p>
+<li><a href="#client_sasl">Configuring SASL authentication in the Postfix SMTP/LMTP client</a></li>
-<p> When sending mail, the Postfix SMTP client can look up the
-remote SMTP server hostname or
-destination domain (the address right-hand part) in a SASL password
-table, and if a username/password is found, it will use that username
-and password to authenticate to the remote SMTP server. And as of
-version 2.3,
-Postfix can be configured to search its SASL password table by the
-sender email address. </p>
+<li><a href="#postfix_build">Building Postfix with SASL support</a></li>
-<p>This document covers the following topics: </p>
+<li><a href="#cyrus_legacy">Using Cyrus SASL version 1.5.x</a></li>
-<ul>
+<li><a href="#credits">Credits</a></li>
-<li><a href="#versions">What SASL implementations are supported</a>
+</ul>
-<li><a href="#build_dovecot">Building Postfix with Dovecot SASL
-support</a></li>
+<h2><a name="server_sasl">Configuring SASL authentication in the
+Postfix SMTP server</a></h2>
-<li><a href="#build_sasl">Building the Cyrus SASL library</a>
+<p> As mentioned earlier, SASL is implemented separately from
+Postfix. For this reason, configuring SASL authentication in the
+Postfix SMTP server involves two different steps: </p>
-<li><a href="#build_postfix">Building Postfix with Cyrus SASL
-support</a></li>
+<ul>
-<li><a href="#server_sasl">Enabling SASL authentication in the
-Postfix SMTP server</a></li>
+<li> <p> Configuring the SASL implementation to offer a list of
+mechanisms that are suitable for SASL authentication and, depending
+on the SASL implementation used, configuring authentication backends
+that verify the remote SMTP client's authentication data against
+the system password file or some other database. </p> </li>
-<li><a href="#server_dovecot">Dovecot SASL configuration for the Postfix
-SMTP server</a></li>
+<li> <p> Configuring the Postfix SMTP server to enable SASL
+authentication, and to authorize clients to relay mail or to control
+what envelope sender addresses the client may use. </p> </li>
-<li><a href="#server_cyrus">Cyrus SASL configuration for the Postfix
-SMTP server</a></li>
+</ul>
-<li><a href="#server_test">Testing SASL authentication in the
-Postfix SMTP server</a></li>
+<p> Successful authentication in the Postfix SMTP server requires
+a functional SASL framework. Configuring SASL should therefore
+always be the first step. </p>
-<li><a href="#debugging">Trouble shooting the SASL internals</a>
+<p> You can read more about the following topics: </p>
-<li><a href="#client_sasl">Enabling SASL authentication in the
-Postfix SMTP client</a></li>
+<ul>
-<li><a href="#client_sasl_sender">Supporting multiple ISP accounts
-in the Postfix SMTP client</a></li>
+<li><a href="#server_which">Which SASL Implementations are
+supported?</a></li>
-<li><a href="#credits">Credits</a>
+<li><a href="#server_dovecot">Configuring Dovecot SASL</a>
-</ul>
+<ul>
-<h2><a name="versions">What SASL implementations are supported</a></h2>
+<li><a href="#server_dovecot_comm">Postfix to Dovecot SASL
+communication</a></li>
-<p> This document describes Postfix with the following SASL
-implementations: </p>
+</ul> </li>
+
+<li><a href="#server_cyrus">Configuring Cyrus SASL</a>
<ul>
-<li> <p> Cyrus SASL version 1 (client and server). </p>
+<li><a href="#server_cyrus_name">Cyrus SASL configuration file
+name</a></li>
-<li> <p> Cyrus SASL version 2 (client and server). </p>
+<li><a href="#server_cyrus_location">Cyrus SASL configuration
+file location</a></li>
-<li> <p> Dovecot protocol version 1 (server only, Postfix version
-2.3 and later) </p>
+<li><a href="#server_cyrus_comm">Postfix to Cyrus SASL
+communication</a></li>
-</ul>
+</ul> </li>
-<p> Postfix version 2.3 introduces a plug-in mechanism that provides
-support for multiple SASL implementations. To find out what
-implementations are built into Postfix, use the following commands:
-</p>
+<li><a href="#server_sasl_enable">Enabling SASL authentication and
+authorization in the Postfix SMTP server</a>
-<blockquote>
-<pre>
-% postconf -a (SASL support in the SMTP server)
-% postconf -A (SASL support in the SMTP+LMTP client)
-</pre>
-</blockquote>
+<ul>
-<p> Needless to say, these commands are not available in earlier
-Postfix versions. </p>
+<li><a href="#server_sasl_authc">Enabling SASL authentication in
+the Postfix SMTP server</a></li>
-<h2><a name="build_dovecot">Building Postfix with Dovecot SASL
-support</a></h2>
+<li><a href="#smtpd_sasl_security_options">Postfix SMTP Server
+Authentication Policy</a></li>
-<p> These instructions assume that you build Postfix from source
-code as described in the <a href="INSTALL.html">INSTALL</a> document. Some modification may
-be required if you build Postfix from a vendor-specific source
-package. </p>
+<li><a href="#server_sasl_authz">Enabling SASL authorization in the Postfix
+SMTP server</a></li>
-<p> Support for the Dovecot version 1 SASL protocol is available
-in Postfix 2.3 and later. At the time
-of writing, only server-side SASL support is available, so you can't
-use it to authenticate to your network provider's server. Dovecot
-uses its own daemon process for authentication. This keeps the
-Postfix build process simple, because there is no need to link extra
-libraries into Postfix. </p>
+<li><a href="#server_sasl_other">Additional SMTP Server SASL options</a></li>
-<p> To generate the necessary Makefiles, execute the following
-in the Postfix top-level directory: </p>
+</ul></li>
-<blockquote>
-<pre>
-% make makefiles CCARGS='-DUSE_SASL_AUTH -DDEF_SERVER_SASL_TYPE=\"dovecot\"'
-</pre>
-</blockquote>
+<li><a href="#server_test">Testing SASL authentication in the Postfix
+SMTP server</a></li>
+
+</ul>
-<p> After this, proceed with "<tt>make</tt>" as described in the
-<a href="INSTALL.html">INSTALL</a> document. </p>
-<p> Notes: </p>
+<h3><a name="server_which">Which SASL Implementations are supported?</a></h3>
-<ul>
+<p> Currently the Postfix SMTP server supports the Cyrus SASL and
+Dovecot SASL implementations. </p>
-<li> <p> The "-DDEF_SERVER_SASL_TYPE" stuff is not necessary; it just
-makes Postfix configuration a little more convenient because you
-don't have to specify the SASL plug-in type in the Postfix <a href="postconf.5.html">main.cf</a>
-file. </p>
+<blockquote>
-<li> <p> If you also want support for LDAP or TLS, you will have to merge
-their CCARGS and AUXLIBS into the above command line. </p>
+<strong>Note</strong>
-</ul>
+<p> Before Postfix version 2.3, Postfix had support only for Cyrus
+SASL. Current Postfix versions have a plug-in architecture that
+can support multiple SASL implementations. </p>
-<h2><a name="build_sasl">Building the Cyrus SASL library</a></h2>
+</blockquote>
-<p> Postfix appears to work with cyrus-sasl-1.5.x or cyrus-sasl-2.1.x,
-which are available from: </p>
+<p> To find out what SASL implementations are compiled into Postfix,
+use the following commands: </p>
<blockquote>
<pre>
-<a href="ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/">ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/</a>
+% <strong><code>postconf -a</code></strong> (SASL support in the SMTP server)
+% <strong><code>postconf -A</code></strong> (SASL support in the SMTP+LMTP client)
</pre>
</blockquote>
-<p> IMPORTANT: if you install the Cyrus SASL libraries as per the
-default, you will have to symlink /usr/lib/sasl -> /usr/local/lib/sasl
-for version 1.5.x or /usr/lib/sasl2 -> /usr/local/lib/sasl2 for
-version 2.1.x. </p>
-
-<p> Reportedly, Microsoft Outlook (Express) requires the
-non-standard LOGIN authentication method. To enable this
-authentication method, specify ``./configure --enable-login''. </p>
+<p> These commands are available only with Postfix version 2.3 and
+later. </p>
-<h2><a name="build_postfix">Building Postfix with Cyrus SASL support</a></h2>
+<h3><a name="server_dovecot">Configuring Dovecot SASL</a></h3>
-<p> These instructions assume that you build Postfix from source
-code as described in the <a href="INSTALL.html">INSTALL</a> document. Some modification may
-be required if you build Postfix from a vendor-specific source
-package. </p>
+<p> Dovecot is a POP/IMAP server that must be configured to
+authenticate POP/IMAP clients. When the Postfix SMTP server uses
+Dovecot SASL, it also reuses this configuration. Consult the <a
+href="http://wiki.dovecot.org">Dovecot documentation</a> for how
+to configure and operate the Dovecot authentication server. </p>
-<p> The following
-assumes that the Cyrus SASL include files are in /usr/local/include,
-and that the Cyrus SASL libraries are in /usr/local/lib. </p>
+<h4><a name="server_dovecot_comm">Postfix to Dovecot SASL communication</a></h4>
-<p> On some systems this generates the necessary Makefile definitions:
+<p> Communication between the Postfix SMTP server
+and Dovecot SASL happens via a UNIX-domain socket. The socket
+pathname and the list of mechanisms offered to Postfix need to be
+specified on the Dovecot server side in <code>dovecot.conf</code>.
</p>
-<dl>
-
-<dt> (for Cyrus SASL version 1.5.x):
-<dd>
-<pre>
-% make tidy # if you have left-over files from a previous build
-% make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
- -I/usr/local/include" AUXLIBS="-L/usr/local/lib -lsasl"
-</pre>
+<p> The following example assumes that the Postfix queue is under
+<code>/var/spool/postfix/</code>. </p>
-<dt> (for Cyrus SASL version 2.1.x):
-<dd>
+<blockquote>
<pre>
-% make tidy # if you have left-over files from a previous build
-% make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
- -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib -lsasl2"
+ 1 /etc/dovecot.conf:
+ 2 auth default {
+ 3 mechanisms = plain login
+ 4 passdb pam {
+ 5 }
+ 6 userdb passwd {
+ 7 }
+ 8 socket listen {
+ 9 client {
+10 path = /var/spool/postfix/private/auth
+11 mode = 0660
+12 user = postfix
+13 group = postfix
+14 }
+15 }
+16 }
</pre>
+</blockquote>
-</dl>
+<p> Line 3 provides <code>plain</code> and <code>login</code> as
+mechanisms for the Postfix SMTP server, line 10 places the Dovecot
+SASL socket in <code>/var/spool/postfix/private/auth</code>, and
+lines 11-13 limit read+write permissions to user and group
+<code>postfix</code> only. </p>
-<p> On Solaris 2.x you need to specify run-time link information,
-otherwise ld.so will not find the SASL shared library: </p>
+<p> Proceed with the section "<a href="#server_sasl_enable"
+title="Enabling SASL authentication and configuring authorization
+in the Postfix SMTP server">Enabling SASL authentication and
+authorization in the Postfix SMTP server</a>" to turn on and use
+SASL in the Postfix SMTP server. </p>
-<dl>
+<h3><a name="server_cyrus">Configuring Cyrus SASL</a></h3>
-<dt> (for Cyrus SASL version 1.5.x):
-<dd>
-<pre>
-% make tidy # if you have left-over files from a previous build
-% make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
- -I/usr/local/include" AUXLIBS="-L/usr/local/lib \
- -R/usr/local/lib -lsasl"
-</pre>
+<p> The Cyrus SASL framework was supports a wide variety of
+applications. Different applications may require different
+configurations. As a consequence each application may have its own
+configuration file. </p>
-<dt> (for Cyrus SASL version 2.1.x):
-<dd>
-<pre>
-% make tidy # if you have left-over files from a previous build
-% make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
- -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib \
- -R/usr/local/lib -lsasl2"
-</pre>
+<p> The first step configuring Cyrus SASL is to determine name and
+location of a configuration file that describes how the Postfix
+SMTP server will use the SASL framework. </p>
-</dl>
+<h4><a name="server_cyrus_name">Cyrus SASL configuration file name</a></h4>
-<h2><a name="server_sasl">Enabling SASL authentication in the Postfix
-SMTP server</a></h2>
+<p> The name of the configuration file (default: <code>smtpd.conf</code>)
+is configurable. It is a concatenation from a value that the Postfix
+SMTP server sends to the Cyrus SASL library, and the suffix
+<code>.conf</code>, added by Cyrus SASL. </p>
-<p> In order to enable SASL support in the Postfix SMTP server: </p>
+<p> The value sent by Postfix is the name of the server component
+that will use Cyrus SASL. It defaults to <code>smtpd</code> and
+is configured with one of the following variables: </p>
<blockquote>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtpd_sasl_auth_enable">smtpd_sasl_auth_enable</a> = yes
-</pre>
-</blockquote>
-
-<p> In order to allow mail relaying by authenticated remote SMTP
-clients: </p>
+ # Postfix 2.3 and later
+ <a href="postconf.5.html#smtpd_sasl_path">smtpd_sasl_path</a> = smtpd
-<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> =
- <a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>
- <a href="postconf.5.html#permit_sasl_authenticated">permit_sasl_authenticated</a>
- <a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a>
+ # Postfix < 2.3
+ <a href="postconf.5.html#smtpd_sasl_application_name">smtpd_sasl_application_name</a> = smtpd
</pre>
</blockquote>
-<p> To report SASL login names in Received: message headers
-(Postfix version 2.3 and later): </p>
+<h4><a name="server_cyrus_location">Cyrus SASL configuration file
+location</a></h4>
-<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtpd_sasl_authenticated_header">smtpd_sasl_authenticated_header</a> = yes
-</pre>
-</blockquote>
+<p> The location where Cyrus SASL searches for the named file depends
+on the Cyrus SASL version and the OS/distribution used. </p>
-<p> Note: the SASL login names will be shared with the entire world.
-</p>
+<p> You can read more about the following topics: </p>
-<p> Older Microsoft SMTP client software implements a non-standard
-version of the AUTH protocol syntax, and expects that the SMTP
-server replies to EHLO with "250 AUTH=mechanism-list" instead of
-"250 AUTH mechanism-list". To accommodate such clients (in addition
-to conformant
-clients) use the following: </p>
+<ul>
-<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#broken_sasl_auth_clients">broken_sasl_auth_clients</a> = yes
-</pre>
-</blockquote>
+<li> <p> Cyrus SASL version 2.x searches for the configuration file
+in <code>/usr/lib/sasl2/</code>. </p> </li>
-<h2><a name="server_dovecot">Dovecot SASL configuration for the
-Postfix SMTP server</a></h2>
+<li> <p> Cyrus SASL version 2.1.22 and newer additionally search
+in <code>/etc/sasl2/</code>. </p> </li>
-<p> Dovecot SASL support is available in Postfix 2.3 and later. On
-the Postfix side you need to specify the location of the
-Dovecot authentication daemon socket. We use a pathname relative
-to the Postfix queue directory, so that it will work whether or not
-the Postfix SMTP server runs chrooted: </p>
+<li> <p> Some Postfix distributions are modified and look for the
+Cyrus SASL configuration file in <code>/etc/postfix/sasl/</code>,
+<code>/var/lib/sasl2/</code> etc. See the distribution-specific
+documentation to determine the expected location. </p> </li>
+
+</ul>
<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtpd_sasl_type">smtpd_sasl_type</a> = dovecot
- <a href="postconf.5.html#smtpd_sasl_path">smtpd_sasl_path</a> = private/auth
-</pre>
-</blockquote>
-<p> On the Dovecot side you also need to specify the Dovecot
-authentication daemon socket. In this case we specify an
-absolute pathname. In the example we assume that the
-Postfix queue is under /var/spool/postfix/. </p>
+<strong>Note</strong>
+
+<p> Cyrus SASL searches <code>/usr/lib/sasl2/</code> first. If it
+finds the specified configuration file there, it will not examine
+other locations. </p>
-<blockquote>
-<pre>
-/some/where/dovecot.conf:
- auth default {
- mechanisms = plain login
- passdb pam {
- }
- userdb passwd {
- }
- socket listen {
- client {
- path = /var/spool/postfix/private/auth
- mode = 0660
- user = postfix
- group = postfix
- }
- }
- }
-</pre>
</blockquote>
-<p> See the Dovecot documentation for how to configure and operate
-the Dovecot authentication server. </p>
+<h4><a name="server_cyrus_comm">Postfix to Cyrus SASL communication</a></h4>
-<h2><a name="server_cyrus">Cyrus SASL configuration for the Postfix
-SMTP server</a></h2>
+<p> As the Postfix SMTP server is linked with the Cyrus SASL library
+<code>libsasl</code>, communication between Postfix and Cyrus SASL
+takes place by calling functions in the SASL library. </p>
-<p> You need to configure how the Cyrus SASL library should
-authenticate a remote SMTP client's username and password. These
-settings must
-be stored in a separate configuration file. </p>
+<p> The SASL library may use an external password verification
+service, or an internal plugin to connect to authentication backends
+and verify the SMTP client's authentication data against the system
+password file or other databases. </p>
-<p> The name of the configuration file (default: smtpd.conf) will
-be constructed from a value that the Postfix SMTP server sends to
-the Cyrus SASL
-library, which adds the suffix .conf. The value is configured using
-one of the following variables: </p>
+<p> The following table shows typical combinations discussed in
+this document: </p>
<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- # Postfix 2.3 and later
- <a href="postconf.5.html#smtpd_sasl_path">smtpd_sasl_path</a> = smtpd
- # Postfix < 2.3
- smtpd_sasl_application_name = smtpd
-</pre>
-</blockquote>
-<p> Cyrus SASL searches for the configuration file in /usr/local/lib/sasl/
-(Cyrus SASL version 1.5.5) or /usr/local/lib/sasl2/ (Cyrus SASL
-version 2.1.x). </p>
+<table border="1">
-<p> Note: some Postfix distributions are modified and look for
-the smtpd.conf file in /etc/postfix/sasl. </p>
+<tr>
-<p> Note: some Cyrus SASL distributions look for the smtpd.conf
-file in /etc/sasl2. </p>
+<th align="center">authentication backend</th>
-<ul>
+<th align="center">password verification service / plugin</th>
-<li> <p> To authenticate against the UNIX password database, use: </p>
+</tr>
-<dl>
-<dt> (Cyrus SASL version 1.5.x)
-<dd>
-<pre>
-/usr/local/lib/sasl/smtpd.conf:
- pwcheck_method: pwcheck
+<tr>
-</pre>
+<td>/etc/shadow</td>
-<p> IMPORTANT: pwcheck establishes a UNIX domain socket in /var/pwcheck
-and waits for authentication requests. The Postfix SMTP server must have
-read+execute permission to this directory or authentication attempts
-will fail. </p>
+<td><a href="#saslauthd">saslauthd</a></td>
-<p> The pwcheck daemon is contained in the cyrus-sasl source tarball. </p>
+</tr>
-<dt> (Cyrus SASL version 1.5.26)
-<dd>
-<pre>
-/usr/local/lib/sasl/smtpd.conf:
- pwcheck_method: saslauthd
-</pre>
+<tr>
-<dt> (Cyrus SASL version 2.1.x)
-<dd>
-<pre>
-/usr/local/lib/sasl2/smtpd.conf:
- pwcheck_method: saslauthd
- mech_list: PLAIN LOGIN
-</pre>
+<td>PAM</td>
-</dl>
+<td><a href="#saslauthd">saslauthd</a></td>
-<p> The saslauthd daemon is also contained in the cyrus-sasl source
-tarball. It is more flexible than the pwcheck daemon, in that it
-can authenticate against PAM and various other sources. To use PAM,
-start saslauthd with "-a pam". </p>
+</tr>
-<p> IMPORTANT: saslauthd usually establishes a UNIX domain socket
-in /var/run/saslauthd and waits for authentication requests. The Postfix
-SMTP server must have read+execute permission to this directory or
-authentication attempts will fail. </p>
+<tr>
-<p> Note: The directory where saslauthd puts the socket is configurable.
-See the command-line option "-m /path/to/socket" in the saslauthd
---help listing. </p>
+<td>IMAP server</td>
-<li> <p> To authenticate against Cyrus SASL's own password database: </p>
+<td><a href="#saslauthd">saslauthd</a></td>
-<dl>
-<dt> (Cyrus SASL version 1.5.x)
-<dd>
-<pre>
-/usr/local/lib/sasl/smtpd.conf:
- pwcheck_method: sasldb
-</pre>
+</tr>
-<dt> (Cyrus SASL version 2.1.x)
-<dd>
-<pre>
-/usr/local/lib/sasl2/smtpd.conf:
- pwcheck_method: auxprop
- auxprop_plugin: sasldb
- mech_list: PLAIN LOGIN CRAM-MD5 DIGEST-MD5
-</pre>
+<tr>
-</dl>
+<td>sasldb</td>
-<p> This will use the Cyrus SASL password file (default: /etc/sasldb in
-version 1.5.x, or /etc/sasldb2 in version 2.1.x), which is maintained
-with the saslpasswd or saslpasswd2 command (part of the Cyrus SASL
-software). On some poorly-supported systems the saslpasswd command needs
-to be run multiple times before it stops complaining. The Postfix SMTP
-server needs read access to the sasldb file - you may have to play games
-with group access permissions. With the OTP authentication mechanism,
-the Postfix SMTP server also needs WRITE access to /etc/sasldb2 or
-/etc/sasldb
-(or the back end SQL database, if used). </p>
+<td><a href="#auxprop_sasldb">sasldb</a></td>
-<p> IMPORTANT: To get sasldb running, make sure that you set the SASL
-domain (realm) to a fully qualified domain name. </p>
+</tr>
-<p> EXAMPLE: </p>
+<tr>
-<dl>
-<dt> (Cyrus SASL version 1.5.x)
-<dd>
-<pre>
-% saslpasswd -c -u `postconf -h <a href="postconf.5.html#myhostname">myhostname</a>` exampleuser
-</pre>
+<td>MySQL, PostgreSQL, SQLite</td>
-<dt> (Cyrus SASL version 2.1.x)
-<dd>
-<pre>
-% saslpasswd2 -c -u `postconf -h <a href="postconf.5.html#myhostname">myhostname</a>` exampleuser
-</pre>
+<td><a href="#auxprop_sql">sql</a></td>
-</dl>
+</tr>
-<p> You can find out SASL's idea about the realms of the users
-in sasldb with <i>sasldblistusers</i> (Cyrus SASL version 1.5.x) or
-<i>sasldblistusers2</i> (Cyrus SASL version 2.1.x). </p>
+<tr>
-<p> On the Postfix side, you can have only one realm per <a href="smtpd.8.html">smtpd(8)</a>
-instance, and only the users belonging to that realm would be able to
-authenticate. The Postfix variable <a href="postconf.5.html#smtpd_sasl_local_domain">smtpd_sasl_local_domain</a> controls the
-realm used by <a href="smtpd.8.html">smtpd(8)</a>: </p>
+<td>LDAP</td>
-<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtpd_sasl_local_domain">smtpd_sasl_local_domain</a> = $<a href="postconf.5.html#myhostname">myhostname</a>
-</pre>
-</blockquote>
+<td><a href="#auxprop_ldapdb">ldapdb</a></td>
-</ul>
+</tr>
-<p> IMPORTANT: The Cyrus SASL password verification services pwcheck
-and saslauthd can only support the plaintext mechanisms PLAIN or
-LOGIN. However, the Cyrus SASL library doesn't know this, and will
-happily advertise other authentication mechanisms that the SASL
-library implements, such as DIGEST-MD5. As a result, if a remote SMTP
-client chooses any mechanism other than PLAIN or LOGIN while pwcheck
-or saslauthd are used, authentication will fail. Thus you may need
-to limit the list of mechanisms advertised by the Postfix SMTP
-server. </p>
+</table>
+
+</blockquote>
-<ul>
+<blockquote>
-<li> <p> With older Cyrus SASL versions you remove the corresponding
-library files from the SASL plug-in directory (and again whenever
-the system is updated). </p>
+<strong>Note</strong>
-<li> <p> With Cyrus SASL version 2.1.x or later the mech_list variable
-can specify a list of authentication mechanisms that Cyrus SASL may
-offer: </p>
+<p> Read the Cyrus SASL documentation for other backends it can
+use. </p>
-<blockquote>
-<pre>
-/usr/local/lib/sasl2/smtpd.conf:
- mech_list: plain login
-</pre>
</blockquote>
-</ul>
+<h4><a name="saslauthd">saslauthd - Cyrus SASL password verification service</a></h4>
-<p> For the same reasons you might want to limit the list of plugins
-used for authentication. </p>
+<p> Communication between the Postfix SMTP server (read: Cyrus SASL's
+<code>libsasl</code>) and the <code>saslauthd</code> server takes
+place over a UNIX-domain socket. </p>
-<ul>
+<p> <code>saslauthd</code> usually establishes the UNIX domain
+socket in <code>/var/run/saslauthd/</code> and waits for authentication
+requests. The Postfix SMTP server must have read+execute permission
+to this directory or authentication attempts will fail. </p>
+
+<blockquote>
-<li> <p> With Cyrus SASL version 1.5.x your only choice is to
-delete the corresponding library files from the SASL plug-in
-directory. </p>
+<strong>Important</strong>
-<li> <p> With SASL version 2.1.x: </p>
+<p> Some distributions require the user <code>postfix</code> to be
+member of a special group e.g. <code>sasl</code>, otherwise it
+will not be able to access the <code>saslauthd</code> socket
+directory. </p>
+
+</blockquote>
+
+<p> The following example configures the Cyrus SASL library to
+contact <code>saslauthd</code> as its password verification service:
+</p>
<blockquote>
<pre>
-/usr/local/lib/sasl2/smtpd.conf:
- pwcheck_method: auxprop
- auxprop_plugin: sql
+/etc/sasl2/smtpd.conf:
+ pwcheck_method: saslauthd
+ mech_list: PLAIN LOGIN
</pre>
</blockquote>
-</ul>
+<blockquote>
-<p> To run software chrooted with SASL support is an interesting
-exercise. It probably is not worth the trouble. </p>
+<strong>Important</strong>
-<h2><a name="server_test">Testing SASL authentication in the Postfix
-SMTP server</a></h2>
+<p> Do not specify any other mechanisms in <code>mech_list</code>
+than <code>PLAIN</code> or <code>LOGIN</code> when using
+<code>saslauthd</code>! It can only handle these two mechanisms,
+and authentication will fail if clients are allowed to choose other
+mechanisms. </p>
-<p> To test the server side, connect (for example, with telnet) to the
-Postfix SMTP server port and you should
-be able to have a conversation as shown below. Information sent by the
-client (that is, you) is shown in bold font. </p>
+</blockquote>
<blockquote>
-<pre>
-$ <b>telnet server.example.com 25</b>
-. . .
-220 server.example.com ESMTP Postfix
-<b>EHLO client.example.com</b>
-250-server.example.com
-250-PIPELINING
-250-SIZE 10240000
-250-ETRN
-250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
-250 8BITMIME
-<b>AUTH PLAIN AHRlc3QAdGVzdHBhc3M=</b>
-235 Authentication successful
-</pre>
-</blockquote>
-<p> Instead of AHRlc3QAdGVzdHBhc3M=, specify the base64 encoded
-form of \0username\0password (the \0 is a null byte). The
-example above is for a user named `test' with password `testpass'.
-</p>
+<strong>Important</strong>
-<p> In order to generate base64 encoded authentication information
-you can use one of the following commands: </p>
+<p> Plaintext mechanisms (<code>PLAIN</code>, <code>LOGIN</code>)
+send credentials unencrypted. This information should be protected
+by an additional security layer such as a TLS-encrypted SMTP session
+(see: <a href="TLS_README.html">TLS_README</a>). </p>
-<blockquote>
-<pre>
-% printf '\0username\0password' | mmencode
-</pre>
</blockquote>
+<p> Additionally the <code>saslauthd</code> server itself must be
+configured. It must be told which authentication backend to turn
+to for password verification. The backend is choosen as a command
+line option when <code>saslauthd</code> is started and will be shown
+in the following examples. </p>
+
<blockquote>
-<pre>
-% perl -MMIME::Base64 -e \
- 'print encode_base64("\0username\0password");'
-</pre>
+
+<strong>Note</strong>
+
+<p> Some distributions use a configuration file to provide saslauthd
+command line options to set e.g. the authentication backend. Typical
+locations are <code>/etc/sysconfig/saslauthd</code> or
+<code>/etc/default/saslauthd</code>. </p>
+
</blockquote>
-<p> The mmencode command is part of the metamail software.
-MIME::Base64 is available from <a href="http://www.cpan.org/">http://www.cpan.org/</a>. </p>
+<h4><a name="id395661">Using saslauthd with /etc/shadow</a></h4>
-<p> Caution: when posting logs of the SASL negotiations to public
-lists,
-please keep in mind that username/password information is trivial
-to recover from the base64-encoded form. </p>
+<p> Access to the <code>/etc/shadow</code> system password file
+requires <code>root</code> privileges. The Postfix SMTP server
+(and in consequence <code>libsasl</code> linked to the server) runs
+with the least privilege possible. Direct access to
+<code>/etc/shadow</code> would not be possible without breaking the
+Postfix security architecture. </p>
-<h2><a name="debugging">Trouble shooting the SASL internals</a></h2>
+<p> The <code>saslauthd</code> socket builds a safe bridge. Postfix,
+running as limited user <code>postfix</code>, can access the
+UNIX-domain socket that <code>saslauthd</code> receives commands
+on; <code>saslauthd</code>, running as privileged user <code>root</code>,
+has the privileges required to access the shadow file. </p>
-<p> In the Cyrus SASL sources you'll find a subdirectory named
-"sample". Run make there, then create a symbolic link from sample.conf
-to smtpd.conf in your Cyrus SASL library directory /usr/local/lib/sasl2.
-"su" to the user <i>postfix</i> (or whatever your <i><a href="postconf.5.html#mail_owner">mail_owner</a></i>
-directive is set to): </p>
+<p> The <code>saslauthd</code> server verifies passwords against the
+authentication backend <code>/etc/shadow</code> if started like this: </p>
<blockquote>
<pre>
-% su postfix
+% <strong><code>saslauthd -a shadow</code></strong>
</pre>
</blockquote>
-<p> then run the resulting sample Cyrus SASL server and client in
-separate terminals. The sample applications send log messages to
-the syslog
-facility auth. Check the log to fix the problem or run strace /
-ktrace / truss on the server to see what makes it unhappy. Repeat
-the previous step until you can successfully authenticate with the
-sample Cyrus SASL client. Only then get back to Postfix. </p>
+<p> See section "<a href="#testing_saslauthd">Testing saslauthd
+authentication</a>" for test instructions. </p>
-<h2><a name="client_sasl">Enabling SASL authentication in the
-Postfix SMTP client</a></h2>
+<h4><a name="id395745">Using saslauthd with PAM</a></h4>
-<p> Turn on client-side SASL authentication, and specify a table
-with per-host or per-destination username and password information.
-The Postfix SMTP client first searches the table for an entry with
-the remote SMTP server hostname; if no entry is found, then the
-Postfix SMTP client searches the table for
-an entry with the next-hop destination. Usually, that is the
-right-hand part of an email address, but it can also be the information
-that is specified with the <a href="postconf.5.html#relayhost">relayhost</a> parameter or with a <a href="transport.5.html">transport(5)</a>
-table. </p>
+<p> Cyrus SASL can use the PAM framework to authenticate credentials.
+<code>saslauthd</code> uses the PAM framework when started like
+this: </p>
<blockquote>
<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_sasl_auth_enable">smtp_sasl_auth_enable</a> = yes
- <a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> = hash:/etc/postfix/sasl_passwd
- <a href="postconf.5.html#smtp_sasl_type">smtp_sasl_type</a> = cyrus
- <a href="postconf.5.html#relayhost">relayhost</a> = [mail.myisp.net]
- # Alternative form:
- # <a href="postconf.5.html#relayhost">relayhost</a> = [mail.myisp.net]:submission
-
-/etc/postfix/sasl_passwd:
- [mail.myisp.net] username:password
- [mail.myisp.net]:submission username:password
+% <strong><code>saslauthd -a pam</code></strong>
</pre>
</blockquote>
-<p> Notes: </p>
-
-<ul>
+<blockquote>
-<li> <p> The "submission" destination port tells Postfix to send
-mail via TCP network port 587, which is normally reserved for email
-clients. The default is to send mail to the "smtp" destination port
-(TCP port 25), which is used for receiving mail across the internet.
-If you use an explicit destination port in <a href="postconf.5.html">main.cf</a>, then you must
-use the same form also in the <a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> file. </p>
-
-<li> <p> Postfix does not deliver mail via TCP port 465 (the obsolete
-"wrappermode" protocol). See <a href="TLS_README.html">TLS_README</a> for a solution that uses the
-"stunnel" command. </p>
-
-<li> <p> The "[" and "]" prevent Postfix from looking up the MX
-(mail exchanger) records for the enclosed name. If you use this
-form in <a href="postconf.5.html">main.cf</a>, then you must use the same form also in the
-<a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> file. </p>
-
-<li> <p> The Postfix SMTP client opens the SASL client password
-file before entering the optional chroot jail, so you can keep the
-file in /etc/postfix and set permissions read / write only for root
-to keep the username:password combinations away from other system
-users. </p>
-
-<li> <p> Specify <b>dbm</b> instead of <b>hash</b> if your system
-uses <b>dbm</b> files instead of <b>db</b> files. To find out what
-lookup tables Postfix supports, use the command "<b>postconf -m</b>".
-</p>
+<strong>Note</strong>
-<li> <p> Execute the command "<b>postmap /etc/postfix/sasl_passwd</b>"
-whenever you change the sasl_passwd table. </p>
+<p> PAM configuration for the Postfix SMTP server is usually given
+in <code>/etc/pam.d/smtp</code> and is beyond the scope of this
+document. </p>
-</ul>
+</blockquote>
-<p> Workarounds: </p>
+<p> See section "<a href="#testing_saslauthd">Testing saslauthd
+authentication</a>" for test instructions. </p>
-<ul>
+<h4><a name="id395792">Using saslauthd with an IMAP server</a></h4>
-<li> <p> Some remote SMTP servers support PLAIN or LOGIN authentication only.
-By default, the Postfix SMTP client does not use authentication
-methods that send plaintext passwords, and defers delivery with
-the following error message: "Authentication failed: cannot SASL
-authenticate to server". To enable plaintext authentication specify,
-for example: </p>
+<p> <code>saslauthd</code> can verify the SMTP client credentials
+by using them to log into an IMAP server. If the login succeeds,
+SASL authentication also succeeds. <code>saslauthd</code> contacts
+an IMAP server when started like this: </p>
<blockquote>
<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_sasl_security_options">smtp_sasl_security_options</a> = noanonymous
+% <strong><code>saslauthd -a rimap -O imap.example.com</code></strong>
</pre>
</blockquote>
-<li> <p> Some remote SMTP servers announce authentication mechanisms
-that don't actually work. It is possible via the <a href="postconf.5.html#smtp_sasl_mechanism_filter">smtp_sasl_mechanism_filter</a>
-parameter to restrict the list of server mechanisms that the Postfix
-SMTP client will take into consideration: </p>
-
<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_sasl_mechanism_filter">smtp_sasl_mechanism_filter</a> = !gssapi, !external, static:all
-</pre>
+
+<strong>Note</strong>
+
+<p> The option "<code>-O imap.example.com</code>" specifies the
+IMAP server <code>saslauthd</code> should contact when it verifies
+credentials. </p>
+
</blockquote>
-<p> In the above example, the Postfix SMTP client will decline to
-use mechanisms
-that require special infrastructure such as Kerberos or TLS. </p>
+<blockquote>
-<li> <p> The Postfix SMTP client is backwards compatible with SMTP
-servers that use the non-standard "AUTH=method..." syntax in response
-to the EHLO command; there is no Postfix client configuration needed
-to work around it. </p>
+<strong>Important</strong>
-</ul>
+<p> <code>saslauthd</code> sends IMAP login information unencrypted.
+Any IMAP session leaving the local host should be protected by an
+additional security layer such as an SSL tunnel. </p>
-<h2><a name="client_sasl_sender">Supporting multiple ISP accounts
-in the Postfix SMTP client</a></h2>
+</blockquote>
-<p> Postfix version 2.3 supports multiple ISP accounts. This can
-be useful when one person uses the same machine for work and for
-personal use, or when people with different ISP accounts share the
-same Postfix server. To make this possible, Postfix 2.3 supports
-per-sender SASL passwords and per-sender relay hosts. In the example
-below, Postfix will search the SASL password file by sender before
-it searches that same file by destination. Likewise, Postfix will
-search the per-sender <a href="postconf.5.html#relayhost">relayhost</a> file, and use the default <a href="postconf.5.html#relayhost">relayhost</a>
-only as a final resort. </p>
+<p> See section "<a href="#testing_saslauthd">Testing saslauthd
+authentication</a>" for test instructions. </p>
-<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_sender_dependent_authentication">smtp_sender_dependent_authentication</a> = yes
- <a href="postconf.5.html#sender_dependent_relayhost_maps">sender_dependent_relayhost_maps</a> = hash:/etc/postfix/sender_relay
- <a href="postconf.5.html#smtp_sasl_auth_enable">smtp_sasl_auth_enable</a> = yes
- <a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> = hash:/etc/postfix/sasl_passwd
- <a href="postconf.5.html#relayhost">relayhost</a> = [mail.myisp.net]
- # Alternative form:
- # <a href="postconf.5.html#relayhost">relayhost</a> = [mail.myisp.net]:submission
+<h4><a name="testing_saslauthd">Testing saslauthd authentication</a></h4>
-/etc/postfix/sasl_passwd:
- # Per-sender authentication; see also /etc/postfix/sender_relay.
- user1@example.com username2:password2
- user2@example.net username2:password2
- # Login information for the default <a href="postconf.5.html#relayhost">relayhost</a>.
- [mail.myisp.net] username:password
- [mail.myisp.net]:submission username:password
+<p> Cyrus SASL provides the <code>testsaslauthd</code> utility to
+test <code>saslauthd</code> authentication. The username and password
+are given as command line arguments. The example shows the response
+when authentication is successful: </p>
-/etc/postfix/sender_relay:
- # Per-sender provider; see also /etc/postfix/sasl_passwd.
- user1@example.com [mail.example.com]:submission
- user2@example.net [mail.example.net]
+<blockquote>
+<pre>
+% <strong><code>testsaslauthd -u <em>username</em> -p <em>password</em></code></strong>
+0: OK "Success."
</pre>
</blockquote>
-<p> Notes: </p>
+<blockquote>
-<ul>
+<strong>Note</strong>
-<li> <p> If you are creative, then you can try to combine the two
-tables into one single MySQL database, and configure different
-Postfix queries to extract the appropriate information. </p>
+<p> Sometimes the <code>testsaslauthd</code> program is not distributed
+with a the Cyrus SASL main package. In that case, it may be
+distributed with -devel, -dev or -debug packages. </p>
-<li> <p> Specify <b>dbm</b> instead of <b>hash</b> if your system
-uses <b>dbm</b> files instead of <b>db</b> files. To find out what
-lookup tables Postfix supports, use the command "<b>postconf -m</b>".
-</p>
+</blockquote>
-<li> <p> Execute the command "<b>postmap /etc/postfix/sasl_passwd</b>"
-whenever you change the sasl_passwd table. </p>
+<p> Specify an additional "<code>-s smtp</code>" if <code>saslauthd</code>
+was configured to contact the PAM authentication framework and an
+additional "<code>-f <em>/path/to/socketdir/mux</em></code>" if
+<code>saslauthd</code> establishes the UNIX-domain socket in a
+non-default location. </p>
-<li> <p> Execute the command "<b>postmap /etc/postfix/sender_relay</b>"
-whenever you change the sender_relay table. </p>
+<p> If authentication succeeds, proceed with the section "<a
+href="#server_sasl_enable">Enabling SASL authentication and authorization
+in the Postfix SMTP server</a>". </p>
-</ul>
+<h4><a name="auxprop">Cyrus SASL Plugins - auxiliary property
+plugins</a></h4>
-<h2><a name="credits">Credits</a></h2>
+<p> Cyrus SASL uses a plugin infrastructure (called <code>auxprop</code>)
+to expand <code>libsasl</code>'s capabilities. Currently Cyrus
+SASL sources provide three authentication plugins. </p>
-<ul>
+<blockquote>
-<li> Postfix SASL support was originally implemented by Till Franke
-of SuSE Rhein/Main AG.
+<dl>
-<li> Wietse trimmed down the code to only the bare necessities.
+<dt><a href="#auxprop_sasldb">sasldb</a></dt>
-<li> Support for Cyrus SASL version 2 was contributed by Jason Hoos.
+<dd> <p> Accounts are stored stored in a Cyrus SASL Berkeley DB
+database </p> </dd>
-<li> Liviu Daia added smtpd_sasl_application_name, split
-<a href="postconf.5.html#reject_sender_login_mismatch">reject_sender_login_mismatch</a> into
-<a href="postconf.5.html#reject_authenticated_sender_login_mismatch">reject_authenticated_sender_login_mismatch</a> and
-<a href="postconf.5.html#reject_unauthenticated_sender_login_mismatch">reject_unauthenticated_sender_login_mismatch</a>, and revised the docs.
+<dt><a href="#auxprop_sql">sql</a></dt>
-<li> Wietse made another iteration through the code to add plug-in
-support for multiple SASL implementations, and changed
-smtpd_sasl_application_name into <a href="postconf.5.html#smtpd_sasl_path">smtpd_sasl_path</a>.
+<dd> <p> Accounts are stored in a SQL database </p> </dd>
-<li> The Dovecot SMTP server-only plug-in was originally implemented by
-Timo Sirainen of Procontrol, Finland.
+<dt><a href="#auxprop_ldapdb">ldapdb</a></dt>
-<li> Patrick Ben Koetter revised this document for Postfix 2.4 and
-made much needed updates.
+<dd> <p> Accounts are stored stored in an LDAP database </p> </dd>
-</ul>
+</dl>
-</body>
+</blockquote>
+
+<blockquote>
+
+<strong>Important</strong>
+
+<p> These three plugins support shared-secret mechanisms i.e.
+CRAM-MD5, DIGEST-MD5 and NTLM. These mechanisms send credentials
+encrypted but their verification process requires the password to
+be available in plaintext. Consequently passwords cannot (!) be
+stored in encrypted form. </p>
+
+</blockquote>
+
+<h4><a name="auxprop_sasldb">The sasldb plugin</a></h4>
+
+<p> The sasldb auxprop plugin authenticates credentials stored in a Berkeley
+DB database. The database schema is specific to Cyrus SASL. The
+database is usually located at <code>/etc/sasldb2</code>. </p>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> The <code>sasldb2</code> file contains passwords in
+plaintext, and should have read+write access only to user
+<code>postfix</code> or a group that <code>postfix</code> is member
+of. </p>
+
+</blockquote>
+
+<p> The <code>saslpasswd2</code> command-line utility creates
+and maintains the database: </p>
+
+<blockquote>
+<pre>
+% <strong>saslpasswd2 -c -u <em>example.com</em> <em>username</em></strong>
+Password:
+Again (for verification):
+</pre>
+</blockquote>
+
+<p> This command creates an account
+<code><em>username@example.com</em></code>. </p>
+
+<blockquote>
+
+<strong>Important</strong>
+
+<p> users must specify <code><em>username@example.com</em></code>
+as login name, not <code><em>username</em></code>. </p>
+
+</blockquote>
+
+<p> Run the following command to reuse the Postfix <code><a href="postconf.5.html#mydomain">mydomain</a></code>
+parameter value as the login domain: </p>
+
+<blockquote>
+<pre>
+% <strong>saslpasswd2 -c -u `postconf -h <a href="postconf.5.html#mydomain">mydomain</a>` <em>username</em></strong>
+Password:
+Again (for verification):
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> Run <code>saslpasswd2</code> without any options for further
+help on how to use the command. </p>
+
+</blockquote>
+
+<p> The <code>sasldblistusers2</code> command lists all existing
+users in the sasldb database: </p>
+
+<blockquote>
+<pre>
+% <strong>sasldblistusers2</strong>
+username1@example.com: password1
+username2@example.com: password2
+</pre>
+</blockquote>
+
+<p> Configure libsasl to use sasldb with the following instructions: </p>
+
+<blockquote>
+<pre>
+/etc/sasl2/smtpd.conf:
+ pwcheck_method: auxprop
+ auxprop_plugin: sasldb
+ mech_list: PLAIN LOGIN CRAM-MD5 DIGEST-MD5 NTLM
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> In the above example adjust <code>mech_list</code> to the
+mechanisms that are applicable for your environment. </p>
+
+</blockquote>
+
+<h4><a name="auxprop_sql">The sql plugin</a></h4>
+
+<p> The sql auxprop plugin is a generic SQL plugin. It provides
+access to credentials stored in a MySQL, a PostgreSQL or a SQLite
+database. </p>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> The shared-secret mechanisms (CRAM-MD5, etc.) require that the
+SASL client passwords are stored as plaintext. </p>
+
+</blockquote>
+
+<blockquote>
+
+<strong>Tip</strong>
+
+<!-- XXX -->
+
+<p> Use "saslauthd > pam > (pam database module)" to
+verify encrypted passwords in an SQL database. </p>
+
+</blockquote>
+
+<p> The following example configures libsasl to use the sql plugin and connects
+it to a PostgreSQL server: </p>
+
+<blockquote>
+<pre>
+/etc/sasl2/smtpd.conf:
+ pwcheck_method: auxprop
+ auxprop_plugin: sql
+ mech_list: PLAIN LOGIN CRAM-MD5 DIGEST-MD5 NTLM
+ sql_engine: pgsql
+ sql_hostnames: 127.0.0.1, 192.0.2.1 sql_user: username
+ sql_passwd: secret
+ sql_database: dbname
+ sql_select: SELECT password FROM users WHERE user = '%u'@'%r'
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> Set appropriate permissions if <code>smtpd.conf</code> contains
+a password. The file should be readable by the <code>postfix</code>
+user. </p>
+
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> In the above example, adjust <code>mech_list</code> to the
+mechanisms that are applicable for your environment. </p>
+
+</blockquote>
+
+<p> The sql plugin has the following configuration options: </p>
+
+<blockquote>
+
+<dl>
+
+<dt>sql_engine</dt>
+
+<dd>
+
+<p> Specify <code>mysql</code> to connect to a MySQL server,
+<code>pgsql</code> for a PostgreSQL server or <code>sqlite</code>
+for an SQLite database </p>
+
+</dd>
+
+<dt>sql_hostnames</dt>
+
+<dd>
+
+<p> Specify one or more servers (hostname or hostname:port) separated
+by commas. </p>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> With MySQL servers, specify <code>localhost</code> to connect
+over a UNIX-domain socket, and specify <code>127.0.0.1</code> to
+connect over a TCP socket. </p>
+
+</blockquote>
+
+</dd>
+
+<dt>sql_user</dt>
+
+<dd>
+
+<p> The login name to gain access to the database. </p>
+
+</dd>
+
+<dt>sql_passwd</dt>
+
+<dd>
+
+<p> The password to gain access to the database. </p>
+
+</dd>
+
+<dt>sql_database</dt>
+
+<dd>
+
+<p> The name of the database to connect to. </p>
+
+</dd>
+
+<dt>sql_select</dt>
+
+<dd>
+
+<p> The SELECT statement that should retrieve the plaintext password
+from a database table. </p>
+
+<blockquote>
+
+<strong>Important</strong>
+
+<p> Do not enclose the statement in quotes! Use single quotes to
+escape macros! </p>
+
+</blockquote>
+
+</dd>
+
+</dl>
+
+</blockquote>
+
+<p> The sql plugin provides macros to build <code>sql_select</code>
+statements. They will be replaced with arguments sent from the client. The
+following macros are available: </p>
+
+<blockquote>
+
+<dl>
+
+<dt>%u</dt>
+
+<dd>
+
+<p> The name of the user whose properties are being selected. </p>
+
+</dd>
+
+<dt>%p</dt>
+
+<dd>
+
+<p> The name of the property being selected. While this could technically be
+anything, Cyrus SASL will try userPassword and cmusaslsecretMECHNAME (where
+MECHNAME is the name of a SASL mechanism). </p>
+
+</dd>
+
+<dt>%r</dt>
+
+<dd>
+
+<p> The name of the realm to which the user belongs. This could be
+the KERBEROS realm, the fully-qualified domain name of the computer
+the SASL application is running on, or the domain after the "@" in a
+username. </p>
+
+</dd>
+
+</dl>
+
+</blockquote>
+
+<h4><a name="auxprop_ldapdb">The ldapdb plugin</a></h4>
+
+<p> The ldapdb auxprop plugin provides access to credentials stored
+in an OpenLDAP LDAP server. It is the only plugin that implements
+proxy authorization. </p>
+
+<p> Proxy authorization in this context means: The ldapdb plugin
+must SASL authenticate with the OpenLDAP server. The server then
+decides if the ldapdb plugin should be authorized to read the
+authenticating user's password. Once the ldapdb plugin has gone
+through proxy authorization it may proceed and authenticate the
+remote SMTP client's credentials. </p>
+
+<p> In a nutshell: Configuring ldapdb means authentication and
+authorization must be configured twice - once in the Postfix SMTP
+server to authenticate and authorize the remote SMTP client, and
+once in the OpenLDAP <code>slapd</code> server to authenticate and
+authorize the ldapdb plugin. </p>
+
+<p> This example configures libsasl to use the ldapdb plugin and
+the plugin to connect to an OpenLDAP server: </p>
+
+<blockquote>
+<pre>
+/etc/sasl2/smtpd.conf:
+ pwcheck_method: auxprop
+ auxprop_plugin: ldapdb
+ mech_list: PLAIN LOGIN NTLM CRAM-MD5 DIGEST-MD5
+ ldapdb_uri: <a href="ldap_table.5.html">ldap</a>://localhost
+ ldapdb_id: proxyuser
+ ldapdb_pw: password
+ ldapdb_mech: DIGEST-MD5
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Important</strong>
+
+<p> Set appropriate permissions if <code>smtpd.conf</code> contains a
+password. The file should be readable by the <code>postfix</code>
+user. </p>
+
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> The shared-secret mechanisms (CRAM-MD5, etc.) require that the
+SASL client passwords are stored as plaintext. </p>
+
+</blockquote>
+
+<p> The following is a summary of applicable <code>smtpd.conf</code>
+file entries: </p>
+
+<blockquote>
+
+<dl>
+
+<dt>auxprop_plugin</dt>
+
+<dd> <p> Specify <code>ldapdb</code> to enable the plugin. </p> </dd>
+
+<dt>ldapdb_uri</dt>
+
+<dd> <p> Specify either <code>ldapi://</code> for to connect over
+a UNIX-domain socket, <code><a href="ldap_table.5.html">ldap</a>://</code> for an unencrypted TCP
+connection or <code>ldaps://</code> for an encrypted TCP connection.
+</p> </dd>
+
+<dt>ldapdb_id</dt>
+
+<dd> <p> The login name to authenticate the ldapdb plugin to the
+LDAP server (proxy authorization). </p> </dd>
+
+<dt>ldapdb_pw</dt>
+
+<dd> <p> The password (in plaintext) to authenticate the ldapdb
+plugin to the LDAP server (proxy authorization). </p> </dd>
+
+<dt>ldapdb_mech</dt>
+
+<dd> <p> The mechanism to authenticate the ldapdb plugin to the
+OpenLDAP slapd server. </p>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> Specify a mechanism here that is supported by the OpenLDAP slapd
+server. </p>
+
+</blockquote>
+
+</dd>
+
+<dt>ldapdb_rc (optional)</dt>
+
+<dd> <p> The path to a file containing individual configuration
+options for the ldapdb LDAP client (libldap). This allows to specify
+a TLS client certificate which in turn can be used to use the SASL
+EXTERNAL mechanism. </p>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> This mechanism supports authentication over an encrypted transport
+layer, which is recommended if the plugin must connect to an OpenLDAP
+server on a remote machine. </p>
+
+</blockquote>
+
+</dd>
+
+<dt>ldapdb_starttls (optional)</dt>
+
+<dd> <p> The TLS policy for connecting to the LDAP server. Specify
+either <code>try</code> or <code>demand</code>. If the option is
+<code>try</code> the plugin will attempt to establish a TLS-encrypted
+connection with the LDAP server, and will fallback to an unencrypted
+connection if TLS fails. If the policy is <code>demand</code> and
+a TLS-encrypted connection cannot be established, the connection
+fails immediately. </p> </dd>
+
+</dl>
+
+</blockquote>
+
+<p> When the ldapdb plugin connects to the OpenLDAP server and
+successfully authenticates, the OpenLDAP server decides if the
+plugin user is authorized to read SASL account information. </p>
+
+<p> The following configuration gives an example of authorization configuration
+in the OpenLDAP slapd server: </p>
+
+<blockquote>
+<pre>
+/etc/openldap/slapd.conf:
+ authz-regexp
+ uid=(.*),cn=.*,cn=auth
+ <a href="ldap_table.5.html">ldap</a>:///dc=example,dc=com??sub?cn=$1
+ authz-policy to
+</pre>
+</blockquote>
+
+<p> Here, the <code>authz-regexp</code> option serves for authentication
+of the ldapdb user. It maps its login name to a DN in the LDAP
+directory tree where <code>slapd</code> can look up the SASL account
+information. The <code>authz-policy</code> options defines the
+authentication policy. In this case it grants authentication
+privileges "<code>to</code>" the ldapdb plugin. </p>
+
+<p> The last configuration step is to tell the OpenLDAP <code>slapd</code>
+server where ldapdb may search for usernames matching the one given
+by the mail client. The example below adds an additional attribute
+ldapdb user object (here: <code>authzTo</code> because the authz-policy
+is "<code>to</code>") and configures the scope where the login name
+"proxyuser" may search: </p>
+
+<blockquote>
+<pre>
+dn: cn=proxyuser,dc=example,dc=com
+changetype: modify
+add: authzTo
+authzTo: dn.regex:uniqueIdentifier=(.*),ou=people,dc=example,dc=com
+</pre>
+</blockquote>
+
+<p> Use the <code>ldapmodify</code> or <code>ldapadd</code> command
+to add the above attribute. </p>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> Read the chapter "Using SASL" in the <a
+href="http://www.openldap.org/doc/admin">OpenLDAP Admin Guide</a>
+for more detailed instructions to set up SASL authentication in
+OpenLDAP. </p>
+
+</blockquote>
+
+<h3><a name="server_sasl_enable">Enabling SASL authentication and
+authorization in the Postfix SMTP server</a></h3>
+
+<p> By default the Postfix SMTP server uses the Cyrus SASL
+implementation. If the Dovecot SASL implementation should be used,
+specify an <code><a href="postconf.5.html#smtpd_sasl_type">smtpd_sasl_type</a></code> value of <code>dovecot</code>
+instead of <code>cyrus</code>: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtpd_sasl_type">smtpd_sasl_type</a> = dovecot
+</pre>
+</blockquote>
+
+<p> Additionally set the path where the Postfix SMTP server can
+find the Dovecot SASL socket: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtpd_sasl_path">smtpd_sasl_path</a> = private/auth
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> This example uses a pathname relative to the Postfix queue
+directory, so that it will work whether or not the Postfix SMTP
+server runs chrooted. </p>
+
+</blockquote>
+
+<h4><a name="server_sasl_authc">Enabling SASL authentication
+in the Postfix SMTP server</a></h4>
+
+<p> Regardless of the SASL implementation type, enabling SMTP
+authentication in the Postfix SMTP server always requires seting
+the <code><a href="postconf.5.html#smtpd_sasl_auth_enable">smtpd_sasl_auth_enable</a></code> option: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtpd_sasl_auth_enable">smtpd_sasl_auth_enable</a> = yes
+</pre>
+</blockquote>
+
+<p> After a "postfix reload", SMTP clients will see the additional
+capability AUTH in an SMTP session, followed by a list of
+authentication mechanisms the server supports: </p>
+
+<blockquote>
+<pre>
+% <strong>telnet server.example.com 25</strong>
+...
+220 server.example.com ESMTP Postfix
+<strong>EHLO client.example.com</strong>
+250-server.example.com
+250-PIPELINING
+250-SIZE 10240000
+250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
+...
+</pre>
+</blockquote>
+
+<p> However not all clients recognize the AUTH capability as defined
+by the SASL authentication RFC. Some historical implementations expect the
+server to send an "<code>=</code>" as separator between the AUTH
+verb and the list of mechanisms that follows it. </p>
+
+<p> The <code><a href="postconf.5.html#broken_sasl_auth_clients">broken_sasl_auth_clients</a></code> configuration option
+lets Postfix repeat the AUTH statement in a form that these broken
+clients understand: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#broken_sasl_auth_clients">broken_sasl_auth_clients</a> = yes
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> Enable this option for Outlook up to and including version 2003
+and Outlook Express up to version 6. This option does not hurt other
+clients. </p>
+
+</blockquote>
+
+<p> After "postfix reload", the Postfix SMTP server will propagate
+the AUTH capability twice - once for compliant and once for broken
+clients: </p>
+
+<blockquote>
+<pre>
+% <strong>telnet server.example.com 25</strong>
+...
+<strong>EHLO client.example.com</strong>
+250-server.example.com
+250-PIPELINING
+250-SIZE 10240000
+250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
+250-AUTH=DIGEST-MD5 PLAIN CRAM-MD5
+...
+</pre>
+</blockquote>
+
+<h4><a name="smtpd_sasl_security_options">Postfix SMTP Server
+Authentication Policy</a></h4>
+
+<p> The Postfix SMTP server provides a way to specify the properties
+of SASL mechanisms that can be made available to the remote SMTP
+client. </p>
+
+<h4><a name="id396877">Unencrypted SMTP session</a></h4>
+
+<p> The default policy is to allow any mechanism in the Postfix SMTP server
+except for those based on anonymous authentication: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ # Specify a list of properties separated by comma or whitespace
+ <a href="postconf.5.html#smtpd_sasl_security_options">smtpd_sasl_security_options</a> = noanonymous
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Important</strong>
+
+<p> Always set at least the <code>noanonymous</code> option.
+Otherwise, the Postfix SMTP server can give strangers the same
+authorization as a properly-authenticated client. </p>
+
+</blockquote>
+
+<p> Postfix can enforce the following policies on SASL authentication
+mechanisms: </p>
+
+<blockquote>
+
+<dl>
+
+<dt>noanonymous</dt>
+
+<dd> <p> Don't use mechanisms that permit anonymous authentication.
+</p> </dd>
+
+<dt>noplaintext</dt>
+
+<dd> <p> Don't use mechanisms that transmit unencrypted username
+and password information. </p> </dd>
+
+<dt>nodictionary</dt>
+
+<dd> <p> Don't use mechanisms that are vulnerable to dictionary
+attacks. </p>
+
+</dd>
+
+<dt>forward_secrecy</dt>
+
+<dd> <p> Use only mechanisms that support forward secrecy (Dovecot
+SASL only).</p>
+
+</dd>
+
+<dt>mutual_auth</dt>
+
+<dd> <p> Use only mechanisms that authenticate both the client and
+the server to each other. </p> </dd>
+
+</dl>
+
+</blockquote>
+
+<h4><a name="id396969">Encrypted SMTP session (TLS)</a></h4>
+
+<p> A separate parameter controls Postfix SASL mechanism policy
+during a TLS-encrypted SMTP session. The default is to copy the
+settings from the unencrypted session: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtpd_sasl_tls_security_options">smtpd_sasl_tls_security_options</a> = $<a href="postconf.5.html#smtpd_sasl_security_options">smtpd_sasl_security_options</a>
+</pre>
+</blockquote>
+
+<p> A more sophisticated policy allows plaintext mechanisms, but
+only over a TLS-encrypted connection: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtpd_sasl_security_options">smtpd_sasl_security_options</a> = noanonymous, noplaintext
+ <a href="postconf.5.html#smtpd_sasl_tls_security_options">smtpd_sasl_tls_security_options</a> = noanonymous
+</pre>
+</blockquote>
+
+<p> To offer SASL authentication only after a TLS-encrypted session has been
+established specify this: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtpd_tls_auth_only">smtpd_tls_auth_only</a> = yes
+</pre>
+</blockquote>
+
+<h4><a name="server_sasl_authz">Enabling SASL authorization in the Postfix
+SMTP server</a></h4>
+
+<p> After the client has authenticated with SASL, the Postfix SMTP
+server decides what the remote SMTP client will be authorized
+for. Examples of possible SMTP clients authorizations are: </p>
+
+<ul>
+
+<li> <p> Send a message to a remote recipient. </p> </li>
+
+<li> <p> Use a specific envelope sender in the MAIL FROM command. </p> </li>
+
+</ul>
+
+<p> These permissions are not enabled by default. </p>
+
+<h4><a name="id397041">Mail relay authorization</a></h4>
+
+<p> The <code><a href="postconf.5.html#permit_sasl_authenticated">permit_sasl_authenticated</a></code> restriction allows
+SASL-authenticated SMTP clients to send mail to remote destinations.
+Add it to the list of <code><a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a></code> as
+follows: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> =
+ ...
+ <a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>
+ <strong><a href="postconf.5.html#permit_sasl_authenticated">permit_sasl_authenticated</a></strong>
+ <a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a>
+ ...
+</pre>
+</blockquote>
+
+<h4><a name="id397072">Envelope sender address authorization</a></h4>
+
+<p> By default an SMTP client may specify any envelope sender address
+in the MAIL FROM command. That is because the Postfix SMTP server
+only knows the remte SMTP client hostname and IP address, but not
+the user who controls the remote SMTP client. </p>
+
+<p> This changes the moment an SMTP client uses SASL authentication.
+Now, the Postfix SMTP server knows who the sender is. Given a table
+of envelope sender addresses and SASL login names, the Postfix SMTP
+server can decide if the SASL authenticated client is allowed to
+use a particular envelope sender address: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <strong><a href="postconf.5.html#smtpd_sender_login_maps">smtpd_sender_login_maps</a> = hash:/etc/postfix/controlled_envelope_senders</strong>
+
+ <a href="postconf.5.html#smtpd_recipient_restrictions">smtpd_recipient_restrictions</a> =
+ ...
+ <strong><a href="postconf.5.html#reject_sender_login_mismatch">reject_sender_login_mismatch</a></strong>
+ <a href="postconf.5.html#permit_sasl_authenticated">permit_sasl_authenticated</a>
+ <a href="postconf.5.html#permit_mynetworks">permit_mynetworks</a>
+ <a href="postconf.5.html#reject_unauth_destination">reject_unauth_destination</a>
+ ...
+</pre>
+</blockquote>
+
+<p> The <code>controlled_envelope_senders</code> table specifies
+the binding between the sender envelope addresses and its their
+SASL login names: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/controlled_envelope_senders
+ # envelope sender owners (SASL login names)
+ john@example.com john@example.com
+ helpdesk@example.com john@example.com, mary@example.com
+ postmaster admin@example.com
+ @example.net barney, fred, john@example.com, mary@example.com
+</pre>
+</blockquote>
+
+<p> With this, the <code><a href="postconf.5.html#reject_sender_login_mismatch">reject_sender_login_mismatch</a></code>
+restriction above will reject the sender address in the MAIL FROM
+command if <code><a href="postconf.5.html#smtpd_sender_login_maps">smtpd_sender_login_maps</a></code> does not specify
+the SMTP client's login name as an owner of that address. </p>
+
+<p> See also <code><a href="postconf.5.html#reject_authenticated_sender_login_mismatch">reject_authenticated_sender_login_mismatch</a></code> and
+<code><a href="postconf.5.html#reject_unauthenticated_sender_login_mismatch">reject_unauthenticated_sender_login_mismatch</a></code> for additional
+control over the SASL login name and the envelope sender. </p>
+
+<h4><a name="server_sasl_other">Additional SMTP Server SASL options</a></h4>
+
+<p> Postfix provides a wide range of SASL authentication configuration
+options. The next section lists a few that are discussed frequently.
+See <a href="postconf.5.html">postconf(5)</a> for a complete list. </p>
+
+<h4><a name="id397172">Default authentication domain</a></h4>
+
+<p> Postfix can append a domain name (or any other string) to a
+SASL login name that does not have a domain part, e.g. "<code>john</code>"
+instead of "<code>john@example.com</code>": </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtpd_sasl_local_domain">smtpd_sasl_local_domain</a> = example.com
+</pre>
+</blockquote>
+
+<p> This is useful as a default setting and safety net for misconfigured
+clients, or during a migration to an authentication method/backend
+that requires an authentication REALM or domain name, before all
+SMTP clients are configured to send such information. </p>
+
+<h4><a name="id397205">Hiding SASL authentication from clients or
+networks</a></h4>
+
+<p> Some clients insist on using SASL authentication if it is offered, even
+when they are not configured to send credentials - and therefore
+they will always fail and disconnect. </p>
+
+<p> Postfix can hide the AUTH capability from these clients/networks: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtpd_sasl_exceptions_networks">smtpd_sasl_exceptions_networks</a> = !192.0.2.171/32, 192.0.2.0/24
+</pre>
+</blockquote>
+
+<h4><a name="id397226">Adding the SASL login name to mail headers</a></h4>
+
+<p> To report SASL login names in Received: message headers (Postfix
+version 2.3 and later): </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtpd_sasl_authenticated_header">smtpd_sasl_authenticated_header</a> = yes
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> The SASL login names will be shared with the entire world. </p>
+
+</blockquote>
+
+<h3><a name="server_test">Testing SASL authentication in the Postfix SMTP Server</a></h3>
+
+<p> To test the server side, connect (for example, with
+<code>telnet</code>) to the Postfix SMTP server port and you should
+be able to have a conversation as shown below. Information sent by
+the client (that is, you) is shown in bold font. </p>
+
+<blockquote>
+<pre>
+% <strong>telnet server.example.com 25</strong>
+...
+220 server.example.com ESMTP Postfix
+<strong>EHLO client.example.com</strong>
+250-server.example.com
+250-PIPELINING
+250-SIZE 10240000
+250-ETRN
+250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
+250 8BITMIME
+<strong>AUTH PLAIN AHRlc3QAdGVzdHBhc3M=</strong>
+235 Authentication successful
+</pre>
+</blockquote>
+
+<p> Instead of <code>AHRlc3QAdGVzdHBhc3M=</code>, specify the
+base64-encoded form of <code>\0username\0password</code> (the \0
+is a null byte). The example above is for a user named `<code>test</code>'
+with password `<code>testpass</code>'. </p>
+<blockquote>
+
+<strong>Caution</strong>
+
+<p> When posting logs of the SASL negotiations to public lists,
+please keep in mind that username/password information is trivial
+to recover from the base64-encoded form. </p>
+
+</blockquote>
+
+<p> You can use one of the following commands to generate base64
+encoded authentication information: </p>
+
+<blockquote>
+<pre>
+% <strong>gen-auth plain</strong>
+username: <strong><em>username</em></strong>
+password:
+</pre>
+</blockquote>
+
+<p> The <strong>gen-auth</strong> Perl script was written by John
+Jetmore and can be found at <a href="http://jetmore.org/john/code/gen-auth">http://jetmore.org/john/code/gen-auth</a>. </p>
+
+<blockquote>
+<pre>
+% <strong>printf '\0<em>username</em>\0<em>password</em>' | mmencode</strong>
+</pre>
+</blockquote>
+
+<p> The <strong>mmencode</strong> command is part of the metamail
+software. </p>
+
+<blockquote>
+<pre>
+% <strong>perl -MMIME::Base64 -e \
+ 'print encode_base64("\0<em>username</em>\0<em>password</em>");'</strong>
+</pre>
+</blockquote>
+
+<p> MIME::Base64 is available from <a href="http://www.cpan.org/">http://www.cpan.org/</a>. </p>
+
+<h2><a name="client_sasl">Configuring SASL authentication in the Postfix SMTP/LMTP client</a></h2>
+
+<p> The Postfix SMTP and the LMTP client can authenticate with a
+remote SMTP server via the Cyrus SASL framework. At this time, the
+Dovecot SASL implementation does not provide client functionality.
+</p>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> The examples in this section discuss only the SMTP client.
+Replace <code>smtp_</code> with <code>lmtp_</code> to get the
+corresponding LMTP client configuration. </p>
+
+</blockquote>
+
+<p> You can read more about the following topics: </p>
+
+<ul>
+
+<li><a href="#client_sasl_enable">Enabling SASL authentication in
+the Postfix SMTP/LMTP client</a></li>
+
+<li><a href="#client_sasl_sender">Configuring sender-dependent SASL
+authentication</a></li>
+
+<li><a href="#client_sasl_policy">Postfix SMTP/LMTP client
+authentication policy</a></li>
+
+<li><a href="#client_sasl_filter">Filtering server mechanism names
+in the Postfix SMTP/LMTP client</a></li>
+
+</ul>
+
+<h3><a name="client_sasl_enable">Enabling SASL authentication in the
+Postfix SMTP/LMTP client</a></h3>
+
+<p> This section shows a typical scenario where the Postfix SMTP
+client sends all messages via a mail gateway server that requires
+SASL authentication. To make the example more readable we introduce
+it in two parts. </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtp_sasl_auth_enable">smtp_sasl_auth_enable</a> = yes
+ <a href="postconf.5.html#relayhost">relayhost</a> = [mail.isp.example]
+ # Alternative form:
+ # <a href="postconf.5.html#relayhost">relayhost</a> = [mail.isp.example]:submission
+ <a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> = hash:/etc/postfix/sasl_passwd
+</pre>
+</blockquote>
+
+<ul>
+
+<li> <p> The <code><a href="postconf.5.html#smtp_sasl_auth_enable">smtp_sasl_auth_enable</a></code> setting enables
+client-side authentication. We will configure the client's username
+and password information in the second part of the example. </p>
+</li>
+
+<li> <p> The <code><a href="postconf.5.html#relayhost">relayhost</a></code> setting forces the Postfix SMTP
+to send all remote messages to the specified mail server instead
+of trying to deliver them directly to their destination. </p> </li>
+
+<li> <p> In the <code><a href="postconf.5.html#relayhost">relayhost</a></code> setting, the "<code>[</code>"
+and "<code>]</code>" prevent the Postfix SMTP client from looking
+up MX (mail exchanger) records for the enclosed name. </p> </li>
+
+<li> <p> The <code><a href="postconf.5.html#relayhost">relayhost</a></code> destination may also specify a
+non-default TCP port. For example, the alternative form
+<code>[mail.isp.example]:submission</code> tells Postfix to connect
+to TCP network port 587, which is reserved for email client
+applications. </p> </li>
+
+<li> <p> The Postfix SMTP client is compatible with SMTP servers
+that use the non-standard "<code>AUTH=<em>method.</em>...</code>"
+syntax in response to the EHLO command; this requires no additional
+Postfix client configuration. </p> </li>
+
+<li> <p> The Postfix SMTP client does not support the obsolete
+"wrappermode" protocol, which uses TCP port <code>465</code> on the
+SMTP server. See <a href="TLS_README.html">TLS_README</a> for a solution that uses the
+<code>stunnel</code> command. </p> </li>
+
+<li> <p> With the <code><a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a></code> parameter,
+we configure the Postfix SMTP client to send username and password
+information to the mail gateway server. As discussed in the next
+section, the Postfix SMTP client supports multiple ISP accounts.
+For this reason the username and password are stored in a table
+that contains one username/password combination for each mail gateway
+server. </p>
+
+</ul>
+
+<blockquote>
+<pre>
+/etc/postfix/sasl_passwd:
+ # destination credentials
+ [mail.isp.example] username:password
+ # Alternative form:
+ # [mail.isp.example]:submission username:password
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Important</strong>
+
+<p> Keep the SASL client password file in <code>/etc/postfix</code>,
+and make the file read+write only for <code>root</code> to protect
+the username/password combinations against other users. The Postfix
+SMTP client will still be able to read the SASL client passwords.
+It opens the file as user <code>root</code> before it drops privileges,
+and before entering an optional chroot jail. </p>
+
+</blockquote>
+
+<ul>
+
+<li> <p> Use the <code>postmap</code> command whenever you
+change the <code>/etc/postfix/sasl_passwd</code> file. </p> </li>
+
+<li> <p> If you specify the "<code>[</code>" and "<code>]</code>"
+in the <code><a href="postconf.5.html#relayhost">relayhost</a></code> destination, then you must use the
+same form in the <code><a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a></code> file. </p>
+</li>
+
+<li> <p> If you specify a non-default TCP Port (such as
+"<code>:submission</code>" or "<code>:587</code>") in the
+<code><a href="postconf.5.html#relayhost">relayhost</a></code> destination, then you must use the same form
+in the <code><a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a></code> file. </p> </li>
+
+</ul>
+
+<h3><a name="client_sasl_sender">Configuring Sender-Dependent SASL
+authentication</a></h3>
+
+<p> Postfix supports different ISP accounts for different sender
+addresses (version 2.3 and later). This can be useful when one
+person uses the same machine for work and for personal use, or when
+people with different ISP accounts share the same Postfix server.
+</p>
+
+<p> To make this possible, Postfix supports per-sender SASL passwords
+and per-sender relay hosts. In the example below, the Postfix SMTP
+client will search the SASL password file by sender address before
+it searches that same file by destination. Likewise, the Postfix
+<a href="trivial-rewrite.8.html">trivial-rewrite(8)</a> daemon will search the per-sender <a href="postconf.5.html#relayhost">relayhost</a> file,
+and use the default <code><a href="postconf.5.html#relayhost">relayhost</a></code> setting only as a final
+resort. </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtp_sender_dependent_authentication">smtp_sender_dependent_authentication</a> = yes
+ <a href="postconf.5.html#sender_dependent_relayhost_maps">sender_dependent_relayhost_maps</a> = hash:/etc/postfix/sender_relay
+ <a href="postconf.5.html#smtp_sasl_auth_enable">smtp_sasl_auth_enable</a> = yes
+ <a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> = hash:/etc/postfix/sasl_passwd
+ <a href="postconf.5.html#relayhost">relayhost</a> = [mail.isp.example]
+ # Alternative form:
+ # <a href="postconf.5.html#relayhost">relayhost</a> = [mail.isp.example]:submission
+</pre>
+</blockquote>
+
+<blockquote>
+<pre>
+/etc/postfix/sasl_passwd:
+ # Per-sender authentication; see also /etc/postfix/sender_relay.
+ user1@example.com username2:password2
+ user2@example.net username2:password2
+ # Login information for the default <a href="postconf.5.html#relayhost">relayhost</a>.
+ [mail.isp.example] username:password
+ # Alternative form:
+ # [mail.isp.example]:submission username:password
+</pre>
+</blockquote>
+
+<blockquote>
+<pre>
+/etc/postfix/sender_relay:
+ # Per-sender provider; see also /etc/postfix/sasl_passwd.
+ user1@example.com [mail.example.com]:submission
+ user2@example.net [mail.example.net]
+</pre>
+</blockquote>
+
+<ul>
+
+<li> <p> If you are creative, then you can try to combine the two
+tables into one single MySQL database, and configure different
+Postfix queries to extract the appropriate information. </p>
+
+<li> <p> Specify dbm instead of hash if your system uses dbm files
+instead of db files. To find out what lookup tables Postfix supports,
+use the command "postconf -m". </p>
+
+<li> <p> Execute the command "postmap /etc/postfix/sasl_passwd"
+whenever you change the sasl_passwd table. </p>
+
+<li> <p> Execute the command "postmap /etc/postfix/sender_relay"
+whenever you change the sender_relay table. </p>
+
+</ul>
+
+<h3><a name="client_sasl_policy">Postfix SMTP/LMTP client authentication
+policy</a></h3>
+
+<p> Just like the Postfix SMTP server, the SMTP client has a policy
+that determines which SASL mechanisms are acceptable and which are
+not. </p>
+
+<h4>Unencrypted SMTP session</h4>
+
+<p> The default policy is stricter than that of the Postfix SMTP
+server - plaintext mechanisms are not allowed (nor is any anonymous
+mechanism): </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtp_sasl_security_options">smtp_sasl_security_options</a> = noplaintext, noanonymous
+</pre>
+</blockquote>
+
+<p> Postfix can enforce the following policies on SASL authentication
+mechanisms: </p>
+
+<blockquote>
+
+<dl>
+
+<dt>noanonymous</dt>
+
+<dd> <p> Don't use mechanisms that permit anonymous authentication.
+</p> </dd>
+
+<dt>noplaintext</dt>
+
+<dd> <p> Don't use mechanisms that transmit unencrypted username
+and password information. </p> </dd>
+
+<dt>nodictionary</dt>
+
+<dd> <p> Don't use mechanisms that are vulnerable to dictionary
+attacks. </p>
+
+</dd>
+
+<dt>
+<dt>mutual_auth</dt>
+
+<dd> <p> Use only mechanisms that authenticate both the client and
+the server to each other. </p> </dd>
+
+</dl>
+
+</blockquote>
+
+<p> With the default policy shown above, the Postfix SMTP client
+will not send its password over an unencrypted connection. This
+sometimes leads to authentication failures if the remote server
+only offers plaintext authentication mechanisms. In such cases the
+SMTP client will log the following error message: </p>
+
+<blockquote>
+<pre>
+SASL authentication failure: No worthy mechs found
+</pre>
+</blockquote>
+
+<p> The less secure approach to deal with this is to lower the
+security standards and permit plaintext authentication mechanisms:
+</p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtp_sasl_security_options">smtp_sasl_security_options</a> = noanonymous
+</pre>
+</blockquote>
+
+<p> Needless to say, sending a username and password over an insecure
+channel is undesirable. </p>
+
+<p> If the remote server supports TLS, you can protect the plaintext
+username and password by turning on TLS in the Postfix SMTP client
+(see: <a href="TLS_README.html">TLS_README</a>), and configuring the client as discussed next.
+
+<h4>Encrypted SMTP session (TLS)</h4>
+
+<p> A separate parameter controls Postfix SASL mechanism policy
+during a TLS-encrypted SMTP session. The default is to copy the
+settings from the unencrypted session: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtp_sasl_tls_security_options">smtp_sasl_tls_security_options</a> = $<a href="postconf.5.html#smtp_sasl_security_options">smtp_sasl_security_options</a>
+</pre>
+</blockquote>
+
+<p> A more sophisticated policy allows plaintext mechanisms, but
+only over a TLS-encrypted connection: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtpd_sasl_security_options">smtpd_sasl_security_options</a> = noanonymous, noplaintext
+ <a href="postconf.5.html#smtpd_sasl_tls_security_options">smtpd_sasl_tls_security_options</a> = noanonymous
+</pre>
+</blockquote>
+
+<h3><a name="client_sasl_filter">Filtering server mechanism names in
+the Postfix SMTP/LMTP client</a></h3>
+
+<p> Cyrus SASL always attempts to use the most secure authentication
+mechanism that the remote SMTP server offers - even if the client
+side was not configured to handle it! In such cases authentication
+will definitely fail. </p>
+
+<p> To prevent this, the Postfix SMTP client can filter the list
+of authentication mechanism names from the remote SMTP server. Used
+correctly, the filter hides unwanted mechanisms from the Cyrus SASL
+library, forcing the library to choose from the mechanisms the
+Postfix filter passes through. </p>
+
+<p> The following example filters out everything but the mechanisms
+<code>PLAIN</code> and <code>LOGIN</code>: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtp_sasl_mechanism_filter">smtp_sasl_mechanism_filter</a> = plain, login
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> If the remote server does not offer any of the mechanisms on
+the filter list, authentication will fail. </p>
+
+</blockquote>
+
+<p> We close this section with an example that passes every mechanism
+except for <code>GSSAPI</code> and <code>LOGIN</code>: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/<a href="postconf.5.html">main.cf</a>:
+ <a href="postconf.5.html#smtp_sasl_mechanism_filter">smtp_sasl_mechanism_filter</a> = !gssapi, !login, static:all
+</pre>
+</blockquote>
+
+<h2><a name="postfix_build">Building Postfix with SASL support</a></h2>
+
+<p> As mentioned elsewhere, Postfix supports two SASL implementations:
+Cyrus SASL (SMTP client and server) and Dovecot SASL (SMTP server
+only). Both implementations can be built into Postfix simultaneously.
+</p>
+
+<ul>
+
+<li><a href="#build_dovecot">Building Dovecot SASL support</a></li>
+
+<li><a href="#sasl_support">Building Cyrus SASL support</a></li>
+
+</ul>
+
+<h3><a name="build_dovecot">Building Dovecot SASL support</a></h3>
+
+<p> These instructions assume that you build Postfix from source
+code as described in the <a href="INSTALL.html">INSTALL</a> document. Some modification may
+be required if you build Postfix from a vendor-specific source
+package. </p>
+
+<p> Support for the Dovecot version 1 SASL protocol is available
+in Postfix 2.3 and later. At the time of writing, only server-side
+SASL support is available, so you can't use it to authenticate the
+Postfix SMTP client to your network provider's server. </p>
+
+<p> Dovecot uses its own daemon process for authentication. This
+keeps the Postfix build process simple, because there is no need
+to link extra libraries into Postfix. </p>
+
+<p> To generate the necessary Makefiles, execute the following in
+the Postfix top-level directory: </p>
+
+<blockquote>
+<pre>
+% <strong>make tidy</strong> # if you have left-over files from a previous build
+% <strong>make makefiles CCARGS='-DUSE_SASL_AUTH \
+ -DDEF_SERVER_SASL_TYPE=\"dovecot\"'</strong>
+</pre>
+</blockquote>
+
+<p> After this, proceed with "<code>make</code>" as described in
+the <a href="INSTALL.html">INSTALL</a> document. </p>
+
+<strong>Note</strong>
+
+<ul>
+
+<li>
+
+<p> The <code>-DDEF_SERVER_SASL_TYPE=\"dovecot\"</code> is not
+necessary; it just makes Postfix configuration a little more
+convenient because you don't have to specify the SASL plug-in type
+in the Postfix <a href="postconf.5.html">main.cf</a> file (but this may cause surprises when you
+switch to a later Postfix version that is built with the default
+SASL type of <code>sasl</code>). </p>
+
+</li>
+
+<li>
+
+<p> If you also want support for LDAP or TLS (or for Cyrus SASL),
+you need to merge their <code>CCARGS</code> and <code>AUXLIBS</code>
+options into the above command line; see the <a href="LDAP_README.html">LDAP_README</a> and
+<a href="TLS_README.html">TLS_README</a> for details. </p>
+
+<blockquote>
+<pre>
+% <strong>make tidy</strong> # if you have left-over files from a previous build
+% <strong>make makefiles CCARGS='-DUSE_SASL_AUTH \
+ -DDEF_SERVER_SASL_TYPE=\"dovecot\" \
+ ...<i>CCARGS options for LDAP or TLS etc.</i>...' \
+ AUXLIBS='...<i>AUXLIBS options for LDAP or TLS etc.</i>...'</strong>
+</pre>
+</blockquote>
+
+</li>
+
+</ul>
+
+<h3><a name="sasl_support">Building Cyrus SASL support</a></h3>
+
+<h4><a name="build_sasl">Building the Cyrus SASL library</a></h4>
+
+<p> Postfix works with cyrus-sasl-1.5.x or cyrus-sasl-2.1.x, which are
+available from <a href="ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/">ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/</a>. </p>
+
+<blockquote>
+
+<strong>Important</strong>
+
+<p> If you install the Cyrus SASL libraries as per the default, you will have
+to create a symlink <code>/usr/lib/sasl</code> ->
+<code>/usr/local/lib/sasl</code> for version 1.5.x or
+<code>/usr/lib/sasl2</code> -> <code>/usr/local/lib/sasl2</code>
+for version 2.1.x. </p>
+
+</blockquote>
+
+<p> Reportedly, Microsoft Outlook (Express) requires the non-standard LOGIN
+and/or NTLM authentication mechanism. To enable these authentication
+mechanisms, build the Cyrus SASL libraries with: </p>
+
+<blockquote>
+<pre>
+% <strong>./configure --enable-login --enable-ntlm</strong>
+</pre>
+</blockquote>
+
+<h4><a name="build_postfix">Building Postfix with Cyrus SASL support</a></h4>
+
+<p> These instructions assume that you build Postfix from source
+code as described in the <a href="INSTALL.html">INSTALL</a> document. Some modification may
+be required if you build Postfix from a vendor-specific source
+package. </p>
+
+<p> The following assumes that the Cyrus SASL include files are in
+<code>/usr/local/include</code>, and that the Cyrus SASL libraries are in
+<code>/usr/local/lib</code>. </p>
+
+<p> On some systems this generates the necessary <code>Makefile</code>
+definitions: </p>
+
+<dl>
+
+<dt>Cyrus SASL version 2.1.x</dt>
+
+<dd>
+
+<pre>
+% <strong>make tidy</strong> # if you have left-over files from a previous build
+% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
+ -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib -lsasl2"</strong>
+</pre>
+
+</dd>
+
+<dt>Cyrus SASL version 1.5.x</dt>
+
+<dd>
+
+<pre>
+% <strong>make tidy</strong> # if you have left-over files from a previous build
+% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
+ -I/usr/local/include" AUXLIBS="-L/usr/local/lib -lsasl"</strong>
+</pre>
+
+</dd>
+
+</dl>
+
+<p> On Solaris 2.x you need to specify run-time link information,
+otherwise the ld.so run-time linker will not find the SASL shared
+library: </p>
+
+<dl>
+
+<dt>Cyrus SASL version 2.1.x</dt>
+
+<dd>
+
+<pre>
+% <strong>make tidy</strong> # remove left-over files from a previous build
+% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
+ -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib \
+ -R/usr/local/lib -lsasl2"</strong>
+</pre>
+
+</dd>
+
+<dt>Cyrus SASL version 1.5.x</dt>
+
+<dd>
+
+<pre>
+% <strong>make tidy</strong> # if you have left-over files from a previous build
+% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
+ -I/usr/local/include" AUXLIBS="-L/usr/local/lib \
+ -R/usr/local/lib -lsasl"</strong>
+</pre>
+
+</dd>
+
+</dl>
+
+<h2><a name="cyrus_legacy">Using Cyrus SASL version 1.5.x</a></h2>
+
+<p> Postfix supports Cyrus SASL version 1.x, but you shouldn't use
+it unless you are forced to. The makers of Cyrus SASL write: </p>
+
+<blockquote> <i> This library is being deprecated and applications
+should transition to using the SASLv2 library</i> (source: <a
+href="http://cyrusimap.web.cmu.edu/downloads.html">Project Cyrus:
+Downloads</a>). </blockquote>
+
+<p> If you still need to set it up, here's a quick rundown: </p>
+
+<p> Read the regular section on SMTP server configurations for the
+Cyrus SASL framework. The differences are: </p>
+
+<ul>
+
+<li> <p> Cyrus SASL version 1.5.x searches for configuration
+(<code>smtpd.conf</code>) in <code>/usr/lib/sasl/</code> only. You
+must place the configuration in that directory. Some systems may
+have modified Cyrus SASL and put the files into e.g.
+<code>/var/lib/sasl/</code>. </p> </li>
+
+<li> <p> Use the <code>saslpasswd</code> command instead of
+<code>saslpasswd2</code> to create users in <code>sasldb</code>.
+</p> </li>
+
+<li> <p> Use the <code>sasldblistusers</code> command instead of
+<code>sasldblistusers2</code> to find users in <code>sasldb</code>.
+</p> </li>
+
+<li> <p> In the <code>smtpd.conf</code> file you can't use
+<code>mech_list</code> to limit the range of mechanisms offered.
+Instead, remove their libraries from <code>/usr/lib/sasl/</code>
+(and remember remove those files again when a system update
+re-installs new versions). </p> </li>
+
+</ul>
+
+<h2><a name="credits">Credits</a></h2>
+
+<ul>
+
+<li> Postfix SASL support was originally implemented by Till Franke
+of SuSE Rhein/Main AG. </li>
+
+<li> Wietse trimmed down the code to only the bare necessities.
+ </li>
+
+<li> Support for Cyrus SASL version 2 was contributed by Jason Hoos.
+</li>
+
+<li> Liviu Daia added <a href="postconf.5.html#smtpd_sasl_application_name">smtpd_sasl_application_name</a>, separated
+<a href="postconf.5.html#reject_sender_login_mismatch">reject_sender_login_mismatch</a> into
+<a href="postconf.5.html#reject_authenticated_sender_login_mismatch">reject_authenticated_sender_login_mismatch</a> and
+<a href="postconf.5.html#reject_unauthenticated_sender_login_mismatch">reject_unauthenticated_sender_login_mismatch</a>, and revised the docs.
+ </li>
+
+<li> Wietse made another iteration through the code to add plug-in
+support for multiple SASL implementations, and for reasons that
+have been lost, also changed <a href="postconf.5.html#smtpd_sasl_application_name">smtpd_sasl_application_name</a> into
+<a href="postconf.5.html#smtpd_sasl_path">smtpd_sasl_path</a>. </li>
+
+<li> The Dovecot SMTP server-only plug-in was originally implemented
+by Timo Sirainen of Procontrol, Finland. </li>
+
+<li> Patrick Ben Koetter revised this document for Postfix 2.4 and
+made much needed updates. </li>
+
+<li> Patrick Ben Koetter revised this document again for Postfix
+2.7 and made much needed updates. </li>
+
+</ul>
+
+</body>
</html>
+
<ul>
-<li><a href="#client_sasl">Enabling SASL authentication in the
+<li><a href="#client_sasl_enable">Enabling SASL authentication in the
Postfix SMTP client</a></li>
-<li><a href="#client_sasl_sender">Supporting multiple ISP accounts
-in the Postfix SMTP client</a></li>
+<li><a href="#client_sasl_sender">Configuring Sender-Dependent SASL
+authentication </a></li>
</ul>
<p> Execute the command "<b>postmap /etc/postfix/virtual</b>"
whenever you change the virtual table. </p>
-<h2><a name="client_sasl">Enabling SASL authentication in the
-Postfix SMTP client</a></h2>
+<h2><a name="client_sasl_enable">Enabling SASL authentication in the
+Postfix SMTP/LMTP client</a></h2>
-<p> Turn on client-side SASL authentication, and specify a table
-with per-host or per-destination username and password information.
-The Postfix SMTP client first searches the table for an entry with
-the remote SMTP server hostname; if no entry is found, then the
-Postfix SMTP client searches the table for
-an entry with the next-hop destination. Usually, that is the
-right-hand part of an email address, but it can also be the information
-that is specified with the <a href="postconf.5.html#relayhost">relayhost</a> parameter or with a <a href="transport.5.html">transport(5)</a>
-table. </p>
+<p> This section shows a typical scenario where the Postfix SMTP
+client sends all messages via a mail gateway server that requires
+SASL authentication. To make the example more readable we introduce
+it in two parts. </p>
<blockquote>
<pre>
/etc/postfix/<a href="postconf.5.html">main.cf</a>:
<a href="postconf.5.html#smtp_sasl_auth_enable">smtp_sasl_auth_enable</a> = yes
- <a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> = hash:/etc/postfix/sasl_passwd
- <a href="postconf.5.html#smtp_sasl_type">smtp_sasl_type</a> = cyrus
- <a href="postconf.5.html#relayhost">relayhost</a> = [mail.myisp.net]
+ <a href="postconf.5.html#relayhost">relayhost</a> = [mail.isp.example]
# Alternative form:
- # <a href="postconf.5.html#relayhost">relayhost</a> = [mail.myisp.net]:submission
-
-/etc/postfix/sasl_passwd:
- [mail.myisp.net] username:password
- [mail.myisp.net]:submission username:password
+ # <a href="postconf.5.html#relayhost">relayhost</a> = [mail.isp.example]:submission
+ <a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> = hash:/etc/postfix/sasl_passwd
</pre>
</blockquote>
-<p> Notes: </p>
-
<ul>
-<li> <p> The "submission" destination port tells Postfix to send
-mail via TCP network port 587, which is normally reserved for email
-clients. The default is to send mail to the "smtp" destination port
-(TCP port 25), which is used for receiving mail across the internet.
-If you use an explicit destination port in <a href="postconf.5.html">main.cf</a>, then you must
-use the same form also in the <a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> file. </p>
-
-<li> <p> Postfix does not deliver mail via TCP port 465 (the obsolete
-"wrappermode" protocol). See <a href="TLS_README.html">TLS_README</a> for a solution that uses the
-"stunnel" command. </p>
-
-<li> <p> The "[" and "]" prevent Postfix from looking up the MX
-(mail exchanger) records for the enclosed name. If you use this
-form in <a href="postconf.5.html">main.cf</a>, then you must use the same form also in the
-<a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> file. </p>
-
-<li> <p> The Postfix SMTP client opens the SASL client password
-file before entering the optional chroot jail, so you can keep the
-file in /etc/postfix and set permissions read / write only for root
-to keep the username:password combinations away from other system
-users. </p>
-
-<li> <p> Specify <b>dbm</b> instead of <b>hash</b> if your system
-uses <b>dbm</b> files instead of <b>db</b> files. To find out what
-lookup tables Postfix supports, use the command "<b>postconf -m</b>".
-</p>
-
-<li> <p> Execute the command "<b>postmap /etc/postfix/sasl_passwd</b>"
-whenever you change the sasl_passwd table. </p>
+<li> <p> The <code><a href="postconf.5.html#smtp_sasl_auth_enable">smtp_sasl_auth_enable</a></code> setting enables
+client-side authentication. We will configure the client's username
+and password information in the second part of the example. </p>
+</li>
+
+<li> <p> The <code><a href="postconf.5.html#relayhost">relayhost</a></code> setting forces the Postfix SMTP
+to send all remote messages to the specified mail server instead
+of trying to deliver them directly to their destination. </p> </li>
+
+<li> <p> In the <code><a href="postconf.5.html#relayhost">relayhost</a></code> setting, the "<code>[</code>"
+and "<code>]</code>" prevent the Postfix SMTP client from looking
+up MX (mail exchanger) records for the enclosed name. </p> </li>
+
+<li> <p> The <code><a href="postconf.5.html#relayhost">relayhost</a></code> destination may also specify a
+non-default TCP port. For example, the alternative form
+<code>[mail.isp.example]:submission</code> tells Postfix to connect
+to TCP network port 587, which is reserved for email client
+applications. </p> </li>
+
+<li> <p> The Postfix SMTP client is compatible with SMTP servers
+that use the non-standard "<code>AUTH=<em>method.</em>...</code>"
+syntax in response to the EHLO command; this requires no additional
+Postfix client configuration. </p> </li>
+
+<li> <p> The Postfix SMTP client does not support the obsolete
+"wrappermode" protocol, which uses TCP port <code>465</code> on the
+SMTP server. See <a href="TLS_README.html">TLS_README</a> for a solution that uses the
+<code>stunnel</code> command. </p> </li>
+
+<li> <p> With the <code><a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a></code> parameter,
+we configure the Postfix SMTP client to send username and password
+information to the mail gateway server. As discussed in the next
+section, the Postfix SMTP client supports multiple ISP accounts.
+For this reason the username and password are stored in a table
+that contains one username/password combination for each mail gateway
+server. </p>
</ul>
-<p> Workarounds: </p>
-
-<ul>
-
-<li> <p> Some remote SMTP servers support PLAIN or LOGIN authentication only.
-By default, the Postfix SMTP client does not use authentication
-methods that send plaintext passwords, and defers delivery with
-the following error message: "Authentication failed: cannot SASL
-authenticate to server". To enable plaintext authentication specify,
-for example: </p>
-
<blockquote>
<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_sasl_security_options">smtp_sasl_security_options</a> = noanonymous
+/etc/postfix/sasl_passwd:
+ # destination credentials
+ [mail.isp.example] username:password
+ # Alternative form:
+ # [mail.isp.example]:submission username:password
</pre>
</blockquote>
-<li> <p> Some remote SMTP servers announce authentication mechanisms
-that don't actually work. It is possible via the <a href="postconf.5.html#smtp_sasl_mechanism_filter">smtp_sasl_mechanism_filter</a>
-parameter to restrict the list of server mechanisms that the Postfix
-SMTP client will take into consideration: </p>
-
<blockquote>
-<pre>
-/etc/postfix/<a href="postconf.5.html">main.cf</a>:
- <a href="postconf.5.html#smtp_sasl_mechanism_filter">smtp_sasl_mechanism_filter</a> = !gssapi, !external, static:all
-</pre>
+
+<strong>Important</strong>
+
+<p> Keep the SASL client password file in <code>/etc/postfix</code>,
+and make the file read+write only for <code>root</code> to protect
+the username/password combinations against other users. The Postfix
+SMTP client will still be able to read the SASL client passwords.
+It opens the file as user <code>root</code> before it drops privileges,
+and before entering an optional chroot jail. </p>
+
</blockquote>
-<p> In the above example, the Postfix SMTP client will decline to
-use mechanisms
-that require special infrastructure such as Kerberos or TLS. </p>
+<ul>
+
+<li> <p> Use the <code>postmap</code> command whenever you
+change the <code>/etc/postfix/sasl_passwd</code> file. </p> </li>
-<li> <p> The Postfix SMTP client is backwards compatible with SMTP
-servers that use the non-standard "AUTH=method..." syntax in response
-to the EHLO command; there is no Postfix client configuration needed
-to work around it. </p>
+<li> <p> If you specify the "<code>[</code>" and "<code>]</code>"
+in the <code><a href="postconf.5.html#relayhost">relayhost</a></code> destination, then you must use the
+same form in the <code><a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a></code> file. </p>
+</li>
+
+<li> <p> If you specify a non-default TCP Port (such as
+"<code>:submission</code>" or "<code>:587</code>") in the
+<code><a href="postconf.5.html#relayhost">relayhost</a></code> destination, then you must use the same form
+in the <code><a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a></code> file. </p> </li>
</ul>
-<h2><a name="client_sasl_sender">Supporting multiple ISP accounts
-in the Postfix SMTP client</a></h2>
+<h2><a name="client_sasl_sender">Configuring Sender-Dependent SASL
+authentication</a></h2>
+
+<p> Postfix supports different ISP accounts for different sender
+addresses (version 2.3 and later). This can be useful when one
+person uses the same machine for work and for personal use, or when
+people with different ISP accounts share the same Postfix server.
+</p>
-<p> Postfix version 2.3 supports multiple ISP accounts. This can
-be useful when one person uses the same machine for work and for
-personal use, or when people with different ISP accounts share the
-same Postfix server. To make this possible, Postfix 2.3 supports
-per-sender SASL passwords and per-sender relay hosts. In the example
-below, Postfix will search the SASL password file by sender before
-it searches that same file by destination. Likewise, Postfix will
-search the per-sender <a href="postconf.5.html#relayhost">relayhost</a> file, and use the default <a href="postconf.5.html#relayhost">relayhost</a>
-only as a final resort. </p>
+<p> To make this possible, Postfix supports per-sender SASL passwords
+and per-sender relay hosts. In the example below, the Postfix SMTP
+client will search the SASL password file by sender address before
+it searches that same file by destination. Likewise, the Postfix
+<a href="trivial-rewrite.8.html">trivial-rewrite(8)</a> daemon will search the per-sender <a href="postconf.5.html#relayhost">relayhost</a> file,
+and use the default <code><a href="postconf.5.html#relayhost">relayhost</a></code> setting only as a final
+resort. </p>
<blockquote>
<pre>
<a href="postconf.5.html#sender_dependent_relayhost_maps">sender_dependent_relayhost_maps</a> = hash:/etc/postfix/sender_relay
<a href="postconf.5.html#smtp_sasl_auth_enable">smtp_sasl_auth_enable</a> = yes
<a href="postconf.5.html#smtp_sasl_password_maps">smtp_sasl_password_maps</a> = hash:/etc/postfix/sasl_passwd
- <a href="postconf.5.html#relayhost">relayhost</a> = [mail.myisp.net]
+ <a href="postconf.5.html#relayhost">relayhost</a> = [mail.isp.example]
# Alternative form:
- # <a href="postconf.5.html#relayhost">relayhost</a> = [mail.myisp.net]:submission
+ # <a href="postconf.5.html#relayhost">relayhost</a> = [mail.isp.example]:submission
+</pre>
+</blockquote>
+<blockquote>
+<pre>
/etc/postfix/sasl_passwd:
# Per-sender authentication; see also /etc/postfix/sender_relay.
- user1@example.com username2:password2
- user2@example.net username2:password2
+ user1@example.com username2:password2
+ user2@example.net username2:password2
# Login information for the default <a href="postconf.5.html#relayhost">relayhost</a>.
- [mail.myisp.net] username:password
- [mail.myisp.net]:submission username:password
+ [mail.isp.example] username:password
+ # Alternative form:
+ # [mail.isp.example]:submission username:password
+</pre>
+</blockquote>
+<blockquote>
+<pre>
/etc/postfix/sender_relay:
# Per-sender provider; see also /etc/postfix/sasl_passwd.
- user1@example.com [mail.example.com]:submission
- user2@example.net [mail.example.net]
+ user1@example.com [mail.example.com]:submission
+ user2@example.net [mail.example.net]
</pre>
</blockquote>
-<p> Notes: </p>
-
<ul>
<li> <p> If you are creative, then you can try to combine the two
tables into one single MySQL database, and configure different
Postfix queries to extract the appropriate information. </p>
-<li> <p> Specify <b>dbm</b> instead of <b>hash</b> if your system
-uses <b>dbm</b> files instead of <b>db</b> files. To find out what
-lookup tables Postfix supports, use the command "<b>postconf -m</b>".
-</p>
+<li> <p> Specify dbm instead of hash if your system uses dbm files
+instead of db files. To find out what lookup tables Postfix supports,
+use the command "postconf -m". </p>
-<li> <p> Execute the command "<b>postmap /etc/postfix/sasl_passwd</b>"
+<li> <p> Execute the command "postmap /etc/postfix/sasl_passwd"
whenever you change the sasl_passwd table. </p>
-<li> <p> Execute the command "<b>postmap /etc/postfix/sender_relay</b>"
+<li> <p> Execute the command "postmap /etc/postfix/sender_relay"
whenever you change the sender_relay table. </p>
</ul>
parameter. This setting controls the minimum acceptable SMTP client
TLS cipher grade for use with mandatory TLS encryption. The default
value "medium" is suitable for most destinations with which you may
-want to enforce TLS, and is beyond the reach of today's crypt-analytic
+want to enforce TLS, and is beyond the reach of today's cryptanalytic
methods. See <a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> for information on how to configure
ciphers on a per-destination basis. </p>
cal line.
Each pattern is a perl-like regular expression. The
- expression delimiter can be any character, except white-
- space or characters that have special meaning (tradition-
- ally the forward slash is used). The regular expression
- can contain whitespace.
+ expression delimiter can be any non-alphanumerical charac-
+ ter, except whitespace or characters that have special
+ meaning (traditionally the forward slash is used). The
+ regular expression can contain whitespace.
By default, matching is case-insensitive, and newlines are
not treated as special characters. The behavior is con-
<p>
Specify a string of the form <i>transport:nexthop</i>, where <i>transport</i>
is the name of a mail delivery transport defined in <a href="master.5.html">master.cf</a>.
-The <i>:nexthop</i> part is optional. For more details see the
-<a href="transport.5.html">transport(5)</a> manual page.
+The <i>:nexthop</i> destination is optional; its syntax is documented
+in the manual page of the corresponding delivery agent.
</p>
<p>
</DD>
<DT><b><a name="empty_address_default_transport_maps_lookup_key">empty_address_default_transport_maps_lookup_key</a>
-(default: <>)</b></DT><DD>
+(default: <>)</b></DT><DD>
<p> The <a href="postconf.5.html#sender_dependent_default_transport_maps">sender_dependent_default_transport_maps</a> search string that
will be used instead of the null sender address. </p>
<p>
Specify a string of the form <i>transport:nexthop</i>, where <i>transport</i>
is the name of a mail delivery transport defined in <a href="master.5.html">master.cf</a>.
-The <i>:nexthop</i> part is optional. For more details see the
-<a href="transport.5.html">transport(5)</a> manual page.
+The <i>:nexthop</i> destination is optional; its syntax is documented
+in the manual page of the corresponding delivery agent.
</p>
<p>
error, or whether the client is listed at the DNSBL sites specified
with the <a href="postconf.5.html#postscreen_dnsbl_sites">postscreen_dnsbl_sites</a> parameter. Take the corresponding
action, or forward the connection to a real SMTP server process.
-</p>
+</dd>
<dt> drop </dt>
<dt> continue </dt>
-<dd> Forward the connection to a real SMTP server process. </p>
+<dd> Forward the connection to a real SMTP server process. </dd>
<dt> drop </dt>
elapsed. If the client is listed at the DNS blocklist domains
specified with the <a href="postconf.5.html#postscreen_dnsbl_sites">postscreen_dnsbl_sites</a> parameter, execute the
action specified with the <a href="postconf.5.html#postscreen_dnsbl_action">postscreen_dnsbl_action</a> parameter, otherwise
-forward the connection to a real SMTP server process. </p>
+forward the connection to a real SMTP server process. </dd>
<dt> drop </dt>
<dd> Continue waiting until the <a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a> time has
elapsed, and report whether the client is listed at the DNSBL sites
specified with the <a href="postconf.5.html#postscreen_dnsbl_sites">postscreen_dnsbl_sites</a> parameter. Do not
-forward the broken connection to a real SMTP server process. </p>
+forward the broken connection to a real SMTP server process. </dd>
<dt> drop </dt>
<p>
Specify a string of the form <i>transport:nexthop</i>, where <i>transport</i>
is the name of a mail delivery transport defined in <a href="master.5.html">master.cf</a>.
-The <i>:nexthop</i> part is optional. For more details see the
-<a href="transport.5.html">transport(5)</a> manual page.
+The <i>:nexthop</i> destination is optional; its syntax is documented
+in the manual page of the corresponding delivery agent.
</p>
<p>
(default: no)</b></DT><DD>
<p>
-Whether or not a <a href="local.8.html">local(8)</a> recipient's home directory must exist
+Require that a <a href="local.8.html">local(8)</a> recipient's home directory exists
before mail delivery is attempted. By default this test is disabled.
It can be useful for environments that import home directories to
-the mail server (NOT RECOMMENDED).
+the mail server (IMPORTING HOME DIRECTORIES IS NOT RECOMMENDED).
</p>
use with
mandatory TLS encryption. The default value "medium" is suitable
for most destinations with which you may want to enforce TLS, and
-is beyond the reach of today's crypt-analytic methods. See
+is beyond the reach of today's cryptanalytic methods. See
<a href="postconf.5.html#smtp_tls_policy_maps">smtp_tls_policy_maps</a> for information on how to configure ciphers
on a per-destination basis. </p>
<dl>
<dt><b>export</b></dt>
-<dd> Enable the mainstream "EXPORT" grade or better OpenSSL
-ciphers. This is always used for opportunistic encryption. It is
+<dd> Enable "EXPORT" grade or better OpenSSL
+ciphers. This is the default for opportunistic encryption. It is
not recommended for mandatory encryption unless you must enforce TLS
with "crippled" peers. The underlying cipherlist is specified via the
<a href="postconf.5.html#tls_export_cipherlist">tls_export_cipherlist</a> configuration parameter, which you are strongly
-encouraged to not change. The default value of <a href="postconf.5.html#tls_export_cipherlist">tls_export_cipherlist</a>
-includes anonymous ciphers, but these are automatically filtered out if
-the client is configured to verify server certificates. If you must
-exclude anonymous ciphers also at the "encrypt" security level, set
-"<a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a> = aNULL". </dd>
+encouraged to not change. </dd>
<dt><b>low</b></dt>
-<dd> Enable the mainstream "LOW" grade or better OpenSSL ciphers. This
+<dd> Enable "LOW" grade or better OpenSSL ciphers. This
setting is only appropriate for internal mail servers. The underlying
cipherlist is specified via the <a href="postconf.5.html#tls_low_cipherlist">tls_low_cipherlist</a> configuration
-parameter, which you are strongly encouraged to not change. The default
-value of <a href="postconf.5.html#tls_low_cipherlist">tls_low_cipherlist</a> includes anonymous ciphers, but these are
-automatically filtered out if the client is configured to verify server
-certificates. If you must exclude anonymous ciphers also at the "encrypt"
-security level, set "<a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a> = aNULL". </dd>
+parameter, which you are strongly encouraged to not change. </dd>
<dt><b>medium</b></dt>
-<dd> Enable the mainstream "MEDIUM" grade or better OpenSSL ciphers.
+<dd> Enable "MEDIUM" grade or better OpenSSL ciphers.
The underlying cipherlist is specified via the <a href="postconf.5.html#tls_medium_cipherlist">tls_medium_cipherlist</a>
configuration parameter, which you are strongly encouraged to not change.
-The default value of <a href="postconf.5.html#tls_medium_cipherlist">tls_medium_cipherlist</a> includes anonymous ciphers,
-but these are automatically filtered out if the client is configured to
-verify server certificates. If you must exclude anonymous ciphers also
-at the "encrypt" security level, set "<a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a>
-= aNULL". </dd>
+</dd>
<dt><b>high</b></dt>
-<dd> Enable only the mainstream "HIGH" grade OpenSSL ciphers. This
-setting is appropriate when all mandatory TLS destinations support
-some of "HIGH" grade ciphers, this is not uncommon. The underlying
-cipherlist is specified via the <a href="postconf.5.html#tls_high_cipherlist">tls_high_cipherlist</a> configuration
-parameter, which you are strongly encouraged to not change. The default
-value of <a href="postconf.5.html#tls_high_cipherlist">tls_high_cipherlist</a> includes anonymous ciphers, but these are
-automatically filtered out if the client is configured to verify server
-certificates. If you must exclude anonymous ciphers also at the "encrypt"
-security level, set "<a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a> = aNULL". </dd>
+<dd> Enable only "HIGH" grade OpenSSL ciphers. This setting may
+be appropriate when all mandatory TLS destinations (e.g. when all
+mail is routed to a suitably capable <a href="postconf.5.html#relayhost">relayhost</a>) support at least one
+"HIGH" grade cipher. The underlying cipherlist is specified via the
+<a href="postconf.5.html#tls_high_cipherlist">tls_high_cipherlist</a> configuration parameter, which you are strongly
+encouraged to not change. </dd>
<dt><b>null</b></dt>
<dd> Enable only the "NULL" OpenSSL ciphers, these provide authentication
UNIX-domain socket that is configured to support "NULL" ciphers. The
underlying cipherlist is specified via the <a href="postconf.5.html#tls_null_cipherlist">tls_null_cipherlist</a>
configuration parameter, which you are strongly encouraged to not
-change. The default value of <a href="postconf.5.html#tls_null_cipherlist">tls_null_cipherlist</a> excludes anonymous
-ciphers (OpenSSL 0.9.8 has NULL ciphers that offer data integrity without
-encryption or authentication). </dd>
+change. </dd>
</dl>
+<p> The underlying cipherlists for grades other than "null" include
+anonymous ciphers, but these are automatically filtered out if the
+Postfix SMTP client is configured to verify server certificates.
+You are very unlikely to need to take any steps to exclude anonymous
+ciphers, they are excluded automatically as necessary. If you must
+exclude anonymous ciphers at the "may" or "encrypt" security levels,
+when the Postfix SMTP client does not need or use peer certificates, set
+"<a href="postconf.5.html#smtp_tls_exclude_ciphers">smtp_tls_exclude_ciphers</a> = aNULL". To exclude anonymous ciphers only when
+TLS is enforced, set "<a href="postconf.5.html#smtp_tls_mandatory_exclude_ciphers">smtp_tls_mandatory_exclude_ciphers</a> = aNULL". </p>
+
<p> This feature is available in Postfix 2.3 and later. </p>
# Opportunistic TLS.
<a href="postconf.5.html#smtp_tls_security_level">smtp_tls_security_level</a> = may
# Postfix ≥ 2.6:
-# Do not tweak opportunistic ciphers unless it is essential
+# Do not tweak opportunistic ciphers or protocol unless it is essential
# to do so (if a security vulnerability is found in the SSL library that
# can be mitigated by disabling a particular protocol or raising the
# cipher grade from "export" to "low" or "medium").
<dt><b>speed_adjust</b></dt>
-<dd> Do not connect to a before-queue content filter until an entire
+<dd> <p> Do not connect to a before-queue content filter until an entire
message has been received. This reduces the number of simultaneous
before-queue content filter processes. </p>
configuration file or rendezvous point. </p>
<p> This feature is available in Postfix 2.3 and later. In earlier
-releases it was called <b>smtpd_sasl_application_name</b>. </p>
+releases it was called <b><a href="postconf.5.html#smtpd_sasl_application_name">smtpd_sasl_application_name</a></b>. </p>
</DD>
<DT><b><a name="smtpd_tls_mandatory_ciphers">smtpd_tls_mandatory_ciphers</a>
(default: medium)</b></DT><DD>
-<p> The minimum TLS cipher grade that the Postfix SMTP server
-will use with mandatory TLS encryption. Cipher types listed in
-<a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">smtpd_tls_mandatory_exclude_ciphers</a> or <a href="postconf.5.html#smtpd_tls_exclude_ciphers">smtpd_tls_exclude_ciphers</a> are
-excluded from the base definition of the selected cipher grade. See
-<a href="postconf.5.html#smtpd_tls_ciphers">smtpd_tls_ciphers</a> for cipher controls that apply to opportunistic
-TLS. </p>
+<p> The minimum TLS cipher grade that the Postfix SMTP server will
+use with mandatory TLS encryption. The default grade ("medium") is
+sufficiently strong that any benefit from globally restricting TLS
+sessions to a more stringent grade is likely negligible, especially
+given the fact that many implementations still do not offer any stronger
+("high" grade) ciphers, while those that do, will always use "high"
+grade ciphers. So insisting on "high" grade ciphers is generally
+counter-productive. Allowing "export" or "low" ciphers is typically
+not a good idea, as systems limited to just these are limited to
+obsolete browsers. No known SMTP clients fail to support at least
+one "medium" or "high" grade cipher. </p>
<p> The following cipher grades are supported: </p>
<dl>
<dt><b>export</b></dt>
-<dd> Enable the mainstream "EXPORT" grade or better OpenSSL ciphers.
+<dd> Enable "EXPORT" grade or stronger OpenSSL ciphers.
This is the most appropriate setting for public MX hosts, and is always
used with opportunistic TLS encryption. The underlying cipherlist
is specified via the <a href="postconf.5.html#tls_export_cipherlist">tls_export_cipherlist</a> configuration parameter,
-which you are strongly encouraged to not change. The default value
-of <a href="postconf.5.html#tls_export_cipherlist">tls_export_cipherlist</a> includes anonymous ciphers, but these are
-automatically filtered out if the server is configured to ask for
-client certificates. If you must always exclude anonymous ciphers,
-set "<a href="postconf.5.html#smtpd_tls_exclude_ciphers">smtpd_tls_exclude_ciphers</a> = aNULL". To exclude anonymous ciphers
-only when TLS is enforced, set "<a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">smtpd_tls_mandatory_exclude_ciphers</a> =
-aNULL". </dd>
+which you are strongly encouraged to not change. </dd>
<dt><b>low</b></dt>
-<dd> Enable the mainstream "LOW" grade or better OpenSSL ciphers. The
+<dd> Enable "LOW" grade or stronger OpenSSL ciphers. The
underlying cipherlist is specified via the <a href="postconf.5.html#tls_low_cipherlist">tls_low_cipherlist</a>
configuration parameter, which you are strongly encouraged to
-not change. The default value of <a href="postconf.5.html#tls_low_cipherlist">tls_low_cipherlist</a> includes
-anonymous ciphers, but these are automatically filtered out if the
-server is configured to ask for client certificates. If you must
-always exclude anonymous ciphers, set "<a href="postconf.5.html#smtpd_tls_exclude_ciphers">smtpd_tls_exclude_ciphers</a> =
-aNULL". To exclude anonymous ciphers only when TLS is enforced, set
-"<a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">smtpd_tls_mandatory_exclude_ciphers</a> = aNULL". </dd>
+not change. </dd>
<dt><b>medium</b></dt>
-<dd> Enable the mainstream "MEDIUM" grade or better OpenSSL ciphers. These
-are essentially the 128-bit or stronger ciphers. This is the default
-minimum strength for mandatory TLS encryption. MSAs that enforce
-TLS and have clients that do not support any "MEDIUM" or "HIGH"
-grade ciphers, may need to configure a weaker ("low" or "export")
-minimum cipher grade. The underlying cipherlist is specified via the
-<a href="postconf.5.html#tls_medium_cipherlist">tls_medium_cipherlist</a> configuration parameter, which you are strongly
-encouraged to not change. The default value of <a href="postconf.5.html#tls_medium_cipherlist">tls_medium_cipherlist</a>
-includes anonymous ciphers, but these are automatically filtered out if
-the server is configured to ask for client certificates. If you must
-always exclude anonymous ciphers, set "<a href="postconf.5.html#smtpd_tls_exclude_ciphers">smtpd_tls_exclude_ciphers</a> =
-aNULL". To exclude anonymous ciphers only when TLS is enforced, set
-"<a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">smtpd_tls_mandatory_exclude_ciphers</a> = aNULL". </dd>
+<dd> Enable "MEDIUM" grade or stronger OpenSSL ciphers. These use 128-bit
+or longer symmetric bulk-encryption keys. This is the default minimum
+strength for mandatory TLS encryption. The underlying cipherlist is
+specified via the <a href="postconf.5.html#tls_medium_cipherlist">tls_medium_cipherlist</a> configuration parameter, which
+you are strongly encouraged to not change. </dd>
<dt><b>high</b></dt>
-<dd> Enable only the mainstream "HIGH" grade OpenSSL ciphers. The
+<dd> Enable only "HIGH" grade OpenSSL ciphers. The
underlying cipherlist is specified via the <a href="postconf.5.html#tls_high_cipherlist">tls_high_cipherlist</a>
configuration parameter, which you are strongly encouraged to
-not change. The default value of <a href="postconf.5.html#tls_high_cipherlist">tls_high_cipherlist</a> includes
-anonymous ciphers, but these are automatically filtered out if the
-server is configured to ask for client certificates. If you must
-always exclude anonymous ciphers, set "<a href="postconf.5.html#smtpd_tls_exclude_ciphers">smtpd_tls_exclude_ciphers</a> =
-aNULL". To exclude anonymous ciphers only when TLS is enforced, set
-"<a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">smtpd_tls_mandatory_exclude_ciphers</a> = aNULL". </dd>
+not change. </dd>
<dt><b>null</b></dt>
<dd> Enable only the "NULL" OpenSSL ciphers, these provide authentication
case that all clients are prepared to use NULL ciphers (not normally
enabled in TLS clients). The underlying cipherlist is specified via the
<a href="postconf.5.html#tls_null_cipherlist">tls_null_cipherlist</a> configuration parameter, which you are strongly
-encouraged to not change. The default value of <a href="postconf.5.html#tls_null_cipherlist">tls_null_cipherlist</a>
-excludes anonymous ciphers (OpenSSL 0.9.8 has NULL ciphers that offer
-data integrity without encryption or authentication). </dd>
+encouraged to not change. </dd>
</dl>
+<p> Cipher types listed in
+<a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">smtpd_tls_mandatory_exclude_ciphers</a> or <a href="postconf.5.html#smtpd_tls_exclude_ciphers">smtpd_tls_exclude_ciphers</a> are
+excluded from the base definition of the selected cipher grade. See
+<a href="postconf.5.html#smtpd_tls_ciphers">smtpd_tls_ciphers</a> for cipher controls that apply to opportunistic
+TLS. </p>
+
+<p> The underlying cipherlists for grades other than "null" include
+anonymous ciphers, but these are automatically filtered out if the
+server is configured to ask for client certificates. You are very
+unlikely to need to take any steps to exclude anonymous ciphers, they
+are excluded automatically as required. If you must exclude anonymous
+ciphers even when Postfix does not need or use peer certificates, set
+"<a href="postconf.5.html#smtpd_tls_exclude_ciphers">smtpd_tls_exclude_ciphers</a> = aNULL". To exclude anonymous ciphers only
+when TLS is enforced, set "<a href="postconf.5.html#smtpd_tls_mandatory_exclude_ciphers">smtpd_tls_mandatory_exclude_ciphers</a> = aNULL". </p>
+
<p> This feature is available in Postfix 2.3 and later. </p>
<p>
Specify a string of the form <i>transport:nexthop</i>, where <i>transport</i>
is the name of a mail delivery transport defined in <a href="master.5.html">master.cf</a>.
-The <i>:nexthop</i> part is optional. For more details see the
-<a href="transport.5.html">transport(5)</a> manual page.
+The <i>:nexthop</i> destination is optional; its syntax is documented
+in the manual page of the corresponding delivery agent.
</p>
<p>
size, arrival time, sender, and the recipients that
still need to be delivered. If mail could not be
delivered upon the last attempt, the reason for
- failure is shown. This mode of operation is imple-
- mented by executing the <a href="postqueue.1.html"><b>postqueue</b>(1)</a> command. The
- queue ID string is followed by an optional status
- character:
+ failure is shown. The queue ID string is followed
+ by an optional status character:
<b>*</b> The message is in the <b>active</b> queue, i.e. the
message is selected for delivery.
Solaris, and in <b>regex</b>(7) with Linux. Other systems may use
other document names.
- The expression delimiter can be any character, except
- whitespace or characters that have special meaning (tradi-
- tionally the forward slash is used). The regular expres-
- sion can contain whitespace.
+ The expression delimiter can be any non-alphanumerical
+ character, except whitespace or characters that have spe-
+ cial meaning (traditionally the forward slash is used).
+ The regular expression can contain whitespace.
By default, matching is case-insensitive, and newlines are
not treated as special characters. The behavior is con-
as if the local hostname were specified, instead of
rejecting the address as invalid.
- <b><a href="postconf.5.html#smtpd_command_filter">smtpd_command_filter</a> (empty)</b>
- A mechanism to transform commands from remote SMTP
- clients.
-
<b><a href="postconf.5.html#smtpd_reject_unlisted_sender">smtpd_reject_unlisted_sender</a> (no)</b>
- Request that the Postfix SMTP server rejects mail
- from unknown sender addresses, even when no
- explicit <a href="postconf.5.html#reject_unlisted_sender">reject_unlisted_sender</a> access restriction
+ Request that the Postfix SMTP server rejects mail
+ from unknown sender addresses, even when no
+ explicit <a href="postconf.5.html#reject_unlisted_sender">reject_unlisted_sender</a> access restriction
is specified.
<b><a href="postconf.5.html#smtpd_sasl_exceptions_networks">smtpd_sasl_exceptions_networks</a> (empty)</b>
- What remote SMTP clients the Postfix SMTP server
+ What remote SMTP clients the Postfix SMTP server
will not offer AUTH support to.
Available in Postfix version 2.2 and later:
<b><a href="postconf.5.html#smtpd_discard_ehlo_keyword_address_maps">smtpd_discard_ehlo_keyword_address_maps</a> (empty)</b>
- Lookup tables, indexed by the remote SMTP client
- address, with case insensitive lists of EHLO key-
- words (pipelining, starttls, auth, etc.) that the
+ Lookup tables, indexed by the remote SMTP client
+ address, with case insensitive lists of EHLO key-
+ words (pipelining, starttls, auth, etc.) that the
SMTP server will not send in the EHLO response to a
remote SMTP client.
<b><a href="postconf.5.html#smtpd_discard_ehlo_keywords">smtpd_discard_ehlo_keywords</a> (empty)</b>
- A case insensitive list of EHLO keywords (pipelin-
- ing, starttls, auth, etc.) that the SMTP server
+ A case insensitive list of EHLO keywords (pipelin-
+ ing, starttls, auth, etc.) that the SMTP server
will not send in the EHLO response to a remote SMTP
client.
<b><a href="postconf.5.html#smtpd_delay_open_until_valid_rcpt">smtpd_delay_open_until_valid_rcpt</a> (yes)</b>
- Postpone the start of an SMTP mail transaction
+ Postpone the start of an SMTP mail transaction
until a valid RCPT TO command is received.
Available in Postfix version 2.3 and later:
<b><a href="postconf.5.html#smtpd_tls_always_issue_session_ids">smtpd_tls_always_issue_session_ids</a> (yes)</b>
- Force the Postfix SMTP server to issue a TLS ses-
- sion id, even when TLS session caching is turned
+ Force the Postfix SMTP server to issue a TLS ses-
+ sion id, even when TLS session caching is turned
off (<a href="postconf.5.html#smtpd_tls_session_cache_database">smtpd_tls_session_cache_database</a> is empty).
Available in Postfix version 2.6 and later:
<b><a href="postconf.5.html#tcp_windowsize">tcp_windowsize</a> (0)</b>
- An optional workaround for routers that break TCP
+ An optional workaround for routers that break TCP
window scaling.
+ Available in Postfix version 2.7 and later:
+
+ <b><a href="postconf.5.html#smtpd_command_filter">smtpd_command_filter</a> (empty)</b>
+ A mechanism to transform commands from remote SMTP
+ clients.
+
<b>ADDRESS REWRITING CONTROLS</b>
See the <a href="ADDRESS_REWRITING_README.html">ADDRESS_REWRITING_README</a> document for a detailed
discussion of Postfix address rewriting.
<b>query</b> <i>address</i>
Look up the <i>status</i> and <i>text</i> for the specified
- address. If the status is unknown, a probe is sent
+ <i>address</i>. If the status is unknown, a probe is sent
and an "in progress" status is returned.
<b>SECURITY</b>
low privilege.
The address verification server can be coerced to store
- unlimited amounts of garbage. Limiting the cache size
- trades one problem (disk space exhaustion) for another one
- (poor response time to client requests).
+ unlimited amounts of garbage. Limiting the cache expiry
+ time trades one problem (disk space exhaustion) for
+ another one (poor response time to client requests).
With Postfix version 2.5 and later, the <a href="verify.8.html"><b>verify</b>(8)</a> server
no longer uses root privileges when opening the
Problems and transactions are logged to <b>syslogd</b>(8).
<b>BUGS</b>
- The address verification service is suitable only for
- sites that handle a low mail volume. Verification probes
- add additional traffic to the mail queue and perform
- poorly under high load. Servers may blacklist sites that
- probe excessively, or that probe excessively for non-exis-
- tent recipient addresses.
+ Address verification probe messages add additional traffic
+ to the mail queue. Recipient verification may cause an
+ increased load on down-stream servers in the case of a
+ dictionary attack or a flood of backscatter bounces.
+ Sender address verification may cause your site to be
+ blacklisted by some providers.
If the persistent database ever gets corrupted then the
world comes to an end and human intervention is needed.
<b>CONFIGURATION PARAMETERS</b>
Changes to <a href="postconf.5.html"><b>main.cf</b></a> are not picked up automatically, as
- <a href="verify.8.html"><b>verify</b>(8)</a> processes are persistent. Use the command "<b>post-</b>
+ <a href="verify.8.html"><b>verify</b>(8)</a> processes are long-lived. Use the command "<b>post-</b>
<b>fix reload</b>" after a configuration change.
The text below provides only a parameter summary. See
Each queue entry shows the queue file ID, message
size, arrival time, sender, and the recipients that still need to
be delivered. If mail could not be delivered upon the last attempt,
-the reason for failure is shown. This mode of operation is implemented
-by executing the \fBpostqueue\fR(1) command. The queue ID string
+the reason for failure is shown. The queue ID string
is followed by an optional status character:
.RS
.IP \fB*\fR
starts with whitespace continues a logical line.
.PP
Each pattern is a perl-like regular expression. The expression
-delimiter can be any character, except whitespace or characters
+delimiter can be any non-alphanumerical character, except
+whitespace or characters
that have special meaning (traditionally the forward slash is used).
The regular expression can contain whitespace.
.PP
Specify a string of the form \fItransport:nexthop\fR, where \fItransport\fR
is the name of a mail delivery transport defined in master.cf.
-The \fI:nexthop\fR part is optional. For more details see the
-\fBtransport\fR(5) manual page.
+The \fI:nexthop\fR destination is optional; its syntax is documented
+in the manual page of the corresponding delivery agent.
.PP
Example:
.PP
.PP
Specify a string of the form \fItransport:nexthop\fR, where \fItransport\fR
is the name of a mail delivery transport defined in master.cf.
-The \fI:nexthop\fR part is optional. For more details see the
-\fBtransport\fR(5) manual page.
+The \fI:nexthop\fR destination is optional; its syntax is documented
+in the manual page of the corresponding delivery agent.
.PP
Beware: if you override the default local delivery agent then you
need to review the LOCAL_RECIPIENT_README document, otherwise the
.PP
Specify a string of the form \fItransport:nexthop\fR, where \fItransport\fR
is the name of a mail delivery transport defined in master.cf.
-The \fI:nexthop\fR part is optional. For more details see the
-\fBtransport\fR(5) manual page.
+The \fI:nexthop\fR destination is optional; its syntax is documented
+in the manual page of the corresponding delivery agent.
.PP
See also the relay domains address class in the ADDRESS_CLASS_README
file.
.ft R
.in -4
.SH require_home_directory (default: no)
-Whether or not a \fBlocal\fR(8) recipient's home directory must exist
+Require that a \fBlocal\fR(8) recipient's home directory exists
before mail delivery is attempted. By default this test is disabled.
It can be useful for environments that import home directories to
-the mail server (NOT RECOMMENDED).
+the mail server (IMPORTING HOME DIRECTORIES IS NOT RECOMMENDED).
.SH resolve_dequoted_address (default: yes)
Resolve a recipient address safely instead of correctly, by
looking inside quotes.
use with
mandatory TLS encryption. The default value "medium" is suitable
for most destinations with which you may want to enforce TLS, and
-is beyond the reach of today's crypt-analytic methods. See
+is beyond the reach of today's cryptanalytic methods. See
smtp_tls_policy_maps for information on how to configure ciphers
on a per-destination basis.
.PP
The following cipher grades are supported:
.IP "\fBexport\fR"
-Enable the mainstream "EXPORT" grade or better OpenSSL
-ciphers. This is always used for opportunistic encryption. It is
+Enable "EXPORT" grade or better OpenSSL
+ciphers. This is the default for opportunistic encryption. It is
not recommended for mandatory encryption unless you must enforce TLS
with "crippled" peers. The underlying cipherlist is specified via the
tls_export_cipherlist configuration parameter, which you are strongly
-encouraged to not change. The default value of tls_export_cipherlist
-includes anonymous ciphers, but these are automatically filtered out if
-the client is configured to verify server certificates. If you must
-exclude anonymous ciphers also at the "encrypt" security level, set
-"smtp_tls_mandatory_exclude_ciphers = aNULL".
+encouraged to not change.
.IP "\fBlow\fR"
-Enable the mainstream "LOW" grade or better OpenSSL ciphers. This
+Enable "LOW" grade or better OpenSSL ciphers. This
setting is only appropriate for internal mail servers. The underlying
cipherlist is specified via the tls_low_cipherlist configuration
-parameter, which you are strongly encouraged to not change. The default
-value of tls_low_cipherlist includes anonymous ciphers, but these are
-automatically filtered out if the client is configured to verify server
-certificates. If you must exclude anonymous ciphers also at the "encrypt"
-security level, set "smtp_tls_mandatory_exclude_ciphers = aNULL".
+parameter, which you are strongly encouraged to not change.
.IP "\fBmedium\fR"
-Enable the mainstream "MEDIUM" grade or better OpenSSL ciphers.
+Enable "MEDIUM" grade or better OpenSSL ciphers.
The underlying cipherlist is specified via the tls_medium_cipherlist
configuration parameter, which you are strongly encouraged to not change.
-The default value of tls_medium_cipherlist includes anonymous ciphers,
-but these are automatically filtered out if the client is configured to
-verify server certificates. If you must exclude anonymous ciphers also
-at the "encrypt" security level, set "smtp_tls_mandatory_exclude_ciphers
-= aNULL".
.IP "\fBhigh\fR"
-Enable only the mainstream "HIGH" grade OpenSSL ciphers. This
-setting is appropriate when all mandatory TLS destinations support
-some of "HIGH" grade ciphers, this is not uncommon. The underlying
-cipherlist is specified via the tls_high_cipherlist configuration
-parameter, which you are strongly encouraged to not change. The default
-value of tls_high_cipherlist includes anonymous ciphers, but these are
-automatically filtered out if the client is configured to verify server
-certificates. If you must exclude anonymous ciphers also at the "encrypt"
-security level, set "smtp_tls_mandatory_exclude_ciphers = aNULL".
+Enable only "HIGH" grade OpenSSL ciphers. This setting may
+be appropriate when all mandatory TLS destinations (e.g. when all
+mail is routed to a suitably capable relayhost) support at least one
+"HIGH" grade cipher. The underlying cipherlist is specified via the
+tls_high_cipherlist configuration parameter, which you are strongly
+encouraged to not change.
.IP "\fBnull\fR"
Enable only the "NULL" OpenSSL ciphers, these provide authentication
without encryption. This setting is only appropriate in the rare case
UNIX-domain socket that is configured to support "NULL" ciphers. The
underlying cipherlist is specified via the tls_null_cipherlist
configuration parameter, which you are strongly encouraged to not
-change. The default value of tls_null_cipherlist excludes anonymous
-ciphers (OpenSSL 0.9.8 has NULL ciphers that offer data integrity without
-encryption or authentication).
+change.
+.PP
+The underlying cipherlists for grades other than "null" include
+anonymous ciphers, but these are automatically filtered out if the
+Postfix SMTP client is configured to verify server certificates.
+You are very unlikely to need to take any steps to exclude anonymous
+ciphers, they are excluded automatically as necessary. If you must
+exclude anonymous ciphers at the "may" or "encrypt" security levels,
+when the Postfix SMTP client does not need or use peer certificates, set
+"smtp_tls_exclude_ciphers = aNULL". To exclude anonymous ciphers only when
+TLS is enforced, set "smtp_tls_mandatory_exclude_ciphers = aNULL".
.PP
This feature is available in Postfix 2.3 and later.
.SH smtp_tls_mandatory_exclude_ciphers (default: empty)
# Opportunistic TLS.
smtp_tls_security_level = may
# Postfix >= 2.6:
-# Do not tweak opportunistic ciphers unless it is essential
+# Do not tweak opportunistic ciphers or protocol unless it is essential
# to do so (if a security vulnerability is found in the SSL library that
# can be mitigated by disabling a particular protocol or raising the
# cipher grade from "export" to "low" or "medium").
.PP
This feature is available in Postfix 2.2 and later.
.SH smtpd_tls_mandatory_ciphers (default: medium)
-The minimum TLS cipher grade that the Postfix SMTP server
-will use with mandatory TLS encryption. Cipher types listed in
-smtpd_tls_mandatory_exclude_ciphers or smtpd_tls_exclude_ciphers are
-excluded from the base definition of the selected cipher grade. See
-smtpd_tls_ciphers for cipher controls that apply to opportunistic
-TLS.
+The minimum TLS cipher grade that the Postfix SMTP server will
+use with mandatory TLS encryption. The default grade ("medium") is
+sufficiently strong that any benefit from globally restricting TLS
+sessions to a more stringent grade is likely negligible, especially
+given the fact that many implementations still do not offer any stronger
+("high" grade) ciphers, while those that do, will always use "high"
+grade ciphers. So insisting on "high" grade ciphers is generally
+counter-productive. Allowing "export" or "low" ciphers is typically
+not a good idea, as systems limited to just these are limited to
+obsolete browsers. No known SMTP clients fail to support at least
+one "medium" or "high" grade cipher.
.PP
The following cipher grades are supported:
.IP "\fBexport\fR"
-Enable the mainstream "EXPORT" grade or better OpenSSL ciphers.
+Enable "EXPORT" grade or stronger OpenSSL ciphers.
This is the most appropriate setting for public MX hosts, and is always
used with opportunistic TLS encryption. The underlying cipherlist
is specified via the tls_export_cipherlist configuration parameter,
-which you are strongly encouraged to not change. The default value
-of tls_export_cipherlist includes anonymous ciphers, but these are
-automatically filtered out if the server is configured to ask for
-client certificates. If you must always exclude anonymous ciphers,
-set "smtpd_tls_exclude_ciphers = aNULL". To exclude anonymous ciphers
-only when TLS is enforced, set "smtpd_tls_mandatory_exclude_ciphers =
-aNULL".
+which you are strongly encouraged to not change.
.IP "\fBlow\fR"
-Enable the mainstream "LOW" grade or better OpenSSL ciphers. The
+Enable "LOW" grade or stronger OpenSSL ciphers. The
underlying cipherlist is specified via the tls_low_cipherlist
configuration parameter, which you are strongly encouraged to
-not change. The default value of tls_low_cipherlist includes
-anonymous ciphers, but these are automatically filtered out if the
-server is configured to ask for client certificates. If you must
-always exclude anonymous ciphers, set "smtpd_tls_exclude_ciphers =
-aNULL". To exclude anonymous ciphers only when TLS is enforced, set
-"smtpd_tls_mandatory_exclude_ciphers = aNULL".
+not change.
.IP "\fBmedium\fR"
-Enable the mainstream "MEDIUM" grade or better OpenSSL ciphers. These
-are essentially the 128-bit or stronger ciphers. This is the default
-minimum strength for mandatory TLS encryption. MSAs that enforce
-TLS and have clients that do not support any "MEDIUM" or "HIGH"
-grade ciphers, may need to configure a weaker ("low" or "export")
-minimum cipher grade. The underlying cipherlist is specified via the
-tls_medium_cipherlist configuration parameter, which you are strongly
-encouraged to not change. The default value of tls_medium_cipherlist
-includes anonymous ciphers, but these are automatically filtered out if
-the server is configured to ask for client certificates. If you must
-always exclude anonymous ciphers, set "smtpd_tls_exclude_ciphers =
-aNULL". To exclude anonymous ciphers only when TLS is enforced, set
-"smtpd_tls_mandatory_exclude_ciphers = aNULL".
+Enable "MEDIUM" grade or stronger OpenSSL ciphers. These use 128-bit
+or longer symmetric bulk-encryption keys. This is the default minimum
+strength for mandatory TLS encryption. The underlying cipherlist is
+specified via the tls_medium_cipherlist configuration parameter, which
+you are strongly encouraged to not change.
.IP "\fBhigh\fR"
-Enable only the mainstream "HIGH" grade OpenSSL ciphers. The
+Enable only "HIGH" grade OpenSSL ciphers. The
underlying cipherlist is specified via the tls_high_cipherlist
configuration parameter, which you are strongly encouraged to
-not change. The default value of tls_high_cipherlist includes
-anonymous ciphers, but these are automatically filtered out if the
-server is configured to ask for client certificates. If you must
-always exclude anonymous ciphers, set "smtpd_tls_exclude_ciphers =
-aNULL". To exclude anonymous ciphers only when TLS is enforced, set
-"smtpd_tls_mandatory_exclude_ciphers = aNULL".
+not change.
.IP "\fBnull\fR"
Enable only the "NULL" OpenSSL ciphers, these provide authentication
without encryption. This setting is only appropriate in the rare
case that all clients are prepared to use NULL ciphers (not normally
enabled in TLS clients). The underlying cipherlist is specified via the
tls_null_cipherlist configuration parameter, which you are strongly
-encouraged to not change. The default value of tls_null_cipherlist
-excludes anonymous ciphers (OpenSSL 0.9.8 has NULL ciphers that offer
-data integrity without encryption or authentication).
+encouraged to not change.
+.PP
+Cipher types listed in
+smtpd_tls_mandatory_exclude_ciphers or smtpd_tls_exclude_ciphers are
+excluded from the base definition of the selected cipher grade. See
+smtpd_tls_ciphers for cipher controls that apply to opportunistic
+TLS.
+.PP
+The underlying cipherlists for grades other than "null" include
+anonymous ciphers, but these are automatically filtered out if the
+server is configured to ask for client certificates. You are very
+unlikely to need to take any steps to exclude anonymous ciphers, they
+are excluded automatically as required. If you must exclude anonymous
+ciphers even when Postfix does not need or use peer certificates, set
+"smtpd_tls_exclude_ciphers = aNULL". To exclude anonymous ciphers only
+when TLS is enforced, set "smtpd_tls_mandatory_exclude_ciphers = aNULL".
.PP
This feature is available in Postfix 2.3 and later.
.SH smtpd_tls_mandatory_exclude_ciphers (default: empty)
.PP
Specify a string of the form \fItransport:nexthop\fR, where \fItransport\fR
is the name of a mail delivery transport defined in master.cf.
-The \fI:nexthop\fR part is optional. For more details see the
-\fBtransport\fR(5) manual page.
+The \fI:nexthop\fR destination is optional; its syntax is documented
+in the manual page of the corresponding delivery agent.
.PP
This feature is available in Postfix 2.0 and later.
.SH virtual_uid_maps (default: empty)
\fBre_format\fR(7) with 4.4BSD, in \fBregex\fR(5) with Solaris, and in
\fBregex\fR(7) with Linux. Other systems may use other document names.
-The expression delimiter can be any character, except whitespace
+The expression delimiter can be any non-alphanumerical
+character, except whitespace
or characters that have special meaning (traditionally the forward
slash is used). The regular expression can contain whitespace.
Resolve an address that ends in the "@" null domain as if the
local hostname were specified, instead of rejecting the address as
invalid.
-.IP "\fBsmtpd_command_filter (empty)\fR"
-A mechanism to transform commands from remote SMTP clients.
.IP "\fBsmtpd_reject_unlisted_sender (no)\fR"
Request that the Postfix SMTP server rejects mail from unknown
sender addresses, even when no explicit reject_unlisted_sender
Available in Postfix version 2.6 and later:
.IP "\fBtcp_windowsize (0)\fR"
An optional workaround for routers that break TCP window scaling.
+.PP
+Available in Postfix version 2.7 and later:
+.IP "\fBsmtpd_command_filter (empty)\fR"
+A mechanism to transform commands from remote SMTP clients.
.SH "ADDRESS REWRITING CONTROLS"
.na
.nf
.IP "\fBupdate\fI address status text\fR"
Update the status and text of the specified address.
.IP "\fBquery\fI address\fR"
-Look up the \fIstatus\fR and \fItext\fR for the specified address.
+Look up the \fIstatus\fR and \fItext\fR for the specified
+\fIaddress\fR.
If the status is unknown, a probe is sent and an "in progress"
status is returned.
.SH "SECURITY"
The verify server can run chrooted at fixed low privilege.
The address verification server can be coerced to store
-unlimited amounts of garbage. Limiting the cache size
+unlimited amounts of garbage. Limiting the cache expiry
+time
trades one problem (disk space exhaustion) for another
one (poor response time to client requests).
.SH BUGS
.ad
.fi
-The address verification service is suitable only for sites that
-handle a low mail volume. Verification probes add additional
-traffic to the mail queue and perform poorly under high load.
-Servers may blacklist sites that probe excessively, or that
-probe excessively for non-existent recipient addresses.
+Address verification probe messages add additional traffic
+to the mail queue.
+Recipient verification may cause an increased load on
+down-stream servers in the case of a dictionary attack or
+a flood of backscatter bounces.
+Sender address verification may cause your site to be
+blacklisted by some providers.
If the persistent database ever gets corrupted then the world
comes to an end and human intervention is needed. This violates
.fi
Changes to \fBmain.cf\fR are not picked up automatically,
as \fBverify\fR(8)
-processes are persistent. Use the command "\fBpostfix reload\fR" after
+processes are long-lived. Use the command "\fBpostfix reload\fR" after
a configuration change.
The text below provides only a parameter summary. See
<ul>
-<li><a href="#client_sasl">Enabling SASL authentication in the
+<li><a href="#client_sasl_enable">Enabling SASL authentication in the
Postfix SMTP client</a></li>
-<li><a href="#client_sasl_sender">Supporting multiple ISP accounts
-in the Postfix SMTP client</a></li>
+<li><a href="#client_sasl_sender">Configuring Sender-Dependent SASL
+authentication </a></li>
</ul>
p
}' STANDARD_CONFIGURATION_README.html
-sed -n '/^<h2><a name="client_sasl">/,${
- /^<h2><a name="credits/q
+sed -n '/^<h3><a name="client_sasl_enable"/,${
+ /^<h3><a name="client_sasl_policy"/q
+ s/h3>/h2>/g
p
}' SASL_README.html
s;\bsmtpd_reject_unlisted_recip[-</bB>]*\n* *[<bB>]*ient\b;<a href="postconf.5.html#smtpd_reject_unlisted_recipient">$&</a>;g;
s;\bsmtpd_reject_unlisted_sender\b;<a href="postconf.5.html#smtpd_reject_unlisted_sender">$&</a>;g;
s;\bsmtpd_restriction_classes\b;<a href="postconf.5.html#smtpd_restriction_classes">$&</a>;g;
+ s;\bsmtpd_sasl_application_name\b;<a href="postconf.5.html#smtpd_sasl_application_name">$&</a>;g;
s;\bsmtpd_sasl_path\b;<a href="postconf.5.html#smtpd_sasl_path">$&</a>;g;
s;\bcyrus_sasl_config_path\b;<a href="postconf.5.html#cyrus_sasl_config_path">$&</a>;g;
s;\bsmtpd_sasl_auth_enable\b;<a href="postconf.5.html#smtpd_sasl_auth_enable">$&</a>;g;
<h2>WARNING </h2>
-<p> The sender/recipient address verification feature described in this
-document is suitable only for low-traffic sites. It performs poorly
-under high load; excessive sender address verification activity may
-even cause your site to be blacklisted by some
-providers. See the "<a href="#limitations">Limitations</a>" section
-below for details. </p>
+<p> Recipient address verification may cause an increased load on
+down-stream servers in the case of a dictionary attack or a flood
+of backscatter bounces. Sender address verification may cause your
+site to be blacklisted by some providers. See also the "<a
+href="#limitations">Limitations</a>" section below for more. </p>
<h2><a name="summary">What Postfix address verification can do for you</a></h2>
<p> The technique has obvious uses to reject junk mail
with an unreplyable sender address. </p>
-<p> The technique may also be useful to block mail for undeliverable
+<p> The technique is also useful to block mail for undeliverable
recipients, for example on a mail relay host that does not have a
list of all the valid recipient addresses. This prevents undeliverable
junk mail from entering the queue, so that Postfix doesn't have to
<blockquote>
-<table>
+<table border="0">
<tr>
- <td bgcolor="#f0f0ff" align="center" valign="middle"> Internet
+ <td rowspan="2" colspan="5" align="center" valign="middle">
+ </td>
+
+ <td rowspan="3" align="center" valign="bottom"> <tt> -> </tt>
</td>
- <td align="center" valign="middle"> <tt> -> </tt> </td>
+ <td rowspan="3" align="center" valign="middle"> probe<br>
+ message </td>
- <td bgcolor="#f0f0ff" align="center" valign="middle"> <a
- href="smtpd.8.html">Postfix<br> SMTP<br> server</a> </td>
+ <td rowspan="3" align="center" valign="middle"> <tt> -> </tt>
+ </td>
- <td colspan="2" align="center" valign="middle"> <tt> <->
- </tt> </td>
+ <td rowspan="3" bgcolor="#f0f0ff" align="center" valign="middle">
+ Postfix<br> mail<br> queue </td>
- <td bgcolor="#f0f0ff" colspan="3" align="center" valign="middle">
- <a href="verify.8.html">Postfix<br> verify<br> server</a>
- </td>
+</tr>
+
+<tr> </tr>
+
+<tr>
+
+ <td rowspan="3" align="center" valign="middle"> Internet </td>
+
+ <td rowspan="3" align="center" valign="middle"> <tt> -> </tt>
+ </td>
+
+ <td rowspan="3" bgcolor="#f0f0ff" align="center" valign="middle">
+ <a href="smtpd.8.html">Postfix<br> SMTP<br> server</a> </td>
- <td colspan="2" align="center" valign="middle"> <tt> <->
+ <td rowspan="3" align="center" valign="middle"> <tt> <->
</tt> </td>
- <td bgcolor="#f0f0ff" align="center" valign="middle"> Address<br>
- verification<br> database </td>
+ <td rowspan="3" bgcolor="#f0f0ff" align="center" valign="middle">
+ <a href="verify.8.html">Postfix<br> verify<br> server</a>
+ </td>
</tr>
<tr>
- <td colspan="3"> </td>
+ <td rowspan="1" colspan="3"> </td>
- <td> </td>
+ <td rowspan="1" align="center" valign="middle"> <tt> |</tt><br>
+ <tt> v</tt> </td>
- <td colspan="2" align="right" valign="middle"> <tt> |</tt><br>
- probe<br> messages<br> <tt> v </tt> </td>
+</tr>
- <td> </td>
+<tr>
- <td colspan="2" align="left" valign="middle"> ^<br> delivery<br>
- status<br> <tt> | </tt> </td>
+ <td rowspan="3" align="center" valign="top"> <tt> <- </tt>
+ </td>
+
+ <td rowspan="3" align="center" valign="middle"> probe<br>
+ status </td>
- <td> </td>
+ <td rowspan="3" align="center" valign="middle"> <tt> <- </tt>
+ </td>
- <td> </td>
+ <td rowspan="3" bgcolor="#f0f0ff" align="center" valign="middle">
+ Postfix<br> delivery<br> agents </td>
+
+ <td rowspan="3" align="left" valign="middle"> <tt>-></tt>
+ Local<br> <tt>-></tt> Remote</td>
</tr>
<tr>
- <td> </td>
-
- <td> </td>
+ <td rowspan="3" colspan="4" align="center" valign="middle">
+ </td>
- <td> </td>
+ <td rowspan="3" align="center" valign="middle"> <tt>
+ ^</tt><br> <tt> |</tt><br> <tt> v</tt> </td>
- <td> </td>
+</tr>
- <td colspan="2" bgcolor="#f0f0ff" align="center" valign="middle">
- Postfix<br> queue </td>
+<tr> </tr>
- <td align="center" valign="middle"> <tt> -> </tt> </td>
+<tr> <td colspan="4"> </td> </tr>
- <td colspan="2" bgcolor="#f0f0ff" align="center" valign="middle">
- Postfix<br> delivery<br> agents </td>
+<tr>
- <td> </td>
+ <td colspan="4" align="center" valign="middle"> </td>
- <td> </td>
+ <td bgcolor="#f0f0ff" align="center" valign="middle">
+ Address<br> verification<br> database </td>
</tr>
MTA for that address, without actually delivering mail to it. If
the nearest MTA accepts the address, then Postfix assumes that the
address is deliverable. In reality, mail for a remote address can
-bounce AFTER the nearest MTA accepts the recipient address. </p>
+bounce AFTER the nearest MTA accepts the recipient address, or AFTER
+the nearest MTA accepts the message content. </p>
<li> <p> Some sites may blacklist you when you are probing them
too often (a probe is an SMTP session that does not deliver mail),
<li> <p> Postfix assumes that an address is undeliverable when the
nearest MTA for the address rejects the probe, regardless of the
reason for rejection (client rejected, HELO rejected, MAIL FROM
-rejected, etc.). Thus, Postfix rejects mail when the sender's MTA
-rejects mail from your machine. This is a good thing. </p>
+rejected, etc.). Thus, Postfix rejects an address when the nearest
+MTA for that address rejects mail from your machine for any reason.
+This is not a limitation, but it is mentioned here just in case
+people believe that it is a limitation. </p>
-<li> <p> Unfortunately, some major sites such as YAHOO do not reject
+<li> <p> Unfortunately, some sites do not reject
unknown addresses in reply to the RCPT TO command, but report a
delivery failure in response to end of DATA after a message is
transferred. Postfix address verification does not work with such
sites. </p>
-<li> <p> By default, Postfix probe messages have "double-bounce@$myorigin"
-as the sender address (with Postfix versions before 2.5, the default
+<li> <p> By default, Postfix probe messages have a sender address
+"double-bounce@$myorigin" (with Postfix versions before 2.5, the
+default
is "postmaster@$myorigin"). This is SAFE because the Postfix SMTP
server does not reject mail for this address. </p>
-<p> You can change this into the null address ("address_verify_sender
+<p> You can change the probe sender address into the null address
+("address_verify_sender
="). This is UNSAFE because address probes will fail with
mis-configured sites that reject MAIL FROM: <>, while
probes from "postmaster@$myorigin" would succeed. </p>
<h2><a name="recipient">Recipient address verification</a></h2>
-<p> As mentioned earlier, recipient address verification may be
+<p> As mentioned earlier, recipient address verification is
useful to block mail for undeliverable recipients on a mail relay
host that does not have a list of all valid recipient addresses.
This can help to prevent the mail queue from filling up with
load on down-stream MTAs when you're being flooded by backscatter
bounces, or when some spammer is mounting a dictionary attack. </p>
-<p> By default, address verification results are not saved. To avoid
-probing the same address repeatedly, you can store the result in a
-<a href="#caching">persistent database</a> as described later. </p>
+<p> By default, address verification results are saved in a <a
+href="#caching">persistent database</a> (Postfix version 2.7 and
+later; with earlier versions, specify the database in main.cf as
+described later). The persistent database helps to avoid probing
+the same address repeatedly. </p>
<blockquote>
<pre>
# Postfix 2.6 and later.
# unverified_sender_defer_code = 250
+ # Default setting for Postfix 2.7 and later.
# Note 1: Be sure to read the "<a href="#caching">Caching</a>" section below!
# Note 2: Avoid hash files here. Use btree instead.
address_verify_map = btree:/var/lib/postfix/verify
/etc/postfix/sender_access:
+ # Don't do this when you handle lots of email.
aol.com reject_unverified_sender
hotmail.com reject_unverified_sender
bigfoot.com reject_unverified_sender
# Postfix 2.6 and later.
# unverified_sender_reject_reason = Address verification failed
+ # Default setting for Postfix 2.7 and later.
# Note 1: Be sure to read the "<a href="#caching">Caching</a>" section below!
# Note 2: Avoid hash files here. Use btree instead.
address_verify_map = btree:/var/lib/postfix/verify
<h2><a name="caching">Address verification database</a></h2>
<p> To improve performance, the Postfix verify(8) daemon can save
-address verification results to a persistent database. The
+address verification results to a persistent database. This is
+enabled by default with Postfix 2.7 and later. The
address_verify_map (NOTE: singular) configuration parameter specifies
persistent storage for sender or recipient address verification
results. If you specify an empty value, all address verification
<li> <p> The verify(8) server verifies that a sender or recipient
address is deliverable before the smtpd(8) server accepts it. The
-verify(8) server injects probe messages into the Postfix queue and
-processes status updates from delivery agents and/or queue manager.
+verify(8) server queries a cache with address verification results.
+If a result is not found, the verify(8) server injects a probe
+message into the Postfix queue and processes the status update from
+a delivery agent or queue manager.
This process is described in the ADDRESS_VERIFICATION_README
document. The verify(8) service is available with Postfix version
2.1 and later. </p>
<table>
-<tr> <td> Network </td> <td> <tt> -> </tt> </td> <td align="center"
-bgcolor="#f0f0ff"> smtpd(8) </td> <td> <tt> <-> </tt> </td>
-<td align="center" bgcolor="#f0f0ff"> verify(8) </td> <td> <tt>
--> </tt> </td> <td align="center" bgcolor="#f0f0ff"> cleanup(8)
-</td> <td> <tt> -> </tt> </td> <td align="center" bgcolor="#f0f0ff">
-qmgr(8)<br> Postfix <br>queue </td> <td> <tt> -> </tt> </td>
-<td align="center" bgcolor="#f0f0ff"> Delivery<br> agents</td>
+<tr>
+
+ <td rowspan="2" colspan="5" align="center" valign="middle">
+ </td> <td rowspan="3" align="center" valign="bottom">
+ <tt> -> </tt> </td> <td rowspan="3" align="center"
+ valign="middle"> probe<br> message </td> <td rowspan="3"
+ align="center" valign="middle"> <tt> -> </tt> </td> <td
+ rowspan="3" bgcolor="#f0f0ff" align="center" valign="middle">
+ Postfix<br> mail<br> queue </td>
+
</tr>
-<tr> <td colspan="5"> </td> <td align="right"> <table> <tr> <td>
-\ </td> <td> </td> </tr> <tr> <td> </td> <td> \ </td> </tr> </table>
-</td> <td align="center" valign="bottom"> <tt> <- </tt> </td>
-<td valign="bottom"> <tt> <- </tt> </td> <td align="center">
-<tt> |<br> v </tt> </td> <td align="center"> <table> <tr> <td>
-</td> <td> / </td> </tr> <tr> <td> / </td> <td> </td> </tr> </table>
+<tr> </tr>
+
+<tr>
+
+ <td rowspan="3" align="center" valign="middle"> Network </td>
+ <td rowspan="3" align="center" valign="middle"> <tt> -> </tt>
+ </td> <td rowspan="3" bgcolor="#f0f0ff" align="center"
+ valign="middle"> smtpd(8) </td> <td rowspan="3" align="center"
+ valign="middle"> <tt> <-> </tt> </td> <td rowspan="3"
+ bgcolor="#f0f0ff" align="center" valign="middle"> verify(8)
+ </td>
+
+</tr>
+
+<tr>
+
+ <td rowspan="1" colspan="3"> </td> <td rowspan="1" align="center"
+ valign="middle"> <tt> |</tt><br> <tt> v</tt> </td>
+
+</tr>
+
+<tr>
+
+ <td rowspan="3" align="center" valign="top"> <tt> <- </tt>
+ </td> <td rowspan="3" align="center" valign="middle"> probe<br>
+ status </td> <td rowspan="3" align="center" valign="middle">
+ <tt> <- </tt> </td> <td rowspan="3" bgcolor="#f0f0ff"
+ align="center" valign="middle"> Postfix<br> delivery<br> agents
+ </td> <td rowspan="3" align="left" valign="middle"> <tt>-></tt>
+ Local<br> <tt>-></tt> Network</td>
+
+</tr>
+
+<tr>
+
+ <td rowspan="3" colspan="4" align="center" valign="middle">
+ </td> <td rowspan="3" align="center" valign="middle">
+ <tt> ^</tt><br> <tt> |</tt><br> <tt> v</tt> </td>
+
+</tr>
+
+<tr> </tr>
+
+<tr> <td colspan="4"> </td> </tr>
+
+<tr>
+
+ <td colspan="4" align="center" valign="middle"> </td>
+ <td bgcolor="#f0f0ff" align="center" valign="middle"> Address<br>
+ verification<br> cache </td>
+
+</tr>
+
+</table>
+
+<li> <p> The postscreen(8) server can be put "in front" of Postfix
+smtpd(8) processes. Its purpose is to accept connections from the
+network and to decide what SMTP clients are allowed to talk to
+Postfix. According to the 2008 MessageLabs annual report, 81% of
+all email was spam, and 90% of that was sent by botnets. While
+postscreen(8) keeps the zombies away, more smtpd(8) processes remain
+available for legitimate clients. </p>
+
+<p> The postscreen(8) server is still evolving, and is likely to
+undergo changes that break compatibility with earlier versions.
+For this reason the postscreen(8) server is not installed with the
+stable Postfix release. </p>
+
+<table>
+
+<tr> <td> zombie </td> </tr>
+
+<tr> <td> </td> <td align="left"> <tt> \ </tt> </td> </tr>
+
+<tr> <td> zombie </td> <td align="left"> <tt> - </tt> </td> <td>
+</td> <td> </td> <td> </td> <td align="right"> <tt> - </tt> </td>
+<td bgcolor="#f0f0ff" align="center"> smtpd(8) </td> </tr>
+
+<tr> <td> </td> <td align="right"> <tt> \ </tt> </td> <td> </td>
+<td align="left"> <tt> / </tt> </td> </tr>
+
+<tr> <td bgcolor="#f0f0ff" align="center"> other </td> <td> <tt>
+--- </tt> </td> <td bgcolor="#f0f0ff" align="center" valign="middle">
+postscreen(8) </td> </tr>
+
+<tr> <td> </td> <td align="right"> <tt> / </tt> </td> <td> </td>
+<td align="right"> <tt> \ </tt> </td> </tr>
+
+<tr> <td bgcolor="#f0f0ff" align="center"> other </td> <td align="left">
+<tt> - </tt> </td> <td> </td> <td> </td> <td> </td> <td align="right">
+<tt> - </tt> </td> <td bgcolor="#f0f0ff" align="center"> smtpd(8)
</td> </tr>
+<tr> <td> </td> <td align="left"> <tt> / </tt> </td> </tr>
+
+<tr> <td> zombie </td> </tr>
+
+
</table>
</ul>
<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
"http://www.w3.org/TR/html4/loose.dtd">
-<html>
-
<head>
<title>Postfix SASL Howto</title>
<hr>
-<h2>WARNING</h2>
+<h2>Warning</h2>
<p> People who go to the trouble of installing Postfix may have the
expectation that Postfix is more secure than some other mailers.
-The Cyrus SASL library is a lot of code. With this, Postfix becomes
-as secure as other mail systems that use the Cyrus SASL library.
-Dovecot provides an alternative that may be worth considering.
-</p>
+The Cyrus SASL library contains a lot of code. With this, Postfix
+becomes as secure as other mail systems that use the Cyrus SASL
+library. Dovecot provides an alternative that may be worth
+considering. </p>
+
+<h2><a name="intro">How Postfix uses SASL authentication</a></h2>
+
+<p> When an SMTP client connects to an SMTP server, the server needs
+to decide whether that client is authorized to send mail to remote
+destinations, or whether the client can send mail only to the
+destinations that the server itself is responsible for. Usually,
+the SMTP server will allow mail to remote destinations only if the
+client's IP address is in the "same network" as the server's IP
+address. </p>
+
+<p> Sometimes the SMTP client and server are in different networks,
+but the client still needs "same network" privileges. To address
+this problem, Postfix supports SASL authentication (RFC 4954,
+formerly RFC 2554). With this a remote SMTP client can authenticate
+to the Postfix SMTP server, and the Postfix SMTP client can
+authenticate to a remote SMTP server. Once the client is authenticated
+the server can give it "same network" privileges. </p>
+
+<p> Postfix does not implement SASL itself, but instead uses existing
+implementations as building blocks. This means that some SASL-related
+configuration will involve files that belong to Postfix, while other
+configuration will involve files that belong to the specific SASL
+implementation that Postfix will use. This document covers both the
+Postfix and non-Postfix configuration. </p>
+
+<p> You can read more about the following topics: </p>
-<h2><a name="intro">How Postfix uses SASL authentication information</a></h2>
+<ul>
-<p> Postfix SASL support (RFC 4954, formerly RFC 2554) can be used
-to authenticate
-remote SMTP clients to the Postfix SMTP server, and to authenticate
-the Postfix SMTP client to a remote SMTP server. </p>
+<li><a href="#server_sasl">Configuring SASL authentication in the
+Postfix SMTP server</a></li>
-<p> When receiving mail, the Postfix SMTP server logs the client-provided
-username,
-authentication method, and sender address to the maillog file, and
-optionally grants mail access via the permit_sasl_authenticated
-UCE restriction. </p>
+<li><a href="#client_sasl">Configuring SASL authentication in the Postfix SMTP/LMTP client</a></li>
-<p> When sending mail, the Postfix SMTP client can look up the
-remote SMTP server hostname or
-destination domain (the address right-hand part) in a SASL password
-table, and if a username/password is found, it will use that username
-and password to authenticate to the remote SMTP server. And as of
-version 2.3,
-Postfix can be configured to search its SASL password table by the
-sender email address. </p>
+<li><a href="#postfix_build">Building Postfix with SASL support</a></li>
-<p>This document covers the following topics: </p>
+<li><a href="#cyrus_legacy">Using Cyrus SASL version 1.5.x</a></li>
-<ul>
+<li><a href="#credits">Credits</a></li>
-<li><a href="#versions">What SASL implementations are supported</a>
+</ul>
-<li><a href="#build_dovecot">Building Postfix with Dovecot SASL
-support</a></li>
+<h2><a name="server_sasl">Configuring SASL authentication in the
+Postfix SMTP server</a></h2>
-<li><a href="#build_sasl">Building the Cyrus SASL library</a>
+<p> As mentioned earlier, SASL is implemented separately from
+Postfix. For this reason, configuring SASL authentication in the
+Postfix SMTP server involves two different steps: </p>
-<li><a href="#build_postfix">Building Postfix with Cyrus SASL
-support</a></li>
+<ul>
-<li><a href="#server_sasl">Enabling SASL authentication in the
-Postfix SMTP server</a></li>
+<li> <p> Configuring the SASL implementation to offer a list of
+mechanisms that are suitable for SASL authentication and, depending
+on the SASL implementation used, configuring authentication backends
+that verify the remote SMTP client's authentication data against
+the system password file or some other database. </p> </li>
-<li><a href="#server_dovecot">Dovecot SASL configuration for the Postfix
-SMTP server</a></li>
+<li> <p> Configuring the Postfix SMTP server to enable SASL
+authentication, and to authorize clients to relay mail or to control
+what envelope sender addresses the client may use. </p> </li>
-<li><a href="#server_cyrus">Cyrus SASL configuration for the Postfix
-SMTP server</a></li>
+</ul>
-<li><a href="#server_test">Testing SASL authentication in the
-Postfix SMTP server</a></li>
+<p> Successful authentication in the Postfix SMTP server requires
+a functional SASL framework. Configuring SASL should therefore
+always be the first step. </p>
-<li><a href="#debugging">Trouble shooting the SASL internals</a>
+<p> You can read more about the following topics: </p>
-<li><a href="#client_sasl">Enabling SASL authentication in the
-Postfix SMTP client</a></li>
+<ul>
-<li><a href="#client_sasl_sender">Supporting multiple ISP accounts
-in the Postfix SMTP client</a></li>
+<li><a href="#server_which">Which SASL Implementations are
+supported?</a></li>
-<li><a href="#credits">Credits</a>
+<li><a href="#server_dovecot">Configuring Dovecot SASL</a>
-</ul>
+<ul>
-<h2><a name="versions">What SASL implementations are supported</a></h2>
+<li><a href="#server_dovecot_comm">Postfix to Dovecot SASL
+communication</a></li>
-<p> This document describes Postfix with the following SASL
-implementations: </p>
+</ul> </li>
+
+<li><a href="#server_cyrus">Configuring Cyrus SASL</a>
<ul>
-<li> <p> Cyrus SASL version 1 (client and server). </p>
+<li><a href="#server_cyrus_name">Cyrus SASL configuration file
+name</a></li>
-<li> <p> Cyrus SASL version 2 (client and server). </p>
+<li><a href="#server_cyrus_location">Cyrus SASL configuration
+file location</a></li>
-<li> <p> Dovecot protocol version 1 (server only, Postfix version
-2.3 and later) </p>
+<li><a href="#server_cyrus_comm">Postfix to Cyrus SASL
+communication</a></li>
-</ul>
+</ul> </li>
-<p> Postfix version 2.3 introduces a plug-in mechanism that provides
-support for multiple SASL implementations. To find out what
-implementations are built into Postfix, use the following commands:
-</p>
+<li><a href="#server_sasl_enable">Enabling SASL authentication and
+authorization in the Postfix SMTP server</a>
-<blockquote>
-<pre>
-% postconf -a (SASL support in the SMTP server)
-% postconf -A (SASL support in the SMTP+LMTP client)
-</pre>
-</blockquote>
+<ul>
-<p> Needless to say, these commands are not available in earlier
-Postfix versions. </p>
+<li><a href="#server_sasl_authc">Enabling SASL authentication in
+the Postfix SMTP server</a></li>
-<h2><a name="build_dovecot">Building Postfix with Dovecot SASL
-support</a></h2>
+<li><a href="#smtpd_sasl_security_options">Postfix SMTP Server
+Authentication Policy</a></li>
-<p> These instructions assume that you build Postfix from source
-code as described in the INSTALL document. Some modification may
-be required if you build Postfix from a vendor-specific source
-package. </p>
+<li><a href="#server_sasl_authz">Enabling SASL authorization in the Postfix
+SMTP server</a></li>
-<p> Support for the Dovecot version 1 SASL protocol is available
-in Postfix 2.3 and later. At the time
-of writing, only server-side SASL support is available, so you can't
-use it to authenticate to your network provider's server. Dovecot
-uses its own daemon process for authentication. This keeps the
-Postfix build process simple, because there is no need to link extra
-libraries into Postfix. </p>
+<li><a href="#server_sasl_other">Additional SMTP Server SASL options</a></li>
-<p> To generate the necessary Makefiles, execute the following
-in the Postfix top-level directory: </p>
+</ul></li>
-<blockquote>
-<pre>
-% make makefiles CCARGS='-DUSE_SASL_AUTH -DDEF_SERVER_SASL_TYPE=\"dovecot\"'
-</pre>
-</blockquote>
+<li><a href="#server_test">Testing SASL authentication in the Postfix
+SMTP server</a></li>
+
+</ul>
-<p> After this, proceed with "<tt>make</tt>" as described in the
-INSTALL document. </p>
-<p> Notes: </p>
+<h3><a name="server_which">Which SASL Implementations are supported?</a></h3>
-<ul>
+<p> Currently the Postfix SMTP server supports the Cyrus SASL and
+Dovecot SASL implementations. </p>
-<li> <p> The "-DDEF_SERVER_SASL_TYPE" stuff is not necessary; it just
-makes Postfix configuration a little more convenient because you
-don't have to specify the SASL plug-in type in the Postfix main.cf
-file. </p>
+<blockquote>
-<li> <p> If you also want support for LDAP or TLS, you will have to merge
-their CCARGS and AUXLIBS into the above command line. </p>
+<strong>Note</strong>
-</ul>
+<p> Before Postfix version 2.3, Postfix had support only for Cyrus
+SASL. Current Postfix versions have a plug-in architecture that
+can support multiple SASL implementations. </p>
-<h2><a name="build_sasl">Building the Cyrus SASL library</a></h2>
+</blockquote>
-<p> Postfix appears to work with cyrus-sasl-1.5.x or cyrus-sasl-2.1.x,
-which are available from: </p>
+<p> To find out what SASL implementations are compiled into Postfix,
+use the following commands: </p>
<blockquote>
<pre>
-ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/
+% <strong><code>postconf -a</code></strong> (SASL support in the SMTP server)
+% <strong><code>postconf -A</code></strong> (SASL support in the SMTP+LMTP client)
</pre>
</blockquote>
-<p> IMPORTANT: if you install the Cyrus SASL libraries as per the
-default, you will have to symlink /usr/lib/sasl -> /usr/local/lib/sasl
-for version 1.5.x or /usr/lib/sasl2 -> /usr/local/lib/sasl2 for
-version 2.1.x. </p>
-
-<p> Reportedly, Microsoft Outlook (Express) requires the
-non-standard LOGIN authentication method. To enable this
-authentication method, specify ``./configure --enable-login''. </p>
+<p> These commands are available only with Postfix version 2.3 and
+later. </p>
-<h2><a name="build_postfix">Building Postfix with Cyrus SASL support</a></h2>
+<h3><a name="server_dovecot">Configuring Dovecot SASL</a></h3>
-<p> These instructions assume that you build Postfix from source
-code as described in the INSTALL document. Some modification may
-be required if you build Postfix from a vendor-specific source
-package. </p>
+<p> Dovecot is a POP/IMAP server that must be configured to
+authenticate POP/IMAP clients. When the Postfix SMTP server uses
+Dovecot SASL, it also reuses this configuration. Consult the <a
+href="http://wiki.dovecot.org">Dovecot documentation</a> for how
+to configure and operate the Dovecot authentication server. </p>
-<p> The following
-assumes that the Cyrus SASL include files are in /usr/local/include,
-and that the Cyrus SASL libraries are in /usr/local/lib. </p>
+<h4><a name="server_dovecot_comm">Postfix to Dovecot SASL communication</a></h4>
-<p> On some systems this generates the necessary Makefile definitions:
+<p> Communication between the Postfix SMTP server
+and Dovecot SASL happens via a UNIX-domain socket. The socket
+pathname and the list of mechanisms offered to Postfix need to be
+specified on the Dovecot server side in <code>dovecot.conf</code>.
</p>
-<dl>
-
-<dt> (for Cyrus SASL version 1.5.x):
-<dd>
-<pre>
-% make tidy # if you have left-over files from a previous build
-% make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
- -I/usr/local/include" AUXLIBS="-L/usr/local/lib -lsasl"
-</pre>
+<p> The following example assumes that the Postfix queue is under
+<code>/var/spool/postfix/</code>. </p>
-<dt> (for Cyrus SASL version 2.1.x):
-<dd>
+<blockquote>
<pre>
-% make tidy # if you have left-over files from a previous build
-% make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
- -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib -lsasl2"
+ 1 /etc/dovecot.conf:
+ 2 auth default {
+ 3 mechanisms = plain login
+ 4 passdb pam {
+ 5 }
+ 6 userdb passwd {
+ 7 }
+ 8 socket listen {
+ 9 client {
+10 path = /var/spool/postfix/private/auth
+11 mode = 0660
+12 user = postfix
+13 group = postfix
+14 }
+15 }
+16 }
</pre>
+</blockquote>
-</dl>
+<p> Line 3 provides <code>plain</code> and <code>login</code> as
+mechanisms for the Postfix SMTP server, line 10 places the Dovecot
+SASL socket in <code>/var/spool/postfix/private/auth</code>, and
+lines 11-13 limit read+write permissions to user and group
+<code>postfix</code> only. </p>
-<p> On Solaris 2.x you need to specify run-time link information,
-otherwise ld.so will not find the SASL shared library: </p>
+<p> Proceed with the section "<a href="#server_sasl_enable"
+title="Enabling SASL authentication and configuring authorization
+in the Postfix SMTP server">Enabling SASL authentication and
+authorization in the Postfix SMTP server</a>" to turn on and use
+SASL in the Postfix SMTP server. </p>
-<dl>
+<h3><a name="server_cyrus">Configuring Cyrus SASL</a></h3>
-<dt> (for Cyrus SASL version 1.5.x):
-<dd>
-<pre>
-% make tidy # if you have left-over files from a previous build
-% make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
- -I/usr/local/include" AUXLIBS="-L/usr/local/lib \
- -R/usr/local/lib -lsasl"
-</pre>
+<p> The Cyrus SASL framework was supports a wide variety of
+applications. Different applications may require different
+configurations. As a consequence each application may have its own
+configuration file. </p>
-<dt> (for Cyrus SASL version 2.1.x):
-<dd>
-<pre>
-% make tidy # if you have left-over files from a previous build
-% make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
- -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib \
- -R/usr/local/lib -lsasl2"
-</pre>
+<p> The first step configuring Cyrus SASL is to determine name and
+location of a configuration file that describes how the Postfix
+SMTP server will use the SASL framework. </p>
-</dl>
+<h4><a name="server_cyrus_name">Cyrus SASL configuration file name</a></h4>
-<h2><a name="server_sasl">Enabling SASL authentication in the Postfix
-SMTP server</a></h2>
+<p> The name of the configuration file (default: <code>smtpd.conf</code>)
+is configurable. It is a concatenation from a value that the Postfix
+SMTP server sends to the Cyrus SASL library, and the suffix
+<code>.conf</code>, added by Cyrus SASL. </p>
-<p> In order to enable SASL support in the Postfix SMTP server: </p>
+<p> The value sent by Postfix is the name of the server component
+that will use Cyrus SASL. It defaults to <code>smtpd</code> and
+is configured with one of the following variables: </p>
<blockquote>
<pre>
/etc/postfix/main.cf:
- smtpd_sasl_auth_enable = yes
-</pre>
-</blockquote>
-
-<p> In order to allow mail relaying by authenticated remote SMTP
-clients: </p>
+ # Postfix 2.3 and later
+ smtpd_sasl_path = smtpd
-<blockquote>
-<pre>
-/etc/postfix/main.cf:
- smtpd_recipient_restrictions =
- permit_mynetworks
- permit_sasl_authenticated
- reject_unauth_destination
+ # Postfix < 2.3
+ smtpd_sasl_application_name = smtpd
</pre>
</blockquote>
-<p> To report SASL login names in Received: message headers
-(Postfix version 2.3 and later): </p>
+<h4><a name="server_cyrus_location">Cyrus SASL configuration file
+location</a></h4>
-<blockquote>
-<pre>
-/etc/postfix/main.cf:
- smtpd_sasl_authenticated_header = yes
-</pre>
-</blockquote>
+<p> The location where Cyrus SASL searches for the named file depends
+on the Cyrus SASL version and the OS/distribution used. </p>
-<p> Note: the SASL login names will be shared with the entire world.
-</p>
+<p> You can read more about the following topics: </p>
-<p> Older Microsoft SMTP client software implements a non-standard
-version of the AUTH protocol syntax, and expects that the SMTP
-server replies to EHLO with "250 AUTH=mechanism-list" instead of
-"250 AUTH mechanism-list". To accommodate such clients (in addition
-to conformant
-clients) use the following: </p>
+<ul>
-<blockquote>
-<pre>
-/etc/postfix/main.cf:
- broken_sasl_auth_clients = yes
-</pre>
-</blockquote>
+<li> <p> Cyrus SASL version 2.x searches for the configuration file
+in <code>/usr/lib/sasl2/</code>. </p> </li>
-<h2><a name="server_dovecot">Dovecot SASL configuration for the
-Postfix SMTP server</a></h2>
+<li> <p> Cyrus SASL version 2.1.22 and newer additionally search
+in <code>/etc/sasl2/</code>. </p> </li>
+
+<li> <p> Some Postfix distributions are modified and look for the
+Cyrus SASL configuration file in <code>/etc/postfix/sasl/</code>,
+<code>/var/lib/sasl2/</code> etc. See the distribution-specific
+documentation to determine the expected location. </p> </li>
-<p> Dovecot SASL support is available in Postfix 2.3 and later. On
-the Postfix side you need to specify the location of the
-Dovecot authentication daemon socket. We use a pathname relative
-to the Postfix queue directory, so that it will work whether or not
-the Postfix SMTP server runs chrooted: </p>
+</ul>
<blockquote>
-<pre>
-/etc/postfix/main.cf:
- smtpd_sasl_type = dovecot
- smtpd_sasl_path = private/auth
-</pre>
-</blockquote>
-<p> On the Dovecot side you also need to specify the Dovecot
-authentication daemon socket. In this case we specify an
-absolute pathname. In the example we assume that the
-Postfix queue is under /var/spool/postfix/. </p>
+<strong>Note</strong>
+
+<p> Cyrus SASL searches <code>/usr/lib/sasl2/</code> first. If it
+finds the specified configuration file there, it will not examine
+other locations. </p>
-<blockquote>
-<pre>
-/some/where/dovecot.conf:
- auth default {
- mechanisms = plain login
- passdb pam {
- }
- userdb passwd {
- }
- socket listen {
- client {
- path = /var/spool/postfix/private/auth
- mode = 0660
- user = postfix
- group = postfix
- }
- }
- }
-</pre>
</blockquote>
-<p> See the Dovecot documentation for how to configure and operate
-the Dovecot authentication server. </p>
+<h4><a name="server_cyrus_comm">Postfix to Cyrus SASL communication</a></h4>
-<h2><a name="server_cyrus">Cyrus SASL configuration for the Postfix
-SMTP server</a></h2>
+<p> As the Postfix SMTP server is linked with the Cyrus SASL library
+<code>libsasl</code>, communication between Postfix and Cyrus SASL
+takes place by calling functions in the SASL library. </p>
-<p> You need to configure how the Cyrus SASL library should
-authenticate a remote SMTP client's username and password. These
-settings must
-be stored in a separate configuration file. </p>
+<p> The SASL library may use an external password verification
+service, or an internal plugin to connect to authentication backends
+and verify the SMTP client's authentication data against the system
+password file or other databases. </p>
-<p> The name of the configuration file (default: smtpd.conf) will
-be constructed from a value that the Postfix SMTP server sends to
-the Cyrus SASL
-library, which adds the suffix .conf. The value is configured using
-one of the following variables: </p>
+<p> The following table shows typical combinations discussed in
+this document: </p>
<blockquote>
-<pre>
-/etc/postfix/main.cf:
- # Postfix 2.3 and later
- smtpd_sasl_path = smtpd
- # Postfix < 2.3
- smtpd_sasl_application_name = smtpd
-</pre>
-</blockquote>
-<p> Cyrus SASL searches for the configuration file in /usr/local/lib/sasl/
-(Cyrus SASL version 1.5.5) or /usr/local/lib/sasl2/ (Cyrus SASL
-version 2.1.x). </p>
+<table border="1">
-<p> Note: some Postfix distributions are modified and look for
-the smtpd.conf file in /etc/postfix/sasl. </p>
+<tr>
-<p> Note: some Cyrus SASL distributions look for the smtpd.conf
-file in /etc/sasl2. </p>
+<th align="center">authentication backend</th>
-<ul>
+<th align="center">password verification service / plugin</th>
-<li> <p> To authenticate against the UNIX password database, use: </p>
+</tr>
-<dl>
-<dt> (Cyrus SASL version 1.5.x)
-<dd>
-<pre>
-/usr/local/lib/sasl/smtpd.conf:
- pwcheck_method: pwcheck
+<tr>
-</pre>
+<td>/etc/shadow</td>
-<p> IMPORTANT: pwcheck establishes a UNIX domain socket in /var/pwcheck
-and waits for authentication requests. The Postfix SMTP server must have
-read+execute permission to this directory or authentication attempts
-will fail. </p>
+<td><a href="#saslauthd">saslauthd</a></td>
-<p> The pwcheck daemon is contained in the cyrus-sasl source tarball. </p>
+</tr>
-<dt> (Cyrus SASL version 1.5.26)
-<dd>
-<pre>
-/usr/local/lib/sasl/smtpd.conf:
- pwcheck_method: saslauthd
-</pre>
+<tr>
-<dt> (Cyrus SASL version 2.1.x)
-<dd>
-<pre>
-/usr/local/lib/sasl2/smtpd.conf:
- pwcheck_method: saslauthd
- mech_list: PLAIN LOGIN
-</pre>
+<td>PAM</td>
-</dl>
+<td><a href="#saslauthd">saslauthd</a></td>
-<p> The saslauthd daemon is also contained in the cyrus-sasl source
-tarball. It is more flexible than the pwcheck daemon, in that it
-can authenticate against PAM and various other sources. To use PAM,
-start saslauthd with "-a pam". </p>
+</tr>
-<p> IMPORTANT: saslauthd usually establishes a UNIX domain socket
-in /var/run/saslauthd and waits for authentication requests. The Postfix
-SMTP server must have read+execute permission to this directory or
-authentication attempts will fail. </p>
+<tr>
-<p> Note: The directory where saslauthd puts the socket is configurable.
-See the command-line option "-m /path/to/socket" in the saslauthd
---help listing. </p>
+<td>IMAP server</td>
-<li> <p> To authenticate against Cyrus SASL's own password database: </p>
+<td><a href="#saslauthd">saslauthd</a></td>
-<dl>
-<dt> (Cyrus SASL version 1.5.x)
-<dd>
-<pre>
-/usr/local/lib/sasl/smtpd.conf:
- pwcheck_method: sasldb
-</pre>
+</tr>
-<dt> (Cyrus SASL version 2.1.x)
-<dd>
-<pre>
-/usr/local/lib/sasl2/smtpd.conf:
- pwcheck_method: auxprop
- auxprop_plugin: sasldb
- mech_list: PLAIN LOGIN CRAM-MD5 DIGEST-MD5
-</pre>
+<tr>
-</dl>
+<td>sasldb</td>
-<p> This will use the Cyrus SASL password file (default: /etc/sasldb in
-version 1.5.x, or /etc/sasldb2 in version 2.1.x), which is maintained
-with the saslpasswd or saslpasswd2 command (part of the Cyrus SASL
-software). On some poorly-supported systems the saslpasswd command needs
-to be run multiple times before it stops complaining. The Postfix SMTP
-server needs read access to the sasldb file - you may have to play games
-with group access permissions. With the OTP authentication mechanism,
-the Postfix SMTP server also needs WRITE access to /etc/sasldb2 or
-/etc/sasldb
-(or the back end SQL database, if used). </p>
+<td><a href="#auxprop_sasldb">sasldb</a></td>
-<p> IMPORTANT: To get sasldb running, make sure that you set the SASL
-domain (realm) to a fully qualified domain name. </p>
+</tr>
-<p> EXAMPLE: </p>
+<tr>
-<dl>
-<dt> (Cyrus SASL version 1.5.x)
-<dd>
-<pre>
-% saslpasswd -c -u `postconf -h myhostname` exampleuser
-</pre>
+<td>MySQL, PostgreSQL, SQLite</td>
-<dt> (Cyrus SASL version 2.1.x)
-<dd>
-<pre>
-% saslpasswd2 -c -u `postconf -h myhostname` exampleuser
-</pre>
+<td><a href="#auxprop_sql">sql</a></td>
-</dl>
+</tr>
-<p> You can find out SASL's idea about the realms of the users
-in sasldb with <i>sasldblistusers</i> (Cyrus SASL version 1.5.x) or
-<i>sasldblistusers2</i> (Cyrus SASL version 2.1.x). </p>
+<tr>
-<p> On the Postfix side, you can have only one realm per smtpd(8)
-instance, and only the users belonging to that realm would be able to
-authenticate. The Postfix variable smtpd_sasl_local_domain controls the
-realm used by smtpd(8): </p>
+<td>LDAP</td>
-<blockquote>
-<pre>
-/etc/postfix/main.cf:
- smtpd_sasl_local_domain = $myhostname
-</pre>
-</blockquote>
+<td><a href="#auxprop_ldapdb">ldapdb</a></td>
-</ul>
+</tr>
-<p> IMPORTANT: The Cyrus SASL password verification services pwcheck
-and saslauthd can only support the plaintext mechanisms PLAIN or
-LOGIN. However, the Cyrus SASL library doesn't know this, and will
-happily advertise other authentication mechanisms that the SASL
-library implements, such as DIGEST-MD5. As a result, if a remote SMTP
-client chooses any mechanism other than PLAIN or LOGIN while pwcheck
-or saslauthd are used, authentication will fail. Thus you may need
-to limit the list of mechanisms advertised by the Postfix SMTP
-server. </p>
+</table>
-<ul>
+</blockquote>
-<li> <p> With older Cyrus SASL versions you remove the corresponding
-library files from the SASL plug-in directory (and again whenever
-the system is updated). </p>
+<blockquote>
-<li> <p> With Cyrus SASL version 2.1.x or later the mech_list variable
-can specify a list of authentication mechanisms that Cyrus SASL may
-offer: </p>
+<strong>Note</strong>
+
+<p> Read the Cyrus SASL documentation for other backends it can
+use. </p>
-<blockquote>
-<pre>
-/usr/local/lib/sasl2/smtpd.conf:
- mech_list: plain login
-</pre>
</blockquote>
-</ul>
+<h4><a name="saslauthd">saslauthd - Cyrus SASL password verification service</a></h4>
-<p> For the same reasons you might want to limit the list of plugins
-used for authentication. </p>
+<p> Communication between the Postfix SMTP server (read: Cyrus SASL's
+<code>libsasl</code>) and the <code>saslauthd</code> server takes
+place over a UNIX-domain socket. </p>
-<ul>
+<p> <code>saslauthd</code> usually establishes the UNIX domain
+socket in <code>/var/run/saslauthd/</code> and waits for authentication
+requests. The Postfix SMTP server must have read+execute permission
+to this directory or authentication attempts will fail. </p>
+
+<blockquote>
+
+<strong>Important</strong>
+
+<p> Some distributions require the user <code>postfix</code> to be
+member of a special group e.g. <code>sasl</code>, otherwise it
+will not be able to access the <code>saslauthd</code> socket
+directory. </p>
-<li> <p> With Cyrus SASL version 1.5.x your only choice is to
-delete the corresponding library files from the SASL plug-in
-directory. </p>
+</blockquote>
-<li> <p> With SASL version 2.1.x: </p>
+<p> The following example configures the Cyrus SASL library to
+contact <code>saslauthd</code> as its password verification service:
+</p>
<blockquote>
<pre>
-/usr/local/lib/sasl2/smtpd.conf:
- pwcheck_method: auxprop
- auxprop_plugin: sql
+/etc/sasl2/smtpd.conf:
+ pwcheck_method: saslauthd
+ mech_list: PLAIN LOGIN
</pre>
</blockquote>
-</ul>
+<blockquote>
-<p> To run software chrooted with SASL support is an interesting
-exercise. It probably is not worth the trouble. </p>
+<strong>Important</strong>
-<h2><a name="server_test">Testing SASL authentication in the Postfix
-SMTP server</a></h2>
+<p> Do not specify any other mechanisms in <code>mech_list</code>
+than <code>PLAIN</code> or <code>LOGIN</code> when using
+<code>saslauthd</code>! It can only handle these two mechanisms,
+and authentication will fail if clients are allowed to choose other
+mechanisms. </p>
-<p> To test the server side, connect (for example, with telnet) to the
-Postfix SMTP server port and you should
-be able to have a conversation as shown below. Information sent by the
-client (that is, you) is shown in bold font. </p>
+</blockquote>
<blockquote>
-<pre>
-$ <b>telnet server.example.com 25</b>
-. . .
-220 server.example.com ESMTP Postfix
-<b>EHLO client.example.com</b>
-250-server.example.com
-250-PIPELINING
-250-SIZE 10240000
-250-ETRN
-250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
-250 8BITMIME
-<b>AUTH PLAIN AHRlc3QAdGVzdHBhc3M=</b>
-235 Authentication successful
-</pre>
-</blockquote>
-<p> Instead of AHRlc3QAdGVzdHBhc3M=, specify the base64 encoded
-form of \0username\0password (the \0 is a null byte). The
-example above is for a user named `test' with password `testpass'.
-</p>
+<strong>Important</strong>
-<p> In order to generate base64 encoded authentication information
-you can use one of the following commands: </p>
+<p> Plaintext mechanisms (<code>PLAIN</code>, <code>LOGIN</code>)
+send credentials unencrypted. This information should be protected
+by an additional security layer such as a TLS-encrypted SMTP session
+(see: TLS_README). </p>
-<blockquote>
-<pre>
-% printf '\0username\0password' | mmencode
-</pre>
</blockquote>
+<p> Additionally the <code>saslauthd</code> server itself must be
+configured. It must be told which authentication backend to turn
+to for password verification. The backend is choosen as a command
+line option when <code>saslauthd</code> is started and will be shown
+in the following examples. </p>
+
<blockquote>
-<pre>
-% perl -MMIME::Base64 -e \
- 'print encode_base64("\0username\0password");'
-</pre>
+
+<strong>Note</strong>
+
+<p> Some distributions use a configuration file to provide saslauthd
+command line options to set e.g. the authentication backend. Typical
+locations are <code>/etc/sysconfig/saslauthd</code> or
+<code>/etc/default/saslauthd</code>. </p>
+
</blockquote>
-<p> The mmencode command is part of the metamail software.
-MIME::Base64 is available from http://www.cpan.org/. </p>
+<h4><a name="id395661">Using saslauthd with /etc/shadow</a></h4>
-<p> Caution: when posting logs of the SASL negotiations to public
-lists,
-please keep in mind that username/password information is trivial
-to recover from the base64-encoded form. </p>
+<p> Access to the <code>/etc/shadow</code> system password file
+requires <code>root</code> privileges. The Postfix SMTP server
+(and in consequence <code>libsasl</code> linked to the server) runs
+with the least privilege possible. Direct access to
+<code>/etc/shadow</code> would not be possible without breaking the
+Postfix security architecture. </p>
-<h2><a name="debugging">Trouble shooting the SASL internals</a></h2>
+<p> The <code>saslauthd</code> socket builds a safe bridge. Postfix,
+running as limited user <code>postfix</code>, can access the
+UNIX-domain socket that <code>saslauthd</code> receives commands
+on; <code>saslauthd</code>, running as privileged user <code>root</code>,
+has the privileges required to access the shadow file. </p>
-<p> In the Cyrus SASL sources you'll find a subdirectory named
-"sample". Run make there, then create a symbolic link from sample.conf
-to smtpd.conf in your Cyrus SASL library directory /usr/local/lib/sasl2.
-"su" to the user <i>postfix</i> (or whatever your <i>mail_owner</i>
-directive is set to): </p>
+<p> The <code>saslauthd</code> server verifies passwords against the
+authentication backend <code>/etc/shadow</code> if started like this: </p>
<blockquote>
<pre>
-% su postfix
+% <strong><code>saslauthd -a shadow</code></strong>
</pre>
</blockquote>
-<p> then run the resulting sample Cyrus SASL server and client in
-separate terminals. The sample applications send log messages to
-the syslog
-facility auth. Check the log to fix the problem or run strace /
-ktrace / truss on the server to see what makes it unhappy. Repeat
-the previous step until you can successfully authenticate with the
-sample Cyrus SASL client. Only then get back to Postfix. </p>
+<p> See section "<a href="#testing_saslauthd">Testing saslauthd
+authentication</a>" for test instructions. </p>
-<h2><a name="client_sasl">Enabling SASL authentication in the
-Postfix SMTP client</a></h2>
+<h4><a name="id395745">Using saslauthd with PAM</a></h4>
-<p> Turn on client-side SASL authentication, and specify a table
-with per-host or per-destination username and password information.
-The Postfix SMTP client first searches the table for an entry with
-the remote SMTP server hostname; if no entry is found, then the
-Postfix SMTP client searches the table for
-an entry with the next-hop destination. Usually, that is the
-right-hand part of an email address, but it can also be the information
-that is specified with the relayhost parameter or with a transport(5)
-table. </p>
+<p> Cyrus SASL can use the PAM framework to authenticate credentials.
+<code>saslauthd</code> uses the PAM framework when started like
+this: </p>
<blockquote>
<pre>
-/etc/postfix/main.cf:
- smtp_sasl_auth_enable = yes
- smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
- smtp_sasl_type = cyrus
- relayhost = [mail.myisp.net]
- # Alternative form:
- # relayhost = [mail.myisp.net]:submission
-
-/etc/postfix/sasl_passwd:
- [mail.myisp.net] username:password
- [mail.myisp.net]:submission username:password
+% <strong><code>saslauthd -a pam</code></strong>
</pre>
</blockquote>
-<p> Notes: </p>
-
-<ul>
+<blockquote>
-<li> <p> The "submission" destination port tells Postfix to send
-mail via TCP network port 587, which is normally reserved for email
-clients. The default is to send mail to the "smtp" destination port
-(TCP port 25), which is used for receiving mail across the internet.
-If you use an explicit destination port in main.cf, then you must
-use the same form also in the smtp_sasl_password_maps file. </p>
-
-<li> <p> Postfix does not deliver mail via TCP port 465 (the obsolete
-"wrappermode" protocol). See TLS_README for a solution that uses the
-"stunnel" command. </p>
-
-<li> <p> The "[" and "]" prevent Postfix from looking up the MX
-(mail exchanger) records for the enclosed name. If you use this
-form in main.cf, then you must use the same form also in the
-smtp_sasl_password_maps file. </p>
-
-<li> <p> The Postfix SMTP client opens the SASL client password
-file before entering the optional chroot jail, so you can keep the
-file in /etc/postfix and set permissions read / write only for root
-to keep the username:password combinations away from other system
-users. </p>
-
-<li> <p> Specify <b>dbm</b> instead of <b>hash</b> if your system
-uses <b>dbm</b> files instead of <b>db</b> files. To find out what
-lookup tables Postfix supports, use the command "<b>postconf -m</b>".
-</p>
+<strong>Note</strong>
-<li> <p> Execute the command "<b>postmap /etc/postfix/sasl_passwd</b>"
-whenever you change the sasl_passwd table. </p>
+<p> PAM configuration for the Postfix SMTP server is usually given
+in <code>/etc/pam.d/smtp</code> and is beyond the scope of this
+document. </p>
-</ul>
+</blockquote>
-<p> Workarounds: </p>
+<p> See section "<a href="#testing_saslauthd">Testing saslauthd
+authentication</a>" for test instructions. </p>
-<ul>
+<h4><a name="id395792">Using saslauthd with an IMAP server</a></h4>
-<li> <p> Some remote SMTP servers support PLAIN or LOGIN authentication only.
-By default, the Postfix SMTP client does not use authentication
-methods that send plaintext passwords, and defers delivery with
-the following error message: "Authentication failed: cannot SASL
-authenticate to server". To enable plaintext authentication specify,
-for example: </p>
+<p> <code>saslauthd</code> can verify the SMTP client credentials
+by using them to log into an IMAP server. If the login succeeds,
+SASL authentication also succeeds. <code>saslauthd</code> contacts
+an IMAP server when started like this: </p>
<blockquote>
<pre>
-/etc/postfix/main.cf:
- smtp_sasl_security_options = noanonymous
+% <strong><code>saslauthd -a rimap -O imap.example.com</code></strong>
</pre>
</blockquote>
-<li> <p> Some remote SMTP servers announce authentication mechanisms
-that don't actually work. It is possible via the smtp_sasl_mechanism_filter
-parameter to restrict the list of server mechanisms that the Postfix
-SMTP client will take into consideration: </p>
-
<blockquote>
-<pre>
-/etc/postfix/main.cf:
- smtp_sasl_mechanism_filter = !gssapi, !external, static:all
-</pre>
+
+<strong>Note</strong>
+
+<p> The option "<code>-O imap.example.com</code>" specifies the
+IMAP server <code>saslauthd</code> should contact when it verifies
+credentials. </p>
+
</blockquote>
-<p> In the above example, the Postfix SMTP client will decline to
-use mechanisms
-that require special infrastructure such as Kerberos or TLS. </p>
+<blockquote>
-<li> <p> The Postfix SMTP client is backwards compatible with SMTP
-servers that use the non-standard "AUTH=method..." syntax in response
-to the EHLO command; there is no Postfix client configuration needed
-to work around it. </p>
+<strong>Important</strong>
-</ul>
+<p> <code>saslauthd</code> sends IMAP login information unencrypted.
+Any IMAP session leaving the local host should be protected by an
+additional security layer such as an SSL tunnel. </p>
-<h2><a name="client_sasl_sender">Supporting multiple ISP accounts
-in the Postfix SMTP client</a></h2>
+</blockquote>
-<p> Postfix version 2.3 supports multiple ISP accounts. This can
-be useful when one person uses the same machine for work and for
-personal use, or when people with different ISP accounts share the
-same Postfix server. To make this possible, Postfix 2.3 supports
-per-sender SASL passwords and per-sender relay hosts. In the example
-below, Postfix will search the SASL password file by sender before
-it searches that same file by destination. Likewise, Postfix will
-search the per-sender relayhost file, and use the default relayhost
-only as a final resort. </p>
+<p> See section "<a href="#testing_saslauthd">Testing saslauthd
+authentication</a>" for test instructions. </p>
-<blockquote>
-<pre>
-/etc/postfix/main.cf:
- smtp_sender_dependent_authentication = yes
- sender_dependent_relayhost_maps = hash:/etc/postfix/sender_relay
- smtp_sasl_auth_enable = yes
- smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
- relayhost = [mail.myisp.net]
- # Alternative form:
- # relayhost = [mail.myisp.net]:submission
+<h4><a name="testing_saslauthd">Testing saslauthd authentication</a></h4>
-/etc/postfix/sasl_passwd:
- # Per-sender authentication; see also /etc/postfix/sender_relay.
- user1@example.com username2:password2
- user2@example.net username2:password2
- # Login information for the default relayhost.
- [mail.myisp.net] username:password
- [mail.myisp.net]:submission username:password
+<p> Cyrus SASL provides the <code>testsaslauthd</code> utility to
+test <code>saslauthd</code> authentication. The username and password
+are given as command line arguments. The example shows the response
+when authentication is successful: </p>
-/etc/postfix/sender_relay:
- # Per-sender provider; see also /etc/postfix/sasl_passwd.
- user1@example.com [mail.example.com]:submission
- user2@example.net [mail.example.net]
+<blockquote>
+<pre>
+% <strong><code>testsaslauthd -u <em>username</em> -p <em>password</em></code></strong>
+0: OK "Success."
</pre>
</blockquote>
-<p> Notes: </p>
+<blockquote>
-<ul>
+<strong>Note</strong>
-<li> <p> If you are creative, then you can try to combine the two
-tables into one single MySQL database, and configure different
-Postfix queries to extract the appropriate information. </p>
+<p> Sometimes the <code>testsaslauthd</code> program is not distributed
+with a the Cyrus SASL main package. In that case, it may be
+distributed with -devel, -dev or -debug packages. </p>
-<li> <p> Specify <b>dbm</b> instead of <b>hash</b> if your system
-uses <b>dbm</b> files instead of <b>db</b> files. To find out what
-lookup tables Postfix supports, use the command "<b>postconf -m</b>".
-</p>
+</blockquote>
-<li> <p> Execute the command "<b>postmap /etc/postfix/sasl_passwd</b>"
-whenever you change the sasl_passwd table. </p>
+<p> Specify an additional "<code>-s smtp</code>" if <code>saslauthd</code>
+was configured to contact the PAM authentication framework and an
+additional "<code>-f <em>/path/to/socketdir/mux</em></code>" if
+<code>saslauthd</code> establishes the UNIX-domain socket in a
+non-default location. </p>
-<li> <p> Execute the command "<b>postmap /etc/postfix/sender_relay</b>"
-whenever you change the sender_relay table. </p>
+<p> If authentication succeeds, proceed with the section "<a
+href="#server_sasl_enable">Enabling SASL authentication and authorization
+in the Postfix SMTP server</a>". </p>
-</ul>
+<h4><a name="auxprop">Cyrus SASL Plugins - auxiliary property
+plugins</a></h4>
-<h2><a name="credits">Credits</a></h2>
+<p> Cyrus SASL uses a plugin infrastructure (called <code>auxprop</code>)
+to expand <code>libsasl</code>'s capabilities. Currently Cyrus
+SASL sources provide three authentication plugins. </p>
-<ul>
+<blockquote>
-<li> Postfix SASL support was originally implemented by Till Franke
-of SuSE Rhein/Main AG.
+<dl>
-<li> Wietse trimmed down the code to only the bare necessities.
+<dt><a href="#auxprop_sasldb">sasldb</a></dt>
-<li> Support for Cyrus SASL version 2 was contributed by Jason Hoos.
+<dd> <p> Accounts are stored stored in a Cyrus SASL Berkeley DB
+database </p> </dd>
-<li> Liviu Daia added smtpd_sasl_application_name, split
-reject_sender_login_mismatch into
-reject_authenticated_sender_login_mismatch and
-reject_unauthenticated_sender_login_mismatch, and revised the docs.
+<dt><a href="#auxprop_sql">sql</a></dt>
-<li> Wietse made another iteration through the code to add plug-in
-support for multiple SASL implementations, and changed
-smtpd_sasl_application_name into smtpd_sasl_path.
+<dd> <p> Accounts are stored in a SQL database </p> </dd>
-<li> The Dovecot SMTP server-only plug-in was originally implemented by
-Timo Sirainen of Procontrol, Finland.
+<dt><a href="#auxprop_ldapdb">ldapdb</a></dt>
-<li> Patrick Ben Koetter revised this document for Postfix 2.4 and
-made much needed updates.
+<dd> <p> Accounts are stored stored in an LDAP database </p> </dd>
-</ul>
+</dl>
+
+</blockquote>
+
+<blockquote>
+
+<strong>Important</strong>
+
+<p> These three plugins support shared-secret mechanisms i.e.
+CRAM-MD5, DIGEST-MD5 and NTLM. These mechanisms send credentials
+encrypted but their verification process requires the password to
+be available in plaintext. Consequently passwords cannot (!) be
+stored in encrypted form. </p>
+
+</blockquote>
+
+<h4><a name="auxprop_sasldb">The sasldb plugin</a></h4>
+
+<p> The sasldb auxprop plugin authenticates credentials stored in a Berkeley
+DB database. The database schema is specific to Cyrus SASL. The
+database is usually located at <code>/etc/sasldb2</code>. </p>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> The <code>sasldb2</code> file contains passwords in
+plaintext, and should have read+write access only to user
+<code>postfix</code> or a group that <code>postfix</code> is member
+of. </p>
+
+</blockquote>
+
+<p> The <code>saslpasswd2</code> command-line utility creates
+and maintains the database: </p>
+
+<blockquote>
+<pre>
+% <strong>saslpasswd2 -c -u <em>example.com</em> <em>username</em></strong>
+Password:
+Again (for verification):
+</pre>
+</blockquote>
+
+<p> This command creates an account
+<code><em>username@example.com</em></code>. </p>
+
+<blockquote>
+
+<strong>Important</strong>
+
+<p> users must specify <code><em>username@example.com</em></code>
+as login name, not <code><em>username</em></code>. </p>
+
+</blockquote>
+
+<p> Run the following command to reuse the Postfix <code>mydomain</code>
+parameter value as the login domain: </p>
+
+<blockquote>
+<pre>
+% <strong>saslpasswd2 -c -u `postconf -h mydomain` <em>username</em></strong>
+Password:
+Again (for verification):
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> Run <code>saslpasswd2</code> without any options for further
+help on how to use the command. </p>
+
+</blockquote>
+
+<p> The <code>sasldblistusers2</code> command lists all existing
+users in the sasldb database: </p>
+
+<blockquote>
+<pre>
+% <strong>sasldblistusers2</strong>
+username1@example.com: password1
+username2@example.com: password2
+</pre>
+</blockquote>
+
+<p> Configure libsasl to use sasldb with the following instructions: </p>
+
+<blockquote>
+<pre>
+/etc/sasl2/smtpd.conf:
+ pwcheck_method: auxprop
+ auxprop_plugin: sasldb
+ mech_list: PLAIN LOGIN CRAM-MD5 DIGEST-MD5 NTLM
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> In the above example adjust <code>mech_list</code> to the
+mechanisms that are applicable for your environment. </p>
+
+</blockquote>
+
+<h4><a name="auxprop_sql">The sql plugin</a></h4>
+
+<p> The sql auxprop plugin is a generic SQL plugin. It provides
+access to credentials stored in a MySQL, a PostgreSQL or a SQLite
+database. </p>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> The shared-secret mechanisms (CRAM-MD5, etc.) require that the
+SASL client passwords are stored as plaintext. </p>
+
+</blockquote>
+
+<blockquote>
+
+<strong>Tip</strong>
+
+<!-- XXX -->
+
+<p> Use "saslauthd > pam > (pam database module)" to
+verify encrypted passwords in an SQL database. </p>
+
+</blockquote>
+
+<p> The following example configures libsasl to use the sql plugin and connects
+it to a PostgreSQL server: </p>
+
+<blockquote>
+<pre>
+/etc/sasl2/smtpd.conf:
+ pwcheck_method: auxprop
+ auxprop_plugin: sql
+ mech_list: PLAIN LOGIN CRAM-MD5 DIGEST-MD5 NTLM
+ sql_engine: pgsql
+ sql_hostnames: 127.0.0.1, 192.0.2.1 sql_user: username
+ sql_passwd: secret
+ sql_database: dbname
+ sql_select: SELECT password FROM users WHERE user = '%u'@'%r'
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> Set appropriate permissions if <code>smtpd.conf</code> contains
+a password. The file should be readable by the <code>postfix</code>
+user. </p>
+
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> In the above example, adjust <code>mech_list</code> to the
+mechanisms that are applicable for your environment. </p>
+
+</blockquote>
+
+<p> The sql plugin has the following configuration options: </p>
+
+<blockquote>
+
+<dl>
+
+<dt>sql_engine</dt>
+
+<dd>
+
+<p> Specify <code>mysql</code> to connect to a MySQL server,
+<code>pgsql</code> for a PostgreSQL server or <code>sqlite</code>
+for an SQLite database </p>
+
+</dd>
+
+<dt>sql_hostnames</dt>
+
+<dd>
+
+<p> Specify one or more servers (hostname or hostname:port) separated
+by commas. </p>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> With MySQL servers, specify <code>localhost</code> to connect
+over a UNIX-domain socket, and specify <code>127.0.0.1</code> to
+connect over a TCP socket. </p>
+
+</blockquote>
+
+</dd>
+
+<dt>sql_user</dt>
+
+<dd>
+
+<p> The login name to gain access to the database. </p>
+
+</dd>
+
+<dt>sql_passwd</dt>
+
+<dd>
+
+<p> The password to gain access to the database. </p>
+
+</dd>
+
+<dt>sql_database</dt>
+
+<dd>
+
+<p> The name of the database to connect to. </p>
+
+</dd>
+
+<dt>sql_select</dt>
+
+<dd>
+
+<p> The SELECT statement that should retrieve the plaintext password
+from a database table. </p>
+
+<blockquote>
+
+<strong>Important</strong>
+
+<p> Do not enclose the statement in quotes! Use single quotes to
+escape macros! </p>
+
+</blockquote>
+
+</dd>
+
+</dl>
+
+</blockquote>
+
+<p> The sql plugin provides macros to build <code>sql_select</code>
+statements. They will be replaced with arguments sent from the client. The
+following macros are available: </p>
+
+<blockquote>
+
+<dl>
+
+<dt>%u</dt>
+
+<dd>
+
+<p> The name of the user whose properties are being selected. </p>
+
+</dd>
+
+<dt>%p</dt>
+
+<dd>
+
+<p> The name of the property being selected. While this could technically be
+anything, Cyrus SASL will try userPassword and cmusaslsecretMECHNAME (where
+MECHNAME is the name of a SASL mechanism). </p>
+
+</dd>
+
+<dt>%r</dt>
+
+<dd>
+
+<p> The name of the realm to which the user belongs. This could be
+the KERBEROS realm, the fully-qualified domain name of the computer
+the SASL application is running on, or the domain after the "@" in a
+username. </p>
+
+</dd>
+
+</dl>
+
+</blockquote>
+
+<h4><a name="auxprop_ldapdb">The ldapdb plugin</a></h4>
+
+<p> The ldapdb auxprop plugin provides access to credentials stored
+in an OpenLDAP LDAP server. It is the only plugin that implements
+proxy authorization. </p>
+
+<p> Proxy authorization in this context means: The ldapdb plugin
+must SASL authenticate with the OpenLDAP server. The server then
+decides if the ldapdb plugin should be authorized to read the
+authenticating user's password. Once the ldapdb plugin has gone
+through proxy authorization it may proceed and authenticate the
+remote SMTP client's credentials. </p>
+
+<p> In a nutshell: Configuring ldapdb means authentication and
+authorization must be configured twice - once in the Postfix SMTP
+server to authenticate and authorize the remote SMTP client, and
+once in the OpenLDAP <code>slapd</code> server to authenticate and
+authorize the ldapdb plugin. </p>
+
+<p> This example configures libsasl to use the ldapdb plugin and
+the plugin to connect to an OpenLDAP server: </p>
+
+<blockquote>
+<pre>
+/etc/sasl2/smtpd.conf:
+ pwcheck_method: auxprop
+ auxprop_plugin: ldapdb
+ mech_list: PLAIN LOGIN NTLM CRAM-MD5 DIGEST-MD5
+ ldapdb_uri: ldap://localhost
+ ldapdb_id: proxyuser
+ ldapdb_pw: password
+ ldapdb_mech: DIGEST-MD5
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Important</strong>
+
+<p> Set appropriate permissions if <code>smtpd.conf</code> contains a
+password. The file should be readable by the <code>postfix</code>
+user. </p>
+
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> The shared-secret mechanisms (CRAM-MD5, etc.) require that the
+SASL client passwords are stored as plaintext. </p>
+
+</blockquote>
+
+<p> The following is a summary of applicable <code>smtpd.conf</code>
+file entries: </p>
+
+<blockquote>
+
+<dl>
+
+<dt>auxprop_plugin</dt>
+
+<dd> <p> Specify <code>ldapdb</code> to enable the plugin. </p> </dd>
+
+<dt>ldapdb_uri</dt>
+
+<dd> <p> Specify either <code>ldapi://</code> for to connect over
+a UNIX-domain socket, <code>ldap://</code> for an unencrypted TCP
+connection or <code>ldaps://</code> for an encrypted TCP connection.
+</p> </dd>
+
+<dt>ldapdb_id</dt>
+
+<dd> <p> The login name to authenticate the ldapdb plugin to the
+LDAP server (proxy authorization). </p> </dd>
+
+<dt>ldapdb_pw</dt>
+
+<dd> <p> The password (in plaintext) to authenticate the ldapdb
+plugin to the LDAP server (proxy authorization). </p> </dd>
+
+<dt>ldapdb_mech</dt>
+
+<dd> <p> The mechanism to authenticate the ldapdb plugin to the
+OpenLDAP slapd server. </p>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> Specify a mechanism here that is supported by the OpenLDAP slapd
+server. </p>
+
+</blockquote>
+
+</dd>
+
+<dt>ldapdb_rc (optional)</dt>
+
+<dd> <p> The path to a file containing individual configuration
+options for the ldapdb LDAP client (libldap). This allows to specify
+a TLS client certificate which in turn can be used to use the SASL
+EXTERNAL mechanism. </p>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> This mechanism supports authentication over an encrypted transport
+layer, which is recommended if the plugin must connect to an OpenLDAP
+server on a remote machine. </p>
+
+</blockquote>
+
+</dd>
+
+<dt>ldapdb_starttls (optional)</dt>
+
+<dd> <p> The TLS policy for connecting to the LDAP server. Specify
+either <code>try</code> or <code>demand</code>. If the option is
+<code>try</code> the plugin will attempt to establish a TLS-encrypted
+connection with the LDAP server, and will fallback to an unencrypted
+connection if TLS fails. If the policy is <code>demand</code> and
+a TLS-encrypted connection cannot be established, the connection
+fails immediately. </p> </dd>
+
+</dl>
+
+</blockquote>
+
+<p> When the ldapdb plugin connects to the OpenLDAP server and
+successfully authenticates, the OpenLDAP server decides if the
+plugin user is authorized to read SASL account information. </p>
+
+<p> The following configuration gives an example of authorization configuration
+in the OpenLDAP slapd server: </p>
+
+<blockquote>
+<pre>
+/etc/openldap/slapd.conf:
+ authz-regexp
+ uid=(.*),cn=.*,cn=auth
+ ldap:///dc=example,dc=com??sub?cn=$1
+ authz-policy to
+</pre>
+</blockquote>
+
+<p> Here, the <code>authz-regexp</code> option serves for authentication
+of the ldapdb user. It maps its login name to a DN in the LDAP
+directory tree where <code>slapd</code> can look up the SASL account
+information. The <code>authz-policy</code> options defines the
+authentication policy. In this case it grants authentication
+privileges "<code>to</code>" the ldapdb plugin. </p>
+
+<p> The last configuration step is to tell the OpenLDAP <code>slapd</code>
+server where ldapdb may search for usernames matching the one given
+by the mail client. The example below adds an additional attribute
+ldapdb user object (here: <code>authzTo</code> because the authz-policy
+is "<code>to</code>") and configures the scope where the login name
+"proxyuser" may search: </p>
+
+<blockquote>
+<pre>
+dn: cn=proxyuser,dc=example,dc=com
+changetype: modify
+add: authzTo
+authzTo: dn.regex:uniqueIdentifier=(.*),ou=people,dc=example,dc=com
+</pre>
+</blockquote>
+
+<p> Use the <code>ldapmodify</code> or <code>ldapadd</code> command
+to add the above attribute. </p>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> Read the chapter "Using SASL" in the <a
+href="http://www.openldap.org/doc/admin">OpenLDAP Admin Guide</a>
+for more detailed instructions to set up SASL authentication in
+OpenLDAP. </p>
+
+</blockquote>
+
+<h3><a name="server_sasl_enable">Enabling SASL authentication and
+authorization in the Postfix SMTP server</a></h3>
+
+<p> By default the Postfix SMTP server uses the Cyrus SASL
+implementation. If the Dovecot SASL implementation should be used,
+specify an <code>smtpd_sasl_type</code> value of <code>dovecot</code>
+instead of <code>cyrus</code>: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_sasl_type = dovecot
+</pre>
+</blockquote>
+
+<p> Additionally set the path where the Postfix SMTP server can
+find the Dovecot SASL socket: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_sasl_path = private/auth
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> This example uses a pathname relative to the Postfix queue
+directory, so that it will work whether or not the Postfix SMTP
+server runs chrooted. </p>
+
+</blockquote>
+
+<h4><a name="server_sasl_authc">Enabling SASL authentication
+in the Postfix SMTP server</a></h4>
+
+<p> Regardless of the SASL implementation type, enabling SMTP
+authentication in the Postfix SMTP server always requires seting
+the <code>smtpd_sasl_auth_enable</code> option: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_sasl_auth_enable = yes
+</pre>
+</blockquote>
+
+<p> After a "postfix reload", SMTP clients will see the additional
+capability AUTH in an SMTP session, followed by a list of
+authentication mechanisms the server supports: </p>
+
+<blockquote>
+<pre>
+% <strong>telnet server.example.com 25</strong>
+...
+220 server.example.com ESMTP Postfix
+<strong>EHLO client.example.com</strong>
+250-server.example.com
+250-PIPELINING
+250-SIZE 10240000
+250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
+...
+</pre>
+</blockquote>
+
+<p> However not all clients recognize the AUTH capability as defined
+by the SASL authentication RFC. Some historical implementations expect the
+server to send an "<code>=</code>" as separator between the AUTH
+verb and the list of mechanisms that follows it. </p>
+
+<p> The <code>broken_sasl_auth_clients</code> configuration option
+lets Postfix repeat the AUTH statement in a form that these broken
+clients understand: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ broken_sasl_auth_clients = yes
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> Enable this option for Outlook up to and including version 2003
+and Outlook Express up to version 6. This option does not hurt other
+clients. </p>
+
+</blockquote>
+
+<p> After "postfix reload", the Postfix SMTP server will propagate
+the AUTH capability twice - once for compliant and once for broken
+clients: </p>
+
+<blockquote>
+<pre>
+% <strong>telnet server.example.com 25</strong>
+...
+<strong>EHLO client.example.com</strong>
+250-server.example.com
+250-PIPELINING
+250-SIZE 10240000
+250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
+250-AUTH=DIGEST-MD5 PLAIN CRAM-MD5
+...
+</pre>
+</blockquote>
+
+<h4><a name="smtpd_sasl_security_options">Postfix SMTP Server
+Authentication Policy</a></h4>
+
+<p> The Postfix SMTP server provides a way to specify the properties
+of SASL mechanisms that can be made available to the remote SMTP
+client. </p>
+
+<h4><a name="id396877">Unencrypted SMTP session</a></h4>
+
+<p> The default policy is to allow any mechanism in the Postfix SMTP server
+except for those based on anonymous authentication: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ # Specify a list of properties separated by comma or whitespace
+ smtpd_sasl_security_options = noanonymous
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Important</strong>
+
+<p> Always set at least the <code>noanonymous</code> option.
+Otherwise, the Postfix SMTP server can give strangers the same
+authorization as a properly-authenticated client. </p>
+
+</blockquote>
+
+<p> Postfix can enforce the following policies on SASL authentication
+mechanisms: </p>
+
+<blockquote>
+
+<dl>
+
+<dt>noanonymous</dt>
+
+<dd> <p> Don't use mechanisms that permit anonymous authentication.
+</p> </dd>
+
+<dt>noplaintext</dt>
+
+<dd> <p> Don't use mechanisms that transmit unencrypted username
+and password information. </p> </dd>
+
+<dt>nodictionary</dt>
+
+<dd> <p> Don't use mechanisms that are vulnerable to dictionary
+attacks. </p>
+
+</dd>
+
+<dt>forward_secrecy</dt>
+
+<dd> <p> Use only mechanisms that support forward secrecy (Dovecot
+SASL only).</p>
+
+</dd>
+
+<dt>mutual_auth</dt>
+
+<dd> <p> Use only mechanisms that authenticate both the client and
+the server to each other. </p> </dd>
+
+</dl>
+
+</blockquote>
+
+<h4><a name="id396969">Encrypted SMTP session (TLS)</a></h4>
+
+<p> A separate parameter controls Postfix SASL mechanism policy
+during a TLS-encrypted SMTP session. The default is to copy the
+settings from the unencrypted session: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_sasl_tls_security_options = $smtpd_sasl_security_options
+</pre>
+</blockquote>
+
+<p> A more sophisticated policy allows plaintext mechanisms, but
+only over a TLS-encrypted connection: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_sasl_security_options = noanonymous, noplaintext
+ smtpd_sasl_tls_security_options = noanonymous
+</pre>
+</blockquote>
+
+<p> To offer SASL authentication only after a TLS-encrypted session has been
+established specify this: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_tls_auth_only = yes
+</pre>
+</blockquote>
+
+<h4><a name="server_sasl_authz">Enabling SASL authorization in the Postfix
+SMTP server</a></h4>
+
+<p> After the client has authenticated with SASL, the Postfix SMTP
+server decides what the remote SMTP client will be authorized
+for. Examples of possible SMTP clients authorizations are: </p>
+
+<ul>
+
+<li> <p> Send a message to a remote recipient. </p> </li>
+
+<li> <p> Use a specific envelope sender in the MAIL FROM command. </p> </li>
+
+</ul>
+
+<p> These permissions are not enabled by default. </p>
+
+<h4><a name="id397041">Mail relay authorization</a></h4>
+
+<p> The <code>permit_sasl_authenticated</code> restriction allows
+SASL-authenticated SMTP clients to send mail to remote destinations.
+Add it to the list of <code>smtpd_recipient_restrictions</code> as
+follows: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_recipient_restrictions =
+ ...
+ permit_mynetworks
+ <strong>permit_sasl_authenticated</strong>
+ reject_unauth_destination
+ ...
+</pre>
+</blockquote>
+
+<h4><a name="id397072">Envelope sender address authorization</a></h4>
+
+<p> By default an SMTP client may specify any envelope sender address
+in the MAIL FROM command. That is because the Postfix SMTP server
+only knows the remte SMTP client hostname and IP address, but not
+the user who controls the remote SMTP client. </p>
+
+<p> This changes the moment an SMTP client uses SASL authentication.
+Now, the Postfix SMTP server knows who the sender is. Given a table
+of envelope sender addresses and SASL login names, the Postfix SMTP
+server can decide if the SASL authenticated client is allowed to
+use a particular envelope sender address: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ <strong>smtpd_sender_login_maps = hash:/etc/postfix/controlled_envelope_senders</strong>
+
+ smtpd_recipient_restrictions =
+ ...
+ <strong>reject_sender_login_mismatch</strong>
+ permit_sasl_authenticated
+ permit_mynetworks
+ reject_unauth_destination
+ ...
+</pre>
+</blockquote>
+
+<p> The <code>controlled_envelope_senders</code> table specifies
+the binding between the sender envelope addresses and its their
+SASL login names: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/controlled_envelope_senders
+ # envelope sender owners (SASL login names)
+ john@example.com john@example.com
+ helpdesk@example.com john@example.com, mary@example.com
+ postmaster admin@example.com
+ @example.net barney, fred, john@example.com, mary@example.com
+</pre>
+</blockquote>
+
+<p> With this, the <code>reject_sender_login_mismatch</code>
+restriction above will reject the sender address in the MAIL FROM
+command if <code>smtpd_sender_login_maps</code> does not specify
+the SMTP client's login name as an owner of that address. </p>
+
+<p> See also <code>reject_authenticated_sender_login_mismatch</code> and
+<code>reject_unauthenticated_sender_login_mismatch</code> for additional
+control over the SASL login name and the envelope sender. </p>
+
+<h4><a name="server_sasl_other">Additional SMTP Server SASL options</a></h4>
+
+<p> Postfix provides a wide range of SASL authentication configuration
+options. The next section lists a few that are discussed frequently.
+See postconf(5) for a complete list. </p>
+
+<h4><a name="id397172">Default authentication domain</a></h4>
+
+<p> Postfix can append a domain name (or any other string) to a
+SASL login name that does not have a domain part, e.g. "<code>john</code>"
+instead of "<code>john@example.com</code>": </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_sasl_local_domain = example.com
+</pre>
+</blockquote>
+
+<p> This is useful as a default setting and safety net for misconfigured
+clients, or during a migration to an authentication method/backend
+that requires an authentication REALM or domain name, before all
+SMTP clients are configured to send such information. </p>
+
+<h4><a name="id397205">Hiding SASL authentication from clients or
+networks</a></h4>
+
+<p> Some clients insist on using SASL authentication if it is offered, even
+when they are not configured to send credentials - and therefore
+they will always fail and disconnect. </p>
+
+<p> Postfix can hide the AUTH capability from these clients/networks: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_sasl_exceptions_networks = !192.0.2.171/32, 192.0.2.0/24
+</pre>
+</blockquote>
+
+<h4><a name="id397226">Adding the SASL login name to mail headers</a></h4>
+
+<p> To report SASL login names in Received: message headers (Postfix
+version 2.3 and later): </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_sasl_authenticated_header = yes
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> The SASL login names will be shared with the entire world. </p>
+
+</blockquote>
+
+<h3><a name="server_test">Testing SASL authentication in the Postfix SMTP Server</a></h3>
+
+<p> To test the server side, connect (for example, with
+<code>telnet</code>) to the Postfix SMTP server port and you should
+be able to have a conversation as shown below. Information sent by
+the client (that is, you) is shown in bold font. </p>
+
+<blockquote>
+<pre>
+% <strong>telnet server.example.com 25</strong>
+...
+220 server.example.com ESMTP Postfix
+<strong>EHLO client.example.com</strong>
+250-server.example.com
+250-PIPELINING
+250-SIZE 10240000
+250-ETRN
+250-AUTH DIGEST-MD5 PLAIN CRAM-MD5
+250 8BITMIME
+<strong>AUTH PLAIN AHRlc3QAdGVzdHBhc3M=</strong>
+235 Authentication successful
+</pre>
+</blockquote>
+
+<p> Instead of <code>AHRlc3QAdGVzdHBhc3M=</code>, specify the
+base64-encoded form of <code>\0username\0password</code> (the \0
+is a null byte). The example above is for a user named `<code>test</code>'
+with password `<code>testpass</code>'. </p>
+<blockquote>
+
+<strong>Caution</strong>
+
+<p> When posting logs of the SASL negotiations to public lists,
+please keep in mind that username/password information is trivial
+to recover from the base64-encoded form. </p>
+
+</blockquote>
+
+<p> You can use one of the following commands to generate base64
+encoded authentication information: </p>
+
+<blockquote>
+<pre>
+% <strong>gen-auth plain</strong>
+username: <strong><em>username</em></strong>
+password:
+</pre>
+</blockquote>
+
+<p> The <strong>gen-auth</strong> Perl script was written by John
+Jetmore and can be found at http://jetmore.org/john/code/gen-auth. </p>
+
+<blockquote>
+<pre>
+% <strong>printf '\0<em>username</em>\0<em>password</em>' | mmencode</strong>
+</pre>
+</blockquote>
+
+<p> The <strong>mmencode</strong> command is part of the metamail
+software. </p>
+
+<blockquote>
+<pre>
+% <strong>perl -MMIME::Base64 -e \
+ 'print encode_base64("\0<em>username</em>\0<em>password</em>");'</strong>
+</pre>
+</blockquote>
+
+<p> MIME::Base64 is available from http://www.cpan.org/. </p>
+
+<h2><a name="client_sasl">Configuring SASL authentication in the Postfix SMTP/LMTP client</a></h2>
+
+<p> The Postfix SMTP and the LMTP client can authenticate with a
+remote SMTP server via the Cyrus SASL framework. At this time, the
+Dovecot SASL implementation does not provide client functionality.
+</p>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> The examples in this section discuss only the SMTP client.
+Replace <code>smtp_</code> with <code>lmtp_</code> to get the
+corresponding LMTP client configuration. </p>
+
+</blockquote>
+
+<p> You can read more about the following topics: </p>
+
+<ul>
+
+<li><a href="#client_sasl_enable">Enabling SASL authentication in
+the Postfix SMTP/LMTP client</a></li>
+
+<li><a href="#client_sasl_sender">Configuring sender-dependent SASL
+authentication</a></li>
+
+<li><a href="#client_sasl_policy">Postfix SMTP/LMTP client
+authentication policy</a></li>
+
+<li><a href="#client_sasl_filter">Filtering server mechanism names
+in the Postfix SMTP/LMTP client</a></li>
+
+</ul>
+
+<h3><a name="client_sasl_enable">Enabling SASL authentication in the
+Postfix SMTP/LMTP client</a></h3>
+
+<p> This section shows a typical scenario where the Postfix SMTP
+client sends all messages via a mail gateway server that requires
+SASL authentication. To make the example more readable we introduce
+it in two parts. </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_sasl_auth_enable = yes
+ relayhost = [mail.isp.example]
+ # Alternative form:
+ # relayhost = [mail.isp.example]:submission
+ smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
+</pre>
+</blockquote>
+
+<ul>
+
+<li> <p> The <code>smtp_sasl_auth_enable</code> setting enables
+client-side authentication. We will configure the client's username
+and password information in the second part of the example. </p>
+</li>
+
+<li> <p> The <code>relayhost</code> setting forces the Postfix SMTP
+to send all remote messages to the specified mail server instead
+of trying to deliver them directly to their destination. </p> </li>
+
+<li> <p> In the <code>relayhost</code> setting, the "<code>[</code>"
+and "<code>]</code>" prevent the Postfix SMTP client from looking
+up MX (mail exchanger) records for the enclosed name. </p> </li>
+
+<li> <p> The <code>relayhost</code> destination may also specify a
+non-default TCP port. For example, the alternative form
+<code>[mail.isp.example]:submission</code> tells Postfix to connect
+to TCP network port 587, which is reserved for email client
+applications. </p> </li>
+
+<li> <p> The Postfix SMTP client is compatible with SMTP servers
+that use the non-standard "<code>AUTH=<em>method.</em>...</code>"
+syntax in response to the EHLO command; this requires no additional
+Postfix client configuration. </p> </li>
+
+<li> <p> The Postfix SMTP client does not support the obsolete
+"wrappermode" protocol, which uses TCP port <code>465</code> on the
+SMTP server. See TLS_README for a solution that uses the
+<code>stunnel</code> command. </p> </li>
+
+<li> <p> With the <code>smtp_sasl_password_maps</code> parameter,
+we configure the Postfix SMTP client to send username and password
+information to the mail gateway server. As discussed in the next
+section, the Postfix SMTP client supports multiple ISP accounts.
+For this reason the username and password are stored in a table
+that contains one username/password combination for each mail gateway
+server. </p>
+
+</ul>
+
+<blockquote>
+<pre>
+/etc/postfix/sasl_passwd:
+ # destination credentials
+ [mail.isp.example] username:password
+ # Alternative form:
+ # [mail.isp.example]:submission username:password
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Important</strong>
+
+<p> Keep the SASL client password file in <code>/etc/postfix</code>,
+and make the file read+write only for <code>root</code> to protect
+the username/password combinations against other users. The Postfix
+SMTP client will still be able to read the SASL client passwords.
+It opens the file as user <code>root</code> before it drops privileges,
+and before entering an optional chroot jail. </p>
+
+</blockquote>
+
+<ul>
+
+<li> <p> Use the <code>postmap</code> command whenever you
+change the <code>/etc/postfix/sasl_passwd</code> file. </p> </li>
+
+<li> <p> If you specify the "<code>[</code>" and "<code>]</code>"
+in the <code>relayhost</code> destination, then you must use the
+same form in the <code>smtp_sasl_password_maps</code> file. </p>
+</li>
+
+<li> <p> If you specify a non-default TCP Port (such as
+"<code>:submission</code>" or "<code>:587</code>") in the
+<code>relayhost</code> destination, then you must use the same form
+in the <code>smtp_sasl_password_maps</code> file. </p> </li>
+
+</ul>
+
+<h3><a name="client_sasl_sender">Configuring Sender-Dependent SASL
+authentication</a></h3>
+
+<p> Postfix supports different ISP accounts for different sender
+addresses (version 2.3 and later). This can be useful when one
+person uses the same machine for work and for personal use, or when
+people with different ISP accounts share the same Postfix server.
+</p>
+
+<p> To make this possible, Postfix supports per-sender SASL passwords
+and per-sender relay hosts. In the example below, the Postfix SMTP
+client will search the SASL password file by sender address before
+it searches that same file by destination. Likewise, the Postfix
+trivial-rewrite(8) daemon will search the per-sender relayhost file,
+and use the default <code>relayhost</code> setting only as a final
+resort. </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_sender_dependent_authentication = yes
+ sender_dependent_relayhost_maps = hash:/etc/postfix/sender_relay
+ smtp_sasl_auth_enable = yes
+ smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd
+ relayhost = [mail.isp.example]
+ # Alternative form:
+ # relayhost = [mail.isp.example]:submission
+</pre>
+</blockquote>
+
+<blockquote>
+<pre>
+/etc/postfix/sasl_passwd:
+ # Per-sender authentication; see also /etc/postfix/sender_relay.
+ user1@example.com username2:password2
+ user2@example.net username2:password2
+ # Login information for the default relayhost.
+ [mail.isp.example] username:password
+ # Alternative form:
+ # [mail.isp.example]:submission username:password
+</pre>
+</blockquote>
+
+<blockquote>
+<pre>
+/etc/postfix/sender_relay:
+ # Per-sender provider; see also /etc/postfix/sasl_passwd.
+ user1@example.com [mail.example.com]:submission
+ user2@example.net [mail.example.net]
+</pre>
+</blockquote>
+
+<ul>
+
+<li> <p> If you are creative, then you can try to combine the two
+tables into one single MySQL database, and configure different
+Postfix queries to extract the appropriate information. </p>
+
+<li> <p> Specify dbm instead of hash if your system uses dbm files
+instead of db files. To find out what lookup tables Postfix supports,
+use the command "postconf -m". </p>
+
+<li> <p> Execute the command "postmap /etc/postfix/sasl_passwd"
+whenever you change the sasl_passwd table. </p>
+
+<li> <p> Execute the command "postmap /etc/postfix/sender_relay"
+whenever you change the sender_relay table. </p>
+
+</ul>
+
+<h3><a name="client_sasl_policy">Postfix SMTP/LMTP client authentication
+policy</a></h3>
+
+<p> Just like the Postfix SMTP server, the SMTP client has a policy
+that determines which SASL mechanisms are acceptable and which are
+not. </p>
+
+<h4>Unencrypted SMTP session</h4>
+
+<p> The default policy is stricter than that of the Postfix SMTP
+server - plaintext mechanisms are not allowed (nor is any anonymous
+mechanism): </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_sasl_security_options = noplaintext, noanonymous
+</pre>
+</blockquote>
+
+<p> Postfix can enforce the following policies on SASL authentication
+mechanisms: </p>
+
+<blockquote>
+
+<dl>
+
+<dt>noanonymous</dt>
+
+<dd> <p> Don't use mechanisms that permit anonymous authentication.
+</p> </dd>
+
+<dt>noplaintext</dt>
+
+<dd> <p> Don't use mechanisms that transmit unencrypted username
+and password information. </p> </dd>
+
+<dt>nodictionary</dt>
+
+<dd> <p> Don't use mechanisms that are vulnerable to dictionary
+attacks. </p>
+
+</dd>
+
+<dt>
+<dt>mutual_auth</dt>
+
+<dd> <p> Use only mechanisms that authenticate both the client and
+the server to each other. </p> </dd>
+
+</dl>
+
+</blockquote>
+
+<p> With the default policy shown above, the Postfix SMTP client
+will not send its password over an unencrypted connection. This
+sometimes leads to authentication failures if the remote server
+only offers plaintext authentication mechanisms. In such cases the
+SMTP client will log the following error message: </p>
+
+<blockquote>
+<pre>
+SASL authentication failure: No worthy mechs found
+</pre>
+</blockquote>
+
+<p> The less secure approach to deal with this is to lower the
+security standards and permit plaintext authentication mechanisms:
+</p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_sasl_security_options = noanonymous
+</pre>
+</blockquote>
+
+<p> Needless to say, sending a username and password over an insecure
+channel is undesirable. </p>
+
+<p> If the remote server supports TLS, you can protect the plaintext
+username and password by turning on TLS in the Postfix SMTP client
+(see: TLS_README), and configuring the client as discussed next.
+
+<h4>Encrypted SMTP session (TLS)</h4>
+
+<p> A separate parameter controls Postfix SASL mechanism policy
+during a TLS-encrypted SMTP session. The default is to copy the
+settings from the unencrypted session: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_sasl_tls_security_options = $smtp_sasl_security_options
+</pre>
+</blockquote>
+
+<p> A more sophisticated policy allows plaintext mechanisms, but
+only over a TLS-encrypted connection: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtpd_sasl_security_options = noanonymous, noplaintext
+ smtpd_sasl_tls_security_options = noanonymous
+</pre>
+</blockquote>
+
+<h3><a name="client_sasl_filter">Filtering server mechanism names in
+the Postfix SMTP/LMTP client</a></h3>
+
+<p> Cyrus SASL always attempts to use the most secure authentication
+mechanism that the remote SMTP server offers - even if the client
+side was not configured to handle it! In such cases authentication
+will definitely fail. </p>
+
+<p> To prevent this, the Postfix SMTP client can filter the list
+of authentication mechanism names from the remote SMTP server. Used
+correctly, the filter hides unwanted mechanisms from the Cyrus SASL
+library, forcing the library to choose from the mechanisms the
+Postfix filter passes through. </p>
+
+<p> The following example filters out everything but the mechanisms
+<code>PLAIN</code> and <code>LOGIN</code>: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_sasl_mechanism_filter = plain, login
+</pre>
+</blockquote>
+
+<blockquote>
+
+<strong>Note</strong>
+
+<p> If the remote server does not offer any of the mechanisms on
+the filter list, authentication will fail. </p>
+
+</blockquote>
+
+<p> We close this section with an example that passes every mechanism
+except for <code>GSSAPI</code> and <code>LOGIN</code>: </p>
+
+<blockquote>
+<pre>
+/etc/postfix/main.cf:
+ smtp_sasl_mechanism_filter = !gssapi, !login, static:all
+</pre>
+</blockquote>
+
+<h2><a name="postfix_build">Building Postfix with SASL support</a></h2>
+
+<p> As mentioned elsewhere, Postfix supports two SASL implementations:
+Cyrus SASL (SMTP client and server) and Dovecot SASL (SMTP server
+only). Both implementations can be built into Postfix simultaneously.
+</p>
+
+<ul>
+
+<li><a href="#build_dovecot">Building Dovecot SASL support</a></li>
+
+<li><a href="#sasl_support">Building Cyrus SASL support</a></li>
+
+</ul>
+
+<h3><a name="build_dovecot">Building Dovecot SASL support</a></h3>
+
+<p> These instructions assume that you build Postfix from source
+code as described in the INSTALL document. Some modification may
+be required if you build Postfix from a vendor-specific source
+package. </p>
+
+<p> Support for the Dovecot version 1 SASL protocol is available
+in Postfix 2.3 and later. At the time of writing, only server-side
+SASL support is available, so you can't use it to authenticate the
+Postfix SMTP client to your network provider's server. </p>
+
+<p> Dovecot uses its own daemon process for authentication. This
+keeps the Postfix build process simple, because there is no need
+to link extra libraries into Postfix. </p>
+
+<p> To generate the necessary Makefiles, execute the following in
+the Postfix top-level directory: </p>
+
+<blockquote>
+<pre>
+% <strong>make tidy</strong> # if you have left-over files from a previous build
+% <strong>make makefiles CCARGS='-DUSE_SASL_AUTH \
+ -DDEF_SERVER_SASL_TYPE=\"dovecot\"'</strong>
+</pre>
+</blockquote>
+
+<p> After this, proceed with "<code>make</code>" as described in
+the INSTALL document. </p>
+
+<strong>Note</strong>
+
+<ul>
+
+<li>
+
+<p> The <code>-DDEF_SERVER_SASL_TYPE=\"dovecot\"</code> is not
+necessary; it just makes Postfix configuration a little more
+convenient because you don't have to specify the SASL plug-in type
+in the Postfix main.cf file (but this may cause surprises when you
+switch to a later Postfix version that is built with the default
+SASL type of <code>sasl</code>). </p>
+
+</li>
+
+<li>
+
+<p> If you also want support for LDAP or TLS (or for Cyrus SASL),
+you need to merge their <code>CCARGS</code> and <code>AUXLIBS</code>
+options into the above command line; see the LDAP_README and
+TLS_README for details. </p>
+
+<blockquote>
+<pre>
+% <strong>make tidy</strong> # if you have left-over files from a previous build
+% <strong>make makefiles CCARGS='-DUSE_SASL_AUTH \
+ -DDEF_SERVER_SASL_TYPE=\"dovecot\" \
+ ...<i>CCARGS options for LDAP or TLS etc.</i>...' \
+ AUXLIBS='...<i>AUXLIBS options for LDAP or TLS etc.</i>...'</strong>
+</pre>
+</blockquote>
+
+</li>
+
+</ul>
+
+<h3><a name="sasl_support">Building Cyrus SASL support</a></h3>
+
+<h4><a name="build_sasl">Building the Cyrus SASL library</a></h4>
+
+<p> Postfix works with cyrus-sasl-1.5.x or cyrus-sasl-2.1.x, which are
+available from ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/. </p>
+
+<blockquote>
+
+<strong>Important</strong>
+
+<p> If you install the Cyrus SASL libraries as per the default, you will have
+to create a symlink <code>/usr/lib/sasl</code> ->
+<code>/usr/local/lib/sasl</code> for version 1.5.x or
+<code>/usr/lib/sasl2</code> -> <code>/usr/local/lib/sasl2</code>
+for version 2.1.x. </p>
+
+</blockquote>
+
+<p> Reportedly, Microsoft Outlook (Express) requires the non-standard LOGIN
+and/or NTLM authentication mechanism. To enable these authentication
+mechanisms, build the Cyrus SASL libraries with: </p>
+
+<blockquote>
+<pre>
+% <strong>./configure --enable-login --enable-ntlm</strong>
+</pre>
+</blockquote>
+
+<h4><a name="build_postfix">Building Postfix with Cyrus SASL support</a></h4>
+
+<p> These instructions assume that you build Postfix from source
+code as described in the INSTALL document. Some modification may
+be required if you build Postfix from a vendor-specific source
+package. </p>
+
+<p> The following assumes that the Cyrus SASL include files are in
+<code>/usr/local/include</code>, and that the Cyrus SASL libraries are in
+<code>/usr/local/lib</code>. </p>
+
+<p> On some systems this generates the necessary <code>Makefile</code>
+definitions: </p>
+
+<dl>
+
+<dt>Cyrus SASL version 2.1.x</dt>
+
+<dd>
+
+<pre>
+% <strong>make tidy</strong> # if you have left-over files from a previous build
+% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
+ -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib -lsasl2"</strong>
+</pre>
+
+</dd>
+
+<dt>Cyrus SASL version 1.5.x</dt>
+
+<dd>
+
+<pre>
+% <strong>make tidy</strong> # if you have left-over files from a previous build
+% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
+ -I/usr/local/include" AUXLIBS="-L/usr/local/lib -lsasl"</strong>
+</pre>
+
+</dd>
+
+</dl>
+
+<p> On Solaris 2.x you need to specify run-time link information,
+otherwise the ld.so run-time linker will not find the SASL shared
+library: </p>
+
+<dl>
+
+<dt>Cyrus SASL version 2.1.x</dt>
+
+<dd>
+
+<pre>
+% <strong>make tidy</strong> # remove left-over files from a previous build
+% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
+ -I/usr/local/include/sasl" AUXLIBS="-L/usr/local/lib \
+ -R/usr/local/lib -lsasl2"</strong>
+</pre>
+
+</dd>
+
+<dt>Cyrus SASL version 1.5.x</dt>
+
+<dd>
+
+<pre>
+% <strong>make tidy</strong> # if you have left-over files from a previous build
+% <strong>make makefiles CCARGS="-DUSE_SASL_AUTH -DUSE_CYRUS_SASL \
+ -I/usr/local/include" AUXLIBS="-L/usr/local/lib \
+ -R/usr/local/lib -lsasl"</strong>
+</pre>
+
+</dd>
+
+</dl>
+
+<h2><a name="cyrus_legacy">Using Cyrus SASL version 1.5.x</a></h2>
+
+<p> Postfix supports Cyrus SASL version 1.x, but you shouldn't use
+it unless you are forced to. The makers of Cyrus SASL write: </p>
+
+<blockquote> <i> This library is being deprecated and applications
+should transition to using the SASLv2 library</i> (source: <a
+href="http://cyrusimap.web.cmu.edu/downloads.html">Project Cyrus:
+Downloads</a>). </blockquote>
+
+<p> If you still need to set it up, here's a quick rundown: </p>
+
+<p> Read the regular section on SMTP server configurations for the
+Cyrus SASL framework. The differences are: </p>
+
+<ul>
+
+<li> <p> Cyrus SASL version 1.5.x searches for configuration
+(<code>smtpd.conf</code>) in <code>/usr/lib/sasl/</code> only. You
+must place the configuration in that directory. Some systems may
+have modified Cyrus SASL and put the files into e.g.
+<code>/var/lib/sasl/</code>. </p> </li>
+
+<li> <p> Use the <code>saslpasswd</code> command instead of
+<code>saslpasswd2</code> to create users in <code>sasldb</code>.
+</p> </li>
+
+<li> <p> Use the <code>sasldblistusers</code> command instead of
+<code>sasldblistusers2</code> to find users in <code>sasldb</code>.
+</p> </li>
+
+<li> <p> In the <code>smtpd.conf</code> file you can't use
+<code>mech_list</code> to limit the range of mechanisms offered.
+Instead, remove their libraries from <code>/usr/lib/sasl/</code>
+(and remember remove those files again when a system update
+re-installs new versions). </p> </li>
+
+</ul>
+
+<h2><a name="credits">Credits</a></h2>
+
+<ul>
+
+<li> Postfix SASL support was originally implemented by Till Franke
+of SuSE Rhein/Main AG. </li>
+
+<li> Wietse trimmed down the code to only the bare necessities.
+ </li>
+
+<li> Support for Cyrus SASL version 2 was contributed by Jason Hoos.
+</li>
+
+<li> Liviu Daia added smtpd_sasl_application_name, separated
+reject_sender_login_mismatch into
+reject_authenticated_sender_login_mismatch and
+reject_unauthenticated_sender_login_mismatch, and revised the docs.
+ </li>
+
+<li> Wietse made another iteration through the code to add plug-in
+support for multiple SASL implementations, and for reasons that
+have been lost, also changed smtpd_sasl_application_name into
+smtpd_sasl_path. </li>
+
+<li> The Dovecot SMTP server-only plug-in was originally implemented
+by Timo Sirainen of Procontrol, Finland. </li>
+
+<li> Patrick Ben Koetter revised this document for Postfix 2.4 and
+made much needed updates. </li>
+
+<li> Patrick Ben Koetter revised this document again for Postfix
+2.7 and made much needed updates. </li>
+
+</ul>
</body>
</html>
+
parameter. This setting controls the minimum acceptable SMTP client
TLS cipher grade for use with mandatory TLS encryption. The default
value "medium" is suitable for most destinations with which you may
-want to enforce TLS, and is beyond the reach of today's crypt-analytic
+want to enforce TLS, and is beyond the reach of today's cryptanalytic
methods. See smtp_tls_policy_maps for information on how to configure
ciphers on a per-destination basis. </p>
# starts with whitespace continues a logical line.
# .PP
# Each pattern is a perl-like regular expression. The expression
-# delimiter can be any character, except whitespace or characters
+# delimiter can be any non-alphanumerical character, except
+# whitespace or characters
# that have special meaning (traditionally the forward slash is used).
# The regular expression can contain whitespace.
#
<p>
Specify a string of the form <i>transport:nexthop</i>, where <i>transport</i>
is the name of a mail delivery transport defined in master.cf.
-The <i>:nexthop</i> part is optional. For more details see the
-transport(5) manual page.
+The <i>:nexthop</i> destination is optional; its syntax is documented
+in the manual page of the corresponding delivery agent.
</p>
<p>
<p>
Specify a string of the form <i>transport:nexthop</i>, where <i>transport</i>
is the name of a mail delivery transport defined in master.cf.
-The <i>:nexthop</i> part is optional. For more details see the
-transport(5) manual page.
+The <i>:nexthop</i> destination is optional; its syntax is documented
+in the manual page of the corresponding delivery agent.
</p>
<p>
%PARAM require_home_directory no
<p>
-Whether or not a local(8) recipient's home directory must exist
+Require that a local(8) recipient's home directory exists
before mail delivery is attempted. By default this test is disabled.
It can be useful for environments that import home directories to
-the mail server (NOT RECOMMENDED).
+the mail server (IMPORTING HOME DIRECTORIES IS NOT RECOMMENDED).
</p>
%PARAM resolve_dequoted_address yes
<dt><b>speed_adjust</b></dt>
-<dd> Do not connect to a before-queue content filter until an entire
+<dd> <p> Do not connect to a before-queue content filter until an entire
message has been received. This reduces the number of simultaneous
before-queue content filter processes. </p>
<p>
Specify a string of the form <i>transport:nexthop</i>, where <i>transport</i>
is the name of a mail delivery transport defined in master.cf.
-The <i>:nexthop</i> part is optional. For more details see the
-transport(5) manual page.
+The <i>:nexthop</i> destination is optional; its syntax is documented
+in the manual page of the corresponding delivery agent.
</p>
<p>
<p>
Specify a string of the form <i>transport:nexthop</i>, where <i>transport</i>
is the name of a mail delivery transport defined in master.cf.
-The <i>:nexthop</i> part is optional. For more details see the
-transport(5) manual page.
+The <i>:nexthop</i> destination is optional; its syntax is documented
+in the manual page of the corresponding delivery agent.
</p>
<p>
# Opportunistic TLS.
smtp_tls_security_level = may
# Postfix ≥ 2.6:
-# Do not tweak opportunistic ciphers unless it is essential
+# Do not tweak opportunistic ciphers or protocol unless it is essential
# to do so (if a security vulnerability is found in the SSL library that
# can be mitigated by disabling a particular protocol or raising the
# cipher grade from "export" to "low" or "medium").
%PARAM smtpd_tls_mandatory_ciphers medium
-<p> The minimum TLS cipher grade that the Postfix SMTP server
-will use with mandatory TLS encryption. Cipher types listed in
-smtpd_tls_mandatory_exclude_ciphers or smtpd_tls_exclude_ciphers are
-excluded from the base definition of the selected cipher grade. See
-smtpd_tls_ciphers for cipher controls that apply to opportunistic
-TLS. </p>
+<p> The minimum TLS cipher grade that the Postfix SMTP server will
+use with mandatory TLS encryption. The default grade ("medium") is
+sufficiently strong that any benefit from globally restricting TLS
+sessions to a more stringent grade is likely negligible, especially
+given the fact that many implementations still do not offer any stronger
+("high" grade) ciphers, while those that do, will always use "high"
+grade ciphers. So insisting on "high" grade ciphers is generally
+counter-productive. Allowing "export" or "low" ciphers is typically
+not a good idea, as systems limited to just these are limited to
+obsolete browsers. No known SMTP clients fail to support at least
+one "medium" or "high" grade cipher. </p>
<p> The following cipher grades are supported: </p>
<dl>
<dt><b>export</b></dt>
-<dd> Enable the mainstream "EXPORT" grade or better OpenSSL ciphers.
+<dd> Enable "EXPORT" grade or stronger OpenSSL ciphers.
This is the most appropriate setting for public MX hosts, and is always
used with opportunistic TLS encryption. The underlying cipherlist
is specified via the tls_export_cipherlist configuration parameter,
-which you are strongly encouraged to not change. The default value
-of tls_export_cipherlist includes anonymous ciphers, but these are
-automatically filtered out if the server is configured to ask for
-client certificates. If you must always exclude anonymous ciphers,
-set "smtpd_tls_exclude_ciphers = aNULL". To exclude anonymous ciphers
-only when TLS is enforced, set "smtpd_tls_mandatory_exclude_ciphers =
-aNULL". </dd>
+which you are strongly encouraged to not change. </dd>
<dt><b>low</b></dt>
-<dd> Enable the mainstream "LOW" grade or better OpenSSL ciphers. The
+<dd> Enable "LOW" grade or stronger OpenSSL ciphers. The
underlying cipherlist is specified via the tls_low_cipherlist
configuration parameter, which you are strongly encouraged to
-not change. The default value of tls_low_cipherlist includes
-anonymous ciphers, but these are automatically filtered out if the
-server is configured to ask for client certificates. If you must
-always exclude anonymous ciphers, set "smtpd_tls_exclude_ciphers =
-aNULL". To exclude anonymous ciphers only when TLS is enforced, set
-"smtpd_tls_mandatory_exclude_ciphers = aNULL". </dd>
+not change. </dd>
<dt><b>medium</b></dt>
-<dd> Enable the mainstream "MEDIUM" grade or better OpenSSL ciphers. These
-are essentially the 128-bit or stronger ciphers. This is the default
-minimum strength for mandatory TLS encryption. MSAs that enforce
-TLS and have clients that do not support any "MEDIUM" or "HIGH"
-grade ciphers, may need to configure a weaker ("low" or "export")
-minimum cipher grade. The underlying cipherlist is specified via the
-tls_medium_cipherlist configuration parameter, which you are strongly
-encouraged to not change. The default value of tls_medium_cipherlist
-includes anonymous ciphers, but these are automatically filtered out if
-the server is configured to ask for client certificates. If you must
-always exclude anonymous ciphers, set "smtpd_tls_exclude_ciphers =
-aNULL". To exclude anonymous ciphers only when TLS is enforced, set
-"smtpd_tls_mandatory_exclude_ciphers = aNULL". </dd>
+<dd> Enable "MEDIUM" grade or stronger OpenSSL ciphers. These use 128-bit
+or longer symmetric bulk-encryption keys. This is the default minimum
+strength for mandatory TLS encryption. The underlying cipherlist is
+specified via the tls_medium_cipherlist configuration parameter, which
+you are strongly encouraged to not change. </dd>
<dt><b>high</b></dt>
-<dd> Enable only the mainstream "HIGH" grade OpenSSL ciphers. The
+<dd> Enable only "HIGH" grade OpenSSL ciphers. The
underlying cipherlist is specified via the tls_high_cipherlist
configuration parameter, which you are strongly encouraged to
-not change. The default value of tls_high_cipherlist includes
-anonymous ciphers, but these are automatically filtered out if the
-server is configured to ask for client certificates. If you must
-always exclude anonymous ciphers, set "smtpd_tls_exclude_ciphers =
-aNULL". To exclude anonymous ciphers only when TLS is enforced, set
-"smtpd_tls_mandatory_exclude_ciphers = aNULL". </dd>
+not change. </dd>
<dt><b>null</b></dt>
<dd> Enable only the "NULL" OpenSSL ciphers, these provide authentication
case that all clients are prepared to use NULL ciphers (not normally
enabled in TLS clients). The underlying cipherlist is specified via the
tls_null_cipherlist configuration parameter, which you are strongly
-encouraged to not change. The default value of tls_null_cipherlist
-excludes anonymous ciphers (OpenSSL 0.9.8 has NULL ciphers that offer
-data integrity without encryption or authentication). </dd>
+encouraged to not change. </dd>
</dl>
+<p> Cipher types listed in
+smtpd_tls_mandatory_exclude_ciphers or smtpd_tls_exclude_ciphers are
+excluded from the base definition of the selected cipher grade. See
+smtpd_tls_ciphers for cipher controls that apply to opportunistic
+TLS. </p>
+
+<p> The underlying cipherlists for grades other than "null" include
+anonymous ciphers, but these are automatically filtered out if the
+server is configured to ask for client certificates. You are very
+unlikely to need to take any steps to exclude anonymous ciphers, they
+are excluded automatically as required. If you must exclude anonymous
+ciphers even when Postfix does not need or use peer certificates, set
+"smtpd_tls_exclude_ciphers = aNULL". To exclude anonymous ciphers only
+when TLS is enforced, set "smtpd_tls_mandatory_exclude_ciphers = aNULL". </p>
+
<p> This feature is available in Postfix 2.3 and later. </p>
%PARAM smtpd_tls_exclude_ciphers
use with
mandatory TLS encryption. The default value "medium" is suitable
for most destinations with which you may want to enforce TLS, and
-is beyond the reach of today's crypt-analytic methods. See
+is beyond the reach of today's cryptanalytic methods. See
smtp_tls_policy_maps for information on how to configure ciphers
on a per-destination basis. </p>
<dl>
<dt><b>export</b></dt>
-<dd> Enable the mainstream "EXPORT" grade or better OpenSSL
-ciphers. This is always used for opportunistic encryption. It is
+<dd> Enable "EXPORT" grade or better OpenSSL
+ciphers. This is the default for opportunistic encryption. It is
not recommended for mandatory encryption unless you must enforce TLS
with "crippled" peers. The underlying cipherlist is specified via the
tls_export_cipherlist configuration parameter, which you are strongly
-encouraged to not change. The default value of tls_export_cipherlist
-includes anonymous ciphers, but these are automatically filtered out if
-the client is configured to verify server certificates. If you must
-exclude anonymous ciphers also at the "encrypt" security level, set
-"smtp_tls_mandatory_exclude_ciphers = aNULL". </dd>
+encouraged to not change. </dd>
<dt><b>low</b></dt>
-<dd> Enable the mainstream "LOW" grade or better OpenSSL ciphers. This
+<dd> Enable "LOW" grade or better OpenSSL ciphers. This
setting is only appropriate for internal mail servers. The underlying
cipherlist is specified via the tls_low_cipherlist configuration
-parameter, which you are strongly encouraged to not change. The default
-value of tls_low_cipherlist includes anonymous ciphers, but these are
-automatically filtered out if the client is configured to verify server
-certificates. If you must exclude anonymous ciphers also at the "encrypt"
-security level, set "smtp_tls_mandatory_exclude_ciphers = aNULL". </dd>
+parameter, which you are strongly encouraged to not change. </dd>
<dt><b>medium</b></dt>
-<dd> Enable the mainstream "MEDIUM" grade or better OpenSSL ciphers.
+<dd> Enable "MEDIUM" grade or better OpenSSL ciphers.
The underlying cipherlist is specified via the tls_medium_cipherlist
configuration parameter, which you are strongly encouraged to not change.
-The default value of tls_medium_cipherlist includes anonymous ciphers,
-but these are automatically filtered out if the client is configured to
-verify server certificates. If you must exclude anonymous ciphers also
-at the "encrypt" security level, set "smtp_tls_mandatory_exclude_ciphers
-= aNULL". </dd>
+</dd>
<dt><b>high</b></dt>
-<dd> Enable only the mainstream "HIGH" grade OpenSSL ciphers. This
-setting is appropriate when all mandatory TLS destinations support
-some of "HIGH" grade ciphers, this is not uncommon. The underlying
-cipherlist is specified via the tls_high_cipherlist configuration
-parameter, which you are strongly encouraged to not change. The default
-value of tls_high_cipherlist includes anonymous ciphers, but these are
-automatically filtered out if the client is configured to verify server
-certificates. If you must exclude anonymous ciphers also at the "encrypt"
-security level, set "smtp_tls_mandatory_exclude_ciphers = aNULL". </dd>
+<dd> Enable only "HIGH" grade OpenSSL ciphers. This setting may
+be appropriate when all mandatory TLS destinations (e.g. when all
+mail is routed to a suitably capable relayhost) support at least one
+"HIGH" grade cipher. The underlying cipherlist is specified via the
+tls_high_cipherlist configuration parameter, which you are strongly
+encouraged to not change. </dd>
<dt><b>null</b></dt>
<dd> Enable only the "NULL" OpenSSL ciphers, these provide authentication
UNIX-domain socket that is configured to support "NULL" ciphers. The
underlying cipherlist is specified via the tls_null_cipherlist
configuration parameter, which you are strongly encouraged to not
-change. The default value of tls_null_cipherlist excludes anonymous
-ciphers (OpenSSL 0.9.8 has NULL ciphers that offer data integrity without
-encryption or authentication). </dd>
+change. </dd>
</dl>
+<p> The underlying cipherlists for grades other than "null" include
+anonymous ciphers, but these are automatically filtered out if the
+Postfix SMTP client is configured to verify server certificates.
+You are very unlikely to need to take any steps to exclude anonymous
+ciphers, they are excluded automatically as necessary. If you must
+exclude anonymous ciphers at the "may" or "encrypt" security levels,
+when the Postfix SMTP client does not need or use peer certificates, set
+"smtp_tls_exclude_ciphers = aNULL". To exclude anonymous ciphers only when
+TLS is enforced, set "smtp_tls_mandatory_exclude_ciphers = aNULL". </p>
+
<p> This feature is available in Postfix 2.3 and later. </p>
%PARAM smtp_tls_exclude_ciphers
<dt> continue </dt>
-<dd> Forward the connection to a real SMTP server process. </p>
+<dd> Forward the connection to a real SMTP server process. </dd>
<dt> drop </dt>
elapsed. If the client is listed at the DNS blocklist domains
specified with the postscreen_dnsbl_sites parameter, execute the
action specified with the postscreen_dnsbl_action parameter, otherwise
-forward the connection to a real SMTP server process. </p>
+forward the connection to a real SMTP server process. </dd>
<dt> drop </dt>
<dd> Continue waiting until the postscreen_greet_wait time has
elapsed, and report whether the client is listed at the DNSBL sites
specified with the postscreen_dnsbl_sites parameter. Do not
-forward the broken connection to a real SMTP server process. </p>
+forward the broken connection to a real SMTP server process. </dd>
<dt> drop </dt>
error, or whether the client is listed at the DNSBL sites specified
with the postscreen_dnsbl_sites parameter. Take the corresponding
action, or forward the connection to a real SMTP server process.
-</p>
+</dd>
<dt> drop </dt>
<p> This feature is available in Postfix 2.7 and later. </p>
-%PARAM empty_address_default_transport_maps_lookup_key <>
+%PARAM empty_address_default_transport_maps_lookup_key <>
<p> The sender_dependent_default_transport_maps search string that
will be used instead of the null sender address. </p>
# \fBre_format\fR(7) with 4.4BSD, in \fBregex\fR(5) with Solaris, and in
# \fBregex\fR(7) with Linux. Other systems may use other document names.
#
-# The expression delimiter can be any character, except whitespace
+# The expression delimiter can be any non-alphanumerical
+# character, except whitespace
# or characters that have special meaning (traditionally the forward
# slash is used). The regular expression can contain whitespace.
#
* Patches change both the patchlevel and the release date. Snapshots have no
* patchlevel; they change the release date only.
*/
-#define MAIL_RELEASE_DATE "20100117"
-#define MAIL_VERSION_NUMBER "2.7"
+#define MAIL_RELEASE_DATE "20100203"
+#define MAIL_VERSION_NUMBER "2.8"
#ifdef SNAPSHOT
# define MAIL_VERSION_DATE "-" MAIL_RELEASE_DATE
/* Each queue entry shows the queue file ID, message
/* size, arrival time, sender, and the recipients that still need to
/* be delivered. If mail could not be delivered upon the last attempt,
-/* the reason for failure is shown. This mode of operation is implemented
-/* by executing the \fBpostqueue\fR(1) command. The queue ID string
+/* the reason for failure is shown. The queue ID string
/* is followed by an optional status character:
/* .RS
/* .IP \fB*\fR
}
myfree(saved_filter);
- /*
- * This process is called by clients that already enforce the max_idle
- * time, so we don't have to do it another time.
- */
- var_idle_limit = 1;
-
/*
* Never, ever, get killed by a master signal, as that could corrupt a
* persistent database when we're in the middle of an update.
/* Resolve an address that ends in the "@" null domain as if the
/* local hostname were specified, instead of rejecting the address as
/* invalid.
-/* .IP "\fBsmtpd_command_filter (empty)\fR"
-/* A mechanism to transform commands from remote SMTP clients.
/* .IP "\fBsmtpd_reject_unlisted_sender (no)\fR"
/* Request that the Postfix SMTP server rejects mail from unknown
/* sender addresses, even when no explicit reject_unlisted_sender
/* Available in Postfix version 2.6 and later:
/* .IP "\fBtcp_windowsize (0)\fR"
/* An optional workaround for routers that break TCP window scaling.
+/* .PP
+/* Available in Postfix version 2.7 and later:
+/* .IP "\fBsmtpd_command_filter (empty)\fR"
+/* A mechanism to transform commands from remote SMTP clients.
/* ADDRESS REWRITING CONTROLS
/* .ad
/* .fi
#define SMTPD_CMD_FLAG_LAST (1<<2) /* last in PIPELINING command group */
static SMTPD_CMD smtpd_cmd_table[] = {
- SMTPD_CMD_HELO, helo_cmd, SMTPD_CMD_FLAG_LIMIT | SMTPD_CMD_FLAG_PRE_TLS,
- SMTPD_CMD_EHLO, ehlo_cmd, SMTPD_CMD_FLAG_LIMIT | SMTPD_CMD_FLAG_PRE_TLS,
+ SMTPD_CMD_HELO, helo_cmd, SMTPD_CMD_FLAG_LIMIT | SMTPD_CMD_FLAG_PRE_TLS | SMTPD_CMD_FLAG_LAST,
+ SMTPD_CMD_EHLO, ehlo_cmd, SMTPD_CMD_FLAG_LIMIT | SMTPD_CMD_FLAG_PRE_TLS | SMTPD_CMD_FLAG_LAST,
#ifdef USE_TLS
SMTPD_CMD_STARTTLS, starttls_cmd, SMTPD_CMD_FLAG_PRE_TLS,
#endif
/* 2xx or 3xx proxy server response is replaced by a generic
/* error response to avoid support problems.
/* In case of error, smtpd_proxy_create() updates the
-/* state->error_mask and state->err fields, and leaves the the
-/* proxy handle in an unconnected state. Destroy the handle
-/* after reporting the error reply in the proxy->buffer field.
+/* state->error_mask and state->err fields, and leaves the
+/* SMTPD_PROXY handle in an unconnected state. Destroy the
+/* handle after reporting the error reply in the proxy->buffer
+/* field.
/*
/* proxy->cmd() formats and either buffers up the command and
/* expected response until the entire message is received, or
* Send our own EHLO command. If this fails then we have a problem
* because the proxy should always accept our EHLO command. Make up our
* own response instead of passing back a negative EHLO reply: the proxy
- * open is delayed to the point that the client expects a MAIL FROM or
- * RCPT TO reply.
+ * open is delayed to the point that the remote SMTP client expects a
+ * MAIL FROM or RCPT TO reply.
*/
if (smtpd_proxy_cmd(state, SMTPD_PROX_WANT_OK, "EHLO %s",
proxy->ehlo_name)) {
* Send XFORWARD attributes. For robustness, explicitly specify what SMTP
* session attributes are known and unknown. Make up our own response
* instead of passing back a negative XFORWARD reply: the proxy open is
- * delayed to the point that the client expects a MAIL FROM or RCPT TO
- * reply.
+ * delayed to the point that the remote SMTP client expects a MAIL FROM
+ * or RCPT TO reply.
*/
if (server_xforward_features) {
buf = vstring_alloc(100);
}
/*
- * Pass-through the client's MAIL FROM command. If this fails, then we
- * have a problem because the proxy should always accept any MAIL FROM
- * command that was accepted by us.
+ * Pass-through the remote SMTP client's MAIL FROM command. If this
+ * fails, then we have a problem because the proxy should always accept
+ * any MAIL FROM command that was accepted by us.
*/
if (smtpd_proxy_cmd(state, SMTPD_PROX_WANT_OK, "%s",
proxy->mail_from) != 0) {
if (resolve_verify.transport_info)
transport_post_init(resolve_verify.transport_info);
check_table_stats(0, (char *) 0);
-
- /*
- * This process is called by clients that already enforce the max_idle
- * time, so we don't have to do it another time.
- */
- var_idle_limit = 1;
}
MAIL_VERSION_STAMP_DECLARE;
/* .IP "\fBupdate\fI address status text\fR"
/* Update the status and text of the specified address.
/* .IP "\fBquery\fI address\fR"
-/* Look up the \fIstatus\fR and \fItext\fR for the specified address.
+/* Look up the \fIstatus\fR and \fItext\fR for the specified
+/* \fIaddress\fR.
/* If the status is unknown, a probe is sent and an "in progress"
/* status is returned.
/* SECURITY
/* The verify server can run chrooted at fixed low privilege.
/*
/* The address verification server can be coerced to store
-/* unlimited amounts of garbage. Limiting the cache size
+/* unlimited amounts of garbage. Limiting the cache expiry
+/* time
/* trades one problem (disk space exhaustion) for another
/* one (poor response time to client requests).
/*
/* DIAGNOSTICS
/* Problems and transactions are logged to \fBsyslogd\fR(8).
/* BUGS
-/* The address verification service is suitable only for sites that
-/* handle a low mail volume. Verification probes add additional
-/* traffic to the mail queue and perform poorly under high load.
-/* Servers may blacklist sites that probe excessively, or that
-/* probe excessively for non-existent recipient addresses.
+/* Address verification probe messages add additional traffic
+/* to the mail queue.
+/* Recipient verification may cause an increased load on
+/* down-stream servers in the case of a dictionary attack or
+/* a flood of backscatter bounces.
+/* Sender address verification may cause your site to be
+/* blacklisted by some providers.
/*
/* If the persistent database ever gets corrupted then the world
/* comes to an end and human intervention is needed. This violates
/* .fi
/* Changes to \fBmain.cf\fR are not picked up automatically,
/* as \fBverify\fR(8)
-/* processes are persistent. Use the command "\fBpostfix reload\fR" after
+/* processes are long-lived. Use the command "\fBpostfix reload\fR" after
/* a configuration change.
/*
/* The text below provides only a parameter summary. See
projects / thirdparty / postfix.git / commitdiff
