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
src/postkick src/postlock src/postlog src/postmap src/postqueue \
src/postsuper src/qmqpd src/spawn src/flush src/verify \
src/virtual src/proxymap src/anvil src/scache src/discard src/tlsmgr \
- src/postmulti src/postscreen src/dnsblog
+ src/postmulti
MANDIRS = proto man html
LIBEXEC = libexec/post-install libexec/postfix-files libexec/postfix-script \
libexec/postfix-wrapper libexec/main.cf libexec/master.cf \
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.
If you upgrade from Postfix 2.5 or earlier, read RELEASE_NOTES-2.6
before proceeding.
-Incompatibility with snapshot 20100117
-======================================
+Major changes - performance
+---------------------------
-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.
-
-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
-cleanup increases the database access latency, so this should not
-be run more often than necessary.
-
-In addition, the postscreen_cache_retention_time (default: 1d)
-parameter specifies how long to keep an expired entry in the cache.
-This prevents a client from being logged as "NEW" after its record
-expired only a little while ago.
-
-Incompatibility with snapshot 20091209
-======================================
+[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.
-The postscreen daemon now checks the permanent whitelist before
-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.
+[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
reused with successive mail transactions (the file is of course
truncated before reuse, so there is no information leakage).
-Incompatibility with snapshot 20091008
-======================================
-
-NOTE: You must stop and start the Postfix master daemon before you
-can use the postscreen(8) daemon. This is needed because the Postfix
-"pass" master service type did not work reliably on some systems.
+Major changes - sender reputation
+---------------------------------
-Major changes with snapshot 20091008
-====================================
+[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.
-Prototype postscreen(8) server that runs a number of time-consuming
-checks in parallel for all incoming SMTP connections, before clients
-are allowed to talk to a real Postfix SMTP server. It detects
-clients that start talking too soon, or clients that appear on DNS
-blocklists, or clients that hang up without sending any command.
+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.
-By doing these checks in a single postscreen(8) process, Postfix
-can avoid wasting one SMTP server process per connection. A side
-benefit of postscreen(8)'s DNSBL lookups is that DNS records are
-already cached before the Postfix SMTP server looks them up later.
+[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.
-postscreen(8) maintains a temporary whitelist of positive decisions.
-Once an SMTP client is whitelisted, it is immediately forwarded
-to a real Postfix SMTP server process without further checking.
+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.
-By default, the program logs only statistics, and it does not run
-any checks on clients in mynetworks (primarily, to avoid problems
-with buggy SMTP implementations in network appliances). The logging
-function alone is already useful for research.
+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).
-postscreen(8) can be configured to drop clients that start talking
-too soon, or clients that appear on DNS blocklists. For details,
-see below.
+Major changes - address verification
+------------------------------------
-postscreen(8) has been tested on FreeBSD and Linux systems. It
-probably needs additional work before it can be used on Solaris.
+[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.
-This snapshot adds three new entries to the master.cf file.
+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.
-To enable the postscreen(8) service and log client information
-without blocking mail:
+[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.
-1 - Comment out the "smtp inet ... smtpd" service in master.cf,
- including any "-o parameter=value" entries that follow.
+Major changes - content filter
+------------------------------
-2 - Uncomment the new "smtpd pass ... smtpd" service in master.cf,
- and duplicate any "-o parameter=value" entries from the smtpd
- service that was commented out in step 1.
+[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.
-3 - Uncomment the the new "smtp inet ... postscreen" service in
- master.cf.
+This compatibility option is not needed with SMTP-based content
+filters, because these always have an explicit next-hop destination.
-4 - Uncomment the new "dnsblog unix ... dnsblog" service in
- master.cf. This service does DNSBL lookups for postscreen(8)
- and logs results.
+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.
-5 - To enable DNSBL lookups, list some DNS blocklist sites in
- main.cf, e.g., "postscreen_dnsbl_sites = zen.spamhaus.org".
- Separate domain names with comma or whitespace.
+[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.
-Note: you must stop and start the master daemon. This is needed
-because the Postfix "pass" master service type did not work reliably
-on all systems.
+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.
-To use the postscreen(8) service to block mail, edit main.cf and
-specify one or more of:
+[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.
-- "postscreen_greet_action = drop", to drop clients that talk before
- their turn. This alone stops about one third of all known-to-be
- illegitimate connections to Wietse's mail server.
+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).
-- "postscreen_hangup_action = drop", to waste no time on clients
- that hang up without sending a command. On Wietse's server, only
- one percent of illegitimate connections behaves like this.
+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.
-- "postscreen_dnsbl_action = drop", to drop clients that are on DNS
- blocklists. Different blocklists cover different client categories.
+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.
-There is also support for permanent blacklists and whitelists; see
-the postscreen(8) manual page for details.
+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).
-Note: right now, postscreen(8) "drop" actions disconnect the client
-without reporting sender and recipient information. In a future
-implementation, the connection may instead be passed to a dummy
-SMTP protocol engine that logs sender and recipient information
-before dropping the connection.
+Major changes - milter
+----------------------
-Incompatibility with snapshot 20090606
-======================================
+[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.
-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 - multi-instance support
+--------------------------------------
-Major changes with snapshot 20090606
-====================================
+[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.
-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
-Wish list:
-
- 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.
-
- It would be nice if the generic dict_cache(3) cache manager
- could postpone process suicide until cache cleanup is
- completed (but that is not possible when postscreen forks
- into the background to finish already-accepted connections,
- and it is not desirable when a host is being shut down).
-
- When postscreen drops a connection, a 521 "greeting" should
- be of the form "521 servername..." and not have an enhanced
- status code. The "521 5.7.1" form can be used after EHLO.
- Of course no spammer is going to complain about Postfix
- SMTP compliance.
-
- Find a place to document all the mail routing mechanisms
- in one place so people can figure out how Postfix works.
-
- owner-listname does not work for shell commands.
-
- Investigate viability of Sendmail socket maps (the moral
- equivalent of tcp_table(5)), and dns maps.
-
- The BCC action is marked "not stable", perhaps because
- people would also expect BCC actions in header/body_checks.
- How much would it take to make the queue file editing code
- generally usable?
-
- Move smtpd_command_filter into smtpd_chat_query() and update
- the session transcript (see smtp_chat_reply() for an example).
-
- Add smtpd_sender_login_maps to proxy_read_maps.
-
- SMTP connection caching without storing connections, to
- improve TLS mail delivery performance.
-
- postscreen has separate socket budgets for whitelisted
- clients and for other clients. If we add a dummy SMTP engine
- then we extend the session length for non-whitelisted clients
- and need to increase the socket budget (or create a new
- budget class, which complicates the user interface).
-
- Should not milter8_mail_event() unset the "hold" default
- reply? Better, the default reply should not be used for
- this purpose.
-
- Unescape the pregreeter's HELO command argument so that
- <CR><LF> don't show up as ??.
-
- Make postscreen logging easier. Always log connect, then log
- why the connection is or is not forwarded.
-
- Don't send MASTER_STAT_TAKEN/MASTER_STAT_AVAIL when a server
- runs with process limit of 1. But this means the master
- never learns that the process is successful and will always
- pause $service_throttle_time before restarting a failed service.
-
- Don't bother maintaining a per-service lockfile when a
- server runs with process limit of 1. The purpose of the
- lockfile is to avoid thundering herd problems when the kernel
- wakes up multiple processes for each new client connection.
-
- Concurrency/speed-matching: invoke a before-queue (smtpd_proxy)
- filter after the entire message is received, so that fewer
- filter processes will be running simultaneously. In some
- parts of the world, after-queue filtering is problematic.
-
- This is different than the MailChannels patented solution
- to multiplex many slow SMTP connections over a few fast
- SMTP connections. We simply postpone opening the connection
- to the filter, and rely on the before-filter SMTP server
- to reject invalid recipients. MailChannels uses one
- connection-to-MTA to discover invalid recipients, receives
- the email message with a potentially reduced bitrate, and
- then uses another connection-to-MTA to deliver the message
- quickly.
-
- Implement PREPEND action for milter_header_checks. Save the
- to-be-prepended text to buffer, then emit it along with the
- new header.
-
- Fix the header_body_checks API, so that the name of the map
- class (e.g. milter_header_checks) is available for logging.
-
- Fix the mime_state and header_body_checks APIs, so that
- they use VSTRINGs. This simplifies REPLACE actions.
-
- Update FILTER_README for multi-instance support, and rename
- the old document to FILTER_LEGACY_README.
-
- Need to sign delivery status notifications, to avoid surprises
- when eventually people start enforcing DKIM etc. signatures.
-
- Either document or remove the internal_mail_filter_classes
- feature (it's disabled by default).
-
- "postconf -N" option to print user-defined parameter names
- (these have no defaults, since they exist only when
- specified in main.cf or with "-o name=value").
-
- Make the "unknown recipient" test configurable as
- first|last|never, with "yes"=="last" for backwards
- compatibility. The "first" setting is good for performance
- (stress=yes) when all users are defined in local files; but
- it may perform worse when users are in networked tables.
-
- Cleanup: make DNSBL query format configurable beyond the
- client's reversed IP address.
-
- With 'final delivery' in the LMTP client, need an option
- to also add delivered-to and other pipe(8) features. This
- requires making mail_copy() functionality available in
- non-mailbox context.
-
- Cleanup: modernize the "add missing From: header" code, to
- ``phrase <addr>'' form. Most likely, quote the entire phrase
- if it contains any text that is special, then rfc822_externalize
- the whole thing.
-
- SMTP server: make the server_addr and server_port available
- to policy server, Dovecot, and perhaps Milters.
-
- Med: local and remote source port and IP address for smtpd
- policy hook.
-
- Maybe change maps_rbl_reject_code default to 521, and
- update wording in STRESS_README.
-
- Encapsulate time_t comparisons so that they can be made
- system dependent (use difftime() where available).
-
- Encapsulate time_t conversions (e.g. REC_TYPE_TIME) so that
- they can be made system dependent.
-
- Plan for time_t larger than long, or wait for LP64 to
- dominate the world?
-
- Make "AUTH=<>" appendage to MAIL FROM configurable, enabled
- by default.
-
- To support ternary operator without a huge parsing effort,
- consider ${value?{xxx}:{yyy}} where ${name} is existing
- syntax, and where ?{text} and :{text} are new syntax that
- is unlikely to break existing configurations. Or perhaps
- it's just too ugly.
-
- Write delivery rate delay example (which _README?) and auth
- failure cache example (SASL_README). Then include them in
- SOHO_README.
-
- Look for alternatives for the use of non_smtpd_milters.
- This involves some way to force local submissions to go
- through a local SMTP client and server, without triggering
- "mail loops back to myself" false alarms. The advantage is
- that it makes smtpd_mumble_restrictions available for local
- and remote mail; the disadvantage is that it makes local
- submissions more dependent on networking. One possibility
- is to use "pickup -o content_filter=smtp:127.0.0.1:10025",
- or a dedicated SMTP client/server on UNIX-domain sockets;
- we could also decide to always suppress "mail loop" detection
- for loopback connections. Another option is to have the
- pickup or cleanup server drive an SMTP client directly;
- this would require extension of the mail_stream() interface,
- plus a way to handle bounced/deferred recipients intelligently,
- but it would be at odds with Postfix design where delivery
- agents access queue files directly; exposing delivery agents
- to raw queue files violates another Postfix design principle.
-
- Consolidate duplicated code in *_server_accept_{pass,inet}().
-
- Consolidate duplicated code in {inet,unix,upass}_trigger.c.
-
- In the SMTP client, handle 421 replies in smtp_loop() by
- having the input function raise a flag after detecting 421
- (kill connection caching and be sure to do the right thing
- with RSET probes), leave the smtp_loop() per-command reply
- handlers unchanged, and have the smtp_loop() reader loop
- bail out with smtp_site_fail("server disconnected after
- %s", where), but only in the case that it isn't already in
- the final state. But first we need to clean up the handling
- of do/don't cache, expired, bad and dead sessions.
-
- Combine smtpd_peer.c and qmqpd_peer.c into a single function
- that produces a client context object, and provide attribute
- print/scan routines that pass these client context objects
- around. With this, we no longer have to update multiple
- pieces of code when a client attribute is added. Ditto for
- SASL and TLS context.
-
- Make TLS_BIO_BUFSIZE run-time adjustable, to future-proof
- Postfix for remote connections with MSS > 8 kbytes.
-
- Don't log "warning: XXXXX: undeliverable postmaster
- notification discarded" for spam from outside.
-
- Really need a cleanup driver that allows testing against
- Milter applications instead of synthetic events. This would
- have to provide stubs for clients that talk to Postfix
- daemon processes. See if this approach can also be used for
- other daemons.
-
- smtpd(8) exempts $address_verify_sender from access controls,
- but it doesn't know whether cleanup(8) or delivery agents
- modify the sender. Would it be possible to "calibrate" this
- exemption, perhaps by having delivery agents pass the probe
- sender to the verify server, keeping in mind that the probe
- sender may differ per delivery agent due to output rewriting.
-
- Update attr_print/scan() so they can send/receive file
- descriptors. This simplifies kludgy code in many daemons.
-
- Would there be a problem adding $smtpd_mumble_restrictions
- and $smtpd_sender_login_maps to the default proxy_read_maps
- settings?
-
- Remove defer(8) and trace(8) references and man pages. These
- are services not program names. On the other hand we have
- man pages for lmtp(8) and smtp(8), but not for relay(8).
- Likewise, retry(8) does not have a man page.
-
- Bind all deliveries to the same local delivery process,
- making Postfix perform as poorly as monolithic mailers, but
- giving a possibility to eliminate duplicate deliveries.
-
- Maybe declare loop when resolve_local(mxhost) is true?
-
- Update message content length when adding/removing headers.
-
- Need scache size limit.
-
- Make postcat header/body aware so people can grep headers.
- What headers? primary, mime, nested? What body? Does it
- include the mime and attached headers?
-
- REDIRECT should override original recipient info, and
- probably override DSN as well.
-
- Find out if with Sendmail, a Milter "add recipient" request
- results in NOTIFY=NONE as Postfix does now.
-
- Update FILTER_README with mailing list suggestions to tag
- with a badness indicator and then filter down-stream.
-
- Make null local-part handling configurable: either expand
- into mailer-daemon (current bahavior) or disallow (strict
- behavior, currently implemented only in the SMTP server).
-
- The type of var_message_limit (and other file size/offset
- configuration parameters or internal protocol attributes)
- should be changed from int to off_t. This also requires
- checking all expressions in which var_message_limit etc.
- appears: qmqpd, netstring, deliver_request, ...
-
- Add M flag (enable multi-recipient delivery) to pipe daemon.
-
- The usage of TLScontext->cache_type is unclear. It specifies
- a TLS session cache type (smtpd, smtp, or lmtp), but it is
- sometimes used as an indicator that TLS session caching is
- unavailable. In reality, that decision is made by not
- registering call-back functions for cache maintenance.
-
- Postfix TLS library code should copy any strings that it
- receives from the application, instead of passing them
- around as pointers. TLScontext->cache_type is a case in
- point.
-
- Are transport:nexthop null fields the same as in the case
- of default_transport etc. parameters?
-
- Don't lose bits when converting st_dev into maildir file
- name. It's 64 bits on Linux. Found with the BEAM source
- code analyzer. Is this really a problem, or are they just
- using 64 bits for upwards compatibility with LP64 systems?
-
- Do or don't introduce unknown_reverse_client_reject_code.
-
- Check that "UINT32 == unsigned int" choice is ok (i.e. LP64
- UNIX).
-
- Tempfail when a Milter application tries to negotiate content
- access, while it is configured in an SMTP server that runs
- before the smtpd_proxy filter.
-
- Log DSN original recipient when rejecting mail.
-
- Keep whitespace between label and ":"?
-
- Make the map case folding/locking options configurable, if
- not at run-time then at least at compile time so we get
- consistent behavior across applications.
-
- Investigate what it would take to eliminate oqmgr, and to
- make the old behavior configurable in a unified queue
- manager. This would shave another 2.7 KLOC from the source
- footprint.
-
- Document the case folding strategy for match_list like
- features.
-
- Eliminate the (incoming,deferred)->active rename operation.
- This requires an in-memory hash of queue file names to avoid
- duplicate open() operations.
-
- Softbounce fallback-to-ISP for SOHO users. This heuristic
- assumes that when direct-to-MX delivery fails with 5XX,
- delivery via the ISP may still succeed. This could be
- implemented by enabling soft bounces for destinations other
- than the smtp_fallback_relay. So the only benefit of this
- over the existing soft_bounce feature is that it has no
- effect on smtp_fallback_relay deliveries.
-
- Centralize main.cf parameter input so that defaults work
- consistently. What about parameter names that are prefixed
- with mail delivery transport names?
-
- Fix default time unit handling so that we can have a default
- bounce lifetime of $maximal_queue_lifetime, without causing
- panics when a non-default maximal_queue_lifetime setting
- includes no time unit.
-
- After the 20051222 ISASCII paranoia, lowercase() lowercases
- ASCII text only.
-
- Privacy: remove local command/pathname details from remote
- delivery status reports, and log them via local msg_warn().
-
- Is it safe to cache a connection after it has been used for
- more than some number of address verification probes?
-
- Try to recognize that Resent- headers appear in blocks,
- newest block first. But don't break on incorrect header
- block organization.
-
- Hard limits on cache sizes (anvil, specifically).
-
- Laptop friendliness: make the qmgr remember when the next
- deferred queue scan needs to be done, and have the pickup
- server stat() the maildrop directory before searching it.
-
- Low: replace_sender/replace_recipient actions in access
- maps, so they can be used in policy servers?
-
- Low: configurable order of local(8) delivery methods.
-
- Med: smtp_connect_timeout_budget (default: 3x smtp_connect_timeout)
- to limit the total time spent trying to connect.
-
- Med: transform IPv4-in-IPv6 address literals to IPv4 form
- when comparing against local IP addresses?
-
- Med: transform IPv4-in-IPv6 address literals to IPv4 form
- when eliminating MX mailer loops?
-
- Med: Postfix requires [] around IPv6 address information
- in match lists such as mynetworks, debug_peer_list etc.,
- but the [] must not be specified in access(5) maps. Other
- places don't care. For now, this gotcha is documented in
- IPV6_README and in postconf(5) with each feature that may
- use IPv6 address information. The general recommendation
- is not to use [] unless absolutely necessary.
-
- Med: the partial address matching of IPv6 addresses in
- access(5) maps is a bit lame: it repeatedly truncates the
- last ":octetpair" from the printable address representation
- until a match is found or until truncation is no longer
- possible. Since one or more ":" are usually omitted from
- the printable IPv6 address representation, this does not
- really try all the possibilities that one might expect to
- be tried. For now, this gotcha is documented in access(5).
-
- Low: reject HELO with any domain name or IP address that
- this MTA is the final destination for.
-
- Low: should the Delivered-To: test in local(8) be configurable?
-
- Low: make mail_addr_find() lookup configurable.
-
- Low: update events.c so that 1-second timer requests do not
- suffer from rounding errors. This is needed for 1-second
- SMTP session caching time limits. A 1-second interval would
- become arbitrarily short when an event is scheduled just
- before the current second rolls over.
-
- Low: configurable internal/system locking method.
-
- Low: add INSTALL section for pre-existing Postfix systems.
-
- Low: add INSTALL section for pre-existing RPM Postfixes.
-
- Low: disallow smtpd_recipient_limit < 100 (the RFC minimum).
-
- Low: noise filter: allow smtp(8) to retry immediately if
- all MXes return a quick ECONNRESET or 4xx reply during the
- initial handshake. Retry once? How many times?
-
- Low: make post-install a "postfix-only script" so it can
- take data from the environment instead of main.cf.
-
- Low: randomize deferred mail backoff.
-
- Med: separate ulimit for delivery to command?
-
- Med: postsuper -r should do something with recipients in
- bounce logfiles, to make sure the sender will be notified.
- To be perfectly safe, no process other than the queue manager
- should move a queue file away from the active queue.
-
- This could involve tagging a queue file, and use up another
- permission bit (postsuper tags a "hot" file, qmgr requeues it).
-
- Low: postsuper re-run after renaming files, but only a
- limited number of times.
-
- Low: smtp-source may block when sending large test messages.
-
- Med: find a way to log the sender address when MAIL FROM
- is rejected due to lack of disk space.
-
- Low: revise other local delivery agent duplicate filters.
-
- Low: all table lookups should consistently use internalized
- (unquoted) or externalized (quoted) forms as lookup keys.
- smtpd, qmgr, local, etc. use unquoted address forms as keys.
- cleanup uses quoted forms.
-
- Low: have a configurable list of errno values for mailbox
- or maildir delivery that result in deferral rather than
- bouncing mail. What about "killed by signal" exits?
-
- Low: after reorganizing configuration parameters, add flags
- to all parameters whose value can be read from file.
-
- Medium: need in-process caching for map lookups. LDAP servers
- seem to need this in particular. Need a way to expire cached
- results that are too old.
-
- Low: generic showq protocol, to allow for more intelligent
- processing than just mailq. Maybe marry this with postsuper.
-
- Low: default domain for appending to unqualified recipients,
- so that unqualified names can be delivered locally.
-
- Low: The $process_id_directory setting is not used anywhere
- in Postfix. Problem reported by Michael Smith, texas.net.
- This should be documented, or better, the code should warn
- about attempts to set read-only parameters.
-
- Low: postconf -e edits parameters that postconf won't list.
-
- Low: while converting 8bit text to quoted-printable, perhaps
- use =46rom to avoid having to produce >From when delivering
- to mailbox.
-
- virtual_mailbox_path expression like forward_path, so that
- people can specify prefix and suffix.
# (yes) (yes) (yes) (never) (100)
# ==========================================================================
smtp inet n - n - - smtpd
-#smtp inet n - n - 1 postscreen
-#smtpd pass - - n - - smtpd
-#dnsblog unix - - n - 0 dnsblog
#submission inet n - n - - smtpd
# -o smtpd_tls_security_level=encrypt
# -o smtpd_sasl_auth_enable=yes
EOF
}
- # Postfix 2.7.
- # Add missing postscreen service to master.cf.
-
- grep '^#*smtp.*postscreen' $config_directory/master.cf >/dev/null || {
- echo Editing $config_directory/master.cf, adding missing entry for postscreen TCP service
- cat >>$config_directory/master.cf <<EOF || exit 1
-#smtp inet n - n - 1 postscreen
-EOF
- }
-
- # Postfix 2.7.
- # Add missing smtpd (unix-domain) service to master.cf.
-
- grep '^#*smtpd.*smtpd' $config_directory/master.cf >/dev/null || {
- echo Editing $config_directory/master.cf, adding missing entry for smtpd unix-domain service
- cat >>$config_directory/master.cf <<EOF || exit 1
-#smtpd pass - - n - - smtpd
-EOF
- }
-
- # Postfix 2.7.
- # Add temporary dnsblog (unix-domain) service to master.cf.
-
- grep '^#*dnsblog.*dnsblog' $config_directory/master.cf >/dev/null || {
- echo Editing $config_directory/master.cf, adding missing entry for dnsblog unix-domain service
- cat >>$config_directory/master.cf <<EOF || exit 1
-#dnsblog unix - - n - 0 dnsblog
-EOF
- }
-
# Report (but do not remove) obsolete files.
test -n "$obsolete" && {
$daemon_directory/bounce:f:root:-:755
$daemon_directory/cleanup:f:root:-:755
$daemon_directory/discard:f:root:-:755
-$daemon_directory/dnsblog:f:root:-:755
$daemon_directory/error:f:root:-:755
$daemon_directory/flush:f:root:-:755
#$daemon_directory/lmtp:f:root:-:755
$daemon_directory/postfix-script:f:root:-:755
$daemon_directory/postfix-wrapper:f:root:-:755
$daemon_directory/postmulti-script:f:root:-:755
-$daemon_directory/postscreen:f:root:-:755
$daemon_directory/proxymap:f:root:-:755
$daemon_directory/qmgr:f:root:-:755
$daemon_directory/qmqpd:f:root:-:755
$manpage_directory/man8/anvil.8:f:root:-:644
$manpage_directory/man8/defer.8:f:root:-:644
$manpage_directory/man8/discard.8:f:root:-:644
-$manpage_directory/man8/dnsblog.8:f:root:-:644
$manpage_directory/man8/error.8:f:root:-:644
$manpage_directory/man8/flush.8:f:root:-:644
$manpage_directory/man8/lmtp.8:f:root:-:644
$manpage_directory/man8/oqmgr.8:f:root:-:644:
$manpage_directory/man8/pickup.8:f:root:-:644
$manpage_directory/man8/pipe.8:f:root:-:644
-$manpage_directory/man8/postscreen.8:f:root:-:644
$manpage_directory/man8/proxymap.8:f:root:-:644
$manpage_directory/man8/qmgr.8:f:root:-:644
$manpage_directory/man8/qmqpd.8:f:root:-:644
$html_directory/cleanup.8.html:f:root:-:644
$html_directory/defer.8.html:h:$html_directory/bounce.8.html:-:644
$html_directory/discard.8.html:f:root:-:644
-$html_directory/dnsblog.8.html:f:root:-:644
$html_directory/error.8.html:f:root:-:644
$html_directory/flush.8.html:f:root:-:644
$html_directory/generics.5.html:f:root:-:644:o
$html_directory/postmap.1.html:f:root:-:644
$html_directory/postmulti.1.html:f:root:-:644
$html_directory/postqueue.1.html:f:root:-:644
-$html_directory/postscreen.8.html:f:root:-:644
$html_directory/postsuper.1.html:f:root:-:644
$html_directory/qshape.1.html:f:root:-:644
$html_directory/proxymap.8.html:f:root:-:644
<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
showq.8.html smtp.8.html smtpd.8.html trivial-rewrite.8.html \
oqmgr.8.html spawn.8.html flush.8.html virtual.8.html qmqpd.8.html \
trace.8.html verify.8.html proxymap.8.html anvil.8.html \
- scache.8.html discard.8.html tlsmgr.8.html postscreen.8.html \
- dnsblog.8.html
+ scache.8.html discard.8.html tlsmgr.8.html
COMMANDS= mailq.1.html newaliases.1.html postalias.1.html postcat.1.html \
postconf.1.html postfix.1.html postkick.1.html postlock.1.html \
postlog.1.html postdrop.1.html postmap.1.html postmulti.1.html \
<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>
+++ /dev/null
-<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
- "http://www.w3.org/TR/html4/loose.dtd">
-<html> <head>
-<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
-<title> Postfix manual - dnsblog(8) </title>
-</head> <body> <pre>
-DNSBLOG(8) DNSBLOG(8)
-
-<b>NAME</b>
- dnsblog - Postfix DNS blocklist logger
-
-<b>SYNOPSIS</b>
- <b>dnsblog</b> [generic Postfix daemon options]
-
-<b>DESCRIPTION</b>
- The <a href="dnsblog.8.html"><b>dnsblog</b>(8)</a> server implements an ad-hoc DNS blocklist
- lookup service that will eventually be replaced by an UDP
- client that is built directly into the <a href="postscreen.8.html"><b>postscreen</b>(8)</a>
- server.
-
- With each connection, the <a href="dnsblog.8.html"><b>dnsblog</b>(8)</a> server receives a DNS
- blocklist domain name and an IP address. If the address is
- listed under the DNS blocklist, the <a href="dnsblog.8.html"><b>dnsblog</b>(8)</a> server logs
- the match and replies with the query arguments plus a non-
- zero status. Otherwise it replies with the query argu-
- ments plus a zero status. Finally, The <a href="dnsblog.8.html"><b>dnsblog</b>(8)</a> server
- closes the connection.
-
-<b>DIAGNOSTICS</b>
- Problems and transactions are logged to <b>syslogd</b>(8).
-
-<b>CONFIGURATION PARAMETERS</b>
- Changes to <a href="postconf.5.html"><b>main.cf</b></a> are picked up automatically, as <b>dns-</b>
- <b>blog</b>(8) processes run for only a limited amount of time.
- Use the command "<b>postfix reload</b>" to speed up a change.
-
- The text below provides only a parameter summary. See
- <a href="postconf.5.html"><b>postconf</b>(5)</a> for more details including examples.
-
- <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
- The default location of the Postfix <a href="postconf.5.html">main.cf</a> and
- <a href="master.5.html">master.cf</a> configuration files.
-
- <b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b>
- How much time a Postfix daemon process may take to
- handle a request before it is terminated by a
- built-in watchdog timer.
-
- <b><a href="postconf.5.html#postscreen_dnsbl_sites">postscreen_dnsbl_sites</a> (empty)</b>
- Optional list of DNS blocklist domains.
-
- <b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b>
- The time limit for sending or receiving information
- over an internal communication channel.
-
- <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b>
- The process ID of a Postfix command or daemon
- process.
-
- <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b>
- The process name of a Postfix command or daemon
- process.
-
- <b><a href="postconf.5.html#queue_directory">queue_directory</a> (see 'postconf -d' output)</b>
- The location of the Postfix top-level queue direc-
- tory.
-
- <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
- The syslog facility of Postfix logging.
-
- <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
- The mail system name that is prepended to the
- process name in syslog records, so that "smtpd"
- becomes, for example, "postfix/smtpd".
-
-<b>SEE ALSO</b>
- <a href="smtpd.8.html">smtpd(8)</a>, Postfix SMTP server
- <a href="postconf.5.html">postconf(5)</a>, configuration parameters
- syslogd(5), system logging
-
-<b>LICENSE</b>
- The Secure Mailer license must be distributed with this
- software.
-
-<b>HISTORY</b>
- This service is temporary with Postfix version 2.7.
-
-<b>AUTHOR(S)</b>
- Wietse Venema
- IBM T.J. Watson Research
- P.O. Box 704
- Yorktown Heights, NY 10598, USA
-
- DNSBLOG(8)
-</pre> </body> </html>
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>
<p> This feature is available in Postfix 2.6 and later. </p>
-</DD>
-
-<DT><b><a name="postscreen_blacklist_action">postscreen_blacklist_action</a>
-(default: continue)</b></DT><DD>
-
-<p> The action that <a href="postscreen.8.html">postscreen(8)</a> takes when an SMTP client is
-permanently blacklisted with the <a href="postconf.5.html#postscreen_blacklist_networks">postscreen_blacklist_networks</a>
-parameter. Specify one of the following: </p>
-
-<dl>
-
-<dt> continue </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 triggers a PREGREET or HANGUP
-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>
-
-<dt> drop </dt>
-
-<dd> Drop the connection immediately with a 521 SMTP reply, without
-reporting PREGREET, HANGUP or DNSBL results. </dd>
-
-</dl>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-
-</DD>
-
-<DT><b><a name="postscreen_blacklist_networks">postscreen_blacklist_networks</a>
-(default: empty)</b></DT><DD>
-
-<p> Network addresses that are permanently blacklisted; see the
-<a href="postconf.5.html#postscreen_blacklist_action">postscreen_blacklist_action</a> parameter for possible actions. This
-parameter uses the same address syntax as the <a href="postconf.5.html#mynetworks">mynetworks</a> parameter.
-The blacklist has higher precedence than whitelists. This feature
-never uses the remote SMTP client hostname. </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-
-</DD>
-
-<DT><b><a name="postscreen_cache_cleanup_interval">postscreen_cache_cleanup_interval</a>
-(default: 12h)</b></DT><DD>
-
-<p> The amount of time between <a href="postscreen.8.html">postscreen(8)</a> cache cleanup runs.
-Cache cleanup increases the load on the cache database and should
-therefore not be run frequently. This feature requires that the
-cache database supports the "delete" and "sequence" operators.
-Specify a zero interval to disable cache cleanup. </p>
-
-<p> After each cache cleanup run, the <a href="postscreen.8.html">postscreen(8)</a> daemon logs the
-number of entries that were retained and dropped. A cleanup run is
-logged as "partial" when the daemon terminates early after "<b>postfix
-reload</b>", "<b>postfix stop</b>", or no requests for $<a href="postconf.5.html#max_idle">max_idle</a>
-seconds. </p>
-
-<p> Time units: s (seconds), m (minutes), h (hours), d (days), w
-(weeks). </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-
-</DD>
-
-<DT><b><a name="postscreen_cache_map">postscreen_cache_map</a>
-(default: btree:$<a href="postconf.5.html#data_directory">data_directory</a>/ps_whitelist)</b></DT><DD>
-
-<p> Persistent storage for the <a href="postscreen.8.html">postscreen(8)</a> server decisions. </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-
-</DD>
-
-<DT><b><a name="postscreen_cache_retention_time">postscreen_cache_retention_time</a>
-(default: 1d)</b></DT><DD>
-
-<p> The amount of time that <a href="postscreen.8.html">postscreen(8)</a> will cache an expired
-temporary whitelist entry before it is removed. This prevents clients
-from being logged as "NEW" just because their cache entry expired
-an hour ago. </p>
-
-<p> Time units: s (seconds), m (minutes), h (hours), d (days), w
-(weeks). </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-
-</DD>
-
-<DT><b><a name="postscreen_cache_ttl">postscreen_cache_ttl</a>
-(default: 1d)</b></DT><DD>
-
-<p> The amount of time that <a href="postscreen.8.html">postscreen(8)</a> will cache a decision for
-a specific SMTP client IP address. During this time, the client IP
-address is excluded from tests. If possible, expired decisions are
-renewed automatically. Specify a non-zero time value (an integral
-value plus an optional one-letter suffix that specifies the time
-unit). </p>
-
-<p> Time units: s (seconds), m (minutes), h (hours), d (days), w
-(weeks). </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-
-</DD>
-
-<DT><b><a name="postscreen_dnsbl_action">postscreen_dnsbl_action</a>
-(default: continue)</b></DT><DD>
-
-<p>The action that <a href="postscreen.8.html">postscreen(8)</a> takes when an SMTP client is listed
-at the DNS blocklist domains specified with the <a href="postconf.5.html#postscreen_dnsbl_sites">postscreen_dnsbl_sites</a>
-parameter. Specify one of the following: </p>
-
-<dl>
-
-<dt> continue </dt>
-
-<dd> Forward the connection to a real SMTP server process. </p>
-
-<dt> drop </dt>
-
-<dd> Drop the connection with a 521 SMTP reply. </dd>
-
-</dl>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-
-</DD>
-
-<DT><b><a name="postscreen_dnsbl_sites">postscreen_dnsbl_sites</a>
-(default: empty)</b></DT><DD>
-
-<p>Optional list of DNS blocklist domains. When the list is non-enpty,
-the <a href="dnsblog.8.html">dnsblog(8)</a> daemon will query these domains with the IP addresses
-of non-whitelisted <a href="postscreen.8.html">postscreen(8)</a> clients. Specify a list of domain
-names, separated by comma or whitespace. </p>
-
-
-</DD>
-
-<DT><b><a name="postscreen_greet_action">postscreen_greet_action</a>
-(default: continue)</b></DT><DD>
-
-<p>The action that <a href="postscreen.8.html">postscreen(8)</a> takes when an SMTP client speaks
-before its turn within the time specified with the <a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a>
-parameter. Specify one of the following: </p>
-
-<dl>
-
-<dt> continue </dt>
-
-<dd> Continue waiting until the <a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a> time has
-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>
-
-<dt> drop </dt>
-
-<dd> Drop the connection immediately with a 521 SMTP reply, without
-examining DNSBL lookup results. </dd>
-
-</dl>
-
-<p> In either case, <a href="postscreen.8.html">postscreen(8)</a> will not whitelist the SMTP client
-IP address. </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-
-</DD>
-
-<DT><b><a name="postscreen_greet_banner">postscreen_greet_banner</a>
-(default: $<a href="postconf.5.html#smtpd_banner">smtpd_banner</a>)</b></DT><DD>
-
-<p> The <i>text</i> in the optional "220-<i>text</i>..." server
-response that
-<a href="postscreen.8.html">postscreen(8)</a> sends ahead of the real Postfix SMTP server's "220
-text..." response, in an attempt to confuse bad SMTP clients so
-that they speak before their turn (pre-greet). Specify an empty
-value to disable this feature. </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-
-</DD>
-
-<DT><b><a name="postscreen_greet_wait">postscreen_greet_wait</a>
-(default: 4s)</b></DT><DD>
-
-<p> The amount of time that <a href="postscreen.8.html">postscreen(8)</a> will wait for an SMTP
-client to send a command before its turn, and for DNS blocklist
-lookup results to arrive. This is done only when the SMTP client
-IP address is not permanently whitelisted, and when it has no cached
-decision. Specify a non-zero time value (an integral value plus
-an optional one-letter suffix that specifies the time unit). </p>
-
-<p> Time units: s (seconds), m (minutes), h (hours), d (days), w
-(weeks). </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-
-</DD>
-
-<DT><b><a name="postscreen_hangup_action">postscreen_hangup_action</a>
-(default: continue)</b></DT><DD>
-
-<p>The action that <a href="postscreen.8.html">postscreen(8)</a> takes when an SMTP client disconnects
-without sending data, within the time specified with the
-<a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a> parameter. Specify one of the following:
-</p>
-
-<dl>
-
-<dt> continue </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>
-
-<dt> drop </dt>
-
-<dd> Drop the connection immediately, without reporting DNSBL lookup
-results. </dd>
-
-</dl>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-
-</DD>
-
-<DT><b><a name="postscreen_post_queue_limit">postscreen_post_queue_limit</a>
-(default: $<a href="postconf.5.html#default_process_limit">default_process_limit</a>)</b></DT><DD>
-
-<p> The number of clients that can be waiting for service from a
-real SMTP server process. When this queue is full, all clients will
-receive a 421 reponse. </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-
-</DD>
-
-<DT><b><a name="postscreen_pre_queue_limit">postscreen_pre_queue_limit</a>
-(default: $<a href="postconf.5.html#default_process_limit">default_process_limit</a>)</b></DT><DD>
-
-<p> The number of non-whitelisted clients that can be waiting for
-a decision whether they will receive service from a real SMTP server
-process. When this queue is full, all non-whitelisted clients will
-receive a 421 reponse. </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-
-</DD>
-
-<DT><b><a name="postscreen_whitelist_networks">postscreen_whitelist_networks</a>
-(default: $<a href="postconf.5.html#mynetworks">mynetworks</a>)</b></DT><DD>
-
-<p> Network addresses that are permanently whitelisted, and that
-will not be subjected to <a href="postscreen.8.html">postscreen(8)</a> checks. This parameter uses
-the same address syntax as the <a href="postconf.5.html#mynetworks">mynetworks</a> parameter. This feature
-never uses the remote SMTP client hostname. </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-
</DD>
<DT><b><a name="prepend_delivered_header">prepend_delivered_header</a>
<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>
</pre>
-</DD>
-
-<DT><b><a name="smtpd_service">smtpd_service</a>
-(default: smtpd)</b></DT><DD>
-
-<p> The internal service that <a href="postscreen.8.html">postscreen(8)</a> forwards allowed
-connections to. In a future version there may be different
-classes of SMTP service. </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-
</DD>
<DT><b><a name="smtpd_soft_error_limit">smtpd_soft_error_limit</a>
<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>
<li> <a href="pipe.8.html">pipe(8)</a>, deliver mail to non-Postfix command
-<li> <a href="postscreen.8.html">postscreen(8)</a>, Postfix SMTP triage server
-
<li> <a href="proxymap.8.html">proxymap(8)</a>, Postfix lookup table proxy server
<li> <a href="qmgr.8.html">qmgr(8)</a>, Postfix queue manager
<a href="qmgr.8.html">oqmgr(8)</a>, old Postfix queue manager
<a href="pickup.8.html">pickup(8)</a>, Postfix local mail pickup
<a href="pipe.8.html">pipe(8)</a>, deliver mail to non-Postfix command
- <a href="postscreen.8.html">postscreen(8)</a>, Postfix SMTP triage server
<a href="proxymap.8.html">proxymap(8)</a>, Postfix lookup table proxy server
<a href="qmgr.8.html">qmgr(8)</a>, Postfix queue manager
<a href="qmqpd.8.html">qmqpd(8)</a>, Postfix QMQP server
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.
+++ /dev/null
-<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
- "http://www.w3.org/TR/html4/loose.dtd">
-<html> <head>
-<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
-<title> Postfix manual - postscreen(8) </title>
-</head> <body> <pre>
-POSTSCREEN(8) POSTSCREEN(8)
-
-<b>NAME</b>
- postscreen - Postfix SMTP triage server
-
-<b>SYNOPSIS</b>
- <b>postscreen</b> [generic Postfix daemon options]
-
-<b>DESCRIPTION</b>
- The Postfix <a href="postscreen.8.html"><b>postscreen</b>(8)</a> server performs triage on multi-
- ple inbound SMTP connections in parallel. While
- <a href="postscreen.8.html"><b>postscreen</b>(8)</a> keeps zombies and other bogus clients away
- from Postfix SMTP server processes, more Postfix SMTP
- server processes remain available for legitimate clients.
-
-<b>GENERAL OPERATION</b>
- The triage process involves a number of tests, in the
- order as described below. Some tests introduce a delay of
- a few seconds. Once a client passes all tests, its IP
- address is temporarily excluded from the tests, typically
- for 24 hours. This minimizes the impact of the tests on
- legitimate mail clients.
-
- After logging the result of its tests, <a href="postscreen.8.html"><b>postscreen</b>(8)</a> by
- default forwards all connections to a real SMTP server
- process. This mode is useful for non-destructive testing.
-
- In a typical production setting, <a href="postscreen.8.html"><b>postscreen</b>(8)</a> is config-
- ured to disconnect clients that fail some tests. A future
- implementation may pass the connection to a dummy SMTP
- protocol engine that logs sender and recipient information
- before hanging up.
-
- Note: <a href="postscreen.8.html"><b>postscreen</b>(8)</a> is not an SMTP proxy; this is inten-
- tional. The purpose is to prioritize legitimate clients
- with as little overhead as possible.
-
-<b>1. PERMANENT WHITELIST TEST</b>
- The <a href="postconf.5.html#postscreen_whitelist_networks">postscreen_whitelist_networks</a> parameter (default:
- $<a href="postconf.5.html#mynetworks">mynetworks</a>) specifies a permanent whitelist for SMTP
- client IP addresses.
-
- When the SMTP client address matches the permanent
- whitelist, this is logged as:
-
- <b>WHITELISTED</b> <i>address</i>
-
- The action is not configurable: immediately forward the
- connection to a real SMTP server process.
-
-<b>2. PERMANENT BLACKLIST TEST</b>
- The <a href="postconf.5.html#postscreen_blacklist_networks">postscreen_blacklist_networks</a> parameter (default:
- empty) specifies a permanent blacklist for SMTP client IP
- addresses. The address syntax is as with <a href="postconf.5.html#mynetworks">mynetworks</a>.
-
- When the SMTP client address matches the permanent black-
- list, this is logged as:
-
- <b>BLACKLISTED</b> <i>address</i>
-
- The <a href="postconf.5.html#postscreen_blacklist_action">postscreen_blacklist_action</a> parameter specifies the
- action that is taken next:
-
- <b>continue</b> (default)
- Continue with the SMTP GREETING PHASE TESTS below.
-
- <b>drop</b> Drop the connection immediately with a 521 SMTP
- reply. In a future implementation, the connection
- may instead be passed to a dummy SMTP protocol
- engine that logs sender and recipient information.
-
-<b>3. TEMPORARY WHITELIST TEST</b>
- The <a href="postscreen.8.html"><b>postscreen</b>(8)</a> daemon maintains a <i>temporary</i> whitelist
- for SMTP client IP addresses that have passed all the
- tests described below. The <a href="postconf.5.html#postscreen_cache_map">postscreen_cache_map</a> parameter
- specifies the location of the temporary whitelist. The
- temporary whitelist is not used for SMTP client addresses
- that appear on the <i>permanent</i> blacklist or whitelist.
-
- When the SMTP client address appears on the temporary
- whitelist, this is logged as:
-
- <b>PASS OLD</b> <i>address</i>
-
- The action is not configurable: immediately forward the
- connection to a real SMTP server process. The client is
- excluded from further tests until its temporary whitelist
- entry expires, as controlled with the <a href="postconf.5.html#postscreen_cache_ttl">postscreen_cache_ttl</a>
- parameter. Expired entries are silently renewed if possi-
- ble.
-
-<b>4. SMTP GREETING PHASE TESTS</b>
- The <a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a> parameter specifies a time
- interval during which <a href="postscreen.8.html"><b>postscreen</b>(8)</a> runs a number of tests
- in parallel. These tests are described below, and are run
- before the client may see the real SMTP server's "220
- text..." server greeting.
-
- When the SMTP client passes all greeting-phase tests, this
- is logged as:
-
- <b>PASS NEW</b> <i>address</i>
-
- The action is to forward the connection to a real SMTP
- server process and to create a temporary whitelist entry
- that excludes the client IP address from further tests
- until the temporary whitelist entry expires, as controlled
- with the <a href="postconf.5.html#postscreen_cache_ttl">postscreen_cache_ttl</a> parameter.
-
- In a future implementation, the connection may first be
- passed to a dummy SMTP protocol engine that implements
- more protocol tests including greylisting, before the
- client is allowed to talk to a real SMTP server process.
-
-<b>4A. PREGREET TEST</b>
- The <a href="postconf.5.html#postscreen_greet_banner">postscreen_greet_banner</a> parameter specifies the <i>text</i>
- portion of a "220-<i>text</i>..." teaser banner (default:
- $<a href="postconf.5.html#smtpd_banner">smtpd_banner</a>). The <a href="postscreen.8.html"><b>postscreen</b>(8)</a> daemon sends this
- before the <a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a> timer is started. The
- purpose of the teaser banner is to confuse SPAM clients so
- that they speak before their turn. It has no effect on
- SMTP clients that correctly implement the protocol.
-
- To avoid problems with broken SMTP engines in network
- appliances, either exclude them from all tests with the
- <a href="postconf.5.html#postscreen_whitelist_networks">postscreen_whitelist_networks</a> feature or else specify an
- empty <a href="postconf.5.html#postscreen_greet_banner">postscreen_greet_banner</a> value to disable the
- "220-text..." teaser banner.
-
- When an SMTP client sends a command before the
- <a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a> time has elapsed, this is logged as:
-
- <b>PREGREET</b> <i>count</i> <b>after</b> <i>time</i> <b>from</b> <i>address text...</i>
-
- Translation: the client at <i>address</i> sent <i>count</i> bytes before
- its turn to speak, and this happened <i>time</i> seconds after
- the <a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a> timer was started. The <i>text</i> is
- what the client sent (truncated to 100 bytes, and with
- non-printable characters replaced with "?").
-
- The <a href="postconf.5.html#postscreen_greet_action">postscreen_greet_action</a> parameter specifies the action
- that is taken next:
-
- <b>continue</b> (default)
- Wait until the <a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a> time has
- elapsed, then report DNSBL lookup results if appli-
- cable. Either perform DNSBL-related actions or for-
- ward the connection to a real SMTP server process.
-
- <b>drop</b> Drop the connection immediately with a 521 SMTP
- reply. In a future implementation, the connection
- may instead be passed to a dummy SMTP protocol
- engine that logs sender and recipient information.
-
-<b>4B. HANGUP TEST</b>
- When the SMTP client hangs up without sending any data
- before the <a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a> time has elapsed, this is
- logged as:
-
- <b>HANGUP after</b> <i>time</i> <b>from</b> <i>address</i>
-
- The <a href="postconf.5.html#postscreen_hangup_action">postscreen_hangup_action</a> specifies the action that is
- taken next:
-
- <b>continue</b> (default)
- Wait until the <a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a> time has
- elapsed, then report DNSBL lookup results if appli-
- cable. Do not forward the broken connection to a
- real SMTP server process.
-
- <b>drop</b> Drop the connection immediately.
-
-<b>4C. DNS BLOCKLIST TEST</b>
- The <a href="postconf.5.html#postscreen_dnsbl_sites">postscreen_dnsbl_sites</a> parameter (default: empty)
- specifies a list of DNS blocklist servers. These lookups
- are made in parallel.
-
- When the <a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a> time has elapsed, and the
- SMTP client address is listed with at least one of these
- blocklists, this is logged as:
-
- <b>DNSBL rank</b> <i>count</i> <b>for</b> <i>address</i>
-
- Translation: the client at <i>address</i> is listed with <i>count</i>
- DNSBL servers. The <i>count</i> does not depend on the number of
- DNS records that an individual DNSBL server returns.
-
- The <a href="postconf.5.html#postscreen_dnsbl_action">postscreen_dnsbl_action</a> parameter specifies the action
- that is taken next:
-
- <b>continue</b> (default)
- Forward the connection to a real SMTP server
- process.
-
- <b>drop</b> Drop the connection immediately with a 521 SMTP
- reply. In a future implementation, the connection
- may instead be passed to a dummy SMTP protocol
- engine that logs sender and recipient information.
-
-<b>SECURITY</b>
- The <a href="postscreen.8.html"><b>postscreen</b>(8)</a> server is moderately security-sensitive.
- It talks to untrusted clients on the network. The process
- can be run chrooted at fixed low privilege.
-
-<b>STANDARDS</b>
- <a href="http://tools.ietf.org/html/rfc5321">RFC 5321</a> (SMTP, including multi-line 220 greetings)
- <a href="http://tools.ietf.org/html/rfc2920">RFC 2920</a> (SMTP Pipelining)
-
-<b>DIAGNOSTICS</b>
- Problems and transactions are logged to <b>syslogd</b>(8).
-
-<b>CONFIGURATION PARAMETERS</b>
- Changes to <a href="postconf.5.html">main.cf</a> are not picked up automatically, as
- <a href="postscreen.8.html"><b>postscreen</b>(8)</a> processes may run for several hours. Use
- the command "postfix reload" after a configuration change.
-
- The text below provides only a parameter summary. See
- <a href="postconf.5.html"><b>postconf</b>(5)</a> for more details including examples.
-
-<b>TRIAGE PARAMETERS</b>
- <b><a href="postconf.5.html#postscreen_blacklist_action">postscreen_blacklist_action</a> (continue)</b>
- The action that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> takes when an SMTP
- client is permanently blacklisted with the
- <a href="postconf.5.html#postscreen_blacklist_networks">postscreen_blacklist_networks</a> parameter.
-
- <b><a href="postconf.5.html#postscreen_blacklist_networks">postscreen_blacklist_networks</a> (empty)</b>
- Network addresses that are permanently blacklisted;
- see the <a href="postconf.5.html#postscreen_blacklist_action">postscreen_blacklist_action</a> parameter for
- possible actions.
-
- <b><a href="postconf.5.html#postscreen_dnsbl_action">postscreen_dnsbl_action</a> (continue)</b>
- The action that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> takes when an SMTP
- client is listed at the DNS blocklist domains spec-
- ified with the <a href="postconf.5.html#postscreen_dnsbl_sites">postscreen_dnsbl_sites</a> parameter.
-
- <b><a href="postconf.5.html#postscreen_dnsbl_sites">postscreen_dnsbl_sites</a> (empty)</b>
- Optional list of DNS blocklist domains.
-
- <b><a href="postconf.5.html#postscreen_greet_action">postscreen_greet_action</a> (continue)</b>
- The action that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> takes when an SMTP
- client speaks before its turn within the time spec-
- ified with the <a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a> parameter.
-
- <b><a href="postconf.5.html#postscreen_greet_banner">postscreen_greet_banner</a> ($<a href="postconf.5.html#smtpd_banner">smtpd_banner</a>)</b>
- The <i>text</i> in the optional "220-<i>text</i>..." server
- response that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> sends ahead of the real
- Postfix SMTP server's "220 text..." response, in an
- attempt to confuse bad SMTP clients so that they
- speak before their turn (pre-greet).
-
- <b><a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a> (4s)</b>
- The amount of time that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> will wait for
- an SMTP client to send a command before its turn,
- and for DNS blocklist lookup results to arrive.
-
- <b><a href="postconf.5.html#postscreen_hangup_action">postscreen_hangup_action</a> (continue)</b>
- The action that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> takes when an SMTP
- client disconnects without sending data, within the
- time specified with the <a href="postconf.5.html#postscreen_greet_wait">postscreen_greet_wait</a>
- parameter.
-
- <b><a href="postconf.5.html#postscreen_post_queue_limit">postscreen_post_queue_limit</a> ($<a href="postconf.5.html#default_process_limit">default_process_limit</a>)</b>
- The number of clients that can be waiting for ser-
- vice from a real SMTP server process.
-
- <b><a href="postconf.5.html#postscreen_pre_queue_limit">postscreen_pre_queue_limit</a> ($<a href="postconf.5.html#default_process_limit">default_process_limit</a>)</b>
- The number of non-whitelisted clients that can be
- waiting for a decision whether they will receive
- service from a real SMTP server process.
-
- <b><a href="postconf.5.html#postscreen_whitelist_networks">postscreen_whitelist_networks</a> ($<a href="postconf.5.html#mynetworks">mynetworks</a>)</b>
- Network addresses that are permanently whitelisted,
- and that will not be subjected to <a href="postscreen.8.html"><b>postscreen</b>(8)</a>
- checks.
-
- <b><a href="postconf.5.html#smtpd_service">smtpd_service</a> (smtpd)</b>
- The internal service that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> forwards
- allowed connections to.
-
-<b>CACHE CONTROLS</b>
- <b><a href="postconf.5.html#postscreen_cache_cleanup_interval">postscreen_cache_cleanup_interval</a> (12h)</b>
- The amount of time between <a href="postscreen.8.html"><b>postscreen</b>(8)</a> cache
- cleanup runs.
-
- <b><a href="postconf.5.html#postscreen_cache_map">postscreen_cache_map</a> (btree:$<a href="postconf.5.html#data_directory">data_directory</a>/ps_whitelist)</b>
- Persistent storage for the <a href="postscreen.8.html"><b>postscreen</b>(8)</a> server
- decisions.
-
- <b><a href="postconf.5.html#postscreen_cache_retention_time">postscreen_cache_retention_time</a> (1d)</b>
- The amount of time that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> will cache an
- expired temporary whitelist entry before it is
- removed.
-
- <b><a href="postconf.5.html#postscreen_cache_ttl">postscreen_cache_ttl</a> (1d)</b>
- The amount of time that <a href="postscreen.8.html"><b>postscreen</b>(8)</a> will cache a
- decision for a specific SMTP client IP address.
-
-<b>MISCELLANEOUS CONTROLS</b>
- <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
- The default location of the Postfix <a href="postconf.5.html">main.cf</a> and
- <a href="master.5.html">master.cf</a> configuration files.
-
- <b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b>
- How much time a Postfix daemon process may take to
- handle a request before it is terminated by a
- built-in watchdog timer.
-
- <b><a href="postconf.5.html#delay_logging_resolution_limit">delay_logging_resolution_limit</a> (2)</b>
- The maximal number of digits after the decimal
- point when logging sub-second delay values.
-
- <b><a href="postconf.5.html#command_directory">command_directory</a> (see 'postconf -d' output)</b>
- The location of all postfix administrative com-
- mands.
-
- <b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b>
- The time limit for sending or receiving information
- over an internal communication channel.
-
- <b><a href="postconf.5.html#max_idle">max_idle</a> (100s)</b>
- The maximum amount of time that an idle Postfix
- daemon process waits for an incoming connection
- before terminating voluntarily.
-
- <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b>
- The process ID of a Postfix command or daemon
- process.
-
- <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b>
- The process name of a Postfix command or daemon
- process.
-
- <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
- The syslog facility of Postfix logging.
-
- <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
- The mail system name that is prepended to the
- process name in syslog records, so that "smtpd"
- becomes, for example, "postfix/smtpd".
-
-<b>SEE ALSO</b>
- <a href="smtpd.8.html">smtpd(8)</a>, Postfix SMTP server
- <a href="dnsblog.8.html">dnsblog(8)</a>, temporary DNS helper
- syslogd(8), system logging
-
-<b>LICENSE</b>
- The Secure Mailer license must be distributed with this
- software.
-
-<b>AUTHOR(S)</b>
- Wietse Venema
- IBM T.J. Watson Research
- P.O. Box 704
- Yorktown Heights, NY 10598, USA
-
- POSTSCREEN(8)
-</pre> </body> </html>
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
export SYSTYPE AR ARFL RANLIB SYSLIBS CC OPT DEBUG AWK OPTS
# Snapshot only.
-CCARGS="$CCARGS -DSNAPSHOT"
+#CCARGS="$CCARGS -DSNAPSHOT"
# Non-production: needs thorough testing, or major changes are still
# needed before the code stabilizes.
man8/showq.8 man8/smtp.8 man8/smtpd.8 man8/trivial-rewrite.8 \
man8/oqmgr.8 man8/spawn.8 man8/flush.8 man8/virtual.8 man8/qmqpd.8 \
man8/verify.8 man8/trace.8 man8/proxymap.8 man8/anvil.8 \
- man8/scache.8 man8/discard.8 man8/tlsmgr.8 man8/postscreen.8 \
- man8/dnsblog.8
+ man8/scache.8 man8/discard.8 man8/tlsmgr.8
COMMANDS= man1/postalias.1 man1/postcat.1 man1/postconf.1 man1/postfix.1 \
man1/postkick.1 man1/postlock.1 man1/postlog.1 man1/postdrop.1 \
man1/postmap.1 man1/postmulti.1 man1/postqueue.1 man1/postsuper.1 \
oqmgr(8), old Postfix queue manager
pickup(8), Postfix local mail pickup
pipe(8), deliver mail to non-Postfix command
-postscreen(8), Postfix SMTP triage server
proxymap(8), Postfix lookup table proxy server
qmgr(8), Postfix queue manager
qmqpd(8), Postfix QMQP server
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
and enabled instances are processed in reverse order.
.PP
This feature is available in Postfix 2.6 and later.
-.SH postscreen_blacklist_action (default: continue)
-The action that \fBpostscreen\fR(8) takes when an SMTP client is
-permanently blacklisted with the postscreen_blacklist_networks
-parameter. Specify one of the following:
-.IP "continue"
-Continue waiting until the postscreen_greet_wait time has
-elapsed, and report whether the client triggers a PREGREET or HANGUP
-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.
-.IP "drop"
-Drop the connection immediately with a 521 SMTP reply, without
-reporting PREGREET, HANGUP or DNSBL results.
-.PP
-This feature is available in Postfix 2.7.
-.SH postscreen_blacklist_networks (default: empty)
-Network addresses that are permanently blacklisted; see the
-postscreen_blacklist_action parameter for possible actions. This
-parameter uses the same address syntax as the mynetworks parameter.
-The blacklist has higher precedence than whitelists. This feature
-never uses the remote SMTP client hostname.
-.PP
-This feature is available in Postfix 2.7.
-.SH postscreen_cache_cleanup_interval (default: 12h)
-The amount of time between \fBpostscreen\fR(8) cache cleanup runs.
-Cache cleanup increases the load on the cache database and should
-therefore not be run frequently. This feature requires that the
-cache database supports the "delete" and "sequence" operators.
-Specify a zero interval to disable cache cleanup.
-.PP
-After each cache cleanup run, the \fBpostscreen\fR(8) daemon logs the
-number of entries that were retained and dropped. A cleanup run is
-logged as "partial" when the daemon terminates early after "\fBpostfix
-reload\fR", "\fBpostfix stop\fR", or no requests for $max_idle
-seconds.
-.PP
-Time units: s (seconds), m (minutes), h (hours), d (days), w
-(weeks).
-.PP
-This feature is available in Postfix 2.7.
-.SH postscreen_cache_map (default: btree:$data_directory/ps_whitelist)
-Persistent storage for the \fBpostscreen\fR(8) server decisions.
-.PP
-This feature is available in Postfix 2.7.
-.SH postscreen_cache_retention_time (default: 1d)
-The amount of time that \fBpostscreen\fR(8) will cache an expired
-temporary whitelist entry before it is removed. This prevents clients
-from being logged as "NEW" just because their cache entry expired
-an hour ago.
-.PP
-Time units: s (seconds), m (minutes), h (hours), d (days), w
-(weeks).
-.PP
-This feature is available in Postfix 2.7.
-.SH postscreen_cache_ttl (default: 1d)
-The amount of time that \fBpostscreen\fR(8) will cache a decision for
-a specific SMTP client IP address. During this time, the client IP
-address is excluded from tests. If possible, expired decisions are
-renewed automatically. Specify a non-zero time value (an integral
-value plus an optional one-letter suffix that specifies the time
-unit).
-.PP
-Time units: s (seconds), m (minutes), h (hours), d (days), w
-(weeks).
-.PP
-This feature is available in Postfix 2.7.
-.SH postscreen_dnsbl_action (default: continue)
-The action that \fBpostscreen\fR(8) takes when an SMTP client is listed
-at the DNS blocklist domains specified with the postscreen_dnsbl_sites
-parameter. Specify one of the following:
-.IP "continue"
-Forward the connection to a real SMTP server process.
-.IP "drop"
-Drop the connection with a 521 SMTP reply.
-.PP
-This feature is available in Postfix 2.7.
-.SH postscreen_dnsbl_sites (default: empty)
-Optional list of DNS blocklist domains. When the list is non-enpty,
-the \fBdnsblog\fR(8) daemon will query these domains with the IP addresses
-of non-whitelisted \fBpostscreen\fR(8) clients. Specify a list of domain
-names, separated by comma or whitespace.
-.SH postscreen_greet_action (default: continue)
-The action that \fBpostscreen\fR(8) takes when an SMTP client speaks
-before its turn within the time specified with the postscreen_greet_wait
-parameter. Specify one of the following:
-.IP "continue"
-Continue waiting until the postscreen_greet_wait time has
-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.
-.IP "drop"
-Drop the connection immediately with a 521 SMTP reply, without
-examining DNSBL lookup results.
-.PP
-In either case, \fBpostscreen\fR(8) will not whitelist the SMTP client
-IP address.
-.PP
-This feature is available in Postfix 2.7.
-.SH postscreen_greet_banner (default: $smtpd_banner)
-The \fItext\fR in the optional "220-\fItext\fR..." server
-response that
-\fBpostscreen\fR(8) sends ahead of the real Postfix SMTP server's "220
-text..." response, in an attempt to confuse bad SMTP clients so
-that they speak before their turn (pre-greet). Specify an empty
-value to disable this feature.
-.PP
-This feature is available in Postfix 2.7.
-.SH postscreen_greet_wait (default: 4s)
-The amount of time that \fBpostscreen\fR(8) will wait for an SMTP
-client to send a command before its turn, and for DNS blocklist
-lookup results to arrive. This is done only when the SMTP client
-IP address is not permanently whitelisted, and when it has no cached
-decision. Specify a non-zero time value (an integral value plus
-an optional one-letter suffix that specifies the time unit).
-.PP
-Time units: s (seconds), m (minutes), h (hours), d (days), w
-(weeks).
-.PP
-This feature is available in Postfix 2.7.
-.SH postscreen_hangup_action (default: continue)
-The action that \fBpostscreen\fR(8) takes when an SMTP client disconnects
-without sending data, within the time specified with the
-postscreen_greet_wait parameter. Specify one of the following:
-.IP "continue"
-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.
-.IP "drop"
-Drop the connection immediately, without reporting DNSBL lookup
-results.
-.PP
-This feature is available in Postfix 2.7.
-.SH postscreen_post_queue_limit (default: $default_process_limit)
-The number of clients that can be waiting for service from a
-real SMTP server process. When this queue is full, all clients will
-receive a 421 reponse.
-.PP
-This feature is available in Postfix 2.7.
-.SH postscreen_pre_queue_limit (default: $default_process_limit)
-The number of non-whitelisted clients that can be waiting for
-a decision whether they will receive service from a real SMTP server
-process. When this queue is full, all non-whitelisted clients will
-receive a 421 reponse.
-.PP
-This feature is available in Postfix 2.7.
-.SH postscreen_whitelist_networks (default: $mynetworks)
-Network addresses that are permanently whitelisted, and that
-will not be subjected to \fBpostscreen\fR(8) checks. This parameter uses
-the same address syntax as the mynetworks parameter. This feature
-never uses the remote SMTP client hostname.
-.PP
-This feature is available in Postfix 2.7.
.SH prepend_delivered_header (default: command, file, forward)
The message delivery contexts where the Postfix \fBlocal\fR(8) delivery
agent prepends a Delivered-To: message header with the address
.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").
.fi
.ad
.ft R
-.SH smtpd_service (default: smtpd)
-The internal service that \fBpostscreen\fR(8) forwards allowed
-connections to. In a future version there may be different
-classes of SMTP service.
-.PP
-This feature is available in Postfix 2.7.
.SH smtpd_soft_error_limit (default: 10)
The number of errors a remote SMTP client is allowed to make without
delivering mail before the Postfix SMTP server slows down all its
.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.
+++ /dev/null
-.TH DNSBLOG 8
-.ad
-.fi
-.SH NAME
-dnsblog
-\-
-Postfix DNS blocklist logger
-.SH "SYNOPSIS"
-.na
-.nf
-\fBdnsblog\fR [generic Postfix daemon options]
-.SH DESCRIPTION
-.ad
-.fi
-The \fBdnsblog\fR(8) server implements an ad-hoc DNS blocklist
-lookup service that will eventually be replaced by an UDP
-client that is built directly into the \fBpostscreen\fR(8)
-server.
-
-With each connection, the \fBdnsblog\fR(8) server receives
-a DNS blocklist domain name and an IP address. If the address
-is listed under the DNS blocklist, the \fBdnsblog\fR(8)
-server logs the match and replies with the query arguments
-plus a non-zero status. Otherwise it replies with the query
-arguments plus a zero status. Finally, The \fBdnsblog\fR(8)
-server closes the connection.
-.SH DIAGNOSTICS
-.ad
-.fi
-Problems and transactions are logged to \fBsyslogd\fR(8).
-.SH "CONFIGURATION PARAMETERS"
-.na
-.nf
-.ad
-.fi
-Changes to \fBmain.cf\fR are picked up automatically, as
-\fBdnsblog\fR(8) processes run for only a limited amount
-of time. Use the command "\fBpostfix reload\fR" to speed
-up a change.
-
-The text below provides only a parameter summary. See
-\fBpostconf\fR(5) for more details including examples.
-.IP "\fBconfig_directory (see 'postconf -d' output)\fR"
-The default location of the Postfix main.cf and master.cf
-configuration files.
-.IP "\fBdaemon_timeout (18000s)\fR"
-How much time a Postfix daemon process may take to handle a
-request before it is terminated by a built-in watchdog timer.
-.IP "\fBpostscreen_dnsbl_sites (empty)\fR"
-Optional list of DNS blocklist domains.
-.IP "\fBipc_timeout (3600s)\fR"
-The time limit for sending or receiving information over an internal
-communication channel.
-.IP "\fBprocess_id (read-only)\fR"
-The process ID of a Postfix command or daemon process.
-.IP "\fBprocess_name (read-only)\fR"
-The process name of a Postfix command or daemon process.
-.IP "\fBqueue_directory (see 'postconf -d' output)\fR"
-The location of the Postfix top-level queue directory.
-.IP "\fBsyslog_facility (mail)\fR"
-The syslog facility of Postfix logging.
-.IP "\fBsyslog_name (see 'postconf -d' output)\fR"
-The mail system name that is prepended to the process name in syslog
-records, so that "smtpd" becomes, for example, "postfix/smtpd".
-.SH "SEE ALSO"
-.na
-.nf
-smtpd(8), Postfix SMTP server
-postconf(5), configuration parameters
-syslogd(5), system logging
-.SH "LICENSE"
-.na
-.nf
-.ad
-.fi
-The Secure Mailer license must be distributed with this software.
-.SH "HISTORY"
-.na
-.nf
-.ad
-.fi
-This service is temporary with Postfix version 2.7.
-.SH "AUTHOR(S)"
-.na
-.nf
-Wietse Venema
-IBM T.J. Watson Research
-P.O. Box 704
-Yorktown Heights, NY 10598, USA
+++ /dev/null
-.TH POSTSCREEN 8
-.ad
-.fi
-.SH NAME
-postscreen
-\-
-Postfix SMTP triage server
-.SH "SYNOPSIS"
-.na
-.nf
-\fBpostscreen\fR [generic Postfix daemon options]
-.SH DESCRIPTION
-.ad
-.fi
-The Postfix \fBpostscreen\fR(8) server performs triage on
-multiple inbound SMTP connections in parallel. While
-\fBpostscreen\fR(8) keeps zombies and other bogus clients
-away from Postfix SMTP server processes, more Postfix SMTP
-server processes remain available for legitimate clients.
-.SH "GENERAL OPERATION"
-.na
-.nf
-.ad
-.fi
-The triage process involves a number of tests, in the order
-as described below. Some tests introduce a delay of a few
-seconds. Once a client passes all tests, its IP address
-is temporarily excluded from the tests, typically for 24
-hours. This minimizes the impact of the tests on legitimate
-mail clients.
-
-After logging the result of its tests, \fBpostscreen\fR(8)
-by default forwards all connections to a real SMTP server
-process. This mode is useful for non-destructive testing.
-
-In a typical production setting, \fBpostscreen\fR(8) is
-configured to disconnect clients that fail some tests. A
-future implementation may pass the connection to a dummy
-SMTP protocol engine that logs sender and recipient information
-before hanging up.
-
-Note: \fBpostscreen\fR(8) is not an SMTP proxy; this is
-intentional. The purpose is to prioritize legitimate clients
-with as little overhead as possible.
-.SH 1. PERMANENT WHITELIST TEST
-.ad
-.fi
-The postscreen_whitelist_networks parameter (default:
-$mynetworks) specifies a permanent whitelist for SMTP client
-IP addresses.
-
-When the SMTP client address matches the permanent whitelist,
-this is logged as:
-.sp
-.nf
-\fBWHITELISTED \fIaddress\fR
-.fi
-.sp
-The action is not configurable: immediately forward the
-connection to a real SMTP server process.
-.SH 2. PERMANENT BLACKLIST TEST
-.ad
-.fi
-The postscreen_blacklist_networks parameter (default: empty)
-specifies a permanent blacklist for SMTP client IP addresses.
-The address syntax is as with mynetworks.
-
-When the SMTP client address matches the permanent blacklist,
-this is logged as:
-.sp
-.nf
-\fBBLACKLISTED \fIaddress\fR
-.fi
-.sp
-The postscreen_blacklist_action parameter specifies the
-action that is taken next:
-.IP "\fBcontinue\fR (default)"
-Continue with the SMTP GREETING PHASE TESTS below.
-.IP \fBdrop\fR
-Drop the connection immediately with a 521 SMTP reply. In
-a future implementation, the connection may instead be
-passed to a dummy SMTP protocol engine that logs sender and
-recipient information.
-.SH 3. TEMPORARY WHITELIST TEST
-.ad
-.fi
-The \fBpostscreen\fR(8) daemon maintains a \fItemporary\fR
-whitelist for SMTP client IP addresses that have passed all
-the tests described below. The postscreen_cache_map parameter
-specifies the location of the temporary whitelist. The
-temporary whitelist is not used for SMTP client addresses
-that appear on the \fIpermanent\fR blacklist or whitelist.
-
-When the SMTP client address appears on the temporary
-whitelist, this is logged as:
-.sp
-.nf
-\fBPASS OLD \fIaddress\fR
-.fi
-.sp
-The action is not configurable: immediately forward the
-connection to a real SMTP server process. The client is
-excluded from further tests until its temporary whitelist
-entry expires, as controlled with the postscreen_cache_ttl
-parameter. Expired entries are silently renewed if possible.
-.SH 4. SMTP GREETING PHASE TESTS
-.ad
-.fi
-The postscreen_greet_wait parameter specifies a time interval
-during which \fBpostscreen\fR(8) runs a number of tests in
-parallel. These tests are described below, and are run
-before the client may see the real SMTP server's "220
-text..." server greeting.
-
-When the SMTP client passes all greeting-phase tests, this
-is logged as:
-.sp
-.nf
-\fBPASS NEW \fIaddress\fR
-.fi
-.sp
-The action is to forward the connection to a real SMTP
-server process and to create a temporary whitelist entry
-that excludes the client IP address from further tests until
-the temporary whitelist entry expires, as controlled with
-the postscreen_cache_ttl parameter.
-
-In a future implementation, the connection may first be passed to
-a dummy SMTP protocol engine that implements more protocol
-tests including greylisting, before the client is allowed
-to talk to a real SMTP server process.
-.SH 4A. PREGREET TEST
-.ad
-.fi
-The postscreen_greet_banner parameter specifies the \fItext\fR
-portion of a "220-\fItext\fR..." teaser banner (default:
-$smtpd_banner).
-The \fBpostscreen\fR(8) daemon sends this before the
-postscreen_greet_wait timer is started. The purpose of the
-teaser banner is to confuse SPAM clients so that they speak
-before their turn. It has no effect on SMTP clients that
-correctly implement the protocol.
-
-To avoid problems with broken SMTP engines in network
-appliances, either exclude them from all tests with the
-postscreen_whitelist_networks feature or else specify an
-empty postscreen_greet_banner value to disable the "220-text..."
-teaser banner.
-
-When an SMTP client sends a command before the
-postscreen_greet_wait time has elapsed, this is logged as:
-.sp
-.nf
-\fBPREGREET \fIcount \fBafter \fItime \fBfrom \fIaddress text...\fR
-.fi
-.sp
-Translation: the client at \fIaddress\fR sent \fIcount\fR
-bytes before its turn to speak, and this happened \fItime\fR
-seconds after the postscreen_greet_wait timer was started.
-The \fItext\fR is what the client sent (truncated to 100
-bytes, and with non-printable characters replaced with "?").
-
-The postscreen_greet_action parameter specifies the action
-that is taken next:
-.IP "\fBcontinue\fR (default)"
-Wait until the postscreen_greet_wait time has elapsed, then
-report DNSBL lookup results if applicable. Either perform
-DNSBL-related actions or forward the connection to a real
-SMTP server process.
-.IP \fBdrop\fR
-Drop the connection immediately with a 521 SMTP reply.
-In a future implementation, the connection may instead be passed
-to a dummy SMTP protocol engine that logs sender and recipient
-information.
-.SH 4B. HANGUP TEST
-.ad
-.fi
-When the SMTP client hangs up without sending any data
-before the postscreen_greet_wait time has elapsed, this is
-logged as:
-.sp
-.nf
-\fBHANGUP after \fItime \fBfrom \fIaddress\fR
-.fi
-.sp
-The postscreen_hangup_action specifies the action
-that is taken next:
-.IP "\fBcontinue\fR (default)"
-Wait until the postscreen_greet_wait time has elapsed, then
-report DNSBL lookup results if applicable. Do not forward
-the broken connection to a real SMTP server process.
-.IP \fBdrop\fR
-Drop the connection immediately.
-.SH 4C. DNS BLOCKLIST TEST
-.ad
-.fi
-The postscreen_dnsbl_sites parameter (default: empty)
-specifies a list of DNS blocklist servers. These lookups
-are made in parallel.
-
-When the postscreen_greet_wait time has elapsed, and the
-SMTP client address is listed with at least one of these
-blocklists, this is logged as:
-.sp
-.nf
-\fBDNSBL rank \fIcount \fBfor \fIaddress\fR
-.fi
-.sp
-Translation: the client at \fIaddress\fR is listed with
-\fIcount\fR DNSBL servers. The \fIcount\fR does not
-depend on the number of DNS records that an individual DNSBL
-server returns.
-
-The postscreen_dnsbl_action parameter specifies the action
-that is taken next:
-.IP "\fBcontinue\fR (default)"
-Forward the connection to a real SMTP server process.
-.IP \fBdrop\fR
-Drop the connection immediately with a 521 SMTP reply.
-In a future implementation, the connection may instead be passed
-to a dummy SMTP protocol engine that logs sender and recipient
-information.
-.SH "SECURITY"
-.na
-.nf
-.ad
-.fi
-The \fBpostscreen\fR(8) server is moderately security-sensitive.
-It talks to untrusted clients on the network. The process
-can be run chrooted at fixed low privilege.
-.SH "STANDARDS"
-.na
-.nf
-RFC 5321 (SMTP, including multi-line 220 greetings)
-RFC 2920 (SMTP Pipelining)
-.SH DIAGNOSTICS
-.ad
-.fi
-Problems and transactions are logged to \fBsyslogd\fR(8).
-.SH "CONFIGURATION PARAMETERS"
-.na
-.nf
-.ad
-.fi
-Changes to main.cf are not picked up automatically, as
-\fBpostscreen\fR(8) processes may run for several hours.
-Use the command "postfix reload" after a configuration
-change.
-
-The text below provides only a parameter summary. See
-\fBpostconf\fR(5) for more details including examples.
-.SH "TRIAGE PARAMETERS"
-.na
-.nf
-.ad
-.fi
-.IP "\fBpostscreen_blacklist_action (continue)\fR"
-The action that \fBpostscreen\fR(8) takes when an SMTP client is
-permanently blacklisted with the postscreen_blacklist_networks
-parameter.
-.IP "\fBpostscreen_blacklist_networks (empty)\fR"
-Network addresses that are permanently blacklisted; see the
-postscreen_blacklist_action parameter for possible actions.
-.IP "\fBpostscreen_dnsbl_action (continue)\fR"
-The action that \fBpostscreen\fR(8) takes when an SMTP client is listed
-at the DNS blocklist domains specified with the postscreen_dnsbl_sites
-parameter.
-.IP "\fBpostscreen_dnsbl_sites (empty)\fR"
-Optional list of DNS blocklist domains.
-.IP "\fBpostscreen_greet_action (continue)\fR"
-The action that \fBpostscreen\fR(8) takes when an SMTP client speaks
-before its turn within the time specified with the postscreen_greet_wait
-parameter.
-.IP "\fBpostscreen_greet_banner ($smtpd_banner)\fR"
-The \fItext\fR in the optional "220-\fItext\fR..." server
-response that
-\fBpostscreen\fR(8) sends ahead of the real Postfix SMTP server's "220
-text..." response, in an attempt to confuse bad SMTP clients so
-that they speak before their turn (pre-greet).
-.IP "\fBpostscreen_greet_wait (4s)\fR"
-The amount of time that \fBpostscreen\fR(8) will wait for an SMTP
-client to send a command before its turn, and for DNS blocklist
-lookup results to arrive.
-.IP "\fBpostscreen_hangup_action (continue)\fR"
-The action that \fBpostscreen\fR(8) takes when an SMTP client disconnects
-without sending data, within the time specified with the
-postscreen_greet_wait parameter.
-.IP "\fBpostscreen_post_queue_limit ($default_process_limit)\fR"
-The number of clients that can be waiting for service from a
-real SMTP server process.
-.IP "\fBpostscreen_pre_queue_limit ($default_process_limit)\fR"
-The number of non-whitelisted clients that can be waiting for
-a decision whether they will receive service from a real SMTP server
-process.
-.IP "\fBpostscreen_whitelist_networks ($mynetworks)\fR"
-Network addresses that are permanently whitelisted, and that
-will not be subjected to \fBpostscreen\fR(8) checks.
-.IP "\fBsmtpd_service (smtpd)\fR"
-The internal service that \fBpostscreen\fR(8) forwards allowed
-connections to.
-.SH "CACHE CONTROLS"
-.na
-.nf
-.ad
-.fi
-.IP "\fBpostscreen_cache_cleanup_interval (12h)\fR"
-The amount of time between \fBpostscreen\fR(8) cache cleanup runs.
-.IP "\fBpostscreen_cache_map (btree:$data_directory/ps_whitelist)\fR"
-Persistent storage for the \fBpostscreen\fR(8) server decisions.
-.IP "\fBpostscreen_cache_retention_time (1d)\fR"
-The amount of time that \fBpostscreen\fR(8) will cache an expired
-temporary whitelist entry before it is removed.
-.IP "\fBpostscreen_cache_ttl (1d)\fR"
-The amount of time that \fBpostscreen\fR(8) will cache a decision for
-a specific SMTP client IP address.
-.SH "MISCELLANEOUS CONTROLS"
-.na
-.nf
-.ad
-.fi
-.IP "\fBconfig_directory (see 'postconf -d' output)\fR"
-The default location of the Postfix main.cf and master.cf
-configuration files.
-.IP "\fBdaemon_timeout (18000s)\fR"
-How much time a Postfix daemon process may take to handle a
-request before it is terminated by a built-in watchdog timer.
-.IP "\fBdelay_logging_resolution_limit (2)\fR"
-The maximal number of digits after the decimal point when logging
-sub-second delay values.
-.IP "\fBcommand_directory (see 'postconf -d' output)\fR"
-The location of all postfix administrative commands.
-.IP "\fBipc_timeout (3600s)\fR"
-The time limit for sending or receiving information over an internal
-communication channel.
-.IP "\fBmax_idle (100s)\fR"
-The maximum amount of time that an idle Postfix daemon process waits
-for an incoming connection before terminating voluntarily.
-.IP "\fBprocess_id (read-only)\fR"
-The process ID of a Postfix command or daemon process.
-.IP "\fBprocess_name (read-only)\fR"
-The process name of a Postfix command or daemon process.
-.IP "\fBsyslog_facility (mail)\fR"
-The syslog facility of Postfix logging.
-.IP "\fBsyslog_name (see 'postconf -d' output)\fR"
-The mail system name that is prepended to the process name in syslog
-records, so that "smtpd" becomes, for example, "postfix/smtpd".
-.SH "SEE ALSO"
-.na
-.nf
-smtpd(8), Postfix SMTP server
-dnsblog(8), temporary DNS helper
-syslogd(8), system logging
-.SH "LICENSE"
-.na
-.nf
-.ad
-.fi
-The Secure Mailer license must be distributed with this software.
-.SH "AUTHOR(S)"
-.na
-.nf
-Wietse Venema
-IBM T.J. Watson Research
-P.O. Box 704
-Yorktown Heights, NY 10598, USA
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
while (<>) {
- if (/^Incompatible changes with/) {
+ if (/^(Incompatible changes|Incompatibility) with/) {
die "No date found: $_" unless /(\d\d\d\d\d\d\d\d)/;
$append_to = \%body;
$prefix = "[Incompat $1] ";
<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
<p> This feature is available in Postfix 2.7, and as an optional
patch for Postfix 2.6. </p>
-%PARAM postscreen_cache_map btree:$data_directory/ps_whitelist
-
-<p> Persistent storage for the postscreen(8) server decisions. </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-%PARAM smtpd_service smtpd
-
-<p> The internal service that postscreen(8) forwards allowed
-connections to. In a future version there may be different
-classes of SMTP service. </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-%PARAM postscreen_post_queue_limit $default_process_limit
-
-<p> The number of clients that can be waiting for service from a
-real SMTP server process. When this queue is full, all clients will
-receive a 421 reponse. </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-%PARAM postscreen_pre_queue_limit $default_process_limit
-
-<p> The number of non-whitelisted clients that can be waiting for
-a decision whether they will receive service from a real SMTP server
-process. When this queue is full, all non-whitelisted clients will
-receive a 421 reponse. </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-%PARAM postscreen_cache_ttl 1d
-
-<p> The amount of time that postscreen(8) will cache a decision for
-a specific SMTP client IP address. During this time, the client IP
-address is excluded from tests. If possible, expired decisions are
-renewed automatically. Specify a non-zero time value (an integral
-value plus an optional one-letter suffix that specifies the time
-unit). </p>
-
-<p> Time units: s (seconds), m (minutes), h (hours), d (days), w
-(weeks). </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-%PARAM postscreen_cache_retention_time 1d
-
-<p> The amount of time that postscreen(8) will cache an expired
-temporary whitelist entry before it is removed. This prevents clients
-from being logged as "NEW" just because their cache entry expired
-an hour ago. </p>
-
-<p> Time units: s (seconds), m (minutes), h (hours), d (days), w
-(weeks). </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-%PARAM postscreen_cache_cleanup_interval 12h
-
-<p> The amount of time between postscreen(8) cache cleanup runs.
-Cache cleanup increases the load on the cache database and should
-therefore not be run frequently. This feature requires that the
-cache database supports the "delete" and "sequence" operators.
-Specify a zero interval to disable cache cleanup. </p>
-
-<p> After each cache cleanup run, the postscreen(8) daemon logs the
-number of entries that were retained and dropped. A cleanup run is
-logged as "partial" when the daemon terminates early after "<b>postfix
-reload</b>", "<b>postfix stop</b>", or no requests for $max_idle
-seconds. </p>
-
-<p> Time units: s (seconds), m (minutes), h (hours), d (days), w
-(weeks). </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-%PARAM postscreen_greet_wait 4s
-
-<p> The amount of time that postscreen(8) will wait for an SMTP
-client to send a command before its turn, and for DNS blocklist
-lookup results to arrive. This is done only when the SMTP client
-IP address is not permanently whitelisted, and when it has no cached
-decision. Specify a non-zero time value (an integral value plus
-an optional one-letter suffix that specifies the time unit). </p>
-
-<p> Time units: s (seconds), m (minutes), h (hours), d (days), w
-(weeks). </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-%PARAM postscreen_dnsbl_sites
-
-<p>Optional list of DNS blocklist domains. When the list is non-enpty,
-the dnsblog(8) daemon will query these domains with the IP addresses
-of non-whitelisted postscreen(8) clients. Specify a list of domain
-names, separated by comma or whitespace. </p>
-
-%PARAM postscreen_dnsbl_action continue
-
-<p>The action that postscreen(8) takes when an SMTP client is listed
-at the DNS blocklist domains specified with the postscreen_dnsbl_sites
-parameter. Specify one of the following: </p>
-
-<dl>
-
-<dt> continue </dt>
-
-<dd> Forward the connection to a real SMTP server process. </p>
-
-<dt> drop </dt>
-
-<dd> Drop the connection with a 521 SMTP reply. </dd>
-
-</dl>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-%PARAM postscreen_greet_action continue
-
-<p>The action that postscreen(8) takes when an SMTP client speaks
-before its turn within the time specified with the postscreen_greet_wait
-parameter. Specify one of the following: </p>
-
-<dl>
-
-<dt> continue </dt>
-
-<dd> Continue waiting until the postscreen_greet_wait time has
-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>
-
-<dt> drop </dt>
-
-<dd> Drop the connection immediately with a 521 SMTP reply, without
-examining DNSBL lookup results. </dd>
-
-</dl>
-
-<p> In either case, postscreen(8) will not whitelist the SMTP client
-IP address. </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-%PARAM postscreen_hangup_action continue
-
-<p>The action that postscreen(8) takes when an SMTP client disconnects
-without sending data, within the time specified with the
-postscreen_greet_wait parameter. Specify one of the following:
-</p>
-
-<dl>
-
-<dt> continue </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>
-
-<dt> drop </dt>
-
-<dd> Drop the connection immediately, without reporting DNSBL lookup
-results. </dd>
-
-</dl>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-%PARAM postscreen_whitelist_networks $mynetworks
-
-<p> Network addresses that are permanently whitelisted, and that
-will not be subjected to postscreen(8) checks. This parameter uses
-the same address syntax as the mynetworks parameter. This feature
-never uses the remote SMTP client hostname. </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-%PARAM postscreen_blacklist_networks
-
-<p> Network addresses that are permanently blacklisted; see the
-postscreen_blacklist_action parameter for possible actions. This
-parameter uses the same address syntax as the mynetworks parameter.
-The blacklist has higher precedence than whitelists. This feature
-never uses the remote SMTP client hostname. </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-%PARAM postscreen_greet_banner $smtpd_banner
-
-<p> The <i>text</i> in the optional "220-<i>text</i>..." server
-response that
-postscreen(8) sends ahead of the real Postfix SMTP server's "220
-text..." response, in an attempt to confuse bad SMTP clients so
-that they speak before their turn (pre-greet). Specify an empty
-value to disable this feature. </p>
-
-<p> This feature is available in Postfix 2.7. </p>
-
-%PARAM postscreen_blacklist_action continue
-
-<p> The action that postscreen(8) takes when an SMTP client is
-permanently blacklisted with the postscreen_blacklist_networks
-parameter. Specify one of the following: </p>
-
-<dl>
-
-<dt> continue </dt>
-
-<dd> Continue waiting until the postscreen_greet_wait time has
-elapsed, and report whether the client triggers a PREGREET or HANGUP
-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>
-
-<dt> drop </dt>
-
-<dd> Drop the connection immediately with a 521 SMTP reply, without
-reporting PREGREET, HANGUP or DNSBL results. </dd>
-
-</dl>
-
-<p> This feature is available in Postfix 2.7. </p>
-
%PARAM smtpd_command_filter
<p> A mechanism to transform commands from remote SMTP clients.
<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.
#
+++ /dev/null
-../../.indent.pro
\ No newline at end of file
+++ /dev/null
-SHELL = /bin/sh
-SRCS = dnsblog.c
-OBJS = dnsblog.o
-HDRS =
-TESTSRC =
-DEFS = -I. -I$(INC_DIR) -D$(SYSTYPE)
-CFLAGS = $(DEBUG) $(OPT) $(DEFS)
-TESTPROG=
-PROG = dnsblog
-INC_DIR = ../../include
-LIBS = ../../lib/libdns.a ../../lib/libmaster.a ../../lib/libglobal.a \
- ../../lib/libutil.a
-
-.c.o:; $(CC) $(CFLAGS) -c $*.c
-
-$(PROG): $(OBJS) $(LIBS)
- $(CC) $(CFLAGS) -o $@ $(OBJS) $(LIBS) $(SYSLIBS)
-
-$(OBJS): ../../conf/makedefs.out
-
-Makefile: Makefile.in
- cat ../../conf/makedefs.out $? >$@
-
-test: $(TESTPROG)
-
-tests: test
-
-root_tests:
-
-update: ../../libexec/$(PROG)
-
-../../libexec/$(PROG): $(PROG)
- cp $(PROG) ../../libexec
-
-printfck: $(OBJS) $(PROG)
- rm -rf printfck
- mkdir printfck
- sed '1,/^# do not edit/!d' Makefile >printfck/Makefile
- set -e; for i in *.c; do printfck -f .printfck $$i >printfck/$$i; done
- cd printfck; make "INC_DIR=../../../include" `cd ..; ls *.o`
-
-lint:
- lint $(DEFS) $(SRCS) $(LINTFIX)
-
-clean:
- rm -f *.o *core $(PROG) $(TESTPROG) junk
- rm -rf printfck
-
-tidy: clean
-
-depend: $(MAKES)
- (sed '1,/^# do not edit/!d' Makefile.in; \
- set -e; for i in [a-z][a-z0-9]*.c; do \
- $(CC) -E $(DEFS) $(INCL) $$i | grep -v '[<>]' | sed -n -e '/^# *1 *"\([^"]*\)".*/{' \
- -e 's//'`echo $$i|sed 's/c$$/o/'`': \1/' \
- -e 's/o: \.\//o: /' -e p -e '}' ; \
- done | sort -u) | grep -v '[.][o][:][ ][/]' >$$$$ && mv $$$$ Makefile.in
- @$(EXPORT) make -f Makefile.in Makefile 1>&2
-
-# do not edit below this line - it is generated by 'make depend'
-dnsblog.o: ../../include/argv.h
-dnsblog.o: ../../include/attr.h
-dnsblog.o: ../../include/dns.h
-dnsblog.o: ../../include/iostuff.h
-dnsblog.o: ../../include/mail_conf.h
-dnsblog.o: ../../include/mail_params.h
-dnsblog.o: ../../include/mail_proto.h
-dnsblog.o: ../../include/mail_server.h
-dnsblog.o: ../../include/mail_version.h
-dnsblog.o: ../../include/msg.h
-dnsblog.o: ../../include/myaddrinfo.h
-dnsblog.o: ../../include/sock_addr.h
-dnsblog.o: ../../include/sys_defs.h
-dnsblog.o: ../../include/valid_hostname.h
-dnsblog.o: ../../include/vbuf.h
-dnsblog.o: ../../include/vstream.h
-dnsblog.o: ../../include/vstring.h
-dnsblog.o: dnsblog.c
+++ /dev/null
-/*++
-/* NAME
-/* dnsblog 8
-/* SUMMARY
-/* Postfix DNS blocklist logger
-/* SYNOPSIS
-/* \fBdnsblog\fR [generic Postfix daemon options]
-/* DESCRIPTION
-/* The \fBdnsblog\fR(8) server implements an ad-hoc DNS blocklist
-/* lookup service that will eventually be replaced by an UDP
-/* client that is built directly into the \fBpostscreen\fR(8)
-/* server.
-/*
-/* With each connection, the \fBdnsblog\fR(8) server receives
-/* a DNS blocklist domain name and an IP address. If the address
-/* is listed under the DNS blocklist, the \fBdnsblog\fR(8)
-/* server logs the match and replies with the query arguments
-/* plus a non-zero status. Otherwise it replies with the query
-/* arguments plus a zero status. Finally, The \fBdnsblog\fR(8)
-/* server closes the connection.
-/* DIAGNOSTICS
-/* Problems and transactions are logged to \fBsyslogd\fR(8).
-/* CONFIGURATION PARAMETERS
-/* .ad
-/* .fi
-/* Changes to \fBmain.cf\fR are picked up automatically, as
-/* \fBdnsblog\fR(8) processes run for only a limited amount
-/* of time. Use the command "\fBpostfix reload\fR" to speed
-/* up a change.
-/*
-/* The text below provides only a parameter summary. See
-/* \fBpostconf\fR(5) for more details including examples.
-/* .IP "\fBconfig_directory (see 'postconf -d' output)\fR"
-/* The default location of the Postfix main.cf and master.cf
-/* configuration files.
-/* .IP "\fBdaemon_timeout (18000s)\fR"
-/* How much time a Postfix daemon process may take to handle a
-/* request before it is terminated by a built-in watchdog timer.
-/* .IP "\fBpostscreen_dnsbl_sites (empty)\fR"
-/* Optional list of DNS blocklist domains.
-/* .IP "\fBipc_timeout (3600s)\fR"
-/* The time limit for sending or receiving information over an internal
-/* communication channel.
-/* .IP "\fBprocess_id (read-only)\fR"
-/* The process ID of a Postfix command or daemon process.
-/* .IP "\fBprocess_name (read-only)\fR"
-/* The process name of a Postfix command or daemon process.
-/* .IP "\fBqueue_directory (see 'postconf -d' output)\fR"
-/* The location of the Postfix top-level queue directory.
-/* .IP "\fBsyslog_facility (mail)\fR"
-/* The syslog facility of Postfix logging.
-/* .IP "\fBsyslog_name (see 'postconf -d' output)\fR"
-/* The mail system name that is prepended to the process name in syslog
-/* records, so that "smtpd" becomes, for example, "postfix/smtpd".
-/* SEE ALSO
-/* smtpd(8), Postfix SMTP server
-/* postconf(5), configuration parameters
-/* syslogd(5), system logging
-/* LICENSE
-/* .ad
-/* .fi
-/* The Secure Mailer license must be distributed with this software.
-/* HISTORY
-/* .ad
-/* .fi
-/* This service is temporary with Postfix version 2.7.
-/* AUTHOR(S)
-/* Wietse Venema
-/* IBM T.J. Watson Research
-/* P.O. Box 704
-/* Yorktown Heights, NY 10598, USA
-/*--*/
-
-/* System library. */
-
-#include <sys_defs.h>
-
-/* Utility library. */
-
-#include <msg.h>
-#include <vstream.h>
-#include <vstring.h>
-#include <argv.h>
-#include <myaddrinfo.h>
-#include <valid_hostname.h>
-#include <sock_addr.h>
-
-/* Global library. */
-
-#include <mail_conf.h>
-#include <mail_version.h>
-#include <mail_proto.h>
-
-/* DNS library. */
-
-#include <dns.h>
-
-/* Server skeleton. */
-
-#include <mail_server.h>
-
-/* Application-specific. */
-
- /*
- * Static so we don't allocate and free on every request.
- */
-static VSTRING *rbl_domain;
-static VSTRING *addr;
-static VSTRING *query;
-static VSTRING *why;
-
- /*
- * Silly little macros.
- */
-#define STR(x) vstring_str(x)
-
-/* static void dnsblog_query - query DNSBL for client address */
-
-static int dnsblog_query(const char *dnsbl_domain, const char *addr)
-{
- const char *myname = "dnsblog_query";
- ARGV *octets;
- int i;
- struct addrinfo *res;
- unsigned char *ipv6_addr;
- int dns_status;
- DNS_RR *addr_list;
- DNS_RR *rr;
- MAI_HOSTADDR_STR hostaddr;
- int found = 0;
-
- if (msg_verbose)
- msg_info("%s: addr %s dnsbl_domain %s",
- myname, addr, dnsbl_domain);
-
- VSTRING_RESET(query);
-
- /*
- * Reverse the client IPV6 address, represented as 32 hexadecimal
- * nibbles. We use the binary address to avoid tricky code. Asking for an
- * AAAA record makes no sense here. Just like with IPv4 we use the lookup
- * result as a bit mask, not as an IP address.
- */
-#ifdef HAS_IPV6
- if (valid_ipv6_hostaddr(addr, DONT_GRIPE)) {
- if (hostaddr_to_sockaddr(addr, (char *) 0, 0, &res) != 0
- || res->ai_family != PF_INET6)
- msg_fatal("%s: unable to convert address %s", myname, addr);
- ipv6_addr = (unsigned char *) &SOCK_ADDR_IN6_ADDR(res->ai_addr);
- for (i = sizeof(SOCK_ADDR_IN6_ADDR(res->ai_addr)) - 1; i >= 0; i--)
- vstring_sprintf_append(query, "%x.%x.",
- ipv6_addr[i] & 0xf, ipv6_addr[i] >> 4);
- freeaddrinfo(res);
- } else
-#endif
-
- /*
- * Reverse the client IPV4 address, represented as four decimal octet
- * values. We use the textual address for convenience.
- */
- {
- octets = argv_split(addr, ".");
- for (i = octets->argc - 1; i >= 0; i--) {
- vstring_strcat(query, octets->argv[i]);
- vstring_strcat(query, ".");
- }
- argv_free(octets);
- }
-
- /*
- * Tack on the RBL domain name and query the DNS for an A record. Don't
- * do this for AAAA records. Yet.
- */
- vstring_strcat(query, dnsbl_domain);
- dns_status = dns_lookup(STR(query), T_A, 0, &addr_list, (VSTRING *) 0, why);
- if (dns_status == DNS_OK) {
- for (rr = addr_list; rr != 0; rr = rr->next) {
- if (dns_rr_to_pa(rr, &hostaddr) == 0) {
- msg_warn("%s: skipping reply record type %s for query %s: %m",
- myname, dns_strtype(rr->type), STR(query));
- } else {
- msg_info("addr %s blocked by domain %s as %s",
- addr, dnsbl_domain, hostaddr.buf);
- found = 1;
- }
- }
- dns_rr_free(addr_list);
- } else if (dns_status == DNS_NOTFOUND) {
- if (msg_verbose)
- msg_info("%s: addr %s not listed under domain %s",
- myname, addr, dnsbl_domain);
- } else {
- msg_warn("%s: lookup error for DNS query %s: %s",
- myname, STR(query), STR(why));
- }
- return (found);
-}
-
-/* dnsblog_service - perform service for client */
-
-static void dnsblog_service(VSTREAM *client_stream, char *unused_service,
- char **argv)
-{
- int found;
-
- /*
- * Sanity check. This service takes no command-line arguments.
- */
- if (argv[0])
- msg_fatal("unexpected command-line argument: %s", argv[0]);
-
- /*
- * This routine runs whenever a client connects to the socket dedicated
- * to the dnsblog service. All connection-management stuff is handled by
- * the common code in single_server.c.
- */
- if (attr_scan(client_stream,
- ATTR_FLAG_MORE | ATTR_FLAG_STRICT,
- ATTR_TYPE_STR, MAIL_ATTR_RBL_DOMAIN, rbl_domain,
- ATTR_TYPE_STR, MAIL_ATTR_ADDR, addr,
- ATTR_TYPE_END) == 2) {
- found = dnsblog_query(STR(rbl_domain), STR(addr));
- attr_print(client_stream, ATTR_FLAG_NONE,
- ATTR_TYPE_STR, MAIL_ATTR_RBL_DOMAIN, STR(rbl_domain),
- ATTR_TYPE_STR, MAIL_ATTR_ADDR, STR(addr),
- ATTR_TYPE_INT, MAIL_ATTR_STATUS, found,
- ATTR_TYPE_END);
- vstream_fflush(client_stream);
- }
-}
-
-/* post_jail_init - post-jail initialization */
-
-static void post_jail_init(char *unused_name, char **unused_argv)
-{
- rbl_domain = vstring_alloc(100);
- addr = vstring_alloc(100);
- query = vstring_alloc(100);
- why = vstring_alloc(100);
-}
-
-MAIL_VERSION_STAMP_DECLARE;
-
-/* main - pass control to the multi-threaded skeleton */
-
-int main(int argc, char **argv)
-{
-
- /*
- * Fingerprint executables and core dumps.
- */
- MAIL_VERSION_STAMP_ALLOCATE;
-
- multi_server_main(argc, argv, dnsblog_service,
- MAIL_SERVER_POST_INIT, post_jail_init,
- MAIL_SERVER_UNLIMITED,
- 0);
-}
* 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.7.0-RC1"
#ifdef SNAPSHOT
# define MAIL_VERSION_DATE "-" MAIL_RELEASE_DATE
/* oqmgr(8), old Postfix queue manager
/* pickup(8), Postfix local mail pickup
/* pipe(8), deliver mail to non-Postfix command
-/* postscreen(8), Postfix SMTP triage server
/* proxymap(8), Postfix lookup table proxy server
/* qmgr(8), Postfix queue manager
/* qmqpd(8), Postfix QMQP server
/* 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
+++ /dev/null
-../../.indent.pro
\ No newline at end of file
+++ /dev/null
-SHELL = /bin/sh
-SRCS = postscreen.c
-OBJS = postscreen.o
-HDRS =
-TESTSRC =
-DEFS = -I. -I$(INC_DIR) -D$(SYSTYPE)
-CFLAGS = $(DEBUG) $(OPT) $(DEFS)
-TESTPROG=
-PROG = postscreen
-INC_DIR = ../../include
-LIBS = ../../lib/libmaster.a ../../lib/libglobal.a ../../lib/libutil.a
-
-.c.o:; $(CC) $(CFLAGS) -c $*.c
-
-$(PROG): $(OBJS) $(LIBS)
- $(CC) $(CFLAGS) -o $@ $(OBJS) $(LIBS) $(SYSLIBS)
-
-$(OBJS): ../../conf/makedefs.out
-
-Makefile: Makefile.in
- cat ../../conf/makedefs.out $? >$@
-
-test: $(TESTPROG)
-
-tests: test
-
-root_tests:
-
-update: ../../libexec/$(PROG)
-
-../../libexec/$(PROG): $(PROG)
- cp $(PROG) ../../libexec
-
-printfck: $(OBJS) $(PROG)
- rm -rf printfck
- mkdir printfck
- sed '1,/^# do not edit/!d' Makefile >printfck/Makefile
- set -e; for i in *.c; do printfck -f .printfck $$i >printfck/$$i; done
- cd printfck; make "INC_DIR=../../../include" `cd ..; ls *.o`
-
-lint:
- lint $(DEFS) $(SRCS) $(LINTFIX)
-
-clean:
- rm -f *.o *core $(PROG) $(TESTPROG) junk
- rm -rf printfck
-
-tidy: clean
-
-depend: $(MAKES)
- (sed '1,/^# do not edit/!d' Makefile.in; \
- set -e; for i in [a-z][a-z0-9]*.c; do \
- $(CC) -E $(DEFS) $(INCL) $$i | grep -v '[<>]' | sed -n -e '/^# *1 *"\([^"]*\)".*/{' \
- -e 's//'`echo $$i|sed 's/c$$/o/'`': \1/' \
- -e 's/o: \.\//o: /' -e p -e '}' ; \
- done | sort -u) | grep -v '[.][o][:][ ][/]' >$$$$ && mv $$$$ Makefile.in
- @$(EXPORT) make -f Makefile.in Makefile 1>&2
-
-# do not edit below this line - it is generated by 'make depend'
-postscreen.o: ../../include/addr_match_list.h
-postscreen.o: ../../include/argv.h
-postscreen.o: ../../include/attr.h
-postscreen.o: ../../include/connect.h
-postscreen.o: ../../include/data_redirect.h
-postscreen.o: ../../include/dict.h
-postscreen.o: ../../include/dict_cache.h
-postscreen.o: ../../include/events.h
-postscreen.o: ../../include/format_tv.h
-postscreen.o: ../../include/htable.h
-postscreen.o: ../../include/iostuff.h
-postscreen.o: ../../include/mail_conf.h
-postscreen.o: ../../include/mail_params.h
-postscreen.o: ../../include/mail_proto.h
-postscreen.o: ../../include/mail_server.h
-postscreen.o: ../../include/mail_version.h
-postscreen.o: ../../include/match_list.h
-postscreen.o: ../../include/match_ops.h
-postscreen.o: ../../include/msg.h
-postscreen.o: ../../include/myaddrinfo.h
-postscreen.o: ../../include/mymalloc.h
-postscreen.o: ../../include/name_code.h
-postscreen.o: ../../include/sane_accept.h
-postscreen.o: ../../include/set_eugid.h
-postscreen.o: ../../include/stringops.h
-postscreen.o: ../../include/sys_defs.h
-postscreen.o: ../../include/vbuf.h
-postscreen.o: ../../include/vstream.h
-postscreen.o: ../../include/vstring.h
-postscreen.o: postscreen.c
+++ /dev/null
-/*++
-/* NAME
-/* postscreen 8
-/* SUMMARY
-/* Postfix SMTP triage server
-/* SYNOPSIS
-/* \fBpostscreen\fR [generic Postfix daemon options]
-/* DESCRIPTION
-/* The Postfix \fBpostscreen\fR(8) server performs triage on
-/* multiple inbound SMTP connections in parallel. While
-/* \fBpostscreen\fR(8) keeps zombies and other bogus clients
-/* away from Postfix SMTP server processes, more Postfix SMTP
-/* server processes remain available for legitimate clients.
-/* GENERAL OPERATION
-/* .ad
-/* .fi
-/* The triage process involves a number of tests, in the order
-/* as described below. Some tests introduce a delay of a few
-/* seconds. Once a client passes all tests, its IP address
-/* is temporarily excluded from the tests, typically for 24
-/* hours. This minimizes the impact of the tests on legitimate
-/* mail clients.
-/*
-/* After logging the result of its tests, \fBpostscreen\fR(8)
-/* by default forwards all connections to a real SMTP server
-/* process. This mode is useful for non-destructive testing.
-/*
-/* In a typical production setting, \fBpostscreen\fR(8) is
-/* configured to disconnect clients that fail some tests. A
-/* future implementation may pass the connection to a dummy
-/* SMTP protocol engine that logs sender and recipient information
-/* before hanging up.
-/*
-/* Note: \fBpostscreen\fR(8) is not an SMTP proxy; this is
-/* intentional. The purpose is to prioritize legitimate clients
-/* with as little overhead as possible.
-/* .SH 1. PERMANENT WHITELIST TEST
-/* .ad
-/* .fi
-/* The postscreen_whitelist_networks parameter (default:
-/* $mynetworks) specifies a permanent whitelist for SMTP client
-/* IP addresses.
-/*
-/* When the SMTP client address matches the permanent whitelist,
-/* this is logged as:
-/* .sp
-/* .nf
-/* \fBWHITELISTED \fIaddress\fR
-/* .fi
-/* .sp
-/* The action is not configurable: immediately forward the
-/* connection to a real SMTP server process.
-/* .SH 2. PERMANENT BLACKLIST TEST
-/* .ad
-/* .fi
-/* The postscreen_blacklist_networks parameter (default: empty)
-/* specifies a permanent blacklist for SMTP client IP addresses.
-/* The address syntax is as with mynetworks.
-/*
-/* When the SMTP client address matches the permanent blacklist,
-/* this is logged as:
-/* .sp
-/* .nf
-/* \fBBLACKLISTED \fIaddress\fR
-/* .fi
-/* .sp
-/* The postscreen_blacklist_action parameter specifies the
-/* action that is taken next:
-/* .IP "\fBcontinue\fR (default)"
-/* Continue with the SMTP GREETING PHASE TESTS below.
-/* .IP \fBdrop\fR
-/* Drop the connection immediately with a 521 SMTP reply. In
-/* a future implementation, the connection may instead be
-/* passed to a dummy SMTP protocol engine that logs sender and
-/* recipient information.
-/* .SH 3. TEMPORARY WHITELIST TEST
-/* .ad
-/* .fi
-/* The \fBpostscreen\fR(8) daemon maintains a \fItemporary\fR
-/* whitelist for SMTP client IP addresses that have passed all
-/* the tests described below. The postscreen_cache_map parameter
-/* specifies the location of the temporary whitelist. The
-/* temporary whitelist is not used for SMTP client addresses
-/* that appear on the \fIpermanent\fR blacklist or whitelist.
-/*
-/* When the SMTP client address appears on the temporary
-/* whitelist, this is logged as:
-/* .sp
-/* .nf
-/* \fBPASS OLD \fIaddress\fR
-/* .fi
-/* .sp
-/* The action is not configurable: immediately forward the
-/* connection to a real SMTP server process. The client is
-/* excluded from further tests until its temporary whitelist
-/* entry expires, as controlled with the postscreen_cache_ttl
-/* parameter. Expired entries are silently renewed if possible.
-/* .SH 4. SMTP GREETING PHASE TESTS
-/* .ad
-/* .fi
-/* The postscreen_greet_wait parameter specifies a time interval
-/* during which \fBpostscreen\fR(8) runs a number of tests in
-/* parallel. These tests are described below, and are run
-/* before the client may see the real SMTP server's "220
-/* text..." server greeting.
-/*
-/* When the SMTP client passes all greeting-phase tests, this
-/* is logged as:
-/* .sp
-/* .nf
-/* \fBPASS NEW \fIaddress\fR
-/* .fi
-/* .sp
-/* The action is to forward the connection to a real SMTP
-/* server process and to create a temporary whitelist entry
-/* that excludes the client IP address from further tests until
-/* the temporary whitelist entry expires, as controlled with
-/* the postscreen_cache_ttl parameter.
-/*
-/* In a future implementation, the connection may first be passed to
-/* a dummy SMTP protocol engine that implements more protocol
-/* tests including greylisting, before the client is allowed
-/* to talk to a real SMTP server process.
-/* .SH 4A. PREGREET TEST
-/* .ad
-/* .fi
-/* The postscreen_greet_banner parameter specifies the \fItext\fR
-/* portion of a "220-\fItext\fR..." teaser banner (default:
-/* $smtpd_banner).
-/* The \fBpostscreen\fR(8) daemon sends this before the
-/* postscreen_greet_wait timer is started. The purpose of the
-/* teaser banner is to confuse SPAM clients so that they speak
-/* before their turn. It has no effect on SMTP clients that
-/* correctly implement the protocol.
-/*
-/* To avoid problems with broken SMTP engines in network
-/* appliances, either exclude them from all tests with the
-/* postscreen_whitelist_networks feature or else specify an
-/* empty postscreen_greet_banner value to disable the "220-text..."
-/* teaser banner.
-/*
-/* When an SMTP client sends a command before the
-/* postscreen_greet_wait time has elapsed, this is logged as:
-/* .sp
-/* .nf
-/* \fBPREGREET \fIcount \fBafter \fItime \fBfrom \fIaddress text...\fR
-/* .fi
-/* .sp
-/* Translation: the client at \fIaddress\fR sent \fIcount\fR
-/* bytes before its turn to speak, and this happened \fItime\fR
-/* seconds after the postscreen_greet_wait timer was started.
-/* The \fItext\fR is what the client sent (truncated to 100
-/* bytes, and with non-printable characters replaced with "?").
-/*
-/* The postscreen_greet_action parameter specifies the action
-/* that is taken next:
-/* .IP "\fBcontinue\fR (default)"
-/* Wait until the postscreen_greet_wait time has elapsed, then
-/* report DNSBL lookup results if applicable. Either perform
-/* DNSBL-related actions or forward the connection to a real
-/* SMTP server process.
-/* .IP \fBdrop\fR
-/* Drop the connection immediately with a 521 SMTP reply.
-/* In a future implementation, the connection may instead be passed
-/* to a dummy SMTP protocol engine that logs sender and recipient
-/* information.
-/* .SH 4B. HANGUP TEST
-/* .ad
-/* .fi
-/* When the SMTP client hangs up without sending any data
-/* before the postscreen_greet_wait time has elapsed, this is
-/* logged as:
-/* .sp
-/* .nf
-/* \fBHANGUP after \fItime \fBfrom \fIaddress\fR
-/* .fi
-/* .sp
-/* The postscreen_hangup_action specifies the action
-/* that is taken next:
-/* .IP "\fBcontinue\fR (default)"
-/* Wait until the postscreen_greet_wait time has elapsed, then
-/* report DNSBL lookup results if applicable. Do not forward
-/* the broken connection to a real SMTP server process.
-/* .IP \fBdrop\fR
-/* Drop the connection immediately.
-/* .SH 4C. DNS BLOCKLIST TEST
-/* .ad
-/* .fi
-/* The postscreen_dnsbl_sites parameter (default: empty)
-/* specifies a list of DNS blocklist servers. These lookups
-/* are made in parallel.
-/*
-/* When the postscreen_greet_wait time has elapsed, and the
-/* SMTP client address is listed with at least one of these
-/* blocklists, this is logged as:
-/* .sp
-/* .nf
-/* \fBDNSBL rank \fIcount \fBfor \fIaddress\fR
-/* .fi
-/* .sp
-/* Translation: the client at \fIaddress\fR is listed with
-/* \fIcount\fR DNSBL servers. The \fIcount\fR does not
-/* depend on the number of DNS records that an individual DNSBL
-/* server returns.
-/*
-/* The postscreen_dnsbl_action parameter specifies the action
-/* that is taken next:
-/* .IP "\fBcontinue\fR (default)"
-/* Forward the connection to a real SMTP server process.
-/* .IP \fBdrop\fR
-/* Drop the connection immediately with a 521 SMTP reply.
-/* In a future implementation, the connection may instead be passed
-/* to a dummy SMTP protocol engine that logs sender and recipient
-/* information.
-/* SECURITY
-/* .ad
-/* .fi
-/* The \fBpostscreen\fR(8) server is moderately security-sensitive.
-/* It talks to untrusted clients on the network. The process
-/* can be run chrooted at fixed low privilege.
-/* STANDARDS
-/* RFC 5321 (SMTP, including multi-line 220 greetings)
-/* RFC 2920 (SMTP Pipelining)
-/* DIAGNOSTICS
-/* Problems and transactions are logged to \fBsyslogd\fR(8).
-/* CONFIGURATION PARAMETERS
-/* .ad
-/* .fi
-/* Changes to main.cf are not picked up automatically, as
-/* \fBpostscreen\fR(8) processes may run for several hours.
-/* Use the command "postfix reload" after a configuration
-/* change.
-/*
-/* The text below provides only a parameter summary. See
-/* \fBpostconf\fR(5) for more details including examples.
-/* TRIAGE PARAMETERS
-/* .ad
-/* .fi
-/* .IP "\fBpostscreen_blacklist_action (continue)\fR"
-/* The action that \fBpostscreen\fR(8) takes when an SMTP client is
-/* permanently blacklisted with the postscreen_blacklist_networks
-/* parameter.
-/* .IP "\fBpostscreen_blacklist_networks (empty)\fR"
-/* Network addresses that are permanently blacklisted; see the
-/* postscreen_blacklist_action parameter for possible actions.
-/* .IP "\fBpostscreen_dnsbl_action (continue)\fR"
-/* The action that \fBpostscreen\fR(8) takes when an SMTP client is listed
-/* at the DNS blocklist domains specified with the postscreen_dnsbl_sites
-/* parameter.
-/* .IP "\fBpostscreen_dnsbl_sites (empty)\fR"
-/* Optional list of DNS blocklist domains.
-/* .IP "\fBpostscreen_greet_action (continue)\fR"
-/* The action that \fBpostscreen\fR(8) takes when an SMTP client speaks
-/* before its turn within the time specified with the postscreen_greet_wait
-/* parameter.
-/* .IP "\fBpostscreen_greet_banner ($smtpd_banner)\fR"
-/* The \fItext\fR in the optional "220-\fItext\fR..." server
-/* response that
-/* \fBpostscreen\fR(8) sends ahead of the real Postfix SMTP server's "220
-/* text..." response, in an attempt to confuse bad SMTP clients so
-/* that they speak before their turn (pre-greet).
-/* .IP "\fBpostscreen_greet_wait (4s)\fR"
-/* The amount of time that \fBpostscreen\fR(8) will wait for an SMTP
-/* client to send a command before its turn, and for DNS blocklist
-/* lookup results to arrive.
-/* .IP "\fBpostscreen_hangup_action (continue)\fR"
-/* The action that \fBpostscreen\fR(8) takes when an SMTP client disconnects
-/* without sending data, within the time specified with the
-/* postscreen_greet_wait parameter.
-/* .IP "\fBpostscreen_post_queue_limit ($default_process_limit)\fR"
-/* The number of clients that can be waiting for service from a
-/* real SMTP server process.
-/* .IP "\fBpostscreen_pre_queue_limit ($default_process_limit)\fR"
-/* The number of non-whitelisted clients that can be waiting for
-/* a decision whether they will receive service from a real SMTP server
-/* process.
-/* .IP "\fBpostscreen_whitelist_networks ($mynetworks)\fR"
-/* Network addresses that are permanently whitelisted, and that
-/* will not be subjected to \fBpostscreen\fR(8) checks.
-/* .IP "\fBsmtpd_service (smtpd)\fR"
-/* The internal service that \fBpostscreen\fR(8) forwards allowed
-/* connections to.
-/* CACHE CONTROLS
-/* .ad
-/* .fi
-/* .IP "\fBpostscreen_cache_cleanup_interval (12h)\fR"
-/* The amount of time between \fBpostscreen\fR(8) cache cleanup runs.
-/* .IP "\fBpostscreen_cache_map (btree:$data_directory/ps_whitelist)\fR"
-/* Persistent storage for the \fBpostscreen\fR(8) server decisions.
-/* .IP "\fBpostscreen_cache_retention_time (1d)\fR"
-/* The amount of time that \fBpostscreen\fR(8) will cache an expired
-/* temporary whitelist entry before it is removed.
-/* .IP "\fBpostscreen_cache_ttl (1d)\fR"
-/* The amount of time that \fBpostscreen\fR(8) will cache a decision for
-/* a specific SMTP client IP address.
-/* MISCELLANEOUS CONTROLS
-/* .ad
-/* .fi
-/* .IP "\fBconfig_directory (see 'postconf -d' output)\fR"
-/* The default location of the Postfix main.cf and master.cf
-/* configuration files.
-/* .IP "\fBdaemon_timeout (18000s)\fR"
-/* How much time a Postfix daemon process may take to handle a
-/* request before it is terminated by a built-in watchdog timer.
-/* .IP "\fBdelay_logging_resolution_limit (2)\fR"
-/* The maximal number of digits after the decimal point when logging
-/* sub-second delay values.
-/* .IP "\fBcommand_directory (see 'postconf -d' output)\fR"
-/* The location of all postfix administrative commands.
-/* .IP "\fBipc_timeout (3600s)\fR"
-/* The time limit for sending or receiving information over an internal
-/* communication channel.
-/* .IP "\fBmax_idle (100s)\fR"
-/* The maximum amount of time that an idle Postfix daemon process waits
-/* for an incoming connection before terminating voluntarily.
-/* .IP "\fBprocess_id (read-only)\fR"
-/* The process ID of a Postfix command or daemon process.
-/* .IP "\fBprocess_name (read-only)\fR"
-/* The process name of a Postfix command or daemon process.
-/* .IP "\fBsyslog_facility (mail)\fR"
-/* The syslog facility of Postfix logging.
-/* .IP "\fBsyslog_name (see 'postconf -d' output)\fR"
-/* The mail system name that is prepended to the process name in syslog
-/* records, so that "smtpd" becomes, for example, "postfix/smtpd".
-/* SEE ALSO
-/* smtpd(8), Postfix SMTP server
-/* dnsblog(8), temporary DNS helper
-/* syslogd(8), system logging
-/* LICENSE
-/* .ad
-/* .fi
-/* The Secure Mailer license must be distributed with this software.
-/* AUTHOR(S)
-/* Wietse Venema
-/* IBM T.J. Watson Research
-/* P.O. Box 704
-/* Yorktown Heights, NY 10598, USA
-/*--*/
-
-/* System library. */
-
-#include <sys_defs.h>
-#include <sys/stat.h>
-#include <stdlib.h>
-
-#ifdef STRCASECMP_IN_STRINGS_H
-#include <strings.h>
-#endif
-
-#ifdef MISSING_STRTOUL
-#define strtoul strtol
-#endif
-
-/* Utility library. */
-
-#include <msg.h>
-#include <connect.h>
-#include <iostuff.h>
-#include <events.h>
-#include <mymalloc.h>
-#include <myaddrinfo.h>
-#include <dict_cache.h>
-#include <sane_accept.h>
-#include <stringops.h>
-#include <set_eugid.h>
-#include <vstream.h>
-#include <format_tv.h>
-#include <htable.h>
-#include <name_code.h>
-
-/* Global library. */
-
-#include <mail_conf.h>
-#include <mail_params.h>
-#include <mail_version.h>
-#include <mail_proto.h>
-#include <addr_match_list.h>
-#include <data_redirect.h>
-
-/* Master server protocols. */
-
-#include <mail_server.h>
-
- /*
- * Configuration parameters.
- */
-char *var_smtpd_service;
-char *var_smtpd_banner;
-char *var_ps_cache_map;
-int var_ps_post_queue_limit;
-int var_ps_pre_queue_limit;
-int var_proc_limit;
-int var_ps_cache_ttl;
-int var_ps_cache_ret;
-int var_ps_cache_scan;
-int var_ps_greet_wait;
-char *var_ps_dnsbl_sites;
-char *var_ps_dnsbl_action;
-char *var_ps_greet_action;
-char *var_ps_hangup_action;
-char *var_ps_wlist_nets;
-char *var_ps_blist_nets;
-char *var_ps_greet_banner;
-char *var_ps_blist_action;
-
- /*
- * Per-session state. See also: new_session_state() and free_event_state()
- * below.
- */
-typedef struct {
- int flags; /* see below */
- VSTREAM *smtp_client_stream; /* remote SMTP client */
- int smtp_server_fd; /* real SMTP server */
- char *smtp_client_addr; /* client address */
- char *smtp_client_port; /* client port */
- struct timeval creation_time; /* as the name says */
-} PS_STATE;
-
-#define PS_FLAG_NOCACHE (1<<0) /* don't store this client */
-#define PS_FLAG_NOFORWARD (1<<1) /* don't forward this session */
-#define PS_FLAG_EXPIRED (1<<2) /* whitelist expired */
-#define PS_FLAG_WHITELISTED (1<<3) /* whitelisted (temp or perm) */
-
- /*
- * This program screens all inbound SMTP connections, so it better not waste
- * time.
- */
-#define PS_GREET_TIMEOUT 5
-#define PS_SMTP_WRITE_TIMEOUT 1
-#define PS_SEND_SOCK_CONNECT_TIMEOUT 1
-#define PS_SEND_SOCK_NOTIFY_TIMEOUT 100
-
-#define PS_READ_BUF_SIZE 1024
-
-#define DNSBL_SERVICE "dnsblog"
-#define DNSBLOG_TIMEOUT 10
-
-#define PS_ACT_DROP 1
-#define PS_ACT_CONT 2
-
-static int check_queue_length; /* connections being checked */
-static int post_queue_length; /* being sent to real SMTPD */
-static DICT_CACHE *cache_map; /* cache table handle */
-static VSTRING *temp; /* scratchpad */
-static char *smtp_service_name; /* path to real SMTPD */
-static char *teaser_greeting; /* spamware teaser banner */
-static ARGV *dnsbl_sites; /* dns blocklist domains */
-static VSTRING *reply_addr; /* address in DNSBL reply */
-static VSTRING *reply_domain; /* domain in DNSBL reply */
-static HTABLE *dnsbl_cache; /* entries being queried */
-static int dnsbl_action; /* PS_ACT_DROP or PS_ACT_CONT */
-static int greet_action; /* PS_ACT_DROP or PS_ACT_CONT */
-static int hangup_action; /* PS_ACT_DROP or PS_ACT_CONT */
-static ADDR_MATCH_LIST *wlist_nets; /* permanently whitelisted networks */
-static ADDR_MATCH_LIST *blist_nets; /* permanently blacklisted networks */
-static int blist_action; /* PS_ACT_DROP or PS_ACT_CONT */
-
- /*
- * See log_adhoc.c for discussion.
- */
-typedef struct {
- int dt_sec; /* make sure it's signed */
- int dt_usec; /* make sure it's signed */
-} DELTA_TIME;
-
-#define PS_CALC_DELTA(x, y, z) \
- do { \
- (x).dt_sec = (y).tv_sec - (z).tv_sec; \
- (x).dt_usec = (y).tv_usec - (z).tv_usec; \
- while ((x).dt_usec < 0) { \
- (x).dt_usec += 1000000; \
- (x).dt_sec -= 1; \
- } \
- while ((x).dt_usec >= 1000000) { \
- (x).dt_usec -= 1000000; \
- (x).dt_sec += 1; \
- } \
- if ((x).dt_sec < 0) \
- (x).dt_sec = (x).dt_usec = 0; \
- } while (0)
-
-#define SIG_DIGS 2
-
-/* READ_EVENT_REQUEST - prepare for transition to next state */
-
-#define READ_EVENT_REQUEST(fd, action, context, timeout) do { \
- if (msg_verbose) msg_info("%s: read-request fd=%d", myname, (fd)); \
- event_enable_read((fd), (action), (context)); \
- event_request_timer((action), (context), (timeout)); \
-} while (0)
-
-/* CLEAR_EVENT_REQUEST - complete state transition */
-
-#define CLEAR_EVENT_REQUEST(fd, action, context) do { \
- if (msg_verbose) msg_info("%s: clear-request fd=%d", myname, (fd)); \
- event_disable_readwrite(fd); \
- event_cancel_timer((action), (context)); \
-} while (0)
-
-/* SLMs. */
-
-#define STR(x) vstring_str(x)
-#define LEN(x) VSTRING_LEN(x)
-
- /*
- * Monitor time-critical operations.
- */
-#define PS_GET_TIME_BEFORE_LOOKUP \
- struct timeval _before, _after; \
- DELTA_TIME _delta; \
- GETTIMEOFDAY(&_before);
-
-#define PS_DELTA_MS(d) ((d).dt_sec * 1000 + (d).dt_usec / 1000)
-
-#define PS_CHECK_TIME_AFTER_LOOKUP(table, action) \
- GETTIMEOFDAY(&_after); \
- PS_CALC_DELTA(_delta, _after, _before); \
- if (_delta.dt_sec > 1 || _delta.dt_usec > 100000) \
- msg_warn("%s: %s %s took %d ms", \
- myname, (table), (action), PS_DELTA_MS(_delta));
-
-/* ps_addr_match_list_match - time-critical address list lookup */
-
-static int ps_addr_match_list_match(ADDR_MATCH_LIST *addr_list,
- const char *addr_str)
-{
- const char *myname = "ps_addr_match_list_match";
- int result;
-
- PS_GET_TIME_BEFORE_LOOKUP;
- result = addr_match_list_match(addr_list, addr_str);
- PS_CHECK_TIME_AFTER_LOOKUP("address list", "lookup");
- return (result);
-}
-
-/* ps_dict_get - time-critical table lookup */
-
-static const char *ps_dict_get(DICT_CACHE *cache, const char *key)
-{
- const char *myname = "ps_dict_get";
- const char *result;
-
- PS_GET_TIME_BEFORE_LOOKUP;
- result = dict_cache_lookup(cache, key);
- PS_CHECK_TIME_AFTER_LOOKUP(dict_cache_name(cache), "lookup");
- return (result);
-}
-
-/* ps_dict_put - table dictionary update */
-
-static void ps_dict_put(DICT_CACHE *cache, const char *key, const char *value)
-{
- const char *myname = "ps_dict_put";
-
- PS_GET_TIME_BEFORE_LOOKUP;
- dict_cache_update(cache, key, value);
- PS_CHECK_TIME_AFTER_LOOKUP(dict_cache_name(cache), "update");
-}
-
- /*
- * DNSBL lookup status per client IP address.
- */
-typedef struct {
- int dnsbl_count; /* is this address listed */
- int refcount; /* query reference count */
-} PS_DNSBL_ENTRY;
-
-/* postscreen_dnsbl_entry_create - create blocklist cache entry */
-
-static PS_DNSBL_ENTRY *postscreen_dnsbl_entry_create(void)
-{
- PS_DNSBL_ENTRY *entry;
-
- entry = (PS_DNSBL_ENTRY *) mymalloc(sizeof(*entry));
- entry->dnsbl_count = 0;
- entry->refcount = 0;
- return (entry);
-}
-
-/* postscreen_dnsbl_done - get blocklist cache entry, decrement refcount */
-
-static int postscreen_dnsbl_done(const char *addr)
-{
- const char *myname = "postscreen_dnsbl_done";
- PS_DNSBL_ENTRY *entry;
- int dnsbl_count;
-
- /*
- * Sanity check.
- */
- if ((entry = (PS_DNSBL_ENTRY *) htable_find(dnsbl_cache, addr)) == 0)
- msg_panic("%s: no blocklist cache entry for %s", myname, addr);
-
- /*
- * Yes, cache reads are destructive.
- */
- dnsbl_count = entry->dnsbl_count;
- entry->refcount -= 1;
- if (entry->refcount < 1) {
- if (msg_verbose)
- msg_info("%s: delete cache entry for %s", myname, addr);
- htable_delete(dnsbl_cache, addr, myfree);
- }
- return (dnsbl_count);
-}
-
-/* postscreen_dnsbl_reply - receive dnsbl reply, update blocklist cache entry */
-
-static void postscreen_dnsbl_reply(int event, char *context)
-{
- const char *myname = "postscreen_dnsbl_reply";
- VSTREAM *stream = (VSTREAM *) context;
- PS_DNSBL_ENTRY *entry;
- int dnsbl_count;
-
- CLEAR_EVENT_REQUEST(vstream_fileno(stream), postscreen_dnsbl_reply, context);
-
- /*
- * Later, this will become an UDP-based DNS client that is built directly
- * into the postscreen daemon.
- *
- * Don't panic when no blocklist cache entry exists. It may be gone when the
- * client triggered a "drop" action after pregreet, DNSBL lookup, or
- * hangup.
- */
- if (event == EVENT_READ
- && attr_scan(stream,
- ATTR_FLAG_MORE | ATTR_FLAG_STRICT,
- ATTR_TYPE_STR, MAIL_ATTR_RBL_DOMAIN, reply_domain,
- ATTR_TYPE_STR, MAIL_ATTR_ADDR, reply_addr,
- ATTR_TYPE_INT, MAIL_ATTR_STATUS, &dnsbl_count,
- ATTR_TYPE_END) == 3) {
- if ((entry = (PS_DNSBL_ENTRY *)
- htable_find(dnsbl_cache, STR(reply_addr))) != 0)
- entry->dnsbl_count += dnsbl_count;
- }
- vstream_fclose(stream);
-}
-
-/* postscreen_dnsbl_query - send dnsbl query */
-
-static void postscreen_dnsbl_query(const char *addr)
-{
- const char *myname = "postscreen_dnsbl_query";
- int fd;
- VSTREAM *stream;
- char **cpp;
- PS_DNSBL_ENTRY *entry;
-
- /*
- * Avoid duplicate effort when this lookup is already in progress. Now,
- * we destroy the entry when the client replies. Later, we increment
- * refcounts with queries sent, and decrement refcounts with replies
- * received, so we can maintain state even after a client talks early,
- * and update the external cache asynchronously.
- */
- if ((entry = (PS_DNSBL_ENTRY *) htable_find(dnsbl_cache, addr)) != 0) {
- entry->refcount += 1;
- return;
- }
- if (msg_verbose)
- msg_info("%s: create cache entry for %s", myname, addr);
- entry = postscreen_dnsbl_entry_create();
- (void) htable_enter(dnsbl_cache, addr, (char *) entry);
- entry->refcount = 1;
-
- /*
- * Later, this will become an UDP-based DNS client that is built directly
- * into the postscreen daemon.
- */
- for (cpp = dnsbl_sites->argv; *cpp; cpp++) {
- if ((fd = LOCAL_CONNECT("private/" DNSBL_SERVICE, NON_BLOCKING, 1)) < 0) {
- msg_warn("%s: connect to " DNSBL_SERVICE " service: %m", myname);
- return;
- }
- stream = vstream_fdopen(fd, O_RDWR);
- attr_print(stream, ATTR_FLAG_NONE,
- ATTR_TYPE_STR, MAIL_ATTR_RBL_DOMAIN, *cpp,
- ATTR_TYPE_STR, MAIL_ATTR_ADDR, addr,
- ATTR_TYPE_END);
- if (vstream_fflush(stream) != 0) {
- msg_warn("%s: error sending to " DNSBL_SERVICE " service: %m", myname);
- vstream_fclose(stream);
- return;
- }
- READ_EVENT_REQUEST(vstream_fileno(stream), postscreen_dnsbl_reply,
- (char *) stream, DNSBLOG_TIMEOUT);
- }
-}
-
-/* new_session_state - fill in connection state for event processing */
-
-static PS_STATE *new_session_state(VSTREAM *stream, const char *addr,
- const char *port)
-{
- PS_STATE *state;
-
- state = (PS_STATE *) mymalloc(sizeof(*state));
- state->flags = 0;
- if ((state->smtp_client_stream = stream) != 0)
- check_queue_length++;
- state->smtp_server_fd = (-1);
- state->smtp_client_addr = mystrdup(addr);
- state->smtp_client_port = mystrdup(port);
- GETTIMEOFDAY(&state->creation_time);
- return (state);
-}
-
-/* free_session_state - destroy connection state including connections */
-
-static void free_session_state(PS_STATE *state)
-{
- if (state->smtp_client_stream != 0) {
- event_server_disconnect(state->smtp_client_stream);
- check_queue_length--;
- }
- if (state->smtp_server_fd >= 0) {
- close(state->smtp_server_fd);
- post_queue_length--;
- }
- myfree(state->smtp_client_addr);
- myfree(state->smtp_client_port);
- myfree((char *) state);
-
- if (check_queue_length < 0 || post_queue_length < 0)
- msg_panic("bad queue length: check_queue=%d, post_queue=%d",
- check_queue_length, post_queue_length);
-}
-
-/* mydelta_time - pretty-formatted delta time */
-
-static char *mydelta_time(VSTRING *buf, struct timeval tv, int *delta)
-{
- DELTA_TIME pdelay;
- struct timeval now;
-
- GETTIMEOFDAY(&now);
- PS_CALC_DELTA(pdelay, now, tv);
- VSTRING_RESET(buf);
- format_tv(buf, pdelay.dt_sec, pdelay.dt_usec, SIG_DIGS, var_delay_max_res);
- *delta = pdelay.dt_sec;
- return (STR(buf));
-}
-
-/* smtp_reply - reply to the client */
-
-static int smtp_reply(int smtp_client_fd, const char *smtp_client_addr,
- const char *smtp_client_port, const char *text)
-{
- int ret;
-
- /*
- * XXX Need to make sure that the TCP send buffer is large enough for any
- * response, so that a nasty client can't cause this process to block.
- */
- ret = (write_buf(smtp_client_fd, text, strlen(text), 1) < 0);
- if (ret != 0 && errno != EPIPE)
- msg_warn("write %s:%s: %m", smtp_client_addr, smtp_client_port);
- return (ret);
-}
-
-/* send_socket_close_event - file descriptor has arrived or timeout */
-
-static void send_socket_close_event(int event, char *context)
-{
- const char *myname = "send_socket_close_event";
- PS_STATE *state = (PS_STATE *) context;
-
- if (msg_verbose)
- msg_info("%s: sq=%d cq=%d event %d on send socket %d from %s:%s",
- myname, post_queue_length, check_queue_length,
- event, state->smtp_server_fd, state->smtp_client_addr,
- state->smtp_client_port);
-
- /*
- * The real SMTP server has closed the local IPC channel, or we have
- * reached the limit of our patience. In the latter case it is still
- * possible that the real SMTP server will receive the socket so we
- * should not interfere.
- */
- CLEAR_EVENT_REQUEST(state->smtp_server_fd, send_socket_close_event, context);
-
- switch (event) {
- case EVENT_TIME:
- msg_warn("timeout sending connection to service %s", smtp_service_name);
- break;
- default:
- break;
- }
- free_session_state(state);
-}
-
-/* send_socket - send socket to real smtpd */
-
-static void send_socket(PS_STATE *state)
-{
- const char *myname = "send_socket";
- int window_size;
-
- if (msg_verbose)
- msg_info("%s: sq=%d cq=%d send socket %d from %s:%s",
- myname, post_queue_length, check_queue_length,
- vstream_fileno(state->smtp_client_stream), state->smtp_client_addr,
- state->smtp_client_port);
-
- /*
- * This is where we would adjust the window size to a value that is
- * appropriate for this client class.
- */
-#if 0
- window_size = 65535;
- if (setsockopt(vstream_fileno(state->smtp_client_stream), SOL_SOCKET, SO_RCVBUF,
- (char *) &window_size, sizeof(window_size)) < 0)
- msg_warn("setsockopt SO_RCVBUF %d: %m", window_size);
-#endif
-
- /*
- * Connect to the real SMTP service over a local IPC channel, send the
- * file descriptor, and close the file descriptor to save resources.
- * Experience has shown that some systems will discard information when
- * we close a channel immediately after writing. Thus, we waste resources
- * waiting for the remote side to close the local IPC channel first. The
- * good side of waiting is that we learn when the real SMTP server is
- * falling behind.
- *
- * This is where we would forward the connection to an SMTP server that
- * provides an appropriate level of service for this client class. For
- * example, a server that is more forgiving, or one that is more
- * suspicious. Alternatively, we could send attributes along with the
- * socket with client reputation information, making everything even more
- * Postfix-specific.
- */
- if ((state->smtp_server_fd = LOCAL_CONNECT(smtp_service_name, NON_BLOCKING,
- PS_SEND_SOCK_CONNECT_TIMEOUT)) < 0) {
- msg_warn("cannot connect to service %s: %m", smtp_service_name);
- smtp_reply(vstream_fileno(state->smtp_client_stream),
- state->smtp_client_addr, state->smtp_client_port,
- "421 4.3.2 All server ports are busy\r\n");
- free_session_state(state);
- return;
- }
- post_queue_length++;
- if (LOCAL_SEND_FD(state->smtp_server_fd,
- vstream_fileno(state->smtp_client_stream)) < 0) {
- msg_warn("cannot pass connection to service %s: %m", smtp_service_name);
- smtp_reply(vstream_fileno(state->smtp_client_stream), state->smtp_client_addr,
- state->smtp_client_port, "421 4.3.2 No system resources\r\n");
- free_session_state(state);
- return;
- } else {
-
- /*
- * Closing the smtp_client_fd here triggers a FreeBSD 7.1 kernel bug
- * where smtp-source sometimes sees the connection being closed after
- * it has already received the real SMTP server's 220 greeting!
- */
-#if 0
- event_server_disconnect(state->smtp_client_stream);
- state->smtp_client_stream = 0;
- check_queue_length--;
-#endif
- READ_EVENT_REQUEST(state->smtp_server_fd, send_socket_close_event,
- (char *) state, PS_SEND_SOCK_NOTIFY_TIMEOUT);
- return;
- }
-}
-
-/* smtp_read_event - handle pre-greet, EOF or timeout. */
-
-static void smtp_read_event(int event, char *context)
-{
- const char *myname = "smtp_read_event";
- PS_STATE *state = (PS_STATE *) context;
- char read_buf[PS_READ_BUF_SIZE];
- int read_count;
- int dnsbl_count;
- int elapsed;
- int action;
-
- if (msg_verbose)
- msg_info("%s: sq=%d cq=%d event %d on smtp socket %d from %s:%s",
- myname, post_queue_length, check_queue_length,
- event, vstream_fileno(state->smtp_client_stream),
- state->smtp_client_addr, state->smtp_client_port);
-
- /*
- * Either the remote SMTP client spoke before its turn, the connection
- * was closed, or we reached the limit of our patience.
- */
- CLEAR_EVENT_REQUEST(vstream_fileno(state->smtp_client_stream),
- smtp_read_event, context);
-
- /*
- * If this session ends here, we MUST read the blocklist cache otherwise
- * we have a memory leak.
- */
- switch (event) {
-
- /*
- * The SMTP client did not speak before its turn. If it is DNS
- * blocklisted, drop the connection, or continue and forward the
- * connection to the real SMTP server.
- *
- * This is where we would use a dummy SMTP protocol engine to further
- * investigate whether the client cuts corners in the protocol,
- * before allowing it to talk to a real SMTP server process.
- */
- case EVENT_TIME:
- if (*var_ps_dnsbl_sites)
- dnsbl_count = postscreen_dnsbl_done(state->smtp_client_addr);
- else
- dnsbl_count = 0;
- if (dnsbl_count > 0) {
- msg_info("DNSBL rank %d for %s",
- dnsbl_count, state->smtp_client_addr);
- if (dnsbl_action == PS_ACT_DROP) {
- smtp_reply(vstream_fileno(state->smtp_client_stream),
- state->smtp_client_addr, state->smtp_client_port,
- "521 5.7.1 Blocked by DNSBL\r\n");
- state->flags |= PS_FLAG_NOFORWARD;
- }
- state->flags |= PS_FLAG_NOCACHE;
- }
- if (state->flags & PS_FLAG_NOFORWARD) {
- free_session_state(state);
- } else {
- if ((state->flags & PS_FLAG_NOCACHE) == 0) {
- msg_info("PASS %s %s", (state->flags & PS_FLAG_EXPIRED) ?
- "OLD" : "NEW", state->smtp_client_addr);
- if (cache_map != 0) {
- vstring_sprintf(temp, "%ld", (long) event_time());
- ps_dict_put(cache_map, state->smtp_client_addr, STR(temp));
- }
- }
- send_socket(state);
- }
- break;
-
- /*
- * EOF or the client spoke before its turn. We simply drop the
- * connection, or we continue waiting and allow DNS replies to
- * trickle in.
- *
- * This is where we would use a dummy SMTP protocol engine to obtain the
- * sender and recipient information before dropping a pregreeter's
- * connection.
- */
- default:
- if ((read_count = recv(vstream_fileno(state->smtp_client_stream),
- read_buf, sizeof(read_buf) - 1, MSG_PEEK)) > 0) {
- read_buf[read_count] = 0;
- msg_info("PREGREET %d after %s from %s: %.100s", read_count,
- mydelta_time(temp, state->creation_time, &elapsed),
- state->smtp_client_addr, printable(read_buf, '?'));
- action = greet_action;
- if (action == PS_ACT_DROP)
- smtp_reply(vstream_fileno(state->smtp_client_stream),
- state->smtp_client_addr, state->smtp_client_port,
- "521 5.5.1 Protocol error\r\n");
- } else {
- msg_info("HANGUP after %s from %s",
- mydelta_time(temp, state->creation_time, &elapsed),
- state->smtp_client_addr);
- action = hangup_action;
- state->flags |= PS_FLAG_NOFORWARD;
- }
- if (action == PS_ACT_DROP) {
- if (*var_ps_dnsbl_sites)
- (void) postscreen_dnsbl_done(state->smtp_client_addr);
- free_session_state(state);
- } else {
- state->flags |= PS_FLAG_NOCACHE;
- /* not: postscreen_dnsbl_done */
- if (elapsed > var_ps_greet_wait)
- elapsed = var_ps_greet_wait;
- event_request_timer(smtp_read_event, context,
- var_ps_greet_wait - elapsed);
- }
- break;
- }
-}
-
-/* postscreen_dump - dump some statistics before exit */
-
-static void postscreen_dump(void)
-{
-
- /*
- * Dump preliminary cache cleanup statistics when the process commits
- * suicide while a cache cleanup run is in progress. We can't currently
- * distinguish between "postfix reload" (we should restart) or "maximal
- * idle time reached" (we could finish the cache cleanup first).
- */
- if (cache_map) {
- dict_cache_close(cache_map);
- cache_map = 0;
- }
-}
-
-/* postscreen_drain - delayed exit after "postfix reload" */
-
-static void postscreen_drain(char *unused_service, char **unused_argv)
-{
- int count;
-
- /*
- * After "postfix reload", complete work-in-progress in the background,
- * instead of dropping already-accepted connections on the floor.
- *
- * Unfortunately we must close all writable tables, so we can't store or
- * look up reputation information. The reason is that we don't have any
- * multi-writer safety guarantees. We also can't use the single-writer
- * proxywrite service, because its latency guarantees are too weak.
- *
- * All error retry counts shall be limited. Instead of blocking here, we
- * could retry failed fork() operations in the event call-back routines,
- * but we don't need perfection. The host system is severely overloaded
- * and service levels are already way down.
- *
- * XXX Some Berkeley DB versions break with close-after-fork. Every new
- * version is an improvement over its predecessor.
- */
- if (cache_map != 0) {
- dict_cache_close(cache_map);
- cache_map = 0;
- }
- for (count = 0; /* see below */ ; count++) {
- if (count >= 5) {
- msg_fatal("fork: %m");
- } else if (event_server_drain() != 0) {
- msg_warn("fork: %m");
- sleep(1);
- continue;
- } else {
- return;
- }
- }
-}
-
-/* postscreen_service - handle new client connection */
-
-static void postscreen_service(VSTREAM *smtp_client_stream,
- char *unused_service,
- char **unused_argv)
-{
- const char *myname = "postscreen_service";
- PS_STATE *state;
- struct sockaddr_storage addr_storage;
- SOCKADDR_SIZE addr_storage_len = sizeof(addr_storage);
- MAI_HOSTADDR_STR smtp_client_addr;
- MAI_SERVPORT_STR smtp_client_port;
- int aierr;
- const char *stamp_str;
- time_t stamp_time;
- int window_size;
- int state_flags = 0;
-
- /*
- * This program handles all incoming connections, so it must not block.
- * We use event-driven code for all operations that introduce latency.
- *
- * We use the event_server framework. This means we get already-accepted
- * connections wrapped into a VSTREAM so we have to invoke getpeername()
- * to find out the remote address and port.
- */
-
-#define PS_SERVICE_GIVEUP_AND_RETURN(stream) do { \
- event_server_disconnect(stream); \
- return; \
- } while (0);
-
- /*
- * Look up the remote SMTP client address and port.
- */
- if (getpeername(vstream_fileno(smtp_client_stream), (struct sockaddr *)
- & addr_storage, &addr_storage_len) < 0) {
- msg_warn("getpeername: %m");
- smtp_reply(vstream_fileno(smtp_client_stream),
- "unknown_address", "unknown_port",
- "421 4.3.2 No system resources\r\n");
- PS_SERVICE_GIVEUP_AND_RETURN(smtp_client_stream);
- }
-
- /*
- * Convert the remote SMTP client address and port to printable form for
- * logging and access control.
- */
- if ((aierr = sockaddr_to_hostaddr((struct sockaddr *) & addr_storage,
- addr_storage_len, &smtp_client_addr,
- &smtp_client_port, 0)) != 0) {
- msg_warn("cannot convert client address/port to string: %s",
- MAI_STRERROR(aierr));
- smtp_reply(vstream_fileno(smtp_client_stream),
- "unknown_address", "unknown_port",
- "421 4.3.2 No system resources\r\n");
- PS_SERVICE_GIVEUP_AND_RETURN(smtp_client_stream);
- }
- if (strncasecmp("::ffff:", smtp_client_addr.buf, 7) == 0)
- memmove(smtp_client_addr.buf, smtp_client_addr.buf + 7,
- sizeof(smtp_client_addr.buf) - 7);
- if (msg_verbose)
- msg_info("%s: sq=%d cq=%d connect from %s:%s",
- myname, post_queue_length, check_queue_length,
- smtp_client_addr.buf, smtp_client_port.buf);
-
- /*
- * Reply with 421 when we can't forward more connections.
- */
- if (var_ps_post_queue_limit > 0
- && post_queue_length >= var_ps_post_queue_limit) {
- msg_info("reject: connect from %s:%s: all server ports busy",
- smtp_client_addr.buf, smtp_client_port.buf);
- smtp_reply(vstream_fileno(smtp_client_stream),
- smtp_client_addr.buf, smtp_client_port.buf,
- "421 4.3.2 All server ports are busy\r\n");
- PS_SERVICE_GIVEUP_AND_RETURN(smtp_client_stream);
- }
-
- /*
- * The permanent whitelist has highest precedence (never block mail from
- * whitelisted sites).
- */
- if (wlist_nets != 0
- && ps_addr_match_list_match(wlist_nets, smtp_client_addr.buf) != 0) {
- msg_info("WHITELISTED %s", smtp_client_addr.buf);
- state_flags |= PS_FLAG_WHITELISTED;
- }
-
- /*
- * The permanent blacklist has second precedence. If the client is
- * permanently blacklisted, send some generic reply and hang up
- * immediately, or torture them a little longer.
- */
- else if (blist_nets != 0
- && ps_addr_match_list_match(blist_nets, smtp_client_addr.buf) != 0) {
- msg_info("BLACKLISTED %s", smtp_client_addr.buf);
- if (blist_action == PS_ACT_DROP) {
- smtp_reply(vstream_fileno(smtp_client_stream),
- smtp_client_addr.buf, smtp_client_port.buf,
- "521 5.3.2 Service currently not available\r\n");
- PS_SERVICE_GIVEUP_AND_RETURN(smtp_client_stream);
- }
- }
-
- /*
- * Finally, the temporary whitelist (i.e. the postscreen cache) has the
- * lowest precedence.
- */
- else if (cache_map != 0
- && (stamp_str = ps_dict_get(cache_map, smtp_client_addr.buf)) != 0) {
- stamp_time = strtoul(stamp_str, 0, 10);
- if (stamp_time > event_time() - var_ps_cache_ttl) {
- msg_info("PASS OLD %s", smtp_client_addr.buf);
- state_flags |= PS_FLAG_WHITELISTED;
- } else
- state_flags |= PS_FLAG_EXPIRED;
- }
-
- /*
- * If the client is permanently or temporarily whitelisted, send the
- * socket to the real SMTP service and get out of the way.
- */
- if (state_flags & PS_FLAG_WHITELISTED) {
- state = new_session_state(smtp_client_stream, smtp_client_addr.buf,
- smtp_client_port.buf);
- send_socket(state);
- return;
- }
-
- /*
- * Reply with 421 when we can't analyze more connections.
- */
- if (var_ps_pre_queue_limit > 0
- && check_queue_length - post_queue_length >= var_ps_pre_queue_limit) {
- msg_info("reject: connect from %s:%s: all screening ports busy",
- smtp_client_addr.buf, smtp_client_port.buf);
- smtp_reply(vstream_fileno(smtp_client_stream),
- smtp_client_addr.buf, smtp_client_port.buf,
- "421 4.3.2 All screening ports are busy\r\n");
- PS_SERVICE_GIVEUP_AND_RETURN(smtp_client_stream);
- }
-
- /*
- * If the client has no cached decision, send half the greeting banner,
- * by way of teaser, then wait briefly to see if the client speaks before
- * its turn.
- *
- * Before sending the banner we could set the TCP window to the smallest
- * possible value to save some network bandwidth, at least with spamware
- * that waits until the server starts speaking.
- */
-#if 0
- window_size = 1;
- if (setsockopt(vstream_fileno(smtp_client_stream), SOL_SOCKET, SO_RCVBUF,
- (char *) &window_size, sizeof(window_size)) < 0)
- msg_warn("setsockopt SO_RCVBUF %d: %m", window_size);
-#endif
- if (teaser_greeting != 0
- && smtp_reply(vstream_fileno(smtp_client_stream), smtp_client_addr.buf,
- smtp_client_port.buf, teaser_greeting) != 0)
- PS_SERVICE_GIVEUP_AND_RETURN(smtp_client_stream);
-
- state = new_session_state(smtp_client_stream, smtp_client_addr.buf,
- smtp_client_port.buf);
- state->flags |= state_flags;
- READ_EVENT_REQUEST(vstream_fileno(state->smtp_client_stream),
- smtp_read_event, (char *) state, var_ps_greet_wait);
-
- /*
- * Run a DNS blocklist query while we wait for the client to respond.
- */
- if (*var_ps_dnsbl_sites)
- postscreen_dnsbl_query(smtp_client_addr.buf);
-}
-
-/* postscreen_cache_validator - validate one cache entry */
-
-static int postscreen_cache_validator(const char *client_addr,
- const char *stamp_str,
- char *unused_context)
-{
- time_t stamp_time;
-
- /*
- * This function is called by the cache cleanup pseudo thread.
- *
- * XX Eliminate code duplication and abstract the parser into a separate
- * routine.
- *
- * Don't report a client as "NEW" just because their cache entry expired.
- */
- stamp_time = strtoul(stamp_str, 0, 10);
- return (event_time() < stamp_time + var_ps_cache_ttl + var_ps_cache_ret);
-}
-
-/* pre_jail_init - pre-jail initialization */
-
-static void pre_jail_init(char *unused_name, char **unused_argv)
-{
- VSTRING *redirect;
-
- /*
- * Open read-only maps as before dropping privilege, for consistency with
- * other Postfix daemons.
- */
- if (*var_ps_wlist_nets)
- wlist_nets =
- addr_match_list_init(MATCH_FLAG_NONE, var_ps_wlist_nets);
-
- if (*var_ps_blist_nets)
- blist_nets =
- addr_match_list_init(MATCH_FLAG_NONE, var_ps_blist_nets);
-
- /*
- * Never, ever, get killed by a master signal, as that would corrupt the
- * database when we're in the middle of an update.
- */
- if (setsid() < 0)
- msg_warn("setsid: %m");
-
- /*
- * Security: don't create root-owned files that contain untrusted data.
- * And don't create Postfix-owned files in root-owned directories,
- * either. We want a correct relationship between (file or directory)
- * ownership and (file or directory) content. To open files before going
- * to jail, temporarily drop root privileges.
- */
- SAVE_AND_SET_EUGID(var_owner_uid, var_owner_gid);
- redirect = vstring_alloc(100);
-
- /*
- * Keep state in persistent external map. As a safety measure we sync the
- * database on each update. This hurts on LINUX systems that sync all
- * their dirty disk blocks whenever any application invokes fsync().
- *
- * Start the cache maintenance pseudo thread after dropping privileges.
- */
-#define PS_DICT_OPEN_FLAGS (DICT_FLAG_DUP_REPLACE | DICT_FLAG_SYNC_UPDATE)
-
- if (*var_ps_cache_map)
- cache_map =
- dict_cache_open(data_redirect_map(redirect, var_ps_cache_map),
- O_CREAT | O_RDWR, PS_DICT_OPEN_FLAGS);
-
- /*
- * Clean up and restore privilege.
- */
- vstring_free(redirect);
- RESTORE_SAVED_EUGID();
-}
-
-/* post_jail_init - post-jail initialization */
-
-static void post_jail_init(char *unused_name, char **unused_argv)
-{
- const NAME_CODE actions[] = {
- "drop", PS_ACT_DROP,
- "continue", PS_ACT_CONT,
- 0, -1,
- };
- int cache_flags;
-
- /*
- * This routine runs after the skeleton code has entered the chroot jail.
- * Prevent automatic process suicide after a limited number of client
- * requests. It is OK to terminate after a limited amount of idle time.
- */
- var_use_limit = 0;
-
- /*
- * Other one-time initialization.
- */
- temp = vstring_alloc(10);
- vstring_sprintf(temp, "%s/%s", MAIL_CLASS_PRIVATE, var_smtpd_service);
- smtp_service_name = mystrdup(STR(temp));
- if (*var_ps_greet_banner) {
- vstring_sprintf(temp, "220-%s\r\n", var_ps_greet_banner);
- teaser_greeting = mystrdup(STR(temp));
- }
- dnsbl_sites = argv_split(var_ps_dnsbl_sites, ", \t\r\n");
- dnsbl_cache = htable_create(13);
- reply_addr = vstring_alloc(100);
- reply_domain = vstring_alloc(100);
- if ((blist_action = name_code(actions, NAME_CODE_FLAG_NONE,
- var_ps_blist_action)) < 0)
- msg_fatal("bad %s value: %s", VAR_PS_BLIST_ACTION, var_ps_blist_action);
- if ((dnsbl_action = name_code(actions, NAME_CODE_FLAG_NONE,
- var_ps_dnsbl_action)) < 0)
- msg_fatal("bad %s value: %s", VAR_PS_DNSBL_ACTION, var_ps_dnsbl_action);
- if ((greet_action = name_code(actions, NAME_CODE_FLAG_NONE,
- var_ps_greet_action)) < 0)
- msg_fatal("bad %s value: %s", VAR_PS_GREET_ACTION, var_ps_greet_action);
- if ((hangup_action = name_code(actions, NAME_CODE_FLAG_NONE,
- var_ps_hangup_action)) < 0)
- msg_fatal("bad %s value: %s", VAR_PS_HUP_ACTION, var_ps_hangup_action);
-
- /*
- * Start the cache maintenance pseudo thread last. Early cleanup makes
- * verbose logging more informative (we get positive confirmation that
- * the cleanup thread runs).
- */
- cache_flags = DICT_CACHE_FLAG_STATISTICS;
- if (msg_verbose)
- cache_flags |= DICT_CACHE_FLAG_VERBOSE;
- if (cache_map != 0 && var_ps_cache_scan > 0)
- dict_cache_control(cache_map,
- DICT_CACHE_CTL_FLAGS, cache_flags,
- DICT_CACHE_CTL_INTERVAL, var_ps_cache_scan,
- DICT_CACHE_CTL_VALIDATOR, postscreen_cache_validator,
- DICT_CACHE_CTL_CONTEXT, (char *) 0,
- DICT_CACHE_CTL_END);
-}
-
-MAIL_VERSION_STAMP_DECLARE;
-
-/* main - pass control to the multi-threaded skeleton */
-
-int main(int argc, char **argv)
-{
- static const CONFIG_STR_TABLE str_table[] = {
- VAR_SMTPD_SERVICE, DEF_SMTPD_SERVICE, &var_smtpd_service, 1, 0,
- VAR_PS_CACHE_MAP, DEF_PS_CACHE_MAP, &var_ps_cache_map, 0, 0,
- VAR_SMTPD_BANNER, DEF_SMTPD_BANNER, &var_smtpd_banner, 1, 0,
- VAR_PS_DNSBL_SITES, DEF_PS_DNSBL_SITES, &var_ps_dnsbl_sites, 0, 0,
- VAR_PS_GREET_ACTION, DEF_PS_GREET_ACTION, &var_ps_greet_action, 1, 0,
- VAR_PS_DNSBL_ACTION, DEF_PS_DNSBL_ACTION, &var_ps_dnsbl_action, 1, 0,
- VAR_PS_HUP_ACTION, DEF_PS_HUP_ACTION, &var_ps_hangup_action, 1, 0,
- VAR_PS_WLIST_NETS, DEF_PS_WLIST_NETS, &var_ps_wlist_nets, 0, 0,
- VAR_PS_BLIST_NETS, DEF_PS_BLIST_NETS, &var_ps_blist_nets, 0, 0,
- VAR_PS_GREET_BANNER, DEF_PS_GREET_BANNER, &var_ps_greet_banner, 0, 0,
- VAR_PS_BLIST_ACTION, DEF_PS_BLIST_ACTION, &var_ps_blist_action, 1, 0,
- 0,
- };
- static const CONFIG_INT_TABLE int_table[] = {
- VAR_PROC_LIMIT, DEF_PROC_LIMIT, &var_proc_limit, 1, 0,
- 0,
- };
- static const CONFIG_NINT_TABLE nint_table[] = {
- VAR_PS_POST_QLIMIT, DEF_PS_POST_QLIMIT, &var_ps_post_queue_limit, 1, 0,
- VAR_PS_PRE_QLIMIT, DEF_PS_PRE_QLIMIT, &var_ps_pre_queue_limit, 1, 0,
- 0,
- };
- static const CONFIG_TIME_TABLE time_table[] = {
- VAR_PS_CACHE_TTL, DEF_PS_CACHE_TTL, &var_ps_cache_ttl, 1, 0,
- VAR_PS_GREET_WAIT, DEF_PS_GREET_WAIT, &var_ps_greet_wait, 1, 0,
- VAR_PS_CACHE_RET, DEF_PS_CACHE_RET, &var_ps_cache_ret, 0, 0,
- VAR_PS_CACHE_SCAN, DEF_PS_CACHE_SCAN, &var_ps_cache_scan, 0, 0,
- 0,
- };
-
- /*
- * Fingerprint executables and core dumps.
- */
- MAIL_VERSION_STAMP_ALLOCATE;
-
- event_server_main(argc, argv, postscreen_service,
- MAIL_SERVER_STR_TABLE, str_table,
- MAIL_SERVER_INT_TABLE, int_table,
- MAIL_SERVER_NINT_TABLE, nint_table,
- MAIL_SERVER_TIME_TABLE, time_table,
- MAIL_SERVER_PRE_INIT, pre_jail_init,
- MAIL_SERVER_POST_INIT, post_jail_init,
- MAIL_SERVER_SOLITARY,
- MAIL_SERVER_SLOW_EXIT, postscreen_drain,
- MAIL_SERVER_EXIT, postscreen_dump,
- 0);
-}
}
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
