From: Wietse Venema Date: Wed, 21 Apr 2004 05:00:00 +0000 (-0500) Subject: postfix-2.2-20040421 X-Git-Tag: v2.2.0-RC1~58 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=3e4842d1c6f36ed7a11cb9fc9f8643d8e1695f11;p=thirdparty%2Fpostfix.git postfix-2.2-20040421 --- diff --git a/postfix/AAAREADME b/postfix/AAAREADME index 85420af5b..ef5fe0553 100644 --- a/postfix/AAAREADME +++ b/postfix/AAAREADME @@ -85,9 +85,9 @@ not yet implement, and how well it works with other software. The HISTORY file gives a detailed log of changes to the software. -Point your browser at html/index.html for Postfix documentation, -for manual pages, and for the unavoidable Postfix FAQ. Expect to -see updated versions on-line at http://www.postfix.org/ +Point your browser at html/index.html for Postfix documentation +and for hyperlinked versions of Postfix manual pages. Expect +to see updated versions on-line at http://www.postfix.org/ Point your MANPATH environment variable at the `man' directory (use an absolute path) for UNIX-style on-line manual pages. These pages @@ -109,7 +109,7 @@ Documentation: Example files: - conf/ sample configuration files + conf/ configuration files, run-time scripts examples/ chroot environments, virtual domains Library routines: @@ -134,20 +134,24 @@ Command-line utilities: Postfix daemons: + src/anvil/ Connection count/rate limiter src/bounce/ Bounce or defer mail src/cleanup/ Canonicalize and enqueue mail src/error/ Trivial error mailer + src/lmtp/ LMTP client src/local/ Local delivery src/master/ Postfix resident superserver + src/oqmgr/ Old queue manager src/pickup/ Local pickup src/pipe/ Pipe delivery src/qmgr/ Queue manager + src/qmqpd/ QMQPD server src/showq/ List Postfix queue status - src/spawn/ Run any command from a network socket - src/lmtp/ LMTP client src/smtp/ SMTP client src/smtpd/ SMTP server + src/spawn/ Run non-Postfix server src/trivial-rewrite/ Address rewriting and resolving + src/verify/ address verification service src/virtual/ virtual mailbox-only delivery agent Test programs: @@ -159,9 +163,9 @@ Miscellaneous: auxiliary/ Auxiliary software etc. bin/ Postfix command executables - conf/ Sample configuration files + conf/ Configuration files, run-time scripts include/ Installed include files lib/ Installed object libraries libexec/ Postfix daemon executables mantools/ Manual page utilities - proto/ Manual pages for sample configuration files + proto/ Documentation source diff --git a/postfix/COMPATIBILITY b/postfix/COMPATIBILITY index c8d65fb0f..885f08608 100644 --- a/postfix/COMPATIBILITY +++ b/postfix/COMPATIBILITY @@ -3,23 +3,27 @@ /usr/spool/mail yes (compile time option) /var/mail yes (compile time option) /var/spool/mail yes (compile time option) -8bitmime yes (including 8bit to quoted-printable conversion) +8bit->7bit MIME yes :include: yes (mail to /file and |command is off by default) +address probing yes (optional persistent database) aliases yes (can enable/disable mail to /file or |command) bare newlines yes (but will send CRLF) blacklisting yes (client name/addr; helo hostname; mail from; rcpt to) -content filter yes (see FILTER_README) +content filter yes (before and after queue, internal and external) db tables yes (compile time option) dbm tables yes (compile time option) delivered-to yes (configurable with prepend_delivered_header) dsn not yet (bounces have DSN form) -errors-to: yes +errors-to: yes (disabled by default since Postfix 2.1) esmtp yes etrn support yes (per-destination log for authorized destinations only) fcntl locking yes (runtime configurable) flock locking yes (runtime configurable) +genericstable no (to be done) +greylist yes (delegated policy script) home mailbox yes ident lookup no +ipv6 no (to be done, patches exist) ldap tables yes (contributed) lmtp support yes (client) luser relay yes @@ -43,9 +47,11 @@ pipeline option yes (server and client) pop/imap yes (with third-party daemons that use /var[/spool]/mail) qmqp server yes (with verp support) rbl support yes -return-receipt: not yet +return-receipt: no +rhsbl support yes sasl support yes (compile time option) sendmail -bt no +sendmail -bv yes (sends delivery report via email) sendmail -q yes sendmail -qRxxx yes (for domains specified in fast_flush_domains) sendmail -qSxxx no @@ -54,6 +60,8 @@ sendmail -v yes (sends delivery report via email) sendmail.cf no (uses table-driven address rewriting) size option yes, server and client smarthost yes (specify relayhost in main.cf) +spf yes (delegated policy script) +starttls yes (third party patch) tcp wrapper no (use built-in blacklist facility) user+extension yes (also: .forward+extension) user-extension yes (also: .forward-extension) diff --git a/postfix/HISTORY b/postfix/HISTORY index 4aad6f247..51eddd3b6 100644 --- a/postfix/HISTORY +++ b/postfix/HISTORY @@ -9092,23 +9092,66 @@ Apologies for any names omitted. Misc. documentation fixes by Victor Duchovni. + Documentation: the README files are now hyperlinked, and + are referenced in the on-line manual pages. + + Bugfix: the pickup daemon now strokes the watchdog frequently + to prevent the watchdog from barking when mail arrives + faster than it can be picked up. File: pickup/pickup.c. + +20040123 + + Feature: set smtpd_reject_unlisted_{sender,recipient}=no to + turn off automatic rejection of non-existent local, virtual + or relay addresses. This way it can be made conditional + for local clients, always on for remote clients. Files: + global/mail_params.h, smtpd/smtpd.c, smtpd/smtpd_check.c. + +20040124 + + Feature: PREPEND in header/body_checks, for message tagging. + File: cleanup/cleanup_message.c. + 20040126 - Safety: handle the case that main.cf is updated while it - is being read. File: util/dict.c. + Safety: handle the case that main.cf is updated while it is + being read. File: util/dict.c. + + Feature: "instance" attribute that links policy etc. queries + to the same message instance. + + Cleanup: the mynetworks setting may now be empty. File: + global/mail_params.c. 20040127 Bugfix: missing flush_init() call. Introduced 20040105. File: postqueue/postqueue.c. +20040128 + + Cleanup: clnt_stream derived classes now try to detect that + the server has disconnected before sending data and warning + about an error. File: global/clnt_stream.c. + 20040202 Bugfix: changed mis-leading warning about text>4096 characters into "unexpected end-of-input". File: util/attr_scan0.c. +20040201 + + Feature: sasl_method, sasl_username and sasl_sender attributes + in smtpd policy queries. Files: src/smtpd/smtpd_check.c. + 20040204 + Safety: smtpd_soft_error_limit now determines when + $smtpd_error_sleep_time starts to take effect. + + Cleanup: local(8) and virtual(8) will now create maildirs + in a world-writable directory. Files: util/make_dirs.c. + Bugfix: don't panic on a corrupt queue file. File: *qmgr/qmgr_message.c. @@ -9124,6 +9167,11 @@ Apologies for any names omitted. previous "354 End data with ." response. File: smtpd/smtpd.c. +20040220 + + Compatibility: accept and ignore the sendmail -bh and -bH + mode of operation requests. + 20040302 Bugfix: SMTPD proxy didn't send QUIT as the result of code @@ -9132,19 +9180,202 @@ Apologies for any names omitted. 20040311 - Bugfix: bad address syntax caused map lookup with zero-length - keys. Problem reported by Andrei Koulik. Files: - util/match_ops.c, src/trivial-rewrite/transport.c. + Bugfix: bad address syntax was passed to transport map + lookups. Problem reported by Andrei Koulik. File: + util/match_ops.c, trivial-rewrite/resolve.c. + +20040324 + + Portability: ekkoBSD support by Philip Reynolds. + Files: makedefs, util/sys_defs.h. + +20040325 + + Cleanup: smtp_skip_4xx_greeting and smtp_skip_5xx_greeting + functionality is moved from connection management to SMTP + protocol processing, so that Postfix now logs the server + response when a server refuses to provide service. Files: + smtp/smtp_connect.c, smtp/smtp_proto.c. + + Cleanup: smtp_skip_4xx_greeting is no longer configurable; + it is now permanently turned on. + +20040326 + + Workaround: in the trivial-rewrite server, turn on the code + to strip trailing "." while rewriting addresses, and change + the address resolver to strip trailing "." in a compatible + manner. This does not eliminate the problem that the SMTP + server may use a different address for recipient validation + than what the cleanup server uses for virtual alias mapping. + +20040329 + + Bugfix: the SMTP server did not log client (and SASL) + information with the real-time content filter was enabled. + Files: smtpd/smtpd.c, smtpd/smtpd_sasl_proto.c. + + Compatibility: smtpd_reject_unlisted_sender is turned off + by default, to avoid trouble with with in-house software + that sends out mail software with an unreplyable address. + +20040331 + + Bugfix: postdrop should not abandon mail submission after + receiving a SIGHUP signal when SIGHUP was ignored by the + parent process. Victor Duchovni, Morgan Stanley. File: + postdrop/postdrop.c. + + Bugfix: parsing bug in PgSQL dictionaries causing UNIX + sockets to be ignored. Liviu Daia. Files: global/dict*sql.c. + + Performance: allow MySQL and PgSQL database connections to + be closed when idle for more than 1 minute; Liviu Daia. + Files: global/dict*sql.c. + +20040401 + + Sanity: the SMTP server no longer accepts sender or recipient + addresses that end in the "@" null domain, as well as + addresses that rewrite into such a form. Specify + "resolve_null_domain=yes" to get the old behavior back. + File: trivial-rewrite/resolve.c. + +20040402 + + Cleanup: added WARN action support for access maps, for + consistency with the WARN action in header and body checks. + File: smtpd/smtpd_check.c. + +20040407 + + Bugfix: missing return statement at the end of the + FREE_MEMORY_AND_RETURN error handling macro. Adi Prasaja. + File: trivial-rewrite/resolve.c. + +20040411 + + Future proofing: client_rate_time_unit is renamed to + anvil_rate_time_unit, so that it is no longer limited to + clients only. File: src/global/mail_params.h. + + Cleanup: postalias and postmap now log problems to syslogd. + Files: postalias/postalias.c, postmap/postmap.c. + +20040413 + + Feature: "postfix set-permissions" (re)sets ownership and + access permissions of Postfix files and directories. + + Feature: "postfix upgrade-configuration" updates main.cf + and master.cf. This is for people who people copy over + their old files after installing a newer Postfix version. + + Feature: HTML files are now optionally installed under + control of the html_directory configuration parameter. + Files: postfix-install, conf/postfix-files, conf/post-install. + + Cleanup: README file installation is now optional. Files: + postfix-install, conf/postfix-files, conf/post-install. + +20040414 + + Cleanup: references to sample-mumble.cf files removed, + conf/mumble_table files removed, new commands added to + conf/postfix-script. + + Cleanups: function declared in but used as void, missing + include file, missing const qualifier, unused variable. + Matthias Andree. Files: bounce/bounce_notify_util.c, + bounce/bounce_service.h, postlog/postlog.c, smtpd/smtpd_check.c, + util/attr_scan64.c. + + Bugfix: more robust version of SIGHUP test of 20040331. + Victor Duchovni, Morgan Stanley. File: postdrop/postdrop.c. + + Safety: added NOCLOBBER qualifiers to local variables that + might be clobbered by longjmp(). Files: util/sys_defs.h, + smtp/smtp_proto.c, lmtp/lmtp_proto.c, smtpd/smtpd_check.c, + smtpstone/smtp-source.c. + + Bugfix: sub-level Makefiles no longer turned on the extra + compiler warnings. Files: Makefile.in.*, makedefs.*. + +20040415 + + Bugfix: the LMTP client attempted to reuse a connection + after timeout, causing protocol synchronization errors. + Reported by Rob Mueller. File: lmtp/lmtp.c. + +20040416 + + Cleanup: non-delivery reports now include the original + recipient information. File: bounce/bounce_notify_util.c. + +20040415-18 + + Typos: many documentation fixes by Rob Foehl. + +20040418 + + Cleanup: "int" versus "const int" prototype mismatch between + the DICT sequence method prototype and possible implementations. + Files: util/dict_db.c, util/dict_dbm.c. + +20040419 + + Bugfix: the code that rejects client/helo RESTRICTIONS with + smtpd_delay_reject=no looked at the wrong evidence and + rejected client/helo ACCESS MAP lookups instead. Michael + Tokarev. Files: smtpd/smtpd.c, smtpd/smtpd_check.c. + + Bugfix: missing # in master.cf in optional submission + service. + +20040420 + + Bugfix: smtpd logged the client too often. Michael Tokarev. + File: smtpd/smtpd.c. + + Cleanup: client_event_status_update_time renamed to + anvil_status_update_time. Files: mantools/postlink, + proto/postconf.proto, anvil/anvil.c. + +20040421 + + Workaround: allow pipelined SMTP clients to overshoot the + SMTP server recipient limit without triggering the server + hard error limit. The SMTP server does not count "too many + recipients" towards the hard error limit, as long as the + number of excess recipients stays within a configurable + overshoot limit (default: smtpd_recipient_overshoot_limit + = 1000). Solution in cooperation with Victor Duchovni. + Files: smtpd/smtpd.c, smtpd/smtpd_state.c, smtpd/smtpd.h. Open problems: - Low: log xdelay (esp. for SMTP and delivery to command). + 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. + + Low: add msg_panic() guard to ensure that at least one of + DICT_FLAG_TRY1NULL or DICT_FLAG_TRY1NULL is set upon lookup. - Med: smtpd_reject_unknown_sender=yes to control the egress - filter. + Low: make post-install a "postfix-only script" so it can + take data from the environment instead of main.cf. - Med: cleanup_enable_errors_to=no to control errors-to - processing. + Low: qmgr should truncate trace logfile before attempting + delivery. + + Low: randomize deferred mail backoff. + + Med: separate ulimit for delivery to command? + + Med: option to open queue file early, after MAIL FROM. + + Low: log xdelay (esp. for SMTP and delivery to command). Med: silly queue file bit so that the queue manager doesn't skip files when fast flush is requested while a queue scan diff --git a/postfix/INSTALL b/postfix/INSTALL deleted file mode 100644 index d544ddc50..000000000 --- a/postfix/INSTALL +++ /dev/null @@ -1,546 +0,0 @@ -1 - Purpose of this document -============================ - -This document describes how to build, install and configure a -Postfix system so that it can do one of the following: - - - Send mail only, without changing an existing sendmail - installation. - - - Send and receive mail via a virtual host interface, still - without any change to an existing sendmail installation. - - - Replace sendmail altogether. - -2 - Typographical conventions -============================= - -In the instructions below, a command written as - - # command - -should be executed as the superuser. - -A command written as - - % command - -should be executed as an unprivileged user. - -3 - Documentation -================= - -Documentation is available as HTML web pages (point your browser -to html/index.html) and as UNIX-style man pages (point your MANPATH -environment variable to the `man' subdirectory; be sure to use an -absolute path). - -The sample configuration files in the `conf' directory have extensive -comments, but they may not describe every nuance of every feature. - -Many files have their own built-in manual page. Tools to extract -those embedded manual pages are available in the mantools directory. - -4 - Building on a supported system -================================== - -At some point in time, a version of Postfix was supported on: - - AIX 3.2.5 - AIX 4.1.x - AIX 4.2.0 - AIX 4.3.x - AIX 5.2 - BSD/OS 2.x - BSD/OS 3.x - BSD/OS 4.x - Darwin 1.x - FreeBSD 2.x - FreeBSD 3.x - FreeBSD 4.x - FreeBSD 5.x - HP-UX 9.x - HP-UX 10.x - HP-UX 11.x - IRIX 5.x - IRIX 6.x - Linux Debian 1.3.1 - Linux Debian 2.x - Linux Debian 3.x - Linux RedHat 3.x (Januway 2004, compile-only test) - Linux RedHat 4.x - Linux RedHat 5.x - Linux RedHat 6.x - Linux RedHat 7.x - Linux RedHat 8.x - Linux RedHat 9.x - Linux Slackware 3.x - Linux Slackware 4.x - Linux Slackware 7.x - Linux SuSE 5.x - Linux SuSE 6.x - Linux SuSE 7.x - Mac OS X - NEXTSTEP 3.x - NetBSD 1.x - OPENSTEP 4.x - OSF1.V3 (Digital UNIX) - OSF1.V4 aka Digital UNIX V4 - OSF1.V5 aka Digital UNIX V5 - OpenBSD 2.x - OpenBSD 3.x - Reliant UNIX 5.x - Rhapsody 5.x - SunOS 4.1.4 (January 2004, running as MTA) - SunOS 5.4..5.9 (Solaris 2.4..9) - Ultrix 4.x (well, that was long ago) - -or something closely resemblant. - -On Solaris, the "make" command and other utilities for software -development are in /usr/ccs/bin, so you MUST have /usr/ccs/bin in -your command search path. - -If you need to build Postfix for multiple architectures, use the -lndir command to build a shadow tree with symbolic links to the -source files. lndir is part of X11R6. - -If at any time in the build process you get messages like: "make: -don't know how to ..." you should be able to recover by running -the following command from the Postfix top-level directory: - - % make -f Makefile.init makefiles - -If you copied the Postfix source code after building it on another -machine, it is a good idea to cd into the top-level directory and - - % make tidy - -first. This will get rid of any system dependencies left over from -compiling the software elsewhere. - -To build with GCC, or with the native compiler if people told me -that is better for your system, just cd into the top-level Postfix -directory of the source tree and type: - - % make - -To build with a non-default compiler, you need to specify the name -of the compiler: - - % make makefiles CC=/opt/SUNWspro/bin/cc (Solaris) - % make - - % make makefiles CC="/opt/ansic/bin/cc -Ae" (HP-UX) - % make - - % make makefiles CC="purify cc" - % make - -and so on. In some cases, optimization is turned off automatically. - -In order to build with non-default settings, for example, with a -configuration directory other than /etc/postfix, use: - - % make makefiles CCARGS='-DDEF_CONFIG_DIR=\"/some/where\"' - % make - -Be sure to get the quotes right. These details matter a lot. - -Parameters whose defaults can be specified in this way are: - - Macro name default value for typical default - ----------------------------------------------------------- - DEF_COMMAND_DIR command_directory /usr/sbin - DEF_CONFIG_DIR config_directory /etc/postfix - DEF_DAEMON_DIR daemon_directory /usr/libexec/postfix - DEF_MAILQ_PATH mailq_path /usr/bin/mailq - DEF_MANPAGE_DIR manpage_directory /usr/local/man - DEF_NEWALIAS_PATH newaliases_path /usr/bin/newaliases - DEF_README_DIR readme_directory no (do not install) - DEF_SAMPLE_DIR sample_directory /etc/postfix - DEF_SENDMAIL_PATH sendmail_path /usr/sbin/sendmail - -In order to build Postfix for very large applications, where you -expect to run more than 1000 delivery processes, you may need to -override the definition of the FD_SETSIZE macro to make select() -work correctly: - - % make makefiles CCARGS=-DFD_SETSIZE=2048 - -In any case, if the command - - % make - -produces compiler error messages, it may be time to examine the -FAQ document (see html/faq.html). - -5 - Porting to on an unsupported system -======================================= - -- Each system type is identified by a unique name. Examples: -SUNOS5, FREEBSD4, and so on. Choose a SYSTEMTYPE name for the new -system. You must use a name that includes at least the major version -of the operating system (such as SUNOS4 or LINUX2), so that different -releases of the same system can be supported without confusion. - -- Add a case statement to the "makedefs" shell script in the -top-level directory that recognizes the new system reliably, and -that emits the right system-specific information. Be sure to make -the code robust against user PATH settings; if the system offers -multiple UNIX flavors (e.g. BSD and SYSV) be sure to build for the -native flavor, not the emulated one. - -- Add an #ifdef SYSTEMTYPE section to the central util/sys_defs.h -include file. You may have to invent new feature macros. Please -choose sensible feature macro names such as HAS_DBM or -FIONREAD_IN_SYS_FILIO_H. I strongly recommend against #ifdef -SYSTEMTYPE dependencies in individual source files. This may seem -to be the quickest solution, but it will create a mess that becomes -increasingly difficult to maintain over time. Moreover, with the -next port you'd have to place #ifdefs all over the source code -again. - -6 - Installing the software after successful compilation -======================================================== - -This text describes how to install Postfix from source code. See -the PACKAGE_README file if you are building a package for distribution -to other systems. - -IMPORTANT: if you are REPLACING an existing sendmail installation -with Postfix, you may need to keep the old sendmail program running -for some time in order to flush the mail queue. As superuser, -execute the following commands (your sendmail, newaliases and mailq -programs may be in a different place): - - # mv /usr/sbin/sendmail /usr/sbin/sendmail.OFF - # mv /usr/bin/newaliases /usr/bin/newaliases.OFF - # mv /usr/bin/mailq /usr/bin/mailq.OFF - # chmod 755 /usr/sbin/sendmail.OFF /usr/bin/newaliases.OFF \ - /usr/bin/mailq.OFF - -In order to install or upgrade Postfix: - -- Create a user account "postfix" with a user id and group id that - are not used by any other user account. Preferably, this is an - account that no-one can log into. The account does not need an - executable login shell, and needs no existing home directory. - My password file entry looks like this: - - postfix:*:12345:12345:postfix:/no/where:/no/shell - - Note: there should be no whitespace before "postfix:". - -- Make sure there is a corresponding alias in /etc/aliases: - - postfix: root - - Note: there should be no whitespace before "postfix:". - -- Create a group "postdrop" with a group id that is not used by - any other user account. Not even by the postfix user account. - My group file entry looks like: - - postdrop:*:54321: - - Note: there should be no whitespace before "postdrop:". - -- Optional: If you want to install symbol-stripped (non-debug) versions - of the Postfix programs and daemons, do: - - % strip bin/* libexec/* - -- Run one of the following commands as the super-user: - - # make install (interactive version, first time install) - # make upgrade (non-interactive version, for upgrades) - - The non-interactive version needs the /etc/postfix/main.cf file - from a previous installation. If the file does not exist, use - interactive installation instead. - - The interactive version offers suggestions for pathnames that - you can override interactively, and stores your preferences in - /etc/postfix/main.cf for convenient future upgrades. - -- Proceed to the section on how you wish to run Postfix on your - particular machine: - - - Send mail only, without changing an existing sendmail - installation (section 7). - - - Send and receive mail via a virtual host interface, still - without any change to an existing sendmail installation - (section 8). - - - Replace sendmail altogether (section 9). - -7 - Configuring Postfix to send mail only -========================================= - -If you are going to use Postfix to send mail only, there is no need -to change your existing sendmail setup. Instead, set up your mail -user agent so that it calls the Postfix sendmail program directly. - -Follow the instructions in the "Mandatory configuration file edits" -in section 10, and review the "To chroot or not to chroot" text in -section 11. - -You MUST comment out the `smtp inet' entry in /etc/postfix/master.cf, -in order to avoid conflicts with the real sendmail. - -Start the Postfix system: - - # postfix start - -or, if you feel nostalgic, use the Postfix sendmail command: - - # sendmail -bd -qwhatever - -and watch your syslog file for any error messages. - - % egrep '(reject|warning|error|fatal|panic):' /some/log/file - -Typical logfile names are: /var/log/maillog or /var/log/syslog. -See /etc/syslog.conf for actual logfile names. - -In order to inspect the mail queue, use - - % sendmail -bp - -See also the "Care and feeding" section 12 below. - -8 - Configuring Postfix to send and receive mail (virtual interface) -==================================================================== - -Alternatively, you can use the Postfix system to send AND receive -mail while leaving your sendmail setup intact, by running Postfix -on a virtual interface address. Simply configure your mail user -agent to directly invoke the Postfix sendmail program. - -The examples/virtual-setup directory gives instructions for setting -up virtual interfaces for a variety of UNIX versions. - -In the /etc/postfix/main.cf file, I would specify - - myhostname = virtual.host.tld - inet_interfaces = $myhostname - mydestination = $myhostname - -Follow the instructions in the "Mandatory configuration file edits" -in section 10, and review the "To chroot or not to chroot" text in -section 11. - -Start the mail system: - - # postfix start - -or, if you feel nostalgic, use the Postfix sendmail program: - - # sendmail -bd -qwhatever - -and watch your syslog file for any error messages. - - % egrep '(reject|warning|error|fatal|panic):' /some/log/file - -Typical logfile names are: /var/log/maillog or /var/log/syslog. -See /etc/syslog.conf for actual logfile names. - -In order to inspect the mail queue, use - - % sendmail -bp - -See also the "Care and feeding" section 12 below. - -9 - Turning off sendmail forever -================================ - -Prior to installing Postfix you should save the existing sendmail -program files as described in section 6. - -Be sure to keep the old sendmail running for at least a couple -days to flush any unsent mail. To do so, stop the sendmail daemon -and restart it as: - - # /usr/sbin/sendmail.OFF -q - -After you have visited the "Mandatory configuration file edits" -section below, you can start the Postfix system with - - # postfix start - -But the good old sendmail way works just as well: - - # sendmail -bd -qwhatever - -and watch the syslog file for any complaints from the mail system. - - % egrep '(reject|warning|error|fatal|panic):' /some/log/file - -Typical logfile names are: /var/log/maillog or /var/log/syslog. -See /etc/syslog.conf for actual logfile names. - -See also the "Care and feeding" section 12 below. - -10 - Mandatory configuration file edits -======================================= - -By default, Postfix configuration files are in /etc/postfix, and -must be owned by root. Giving someone else write permission to -main.cf or master.cf means giving root privileges to that person. - -Whenever you make a change to a config file, execute the following -command in order to refresh a running mail system: - - # postfix reload - -In /etc/postfix/main.cf you will have to set up a minimal number of -configuration parameters. Postfix configuration parameters -resemble shell variables. You specify a variable as - - parameter = value - -and you use it by putting a $ in front of its name: - - other_parameter = $parameter - -You can use $parameter before it is given a value. The Postfix -configuration language uses lazy evaluation, and does not look at -a parameter value until it is needed at runtime. - -First of all, you must specify what domain will be appended to an -unqualified address (i.e. an address without @domain.tld). The -"myorigin" parameter defaults to the local hostname, but that is -probably OK only for very small sites. - -Some examples: - - myorigin = $myhostname - myorigin = $mydomain - -In the first case, local mail goes out as user@$myhostname, in -the second case the sender address is user@$mydomain. - -Next you need to specify what mail addresses Postfix should deliver -locally. - -Some examples: - - mydestination = $myhostname, localhost.$mydomain - mydestination = $myhostname, localhost.$mydomain, $mydomain - mydestination = $myhostname - -The first example is appropriate for a workstation, the second is -appropriate for the mailserver for an entire domain. The third -example should be used when running on a virtual host interface. - -If your machine is on an open network then you must specify what -client IP addresses are authorized to relay their mail through your -machine. The default setting includes all class A, B or C networks -that the machine is attached to. Often, that gives relay permission -to too many clients. My own settings are: - - mynetworks = 168.100.189.0/28, 127.0.0.0/8 - -If you're behind a firewall, you should set up a relayhost. If -you can, specify the organizational domain name so that Postfix -can use DNS lookups, and so that it can fall back to a secondary -MX host when the primary MX host is down. Otherwise just specify -a hard-coded hostname. - -Some examples: - - relayhost = $mydomain - relayhost = mail.$mydomain - relayhost = [mail.$mydomain] - -The form enclosed with [] eliminates DNS MX lookups. - -By default, the SMTP client will do DNS lookups for sender and -recipient addresses even when you specify a relay host. If your -machine has no access to a DNS server, turn off SMTP client DNS -lookups like this: - - disable_dns_lookups = yes - -The FAQ (html/faq.html) has more hints and tips for firewalled -and/or dial-up networks. - -Finally, if you haven't used Sendmail prior to using Postfix, you -will have to build the alias database (with: sendmail -bi, or: -newaliases). Be sure to set up aliases for root and postmaster that -forward mail to a real person. Postfix has a sample aliases file -conf/aliases that you can adapt to local conditions. - -11 - To chroot or not to chroot -=============================== - -Postfix can run most daemon processes in a chroot jail, that is, -the processes run at a fixed low privilege and with access only to -the Postfix queue directories (/var/spool/postfix). This provides -a significant barrier against intrusion. The barrier is not -impenetrable, but every little bit helps. - -With the exception of the Postfix daemons that deliver mail locally, -every Postfix daemon can run chrooted. - -Sites with high security requirements should consider to chroot -all daemons that talk to the network: the smtp and smtpd processes, -and perhaps also the lmtp client. - -The default /etc/postfix/master.cf file specifies that no Postfix -daemon runs chrooted. In order to enable chroot operation, edit -the file /etc/postfix/master.cf. Instructions are in the file. - -Note that a chrooted daemon resolves all filenames relative to the -Postfix queue directory (/var/spool/postfix). For successful use -of a chroot jail, most UNIX systems require you to bring in some -files or device nodes. The examples/chroot-setup directory has a -collection of scripts that help you set up chroot environments for -Postfix systems. - -IMPORTANT: if you enable chrooted operation of the SMTP server you -must copy the passwd file into the chroot jail, otherwise the SMTP -server will reject mail for local addresses. - -44BSD systems: - - # mkdir /var/spool/postfix/etc - # cp /etc/pwd.db /var/spool/postfix/etc - -Other systems: - - # mkdir /var/spool/postfix/etc - # cp /etc/passwd /var/spool/postfix/etc - -You may also have to copy /etc/nsswitch.conf and the files referenced -by /etc/nsswitch.conf. See the system dependent scripts in -examples/chroot-setup for suggestions. - -12 - Care and feeding of the Postfix system -=========================================== - -The Postfix programs log all problems to the syslog daemon. The -names of logfiles are specified in /etc/syslog.conf. Note: the -syslogd will not create files. You must create them ahead of time -before (re)starting syslogd. At the very least you need something -like: - - mail.err /dev/console - mail.debug /var/log/maillog - -Hopefully, the number of problems will be small, but it is a good -idea to run every night before the syslog files are rotated: - - # postfix check - # egrep '(reject|warning|error|fatal|panic):' /some/log/file - -Typical logfile names are: /var/log/maillog or /var/log/syslog. -See /etc/syslog.conf for actual logfile names. - -The first line (postfix check) causes Postfix to report file -permission/ownership discrepancies. - -The second line looks for problem reports from the mail software, -and reports how effective the anti-relay and anti-UCE blocks are. diff --git a/postfix/INSTALL b/postfix/INSTALL new file mode 120000 index 000000000..362cf2a57 --- /dev/null +++ b/postfix/INSTALL @@ -0,0 +1 @@ +README_FILES/INSTALL \ No newline at end of file diff --git a/postfix/Makefile.in b/postfix/Makefile.in index fe366ac92..53aa735bc 100644 --- a/postfix/Makefile.in +++ b/postfix/Makefile.in @@ -1,6 +1,6 @@ SHELL = /bin/sh WARN = -Wmissing-prototypes -Wformat -OPTS = 'CC=$(CC) -DSNAPSHOT' +OPTS = 'CC=$(CC)' DIRS = src/util src/global src/dns src/master src/postfix src/smtpstone \ src/sendmail src/error src/pickup src/cleanup src/smtpd src/local \ src/lmtp src/trivial-rewrite src/qmgr src/oqmgr src/smtp src/bounce \ @@ -15,7 +15,7 @@ default: update makefiles Makefiles: set -e; for i in $(DIRS); do \ (set -e; echo "[$$i]"; cd $$i; rm -f Makefile; \ - $(MAKE) $(OPTS) -f Makefile.in Makefile MAKELEVEL=) || exit 1; \ + $(MAKE) -f Makefile.in Makefile MAKELEVEL=) || exit 1; \ done; rm -f Makefile; (set -e; $(SHELL) makedefs && cat Makefile.in) >Makefile (echo "# Do not edit -- this file documents how Postfix was built for your machine."; $(SHELL) makedefs) >makedefs.tmp diff --git a/postfix/Makefile.in.shapshot b/postfix/Makefile.in.snapshot similarity index 96% rename from postfix/Makefile.in.shapshot rename to postfix/Makefile.in.snapshot index fe366ac92..53aa735bc 100644 --- a/postfix/Makefile.in.shapshot +++ b/postfix/Makefile.in.snapshot @@ -1,6 +1,6 @@ SHELL = /bin/sh WARN = -Wmissing-prototypes -Wformat -OPTS = 'CC=$(CC) -DSNAPSHOT' +OPTS = 'CC=$(CC)' DIRS = src/util src/global src/dns src/master src/postfix src/smtpstone \ src/sendmail src/error src/pickup src/cleanup src/smtpd src/local \ src/lmtp src/trivial-rewrite src/qmgr src/oqmgr src/smtp src/bounce \ @@ -15,7 +15,7 @@ default: update makefiles Makefiles: set -e; for i in $(DIRS); do \ (set -e; echo "[$$i]"; cd $$i; rm -f Makefile; \ - $(MAKE) $(OPTS) -f Makefile.in Makefile MAKELEVEL=) || exit 1; \ + $(MAKE) -f Makefile.in Makefile MAKELEVEL=) || exit 1; \ done; rm -f Makefile; (set -e; $(SHELL) makedefs && cat Makefile.in) >Makefile (echo "# Do not edit -- this file documents how Postfix was built for your machine."; $(SHELL) makedefs) >makedefs.tmp diff --git a/postfix/Makefile.in.stable b/postfix/Makefile.in.stable index 981909ac9..ac70d7ad6 100644 --- a/postfix/Makefile.in.stable +++ b/postfix/Makefile.in.stable @@ -15,7 +15,7 @@ default: update makefiles Makefiles: set -e; for i in $(DIRS); do \ (set -e; echo "[$$i]"; cd $$i; rm -f Makefile; \ - $(MAKE) $(OPTS) -f Makefile.in Makefile MAKELEVEL=) || exit 1; \ + $(MAKE) -f Makefile.in Makefile MAKELEVEL=) || exit 1; \ done; rm -f Makefile; (set -e; $(SHELL) makedefs && cat Makefile.in) >Makefile (echo "# Do not edit -- this file documents how Postfix was built for your machine."; $(SHELL) makedefs) >makedefs.tmp diff --git a/postfix/PORTING b/postfix/PORTING index 672eff62e..7a2d50301 100644 --- a/postfix/PORTING +++ b/postfix/PORTING @@ -1,25 +1,24 @@ In order to port software to a new platform: -- Each system type needs to be identified by a unique name. Examples: -SUNOS5, FREEBSD4, and so on. Choose a SYSTEMTYPE name for the new -system. You must use a name that includes at least the major version -of the operating system (such as SUNOS4 or LINUX2), so that different -releases of the same system can be supported without confusion. +- Choose a SYSTEMTYPE name for the new system. You must use a name +that includes at least the major version of the operating system +(such as SUNOS4 or LINUX2), so that different releases of the same +system can be supported without confusion. -- Add a case statement to the "makedefs" shell script in the -top-level directory that recognizes the new system reliably, and -that emits the right system-specific information. Be sure to make -the code robust against user PATH settings; if the system offers -multiple UNIX flavors (e.g. BSD and SYSV) be sure to build for the -native flavor, not the emulated one. +- Add a case statement to the "makedefs" shell script in the source +code top-level directory that recognizes the new system reliably, +and that emits the right system-specific information. Be sure to +make the code robust against user PATH settings; if the system +offers multiple UNIX flavors (e.g. BSD and SYSV) be sure to build +for the native flavor, instead of the emulated one. -- Add an #ifdef SYSTEMTYPE section to the central util/sys_defs.h -include file. You may have to invent new feature macros. Please -choose sensible feature macro names such as HAS_DBM or -FIONREAD_IN_SYS_FILIO_H. +- Add an "#ifdef SYSTEMTYPE" section to the central util/sys_defs.h +include file. You may have to invent new feature macro names. +Please choose sensible feature macro names such as HAS_DBM or +FIONREAD_IN_SYS_FILIO_H. -I strongly object to #ifdef SYSTEMTYPE dependencies in individual -source files. This may seem to be the quickest solution, but it -will create a mess that becomes increasingly difficult to maintain -over time. Moreover, with the next port to another system you'd -have to place #ifdefs all over the source code again. +I strongly recommend against using "#ifdef SYSTEMTYPE" in individual +source files. While this may look like the quickest solution, it +will create a mess when newer versions of the same SYSTEMTYPE need +to be supported. You're likely to end up placing "#ifdef" sections +all over the source code again. diff --git a/postfix/README_FILES/AAAREADME b/postfix/README_FILES/AAAREADME new file mode 100644 index 000000000..19cc9a485 --- /dev/null +++ b/postfix/README_FILES/AAAREADME @@ -0,0 +1,76 @@ + PPoossttffiixx DDooccuummeennttaattiioonn + +------------------------------------------------------------------------------- +GGeenneerraall ccoonnffiigguurraattiioonn + + * BASIC_CONFIGURATION_README: Basic configuration + * STANDARD_CONFIGURATION_README: Standard configuration examples + * ADDRESS_REWRITING_README: Address rewriting + * VIRTUAL_README: Virtual domain hosting + * SASL_README: SASL Authentication + * INSTALL: Installation from source code + +PPrroobblleemm ssoollvviinngg + + * QSHAPE_README: Bottleneck analysis + * TUNING_README: Performance tuning + * DEBUG_README: Debugging strategies + * Error messages (*) + +CCoonntteenntt iinnssppeeccttiioonn + + * CONTENT_INSPECTION_README: Content inspection overview + * BACKSCATTER_README: Stopping backscatter mail + * BUILTIN_FILTER_README: Built-in content inspection + * FILTER_README: After-queue content filter + * SMTPD_PROXY_README: Before-queue content Filter + +SSMMTTPP RReellaayy aanndd aacccceessss ccoonnttrrooll + + * SMTPD_ACCESS_README: Relay/access control overview + * SMTPD_POLICY_README: Access policy delegation + * ADDRESS_VERIFICATION_README: Address verification + * RESTRICTION_CLASS_README: Per-client/user/etc. access + * ETRN_README: ETRN Support + * UUCP_README: LAN connected via UUCP + +LLooookkuupp ttaabblleess ((ddaattaabbaasseess)) + + * DATABASE_README: Lookup table overview + * DB_README: Berkeley DB Howto + * LDAP_README: LDAP Howto + * MYSQL_README: MySQL Howto + * PCRE_README: PCRE Howto + * PGSQL_README: PostgreSQL Howto + +MMaaiilliinngg lliisstt ssuuppppoorrtt + + * qmail/ezmlm support (*) + * VERP_README: VERP Support + +SSppeecciiffiicc eennvviirroonnmmeennttss + + * LINUX_README: Linux issues + * NFS_README: NFS issues + * ULTRIX_README: Ultrix support + +OOtthheerr mmaaiill ddeelliivveerryy aaggeennttss + + * Cyrus (*) + * MAILDROP_README: Maildrop + * LMTP (*) + +OOtthheerr ttooppiiccss + + * OVERVIEW: Architecture overview + * postconf(5): All main.cf parameters + * LOCAL_RECIPIENT_README: Rejecting Unknown Local Recipients + * ADDRESS_CLASS_README: Address Classes + * PACKAGE_README: Guidelines for Package Builders + * SCHEDULER_README: Queue Scheduler + * XCLIENT_README: XCLIENT Command + * XFORWARD_README: XFORWARD Command + +(*) These documents will be made available via http://www.postfix.org/ and +mirror sites. + diff --git a/postfix/README_FILES/ADDRESS_CLASS_README b/postfix/README_FILES/ADDRESS_CLASS_README index 65f02feb5..9a8b9075c 100644 --- a/postfix/README_FILES/ADDRESS_CLASS_README +++ b/postfix/README_FILES/ADDRESS_CLASS_README @@ -1,99 +1,199 @@ -Introduction -============ - -Postfix version 2.0 introduces the concept of address classes. -This is a way of grouping recipient addresses by their delivery -method. The idea comes from discussions with Victor Duchovni. - -Benefits of address classes are: - -- You no longer need to specify all the virtual(8) mailbox domains - in the Postfix transport map. The virtual(8) delivery agent has - become a first-class citizen just like local(8) or smtp(8). - -- On mail gateway systems, separation of inbound mail relay traffic - from outbound traffic. This eliminates a problem where inbound - mail deliveries could become resource starved in the presence of - a high volume of outbound mail. - -- The SMTP server rejects unknown recipients in a more consistent - manner than was possible with previous Postfix versions. - -The list with "bad news" is at the end of this file :-) - -What address classes does Postfix implement? -============================================ - -Initially the list of address classes is hard coded, but this is -meant to become extensible: - -------------------------------------------------------------------- -Class Description -------------------------------------------------------------------- -local For UNIX accounts and for traditional /etc/aliases - Domain names are listed in $mydestination (or match the IP - address listed with $inet_interfaces or $proxy_interfaces) - Known recipients are listed in $local_recipient_maps (this - information is currently used by the Postfix SMTP server - only; if $local_recipient_maps is empty, the Postfix - SMTP server accepts all recipients) - Default delivery agent: local - -virtual For hosted domains that are aliased to mailboxes in other -alias domains - Known recipients are listed in $virtual_alias_maps (default - is $virtual_maps for Postfix 1.1 compatibility) - Domain names are listed in $virtual_alias_domains (default - is $virtual_alias_maps for Postfix 1.1 compatibility) - -virtual For hosted domains with their own mailboxes -mailbox Known recipients are listed in $virtual_mailbox_maps (if - this parameter is empty, the Postfix SMTP server accepts - all recipients for domains listed in $virtual_mailbox_domains) - Domain names are listed in $virtual_mailbox_domains (default - is $virtual_mailbox_maps for Postfix 1.1 compatibility) - Default delivery agent: virtual - -relay For remote destinations that list your system as MX host - Domain names are listed in $relay_domains - Known recipients are listed in $relay_recipient_maps (if - this parameter is empty, the Postfix SMTP server accepts - all recipients for domains listed in $relay_domains) - Default delivery agent: relay (clone of default smtp agent) - -other Restricted to mail from authorized clients - Default delivery agent: smtp - No domain table - No recipient table -------------------------------------------------------------------- - -Incompatibilities with Postfix 1.1 -================================== - -- virtual_maps is replaced by virtual_alias_maps (for address - lookups) and virtual_alias_domains (for the names of what were - formerly called "Postfix-style virtual domains"). - - For backwards compatibility with Postfix version 1.1, the new - virtual_alias_maps parameter defaults to $virtual_maps, and the - new virtual_alias_domains parameter defaults to $virtual_alias_maps. - -- virtual_mailbox_maps now has a companion parameter called - virtual_mailbox_domains (for the names of domains served by the - virtual delivery agent). virtual_mailbox_maps is now used for - address lookups only. - - For backwards compatibility with Postfix version 1.1,, the new - virtual_mailbox_domains parameter defaults to $virtual_mailbox_maps. - -- Introduction of relay_recipient_maps, so that the Postfix SMTP - server can block mail for relay recipients that don't exist. This - list is empty by default. - -- The local_recipient_maps feature is now turned on by default, so - that the Postfix SMTP server rejects mail for unknown local - recipients. See the LOCAL_RECIPIENT_README file hints and tips. - -- Introduction of relay delivery transport in master.cf. This helps - to avoid mail delivery scheduling problems on inbound mail relays, - but may require that you update your "defer_transports" setting. +PPoossttffiixx AAddddrreessss CCllaasssseess + +------------------------------------------------------------------------------- + +IInnttrroodduuccttiioonn + +Postfix version 2.0 introduces the concept of address classes. This is a way of +grouping recipient addresses by their delivery method. The idea comes from +discussions with Victor Duchovni. Although address classes introduced a few +incompatibilities they also made it possible to improve the handling of hosted +domains and of unknown recipients. + +This document provides information on the following topics: + + * What are address classes good for? + * What address classes does Postfix implement? + * Improvements compared to Postfix 1.1 + * Incompatibilities with Postfix 1.1 + +WWhhaatt aarree aaddddrreessss ccllaasssseess ggoooodd ffoorr?? + +Why should you care about address classes? This is how Postfix decides what +mail to accept, and how to deliver it. In other words, address classes are very +important for the operation of Postfix. + +An address class is defined by three items. + + * The list of domains that are a member of the class: for example, all local + domains, or all relay domains. + + * The default delivery method. For example, the local or smtp delivery agent. + This helps to keep Postfix configurations simple. + + * The list of valid recipient addresses for that address class. The Postfix + SMTP server rejects invalid recipients with "User unknown in table". This helps to keep the Postfix queue free of + undeliverable MAILER-DAEMON messages. + +WWhhaatt aaddddrreessss ccllaasssseess ddooeess PPoossttffiixx iimmpplleemmeenntt?? + +Initially the list of address classes is hard coded, but this is meant to +become extensible. The summary below describes the main purpose of each class, +and what the relevant configuration parameters are. + +The local domain class. + + * Purpose: final delivery for traditional UNIX system accounts and + traditional Sendmail-style aliases. This is typically used for the + canonical domains of the machine. For a discussion of the difference + between canonical domains, hosted domains and other domains, see the + VIRTUAL_README file. + + * Domain names are listed with the mydestination parameter. This domain class + also includes mail for user@[ipaddress] when the IP address is listed with + the inet_interfaces or proxy_interfaces parameters. + + * Valid recipient addresses are listed with the local_recipient_maps + parameter, as described in LOCAL_RECIPIENT_README. The Postfix SMTP server + rejects invalid recipients with "User unknown in local recipient table". If + the local_recipient_maps parameter value is empty, then the Postfix SMTP + server accepts any address in the local domain class. + + * The mail delivery transport is specified with the local_transport + parameter. The default value is llooccaall::$$mmyyhhoossttnnaammee for delivery with the + local(8) delivery agent. + +The virtual alias domain class. + + * Purpose: hosted domains where each recipient address is aliased to a local + UNIX system account or to a remote address. A virtual alias example is + given in the VIRTUAL_README file. + + * Domain names are listed in virtual_alias_domains. The default value is + $virtual_alias_maps for Postfix 1.1 compatibility. + + * Valid recipient addresses are listed with the virtual_alias_maps parameter. + The Postfix SMTP server rejects invalid recipients with "User unknown in + virtual alias table". The default value is $virtual_maps for Postfix 1.1 + compatibility. + + * There is no mail delivery transport parameter. Every address must be + aliased to some other address. + +The virtual mailbox domain class. + + * Purpose: final delivery for hosted domains where each recipient address can + have its own mailbox, and where users do not need to have a UNIX system + account. A virtual mailbox example is given in the VIRTUAL_README file. + + * Domain names are listed with the virtual_mailbox_domains parameter. The + default value is $virtual_mailbox_maps for Postfix 1.1 compatibility. + + * Valid recipient addresses are listed with the virtual_mailbox_maps + parameter. The Postfix SMTP server rejects invalid recipients with "User + unknown in virtual mailbox table". If this parameter value is empty, the + Postfix SMTP server accepts all recipients for domains listed in + $virtual_mailbox_domains. + + * The mail delivery transport is specified with the virtual_transport + parameter. The default value is vviirrttuuaall for delivery with the virtual(8) + delivery agent. + +The relay domain class. + + * Purpose: mail forwarding to remote destinations that list your system as + primary or backup MX host. For a discussion of the basic configuration + details, see the BASIC_CONFIGURATION_README document. For a discussion of + the difference between canonical domains, hosted domains and other domains, + see the VIRTUAL_README file. + + * Domain names are listed with the relay_domains parameter. + + * Valid recipient addresses are listed with the relay_recipient_maps + parameter. The Postfix SMTP server rejects invalid recipients with "User + unknown in relay recipient table". If this parameter value is empty, the + Postfix SMTP server accepts all recipients for domains listed with the + relay_domains parameter. + + * The mail delivery transport is specified with the relay_transport + parameter. The default value is rreellaayy which is a clone of the smtp(8) + delivery agent. + +The default domain class. + + * Purpose: mail forwarding to the Internet on behalf of authorized clients. + For a discussion of the basic configuration details, see the + BASIC_CONFIGURATION_README file. For a discussion of the difference between + canonical domains, hosted domains and other domains, see the VIRTUAL_README + file. + + * This class has no destination domain table. + + * This class has no valid recipient address table. + + * The mail delivery transport is specified with the default_transport + parameter. The default value is ssmmttpp for delivery with the smtp(8) delivery + agent. + +IImmpprroovveemmeennttss ccoommppaarreedd ttoo PPoossttffiixx 11..11 + +Postfix 2.0 address classes made the following improvements possible over +earlier Postfix versions: + + * You no longer need to specify all the virtual(8) mailbox domains in the + Postfix transport map. The virtual(8) delivery agent has become a first- + class citizen just like local(8) or smtp(8). + + * On mail gateway systems, address classes provide separation of inbound mail + relay traffic ($relay_transport) from outbound traffic + ($default_transport). This eliminates a problem where inbound mail + deliveries could become resource starved in the presence of a high volume + of outbound mail. + + * The SMTP server rejects unknown recipients in a more consistent manner than + was possible with Postfix version 1. This is needed to keep undeliverable + mail (and bounced undeliverable mail) out of the mail queue. This is + controlled by the smtpd_reject_unlisted_recipient configuration parameter. + + * As of Postfix version 2.1, the SMTP server also rejects unknown sender + addresses (i.e. addresses that it would reject as unknown recipient + addresses). Sender "egress filtering" can help to slow down an email worm + explosion. This is controlled by the smtpd_reject_unlisted_sender + configuration parameter. + +IInnccoommppaattiibbiilliittiieess wwiitthh PPoossttffiixx 11..11 + +Postfix 2.0 address classes introduce a few incompatible changes in documented +behavior. In order to ease the transitions, new parameters have default values +that are backwards compatible. + + * The virtual_maps parameter is replaced by virtual_alias_maps (for address + lookups) and by virtual_alias_domains (for the names of what were formerly + called "Postfix-style virtual domains"). + + For backwards compatibility with Postfix version 1.1, the new + virtual_alias_maps parameter defaults to $virtual_maps, and the new + virtual_alias_domains parameter defaults to $virtual_alias_maps. + + * The virtual_mailbox_maps parameter now has a companion parameter called + virtual_mailbox_domains (for the names of domains served by the virtual + delivery agent). The virtual_mailbox_maps parameter is now used for address + lookups only. + + For backwards compatibility with Postfix version 1.1, the new + virtual_mailbox_domains parameter defaults to $virtual_mailbox_maps. + + * Introduction of the relay_recipient_maps parameter. The Postfix SMTP server + can use this to block mail for relay recipients that don't exist. This list + is empty by default, which means accept any recipient. + + * The local_recipient_maps feature is now turned on by default. The Postfix + SMTP server uses this to reject mail for unknown local recipients. See the + LOCAL_RECIPIENT_README file hints and tips. + + * Introduction of the relay delivery transport in master.cf. This helps to + avoid mail delivery scheduling problems on inbound mail relays when there + is a lot of outbound mail, but may require that you update your + "defer_transports" setting. + diff --git a/postfix/README_FILES/ADDRESS_REWRITING_README b/postfix/README_FILES/ADDRESS_REWRITING_README new file mode 100644 index 000000000..54e4f4549 --- /dev/null +++ b/postfix/README_FILES/ADDRESS_REWRITING_README @@ -0,0 +1,698 @@ +PPoossttffiixx AAddddrreessss RReewwrriittiinngg + +------------------------------------------------------------------------------- + +PPoossttffiixx aaddddrreessss rreewwrriittiinngg ppuurrppoossee + +Address rewriting is at the heart of the Postfix mail system. Postfix rewrites +addresses for many different purposes. Some are merely cosmetic, and some are +necessary to deliver correctly formatted mail to the correct destination. +Examples of address rewriting in Postfix are: + + * Transform an incomplete address into a complete address. For example, + transform "username" into "username@example.com", or transform + "username@hostname" into "username@hostname.example.com". + + * Replace an address by an equivalent address. For example, replace + "username@example.com" by "firstname.lastname@example.com" when sending + mail, and do the reverse transformation when receiving mail. + + * Replace an address by multiple addresses. For example, replace the address + of an alias by the addresses listed under that alias. + + * Determine how and where to deliver mail for a specific address. For + example, deliver mail for "username@example.com" with the smtp(8) delivery + agent, to the hosts that are listed in the DNS as the mail servers for the + domain "example.com". + +Although Postfix currently has no address rewriting language, it can do +surprisingly powerful address manipulation via table lookup. Postfix typically +uses lookup tables with fixed strings to map one address to one or multiple +addresses, and typically uses regular expressions to map multiple addresses to +one or multiple addresses. Fixed-string lookup tables may be in the form of +local files, or in the form of NIS, LDAP or SQL databases. The DATABASE_README +document gives an introduction to Postfix lookup tables. + +Topics covered in this document: + + * Postfix address rewriting overview + * Address rewriting when mail is received + + o Rewrite addresses to standard form + o Canonical address mapping + o Address masquerading + o Automatic BCC recipients + o Virtual aliasing + + * Address rewriting when mail is delivered + + o Resolve address to destination + o Mail transport switch + o Relocated users table + o Local alias database + o Local per-user .forward files + o Local catch-all address + + * Debugging your address manipulations + +PPoossttffiixx aaddddrreessss rreewwrriittiinngg oovveerrvviieeww + +The figure below zooms in on those parts of Postfix that are most involved with +address rewriting activity. See the OVERVIEW document for an overview of the +complete Postfix architecture. Names followed by a number are Postfix daemon +programs, while unnumbered names represent Postfix queues or internal sources +of mail messages. + + trivial- trivial- + rewrite(8) rewrite(8) + (std form) (resolve) + + ^ | ^ | + | v | v + + smtpd(8) smtp(8) + + qmqpd(8) >- cleanup(8) -> incoming -> active -> qmgr(8) -< lmtp(8) + + pickup(8) local(8) + + ^ ^ | + | | v + + bounces + forwarding deferred + notices + +The table below summarizes all Postfix address manipulations. If you're reading +this document for the first time, skip forward to "Address rewriting when mail +is received". Once you've finished reading the remainder of this document, the +table will help you to quickly find what you need. + + _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ + |AAddddrreessss |SSccooppee|DDaaeemmoonn |GGlloobbaall ttuurrnn--oonn |SSeelleeccttiivvee ttuurrnn--ooffff | + |mmaanniippuullaattiioonn| | |ccoonnttrrooll |ccoonnttrrooll | + |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |Rewrite | |trivial-|append_at_myorigin, | | + |addresses to|all |rewrite |append_dot_mydomain,|none | + |standard |mail |(8) |swap_bangpath, | | + |form | | |allow_percent_hack | | + |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |Canonical |all |cleanup | | | + |address |mail |(8) |canonical_maps |receive_override_options| + |mapping | | | | | + |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |Address |all |cleanup |masquerade_domains |receive_override_options| + |masquerading|mail |(8) | | | + |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |Automatic |new |cleanup |always_bcc, | | + |BCC |mail |(8) |sender_bcc_maps, |receive_override_options| + |recipients | | |recipient_bcc_maps | | + |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |Virtual |all |cleanup |virtual_alias_maps |receive_override_options| + |aliasing |mail |(8) | | | + |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |Resolve |all |trivial-| | | + |address to |mail |rewrite |none |none | + |destination | |(8) | | | + |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |Mail |all |trivial-| | | + |transport |mail |rewrite |transport_maps |none | + |switch | |(8) | | | + |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |Relocated |all |trivial-| | | + |users table |mail |rewrite |relocated_maps |none | + | | |(8) | | | + |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |Local alias |all |local(8)|alias_maps |none | + |database |mail | | | | + |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |Local per- | | | | | + |user |all |local(8)|forward_path |none | + |.forward |mail | | | | + |files | | | | | + |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |Local catch-|all |local(8)|luser_relay |none | + |all address |mail | | | | + |_ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + +AAddddrreessss rreewwrriittiinngg wwhheenn mmaaiill iiss rreecceeiivveedd + +The cleanup(8) server receives mail from outside of Postfix as well as mail +from internal sources such as forwarded mail, undeliverable mail that is +bounced to the sender, and postmaster notifications about problems with the +mail system. + +The cleanup(8) server transforms the sender, recipients and message content +into a standard form before writing it to an incoming queue file. The server +cleans up sender and recipient addresses in message headers and in the +envelope, adds missing message headers such as From: or Date: that are required +by mail standards, and removes message headers such as Bcc: that should not be +present. The cleanup(8) server delegates the more complex address manipulations +to the trivial-rewrite(8) server as described later in this document. + +Address manipulations at this stage are: + + * Rewrite addresses to standard form + * Canonical address mapping + * Address masquerading + * Automatic BCC recipients + * Virtual aliasing + +RReewwrriittee aaddddrreesssseess ttoo ssttaannddaarrdd ffoorrmm + +Before the cleanup(8) daemon runs an address through any address mapping lookup +table, it first rewrites the address to the standard +"user@fully.qualified.domain" form, by sending the address to the trivial- +rewrite(8) daemon. The purpose of rewriting to standard form is to reduce the +number of entries needed in lookup tables. + +The Postfix trivial-rewrite(8) daemon implements the following hard-coded +address manipulations: + + Rewrite "@hosta,@hostb:user@site" to "user@site" + In case you wonder what this is, the address form above is called a + route address, and specifies that mail for "user@site" be delivered via + "hosta" and "hostb". Usage of this form has been deprecated for a long + time. Postfix has no ability to handle route addresses, other than to + strip off the route part. + + Rewrite "site!user" to "user@site" + This feature is controlled by the boolean swap_bangpath parameter + (default: yes). The purpose is to rewrite UUCP-style addresses to + domain style. This is useful only when you receive mail via UUCP, but + it probably does not hurt otherwise. + + Rewrite "user%domain" to "user@domain" + This feature is controlled by the boolean allow_percent_hack parameter + (default: yes). Typically, this is used in order to deal with + monstrosities such as "user%domain@otherdomain". + + Rewrite "user" to "user@$myorigin" + This feature is controlled by the boolean append_at_myorigin parameter + (default: yes). You should never turn off this feature, because a lot + of Postfix components expect that all addresses have the form + "user@domain". + + If your machine is not the main machine for $myorigin and you wish to + have some users delivered locally without going via that main machine, + make an entry in the virtual alias table that redirects + "user@$myorigin" to "user@$myhostname". See also the "delivering some + users locally" section in the STANDARD_CONFIGURATION_README document. + + Rewrite "user@host" to "user@host.$mydomain" + This feature is controlled by the boolean append_dot_mydomain parameter + (default: yes). The purpose is to get consistent treatment of different + forms of the same hostname. + + Some will argue that rewriting "host" to "host.$mydomain" is bad. That + is why it can be turned off. Others like the convenience of having the + local domain appended automatically. + + Rewrite "user@site." to "user@site" (without the trailing dot). + A single trailing dot is silently removed. However, an address that + ends in multiple dots will be rejected as an invalid address. + +CCaannoonniiccaall aaddddrreessss mmaappppiinngg + +The cleanup(8) daemon uses the canonical(5) tables to rewrite all addresses in +message envelopes and in message headers. This is done for local and remote +addresses. The mapping is useful to replace login names by "Firstname.Lastname" +style addresses, or to clean up invalid domains in mail addresses produced by +legacy mail systems. + +Canonical mapping is disabled by default. To enable, edit the canonical_maps +parameter in the main.cf file and specify one or more lookup tables, separated +by whitespace or commas. + +Example: + + /etc/postfix/main.cf: + canonical_maps = hash:/etc/postfix/canonical + + /etc/postfix/canonical: + wietse Wietse.Venema + +For static mappings as shown above, lookup tables such as hash:, ldap:, mysql: +or pgsql: are sufficient. For dynamic mappings you can use regular expression +tables. This requires that you become intimately familiar with the ideas +expressed in regexp_table(5), pcre_table(5) and canonical(5). + +In addition to the canonical maps which are applied to both sender and +recipient addresses, you can specify canonical maps that are applied only to +sender addresses or to recipient addresses. + +Example: + + /etc/postfix/main.cf: + sender_canonical_maps = hash:/etc/postfix/sender_canonical + recipient_canonical_maps = hash:/etc/postfix/recipient_canonical + +The sender and recipient canonical maps are applied before the common canonical +maps. + +Sender-specific rewriting is useful when you want to rewrite ugly sender +addresses to pretty ones, and still want to be able to send mail to the those +ugly address without creating a mailer loop. + +Canonical mapping can be turned off selectively for mail received by smtpd(8), +qmqpd(8), or pickup(8), by overriding main.cf settings in the master.cf file. +This feature is available in Postfix version 2.1 and later. + +Example: + + /etc/postfix/master.cf: + :10026 inet n - n - - smtpd + -o receive_override_options=no_address_mapping + +Note: do not specify whitespace around the "=" here. + +AAddddrreessss mmaassqquueerraaddiinngg + +Address masquerading is a method to hide hosts inside a domain behind their +mail gateway, and to make it appear as if the mail comes from the gateway +itself, instead of from individual machines. + +Address masquerading is disabled by default, and is implemented by the cleanup +(8) server. To enable, edit the masquerade_domains parameter in the main.cf +file and specify one or more domain names separated by whitespace or commas. +When Postfix tries to masquerade a domain, it processes the list from left to +right, and processing stops at the first match. + +Example: + + /etc/postfix/main.cf: + masquerade_domains = foo.example.com example.com + +strips "any.thing.foo.example.com" to "foo.example.com", but strips +"any.thing.else.example.com" to "example.com". + +A domain name prefixed with "!" means do not masquerade this domain or its +subdomains: + + /etc/postfix/main.cf: + masquerade_domains = !foo.example.com example.com + +does not change "any.thing.foo.example.com" and "foo.example.com", but strips +"any.thing.else.example.com" to "example.com". + +The masquerade_exceptions configuration parameter specifies what user names +should not be subjected to address masquerading. Specify one or more user names +separated by whitespace or commas. + +Example: + + /etc/postfix/main.cf: + masquerade_exceptions = root + +By default, Postfix makes no exceptions. + +Subtle point: by default, address masquerading is applied only to message +headers and to envelope sender addresses, but not to envelope recipients. This +allows you to use address masquerading on a mail gateway machine, while still +being able to forward mail from outside to users on individual machines. + +In order to subject envelope recipient addresses to masquerading, too, specify +(Postfix version 1.1 and later): + + /etc/postfix/main.cf: + masquerade_classes = envelope_sender, envelope_recipient, + header_sender, header_recipient + +If you rewrite the envelope recipient like this, Postfix will no longer be able +to send mail to individual machines. + +Address masquerading can be turned off selectively for mail received by smtpd +(8), qmqpd(8), or pickup(8), by overriding main.cf settings in the master.cf +file. This feature is available in Postfix version 2.1 and later. + +Example: + + /etc/postfix/master.cf: + :10026 inet n - n - - smtpd + -o receive_override_options=no_address_mapping + +Note: do not specify whitespace around the "=" here. + +AAuuttoommaattiicc BBCCCC rreecciippiieennttss + +After applying the canonical and masquerade mappings, the cleanup(8) daemon can +generate optional BCC (blind carbon-copy) recipients. Postfix provides three +mechanisms: + + always_bcc = address + Deliver a copy of all mail to the specified address. In Postfix + versions before 2.1, this feature is implemented by smtpd(8), qmqpd(8), + or pickup(8). + sender_bcc_maps = type:table + Search the specified "type:table" lookup table with the envelope sender + address for an automatic BCC address. This feature is available in + Postfix 2.1 and later. + recipient_bcc_maps = type:table + Search the specified "type:table" lookup table with the envelope + recipient address for an automatic BCC address. This feature is + available in Postfix 2.1 and later. + +Note: automatic BCC recipients are produced only for new mail. To avoid mailer +loops, automatic BCC recipients are not generated for mail that Postfix +forwards internally, nor for mail that Postfix generates itself. + +Automatic BCC recipients (including always_bcc) can be turned off selectively +for mail received by smtpd(8), qmqpd(8), or pickup(8), by overriding main.cf +settings in the master.cf file. This feature is available in Postfix version +2.1 and later. + +Example: + + /etc/postfix/master.cf: + :10026 inet n - n - - smtpd + -o receive_override_options=no_address_mapping + +Note: do not specify whitespace around the "=" here. + +VViirrttuuaall aalliiaassiinngg + +Before writing the recipients to the queue file, the cleanup(8) daemon uses the +optional virtual(5) alias tables to redirect mail for recipients. The mapping +affects only envelope recipient addresses; it has no effect on message headers +or envelope sender addresses. Virtual alias lookups are useful to redirect mail +for virtual alias domains to real user mailboxes, and to redirect mail for +domains that no longer exist. Virtual alias lookups can also be used to +transform " Firstname.Lastname " back into UNIX login names, although it seems +that local aliases may be a more appropriate vehicle. See the VIRTUAL_README +document for an overview of methods to host virtual domains with Postfix. + +Virtual aliasing is disabled by default. To enable, edit the virtual_alias_maps +parameter in the main.cf file and specify one or more lookup tables, separated +by whitespace or commas. + +Example: + + /etc/postfix/main.cf: + virtual_alias_maps = hash:/etc/postfix/virtual + + /etc/postfix/virtual: + Wietse.Venema wietse + +Addresses found in virtual alias maps are subjected to another iteration of +virtual aliasing, but are not subjected to canonical mapping, in order to avoid +loops. + +For static mappings as shown above, lookup tables such as hash:, ldap:, mysql: +or pgsql: are sufficient. For dynamic mappings you can use regular expression +tables. This requires that you become intimately familiar with the ideas +expressed in regexp_table(5), pcre_table(5) and virtual(5). + +Note: automatic BCC recipients are produced only for new mail. To avoid mailer +loops, automatic BCC recipients are not generated for mail that is forwarded +internally, and are not generated for mail that is generated by Postfix itself. + +Virtual aliasing can be turned off selectively for mail received by smtpd(8), +qmqpd(8), or pickup(8), by overriding main.cf settings in the master.cf file. +This feature is available in Postfix version 2.1 and later. + +Example: + + /etc/postfix/master.cf: + :10026 inet n - n - - smtpd + -o receive_override_options=no_address_mapping + +Note: do not specify whitespace around the "=" here. + +At this point the message is ready to be stored into the Postfix incoming +queue. + +AAddddrreessss rreewwrriittiinngg wwhheenn mmaaiill iiss ddeelliivveerreedd + +The Postfix queue manager sorts mail according to its destination and gives it +to Postfix delivery agents such as local(8), smtp(8), or lmtp(8). Just like the +cleanup(8) server, the Postfix queue manager delegates the more complex address +manipulations to the trivial-rewrite(8) server. + +Address manipulations at this stage are: + + * Resolve address to destination + * Mail transport switch + * Relocated users table + +Each Postfix delivery agent tries to deliver the mail to its destination, while +encapsulating the sender, recipients, and message content according to the +rules of the SMTP, LMTP, etc. protocol. When mail cannot be delivered, it is +either returned to the sender or moved to the deferred queue and tried again +later. + +Address manipulations when mail is delivered via the local(8) delivery agent: + + * Local alias database + * Local per-user .forward files + * Local catch-all address + +The remainder of this document presents each address manipulation step in more +detail, with specific examples or with pointers to documentation with examples. + +RReessoollvvee aaddddrreessss ttoo ddeessttiinnaattiioonn + +The Postfix qmgr(8) queue manager selects new mail from the incoming queue or +old mail from the deferred queue, and asks the trivial-rewrite(8) address +rewriting and resolving daemon where it should be delivered. + +As of version 2.0, Postfix distinguishes four major address classes. Each class +has its own list of domain names, and each class has its own default delivery +method, as shown in the table below. See the ADDRESS_CLASS_README document for +the fine details. Postfix versions before 2.0 only distinguish between local +delivery and everything else. + + _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ + |DDeessttiinnaattiioonn ddoommaaiinn lliisstt |DDeeffaauulltt ddeelliivveerryy mmeetthhoodd|AAvvaaiillaabbiilliittyy| + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ | + |$mydestination, $inet_interfaces,|$local_transport |Postfix 1.0 | + |$proxy_interfaces | | | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ | + |$virtual_mailbox_domains |$virtual_transport |Postfix 2.0 | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ | + |$relay_domains |$relay_transport |Postfix 2.0 | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ | + |none |$default_transport |Postfix 1.0 | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ | + +MMaaiill ttrraannssppoorrtt sswwiittcchh + +Once the trivial-rewrite(8) daemon has determined a default delivery method it +searches the optional transport(5) table for information that overrides the +message destination and/or delivery method. Typical use of the transport(5) is +to send mail to a system that is not connected to the Internet, or to use a +special SMTP client configuration for destinations that have special +requirements. See, for example, the STANDARD_CONFIGURATION_README and +UUCP_README documents, and the examples in the transport(5) manual page. + +Transport table lookups are disabled by default. To enable, edit the +transport_maps parameter in the main.cf file and specify one or more lookup +tables, separated by whitespace or commas. + +Example: + + /etc/postfix/main.cf: + transport_maps = hash:/etc/postfix/transport + +RReellooccaatteedd uusseerrss ttaabbllee + +Next, the trivial-rewrite(8) address rewriting and resolving daemon runs each +recipient through the relocated(5) database. This table provides information on +how to reach users that no longer have an account, or what to do with mail for +entire domains that no longer exist. When mail is sent to an address that is +listed in this table, the message is returned to the sender with an informative +message. + +The relocated(5) database is searched after transport(5) table lookups, in +anticipation of transport(5) tables that can replace one recipient address by a +different one. + +Lookups of relocated users are disabled by default. To enable, edit the +relocated_maps parameter in the main.cf file and specify one or more lookup +tables, separated by whitespace or commas. + +Example: + + /etc/postfix/main.cf: + relocated_maps = hash:/etc/postfix/relocated + + /etc/postfix/relocated: + username@example.com otheruser@elsewhere.tld + +As of Postfix version 2, mail for a relocated user will be rejected by the SMTP +server with the reason "user has moved to otheruser@elsewhere.tld". Older +Postfix versions will receive the mail first, and then return it to the sender +as undeliverable, with the same reason. + +LLooccaall aalliiaass ddaattaabbaassee + +When mail is to be delivered locally, the local(8) delivery agent runs each +local recipient name through the aliases(5) database. The mapping does not +affect addresses in message headers. Local aliases are typically used to +implement distribution lists, or to direct mail for standard aliases such as +postmaster to real people. The table can also be used to map +"Firstname.Lastname" addresses to login names. + +Alias lookups are enabled by default. The default configuration depends on the +operating system environment, but it is typically one of the following: + + /etc/postfix/main.cf: + alias_maps = hash:/etc/aliases + alias_maps = dbm:/etc/aliases, nis:mail.aliases + +The pathname of the alias database file is controlled with the alias_database +configuration parameter. The value is system dependent. Usually it is one of +the following: + + /etc/postfix/main.cf: + alias_database = hash:/etc/aliases (4.4BSD, LINUX) + alias_database = dbm:/etc/aliases (4.3BSD, SYSV<4) + alias_database = dbm:/etc/mail/aliases (SYSV4) + +An aliases(5) file can specify that mail should be delivered to a local file, +or to a command that receives the message in the standard input stream. For +security reasons, deliveries to command and file destinations are performed +with the rights of the alias database owner. A default userid, default_privs, +is used for deliveries to commands or files in "root"-owned aliases. + +LLooccaall ppeerr--uusseerr ..ffoorrwwaarrdd ffiilleess + +With delivery via the local(8) deliver agent, users can control their own mail +delivery by specifying destinations in a file called .forward in their home +directories. The syntax of these files is the same as with the local aliases(5) +file, except that the left-hand side of the alias (lookup key and colon) are +not present. + +LLooccaall ccaattcchh--aallll aaddddrreessss + +When the local(8) delivery agent finds that a message recipient does not exist, +the message is normally returned to the sender ("user unknown"). Sometimes it +is desirable to forward mail for non-existing recipients to another machine. +For this purpose you can specify an alternative destination with the +luser_relay configuration parameter. + +Alternatively, mail for non-existent recipients can be delegated to an entirely +different message transport, as specified with the fallback_transport +configuration parameter. For details, see the local(8) delivery agent +documentation. + +Note: if you use the luser_relay feature in order to receive mail for non-UNIX +accounts, then you must specify: + + /etc/postfix/main.cf: + local_recipient_maps = + +(i.e. empty) in the main.cf file, otherwise the Postfix SMTP server will reject +mail for non-UNIX accounts with "User unknown in local recipient table". See +the LOCAL_RECIPIENT_README file for more information on this. + +luser_relay can specify one address. It is subjected to "$name" expansions. +Examples: + + $user@other.host + The bare username, without address extension, is prepended to + "@other.host". For example, mail for "username+foo" is sent to + "username@other.host". + + $local@other.host + The entire original recipient localpart, including address extension, + is prepended to "@other.host". For example, mail for "username+foo" is + sent to "username+foo@other.host". + + sysadmin+$user + The bare username, without address extension, is appended to + "sysadmin". For example, mail for "username+foo" is sent to + "sysadmin+username". + + sysadmin+$local + The entire original recipient localpart, including address extension, + is appended to "sysadmin". For example, mail for "username+foo" is sent + to "sysadmin+username+foo". + +DDeebbuuggggiinngg yyoouurr aaddddrreessss mmaanniippuullaattiioonnss + +With Postfix version 2.1 and later you can ask Postfix to produce mail delivery +reports for debugging purposes. These reports not only show sender/recipient +addresses after address rewriting and alias expansion or forwarding, they also +show information about delivery to mailbox, delivery to non-Postfix command, +responses from remote SMTP servers, and so on. + +Postfix can produce two types of mail delivery reports for debugging: + + * What-if: report what would happen, but do not actually deliver mail. This + mode of operation is requested with: + + $ //uussrr//ssbbiinn//sseennddmmaaiill --bbvv aaddddrreessss...... + Mail Delivery Status Report will be mailed to . + + * What happened: deliver mail and report successes and/or failures, including + replies from remote SMTP servers. This mode of operation is requested with: + + $ //uussrr//ssbbiinn//sseennddmmaaiill --vv aaddddrreessss...... + Mail Delivery Status Report will be mailed to . + +These reports contain information that is generated by Postfix delivery agents. +Since these run as daemon processes and do not interact with users directly, +the result is sent as mail to the sender of the test message. The format of +these reports is practically identical to that of ordinary non-delivery +notifications. + +As an example, below is the delivery report that is produced with the command +"sendmail -bv postfix-users@postfix.org". The first part of the report contains +human-readable text. In this case, mail would be delivered via mail.cloud9.net, +and the SMTP server replies with "250 Ok". Other reports may show delivery to +mailbox, or delivery to non-Postfix command. + + Content-Description: Notification + Content-Type: text/plain + + This is the Postfix program at host spike.porcupine.org. + + Enclosed is the mail delivery report that you requested. + + The Postfix program + + : delivery via mail.cloud9.net[168.100.1.4]: 250 + Ok + +The second part of the report is in machine-readable form, and includes the +following information: + + * The envelope sender address (wietse@porcupine.org). + * The envelope recipient address (postfix-users@postfix.org). If the + recipient address was changed by Postfix then Postfix also includes the + original recipient address. + * The delivery status. + +Some details are still preliminary and will change as Postfix implements the +DSN (delivery status notification) standards. + + Content-Description: Delivery report + Content-Type: message/delivery-status + + Reporting-MTA: dns; spike.porcupine.org + X-Postfix-Queue-ID: 84863BC0E5 + X-Postfix-Sender: rfc822; wietse@porcupine.org + Arrival-Date: Tue, 13 Apr 2004 19:27:43 -0400 (EDT) + + Final-Recipient: rfc822; postfix-users@postfix.org + Action: deliverable + Status: 2.0.0 + Diagnostic-Code: X-Postfix; delivery via mail.cloud9.net[168.100.1.4]: 250 + Ok + +The third part of the report contains the message that Postfix would have +delivered, including From: and To: message headers, so that you can see any +effects of address rewriting on those. Mail submitted with "sendmail -bv" has +no body content so none is shown in the example below. + + Content-Description: Message + Content-Type: message/rfc822 + + Received: by spike.porcupine.org (Postfix, from userid 1001) + id 84863BC0E5; Tue, 13 Apr 2004 19:27:43 -0400 (EDT) + Subject: probe + To: postfix-users@postfix.org + Message-Id: <20040413232743.84863BC0E5@spike.porcupine.org> + Date: Tue, 13 Apr 2004 19:27:43 -0400 (EDT) + From: wietse@porcupine.org (Wietse Venema) + diff --git a/postfix/README_FILES/ADDRESS_VERIFICATION_README b/postfix/README_FILES/ADDRESS_VERIFICATION_README index 1813f58af..c6ff2fee6 100644 --- a/postfix/README_FILES/ADDRESS_VERIFICATION_README +++ b/postfix/README_FILES/ADDRESS_VERIFICATION_README @@ -1,286 +1,326 @@ -WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING -=============================================================== - -The sender/recipient address verification feature described in this -document is suitable only for low-traffic sites. It performs poorly -under high load. See the "Limitations" section below for details. - -Address verification -==================== - -Sender address verification blocks mail from an unknown sender -address until after the address is verified. An address is verified -by probing the nearest MTA for that address, without actually -delivering mail to it (SMTP interruptus). Probe messages are like -normal mail, but are discarded instead of being deferred or bounced. - -The same technique may be useful to block mail for undeliverable -recipients, for example on mail relay hosts that do not have a copy -of all the relayed 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. - -With address verification turned on, normal mail will suffer only -a short delay of up to 6 seconds while an address is verified for -the first time. Once an address status is known, the status is -cached and Postfix replies immediately. When verification takes -too long the Postfix SMTP server defers the sender or recipient -address with a 450 reply. Normal mail clients will connect again -after some delay. - -The address verification delay is configurable with the main.cf -address_verify_poll_count and address_verify_poll_delay parameters. -See the sample-verify.cf file for details. - -Limitations -=========== - -Postfix probes the nearest MTA for the address that is being -verified, without actually sending mail to that address. If the -nearest MTA accepts the recipient, then Postfix assumes that the -address is deliverable, even when the address will bounce AFTER -that MTA accepts it. - -Normally, address verification probe messages follow the same path -as regular mail. However, some sites send mail to the Internet -via an intermediate relayhost; this breaks address verification. -See below, section "Controlling the routing of address verification -probes", for how to override mail routing and for possible limitations -when you have to do this. - -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. - -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. - -By default, Postfix probe messages have "postmaster@$myorigin" as -the sender address. You can change this into the null address -(address_verify_sender =) but that causes address probes to fail -with mis-configured sites that reject MAIL FROM: <>. - -Turning on recipient address verification -========================================= - -Recipient address verification may be useful to block mail for -undeliverable recipients on mail relay hosts that do not have a -copy of all the relayed recipient addresses. This prevents the mail -queue from filling up with undeliverable and bounced mail. - -Recipient address verification is relatively straightforward and -there are no surprises. If a recipient probe fails, then Postfix -rejects mail for the recipient address. If a recipient probe -succeeds, then Postfix accepts mail for the recipient address. - -/etc/postfix/main.cf: - smtpd_recipient_restrictions = - permit_mynetworks - reject_unauth_destination - ... - reject_unknown_recipient_domain - reject_unverified_recipient - ... - -The "reject_unknown_recipient_domain" restriction blocks mail for -non-existent domains. Putting this before "reject_unverified_recipient" -avoids the overhead of generating unnecessary probe messages. - -The unverified_recipient_reject_code parameter (default 450) -specifies how Postfix replies when a recipient address is known to -bounce. Change this setting into 550 when you trust Postfix's -judgments. - -Sender address verification for mail from frequently forged domains -=================================================================== - -It is relatively safe to turn on sender address verification for -specific domains that often appear in forged email. - -/etc/postfix/main.cf: - smtpd_sender_restrictions = hash:/etc/postfix/sender_access - unverified_sender_reject_code = 550 - # Be sure to read the "Caching" section below! - address_verify_map = btree:/var/mta/verify - -/etc/postfix/sender_access: - aol.com reject_unverified_sender - hotmail.com reject_unverified_sender - bigfoot.com reject_unverified_sender - ... etcetera ... - -A list of frequently forged MAIL FROM domains can be found at -http://www.monkeys.com/anti-spam/filtering/sender-domain-validate.in - -NOTE: One of the first things you might want to do is to turn on -sender address verification for all your own domains. - -Turning on sender address verification for all email -==================================================== - -Unfortunately, sender address verification cannot simply be turned -on for all email - you are likely to lose legitimate mail from -mis-configured systems. You almost certainly will have to set up -white lists for specific addresses, or even for entire domains. - -To find out how sender address verification would affect your mail, -specify "warn_if_reject reject_unverified_sender" so that you can -see what mail would be blocked: - -/etc/postfix/main.cf: - smtpd_sender_restrictions = - permit_mynetworks - ... - check_sender_access hash:/etc/postfix/sender_access - reject_unknown_sender_domain - warn_if_reject reject_unverified_sender - ... - # Be sure to read the "Caching" section below! - address_verify_map = btree:/var/mta/verify - -This is also a good way to populate your cache with address -verification results before you start to actually reject mail. - -The sender_access restriction is needed to whitelist domains or -addresses that are known to be OK. Although Postfix will not mark -a known-to-be-good address as bad after a probe fails, it is better -to be safe than sorry. - -NOTE: You will have to whitelist sites such as securityfocus.com -and other sites that operate mailing lists that use a different -sender address for each posting (VERP). Such addresses pollute -the address verification cache quickly, and generate unnecessary -sender verification probes. - -/etc/postfix/sender_access - securityfocus.com OK - ... - -The "reject_unknown_sender_domain" restriction blocks mail from -non-existent domains. Putting this before "reject_unverified_sender" -avoids the overhead of generating unnecessary probe messages. - -The unverified_sender_reject_code parameter (default 450) specifies -how Postfix replies when a sender address is known to bounce. -Change this setting into 550 when you trust Postfix's judgments. - -Caching -======= - -NOTE: By default, address verification information is not stored -in a persistent file. You have to specify one in main.cf (see -below). Persistent storage is off by default because it may need -more disk space than is available in your file system. - -Address verification information is cached by the Postfix verify -daemon. Postfix has a bunch of parameters that control the caching -of positive and negative results. Refer to the verify(8) manual -page or the sample-verify.cf file for details. - -The address_verify_map (NOTE: singular) configuration parameter -specifies an optional persistent database for sender address -verification results. If you don't specify a file, all address -verification information is lost after "postfix reload" or "postfix -stop". +PPoossttffiixx AAddddrreessss VVeerriiffiiccaattiioonn HHoowwttoo + +------------------------------------------------------------------------------- + +WWAARRNNIINNGG WWAARRNNIINNGG WWAARRNNIINNGG + +The sender/recipient address verification feature described in this document is +suitable only for low-traffic sites. It performs poorly under high load and may +cause your site to be blacklisted by some providers. See the "Limitations" +section below for details. + +WWhhaatt PPoossttffiixx aaddddrreessss vveerriiffiiccaattiioonn ccaann ddoo ffoorr yyoouu + +Address verification is a feature that allows the Postfix SMTP server to block +a sender (MAIL FROM) or recipient (RCPT TO) address until the address has been +verified to be deliverable. + +The technique has obvious uses in order 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 +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. + +This feature is available in Postfix version 2.1 and later. + +Topics covered in this document: + + * How address verification works + * Limitations of address verification + * Recipient address verification + * Sender address verification for mail from frequently forged domains + * Sender address verification for all email + * Address verification database + * Managing the address verification database + * Controlling the routing of address verification probes + * Forced probe routing examples + * Limitations of forced probe routing + +HHooww aaddddrreessss vveerriiffiiccaattiioonn wwoorrkkss + +A sender or recipient address is verified by probing the nearest MTA for that +address, without actually delivering mail. The nearest MTA could be Postfix +itself, or it could be a remote MTA (SMTP interruptus). Probe 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 + +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 +time. Once an address status is known, the status is cached and Postfix replies +immediately. + +When verification takes too long the Postfix SMTP server defers the sender or +recipient address with a 450 reply. Normal mail clients will connect again +after some delay. The address verification delay is configurable with the +main.cf address_verify_poll_count and address_verify_poll_delay parameters. See +postconf(5) for details. + +LLiimmiittaattiioonnss ooff aaddddrreessss vveerriiffiiccaattiioonn + + * Postfix probes the nearest MTA for the address that is being verified, + without actually sending mail to that address. If the nearest MTA accepts + the address, then Postfix assumes that the address is deliverable, even + when the address will bounce AFTER that MTA accepts it. + + * Sites like AOL 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 them too often for a non-existent address. + + * Normally, address verification probe messages follow the same path as + regular mail. However, some sites send mail to the Internet via an + intermediate relayhost; this breaks address verification. See below, + section "Controlling the routing of address verification probes", for how + to override mail routing and for possible limitations when you have to do + this. + + * 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. + + * 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. + + * By default, Postfix probe messages have "postmaster@$myorigin" as the + sender address. 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. + +RReecciippiieenntt aaddddrreessss vveerriiffiiccaattiioonn + +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. + +Recipient address verification is relatively straightforward and there are no +surprises. If a recipient probe fails, then Postfix rejects mail for the +recipient address. If a recipient probe succeeds, then Postfix accepts mail for +the recipient address. + + /etc/postfix/main.cf: + smtpd_recipient_restrictions = + permit_mynetworks + reject_unauth_destination + ... + reject_unknown_recipient_domain + reject_unverified_recipient + ... + +The "reject_unknown_recipient_domain" restriction blocks mail for non-existent +domains. Putting this before "reject_unverified_recipient" avoids the overhead +of generating unnecessary probe messages. + +The unverified_recipient_reject_code parameter (default 450) specifies how +Postfix replies when a recipient address is known to bounce. Change this +setting into 550 when you trust Postfix's judgments. + +SSeennddeerr aaddddrreessss vveerriiffiiccaattiioonn ffoorr mmaaiill ffrroomm ffrreeqquueennttllyy ffoorrggeedd ddoommaaiinnss + +It is relatively safe to turn on sender address verification for specific +domains that often appear in forged email. + + /etc/postfix/main.cf: + smtpd_sender_restrictions = hash:/etc/postfix/sender_access + unverified_sender_reject_code = 550 + # Note 1: Be sure to read the "Caching" section below! + # Note 2: Avoid hash files here. Use btree instead. + address_verify_map = btree:/var/mta/verify + + /etc/postfix/sender_access: + aol.com reject_unverified_sender + hotmail.com reject_unverified_sender + bigfoot.com reject_unverified_sender + ... etcetera ... + +A list of frequently forged MAIL FROM domains can be found at http:// +www.monkeys.com/anti-spam/filtering/sender-domain-validate.in. + +NOTE: One of the first things you might want to do is to turn on sender address +verification for all your own domains. + +SSeennddeerr aaddddrreessss vveerriiffiiccaattiioonn ffoorr aallll eemmaaiill + +Unfortunately, sender address verification cannot simply be turned on for all +email - you are likely to lose legitimate mail from mis-configured systems. You +almost certainly will have to set up white lists for specific addresses, or +even for entire domains. + +To find out how sender address verification would affect your mail, specify +"warn_if_reject reject_unverified_sender" so that you can see what mail would +be blocked: + + /etc/postfix/main.cf: + smtpd_sender_restrictions = + permit_mynetworks + ... + check_sender_access hash:/etc/postfix/sender_access + reject_unknown_sender_domain + warn_if_reject reject_unverified_sender + ... + # Note 1: Be sure to read the "Caching" section below! + # Note 2: Avoid hash files here. Use btree instead. + address_verify_map = btree:/var/mta/verify + +This is also a good way to populate your cache with address verification +results before you start to actually reject mail. + +The sender_access restriction is needed to whitelist domains or addresses that +are known to be OK. Although Postfix will not mark a known-to-be-good address +as bad after a probe fails, it is better to be safe than sorry. + +NOTE: You will have to whitelist sites such as securityfocus.com and other +sites that operate mailing lists that use a different sender address for each +posting (VERP). Such addresses pollute the address verification cache quickly, +and generate unnecessary sender verification probes. + + /etc/postfix/sender_access + securityfocus.com OK + ... + +The "reject_unknown_sender_domain" restriction blocks mail from non-existent +domains. Putting this before "reject_unverified_sender" avoids the overhead of +generating unnecessary probe messages. + +The unverified_sender_reject_code parameter (default 450) specifies how Postfix +replies when a sender address is known to bounce. Change this setting into 550 +when you trust Postfix's judgments. + +AAddddrreessss vveerriiffiiccaattiioonn ddaattaabbaassee + +NOTE: By default, address verification information is not stored in a +persistent file. You have to specify one in main.cf (see below). Persistent +storage is off by default because it may need more disk space than is available +in your file system. + +Address verification information is cached by the Postfix verify daemon. +Postfix has a bunch of parameters that control the caching of positive and +negative results. Refer to the verify(8) manual page for details. + +The address_verify_map (NOTE: singular) configuration parameter specifies an +optional persistent database for sender address verification results. If you +don't specify a file, all address verification information is lost after +"postfix reload" or "postfix stop". If your /var file system has sufficient space, try: - address_verify_map = btree:/var/mta/verify - -NOTE: Do not put this file in a file system that fills up. When -the address verification table gets corrupted the world comes to -an end and YOU will have to MANUALLY fix things as described in -the next section. Meanwhile you will not receive mail via SMTP. - -The verify daemon process will create a new database when none -exists, and will open/create the file before it enters the chroot -jail and before it drops root privileges. - -Managing the address verification database -========================================== - -The verify(8) manual page describes parameters that control how -long information remains cached before it needs to be refreshed, -and how long information can remain "unrefreshed" before it expires. -Postfix uses different controls for positive results (address was -accepted) and for negative results (address was rejected). - -Right now, no tools are provided to manage the address verification -database. If the file gets too big, or if it gets corrupted, you -can manually rename or delete the file and run "postfix reload". -The new verify daemon process will then create a new database. - -Controlling the routing of address verification probes -====================================================== - -By default, Postfix sends address verification probe messages via -the same route as regular mail, because that normally produces the -most accurate result. It's no good to verify a local address by -connecting to your own SMTP port; that just triggers all kinds of -mailer loop alarms. The same is true for any destination that your -machine is best MX host for: hidden domains, virtual domains, etc. - -However, some sites have a complex infrastructure where mail is -not sent directly to the Internet, but is instead given to an -intermediate relayhost. This is a problem for address verification, -because remote Internet destinations can be verified only when -Postfix can access those destinations directly. - -For this reason, Postfix allows you to override the routing parameters -when it delivers an address verification probe message. - -First, the address_verify_relayhost parameter allows you to override -the relayhost setting, and the address_verify_transport_maps -parameter allows you to override the transport_maps setting. - -Second, each address class is given its own address verification -version of the message delivery transport (address classes are -defined in the ADDRESS_CLASS_README file) as shown in the table: - -Destination type Regular transport Verify transport - parameter name parameter name -===================================================================== -mydestination local_transport address_verify_local_transport -virtual_alias_domains (not applicable) (not applicable) -virtual_mailbox_domains virtual_transport address_verify_virtual_transport -relay_domains relay_transport address_verify_relay_transport -other default_transport address_verify_default_transport - -By default, the parameters that control delivery of address probes -have the same value as the parameters that control normal mail -delivery. - -Examples --------- - -In a typical scenario one would override the relayhost setting -for address verification probes and leave everything else alone: - -/etc/postfix/main.cf: - relayhost = $mydomain - address_verify_relayhost = - ... - -Sites behind an address translation relay might have to use a -different SMTP client that sends the correct hostname information: - -/etc/postfix/main.cf: - relayhost = $mydomain - address_verify_relayhost = - address_verify_default_transport = direct_smtp - -/etc/postfix/master.cf: - direct_smtp .. .. .. .. .. .. .. .. .. smtp -o smtp_helo_name=nat.box.tld - -Limitations ------------ - -Inconsistencies can happen when probe messages don't follow the -same path as regular mail. For example, a message can be accepted -when it follows the regular route while an otherwise identical -probe message is rejected when it follows the forced route. The -opposite can happen, too, but is less likely. + /etc/postfix/main.cf: + # Note: avoid hash files here. Use btree instead. + address_verify_map = btree:/var/mta/verify + +NOTE: Do not put this file in a file system that may run out of space. When the +address verification table gets corrupted the world comes to an end and YOU +will have to MANUALLY fix things as described in the next section. Meanwhile, +you will not receive mail via SMTP. + +The verify(8) daemon process will create a new database when none exists, and +will open/create the file before it enters the chroot jail and before it drops +root privileges. + +MMaannaaggiinngg tthhee aaddddrreessss vveerriiffiiccaattiioonn ddaattaabbaassee + +The verify(8) manual page describes parameters that control how long +information remains cached before it needs to be refreshed, and how long +information can remain "unrefreshed" before it expires. Postfix uses different +controls for positive results (address was accepted) and for negative results +(address was rejected). + +Right now, no tools are provided to manage the address verification database. +If the file gets too big, or if it gets corrupted, you can manually rename or +delete the file and run "postfix reload". The new verify daemon process will +then create a new database. + +CCoonnttrroolllliinngg tthhee rroouuttiinngg ooff aaddddrreessss vveerriiffiiccaattiioonn pprroobbeess + +By default, Postfix sends address verification probe messages via the same +route as regular mail, because that normally produces the most accurate result. +It's no good to verify a local address by connecting to your own SMTP port; +that just triggers all kinds of mailer loop alarms. The same is true for any +destination that your machine is best MX host for: hidden domains, virtual +domains, etc. + +However, some sites have a complex infrastructure where mail is not sent +directly to the Internet, but is instead given to an intermediate relayhost. +This is a problem for address verification, because remote Internet addresses +can be verified only when Postfix can access remote destinations directly. + +For this reason, Postfix allows you to override the routing parameters when it +delivers an address verification probe message. + +First, the address_verify_relayhost parameter allows you to override the +relayhost setting, and the address_verify_transport_maps parameter allows you +to override the transport_maps setting. + +Second, each address class is given its own address verification version of the +message delivery transport, as shown in the table below. Address classes are +defined in the ADDRESS_CLASS_README file. + + _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ + |DDoommaaiinn lliisstt |RReegguullaarr ttrraannssppoorrtt|VVeerriiffyy ttrraannssppoorrtt | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |mydestination |local_transport |address_verify_local_transport | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |virtual_alias_domains |(not applicable) |(not applicable) | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |virtual_mailbox_domains|virtual_transport|address_verify_virtual_transport| + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |relay_domains |relay_transport |address_verify_relay_transport | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |(not applicable) |default_transport|address_verify_default_transport| + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + +By default, the parameters that control delivery of address probes have the +same value as the parameters that control normal mail delivery. + +FFoorrcceedd pprroobbee rroouuttiinngg eexxaammpplleess + +In a typical scenario one would override the relayhost setting for address +verification probes and leave everything else alone: + + /etc/postfix/main.cf: + relayhost = $mydomain + address_verify_relayhost = + ... + +Sites behind a network address translation box might have to use a different +SMTP client that sends the correct hostname information: + + /etc/postfix/main.cf: + relayhost = $mydomain + address_verify_relayhost = + address_verify_default_transport = direct_smtp + + /etc/postfix/master.cf: + direct_smtp .. .. .. .. .. .. .. .. .. smtp + -o smtp_helo_name=nat.box.tld + +LLiimmiittaattiioonnss ooff ffoorrcceedd pprroobbee rroouuttiinngg + +Inconsistencies can happen when probe messages don't follow the same path as +regular mail. For example, a message can be accepted when it follows the +regular route while an otherwise identical probe message is rejected when it +follows the forced route. The opposite can happen, too, but is less likely. + diff --git a/postfix/README_FILES/BACKSCATTER_README b/postfix/README_FILES/BACKSCATTER_README new file mode 100644 index 000000000..be0d750c5 --- /dev/null +++ b/postfix/README_FILES/BACKSCATTER_README @@ -0,0 +1,185 @@ +PPoossttffiixx BBaacckkssccaatttteerr HHoowwttoo + +------------------------------------------------------------------------------- + +OOvveerrvviieeww + +This document describes features that require Postfix version 2.0 or later. + +Topics covered in this document: + + * What is backscatter mail? + * How do I block backscatter mail to random recipient addresses? + * How do I block backscatter mail to real recipient addresses? + + o Blocking backscatter mail with forged HELO information + o Blocking backscatter mail with forged sender information + o Blocking backscatter mail with other forged information + o Blocking backscatter mail from virus scanners + +WWhhaatt iiss bbaacckkssccaatttteerr mmaaiill?? + +When a spammer or worm sends mail with forged sender addresses, innocent sites +are flooded with undeliverable mail notifications. This is called backscatter +mail, and if your system is flooded then you will find out soon enough. + +HHooww ddoo II bblloocckk bbaacckkssccaatttteerr mmaaiill ttoo rraannddoomm rreecciippiieenntt aaddddrreesssseess?? + +If your machine receives backscatter mail to random addresses, configure +Postfix to reject all mail for non-existent recipients as described in the +LOCAL_RECIPIENT_README and STANDARD_CONFIGURATION_README documentation. + +If your machine runs Postfix 2.0 and earlier, disable the "pause before reject" +feature in the SMTP server. If your system is under stress then it should not +waste time. + + /etc/postfix/main.cf: + # Not needed with Postfix 2.1 and later. + smtpd_error_sleep_time = 0 + +HHooww ddoo II bblloocckk bbaacckkssccaatttteerr mmaaiill ttoo rreeaall rreecciippiieenntt aaddddrreesssseess?? + +When backscatter mail passes the "unknown recipient" barrier, there still is no +need to despair. Many mail systems are kind enough to attach the message +headers of the undeliverable mail in the non-delivery notification. These +message headers contain information that you can use to recognize and block +forged mail. + +BBlloocckkiinngg bbaacckkssccaatttteerr mmaaiill wwiitthh ffoorrggeedd HHEELLOO iinnffoorrmmaattiioonn + +Although my email address is "wietse@porcupine.org", all my mail systems +announce themselves with the SMTP HELO command as "hostname.porcupine.org". +Thus, if returned mail has a Received: message header like this: + + Received: from porcupine.org ... + +Then I know that this is almost certainly forged mail. Mail that is really sent +by my systems looks like this: + + Received: from hostname.porcupine.org ... + +For the same reason the following message headers are very likely to be the +result of forgery: + + Received: from host.example.com ([1.2.3.4] helo=porcupine.org) ... + Received: from [1.2.3.4] (port=12345 helo=porcupine.org) ... + Received: from host.example.com (HELO porcupine.org) ... + Received: from host.example.com (EHLO porcupine.org) ... + +To block such backscatter I use header_checks and body_checks patterns like +this: + + /etc/postfix/main.cf: + header_checks = regexp:/etc/postfix/header_checks + body_checks = regexp:/etc/postfix/body_checks + + /etc/postfix/header_checks: + /^Received: +from +(porcupine\.org) +/ + reject forged client name in Received: header: $1 + /^Received: +from +[^ ]+ +\(([^ ]+ +[he]+lo=|[he]+lo +) + (porcupine\.org)\)/ + reject forged client name in Received: header: $2 + + /etc/postfix/body_checks: + /^[> ]*Received: +from +(porcupine\.org) / + reject forged client name in Received: header: $1 + /^[> ]*Received: +from +[^ ]+ +\(([^ ]+ +[he]+lo=|[he]+lo +) + (porcupine\.org)\)/ + reject forged client name in Received: header: $2 + +Notes: + + * The example is simplified for educational purposes. In reality my patterns + list multiple domain names, as "(domain|domain|...)". + + * The "\." matches "." literally. Without the "\", the "." would match any + character. + + * The "\(" and "\)" match "(" and ")" literally. Without the "\", the "(" and + ")" would be grouping operators. + +CCaavveeaattss + +Netscape Messenger (and reportedly, Mozilla) sends a HELO name that is +identical to the sender address domain part. If you have such clients then the +above patterns would block legitimate email. + +My network has only one such machine, and to prevent its mail from being +blocked I have configured it to send mail as user@hostname.porcupine.org. On +the Postfix server, a canonical mapping translates this temporary address into +user@porcupine.org. + + /etc/postfix/main.cf: + canonical_maps = hash:/etc/postfix/canonical + + /etc/postfix/canonical: + @hostname.porcupine.org @porcupine.org + +This is of course practical only when you have very few systems that send HELO +commands like this, and when you never have to send mail to a user on such a +host. + +An alternative would be to remove the hostname with address masquerading, as +described in the ADDRESS_REWRITING_README document. + +BBlloocckkiinngg bbaacckkssccaatttteerr mmaaiill wwiitthh ffoorrggeedd sseennddeerr iinnffoorrmmaattiioonn + +Like many people I still have a few email addresses in domains that I used in +the past. Mail for those addresses is forwarded to my current address. Most of +the backscatter mail that I get claims to be sent from these addresses. Such +mail is obviously forged and is very easy to stop. + + /etc/postfix/main.cf: + header_checks = regexp:/etc/postfix/header_checks + body_checks = regexp:/etc/postfix/body_checks + + /etc/postfix/header_checks: + /^(From|Return-Path):.*[[:<:]](user@domain\.tld)[[:>:]]/ + reject forged sender address in $1: message header: $2 + + /etc/postfix/body_checks: + /^[> ]*(From|Return-Path):.*[[:<:]](user@domain\.tld)[[:>:]]/ + reject forged sender address in $1: message header: $2 + +Notes: + + * The example is simplified for educational purposes. In reality, my patterns + list multiple email addresses as "(user1@domain1\.tld|user2@domain2\.tld)". + + * The [[:<:]] matches the beginning of a word, and the [[:>:]] matches the + end. + + * The "\." matches "." literally. Without the "\", the "." would match any + character. + +BBlloocckkiinngg bbaacckkssccaatttteerr mmaaiill wwiitthh ootthheerr ffoorrggeedd iinnffoorrmmaattiioonn + +Another sign of forgery can be found in the IP address that is recorded in +Received: headers next to your HELO host or domain name. This information must +be used with care, though. Some mail servers are behind a network address +translator and never see the true client IP address. + +BBlloocckkiinngg bbaacckkssccaatttteerr mmaaiill ffrroomm vviirruuss ssccaannnneerrss + +With all the easily recognizable forgeries eliminated, there is one category of +backscatter mail that remains, and that is notifications from virus scanner +software. Unfortunately, some virus scanning software doesn't know that viruses +forge sender addresses. To make matters worse, the software also doesn't know +how to report a mail delivery problem, so that we cannot use the above +techniques to recognize forgeries. + +Recognizing virus scanner mail is an error prone process, because there is a +lot of variation in report formats. The following is only a small example of +message header patterns. For a large collection of header and body patterns +that recognize virus notification email, see http://www.dkuug.dk/keld/virus/. + + /etc/postfix/header_checks: + /^Subject: *Your email contains VIRUSES/ DISCARD virus notification + /^Content-Disposition:.*VIRUS1_DETECTED_AND_REMOVED/ + DISCARD virus notification + /^Content-Disposition:.*VirusWarning.txt/ DISCARD virus notification + +A plea to virus or spam scanner operators: please do not make the problem worse +by sending return mail to forged sender addresses. You're only harassing +innocent people. + diff --git a/postfix/README_FILES/BASIC_CONFIGURATION_README b/postfix/README_FILES/BASIC_CONFIGURATION_README new file mode 100644 index 000000000..dd17c5282 --- /dev/null +++ b/postfix/README_FILES/BASIC_CONFIGURATION_README @@ -0,0 +1,482 @@ +PPoossttffiixx BBaassiicc CCoonnffiigguurraattiioonn + +------------------------------------------------------------------------------- + +IInnttrroodduuccttiioonn + +Postfix has several hundred configuration parameters that are controlled via +the main.cf file. Fortunately, all parameters have sensible default values. In +many cases, you need to configure only two or three parameters before you can +start to play with the mail system. Here's a quick introduction to the syntax: + + * Postfix configuration files + +The text below assumes that you already have Postfix installed on the system, +either by compiling the source code yourself (as described in the INSTALL file) +or by installing an already compiled version. + +This document covers basic Postfix configuration. Information about how to +configure Postfix for specific applications such as mailhub, firewall or dial- +up client can be found in the STANDARD_CONFIGURATION_README file. But don't go +there until you already have covered the material presented below. + +The first parameters of interest specify the machine's identity and role in the +network. + + * What domain name to use in outbound mail + + * What domains to receive mail for + + * What clients to relay mail from + + * What destinations to relay mail to + + * What delivery method: direct or indirect + +The default values for many other configuration parameters are derived from +just these. + +The next parameter of interest controls the amount of mail sent to the local +postmaster: + + * What trouble to report to the postmaster + +Be sure to set the following correctly if you're behind a proxy or network +address translator, and you are running a backup MX host for some other domain: + + * Proxy/NAT external network addresses + +Postfix daemon processes run in the background, and log problems and normal +activity to the syslog daemon. Here are a few things that you need to be aware +of: + + * What you need to know about Postfix logging + +If your machine has unusual security requirements you may want to run Postfix +daemon processes inside a chroot environment. + + * Running Postfix daemon processes chrooted + +If you run Postfix on a virtual network interface, or if your machine runs +other mailers on virtual interfaces, you'll have to look at the other +parameters listed here as well: + + * My own hostname + + * My own domain name + + * My own network addresses + +PPoossttffiixx ccoonnffiigguurraattiioonn ffiilleess + +By default, Postfix configuration files are in /etc/postfix. The two most +important files are main.cf and master.cf; these files must be owned by root. +Giving someone else write permission to main.cf or master.cf (or to their +parent directories) means giving root privileges to that person. + +In /etc/postfix/main.cf you will have to set up a minimal number of +configuration parameters. Postfix configuration parameters resemble shell +variables, with two important differences: the first one is that Postfix does +not know about quotes like the UNIX shell does. + +You specify a configuration parameter as: + + /etc/postfix/main.cf: + parameter = value + +and you use it by putting a "$" character in front of its name: + + /etc/postfix/main.cf: + other_parameter = $parameter + +You can use $parameter before it is given a value (that is the second main +difference with UNIX shell variables). The Postfix configuration language uses +lazy evaluation, and does not look at a parameter value until it is needed at +runtime. + +Postfix uses database files for access control, address rewriting and other +purposes. The DATABASE_README file gives an introduction to how Postfix works +with Berkeley DB, LDAP or SQL and other types. Here is a common example of how +Postfix invokes a database: + + /etc/postfix/main.cf: + virtual_alias_maps = hash:/etc/postfix/virtual + +Whenever you make a change to the main.cf or master.cf file, execute the +following command as root in order to refresh a running mail system: + + # postfix reload + +WWhhaatt ddoommaaiinn nnaammee ttoo uussee iinn oouuttbboouunndd mmaaiill + +The myorigin parameter specifies the domain that appears in mail that is posted +on this machine. The default is to use the local machine name, $myhostname, +which defaults to the name of the machine. Unless you are running a really +small site, you probably want to change that into $mydomain, which defaults to +the parent domain of the machine name. + +For the sake of consistency between sender and recipient addresses, myorigin +also specifies the default domain name that is appended to an unqualified +recipient address. + +Examples (specify only one of the following): + + /etc/postfix/main.cf: + myorigin = $myhostname (default: send mail as "user@$myhostname") + myorigin = $mydomain (probably desirable: "user@$mydomain") + +WWhhaatt ddoommaaiinnss ttoo rreecceeiivvee mmaaiill ffoorr + +The mydestination parameter specifies what domains this machine will deliver +locally, instead of forwarding to another machine. The default is to receive +mail for the machine itself. See the VIRTUAL_README file for how to configure +Postfix for hosted domains. + +You can specify zero or more domain names, "/file/name" patterns and/or "type: +table" lookup tables (such as hash:, btree:, nis:, ldap:, or mysql:), separated +by whitespace and/or commas. A "/file/name" pattern is replaced by its +contents; "type:table" requests that a table lookup is done and merely tests +for existence: the lookup result is ignored. + +IMPORTANT: If your machine is a mail server for its entire domain, you must +list $mydomain as well. + +Example 1: default setting. + + /etc/postfix/main.cf: + mydestination = $myhostname localhost.$mydomain localhost + +Example 2: domain-wide mail server. + + /etc/postfix/main.cf: + mydestination = $myhostname localhost.$mydomain localhost $mydomain + +Example 3: host with multiple DNS A records. + + /etc/postfix/main.cf: + mydestination = $myhostname localhost.$mydomain localhost + www.$mydomain ftp.$mydomain + +Caution: in order to avoid mail delivery loops, you must list all hostnames of +the machine, including $myhostname, and localhost.$mydomain. + +WWhhaatt cclliieennttss ttoo rreellaayy mmaaiill ffrroomm + +By default, Postfix will forward mail from clients in authorized network blocks +to any destination. Authorized networks are defined with the mynetworks +configuration parameter. The default is to authorize all clients in the IP +subnetworks that the local machine is attached to. + +IMPORTANT: If your machine is connected to a wide area network then your +default mynetworks setting may be too friendly. + +Examples (specify only one of the following): + + /etc/postfix/main.cf: + mynetworks_style = subnet (default: authorize subnetworks) + mynetworks_style = host (safe: authorize local machine only) + mynetworks = 127.0.0.0/8 (safe: authorize local machine only) + mynetworks = 127.0.0.0/8 168.100.189.2/32 (authorize local machine) + +You can specify the trusted networks in the main.cf file, or you can let +Postfix do the work for you. The default is to let Postfix do the work. The +result depends on the mynetworks_style parameter value. + + * Specify "mynetworks_style = host" when Postfix should forward mail from + only the local machine. + + * Specify "mynetworks_style = subnet" (the default) when Postfix should + forward mail from SMTP clients in the same IP subnetworks as the local + machine. On Linux, this works correctly only with interfaces specified with + the "ifconfig" command. + + * Specify "mynetworks_style = class" when Postfix should forward mail from + SMTP clients in the same IP class A/B/C networks as the local machine. + Don't do this with a dialup site - it would cause Postfix to "trust" your + entire provider's network. Instead, specify an explicit mynetworks list by + hand, as described below. + +Alternatively, you can specify the mynetworks list by hand, in which case +Postfix ignores the mynetworks_style setting. To specify the list of trusted +networks by hand, specify network blocks in CIDR (network/mask) notation, for +example: + + /etc/postfix/main.cf: + mynetworks = 168.100.189.0/28, 127.0.0.0/8 + +You can also specify the absolute pathname of a pattern file instead of listing +the patterns in the main.cf file. + +WWhhaatt ddeessttiinnaattiioonnss ttoo rreellaayy mmaaiill ttoo + +By default, Postfix will forward mail from strangers (clients outside +authorized networks) to authorized destinations only. Authorized destinations +are defined with the relay_domains configuration parameter. The default is to +authorize all domains (and subdomains) of the domains listed with the +mydestination parameter. + +Examples (specify only one of the following): + + /etc/postfix/main.cf: + relay_domains = $mydestination (default) + relay_domains = (safe: never forward mail from strangers) + relay_domains = $mydomain (forward mail to my domain and subdomains) + +WWhhaatt ddeelliivveerryy mmeetthhoodd:: ddiirreecctt oorr iinnddiirreecctt + +By default, Postfix tries to deliver mail directly to the Internet. Depending +on your local conditions this may not be possible or desirable. For example, +your system may be turned off outside office hours, it may be behind a +firewall, or it may be connected via a provider who does not allow direct mail +to the Internet. In those cases you need to configure Postfix to deliver mail +indirectly via a relay host. + +Examples (specify only one of the following): + + /etc/postfix/main.cf: + relayhost = (default: direct delivery to Internet) + relayhost = $mydomain (deliver via local mailhub) + relayhost = [mail.$mydomain] (deliver via local mailhub) + relayhost = [mail.isp.tld] (deliver via provider mailhub) + +The form enclosed with [] eliminates DNS MX lookups. Don't worry if you don't +know what that means. + +The STANDARD_CONFIGURATION_README file has more hints and tips for firewalled +and/or dial-up networks. + +WWhhaatt ttrroouubbllee ttoo rreeppoorrtt ttoo tthhee ppoossttmmaasstteerr + +You should set up a postmaster alias in the aliases(5) table that directs mail +to a human person. The postmaster address is required to exist, so that people +can report mail delivery problems. While you're updating the aliases(5) table, +be sure to direct mail for the super-user to a human person too. + + /etc/aliases: + postmaster: you + root: you + +Execute the command "newaliases" after changing the aliases file. Instead of / +etc/aliases, your alias file may be located elsewhere. Use the command +"postconf alias_maps" to find out. + +The Postfix system reports problems to the postmaster alias. You may not be +interested in all types of trouble reports, so this reporting mechanism is +configurable. The default is to report only serious problems (resource, +software) to postmaster: + +Default setting: + + /etc/postfix/main.cf: + notify_classes = resource, software + +The meaning of the classes is as follows: + + bounce + Inform the postmaster of undeliverable mail. Either send the postmaster + a copy of undeliverable mail that is returned to the sender, or send a + transcript of the SMTP session when Postfix rejected mail. For privacy + reasons, the postmaster copy of undeliverable mail is truncated after + the original message headers. This implies "2bounce" (see below). See + also the luser_relay feature. The notification is sent to the address + specified with the bounce_notice_recipient configuration parameter + (default: postmaster). + 2bounce + When Postfix is unable to return undeliverable mail to the sender, send + it to the postmaster instead (without truncating the message after the + primary headers). The notification is sent to the address specified + with the 2bounce_notice_recipient configuration parameter (default: + postmaster). + delay + Inform the postmaster of delayed mail. In this case, the postmaster + receives message headers only. The notification is sent to the address + specified with the delay_notice_recipient configuration parameter + (default: postmaster). + policy + Inform the postmaster of client requests that were rejected because of + (UCE) policy restrictions. The postmaster receives a transcript of the + SMTP session. The notification is sent to the address specified with + the error_notice_recipient configuration parameter (default: + postmaster). + protocol + Inform the postmaster of protocol errors (client or server side) or + attempts by a client to execute unimplemented commands. The postmaster + receives a transcript of the SMTP session. The notification is sent to + the address specified with the error_notice_recipient configuration + parameter (default: postmaster). + resource + Inform the postmaster of mail not delivered due to resource problems + (for example, queue file write errors). The notification is sent to the + address specified with the error_notice_recipient configuration + parameter (default: postmaster). + software + Inform the postmaster of mail not delivered due to software problems. + The notification is sent to the address specified with the + error_notice_recipient configuration parameter (default: postmaster). + +PPrrooxxyy//NNAATT eexxtteerrnnaall nneettwwoorrkk aaddddrreesssseess + +Some mail servers are connected to the Internet via a network address +translator (NAT) or proxy. This means that systems on the Internet connect to +the address of the NAT or proxy, instead of connecting to the network address +of the mail server. The NAT or proxy forwards the connection to the network +address of the mail server, but Postfix does not know this. + +If you run a Postfix server behind a proxy or NAT, you need to configure the +proxy_interfaces parameter and specify all the external proxy or NAT addresses +that Postfix receives mail on. You may specify symbolic hostnames instead of +network addresses. + +IMPORTANT: You must specify your proxy/NAT external addresses when your system +is a backup MX host for other domains, otherwise mail delivery loops will +happen when the primary MX host is down. + +Example: host behind NAT box running a backup MX host. + + /etc/postfix/main.cf: + proxy_interfaces = 1.2.3.4 (the proxy/NAT external network address) + +WWhhaatt yyoouu nneeeedd ttoo kknnooww aabboouutt PPoossttffiixx llooggggiinngg + +Postfix daemon processes run in the background, and log problems and normal +activity to the syslog daemon. The syslogd process sorts events by class and +severity, and appends them to logfiles. The logging classes, levels and logfile +names are usually specified in /etc/syslog.conf. At the very least you need +something like: + + /etc/syslog.conf: + mail.err /dev/console + mail.debug /var/log/maillog + +After changing the syslog.conf file, send a "HUP" signal to the syslogd +process. + +IMPORTANT: many syslogd implementations will not create files. You must create +files before (re)starting syslogd. + +IMPORTANT: on Linux you need to put a "-" character before the pathname, e.g., +-/var/log/maillog, otherwise the syslogd process will use more system resources +than Postfix. + +Hopefully, the number of problems will be small, but it is a good idea to run +every night before the syslog files are rotated: + + # postfix check + # egrep '(reject|warning|error|fatal|panic):' /some/log/file + + * The first line (postfix check) causes Postfix to report file permission/ + ownership discrepancies. + + * The second line looks for problem reports from the mail software, and + reports how effective the relay and junk mail access blocks are. This may + produce a lot of output. You will want to apply some postprocessing to + eliminate uninteresting information. + +The DEBUG_README document describes the meaning of the "warning" etc. labels in +Postfix logging. + +RRuunnnniinngg PPoossttffiixx ddaaeemmoonn pprroocceesssseess cchhrrooootteedd + +Postfix daemon processes can be configured (via the master.cf file) to run in a +chroot jail. The processes run at a fixed low privilege and with file system +access limited to the Postfix queue directories (/var/spool/postfix). This +provides a significant barrier against intrusion. The barrier is not +impenetrable (chroot limits file system access only), but every little bit +helps. + +With the exception of Postfix daemons that deliver mail locally and/or that +execute non-Postfix commands, every Postfix daemon can run chrooted. + +Sites with high security requirements should consider to chroot all daemons +that talk to the network: the smtp(8) and smtpd(8) processes, and perhaps also +the lmtp(8) client. The author's own porcupine.org mail server runs all daemons +chrooted that can be chrooted. + +The default /etc/postfix/master.cf file specifies that no Postfix daemon runs +chrooted. In order to enable chroot operation, edit the file /etc/postfix/ +master.cf, and follow instructions in the file. When you're finished, execute +"postfix reload" to make the change effective. + +Note that a chrooted daemon resolves all filenames relative to the Postfix +queue directory (/var/spool/postfix). For successful use of a chroot jail, most +UNIX systems require you to bring in some files or device nodes. The examples/ +chroot-setup directory in the source code distribution has a collection of +scripts that help you set up Postfix chroot environments on different operating +systems. + +Additionally, you almost certainly need to configure syslogd so that it listens +on a socket inside the Postfix queue directory. Examples of syslogd command +line options that achieve this for specific systems: + +FreeBSD: syslogd -l /var/spool/postfix/var/run/log + +Linux, OpenBSD: syslogd -a /var/spool/postfix/dev/log + +MMyy oowwnn hhoossttnnaammee + +The myhostname parameter specifies the fully-qualified domain name of the +machine running the Postfix system. $myhostname appears as the default value in +many other Postfix configuration parameters. + +By default, myhostname is set to the local machine name. If your local machine +name is not in fully-qualified domain name form, or if you run Postfix on a +virtual interface, you will have to specify the fully-qualified domain name +that the mail system should use. + +Alternatively, if you specify mydomain in main.cf, then Postfix will use its +value to generate a fully-qualified default value for the myhostname parameter. + +Examples (specify only one of the following): + + /etc/postfix/main.cf: + myhostname = host.local.domain (machine name is not FQDN) + myhostname = host.virtual.domain (virtual interface) + myhostname = virtual.domain (virtual interface) + +MMyy oowwnn ddoommaaiinn nnaammee + +The mydomain parameter specifies the parent domain of $myhostname. By default, +it is derived from $myhostname by stripping off the first part (unless the +result would be a top-level domain). + +Conversely, if you specify mydomain in main.cf, then Postfix will use its value +to generate a fully-qualified default value for the myhostname parameter. + +Examples (specify only one of the following): + + /etc/postfix/main.cf: + mydomain = local.domain + mydomain = virtual.domain (virtual interface) + +MMyy oowwnn nneettwwoorrkk aaddddrreesssseess + +The inet_interfaces parameter specifies all network interface addresses that +the Postfix system should listen on; mail addressed to "user@[network address]" +will be delivered locally, as if it is addressed to a domain listed in +$mydestination. + +You can override the inet_interfaces setting in the Postfix master.cf file by +prepending an IP address to a server name. + +The default is to listen on all active interfaces. If you run mailers on +virtual interfaces, you will have to specify what interfaces to listen on. + +IMPORTANT: If you run MTAs on virtual interfaces you must specify explicit +inet_interfaces values for the MTA that receives mail for the machine itself: +this MTA should never listen on the virtual interfaces or you would have a +mailer loop when a virtual MTA is down. + +Example: default setting. + + /etc/postfix/main.cf: + inet_interfaces = all + +Example: host running one or more virtual mailers. For each Postfix instance, +specify only one of the following. + + /etc/postfix/main.cf: + inet_interfaces = virtual.host.tld (virtual Postfix) + inet_interfaces = $myhostname localhost... (non-virtual Postfix) + +Note: you need to stop and start Postfix after changing this parameter. + diff --git a/postfix/README_FILES/BUILTIN_FILTER_README b/postfix/README_FILES/BUILTIN_FILTER_README new file mode 100644 index 000000000..662a2d3ea --- /dev/null +++ b/postfix/README_FILES/BUILTIN_FILTER_README @@ -0,0 +1,271 @@ + PPoossttffiixx BBuuiilltt--iinn CCoonntteenntt IInnssppeeccttiioonn + +------------------------------------------------------------------------------- + +BBuuiilltt--iinn ccoonntteenntt iinnssppeeccttiioonn iinnttrroodduuccttiioonn + +Postfix supports a built-in filter mechanism that examines message header and +message body content, one line at a time, before it is stored in the Postfix +queue. The filter is usually implemented with POSIX or PCRE regular +expressions, as described in the header_checks(5) manual page. + +The original purpose of the built-in filter is to stop an outbreak of specific +email worms or viruses, and it does this job well. The filter has also helped +to block bounced junk email, bounced email from worms or viruses, and +notifications from virus detection systems. Information about this secondary +application is given in the BACKSCATTER_README document. + +Because the built-in filter is optimized for stopping specific worms and virus +outbreaks, it has limitations that make it NOT suitable for general junk email +and virus detection. For that, you should use one of the external content +inspection methods that are described in the FILTER_README and +SMTPD_PROXY_README documents. + +The following diagram gives an over-all picture of how Postfix built-in content +inspection works: + + Postmaster + notifications + + | + v + + Network or -> BBuuiilltt--iinn -> Postfix -> Delivery -> Network or + local users ffiilltteerr queue agents local mailbox + + ^ | + | v + + Undeliverable mail + Forwarded mail + +The picture makes clear that the filter works while Postfix is receiving new +mail. This means that Postfix can reject mail from the network without having +to return undeliverable mail to the originator address (which is often spoofed +anyway). However, this ability comes at a price: if mail inspection takes too +much time, then the remote client will time out, and the client may send the +same message repeatedly. + +Topics covered by this document: + + * What mail is subjected to header/body checks + * Limitations of Postfix header/body checks + * Preventing daily mail status reports from being blocked + * Configuring header/body checks for mail from outside users only + * Configuring header/body checks for mail to some domains only + +WWhhaatt mmaaiill iiss ssuubbjjeecctteedd ttoo hheeaaddeerr//bbooddyy cchheecckkss + +Postfix header/body checks are implemented by the cleanup(8) server before it +injects mail into the incoming queue. The diagram below zooms in on the cleanup +(8) server, and shows that this server handles mail from many different +sources. In order to keep the diagram readable, the sources of postmaster +notifications are not shown, because they can be produced by many Postfix +daemon processes. + + bounce(8) + (undeliverable) + + ssmmttppdd((88)) | + ((nneettwwoorrkk)) \ v + + qqmmqqppdd((88)) -\ cleanup(8) -> incoming + ((nneettwwoorrkk)) -/ queue + + ppiicckkuupp((88)) / ^ + ((llooccaall)) | + + local(8) + (forwarded) + +For efficiency reasons, only mail that enters from outside of Postfix is +inspected with header/body checks. It would be inefficient to filter already +filtered mail again, and it would be undesirable to block postmaster +notifications. The table below summarizes what mail is and is not subject to +header/body checks. + + _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ + |MMeessssaaggee ttyyppee |SSoouurrccee |HHeeaaddeerr//bbooddyy cchheecckkss??| + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |Undeliverable mail|bounce(8)|No | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |Network mail |smtpd(8) |Configurable | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |Network mail |qmqpd(8) |Configurable | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |Local submission |pickup(8)|Configurable | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |Local forwarding |local(8) |No | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |Postmaster notice |many |No | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + +How does Postfix decide what mail needs to be filtered? It would be clumsy to +make the decision in the cleanup(8) server, as this program receives mail from +so many different sources. Instead, header/body checks are requested by the +source. Examples of how to turn off header/body checks for mail received with +smtpd(8), qmqpd(8) or pickup(8) are given below under "Configuring header/body +checks for mail from outside users only" and "Configuring header/body checks +for mail to some domains only". + +LLiimmiittaattiioonnss ooff PPoossttffiixx hheeaaddeerr//bbooddyy cchheecckkss + + * Header/body checks do not decode message headers or message body content. + For example, if text in the message body is BASE64 encoded (RFC 2045) then + your regular expressions will have to match the BASE64 encoded form. + Likewise, message headers with encoded non-ASCII characters (RFC 2047) need + to be matched in their encoded form. + + * Header/body checks cannot filter on a combination of message headers or + body lines. Header/body checks examine content one message header at a + time, or one message body line at a time, and cannot carry a decision over + to the next message header or body line. + + * Header/body checks cannot depend on the recipient of a message. + + o One message can have multiple recipients, and all recipients of a + message receive the same treatment. Workarounds have been proposed that + involve selectively deferring some recipients of multi-recipient mail, + but that results in poor SMTP performance and does not work for non- + SMTP mail. + + o Some sources of mail send the headers and content ahead of the + recipient information. It would be inefficient to buffer up an entire + message before deciding if it needs to be filtered, and it would be + clumsy to filter mail and to buffer up all the actions until it is + known whether those actions need to be executed. + + * Despite warnings, some people try to use the built-in filter feature for + general junk email and/or virus blocking, using hundreds or even thousands + of regular expressions. This can result in catastrophic performance + failure. The symptoms are as follows: + + o The cleanup(8) processes use up all available CPU time in order to + process the regular expressions, and/or they use up all available + memory so that the system begins to swap. This slows down all incoming + mail deliveries. + + o As Postfix needs more and more time to receive an email message, the + number of simultaneous SMTP sessions increases to the point that the + SMTP server process limit is reached. + + o While all SMTP server processes are waiting for the cleanup(8) servers + to finish, new SMTP clients have to wait until an SMTP server process + becomes available. This causes mail deliveries to time out before they + have even begun. + + The remedy for this type of performance problem is simple: don't use + header/body checks for general junk email and/or virus blocking, and don't + filter mail before it is queued. When performance is a concern, use an + external content filter that runs after mail is queued, as described in the + FILTER_README document. + +PPrreevveennttiinngg ddaaiillyy mmaaiill ssttaattuuss rreeppoorrttss ffrroomm bbeeiinngg bblloocckkeedd + +The following is quoted from Jim Seymour's Pflogsumm FAQ at http:// +jimsun.linxnet.com/downloads/pflogsumm-faq.txt. Pflogsumm is a program that +analyzes Postfix logs, including the logging from rejected mail. If these logs +contain text that was rejected by Postfix body_checks patterns, then the +logging is also likely to be rejected by those same body_checks patterns. This +problem does not exist with header_checks patterns, because those are not +applied to the text that is part of the mail status report. + + You configure Postfix to do body checks, Postfix does its thing, Pflogsumm + reports it and Postfix catches the same string in the Pflogsumm report. + There are several solutions to this. + + Wolfgang Zeikat contributed this: + + #!/usr/bin/perl + use MIME::Lite; + + ### Create a new message: + $msg = MIME::Lite->new( + From => 'your@send.er', + To => 'your@recipie.nt', + # Cc => 'some@other.com, some@more.com', + Subject => 'pflogsumm', + Date => `date`, + Type => 'text/plain', + Encoding => 'base64', + Path => '/tmp/pflogg', + ); + + $msg->send; + + Where "/tmp/pflogg" is the output of Pflogsumm. This puts Pflogsumm's + output in a base64 MIME attachment. + +Note by Wietse: if you run this on a machine that is accessible by untrusted +users, it is safer to store the Pflogsumm report in a directory that is not +world writable. + + In a follow-up to a thread in the postfix-users mailing list, Ralf + Hildebrandt noted: + + "mpack does the same thing." + +And it does. Which tool one should use is a matter of preference. + +Other solutions involve additional body_checks rules that make exceptions for +daily mail status reports, but this is not recommended. Such rules slow down +all mail and complicate Postfix maintenance. + +CCoonnffiigguurriinngg hheeaaddeerr//bbooddyy cchheecckkss ffoorr mmaaiill ffrroomm oouuttssiiddee uusseerrss oonnllyy + +The following information applies to Postfix 2.1. Earlier Postfix versions do +not support the receive_override_options feature. + +The easiest approach is to configure ONE Postfix instance with multiple SMTP +server IP addresses in master.cf: + + * Two SMTP server IP addresses for mail from inside users only, with header/ + body filtering turned off, and a local mail pickup service with header/body + filtering turned off. + + /etc/postfix.master.cf: + # ================================================================== + # service type private unpriv chroot wakeup maxproc command + # (yes) (yes) (yes) (never) (100) + # ================================================================== + 1.2.3.4:smtp inet n - n - - smtpd + -o receive_override_options=no_header_body_checks + 127.0.0.1:smtp inet n - n - - smtpd + -o receive_override_options=no_header_body_checks + pickup fifo n - n 60 1 pickup + -o receive_override_options=no_header_body_checks + + * One SMTP server address for mail from outside users with header/body + filtering turned on via main.cf. + + /etc/postfix.master.cf: + # ================================================================= + # service type private unpriv chroot wakeup maxproc command + # (yes) (yes) (yes) (never) (100) + # ================================================================= + 1.2.3.5:smtp inet n - n - - smtpd + +CCoonnffiigguurriinngg hheeaaddeerr//bbooddyy cchheecckkss ffoorr mmaaiill ttoo ssoommee ddoommaaiinnss oonnllyy + +The following information applies to Postfix 2.1. Earlier Postfix versions do +not support the receive_override_options feature. + +If you are MX service provider and want to apply disable head/body checks for +some domains, you can configure ONE Postfix instance with multiple SMTP server +IP addresses in master.cf. Each address provides a different service. + + /etc/postfix.master.cf: + # ================================================================= + # service type private unpriv chroot wakeup maxproc command + # (yes) (yes) (yes) (never) (100) + # ================================================================= + # SMTP service for domains with header/body checks turned on. + 1.2.3.4:smtp inet n - n - - smtpd + + # SMTP service for domains with header/body checks turned off. + 1.2.3.5:smtp inet n - n - - smtpd + -o receive_override_options=no_header_body_checks + +Once this is set up you can configure MX records in the DNS that route each +domain to the proper SMTP server instance. + diff --git a/postfix/README_FILES/CONTENT_INSPECTION_README b/postfix/README_FILES/CONTENT_INSPECTION_README new file mode 100644 index 000000000..aa7b64452 --- /dev/null +++ b/postfix/README_FILES/CONTENT_INSPECTION_README @@ -0,0 +1,48 @@ +PPoossttffiixx CCoonntteenntt IInnssppeeccttiioonn + +------------------------------------------------------------------------------- +Postfix supports three content inspection methods, ranging from light-weight +one-line-at-a-time scanning before mail is queued, to heavy duty machinery that +does sophisticated content analysis after mail is queued. Each approach serves +a different purpose. + +bbuuiilltt--iinn,, lliigghhtt--wweeiigghhtt,, rreeaall--ttiimmee + This method inspects mail BEFORE it is stored in the queue, and uses + Postfix's built-in message header and message body inspection. Although the + main purpose is to stop a specific flood of mail from worms or viruses, it + is also useful to block a flood of bounced junk email and email + notifications from virus detection systems. The built-in regular + expressions are not meant to implement general SPAM and virus detection. + For that, you should use one of the content inspection methods described + below. Details are described in the BUILTIN_FILTER_README and + BACKSCATTER_README documents. + +eexxtteerrnnaall,, hheeaavvyy--wweeiigghhtt,, nnoott rreeaall ttiimmee + This method inspects mail AFTER it is stored in the queue, and uses + standard protocols such as SMTP or "pipe to command and wait for exit + status". After-queue inspection allows you to use content filters of + arbitrary complexity without causing timeouts while receiving mail, and + without running out of memory resources under a peak load. Details of this + approach are in the FILTER_README document. + +eexxtteerrnnaall,, mmeeddiiuumm--wweeiigghhtt,, rreeaall--ttiimmee + This method inspects mail BEFORE it is stored in the queue, and uses the + SMTP protocol. Although this approach appears to be the more attractive + one, it really combines the worst of the other two. Because mail is + inspected before it is queued, content inspection software must finish in a + limited amount of time, and must run in a limited amount of memory. If + content inspection needs too much time then incoming mail deliveries will + time out, and if content inspection needs too much memory then software + will crash under a peak load. Before-queue inspection limits the peak load + that your system can handle, and limits the sophistication of the content + filter that you can use. Details are in the SMTPD_PROXY_README document. + This approach is available only with Postfix version 2.1 and later. + +The more sophisticated content filtering software is not built into Postfix for +good reasons: writing an MTA requires different skills than writing a SPAM or +virus killer. Postfix encourages the use of external filters and standard +protocols because this allows you to choose the best MTA and the best content +inspection software for your purpose. Information about external content +inspection software can be found on the Postfix website at http:// +www.postfix.org/, and on the postfix-users@postfix.org mailing list. + diff --git a/postfix/README_FILES/CYRUS_README b/postfix/README_FILES/CYRUS_README new file mode 100644 index 000000000..a00df0bb5 --- /dev/null +++ b/postfix/README_FILES/CYRUS_README @@ -0,0 +1,5 @@ +PPoossttffiixx CCyyrruuss HHoowwttoo + +------------------------------------------------------------------------------- +This document will be made available via http://www.postfix.org/. + diff --git a/postfix/README_FILES/DATABASE_README b/postfix/README_FILES/DATABASE_README new file mode 100644 index 000000000..3c080e5d3 --- /dev/null +++ b/postfix/README_FILES/DATABASE_README @@ -0,0 +1,241 @@ +PPoossttffiixx LLooookkuupp TTaabbllee OOvveerrvviieeww + +------------------------------------------------------------------------------- + +OOvveerrvviieeww + +This document covers the following topics: + + * The Postfix lookup table model + * Postfix lists versus tables + * Preparing Postfix for LDAP or SQL lookups + * Maintaining Postfix lookup table files + * Updating Berkeley DB files safely + * Postfix lookup table types + +TThhee PPoossttffiixx llooookkuupp ttaabbllee mmooddeell + +Postfix uses lookup tables to store and look up information for access control, +address rewriting and even for content filtering. All Postfix lookup tables are +specified as "type:table", where "type" is one of the database types described +under "Postfix lookup table types" at the end of this document, and where +"table" is the lookup table name. The Postfix documentation uses the terms +"database" and "lookup table" for the same thing. + +Examples of lookup tables that appear often in the Postfix documentation: + + /etc/postfix/main.cf: + alias_maps = hash:/etc/postfix/aliases (local aliasing) + header_checks = regexp:/etc/postfix/header_checks (content filtering) + transport_maps = hash:/etc/postfix/transport (routing table) + virtual_alias_maps = hash:/etc/postfix/virtual (address rewriting) + +All Postfix lookup tables store information as (key, value) pairs. This +interface may seem simplistic at first, but it turns out to be very powerful. +The (key, value) query interface completely hides the complexities of LDAP or +SQL from Postfix. This is a good example of connecting complex systems with +simple interfaces. + +Benefits of the Postfix (key, value) query interface: + + * You can implement Postfix lookup tables first with local Berkeley DB files + and then switch to LDAP or MySQL without any impact on the Postfix + configuration itself, as described under "Preparing Postfix for LDAP or SQL + lookups" below. + * You can use Berkeley DB files with fixed lookup strings for simple address + rewriting operations and you can use regular expression tables for the more + complicated work. + +PPoossttffiixx lliissttss vveerrssuuss ttaabblleess + +Most Postfix lookup tables are used to look up information. Examples are +address rewriting (the lookup string is the old address, and the result is the +new address) or access control (the lookup string is the client, sender or +recipient, and the result is an action such as "reject"). + +With some tables, however, Postfix needs to know only if the lookup key exists. +The lookup result itself is not used. Examples are the local_recipient_maps +that determine what local recipients Postfix accepts in mail from the network, +the mydestination parameter that specifies what domains Postfix delivers +locally, or the mynetworks parameter that specifies the IP addresses of trusted +clients or client networks. Technically, these are lists, not tables. Despite +the difference, Postfix lists are described here because they use the same +underlying infrastructure as Postfix lookup tables. + +PPrreeppaarriinngg PPoossttffiixx ffoorr LLDDAAPP oorr SSQQLL llooookkuuppss + +LDAP and SQL are complex systems. Trying to set up both Postfix and LDAP or SQL +at the same time is definitely not a good idea. You can save yourself a lot of +time by implementing Postfix first with local files such as Berkeley DB. Local +files have few surprises, and are easy to debug with the postmap(1) command: + + % ppoossttmmaapp --qq iinnffoo@@eexxaammppllee..ccoomm hhaasshh:://eettcc//ppoossttffiixx//vviirrttuuaall + +Once you have local files working properly you can follow the instructions in +ldap_table(5), mysql_table(5) or pgsql_table(5) and replace local file lookups +with LDAP or SQL lookups. When you do this, you should use the postmap(1) +command again, to verify that database lookups still produce the exact same +results as local file lookup: + + % ppoossttmmaapp --qq iinnffoo@@eexxaammppllee..ccoomm llddaapp:://eettcc//ppoossttffiixx//vviirrttuuaall..ccff + +Be sure to exercise all the partial address or parent domain queries that are +documented under "table search order" in the relevant manual page: access(5), +canonical(5), virtual(5), transport(5), or under the relevant configuration +parameter: mynetworks, relay_domains, parent_domain_matches_subdomains. + +MMaaiinnttaaiinniinngg PPoossttffiixx llooookkuupp ttaabbllee ffiilleess + +When you make changes to a database while the mail system is running, it would +be desirable if Postfix avoids reading information while that information is +being changed. It would also be nice if you can change a database without +having to execute "postfix reload", in order to force Postfix to use the new +information. Each time you do "postfix reload" Postfix loses a lot of +performance. + + * If you change a network database such as LDAP, NIS or SQL, there is no need + to execute "postfix reload". The LDAP, NIS or SQL server takes care of + read/write access conflicts and gives the new data to Postfix once that + data is available. + + * If you change a regexp: or pcre: file then Postfix may or may not pick up + the file changes immediately. This is because a Postfix process reads the + entire file into memory once and never examines the file again. + + o If the file is used by a short-running process such as smtpd(8), + cleanup(8) or local(8), there is no need to execute "postfix reload" + after making a change. + + o If the file is being used by a long-running process such as trivial- + rewrite(8) on a busy server it may be necessary to execute "postfix + reload". + + * If you change a local file based database such as DBM or Berkeley DB, there + is no need to execute "postfix reload". Postfix uses file locking to avoid + read/write access conflicts, and whenever a Postfix daemon process notices + that a file has changed it will terminate before handling the next client + request, so that a new process can initialize with the new database. + +UUppddaattiinngg BBeerrkkeelleeyy DDBB ffiilleess ssaaffeellyy + +Although Postfix uses file locking to avoid access conflicts while updating +Berkeley DB or other local database files, you still have a problem when the +update fails because the disk is full or because something else happens. This +is because commands such as postmap(1) or postalias(1) overwrite existing +files. If the update fails in the middle then you have no usable database, and +Postfix will stop working. + +With multi-file databases such as DBM, there is no simple solution. With +Berkeley DB and other "one file" databases, it is possible to add some extra +robustness by using "mv" to REPLACE an existing database file instead of +overwriting it: + + # ppoossttmmaapp aacccceessss..iinn &&&& mmvv aacccceessss..iinn..ddbb aacccceessss..ddbb + +This converts the input file "access.in" into the output file "access.in.db", +and replaces the file "access.db" only when the postmap(1) command was +successful. Of course typing such commands becomes boring quickly, and this is +why people use "make" instead, as shown below. User input is shown in bold +font. + + # ccaatt MMaakkeeffiillee + all: aliases.db access.db virtual.db ...etcetera... + + # Note 1: commands are specified after a TAB character. + # Note 2: use postalias(1) for local aliases, postmap(1) for the rest. + aliases.db: aliases.in + postalias aliases.in + mv aliases.in.db aliases.db + + access.db: access.in + postmap access.in + mv access.in.db access.db + + virtual.db: virtual.in + postmap virtual.in + mv virtual.in.db virtual.db + + ...etcetera... + # vvii aacccceessss..iinn + ...editing session not shown... + # mmaakkee + postmap access.in + mv access.in.db access.db + # + +The "make" command updates only the files that have changed. In case of error, +the "make" command will stop and will not invoke the "mv" command, so that +Postfix will keep using the existing database file as if nothing happened. + +PPoossttffiixx llooookkuupp ttaabbllee ttyyppeess + +To find out what database types your Postfix system supports, use the "postconf +-m" command. Here is a list of database types that are often supported: + + bbttrreeee + A sorted, balanced tree structure. This is available only on systems + with support for Berkeley DB databases. Database files are created with + the postmap(1) or postalias(1) command. The lookup table name as used + in "btree:table" is the database file name without the ".db" suffix. + cciiddrr + A table that associates values with Classless Inter-Domain Routing + (CIDR) patterns. The table format is described in cidr_table(5). + ddbbmm + An indexed file type based on hashing. This is available only on + systems with support for DBM databases. Database files are created with + the postmap(1) or postalias(1) command. The lookup table name as used + in "dbm:table" is the database file name without the ".dir" or ".pag" + suffix. + eennvviirroonn + The UNIX process environment array. The lookup key is the variable + name. The lookup table name in "environ:table" is ignored. + hhaasshh + An indexed file type based on hashing. This is available only on + systems with support for Berkeley DB databases. Database files are + created with the postmap(1) or postalias(1) command. The database name + as used in "hash:table" is the database file name without the ".db" + suffix. + llddaapp (read-only) + Perform lookups using the LDAP protocol. Configuration details are + given in the ldap_table(5). + mmyyssqqll (read-only) + Perform MySQL database lookups. Configuration details are given in + mysql_table(5). + ppccrree (read-only) + A lookup table based on Perl Compatible Regular Expressions. The file + format is described in pcre_table(5). The lookup table name as used in + "pcre:table" is the name of the regular expression file. + ppggssqqll (read-only) + Perform PostgreSQL database lookups. Configuration details are given in + pgsql_table(5). + pprrooxxyy (read-only) + Access information via the Postfix proxymap(8) service. The lookup + table name syntax is "proxy:type:table". + rreeggeexxpp (read-only) + A lookup table based on regular expressions. The file format is + described in regexp_table(5). The lookup table name as used in "regexp: + table" is the name of the regular expression file. + ssttaattiicc (read-only) + Always returns its lookup table name as lookup result. For example, the + lookup table "static:foobar" always returns the string "foobar" as + lookup result. + ttccpp + Access information through a TCP/IP server. The protocol is described + in tcp_table(5). The lookup table name is "tcp:host:port" where "host" + specifies a symbolic hostname or a numeric IP address, and "port" + specifies a symbolic service name or a numeric port number. This + protocol is not available in Postfix version 2.1. + uunniixx (read-only) + A limited way to query the UNIX authentication database. The following + tables are implemented: + uunniixx::ppaasssswwdd..bbyynnaammee + The table is the UNIX password database. The key is a login name. + The result is a password file entry in passwd(5) format. + uunniixx::ggrroouupp..bbyynnaammee + The table is the UNIX group database. The key is a group name. The + result is a group file entry in group(5) format. + +Other lookup table types may be available depending on how Postfix was built. +With some Postfix distributions the list is dynamically extensible as support +for lookup tables is dynamically linked into Postfix. + diff --git a/postfix/README_FILES/DB_README b/postfix/README_FILES/DB_README index 5819070ea..2f2638fd3 100644 --- a/postfix/README_FILES/DB_README +++ b/postfix/README_FILES/DB_README @@ -1,112 +1,148 @@ -Purpose of this document -======================== +PPoossttffiixx BBeerrkkeelleeyy DDBB HHoowwttoo -This document describes +------------------------------------------------------------------------------- -1 - How to build Postfix with third-party Berkeley DB from -www.sleepycat.com, or how to choose a specific Berkeley DB version -when your system provides multiple implementations. +IInnttrroodduuccttiioonn -2 - How to tweak performance. +Postfix uses databases of various kinds to store and look up information. +Postfix databases are specified as "type:name". Berkeley DB implements the +Postfix database type "hash" and "btree". The name of a Postfix Berkeley DB +database is the name of the database file without the ".db" suffix. Berkeley DB +databases are maintained with the postmap(1) command. -Building Postfix with Sleepycat Berkeley DB -=========================================== +Note: Berkeley DB version 4 is not supported by Postfix versions before 2.0. -Many commercial UNIXes ship without Berkeley DB support. Examples -are Solaris, HP-UX, IRIX, UNIXWARE. In order to build Postfix with -Berkeley DB support you need to download and install the source -code from www.sleepycat.com. +This document describes: -To build Postfix after you installed the Berkeley DB from Sleepycat, -use something like: + 1. How to build Postfix on systems without Berkeley DB library. + + 2. How to build Postfix on BSD or Linux systems with multiple Berkeley DB + versions. + + 3. How to tweak performance. + + 4. Missing pthread library trouble. + +BBuuiillddiinngg PPoossttffiixx oonn ssyysstteemmss wwiitthhoouutt BBeerrkkeelleeyy DDBB + +Many commercial UNIXes ship without Berkeley DB support. Examples are Solaris, +HP-UX, IRIX, UNIXWARE. In order to build Postfix with Berkeley DB support you +need to download and install the source code from http://www.sleepycat.com/ + +Warning: some Linux system libraries use Berkeley DB, as do some third-party +libraries such as SASL. If you compile Postfix with a different Berkeley DB +implementation, then every Postfix program will dump core because either the +system library, SASL library, or Postfix itself ends up using the wrong +version. + +The more recent Berkeley DB versions have a compile-time switch, "--with- +uniquename", which renames the symbols so that multiple versions of Berkeley DB +can co-exist in the same application. Although wasteful, this may be the only +way to keep things from falling apart. + +To build Postfix after you installed the Berkeley DB from http:// +www.sleepycat.com/, use something like: % make tidy % make makefiles CCARGS="-DHAS_DB -I/usr/local/BerkeleyDB.3.1/include" \ - AUXLIBS="-L/usr/local/BerkeleyDB.3.1/lib -ldb" + AUXLIBS="-L/usr/local/BerkeleyDB.3.1/lib -ldb" % make -The exact pathnames depend on the DB version that you installed. -For example, Berkeley DB version 2 installs in /usr/local/BerkeleyDB. +The exact pathnames depend on the DB version that you installed. For example, +Berkeley DB version 2 installs in /usr/local/BerkeleyDB. -Warning: the file format produced by Berkeley DB version 1 is not -compatible with that of versions 2 and 3 (versions 2 and 3 have -the same format). If you switch between DB versions, then you may -have to rebuild all your Postfix DB files. +Warning: the file format produced by Berkeley DB version 1 is not compatible +with that of versions 2 and 3 (versions 2 and 3 have the same format). If you +switch between DB versions, then you may have to rebuild all your Postfix DB +files. -Warning: if you use Berkeley DB version 2 or later, do not enable -DB 1.85 compatibility mode. Doing so would break fcntl file locking. +Warning: if you use Berkeley DB version 2 or later, do not enable DB 1.85 +compatibility mode. Doing so would break fcntl file locking. -Warning: if you use PERL to manipulate Postfix .db files, then you -need to use the same Berkeley DB version in PERL as in Postfix. +Warning: if you use Perl to manipulate Postfix's Berkeley DB files, then you +need to use the same Berkeley DB version in Perl as in Postfix. -Building Postfix on BSD systems with a specific Berkeley DB version -=================================================================== +BBuuiillddiinngg PPoossttffiixx oonn BBSSDD ssyysstteemmss wwiitthh mmuullttiippllee BBeerrkkeelleeyy DDBB vveerrssiioonnss -Some BSD systems ship with multiple Berkeley DB implementations. -Normally, Postfix builds with the default DB version that ships -with the system. +Some BSD systems ship with multiple Berkeley DB implementations. Normally, +Postfix builds with the default DB version that ships with the system. -To build Postfix on BSD systems with a specific DB version, use a -variant of the following commands: +To build Postfix on BSD systems with a specific DB version, use a variant of +the following commands: % make tidy - % make makefiles CCARGS=-I/usr/include/db2 AUXLIBS=-ldb2 + % make makefiles CCARGS=-I/usr/include/db3 AUXLIBS=-ldb3 % make -Warning: the file format produced by Berkeley DB version 1 is not -compatible with that of versions 2 and 3 (versions 2 and 3 have -the same format). If you switch between DB versions, then you may -have to rebuild all your Postfix DB files. +Warning: the file format produced by Berkeley DB version 1 is not compatible +with that of versions 2 and 3 (versions 2 and 3 have the same format). If you +switch between DB versions, then you may have to rebuild all your Postfix DB +files. + +Warning: if you use Berkeley DB version 2 or later, do not enable DB 1.85 +compatibility mode. Doing so would break fcntl file locking. + +Warning: if you use Perl to manipulate Postfix's Berkeley DB files, then you +need to use the same Berkeley DB version in Perl as in Postfix. + +BBuuiillddiinngg PPoossttffiixx oonn LLiinnuuxx ssyysstteemmss wwiitthh mmuullttiippllee BBeerrkkeelleeyy DDBB vveerrssiioonnss + +Some Linux systems ship with multiple Berkeley DB implementations. Normally, +Postfix builds with the default DB version that ships with the system. + +Warning: some Linux system libraries use Berkeley DB. If you compile Postfix +with a non-default Berkeley DB implementation, then every Postfix program will +dump core because either the system library or Postfix itself ends up using the +wrong version. + +On Linux, you need to edit the makedefs script in order to specify a non- +default DB library. The reason is that the location of the default db.h include +file changes randomly between vendors and between versions, so that Postfix has +to choose the file for you. + +Warning: the file format produced by Berkeley DB version 1 is not compatible +with that of versions 2 and 3 (versions 2 and 3 have the same format). If you +switch between DB versions, then you may have to rebuild all your Postfix DB +files. -Warning: if you use Berkeley DB version 2 or later, do not enable -DB 1.85 compatibility mode. Doing so would break fcntl file locking. +Warning: if you use Berkeley DB version 2 or later, do not enable DB 1.85 +compatibility mode. Doing so would break fcntl file locking. -Warning: if you use PERL to manipulate Postfix .db files, then you -need to use the same Berkeley DB version in PERL as in Postfix. +Warning: if you use Perl to manipulate Postfix's Berkeley DB files, then you +need to use the same Berkeley DB version in Perl as in Postfix. -Building Postfix on Linux with a specific Berkeley DB version -============================================================= +TTwweeaakkiinngg ppeerrffoorrmmaannccee -Some Linux systems ship with multiple Berkeley DB implementations. -Normally, Postfix builds with the default DB version that ships -with the system. +Postfix provides two configuration parameters that control how much buffering +memory Berkeley DB will use. -On Linux, you need to edit the makedefs script in order to specify -a non-default DB library. + * berkeley_db_create_buffer_size (default: 16 MBytes per table). This setting + is used by the commands that maintain Berkeley DB files: postalias(1) and + postmap(1). For "hash" files, create performance degrades rapidly unless + the memory pool is O(file size). For "btree" files, create performance is + good with sorted input even for small memory pools, but with random input + degrades rapidly unless the memory pool is O(file size). -The reason is that the location of the default db.h include file -changes randomly between vendors and between versions, so that -Postfix has to choose the file for you. + * berkeley_db_read_buffer_size (default: 128 kBytes per table). This setting + is used by all other Postfix programs. The buffer size is adequate for + reading. If the cache is smaller than the table, random read performance is + hardly cache size dependent, except with btree tables, where the cache size + must be large enough to contain the entire path from the root node. + Empirical evidence shows that 64 kBytes may be sufficient. We double the + size to play safe, and to anticipate changes in implementation and bloat. -Warning: the file format produced by Berkeley DB version 1 is not -compatible with that of versions 2 and 3 (versions 2 and 3 have -the same format). If you switch between DB versions, then you may -have to rebuild all your Postfix DB files. +MMiissssiinngg pptthhrreeaadd lliibbrraarryy ttrroouubbllee -Warning: if you use Berkeley DB version 2 or later, do not enable -DB 1.85 compatibility mode. Doing so would break fcntl file locking. +When building Postfix fails with: -Warning: if you use PERL to manipulate Postfix .db files, then you -need to use the same Berkeley DB version in PERL as in Postfix. + undefined reference to `pthread_condattr_setpshared' + undefined reference to `pthread_mutexattr_destroy' + undefined reference to `pthread_mutexattr_init' + undefined reference to `pthread_mutex_trylock' -Tweaking performance -==================== +Add the "-lpthread" library to the "make makefiles" command. -Postfix provides two configuration parameters that control how much -buffering memory Berkeley DB will use. + % make makefiles .... AUXLIBS="... -lpthread" -- berkeley_db_create_buffer_size (default: 16 MBytes per table). -This setting is used by the postalias and postmap commands. For -"hash" files, create performance degrades rapidly unless the memory -pool is O(file size). For "btree" files, create peformance is good -with sorted input even for small memory pools, but with random -input degrades rapidly unless the memory pool is O(file size). +More information is available at http://www.sleepycat.com/. -- berkeley_db_read_buffer_size (default: 128 kBytes per table). -This setting is used by all other Postfix programs. The buffer size -is adequate for reading. If the cache is smaller than the table, -random read performance is hardly cache size dependent, except with -btree tables, where the cache size must be large enough to contain -the entire path from the root node. Empirical evidence shows that -64 kBytes may be sufficient. We double the size to play safe, and -to anticipate changes in implementation and bloat. diff --git a/postfix/README_FILES/DEBUG_README b/postfix/README_FILES/DEBUG_README index 10d2d3c7d..e29c367e1 100644 --- a/postfix/README_FILES/DEBUG_README +++ b/postfix/README_FILES/DEBUG_README @@ -1,101 +1,168 @@ -1 - Purpose of this document -============================ +PPoossttffiixx DDeebbuuggggiinngg HHoowwttoo -This document describes how to debug parts of the Postfix mail -system, either by making the software log a lot of detail to the -syslog daemon, or by running some daemon processes under control -of an interactive debugger. +------------------------------------------------------------------------------- -The text assumes that the Postfix main.cf and master.cf configuration -files are stored in directory /etc/postfix. You can use the command -"postconf config_directory" to find out the actual location of this -directory on your machine. +PPuurrppoossee ooff tthhiiss ddooccuummeenntt -2 - Try turning off chroot operation in master.cf -================================================= +This document describes how to debug parts of the Postfix mail system when +things do not work according to expectation. The methods vary from making +Postfix log a lot of detail, to running some daemon processes under control of +a call tracer or debugger. -A common mistake is to turn on chroot operation in the master.cf -file without going through all the necessary steps to set up a -chroot environment. This causes Postfix daemon processes to fail -due to all kinds of missing files. +The text assumes that the Postfix main.cf and master.cf configuration files are +stored in directory /etc/postfix. You can use the command "ppoossttccoonnff +ccoonnffiigg__ddiirreeccttoorryy" to find out the actual location of this directory on your +machine. -Inspect master.cf for any chrooted processes, save a copy of the -master.cf file, and edit the entries that have chroot operation -turned on. After executing the commands "postfix stop" and "postfix -start", see if the problem has gone away. +Listed in order of increasing invasiveness, the debugging techniques are as +follows: -If turning off chrooted operation made the problem go away, then -congratulations. Leaving Postfix running in this way is adequate -for most sites. If you prefer chrooted operation, see the Postfix -INSTALL file for information about how to prepare Postfix for -chrooted operation. + * Look for obvious signs of trouble + * Debugging Postfix from inside + * Try turning off chroot operation in master.cf + * Verbose logging for specific SMTP connections + * Record the SMTP session with a network sniffer + * Making Postfix daemon programs more verbose + * Manually tracing a Postfix daemon process + * Automatically tracing a Postfix daemon process + * Running daemon programs with the interactive xxgdb debugger + * Running daemon programs under a non-interactive debugger + * Unreasonable behavior + * Reporting problems to postfix-users@postfix.org -3 - Look for obvious signs of trouble -===================================== +LLooookk ffoorr oobbvviioouuss ssiiggnnss ooff ttrroouubbllee -Postfix logs all failed and successful deliveries to a logfile. -The file is usually called /var/log/maillog or /var/log/mail; the -exact pathname is defined in the syslog.conf file. +Postfix logs all failed and successful deliveries to a logfile. The file is +usually called /var/log/maillog or /var/log/mail; the exact pathname is defined +in the /etc/syslog.conf file. -First look for errors that prevent Postfix from working at all: +When Postfix does not receive or deliver mail, the first order of business is +to look for errors that prevent Postfix from working properly: % egrep '(warning|error|fatal|panic):' /some/log/file | more -Note: the most important message is near the BEGINNING of the output. -Error messages that come later are less useful. +Note: the most important message is near the BEGINNING of the output. Error +messages that come later are less useful. + +The nature of each problem is indicated as follows: + + * "ppaanniicc" indicates a problem in the software itself that only a programmer + can fix. Postfix cannot proceed until this is fixed. + + * "ffaattaall" is the result of missing files, incorrect permissions, incorrect + configuration file settings that you can fix. Postfix cannot proceed until + this is fixed. + + * "eerrrroorr" reports a fatal or non-fatal error condition. Postfix cannot + proceed until this is fixed. + + * "wwaarrnniinngg" indicates a non-fatal error. These are problems that you may not + be able to fix (such as a broken DNS server elsewhere on the network) but + may also indicate local configuration errors that could become a problem + later. + +DDeebbuuggggiinngg PPoossttffiixx ffrroomm iinnssiiddee + +With Postfix version 2.1 and later you can ask Postfix to produce mail delivery +reports for debugging purposes. These reports not only show sender/recipient +addresses after address rewriting and alias expansion or forwarding, they also +show information about delivery to mailbox, delivery to non-Postfix command, +responses from remote SMTP servers, and so on. + +Postfix can produce two types of mail delivery reports for debugging: + + * What-if: report what would happen, but do not actually deliver mail. This + mode of operation is requested with: -"PANIC" messages indicate a problem in the software itself that -only a programmer can fix. Postfix cannot proceed until this is -fixed. + $ //uussrr//ssbbiinn//sseennddmmaaiill --bbvv aaddddrreessss...... + Mail Delivery Status Report will be mailed to . -"FATAL" messages are the result of missing files, incorrect permissions, -incorrect configuration file settings. Postfix cannot proceed until -this is fixed. + * What happened: deliver mail and report successes and/or failures, including + replies from remote SMTP servers. This mode of operation is requested with: -"ERROR" messages report a fatal or non-fatal error condition. + $ //uussrr//ssbbiinn//sseennddmmaaiill --vv aaddddrreessss...... + Mail Delivery Status Report will be mailed to . -"WARNING" messages indicate non-fatal errors. These are problems -that you may not be able to fix (such as a broken DNS server -elsewhere on the network) but may also indicate local configuration -errors that could become a problem later. +These reports contain information that is generated by Postfix delivery agents. +Since these run as daemon processes and do not interact with users directly, +the result is sent as mail to the sender of the test message. The format of +these reports is practically identical to that of ordinary non-delivery +notifications. -4 - Verbose logging for specific SMTP connections -================================================= +For a detailed example of a mail delivery status report, see the debugging +section at the end of the ADDRESS_REWRITING_README document. -In /etc/postfix/main.cf, list the remote site name or address in -the "debug_peer_list" parameter. For example, in order to make the -software log a lot of information to the syslog daemon for connections -from or to the loopback interface: +TTrryy ttuurrnniinngg ooffff cchhrroooott ooppeerraattiioonn iinn mmaasstteerr..ccff - debug_peer_list = 127.0.0.1 +A common mistake is to turn on chroot operation in the master.cf file without +going through all the necessary steps to set up a chroot environment. This +causes Postfix daemon processes to fail due to all kinds of missing files. -You can specify one or more hosts, domains, addresses or net/masks. +The example below shows an SMTP server that is configured with chroot turned +off: -5 - Record the SMTP connection with a sniffer -============================================= + /etc/postfix/master.cf: + # ============================================================= + # service type private unpriv cchhrroooott wakeup maxproc command + # (yes) (yes) ((yyeess)) (never) (100) + # ============================================================= + smtp inet n - nn - - smtpd -This example uses tcpdump. In order to record a conversation you -need to specify a large enough buffer or else you will miss some +Inspect master.cf for any processes that have chroot operation not turned off. +If you find any, save a copy of the master.cf file, and edit the entries in +question. After executing the command "ppoossttffiixx rreellooaadd", see if the problem has +gone away. + +If turning off chrooted operation made the problem go away, then +congratulations. Leaving Postfix running in this way is adequate for most +sites. If you prefer chrooted operation, see the Postfix +BASIC_CONFIGURATION_README file for information about how to prepare Postfix +for chrooted operation. + +VVeerrbboossee llooggggiinngg ffoorr ssppeecciiffiicc SSMMTTPP ccoonnnneeccttiioonnss + +In /etc/postfix/main.cf, list the remote site name or address in the +debug_peer_list parameter. For example, in order to make the software log a lot +of information to the syslog daemon for connections from or to the loopback +interface: + + /etc/postfix/main.cf: + debug_peer_list = 127.0.0.1 + +You can specify one or more hosts, domains, addresses or net/masks. To make the +change effective immediately, execute the command "ppoossttffiixx rreellooaadd". + +RReeccoorrdd tthhee SSMMTTPP sseessssiioonn wwiitthh aa nneettwwoorrkk ssnniiffffeerr + +This example uses ttccppdduummpp. In order to record a conversation you need to +specify a large enough buffer with the "-s" option or else you will miss some or all of the packet payload. - tcpdump -w /file/name -s 2000 host hostname and port 25 + # tcpdump -w /file/name -s 2000 host example.com and port 25 + +Run this for a while, stop with Ctrl-C when done. To view the data use a binary +viewer, or eetthheerreeaall, or use my ttccppdduummppxx utility that is available from ftp:// +ftp.porcupine.org/pub/debugging/. -Run this for a while, stop with Ctrl-C when done. To view the data -use a binary viewer, or ethereal, or use my tcpdumpx utility that -is available from ftp://ftp.porcupine.org/pub/debugging. +MMaakkiinngg PPoossttffiixx ddaaeemmoonn pprrooggrraammss mmoorree vveerrbboossee -6 - Making Postfix daemon programs more verbose -=============================================== +Append one or more "--vv" options to selected daemon definitions in /etc/postfix/ +master.cf and type "ppoossttffiixx rreellooaadd". This will cause a lot of activity to be +logged to the syslog daemon. Example: -Append one or more -v options to selected daemon definitions in -/etc/postfix/master.cf and type "postfix reload". This will cause -a lot of activity to be logged to the syslog daemon. + /etc/postfix/master.cf: + smtp inet n - n - - smtpd -v -7 - Manually tracing a Postfix daemon process -============================================= +This makes the Postfix SMTP server more verbose. To diagnose problems with +address rewriting one would specify a "--vv" option for the cleanup(8) and/or +trivial-rewrite(8) daemon, and to diagnose problems with mail delivery one +would specify a "--vv" option for the qmgr(8) or oqmgr(8) queue manager, or for +the lmtp(8), local(8), pipe(8), smtp(8), or virtual(8) delivery agent. -Some systems allow you to inspect a running process with a system -call tracer. For example: +MMaannuuaallllyy ttrraacciinngg aa PPoossttffiixx ddaaeemmoonn pprroocceessss + +Many systems allow you to inspect a running process with a system call tracer. +For example: # trace -p process-id (SunOS 4) # strace -p process-id (Linux and many others) @@ -109,130 +176,132 @@ Even more informative are traces of system library calls. Examples: See your system documentation for details. -Tracing a running process can give valuable information about what -a process is attempting to do. This is as much information as you -can get without running an interactive debugger program, as described -in a later section. +Tracing a running process can give valuable information about what a process is +attempting to do. This is as much information as you can get without running an +interactive debugger program, as described in a later section. -8 - Automatically tracing a Postfix daemon process -================================================== +AAuuttoommaattiiccaallllyy ttrraacciinngg aa PPoossttffiixx ddaaeemmoonn pprroocceessss -Postfix can attach a call tracer whenever a daemon process starts. -Call tracers come in several kinds. +Postfix can attach a call tracer whenever a daemon process starts. Call tracers +come in several kinds. -1) System call tracers such as trace, truss, strace, or ktrace. - These show the communication between the process and the kernel. + 1. System call tracers such as ttrraaccee, ttrruussss, ssttrraaccee, or kkttrraaccee. These show the + communication between the process and the kernel. -2) Library call tracers such as sotruss and ltrace. These show - calls of library routines, and give a better idea of what is - going on within the process. + 2. Library call tracers such as ssoottrruussss and llttrraaccee. These show calls of + library routines, and give a better idea of what is going on within the + process. -Append a -D option to the suspect command in /etc/postfix/master.cf, -for example: +Append a --DD option to the suspect command in /etc/postfix/master.cf, for +example: - smtp inet n - n - - smtpd -D + /etc/postfix/master.cf: + smtp inet n - n - - smtpd -D -Edit the debugger_command definition in /etc/postfix/main.cf so -that it invokes the call tracer of your choice, for example: +Edit the debugger_command definition in /etc/postfix/main.cf so that it invokes +the call tracer of your choice, for example: - debugger_command = - PATH=/bin:/usr/bin:/usr/local/bin; - (truss -p $process_id 2>&1 | logger -p mail.info) & sleep 5 + /etc/postfix/main.cf: + debugger_command = + PATH=/bin:/usr/bin:/usr/local/bin; + (truss -p $process_id 2>&1 | logger -p mail.info) & sleep 5 -Type "postfix reload" and watch the logfile. +Type "ppoossttffiixx rreellooaadd" and watch the logfile. -9 - Running daemon programs under a debugger -============================================ +RRuunnnniinngg ddaaeemmoonn pprrooggrraammss wwiitthh tthhee iinntteerraaccttiivvee xxxxggddbb ddeebbuuggggeerr -Append a -D option to the suspect command in /etc/postfix/master.cf, -for example: +If you have X Windows installed on the Postfix machine, then an interactive +debugger such as xxxxggddbb can be convenient. + +Edit the debugger_command definition in /etc/postfix/main.cf so that it invokes +xxxxggddbb: + + /etc/postfix/main.cf: + debugger_command = + PATH=/bin:/usr/bin:/usr/local/bin:/usr/X11R6/bin + xxgdb $daemon_directory/$process_name $process_id & sleep 5 - smtp inet n - n - - smtpd -D +Be sure that ggddbb is in the command search path, and export XXAAUUTTHHOORRIITTYY so that X +access control works, for example: -Edit the debugger_command definition in /etc/postfix/main.cf so -that it invokes the debugger of your choice. + % setenv XAUTHORITY ~/.Xauthority (csh syntax) + $ export XAUTHORITY=$HOME/.Xauthority (sh syntax) -Two choices are described in detail: +Append a --DD option to the suspect daemon definition in /etc/postfix/master.cf, +for example: + + /etc/postfix/master.cf: + smtp inet n - n - - smtpd -D -1) If you do not have X Windows installed on the Postfix machine, - or if you are not familiar with interactive debuggers, then you - can try to run gdb in non-interactive mode: +Stop and start the Postfix system. This is necessary so that Postfix runs with +the proper XXAAUUTTHHOORRIITTYY and DDIISSPPLLAAYY settings. - /etc/postfix/main.cf: - -------------------- - debugger_command = - PATH=/bin:/usr/bin:/usr/local/bin; export PATH; (echo cont; - echo where) | gdb $daemon_directory/$process_name $process_id 2>&1 - >$config_directory/$process_name.$process_id.log & sleep 5 +Whenever the suspect daemon process is started, a debugger window pops up and +you can watch in detail what happens. - Type "postfix reload" to make the configuration changes effective. +RRuunnnniinngg ddaaeemmoonn pprrooggrraammss uunnddeerr aa nnoonn--iinntteerraaccttiivvee ddeebbuuggggeerr - Whenever a suspect daemon process is started, an output file - is created, named after the daemon and process ID (for example, - smtpd.12345.log). When the process crashes, a stack trace (with - output from the "where" command) is written to its logfile. +If you do not have X Windows installed on the Postfix machine, or if you are +not familiar with interactive debuggers, then you can try to run ggddbb in non- +interactive mode, and have it print a stack trace when the process crashes. -2) If you have X Windows installed on the Postfix machine, then - an interactive debugger such as xxgdb can be convenient. +Edit the debugger_command definition in /etc/postfix/main.cf so that it invokes +the ggddbb debugger: - /etc/postfix/main.cf: - -------------------- - debugger_command = - PATH=/bin:/usr/bin:/usr/local/bin:/usr/X11R6/bin - xxgdb $daemon_directory/$process_name $process_id & sleep 5 + /etc/postfix/main.cf: + debugger_command = + PATH=/bin:/usr/bin:/usr/local/bin; export PATH; (echo cont; + echo where) | gdb $daemon_directory/$process_name $process_id 2>&1 + >$config_directory/$process_name.$process_id.log & sleep 5 - Be sure that gdb is in the command search path, and export - XAUTHORITY so that X access control works, for example: +Append a --DD option to the suspect daemon in /etc/postfix/master.cf, for +example: - % setenv XAUTHORITY ~/.Xauthority + /etc/postfix/master.cf: + smtp inet n - n - - smtpd -D - Stop and start the Postfix system. This is necessary so that - Postfix runs with the proper XAUTHORITY and DISPLAY settings. +Type "ppoossttffiixx rreellooaadd" to make the configuration changes effective. - Whenever the suspect daemon process is started, a debugger window - pops up and you can watch in detail what happens (when using - xxgdb) or a file is created (if using gdb in non-interactive - mode). +Whenever a suspect daemon process is started, an output file is created, named +after the daemon and process ID (for example, smtpd.12345.log). When the +process crashes, a stack trace (with output from the "wwhheerree" command) is +written to its logfile. -10 - Unreasonable behavior -========================== +UUnnrreeaassoonnaabbllee bbeehhaavviioorr -Sometimes the behavior exhibit by Postfix just does not match the -source code. Why can a program deviate from the instructions given -by its author? There are two possibilities. +Sometimes the behavior exhibited by Postfix just does not match the source +code. Why can a program deviate from the instructions given by its author? +There are two possibilities. -1 - The compiler has messed up. + * The compiler has erred. This rarely happens. -2 - The hardware has messed up. + * The hardware has erred. Does the machine have ECC memory? -In both cases, the program being executed is not the program that -was supposed to be executed, so anything can happen. +In both cases, the program being executed is not the program that was supposed +to be executed, so anything could happen. There is a third possibility: -3 - Bugs in system software (kernel or libraries). + * Bugs in system software (kernel or libraries). -Hardware-related failures happen erratically, and they usually do -not reproduce after power cycling and rebooting the system. There's -little I can do about bad hardware. Be sure to use hardware that -at the very least can detect memory errors. Otherwise, Postfix will -just be a sitting duck waiting to be hit by a bit error. Critical -systems deserve real hardware. +Hardware-related failures usually do not reproduce in exactly the same way +after power cycling and rebooting the system. There's little Postfix can do +about bad hardware. Be sure to use hardware that at the very least can detect +memory errors. Otherwise, Postfix will just be waiting to be hit by a bit +error. Critical systems deserve real hardware. -When a compiler messes up, the problem can be reproduced whenever -the resulting program is run. Compiler errors are most likely to -happen in the code optimizer. If a problem is reproducible across -power cycles and system reboots, it can be worthwhile to rebuild -Postfix with optimization disabled, and to see if optimization -makes a difference. +When a compiler makes an error, the problem can be reproduced whenever the +resulting program is run. Compiler errors are most likely to happen in the code +optimizer. If a problem is reproducible across power cycles and system reboots, +it can be worthwhile to rebuild Postfix with optimization disabled, and to see +if optimization makes a difference. In order to compile Postfix with optimizations turned off: % make tidy % make makefiles OPT= -This produces a set of Makefiles that do not request compiler -optimization. +This produces a set of Makefiles that do not request compiler optimization. Once the makefiles are set up, build the software: @@ -240,5 +309,40 @@ Once the makefiles are set up, build the software: % su # make install -And see if the problem reproduces. If the problem goes away, talk -to your vendor. +If the problem goes away, then it is time to ask your vendor for help. + +RReeppoorrttiinngg pprroobblleemmss ttoo ppoossttffiixx--uusseerrss@@ppoossttffiixx..oorrgg + +The people who participate on the postfix-users@postfix.org are very helpful, +especially if YOU provide them with sufficient information. Remember, these +volunteers are willing to help, but their time is limited. + +When reporting a problem, be sure to include the following information. + + * A summary of the problem. Please do not just send some logging without + explanation of what YOU believe is wrong. + + * Consider using a test email address so that you don't have to reveal email + addresses of innocent people. + + * If you can't use a test email address, please anonymize information + consistently. Replace each letter by "A", each digit by "D" so that the + helpers can still recognize syntactical errors. + + * Complete error messages. Please use cut-and-paste, or use attachments, + instead of reciting information from memory. + + * Postfix logging. See the text at the top of the DEBUG_README document to + find out where logging is stored. Please do not frustrate the helpers by + word wrapping the logging. + + * Output from "postconf -n". Please do not send your main.cf file. Or better, + provide output from the "postfinger" tool. + + * If the problem is about too much mail in the queue, consider including + output from the qshape tool, as described in the QSHAPE_README file. + + * If the problem is protocol related (connections time out or an SMTP server + complains about syntax errors etc.) consider recording a session with + tcpdump, as described in the DEBUG_README document. + diff --git a/postfix/README_FILES/ETRN_README b/postfix/README_FILES/ETRN_README index 0dc5d7c12..5970aacbb 100644 --- a/postfix/README_FILES/ETRN_README +++ b/postfix/README_FILES/ETRN_README @@ -1,117 +1,248 @@ -Purpose of this document -======================== +PPoossttffiixx EETTRRNN HHoowwttoo -This document describes the purpose of the Postfix fast ETRN service, -how the service works, and how it can be tested. +------------------------------------------------------------------------------- -Other documents with information on this subject: - -- conf/sample-flush.cf, sample configuration file -- conf/main.cf, sample configuration file -- flush(8), flush service implementation - -The Postfix fast ETRN service -============================= - -The SMTP ETRN command was designed for sites that have intermittent -Internet connectivity. With ETRN, a site can tell the mail server -of its provider to "Please deliver all my mail now". - -Postfix versions before 20001005 implemented the ETRN command in -a lame manner: they simply attempted to deliver all queued mail. -This is slow on mail servers that queue mail for many customers. - -As of version 20001005, Postfix has a fast ETRN implementation that -does not require Postfix to examine every queue file. The command -"sendmail -qR" is now implemented by sending an ETRN command to -the local SMTP server. +PPuurrppoossee ooff tthhee PPoossttffiixx ffaasstt EETTRRNN sseerrvviiccee -Postfix "fast ETRN/sendmail -qR" speeds up deliveries by attempting -to deliver only mail that is queued for a given destination site. -The old Postfix "slow ETRN" is still used as a fall-back method. +The SMTP ETRN command was designed for sites that have intermittent Internet +connectivity. With ETRN, a site can tell the mail server of its provider to +"Please deliver all my mail now". The SMTP server searches the queue for mail +to the customer, and delivers that mail bbyy ccoonnnneeccttiinngg ttoo tthhee ccuussttoommeerr''ss SSMMTTPP +sseerrvveerr. The mail is not delivered via the connection that was used for sending +ETRN. -How Postfix fast ETRN works -=========================== +Postfix versions before 1.0 (also known as version 20010228) implemented the +ETRN command in an inefficient manner: they simply attempted to deliver all +queued mail. This is slow on mail servers that queue mail for many customers. -The "fast ETRN" service uses the new "flush" daemon which maintains -per-destination logfiles of queued mail. These logfiles are kept -below /var/spool/postfix/flush. Each logfile is named after its -destination domain name. Only destinations with syntactically valid -domain names can have per-destination logfiles. +As of version 1.0, Postfix has a fast ETRN implementation that does not require +Postfix to examine every queue file. Instead, Postfix maintains a record of +what queue files contain mail for destinations that are configured for ETRN +service. ETRN service is no longer available for domains that aren't configured +for the service. -The behavior of the new "flush" daemon is controlled by parameters -in the main.cf configuration file. +This document provides information on the following topics: -By default, Postfix "fast ETRN/sendmail -qR" service is available -only for destinations that Postfix is willing to relay mail to: + * Using the Postfix fast ETRN service + * How Postfix fast ETRN works + * Postfix fast ETRN service limitations + * Configuring the Postfix fast ETRN service + * Configuring a domain for ETRN service only + * Testing the Postfix fast ETRN service - fast_flush_domains = $relay_domains - -The "relay_domains" parameter specifies what destinations Postfix -will relay to. - -For destinations that are not eligible for the new "fast ETRN/sendmail --qR" service, Postfix falls back to the old "slow ETRN" method -which attempts to deliver all queued mail. - -To enable "fast ETRN/sendmail -qR" for some other destination, specify: - - fast_flush_domains = $relay_domains, some.other.domain - -To disable "fast ETRN/sendmail -qR", so that Postfix always uses -the old "slow ETRN" which delivers all queued mail, specify: +Other documents with information on this subject: - fast_flush_domains = + * flush(8), flush service implementation -Testing the fast ETRN service -============================= +UUssiinngg tthhee PPoossttffiixx ffaasstt EETTRRNN sseerrvviiccee -If you run Postfix with "fast ETRN" service for the very first -time, you need to run "sendmail -q" to populate the per-site deferred -mail logfiles. If you omit this step, the logfiles will eventually -become populated as Postfix routinely attempts to deliver delayed -mail, but that will take a couple hours. +The following is an example SMTP session that shows how an SMTP client requests +the ETRN service. Client commands are shown in bold font. -After the "sendmail -q" has completed all delivery attempts (that -can take a while), you're ready to test the "fast ETRN" service. -Telnet to the Postfix SMTP server from a client that is allowed to -execute ETRN commands (by default, that's every client), and type: + 220 my.server.tld ESMTP Postfix + hheelloo mmyy..cclliieenntt..ttlldd + 250 Ok + eettrrnn ssoommee..ccuussttoommeerr..ddoommaaiinn + 250 Queuing started + qquuiitt + 221 Bye - helo my.client.tld - etrn some.customer.domain +As mentioned in the introduction, the mail is delivered by connecting to the +customer's SMTP server; it is not sent over the connection that was used to +send the ETRN command. -where "some.customer.domain" is the name of a domain that has a -non-empty logfile somewhere under /var/spool/postfix/flush. +The Postfix operator can request delivery for a specific customer by using the +command "sendmail -qRdestination" and, with Postfix version 1.1 and later, +"postqueue -sdestination". -In the maillog file, you should immediately see a couple of logfile -records, as evidence that the queue manager has opened queue files: +HHooww PPoossttffiixx ffaasstt EETTRRNN wwoorrkkss - Oct 2 10:51:19 localhost postfix/qmgr[51999]: 682E8440A4: - from=, size=12345, nrcpt=1 (queue active) - Oct 2 10:51:19 localhost postfix/qmgr[51999]: 02249440B7: - from=, size=4711, nrcpt=1 (queue active) +When a Postfix delivery agent decides that mail must be delivered later, it +sends the destination domain name and the queue file name to the flush(8) +daemon which maintains per-destination logfiles with file names of queued mail. +These logfiles are kept below $queue_directory/flush. Per-destination logfiles +are maintained only for destinations that are listed with the +$fast_flush_domains parameter and that have syntactically valid domain names. + + Postfix Postfix One logfile + delivery -(domain, queue ID)-> flush -(queue ID)-> per eligible + agent daemon domain + +When Postfix receives a request to "deliver mail for a domain now", the flush +(8) daemon moves all deferred queue files that are listed for that domain to +the incoming queue, and requests that the queue manager deliver them. In order +to force delivery, the queue manager temporarily ignores the lists of +undeliverable destinations: the volatile in-memory list of dead domains, and +the list of message delivery transports specified with the defer_transports +configuration parameter. + +PPoossttffiixx ffaasstt EETTRRNN sseerrvviiccee lliimmiittaattiioonnss -What happens next depends on whether the destination is reachable. -If it's not reachable, the mail queue IDs will be added back to -the some.customer.domain logfile under /var/spool/postfix/flush. +The design of the flush(8) server and of the flush queue introduce a few +limitations that should not be an issue unless you want to turn on fast ETRN +service for every possible destination. -Repeat the exercise with another domain that your server is willing -to relay to (domain listed in "relay_domains"), but that has no mail -queued. + * The flush(8) daemon maintains per-destination logfiles with queue file + names. When a request to "deliver mail now" arrives, Postfix will attempt + to deliver all recipients in the queue files that have mail for the + destination in question. This does not perform well when queue files have + recipients in many different domains. - helo my.client.tld - etrn some.other.customer.domain + * The flush(8) daemon maintains per-destination logfiles only for + destinations listed with $fast_flush_domains. With other destinations it + not possible to trigger delivery with "sendmail -qRdestination" or, with + Postfix version 1.1 and later, "postqueue -sdestination". + + * Up to and including early versions of Postfix version 2.1, the "fast flush" + service may not deliver some messages if the request to "deliver mail now" + is received while a deferred queue scan is already in progress. The reason + is that the queue manager does not ignore the volatile in-memory list of + dead domains, and the list of message delivery transports specified with + the defer_transports configuration parameter. + +CCoonnffiigguurriinngg tthhee PPoossttffiixx ffaasstt EETTRRNN sseerrvviiccee + +The behavior of the flush(8) daemon is controlled by parameters in the main.cf +configuration file. + +By default, Postfix "fast ETRN" service is available only for destinations that +Postfix is willing to relay mail to: + + /etc/postfix/main.cf: + fast_flush_domains = $relay_domains + smtpd_etrn_restrictions = permit_mynetworks, reject + +Notes: + + * The relay_domains parameter specifies what destinations Postfix will relay + to. For destinations that are not eligible for the "fast ETRN" service, + Postfix replies with an error message. + + * The smtpd_etrn_restrictions parameter limits what clients may execute the + ETRN command. By default, any client has permission. + +To enable "fast ETRN" for some other destination, specify: + + /etc/postfix/main.cf: + fast_flush_domains = $relay_domains, some.other.domain + +To disable "fast ETRN", so that Postfix rejects all ETRN requests and so that +it maintains no per-destination logfiles, specify: + + /etc/postfix/main.cf: + fast_flush_domains = + +CCoonnffiigguurriinngg aa ddoommaaiinn ffoorr EETTRRNN sseerrvviiccee oonnllyy + +While an "ETRN" customer is off-line, Postfix will make spontaneous attempts to +deliver mail to it. These attempts are separated in time by increasing time +intervals, ranging from $minimal_backoff_time to $maximal_backoff_time, and +should not be a problem unless a lot of mail is queued. + +To prevent Postfix from making spontaneous delivery attempts you can configure +Postfix to always defer mail for the "ETRN" customer. Mail is delivered only +after the ETRN command or with "sendmail -q", with "sendmail -qRdomain", or +with "postqueue -sdomain"(Postfix version 1.1 and later only), + +In the example below we configure an "etrn-only" delivery transport which is +simply a duplicate of the "smtp" and "relay" mail delivery transports. The only +difference is that mail destined for this delivery transport is deferred as +soon as it arrives. + + 1 /etc/postfix/master.cf: + 2 # ============================================================= + 3 # service type private unpriv chroot wakeup maxproc command + 4 # (yes) (yes) (yes) (never) (100) + 5 # ============================================================= + 6 smtp unix - - n - - smtp + 7 relay unix - - n - - smtp + 8 etrn-only unix - - n - - smtp + 9 + 10 /etc/postfix/main.cf: + 11 relay_domains = customer.tld ...other domains... + 12 defer_transports = etrn-only + 13 transport_maps = hash:/etc/postfix/transport + 14 + 15 /etc/postfix/transport: + 16 customer.tld etrn-only:[mailhost.customer.tld] + +Translation: + + * Line 8: The "etrn-only" mail delivery service is a copy of the "smtp" and + "relay" service. + + * Line 11: Don't forget to authorize relaying for this customer, either via + relay_domains or with the permit_mx_backup feature. + + * Line 12: The "etrn-only" mail delivery service is configured so that + spontaneous mail delivery is disabled. + + * Lines 13-16: Mail for the customer is given to the "etrn-only" mail + delivery service. + + * Line 16: The "[mailhost.customer.tld]" turns off MX record lookups; you + must specify this if your Postfix server is the primary MX host for the + customer's domain. + +TTeessttiinngg tthhee PPoossttffiixx ffaasstt EETTRRNN sseerrvviiccee + +By default, "fast ETRN" service is enabled for all domains that match +$relay_domains. If you run Postfix with "fast ETRN" service for the very first +time, you need to run "sendmail -q" once in order to populate the per-site +deferred mail logfiles. If you omit this step, no harm is done. The logfiles +will eventually become populated as Postfix routinely attempts to deliver +delayed mail, but that will take a couple hours. After the "sendmail -q" +command has completed all delivery attempts (this can take a while), you're +ready to test the "fast ETRN" service. + +To test the "fast ETRN" service, telnet to the Postfix SMTP server from a +client that is allowed to execute ETRN commands (by default, that's every +client), and type the commands shown in boldface: -This time, the "etrn" command should trigger NO mail deliveries at -all. If this triggers delivery of all mail, then you used the wrong -domain name, or "fast ETRN" service is turned off. + 220 my.server.tld ESMTP Postfix + hheelloo mmyy..cclliieenntt..ttlldd + 250 Ok + eettrrnn ssoommee..ccuussttoommeerr..ddoommaaiinn + 250 Queuing started -Finally, repeat the exercise with a destination that your mail -server is not willing to relay to. It does not matter if your -server has mail queued for that destination. +where "some.customer.domain" is the name of a domain that has a non-empty +logfile somewhere under $queue_directory/flush. - helo my.client.tld - etrn not.a.customer.domain +In the maillog file, you should immediately see a couple of logfile records, as +evidence that the queue manager has opened queue files: + + Oct 2 10:51:19 myhostname postfix/qmgr[51999]: 682E8440A4: + from=, size=12345, nrcpt=1 (queue active) + Oct 2 10:51:19 myhostname postfix/qmgr[51999]: 02249440B7: + from=, size=4711, nrcpt=1 (queue active) + +What happens next depends on whether the destination is reachable. If it's not +reachable, the mail queue IDs will be added back to the some.customer.domain +logfile under $queue_directory/flush. + +Repeat the exercise with some other destination that your server is willing to +relay to (any domain listed in $relay_domains), but that has no mail queued. +The text in bold face stands for the commands that you type: + + 220 my.server.tld ESMTP Postfix + hheelloo mmyy..cclliieenntt..ttlldd + 250 Ok + eettrrnn ssoommee..ootthheerr..ccuussttoommeerr..ddoommaaiinn + 250 Queuing started + +This time, the "ETRN"" command should trigger NO mail deliveries at all. If +this triggers delivery of all mail, then you used the wrong domain name, or +"fast ETRN" service is turned off. + +Finally, repeat the exercise with a destination that your mail server is not +willing to relay to. It does not matter if your server has mail queued for that +destination. + + 220 my.server.tld ESMTP Postfix + hheelloo mmyy..cclliieenntt..ttlldd + 250 Ok + eettrrnn nnoott..aa..ccuussttoommeerr..ddoommaaiinn + 459 : service unavailable + +In this case, Postfix should reject the request as shown above. -If your "fast ETRN" caching policy is left at its default setting, -then the "etrn" command should trigger delivery of all queued mail. diff --git a/postfix/README_FILES/FILTER_README b/postfix/README_FILES/FILTER_README index 1ae78e6e2..64a71e996 100644 --- a/postfix/README_FILES/FILTER_README +++ b/postfix/README_FILES/FILTER_README @@ -1,404 +1,511 @@ -Introduction -============ +PPoossttffiixx AAfftteerr--QQuueeuuee CCoonntteenntt FFiilltteerr + +------------------------------------------------------------------------------- + +IInnttrroodduuccttiioonn + +This document requires Postfix version 2.1 or later. + +Normally, Postfix receives mail, stores it in the mail queue and then delivers +it. With the external content filter described here, mail is filtered AFTER it +is queued. This approach decouples mail receiving processes from mail filtering +processes, and gives you maximal control over how many filtering processes you +are willing to run in parallel. + +The after-queue content filter is meant to be used as follows: + + Network or -> Postfix -> CCoonntteenntt -> Postfix -> Network or + local users queue ffiilltteerr queue local mailbox + +This document describes implementations that use a single Postfix instance for +everything: receiving, filtering and delivering mail. Applications that use two +separate Postfix instances will be covered by a later version of this document. + +The after-queue content filter is not to be confused with the approach that is +described in the SMTPD_PROXY_README document, where incoming SMTP mail is +filtered BEFORE it is stored into the Postfix queue. + +This document describes two approaches to content filter all email, as well as +several options filter mail selectively: + + * Principles of operation + * Simple content filter example + * Simple content filter limitations + * Advanced content filter example + * Advanced content filter performance + * Filtering mail from outside users only + * Different filters for different domains + * FILTER actions in access or header/body tables + +PPrriinncciipplleess ooff ooppeerraattiioonn + +An external content filter receives unfiltered mail from Postfix (as described +further below) and does one of the following: + + 1. Re-inject the mail back into Postfix, perhaps after changing content and/or + destination. + + 2. Reject the mail (by sending a suitable status code back to Postfix). + Postfix will return the mail to the sender. + +NOTE: in this time of mail worms and forged spam, it is a VERY BAD IDEA to send +viruses back to the sender address, because the sender address is almost +certainly not the originator. It is better to discard known viruses, and to +quarantine material that is suspect so that a human can decide what to do with +it. + +SSiimmppllee ccoonntteenntt ffiilltteerr eexxaammppllee + +The first example is simple to set up. Postfix receives unfiltered mail from +the network with the smtpd(8) server, and delivers unfiltered mail to a content +filter with the Postfix pipe(8) delivery agent. The content filter injects +filtered mail back into Postfix with the Postfix sendmail(1) command, so that +Postfix can deliver it to the final destination. + +This means that mail submitted via the Postfix sendmail(1) command cannot be +content filtered. + +In the figure below, names followed by a number represent Postfix commands or +daemon programs. See the OVERVIEW document for an introduction to the Postfix +architecture. + + Unfiltered -> smtpd(8) qmgr(8) local(8) -> Filtered + >- cleanup(8) -> Postfix -< smtp(8) -> Filtered + pickup(8) queue pipe(8) + + ^ | + | v + + maildrop Postfix Postfix Content + queue <- postdrop <- sendmail <- filter + (1) (1) + +The content filter can be a simple shell script like this: + + 1 #!/bin/sh + 2 + 3 # Simple shell-based filter. It is meant to be invoked as follows: + 4 # /path/to/script -f sender recipients... + 5 + 6 # Localize these. + 7 INSPECT_DIR=/var/spool/filter + 8 SENDMAIL="/usr/sbin/sendmail -i" + 9 + 10 # Exit codes from + 11 EX_TEMPFAIL=75 + 12 EX_UNAVAILABLE=69 + 13 + 14 # Clean up when done or when aborting. + 15 trap "rm -f in.$$" 0 1 2 3 15 + 16 + 17 # Start processing. + 18 cd $INSPECT_DIR || { + 19 echo $INSPECT_DIR does not exist; exit $EX_TEMPFAIL; } + 20 + 21 cat >in.$$ || { + 22 echo Cannot save mail to file; exit $EX_TEMPFAIL; } + 23 + 24 # Specify your content filter here. + 25 # filter smtpd \ /local---->Filtered mail - : -cleanup->queue- : - ---->pickup / \smtp----->Filtered mail - ^ : | : - | : \pipe-----+ - | .................................. | - | | - | | - +-Postfix sendmail<----filter script<--+ +To turn off content filtering, edit the master.cf file, remove the "- +o content_filter=filter:dummy" text from the entry that defines the Postfix +SMTP server, and execute another "ppoossttffiixx rreellooaadd". -In this example, mail is filtered by a /some/where/filter program. -This can be a simple shell script like this: +With the shell script as shown above you will lose a factor of four in Postfix +performance for transit mail that arrives and leaves via SMTP. You will lose +another factor in transit performance for each additional temporary file that +is created and deleted in the process of content filtering. The performance +impact is less for mail that is submitted or delivered locally, because such +deliveries are already slower than SMTP transit mail. - #!/bin/sh +SSiimmppllee ccoonntteenntt ffiilltteerr lliimmiittaattiioonnss - # Localize these. - INSPECT_DIR=/var/spool/filter - SENDMAIL="/usr/sbin/sendmail -i" +The problem with content filters like the one above is that they are not very +robust. The reason is that the software does not talk a well-defined protocol +with Postfix. If the filter shell script aborts because the shell runs into +some memory allocation problem, the script will not produce a nice exit status +as defined in the file /usr/include/sysexits.h. Instead of going to the +deferred queue, mail will bounce. The same lack of robustness can happen when +the content filtering software itself runs into a resource problem. - # Exit codes from - EX_TEMPFAIL=75 - EX_UNAVAILABLE=69 +The simple content filter method is not suitable for content filter actions +that are invoked via header_checks or body_checks patterns. These patterns will +be applied again after mail is re-injected with the Postfix sendmail command, +resulting in a mail filtering loop. The advanced content filtering method (see +below) makes it possible to turn off header_checks or body_checks patterns for +filtered mail. - # Clean up when done or when aborting. - trap "rm -f in.$$" 0 1 2 3 15 +AAddvvaanncceedd ccoonntteenntt ffiilltteerr eexxaammppllee - # Start processing. - cd $INSPECT_DIR || { echo $INSPECT_DIR does not exist; exit $EX_TEMPFAIL; } +The second example is more complex, but can give better performance, and is +less likely to bounce mail when the machine runs into some resource problem. +This content filter receives unfiltered mail with SMTP on localhost port 10025, +and sends filtered mail back into Postfix with SMTP on localhost port 10026. - cat >in.$$ || { echo Cannot save mail to file; exit $EX_TEMPFAIL; } +For non-SMTP capable content filtering software, Bennett Todd's SMTP proxy +implements a nice PERL/SMTP content filtering framework. See: http:// +bent.latency.net/smtpprox/. - # filter smtpd(8) qmgr(8) smtp(8) -> Filtered + >- cleanup(8) -> Postfix -< + Unfiltered -> pickup(8) queue local(8) -> Filtered - exit $? + ^ | + | v -The idea is to first capture the message to file and then run the -content through a third-party content filter program. + smtpd(8) smtp(8) + 10026 -- If the mail cannot be captured to file, mail delivery is deferred - by terminating with exit status 75 (EX_TEMPFAIL). Postfix places - the message in the deferred mail queue and tries again later. + ^ | + | v -- If the content filter program finds a problem, the mail is bounced - by terminating with exit status 69 (EX_UNAVAILABLE). Postfix - will return the message to the sender as undeliverable. + content filter 10025 -- If the content is OK, it is given as input to the Postfix sendmail - command, and the exit status of the filter command is whatever - exit status the Postfix sendmail command produces. Postfix will - deliver the message as usual. +The example given here filters all mail, including mail that arrives via SMTP +and mail that is locally submitted via the Postfix sendmail command. See +examples near the end of this document for how to exclude local users from +filtering, or how to configure a destination dependent content filter. -I suggest that you run this script by hand until you are satisfied -with the results. Run it with a real message (headers+body) as -input: +You can expect to lose about a factor of two in Postfix performance for mail +that arrives and leaves via SMTP, provided that the content filter creates no +temporary files. Each temporary file created by the content filter adds another +factor to the performance loss. - % /some/where/filter -f sender recipient... smtpd \ /local----> - : -cleanup->queue- : - ---->pickup / ^ | \smtp-----> - : | v : - : smtpd smtp : - : 10026 | : - ......................|........... - ^ | - | v - ....|............ - : | 10025 : - : filter : - : : - ................. - -To enable content filtering in this manner, specify in main.cf: - -/etc/postfix/main.cf: - content_filter = scan:localhost:10025 - receive_override_options = no_address_mappings - -- The "content_filter" line causes Postfix to add one content - filtering record to each incoming mail message, with content - scan:localhost:10025. The content filtering records are added - by the smtpd, pickup and qmqpd servers. - -- The "receive_override_options" line disables address manipulation - before the content filter, so that the content filter sees the - original mail addresses instead of the result of virtual alias - expansion, canonical mapping, automatic bcc, address masquerading, - etc. - -To turn off content filtering, delete or comment out the two above -main.cf lines. All the changes made in the text below have no effect -when content filtering is turned off. + /etc/postfix/master.cf: + # =================================================================== + # service type private unpriv chroot wakeup maxproc command + # (yes) (yes) (yes) (never) (100) + # =================================================================== + localhost:10025 inet n n n - 10 spawn + user=filter argv=/path/to/filter localhost 10026 -Content filter information is stored in queue files; this is how -Postfix keeps track of what mail needs filtering. When a queue -file contains content filter information, the queue manager will -deliver the mail to the specified content filter regardless of its -final destination. - -In this example, "scan" is an instance of the Postfix SMTP client -with slightly different configuration parameters. This is how -one would set up the service in the Postfix master.cf file: - -/etc/postfix/master.cf: - # ============================================================= - # service type private unpriv chroot wakeup maxproc command - # (yes) (yes) (yes) (never) (100) - # ============================================================= - scan unix - - n - 10 smtp - -o smtp_send_xforward_command=yes - -- Instead of a limit of 10 concurrent processes, use whatever - process limit is feasible for your machine. Content inspection - software can gobble up a lot of system resources, so you don't - want to have too much of it running at the same time. - -- With "-o smtp_send_xforward_command=yes", the scan transport will - try to forward the original client name and IP address to the - after-filter smtpd process, so that filtered mail is logged with - the real client name IP address. See sample-smtp.cf and smtp(8). - -The content filter can be set up with the Postfix spawn service, -which is the Postfix equivalent of inetd. For example, to instantiate -up to 10 content filtering processes on demand: + * "filter" is a dedicated local user account. The user will never log in, and + can be given a "*" password and non-existent shell and home directory. This + user handles all potentially dangerous mail content - that is why it should + be a separate account. + +If you want to have your filter listening on port localhost:10025 instead of +Postfix, then you must run your filter as a stand-alone program, and must not +use the Postfix spawn service. + +AAddvvaanncceedd ffiilltteerr:: iinnjjeeccttiinngg mmaaiill bbaacckk iinnttoo PPoossttffiixx + +The job of the content filter is to either bounce mail with a suitable +diagnostic, or to feed the mail back into Postfix through a dedicated listener +on port localhost 10026. + +The simplest content filter just copies SMTP commands and data between its +inputs and outputs. If it has a problem, all it has to do is to reply to an +input of `.' from Postfix with `550 content rejected', and to disconnect +without sending `.' on the connection that injects mail back into Postfix. /etc/postfix/master.cf: - # =================================================================== - # service type private unpriv chroot wakeup maxproc command - # (yes) (yes) (yes) (never) (100) - # =================================================================== - localhost:10025 inet n n n - 10 spawn - user=filter argv=/some/where/filter localhost 10026 - -- "filter" is a dedicated local user account. The user will never - log in, and can be given a "*" password and non-existent shell - and home directory. This user handles all potentially dangerous - mail content - that is why it should be a separate account. - -- In the above example, Postfix listens on port localhost:10025. - If you want to have your filter listening on port localhost:10025 - instead of Postfix, then you must run your filter as a stand-alone - program, and not use the Postfix spawn service. - -The simplest content filter just copies SMTP commands and data -between its inputs and outputs. If it has a problem, all it has to -do is to reply to an input of `.' with `550 content rejected', and -to disconnect without sending `.' on the connection that injects -mail back into Postfix. - -The job of the content filter is to either bounce mail with a -suitable diagnostic, or to feed the mail back into Postfix through -a dedicated listener on port localhost 10026: - -/etc/postfix/master.cf: - # =================================================================== - # service type private unpriv chroot wakeup maxproc command - # (yes) (yes) (yes) (never) (100) - # =================================================================== - localhost:10026 inet n - n - 10 smtpd - -o content_filter= - -o receive_override_options=no_unknown_recipient_checks,no_header_body_checks - -o smtpd_helo_restrictions= - -o smtpd_client_restrictions= - -o smtpd_sender_restrictions= - -o smtpd_recipient_restrictions=permit_mynetworks,reject - -o mynetworks=127.0.0.0/8 - -o smtpd_authorized_xforward_hosts=127.0.0.0/8 - -- Note: do not use spaces around the "=" or "," characters. - -- Note: the SMTP server must not have a smaller process limit than - the "filter" master.cf entry. - -- The "-o content_filter=" overrides main.cf and requests no content - filtering for incoming mail. This is required or else mail will - stay in the content filtering loop. - -- The "-o receive_override_options" overrides main.cf. It is - complementary to the options that are specified in main.cf: - - - Disable attempts to find out if a recipient is unknown, and - disable header/body checks. This work was already done before - the content filter and repeating it would be wasteful. - - - Enable virtual alias expansion, canonical mappings, address - masquerading, and other address mappings. - - These receive override options are either implemented by the SMTP - server itself, or they are passed on to the cleanup server. - -- The "-o smtpd_xxx_restrictions" and "-o mynetworks=127.0.0.0/8" - override main.cf turn off junk mail controls that would only - waste time here. - -- With "-o smtpd_authorized_xforward_hosts=mynetworks=127.0.0.0/8", - the scan transport will try to forward the original client name - and IP address to the after-filter smtpd process, so that filtered - mail is logged with the real client name IP address. See - sample-smtpd.cf and smtpd(8). - -Filtering mail from outside users only -====================================== - -The easiest approach is to configure ONE Postfix instance with -multiple SMTP server IP addresses in master.cf: - -- Two SMTP server IP addresses for inside users only that never - invoke content filtering. - -- One SMTP server address for outside users that always invokes - content filtering. - -/etc/postfix.master.cf: - # SMTP service for internal users only, no content filtering. - 1.2.3.4:smtp inet n - n - - smtpd - -o smtpd_client_restrictions=permit_mynetworks,reject - 127.0.0.1:smtp inet n - n - - smtpd - -o smtpd_client_restrictions=permit_mynetworks,reject - - # SMTP service for external users, with content filtering. - 1.2.3.5:smtp inet n - n - - smtpd - -o content_filter=foo:bar - -o receive_override_options=no_address_mappings - -After this, you can follow the same procedure as outlined in the -"advanced" or "simple" content filtering examples above, except -that you do not need to specify "content_filter" settings in the -main.cf file. - -Getting really nasty -==================== - -The above filtering configurations are static. Mail that follows -a given path is either always filtered or it is never filtered. As -of Postfix 2.0 you can also turn on content filtering on the fly. - - FILTER foo:bar - -You can do this in smtpd access maps as well as the cleanup server's -header/body_checks. This feature must be used with great care: -you must disable all the UCE features in the after-filter smtpd -and cleanup daemons or else you will have a content filtering loop. + # =================================================================== + # service type private unpriv chroot wakeup maxproc command + # (yes) (yes) (yes) (never) (100) + # =================================================================== + localhost:10026 inet n - n - 10 smtpd + -o content_filter= + - + o + receive_override_options=no_unknown_recipient_checks,no_header_body_checks + -o smtpd_helo_restrictions= + -o smtpd_client_restrictions= + -o smtpd_sender_restrictions= + -o smtpd_recipient_restrictions=permit_mynetworks,reject + -o mynetworks=127.0.0.0/8 + -o smtpd_authorized_xforward_hosts=127.0.0.0/8 + + * Note: do not use spaces around the "=" or "," characters. + + * Note: the SMTP server must not have a smaller process limit than the + "filter" master.cf entry. + + * The "-o content_filter=" overrides main.cf settings, and requests no + content filtering for mail from the content filter. This is required or + else mail will stay in the content filtering loop. + + * The "-o receive_override_options" overrides main.cf settings. It is + complementary to the options that are specified in main.cf: + + o Disable attempts to find out if a recipient is unknown, and disable + header/body checks. This work was already done before the content + filter and repeating it would be wasteful. + + o Enable virtual alias expansion, canonical mappings, address + masquerading, and other address mappings. + + These receive override options are either implemented by the SMTP server + itself, or they are passed on to the cleanup server. + + * The "-o smtpd_xxx_restrictions" and "-o mynetworks=127.0.0.0/8" override + main.cf settings. They turn off junk mail controls that would only waste + time here. + + * With "-o smtpd_authorized_xforward_hosts=127.0.0.0/8", the scan transport + will try to forward the original client name and IP address to the after- + filter smtpd process, so that filtered mail is logged with the real client + name and IP address. See XFORWARD_README and smtpd(8). + +AAddvvaanncceedd ccoonntteenntt ffiilltteerr ppeerrffoorrmmaannccee + +With the "sandwich" approach to content filtering described here, it is +important to match the filter concurrency to the available CPU, memory and I/ +O resources. Too few content filter processes and mail accumulates in the +active queue even with low traffic volume; too much concurrency and Postfix +ends up deferring mail destined for the content filter because processes fail +due to insufficient resources. + +Currently, content filter performance tuning is a process of trial and error; +analysis is handicapped because filtered and unfiltered messages share the same +queue. As mentioned in the introduction of this document, content filtering +with multiple Postfix instances will be covered in a future version. + +FFiilltteerriinngg mmaaiill ffrroomm oouuttssiiddee uusseerrss oonnllyy + +The easiest approach is to configure ONE Postfix instance with multiple SMTP +server IP addresses in master.cf: + + * Two SMTP server IP addresses for mail from inside users only, with content + filtering turned off. + + /etc/postfix.master.cf: + # ================================================================== + # service type private unpriv chroot wakeup maxproc command + # (yes) (yes) (yes) (never) (100) + # ================================================================== + 1.2.3.4:smtp inet n - n - - smtpd + -o smtpd_client_restrictions=permit_mynetworks,reject + 127.0.0.1:smtp inet n - n - - smtpd + -o smtpd_client_restrictions=permit_mynetworks,reject + + * One SMTP server address for mail from outside users with content filtering + turned on. + + /etc/postfix.master.cf: + # ================================================================= + # service type private unpriv chroot wakeup maxproc command + # (yes) (yes) (yes) (never) (100) + # ================================================================= + 1.2.3.5:smtp inet n - n - - smtpd + -o content_filter=foo:bar + -o receive_override_options=no_address_mappings + +After this, you can follow the same procedure as outlined in the "advanced" or +"simple" content filtering examples above, except that you must not specify +"content_filter" or "receive_override_options" in the main.cf file. + +DDiiffffeerreenntt ffiilltteerrss ffoorr ddiiffffeerreenntt ddoommaaiinnss + +If you are an MX service provider and want to apply different content filters +for different domains, you can configure ONE Postfix instance with multiple +SMTP server IP addresses in master.cf. Each address provides a different +content filter service. + + /etc/postfix.master.cf: + # ================================================================= + # service type private unpriv chroot wakeup maxproc command + # (yes) (yes) (yes) (never) (100) + # ================================================================= + # SMTP service for domains that are content filtered with foo:bar + 1.2.3.4:smtp inet n - n - - smtpd + -o content_filter=foo:bar + -o receive_override_options=no_address_mappings + + # SMTP service for domains that are content filtered with xxx:yyy + 1.2.3.5:smtp inet n - n - - smtpd + -o content_filter=xxx:yyy + -o receive_override_options=no_address_mappings + +After this, you can follow the same procedure as outlined in the "advanced" or +"simple" content filtering examples above, except that you must not specify +"content_filter" or "receive_override_options" in the main.cf file. + +Set up MX records in the DNS that route each domain to the proper SMTP server +instance. + +FFIILLTTEERR aaccttiioonnss iinn aacccceessss oorr hheeaaddeerr//bbooddyy ttaabblleess + +The above filtering configurations are static. Mail that follows a given path +is either always filtered or it is never filtered. As of Postfix 2.0 you can +also turn on content filtering on the fly. + +To turn on content filtering with an access(5) table rule: + + /etc/postfix/access: + whatever FILTER foo:bar + +To turn on content filtering with a header_checks(5) or body_checks(5) table +pattern: + + /etc/postfix/header_checks: + /whatever/ FILTER foo:bar + +You can do this in smtpd access maps as well as the cleanup server's header/ +body_checks. This feature must be used with great care: you must disable all +the UCE features in the after-filter smtpd and cleanup daemons or else you will +have a content filtering loop. Limitations: -- FILTER actions from smtpd access maps and header/body_checks take - precedence over filters specified with the main.cf content_filter - parameter. + * FILTER actions from smtpd access maps and header/body_checks take + precedence over filters specified with the main.cf content_filter + parameter. + + * If a message triggers more than one filter action, only the last one takes + effect. -- If a message triggers more than one filter action, only the last - one takes effect. + * The same content filter is applied to all the recipients of a given + message. -- The same content filter is applied to all the recipients of a - given message. diff --git a/postfix/README_FILES/HOSTING_README b/postfix/README_FILES/HOSTING_README deleted file mode 100644 index 246ffb610..000000000 --- a/postfix/README_FILES/HOSTING_README +++ /dev/null @@ -1,424 +0,0 @@ -Purpose of this document -======================== - -This document gives an overview of how Postfix can be used for -hosting multiple Internet domains, both for final delivery on the -machine itself and for the purpose of forwarding to destinations -elsewhere. - -The text not only describes delivery mechanisms that are built into -Postfix, but also gives pointers for using non-Postfix mail delivery -software. - -The following topics are covered: - -- Preliminaries - - Local files versus databases - - Canonical versus hosted domains -- As simple as can be: shared domains, UNIX system accounts -- Postfix virtual alias domains: separate domains, UNIX system accounts -- Postfix virtual mailbox domains: separate domains, non-UNIX accounts -- Non-Postfix mailbox store: separate domains, non-UNIX accounts -- Mail forwarding domains -- Aliases, mailing lists, etc. - -Preliminaries: local files versus databases -=========================================== - -The examples in this text use table lookups from local files. -These are easy to debug with the postmap "-q" command option. - -Example: postmap -q info@example.com hash:/etc/postfix/virtual - -See LDAP_README, MYSQL_README and PGSQL_README for how to replace -local files by databases. The reader is strongly advised to make -the system work with local files before migrating to database files, -and to use the postmap "-q" command option to verify that database -lookups produce the exact same results as local file lookup. - -Example: postmap -q info@example.com ldap:/etc/postfix/virtual.cf - -Preliminaries: canonical versus hosted domains -============================================== - -Most Postfix systems do final email delivery for only a few domain -names. These include the names of the machine that Postfix runs -on, and sometimes include their parent domain. The remainder of -this document will refer to these domains as the canonical domains. - -Besides the canonical domains, Postfix can be configured to do -final delivery for any number of additional domains. These domains -are called hosted, because they are not directly associated with -the name of the machine itself. - -As simple as can be: shared domains, UNIX system accounts -========================================================= - -The simplest method to host an additional domain is to add the -domain name to the domains listed in the Postfix mydestination -configuration parameter, and to add the user names to the UNIX -password file. - -This approach makes no distinction between canonical and hosted -domains. Each username can receive mail in every domain. - -In the examples we will use "example.com" as the domain that is -being hosted on the local Postfix machine. - -/etc/postfix/main.cf: - mydestination = $myhostname localhost.$mydomain ... example.com - -The downside of this approach is a total lack of separation: mail -for info@my.host.name is delivered to the same UNIX system account -as mail for info@example.com. - -Another downside of listing all users in the UNIX password file is -that administration of large numbers of users becomes inconvenient. - -Postfix virtual ALIAS domains: separate domains, UNIX system accounts -===================================================================== - -The approach described in this section maintains separation between -email addresses in canonical and hosted domains, while still using -UNIX system accounts. - -With virtual alias domains, each hosted address is aliased to a -UNIX system account. The example below shows how to use this -mechanism for the example.com domain. - -/etc/postfix/main.cf: - virtual_alias_domains = example.com ...other hosted domains... - virtual_alias_maps = hash:/etc/postfix/virtual - -/etc/postfix/virtual: - postmaster@example.com postmaster - info@example.com joe - sales@example.com jane - # Uncomment entry below to implement a catch-all address - # @example.com jim - ...virtual aliases for other domains... - -The virtual_alias_domains setting tells Postfix that example.com -is a so-called virtual alias domain. If you omit this setting then -Postfix will reject mail (relay access denied) or will not be able -to deliver it (mail for example.com loops back to myself). - -NEVER list a virtual alias domain name as a mydestination domain! - -The /etc/postfix/virtual file contains the virtual aliases. With -the example above, mail for postmaster@example.com goes to the -local postmaster, while mail for info@example.com goes to the UNIX -account joe, and mail for sales@example.com goes to the UNIX account -jane. Mail for all other addresses in example.com is rejected with -the error message "User unknown". - -The commented out entry (text after #) shows how one would implement -a catch-all virtual alias that receives mail for every example.com -address not listed in the virtual alias file. This is not without -risk. Spammers nowadays try to send mail from (or mail to) every -possible name that they can think of. A catch-all mailbox is likely -to receive many spam messages, and many bounces for spam messages -that were sent in the name of anything@example.com. - -Execute the command "postmap /etc/postfix/virtual" after changing -the virtual file, and execute the command "postfix reload" after -changing the main.cf file. - -Note: virtual aliases can resolve to a local address or to a remote -address, or both. They don't have to resolve to UNIX system accounts -on your machine. - -More details about the virtual alias file are given in the virtual(5) -manual page, including multiple addresses on the right-hand side. - -Virtual aliasing solves one problem: it allows each domain to have -its own info mail address. But there still is one drawback: each -virtual address is aliased to a UNIX system account. As you add -more virtual addresses you also add more UNIX system accounts. -The next section eliminates this problem. - -Postfix virtual MAILBOX domains: separate domains, non-UNIX accounts -==================================================================== - -As a system hosts more and more domains and users, it becomes -less desirable to give everyone their own UNIX system account. - -With the Postfix virtual delivery agent, every recipient address -can have its own virtual mailbox. Unlike virtual alias domains, -there is no translation from recipient addresses into different -addresses. - -The Postfix virtual delivery agent looks up the user mailbox -pathname, uid and gid via separate tables that are searched with -the recipient's mail address. Maildir style delivery is turned on -by terminating the mailbox pathname with "/". - -If you find the idea of multiple tables bothersome, remember that -you can migrate the information (once it works), to an SQL database. -If you take that route, be sure to review the "local files versus -databases" section at the top of this document. - -Here is an example of a virtual mailbox domain example.com: - -/etc/postfix/main.cf: - virtual_mailbox_domains = example.com ...other domains... - virtual_mailbox_base = /var/mail/vhosts - virtual_mailbox_maps = hash:/etc/postfix/vmailbox - virtual_minimum_uid = 100 - virtual_uid_maps = static:5000 - virtual_gid_maps = static:5000 - virtual_alias_maps = hash:/etc/postfix/virtual - -/etc/postfix/vmailbox: - info@example.com example.com/info - sales@example.com example.com/sales/ - # Comment out the entry below to implement a catch-all. - # @example.com example.com/catchall - ...virtual mailboxes for other domains... - -/etc/postfix/virtual: - postmaster@example.com postmaster - -This example assumes that main.cf lists the value of myorigin in -the mydestination parameter setting. If that is not the case, -specify an explicit domain name on the right-hand side of the -virtual alias table entries. - -The virtual_mailbox_domains setting tells Postfix that example.com -is a so-called virtual mailbox domain. If you omit this setting -then Postfix will reject mail (relay access denied) or will not be -able to deliver it (mail for example.com loops back to myself). - -NEVER list a virtual MAILBOX domain name as a mydestination domain! - -NEVER list a virtual MAILBOX domain name as a virtual ALIAS domain! - -The virtual_mailbox_base parameter specifies a prefix for all -virtual mailbox pathnames. This is a safety mechanism in case -someone makes a mistake. It prevents mail from being delivered all -over the file system. - -The virtual_mailbox_maps parameter specifies the lookup table with -mailbox (or maildir) pathnames, indexed by the virtual mail address. -In this example, mail for info@example.com goes to the mailbox at -/var/mail/vhosts/example.com/info while mail for sales@example.com -goes to the maildir located at /var/mail/vhosts/example.com/sales/. - -The virtual_minimum_uid prevents specifies a lower bound on the -mailbox or maildir owner's UID. This is a safety mechanism in case -someone makes a mistake. It prevents mail from being written to -sensitive files. - -In the above example, the virtual_uid_maps and virtual_gid_maps -parameters specify that all the virtual mailboxes are owned by a -fixed uid and gid 5000. If this is not what you want, specify -lookup tables that are searched by the recipient's mail address. - -The commented out entry (text after #) shows how one would implement -a catch-all virtual mailbox address. Be prepared to receive a lot -of spam, as well as bounced spam that was sent in the name of -anything@example.com. - -NEVER put a virtual MAILBOX wild-card in the virtual ALIAS file!! - -As you see above, it is possible to mix virtual aliases with virtual -mailboxes. We use this feature to redirect mail for example.com's -postmaster address to the local postmaster. You can use the same -mechanism to redirect an addresses to a remote address. - -This approach maintains separation between canonical domains and -hosted domains by listing the domain names in mydestination and -virtual_mailbox_domains, respectively. - -The separation between hosted domains is maintained by listing the -full email addresses in the virtual mailbox map. - -Execute the command "postmap /etc/postfix/virtual" after changing -the virtual file, execute "postmap /etc/postfix/vmailbox" after -changing the vmailbox file, and execute the command "postfix reload" -after changing the main.cf file. - -Note: mail delivery happens with the recipient's UID/GID privileges. -Postfix will not create mailDIRs; you must create them in advance -before you can use them. Postfix may be able to create mailBOX -files by itself, depending on directory write permissions, but it -is safer to create mailBOX files ahead of time. - -More details about the virtual mailbox delivery agent are given -in the file VIRTUAL_MAILBOX_README, and in the virtual(8) manual -page. - -Non-Postfix mailbox store: separate domains, non-UNIX accounts -============================================================== - -This is a variation on the Postfix virtual mailbox domain mechanism. -Again, every hosted address can have its own mailbox. - -While non-Postfix software is being used for final delivery, some -Postfix concepts are still needed in order to glue everything -together. For additional background on this glue you may want to -take a look at the ADDRESS_CLASS_README file. - -The text in this section describes what things should look like -from Postfix's point of view. See LMTP_README or MAILDROP_README -for specific information about Cyrus or about Courier maildrop. - -Here is an example for a hosted domain example.com that delivers -to a non-Postfix delivery agent: - -/etc/postfix/main.cf: - virtual_transport = ...see below... - virtual_mailbox_domains = example.com ...other domains... - virtual_mailbox_maps = hash:/etc/postfix/vmailbox - virtual_alias_maps = hash:/etc/postfix/virtual - -/etc/postfix/vmailbox: - info@example.com whatever - sales@example.com whatever - # Comment out the entry below to implement a catch-all. - # You also need to configure the mailbox store to accept all addresses. - # @example.com whatever - ...virtual mailboxes for other domains... - -/etc/postfix/virtual: - postmaster@example.com postmaster - -This example assumes that main.cf lists the value of myorigin in -the mydestination parameter setting. If that is not the case, -specify an explicit domain name on the right-hand side of any -virtual alias table entries. - -With delivery to a non-Postfix mailbox store for hosted domains, -the virtual_transport parameter usually specifies the Postfix LMTP -client, or the name of a master.cf entry that executes non-Postfix -software via the pipe delivery agent. Typical examples: - - virtual_transport = lmtp:unix:/path/name (uses UNIX-domain socket) - virtual_transport = lmtp:hostname:port (uses TCP socket) - virtual_transport = maildrop: (uses pipe(8) to command) - -Postfix comes ready with support for LMTP. And an example maildrop -delivery method is already defined in the default Postfix master.cf -file. - -In the main.cf file example above, the virtual_mailbox_domains -setting tells Postfix that example.com is delivered via the -virtual_transport that was discussed in the previous paragraph. If -you omit this virtual_mailbox_domains setting then Postfix will -either reject mail (relay access denied) or will not be able to -deliver it (mail for example.com loops back to myself). - -NEVER list a virtual MAILBOX domain name as a mydestination domain! - -NEVER list a virtual MAILBOX domain name as a virtual ALIAS domain! - -The virtual_mailbox_maps parameter above specifies the lookup table -with all valid recipient addresses. The lookup result is ignored -by Postfix. In the above example, info@example.com and sales@example.com -are listed as valid addresses, and mail for anything else is rejected -with "User unknown". If you intend to use LDAP, MySQL or PgSQL -instead of local files, be sure to review the "local files versus -databases" section at the top of this document! - -The commented out entry (text after #) shows how one would inform -Postfix of the existence of a catch-all address. Again, the lookup -result is ignored by Postfix. - -NEVER put a virtual MAILBOX wild-card in the virtual ALIAS file!! - -Note: if you specify a wildcard in virtual_mailbox_maps, then you -still need to configure the non-Postfix mailbox store to receive -mail for any address in that domain. - -As you see above, it is possible to mix virtual aliases with virtual -mailboxes. We use this feature to redirect mail for example.com's -postmaster address to the local postmaster. You can use the same -mechanism to redirect any addresses to a local or remote address. - -Execute the command "postmap /etc/postfix/virtual" after changing -the virtual file, execute "postmap /etc/postfix/vmailbox" after -changing the vmailbox file, and execute the command "postfix reload" -after changing the main.cf file. - -Mail forwarding domains -======================= - -Some providers host domains that have no (or only a few) local -mailboxes. The main purpose of these domains is to forward mail -elsewhere. The following example shows how to set up example.com -as a mail forwarding domain: - -/etc/postfix/main.cf: - virtual_alias_domains = example.com ...other hosted domains... - virtual_alias_maps = hash:/etc/postfix/virtual - -/etc/postfix/virtual: - postmaster@example.com postmaster - joe@example.com joe@somewhere - jane@example.com jane@somewhere-else - # Uncomment entry below to implement a catch-all address - # @example.com jim@yet-another-site - ...virtual aliases for other domains... - -The virtual_alias_domains setting tells Postfix that example.com -is a so-called virtual alias domain. If you omit this setting then -Postfix will reject mail (relay access denied) or will not be able -to deliver it (mail for example.com loops back to myself). - -NEVER list a virtual alias domain name as a mydestination domain! - -The /etc/postfix/virtual file contains the virtual aliases. With -the example above, mail for postmaster@example.com goes to the -local postmaster, while mail for joe@example.com goes to the remote -address joe@somewhere, and mail for jane@example.com goes to the -remote address jane@somewhere-else. Mail for all other addresses -in example.com is rejected with the error message "User unknown". - -The commented out entry (text after #) shows how one would implement -a catch-all virtual alias that receives mail for every example.com -address not listed in the virtual alias file. This is not without -risk. Spammers nowadays try to send mail from (or mail to) every -possible name that they can think of. A catch-all mailbox is likely -to receive many spam messages, and many bounces for spam messages -that were sent in the name of anything@example.com. - -Execute the command "postmap /etc/postfix/virtual" after changing -the virtual file, and execute the command "postfix reload" after -changing the main.cf file. - -More details about the virtual alias file are given in the virtual(5) -manual page, including multiple addresses on the right-hand side. - -Aliases, mailing lists, etc. -============================ - -The examples that were given above already show how to direct mail -for virtual postmaster addresses to a local postmaster. You can -use the same method to direct mail for any address to a local or -remote address. - -There is one major limitation: virtual aliases and virtual mailboxes -can't directly deliver to mailing list managers such as majordomo. -The solution is to set up virtual aliases that direct virtual -addresses to the local delivery agent: - -/etc/postfix/main.cf: - virtual_alias_maps = hash:/etc/postfix/virtual - -/etc/postfix/virtual: - listname-request@example.com listname-request - listname@example.com listname - owner-listname@example.com owner-listname - -/etc/aliases: - listname: "|/some/where/majordomo/wrapper ..." - owner-listname: ... - listname-request: ... - -This example assumes that main.cf lists the value of myorigin in -the mydestination parameter setting. If that is not the case, -specify an explicit domain name on the right-hand side of the -virtual alias table. - -More information about the Postfix local delivery agent can be -found in the local(8) manual page. diff --git a/postfix/README_FILES/INSTALL b/postfix/README_FILES/INSTALL deleted file mode 120000 index 99d491b4f..000000000 --- a/postfix/README_FILES/INSTALL +++ /dev/null @@ -1 +0,0 @@ -../INSTALL \ No newline at end of file diff --git a/postfix/README_FILES/INSTALL b/postfix/README_FILES/INSTALL new file mode 100644 index 000000000..524afb53e --- /dev/null +++ b/postfix/README_FILES/INSTALL @@ -0,0 +1,688 @@ +PPoossttffiixx IInnssttaallllaattiioonn FFrroomm SSoouurrccee CCooddee + +------------------------------------------------------------------------------- + +11 -- PPuurrppoossee ooff tthhiiss ddooccuummeenntt + +This is a bootstrap document that helps you get Postfix up and running from +scratch with the minimal number of steps. If you are using a pre-compiled +version of Postfix, you should be reading the general Postfix documentation +which aims to describe the system in more detail. This bootstrap document +should not be considered part of the general Postfix documentation. + +This document describes how to build, install and configure a Postfix system so +that it can do one of the following: + + * Send mail only, without changing an existing Sendmail installation. + * Send and receive mail via a virtual host interface, still without any + change to an existing Sendmail installation. + * Run Postfix instead of Sendmail. + +Topics covered in this document: + + 1. Purpose of this document + 2. Typographical conventions + 3. Documentation + 4. Building on a supported system + 5. Porting Postfix to an unsupported system + 6. Installing the software after successful compilation + 7. Configuring Postfix to send mail only + 8. Configuring Postfix to send and receive mail via virtual interface + 9. Running Postfix instead of Sendmail +10. Mandatory configuration file edits +11. To chroot or not to chroot +12. Care and feeding of the Postfix system + +22 -- TTyyppooggrraapphhiiccaall ccoonnvveennttiioonnss + +In the instructions below, a command written as + + # command + +should be executed as the superuser. + +A command written as + + % command + +should be executed as an unprivileged user. + +33 -- DDooccuummeennttaattiioonn + +Documentation is available as README files (start with the file README_FILES/ +AAAREADME), as HTML web pages (point your browser to "html/index.html") and as +UNIX-style manual pages. + +You should view the README files with a pager such as more(1) or less(1), +because the files use backspace characters in order to produce bboolldd font. To +print a README file without backspace characters, use the col(1) command. For +example: + + % col -bx directly (which is +not allowed) and overriding the __FD_SETSIZE macro. Beware, undocumented +interfaces can change at any time and without warning. + +44..66 -- CCoommppiilliinngg PPoossttffiixx,, aatt llaasstt + +If the command + + % make + +is successful, then you can proceed to install Postfix (section 6). + +If the command produces compiler error messages, it may be time to search the +web or to ask the postfix-users@postfix.org mailing list, but be sure to search +the mailing list archives first. Some mailing list archives are linked from +http://www.postfix.org/. + +55 -- PPoorrttiinngg PPoossttffiixx ttoo aann uunnssuuppppoorrtteedd ssyysstteemm + +Each system type that Postfix knows is identified by a unique name. Examples: +SUNOS5, FREEBSD4, and so on. When porting Postfix to a new system, the first +step is to choose a SYSTEMTYPE name for the new system. You must use a name +that includes at least the major version of the operating system (such as +SUNOS4 or LINUX2), so that different releases of the same system can be +supported without confusion. + +Add a case statement to the "makedefs" shell script in the source code top- +level directory that recognizes the new system reliably, and that emits the +right system-specific information. Be sure to make the code robust against user +PATH settings; if the system offers multiple UNIX flavors (e.g. BSD and SYSV) +be sure to build for the native flavor, instead of the emulated one. + +Add an "#ifdef SYSTEMTYPE" section to the central util/sys_defs.h include file. +You may have to invent new feature macro names. Please choose sensible feature +macro names such as HAS_DBM or FIONREAD_IN_SYS_FILIO_H. + +I strongly recommend against using "#ifdef SYSTEMTYPE" in individual source +files. While this may look like the quickest solution, it will create a mess +when newer versions of the same SYSTEMTYPE need to be supported. You're likely +to end up placing "#ifdef" sections all over the source code again. + +66 -- IInnssttaalllliinngg tthhee ssooffttwwaarree aafftteerr ssuucccceessssffuull ccoommppiillaattiioonn + +This text describes how to install Postfix from source code. See the +PACKAGE_README file if you are building a package for distribution to other +systems. See auxiliary/MacOSX/README-INSTALL.OSX for information about +installing Postfix from source on Mac OS X. + +66..11 -- SSaavvee eexxiissttiinngg SSeennddmmaaiill bbiinnaarriieess + +IMPORTANT: if you are REPLACING an existing Sendmail installation with Postfix, +you may need to keep the old sendmail program running for some time in order to +flush the mail queue. As superuser, execute the following commands (your +sendmail, newaliases and mailq programs may be in a different place): + + # mv /usr/sbin/sendmail /usr/sbin/sendmail.OFF + # mv /usr/bin/newaliases /usr/bin/newaliases.OFF + # mv /usr/bin/mailq /usr/bin/mailq.OFF + # chmod 755 /usr/sbin/sendmail.OFF /usr/bin/newaliases.OFF \ + /usr/bin/mailq.OFF + +66..22 -- CCrreeaattee aaccccoouunntt aanndd ggrroouuppss + +Before you install Postfix for the first time you need to create an account and +a group: + + * Create a user account "postfix" with a user id and group id that are not + used by any other user account. Preferably, this is an account that no-one + can log into. The account does not need an executable login shell, and + needs no existing home directory. My password and group file entries look + like this: + + /etc/passwd: + postfix:*:12345:12345:postfix:/no/where:/no/shell + + /etc/group: + postfix:*:12345: + + Note: there should be no whitespace before "postfix:". + + * Make sure there is a "postfix" alias in /etc/aliases, or whatever the + pathname of your aliases file is; the command "postconf alias_maps" will + tell you. + + /etc/aliases: + postfix: root + + Note: there should be no whitespace before "postfix:". + + * Create a group "postdrop" with a group id that is not used by any other + user account. Not even by the postfix user account. My group file entry + looks like: + + /etc/group: + postdrop:*:54321: + + Note: there should be no whitespace before "postdrop:". + +66..33 -- IInnssttaallll PPoossttffiixx + +To install or upgrade Postfix from compiled source code, run one of the +following commands as the super-user: + + # make install (interactive version, first time install) + + # make upgrade (non-interactive version, for upgrades) + + * The non-interactive version ("make upgrade") needs the /etc/postfix/main.cf + file from a previous installation. If the file does not exist, use + interactive installation ("make install") instead. + + * The interactive version offers suggestions for pathnames that you can + override interactively, and stores your preferences in /etc/postfix/main.cf + for convenient future upgrades. + +66..44 -- CCoonnffiigguurree PPoossttffiixx + +Proceed to the section on how you wish to run Postfix on your particular +machine: + + * Send mail only, without changing an existing Sendmail installation (section + 7). + + * Send and receive mail via a virtual host interface, still without any + change to an existing Sendmail installation (section 8). + + * Run Postfix instead of Sendmail (section 9). + +77 -- CCoonnffiigguurriinngg PPoossttffiixx ttoo sseenndd mmaaiill oonnllyy + +If you are going to use Postfix to send mail only, there is no need to change +your existing sendmail setup. Instead, set up your mail user agent so that it +calls the Postfix sendmail program directly. + +Follow the instructions in the "Mandatory configuration file edits" in section +10, and review the "To chroot or not to chroot" text in section 11. + +You MUST comment out the "smtp inet" entry in /etc/postfix/master.cf, in order +to avoid conflicts with the real sendmail. Put a "#" character in front of the +line that defines the smtpd service: + + /etc/postfix/master.cf: + #smtp inet n - n - - smtpd + +Start the Postfix system: + + # postfix start + +or, if you feel nostalgic, use the Postfix sendmail command: + + # sendmail -bd -qwhatever + +and watch your maillog file for any error messages. The pathname is /var/log/ +maillog, /var/log/mail, /var/log/syslog, or something else. Typically, the +pathname is defined in the /etc/syslog.conf file. + + % egrep '(reject|warning|error|fatal|panic):' /some/log/file + +Note: the most important error message is logged first. Later messages are not +as useful. + +In order to inspect the mail queue, use one of the following commands: + + % mailq + + % sendmail -bp + + % postqueue -p + +See also the "Care and feeding" section 12 below. + +88 -- CCoonnffiigguurriinngg PPoossttffiixx ttoo sseenndd aanndd rreecceeiivvee mmaaiill vviiaa vviirrttuuaall iinntteerrffaaccee + +Alternatively, you can use the Postfix system to send AND receive mail while +leaving your Sendmail setup intact, by running Postfix on a virtual interface +address. Simply configure your mail user agent to directly invoke the Postfix +sendmail program. + +In the /etc/postfix/main.cf file, I would specify + + /etc/postfix/main.cf: + myhostname = virtual.host.tld + inet_interfaces = $myhostname + mydestination = $myhostname + +Follow the instructions in the "Mandatory configuration file edits" in section +10, and review the "To chroot or not to chroot" text in section 11. + +Start the Postfix system: + + # postfix start + +or, if you feel nostalgic, use the Postfix sendmail command: + + # sendmail -bd -qwhatever + +and watch your maillog file for any error messages. The pathname is /var/log/ +maillog, /var/log/mail, /var/log/syslog, or something else. Typically, the +pathname is defined in the /etc/syslog.conf file. + + % egrep '(reject|warning|error|fatal|panic):' /some/log/file + +Note: the most important error message is logged first. Later messages are not +as useful. + +In order to inspect the mail queue, use one of the following commands: + + % mailq + + % sendmail -bp + + % postqueue -p + +See also the "Care and feeding" section 12 below. + +99 -- RRuunnnniinngg PPoossttffiixx iinnsstteeaadd ooff SSeennddmmaaiill + +Prior to installing Postfix you should save any existing sendmail program files +as described in section 6. Be sure to keep the old sendmail running for at +least a couple days to flush any unsent mail. To do so, stop the sendmail +daemon and restart it as: + + # /usr/sbin/sendmail.OFF -q + +Note: this is old sendmail syntax. Newer versions use separate processes for +mail submission and for running the queue. + +After you have visited the "Mandatory configuration file edits" section below, +you can start the Postfix system with: + + # postfix start + +or, if you feel nostalgic, use the Postfix sendmail command: + + # sendmail -bd -qwhatever + +and watch your maillog file for any error messages. The pathname is /var/log/ +maillog, /var/log/mail, /var/log/syslog, or someting else. Typically, the +pathname is defined in the /etc/syslog.conf file. + + % egrep '(reject|warning|error|fatal|panic):' /some/log/file + +Note: the most important error message is logged first. Later messages are not +as useful. + +In order to inspect the mail queue, use one of the following commands: + + % mailq + + % sendmail -bp + + % postqueue -p + +See also the "Care and feeding" section 12 below. + +1100 -- MMaannddaattoorryy ccoonnffiigguurraattiioonn ffiillee eeddiittss + +Note: the material covered in this section is covered in more detail in the +BASIC_CONFIGURATION_README document. The information presented below is +targeted at experienced system administrators. + +1100..11 -- PPoossttffiixx ccoonnffiigguurraattiioonn ffiilleess + +By default, Postfix configuration files are in /etc/postfix. The two most +important files are main.cf and master.cf; these files must be owned by root. +Giving someone else write permission to main.cf or master.cf (or to their +parent directories) means giving root privileges to that person. + +In /etc/postfix/main.cf, you will have to set up a minimal number of +configuration parameters. Postfix configuration parameters resemble shell +variables, with two important differences: the first one is that Postfix does +not know about quotes like the UNIX shell does. + +You specify a configuration parameter as: + + /etc/postfix/main.cf: + parameter = value + +and you use it by putting a "$" character in front of its name: + + /etc/postfix/main.cf: + other_parameter = $parameter + +You can use $parameter before it is given a value (that is the second main +difference with UNIX shell variables). The Postfix configuration language uses +lazy evaluation, and does not look at a parameter value until it is needed at +runtime. + +Whenever you make a change to the main.cf or master.cf file, execute the +following command in order to refresh a running mail system: + + # postfix reload + +1100..22 -- DDeeffaauulltt ddoommaaiinn ffoorr uunnqquuaalliiffiieedd aaddddrreesssseess + +First of all, you must specify what domain will be appended to an unqualified +address (i.e. an address without @domain.tld). The "myorigin" parameter +defaults to the local hostname, but that is probably OK only for very small +sites. + +Some examples (use only one): + + /etc/postfix/main.cf: + myorigin = $myhostname (send mail as "user@$myhostname") + myorigin = $mydomain (send mail as "user@$mydomain") + +1100..33 -- WWhhaatt ddoommaaiinnss ttoo rreecceeiivvee llooccaallllyy + +Next you need to specify what mail addresses Postfix should deliver locally. + +Some examples (use only one): + + /etc/postfix/main.cf: + mydestination = $myhostname, localhost.$mydomain, localhost + mydestination = $myhostname, localhost.$mydomain, localhost, $mydomain + mydestination = $myhostname + +The first example is appropriate for a workstation, the second is appropriate +for the mailserver for an entire domain. The third example should be used when +running on a virtual host interface. + +1100..44 -- PPrrooxxyy//NNAATT iinntteerrffaaccee aaddddrreesssseess + +The proxy_interfaces parameter specifies all network addresses that Postfix +receives mail on by way of a proxy or network address translation unit. You may +specify symbolic hostnames instead of network addresses. + +IMPORTANT: You must specify your proxy/NAT external addresses when your system +is a backup MX host for other domains, otherwise mail delivery loops will +happen when the primary MX host is down. + +Example: host behind NAT box running a backup MX host. + + /etc/postfix/main.cf: + proxy_interfaces = 1.2.3.4 (the proxy/NAT external network address) + +1100..55 -- WWhhaatt llooccaall cclliieennttss ttoo rreellaayy mmaaiill ffrroomm + +If your machine is on an open network then you must specify what client IP +addresses are authorized to relay their mail through your machine into the +Internet. The default setting includes all subnetworks that the machine is +attached to. This may give relay permission to too many clients. My own +settings are: + + /etc/postfix/main.cf: + mynetworks = 168.100.189.0/28, 127.0.0.0/8 + +1100..66 -- WWhhaatt rreellaayy ddeessttiinnaattiioonnss ttoo aacccceepptt ffrroomm ssttrraannggeerrss + +If your machine is on an open network then you must also specify whether +Postfix will forward mail from strangers. The default setting will forward mail +to all domains (and subdomains of) what is listed in $mydestination. This may +give relay permission for too many destinations. Recommended settings (use only +one): + + /etc/postfix/main.cf: + relay_domains = (do not forward mail from strangers) + relay_domains = $mydomain (my domain and subdomains) + relay_domains = $mydomain, other.domain.tld, ... + +1100..77 -- OOppttiioonnaall:: ccoonnffiigguurree aa ssmmaarrtt hhoosstt ffoorr rreemmoottee ddeelliivveerryy + +If you're behind a firewall, you should set up a relayhost. If you can, specify +the organizational domain name so that Postfix can use DNS lookups, and so that +it can fall back to a secondary MX host when the primary MX host is down. +Otherwise just specify a hard-coded hostname. + +Some examples (use only one): + + /etc/postfix/main.cf: + relayhost = $mydomain + relayhost = [mail.$mydomain] + +The form enclosed with [] eliminates DNS MX lookups. + +By default, the SMTP client will do DNS lookups even when you specify a relay +host. If your machine has no access to a DNS server, turn off SMTP client DNS +lookups like this: + + /etc/postfix/main.cf: + disable_dns_lookups = yes + +The STANDARD_CONFIGURATION_README file has more hints and tips for firewalled +and/or dial-up networks. + +1100..88 -- CCrreeaattee tthhee aalliiaasseess ddaattaabbaassee + +Finally, if you haven't used Sendmail prior to using Postfix, you will have to +build the alias database with one of the following commands: + + # newaliases + # sendmail -bi + +Be sure to set up aliases for root and postmaster that forward mail to a real +person. Postfix has a sample aliases file /etc/postfix/aliases that you can +adapt to local conditions. + +1111 -- TToo cchhrroooott oorr nnoott ttoo cchhrroooott + +Postfix daemon processes can be configured (via master.cf) to run in a chroot +jail. The processes run at a fixed low privilege and with access only to the +Postfix queue directories (/var/spool/postfix). This provides a significant +barrier against intrusion. The barrier is not impenetrable, but every little +bit helps. + +With the exception of Postfix daemons that deliver mail locally and/or that +execute non-Postfix commands, every Postfix daemon can run chrooted. + +Sites with high security requirements should consider to chroot all daemons +that talk to the network: the smtp(8) and smtpd(8) processes, and perhaps also +the lmtp(8) client. The author's own porcupine.org mail server runs all daemons +chrooted that can be chrooted. + +The default /etc/postfix/master.cf file specifies that no Postfix daemon runs +chrooted. In order to enable chroot operation, edit the file /etc/postfix/ +master.cf. Instructions are in the file. + +Note that a chrooted daemon resolves all filenames relative to the Postfix +queue directory (/var/spool/postfix). For successful use of a chroot jail, most +UNIX systems require you to bring in some files or device nodes. The examples/ +chroot-setup directory in the source code distribution has a collection of +scripts that help you set up Postfix chroot environments on different operating +systems. + +Additionally, you almost certainly need to configure syslogd so that it listens +on a socket inside the Postfix queue directory. Examples for specific systems: + +FreeBSD: syslogd -l /var/spool/postfix/var/run/log + +Linux, OpenBSD: syslogd -a /var/spool/postfix/dev/log + +1122 -- CCaarree aanndd ffeeeeddiinngg ooff tthhee PPoossttffiixx ssyysstteemm + +Postfix daemon processes run in the background, and log problems and normal +activity to the syslog daemon. The names of logfiles are specified in /etc/ +syslog.conf. At the very least you need something like: + + /etc/syslog.conf: + mail.err /dev/console + mail.debug /var/log/maillog + +IMPORTANT: the syslogd will not create files. You must create them before +(re)starting syslogd. + +IMPORTANT: on Linux you need to put a "-" character before the pathname, e.g., +-/var/log/maillog, otherwise the syslogd will use more system resources than +Postfix does. + +Hopefully, the number of problems will be small, but it is a good idea to run +every night before the syslog files are rotated: + + # postfix check + # egrep '(reject|warning|error|fatal|panic):' /some/log/file + + * The first line (postfix check) causes Postfix to report file permission/ + ownership discrepancies. + + * The second line looks for problem reports from the mail software, and + reports how effective the relay and junk mail access blocks are. This may + produce a lot of output. You will want to apply some postprocessing to + eliminate uninteresting information. + +The DEBUG_README document describes the meaning of the "warning" etc. labels in +Postfix logging. + diff --git a/postfix/README_FILES/LDAP_README b/postfix/README_FILES/LDAP_README index 72ce12363..39dc85c91 100644 --- a/postfix/README_FILES/LDAP_README +++ b/postfix/README_FILES/LDAP_README @@ -1,475 +1,247 @@ -LDAP SUPPORT IN POSTFIX -======================= +PPoossttffiixx LLDDAAPP HHoowwttoo -Postfix can use an LDAP directory as a source for any of its lookups: -aliases, virtual, canonical, etc. This allows you to keep information -for your mail service in a replicated network database with fine-grained -access controls. By not storing it locally on the mail server, the -administrators can maintain it from anywhere, and the users can control -whatever bits of it you think appropriate. You can have multiple mail -servers using the same information, without the hassle and delay of -having to copy it to each. +------------------------------------------------------------------------------- -BUILDING WITH LDAP SUPPORT -========================== +LLDDAAPP SSuuppppoorrtt iinn PPoossttffiixx -Note: Postfix no longer supports the LDAP version 1 interface. +Postfix can use an LDAP directory as a source for any of its lookups: aliases +(5), virtual(5), canonical(5), etc. This allows you to keep information for +your mail service in a replicated network database with fine-grained access +controls. By not storing it locally on the mail server, the administrators can +maintain it from anywhere, and the users can control whatever bits of it you +think appropriate. You can have multiple mail servers using the same +information, without the hassle and delay of having to copy it to each. -You need to have LDAP libraries and include files installed somewhere -on your system, and you need to configure the Postfix Makefiles -accordingly. +Topics covered in this document: -For example, to build the OpenLDAP libraries for use with Postfix -(i.e. LDAP client code only), you could use the following command: + * Building Postfix with LDAP support + * Configuring LDAP lookups + * Example: aliases + * Example: virtual domains/addresses + * Other uses of LDAP lookups + * Notes and things to think about + * Feedback + * Credits + +BBuuiillddiinngg PPoossttffiixx wwiitthh LLDDAAPP ssuuppppoorrtt + +Note 1: Postfix no longer supports the LDAP version 1 interface. + +Note 2: to use LDAP with Debian GNU/Linux's Postfix, all you need is to install +the postfix-ldap package and you're done. There is no need to recompile +Postfix. + +You need to have LDAP libraries and include files installed somewhere on your +system, and you need to configure the Postfix Makefiles accordingly. + +For example, to build the OpenLDAP libraries for use with Postfix (i.e. LDAP +client code only), you could use the following command: % ./configure --without-kerberos --without-cyrus-sasl --without-tls \ - --without-threads --disable-slapd --disable-slurpd \ - --disable-debug --disable-shared + --without-threads --disable-slapd --disable-slurpd \ + --disable-debug --disable-shared -If you're using the libraries from the UM distribution -(http://www.umich.edu/~dirsvcs/ldap/ldap.html) or OpenLDAP -(http://www.openldap.org), something like this in the top level of your -Postfix source tree should work: +If you're using the libraries from the UM distribution (http://www.umich.edu/ +~dirsvcs/ldap/ldap.html) or OpenLDAP (http://www.openldap.org), something like +this in the top level of your Postfix source tree should work: % make tidy % make makefiles CCARGS="-I/usr/local/include -DHAS_LDAP" \ - AUXLIBS="-L/usr/local/lib -lldap -L/usr/local/lib -llber" + AUXLIBS="-L/usr/local/lib -lldap -L/usr/local/lib -llber" -On Solaris 2.x you may have to specify run-time link information, -otherwise ld.so will not find some of the shared libraries: +On Solaris 2.x you may have to specify run-time link information, otherwise +ld.so will not find some of the shared libraries: % make tidy % make makefiles CCARGS="-I/usr/local/include -DHAS_LDAP" \ - AUXLIBS="-L/usr/local/lib -R/usr/local/lib -lldap \ - -L/usr/local/lib -R/usr/local/lib -llber" + AUXLIBS="-L/usr/local/lib -R/usr/local/lib -lldap \ + -L/usr/local/lib -R/usr/local/lib -llber" -The 'make tidy' command is needed only if you have previously built -Postfix without LDAP support. +The 'make tidy' command is needed only if you have previously built Postfix +without LDAP support. -Instead of '/usr/local' specify the actual locations of your LDAP -include files and libraries. Be sure to not mix LDAP include files -and LDAP libraries of different versions!! +Instead of '/usr/local' specify the actual locations of your LDAP include files +and libraries. Be sure to not mix LDAP include files and LDAP libraries of +different versions!! -If your LDAP libraries were built with Kerberos support, you'll also -need to include your Kerberos libraries in this line. Note that the KTH -Kerberos IV libraries might conflict with Postfix's lib/libdns.a, which -defines dns_lookup. If that happens, you'll probably want to link with -LDAP libraries that lack Kerberos support just to build Postfix, as it -doesn't support Kerberos binds to the LDAP server anyway. Sorry about -the bother. +If your LDAP libraries were built with Kerberos support, you'll also need to +include your Kerberos libraries in this line. Note that the KTH Kerberos IV +libraries might conflict with Postfix's lib/libdns.a, which defines dns_lookup. +If that happens, you'll probably want to link with LDAP libraries that lack +Kerberos support just to build Postfix, as it doesn't support Kerberos binds to +the LDAP server anyway. Sorry about the bother. If you're using one of the Netscape LDAP SDKs, you'll need to change the -AUXLIBS line to point to libldap10.so or libldapssl30.so or whatever you -have, and you may need to use the appropriate linker option (e.g. '-R') -so the executables can find it at runtime. - -CONFIGURING LDAP LOOKUPS -======================== - -In order to use LDAP lookups, define at least one LDAP source as a table -lookup in main.cf, for example: - - alias_maps = hash:/etc/aliases, ldap:/etc/ldap-aliases.cf - -The file /etc/postfix/ldap-aliases.cf can specify the following -parameters. Defaults are given in parentheses: - - server_host (localhost) - The name of the host running the LDAP server, e.g. - server_host = ldap.your.com - It should be possible with all the libraries mentioned above - to specify multiple servers, with the libraries trying them in - order should the first one fail. It should also be possible to - give each server in the list a different port, by naming them - like "ldap.your.com:1444". - - With OpenLDAP, LDAP URLs can be used to request connection - over UNIX domain sockets (ldapi://%2Fsome%2Fpath) or LDAP SSL - (ldaps://ldap.your.com:636, provided OpenLDAP was compiled with - support for SSL). - - server_port (389) - The port the LDAP server listens on, e.g. - server_port = 778 - - search_base (No default; you must configure this.) - The RFC2253 base DN at which to conduct the search, e.g. - search_base = dc=your, dc=com - - timeout (10 seconds) - The number of seconds a search can take before timing out, e.g. - timeout = 5 - - query_filter (mailacceptinggeneralid=%s) - The RFC2254 filter used to search the directory, where %s is a - substitute for the address Postfix is trying to resolve, e.g. - query_filter = (&(mail=%s)(paid_up=true)) - See sample-ldap.cf for more details. - - result_filter (%s) - Format template applied to result attributes. Supports the same - expansions as the query_filter, and can be easily used to append - (or prepend) text. See sample-ldap.cf for more details. - - domain (Default is no domain list.) - This is a list of domain names, paths to files, or dictionaries. - When specified, only fully qualified search keys with a - *non-empty* localpart and a matching domain are eligible for - lookup: 'user' lookups, bare domain lookups and "@domain" lookups - are not performed. This can significantly reduce the query load - on the LDAP server. - domain = postfix.org, hash:/etc/postfix/searchdomains - It is best not to use LDAP to store the domains eligible for LDAP - lookups. - - result_attribute (maildrop) - The attribute(s) Postfix will read from any directory entries - returned by the lookup, to be resolved to an email address. - result_attribute = mailbox,maildrop - - special_result_attribute (No default) - The attribute(s) of directory entries that can contain DNs or URLs. - If found, a recursive subsequent search is done using their values. - special_result_attribute = member - DN recursion retrieves the same result_attributes as the main - query, including the special attributes for further recursion. - URI processing retrieves only those attributes that are included - in the URI definition and are *also* listed in "result_attribute". - If the URI lists any of the map's special result attributes, these - are also retrieved and used recursively. - - scope (sub) - The LDAP search scope: sub, base, or one. These translate into - LDAP_SCOPE_SUBTREE, LDAP_SCOPE_BASE, and LDAP_SCOPE_ONELEVEL. - - bind (yes) - Whether or not to bind to the LDAP server. Newer LDAP - implementations don't require clients to bind, which saves - time. Example: - bind = no - - If you do need to bind, you might consider configuring Postfix - to connect to the local machine on a port that's an SSL tunnel - to your LDAP server. If your LDAP server doesn't natively - support SSL, put a tunnel (wrapper, proxy, whatever you want to - call it) on that system too. This should prevent the password - from traversing the network in the clear. - - bind_dn ("") - If you do have to bind, do it with this distinguished name. - Example: - bind_dn = uid=postfix, dc=your, dc=com - - bind_pw ("") - The password for the distinguished name above. If you have to - use this, you probably want to make the map configuration file - readable only by the Postfix user. When using the obselete - ldap:ldapsource syntax, with map parameters in main.cf, it is - not possible to securely store the bind password. This is - because main.cf needs to be world readable to allow local - accounts to submit mail via the sendmail command. Example: - bind_pw = postfixpw - - cache (IGNORED with a warning) - cache_expiry (IGNORED with a warning) - cache_size (IGNORED with a warning) - The above parameters are NO LONGER SUPPORTED by Postfix. - Cache support has been dropped from OpenLDAP as of release 2.1.13. - - recursion_limit (1000) - A limit on the nesting depth of DN and URL special result - attribute evaluation. The limit must be a non-zero positive - number. - - expansion_limit (0) - A limit on the total number of result elements returned (as a - comma separated list) by a lookup against the map. A setting of - zero disables the limit. Lookups fail with a temporary error - if the limit is exceeded. Setting the limit to 1 ensures that - lookups do not return multiple values. - - size_limit ($expansion_limit) - A limit on the number of LDAP entries returned by any single LDAP - query performed as part of the lookup. A setting of 0 disables - the limit. Expansion of DN and URL references involves nested - LDAP queries, each of which is separately subjected to this - limit. - - Note: even a single LDAP entry can generate multiple lookup - results, via multiple result attributes and/or multi-valued - result attributes. This limit caps the per query resource - utilization on the LDAP server, not the final multiplicity of the - lookup result. It is analogous to the "-z" option of "ldapsearch". - - dereference (0) - When to dereference LDAP aliases. (Note that this has nothing - do with Postfix aliases.) The permitted values are those legal - for the OpenLDAP/UM LDAP implementations: - - 0 never - 1 when searching - 2 when locating the base object for the search - 3 always - - See ldap.h or the ldap_open(3) or ldapsearch(1) man pages for - more information. And if you're using an LDAP package that has - other possible values, please bring it to the attention of the - postfix-users@postfix.org mailing list. - - chase_referrals (0) - Sets (or clears) LDAP_OPT_REFERRALS (requires LDAP version 3 - support. - - version (2) - Specifies the LDAP protocol version to use. - - debuglevel (0) - What level to set for debugging in the OpenLDAP libraries. - -Don't use quotes in these variables; at least, not until the Postfix -configuration routines understand how to deal with quoted strings. - -For backward compatibility, these parameters can also be defined -in main.cf, prefixed with the name you've given the source in its -definition, and an underscore. For example, if the map is specified as -"ldap:ldapsource", the first parameter above, "server_host", would be -defined in main.cf as "ldapsource_server_host". - -LDAP SSL and STARTTLS ---------------------- - -If you're using the OpenLDAP libraries compiled with SSL support, -Postfix can connect to LDAP SSL servers and can issue the STARTTLS -command. The first form can be requested by using a LDAP URL in -server_host: - - server_host = ldaps://ldap.your.com:636 - -STARTTLS can be turned on with the start_tls command: - - start_tls = yes - -Both forms require LDAP protocol version 3, which has to be set -explicitly: - - version = 3 - -If any of the Postfix programs querying the map is configured in -master.cf to run chrooted, all the certificates and keys involved have -to be copied to the chroot jail. Of course, the private keys should -only be readable by the user "postfix". - -The following commands are relevant to LDAP SSL and STARTTLS: - - start_tls (no) - Whether or not to issue STARTTLS upon connection to - the server. Don't set this with LDAP SSL. - - tls_ca_cert_dir (No default; set either this or tls_ca_cert_file) - Directory containing, in separate individual files, - the X509 Certificate Authority certificates which - are to be recognized by the client in SSL/TLS con- - nections. - - tls_ca_cert_file (No default; set either this or tls_ca_cert_dir) - File containing the X509 Certificate Authority cer- - tificates which are to be recognized by the client - in SSL/TLS connections. This setting takes prece- - dence over tls_ca_cert_dir. - - tls_cert (No default; you must set this) - File containing client's X509 certificate to be - used by the client in SSL/TLS connections. - - tls_key (No default; you must set this) - File containing the private key corresponding to - the above tls_cert. - - tls_require_cert (no) - Whether or not to request server's X509 certificate - and check its validity when establishing SSL/TLS - connections. - - tls_random_file (No default) - Path of a file to obtain random bits from when - /dev/[u]random is not available, to be used by the - client in SSL/TLS connections. +AUXLIBS line to point to libldap10.so or libldapssl30.so or whatever you have, +and you may need to use the appropriate linker option (e.g. '-R') so the +executables can find it at runtime. + +CCoonnffiigguurriinngg LLDDAAPP llooookkuuppss + +In order to use LDAP lookups, define an LDAP source as a table lookup in +main.cf, for example: + + alias_maps = hash:/etc/aliases, ldap:/etc/postfix/ldap-aliases.cf - tls_cipher_suite (No default) - Cipher suite to use in SSL/TLS negotiations. - - -EXAMPLES -======== - -ALIASES -------- - -Here's a basic example for using LDAP to look up aliases. Assume that in -main.cf, you have: - -alias_maps = hash:/etc/aliases, ldap:/etc/ldap-aliases.cf - -and in ldap:/etc/ldap-aliases.cf you have: - -server_host = ldap.my.com -search_base = dc=my, dc=com - -Upon receiving mail for a local address "ldapuser" that isn't found in -the /etc/aliases database, Postfix will search the LDAP server listening -at port 389 on ldap.my.com. It will bind anonymously, search for any -directory entries whose mailacceptinggeneralid attribute is "ldapuser", -read the "maildrop" attributes of those found, and build a list of their -maildrops, which will be treated as RFC822 addresses to which the -message will be delivered. - -VIRTUAL DOMAINS/ADDRESSES -------------------------- - -If you want to keep information for virtual lookups in your directory, -it's only a little more complicated. First you need to make sure Postfix -knows about the virtual domain. An easy way to do that is to add the -domain to the mailacceptinggeneralid attribute of some entry in the -directory. Next you'll want to make sure all of your virtual recipients' -mailacceptinggeneralid attributes are fully qualified with their virtual -domains. Finally, if you want to designate a directory entry as the -default user for a virtual domain, just give it an additional -mailacceptinggeneralid (or the equivalent in your directory) of -"@virtual.dom". That's right, no user part. If you don't want a catchall -user, omit this step and mail to unknown users in the domain will simply -bounce. - -If you're using a version of Postfix newer than 19991226, that should do -it. If not, you also need to add your virtual domains to relay_domains. -Simply add "$virtual_maps" to your relay_domains line. Then you can use -the same map you use to find virtual recipients to determine if a domain -is a valid virtual domain and should be allowed to relay. - -In summary, you might have a catchall user for a virtual domain that -looks like this: - - dn: cn=defaultrecipient, dc=fake, dc=dom - objectclass: top - objectclass: virtualaccount - cn: defaultrecipient - owner: uid=root, dc=someserver, dc=isp, dc=dom - 1 -> mailacceptinggeneralid: fake.dom - 2 -> mailacceptinggeneralid: @fake.dom - 3 -> maildrop: realuser@real.dom - -1: Postfix knows fake.dom is a valid virtual domain when it looks for - this and gets something (the maildrop) back. - -2: This causes any mail for unknown users in fake.dom to go to this entry ... - -3: ... and then to its maildrop. - -Normal users might simply have one mailacceptinggeneralid and maildrop, -e.g. "normaluser@fake.dom" and "normaluser@real.dom". - -OTHER USES ----------- - -Other common uses for LDAP lookups include rewriting senders and -recipients with Postfix' canonical lookups, for example in order to make -mail leaving your site appear to be coming from "First.Last@site.dom" -instead of "userid@site.dom". - -NOTES AND THINGS TO THINK ABOUT -=============================== - -- The bits of schema and attribute names used in this document are just - examples. There's nothing special about them, other than that some are - the defaults in the LDAP configuration parameters. You can use - whatever schema you like, and configure Postfix accordingly. - -- You probably want to make sure that mailacceptinggeneralids are - unique, and that not just anyone can specify theirs as postmaster or - root, say. - -- An entry can have an arbitrary number of mailacceptinggeneralids or - maildrops. Maildrops can also be comma-separated lists of addresses. - They will all be found and returned by the lookups. For example, you - could define an entry intended for use as a mailing list that looks - like this (Warning! Schema made up just for this example): - - dn: cn=Accounting Staff List, dc=my, dc=com - cn: Accounting Staff List - o: my.com - objectclass: maillist - mailacceptinggeneralid: accountingstaff - mailacceptinggeneralid: accounting-staff - maildrop: mylist-owner - maildrop: an-accountant - maildrop: some-other-accountant - maildrop: this, that, theother - -- If you use an LDAP map for lookups other than aliases, you may have to - make sure the lookup makes sense. In the case of virtual lookups, - maildrops other than mail addresses are pretty useless, because - Postfix can't know how to set the ownership for program or file - delivery. Your query_filter should probably look something like this: - - query_filter = (&(mailacceptinggeneralid=%s)(!(|(maildrop="*|*")(maildrop="*:*")(maildrop="*/*")))) - -- And for that matter, even for aliases, you may not want users able to - specify their maildrops as programs, includes, etc. This might be - particularly pertinent on a "sealed" server where they don't have - local UNIX accounts, but exist only in LDAP and Cyrus. You might allow - the fun stuff only for directory entries owned by an administrative - account: - - query_filter = (&(mailacceptinggeneralid=%s)(!(|(maildrop="*|*")(maildrop="*:*")(maildrop="*/*"))(owner=cn=root, dc=your, dc=com))) - - So that if the object had a program as its maildrop and weren't owned - by "cn=root" it wouldn't be returned as a valid local user. This will - require some thought on your part to implement safely, considering the - ramifications of this type of delivery. You may decide it's not worth - the bother to allow any of that nonsense in LDAP lookups, ban it in - the query_filter, and keep things like majordomo lists in local alias - databases. - -- LDAP lookups are slower than local DB or DBM lookups. For most sites - they won't be a bottleneck, but it's a good idea to know how to tune - your directory service. - -- Multiple LDAP maps share the same LDAP connection if they differ - only in their query related parameters: base, scope, query_filter, and - so on. To take advantage of this avoid spurious differences in the - definitions of LDAP maps: host selection order, version, bind, tls - parameters, ... should be the same for multiple maps whenever possible. - -FEEDBACK -======== - -If you have questions, send them to postfix-users@postfix.org. Please -include relevant information about your Postfix setup: LDAP-related -output from postconf, which LDAP libraries you built with, and which -directory server you're using. If your question involves your directory -contents, please include the applicable bits of some directory entries. - -CREDITS -======= - -Manuel Guesdon: Spotted a bug with the timeout attribute. -John Hensley: Multiple LDAP sources with more configurable attributes. -Carsten Hoeger: Search scope handling. -LaMont Jones: Domain restriction, URL and DN searches, multiple result - attributes. -Mike Mattice: Alias dereferencing control. -Hery Rakotoarisoa: Patches for LDAPv3 updating. -Prabhat K Singh: Wrote the initial Postfix LDAP lookups and connection caching. -Keith Stevenson: RFC 2254 escaping in queries. -Samuel Tardieu: Noticed that searches could include wildcards, prompting - the work on RFC 2254 escaping in queries. Spotted a bug - in binding. -Sami Haahtinen: Referral chasing and v3 support. -Victor Duchovni: ldap_bind() timeout. With fixes from LaMont Jones: - OpenLDAP cache deprecation. Limits on recursion, expansion - and query results size. LDAP connection sharing for maps - differing only in the query parameters. -Liviu Daia: Support for SSL/STARTTLS. Support for storing map definitions in - external files (ldap:/path/ldap.cf) needed to securely store - passwords for plain auth. +The file /etc/postfix/ldap-aliases.cf can specify a great number of parameters, +including parameters that enable LDAP SSL and STARTTLS. For a complete +description, see the ldap_table(5) manual page. + +EExxaammppllee:: llooccaall((88)) aalliiaasseess + +Here's a basic example for using LDAP to look up local(8) aliases. Assume that +in main.cf, you have: + + alias_maps = hash:/etc/aliases, ldap:/etc/postfix/ldap-aliases.cf + +and in ldap:/etc/postfix/ldap-aliases.cf you have: + + server_host = ldap.my.com + search_base = dc=my, dc=com + +Upon receiving mail for a local address "ldapuser" that isn't found in the / +etc/aliases database, Postfix will search the LDAP server listening at port 389 +on ldap.my.com. It will bind anonymously, search for any directory entries +whose mailacceptinggeneralid attribute is "ldapuser", read the "maildrop" +attributes of those found, and build a list of their maildrops, which will be +treated as RFC822 addresses to which the message will be delivered. + +EExxaammppllee:: vviirrttuuaall ddoommaaiinnss//aaddddrreesssseess + +If you want to keep information for virtual lookups in your directory, it's +only a little more complicated. First, you need to make sure Postfix knows +about the virtual domain. An easy way to do that is to add the domain to the +mailacceptinggeneralid attribute of some entry in the directory. Next, you'll +want to make sure all of your virtual recipient's mailacceptinggeneralid +attributes are fully qualified with their virtual domains. Finally, if you want +to designate a directory entry as the default user for a virtual domain, just +give it an additional mailacceptinggeneralid (or the equivalent in your +directory) of "@virtual.dom". That's right, no user part. If you don't want a +catchall user, omit this step and mail to unknown users in the domain will +simply bounce. + +In summary, you might have a catchall user for a virtual domain that looks like +this: + + dn: cn=defaultrecipient, dc=fake, dc=dom + objectclass: top + objectclass: virtualaccount + cn: defaultrecipient + owner: uid=root, dc=someserver, dc=isp, dc=dom + 1 -> mailacceptinggeneralid: fake.dom + 2 -> mailacceptinggeneralid: @fake.dom + 3 -> maildrop: realuser@real.dom + + 1: Postfix knows fake.dom is a valid virtual domain when it looks for this + and gets something (the maildrop) back. + + 2: This causes any mail for unknown users in fake.dom to go to this entry + ... + + 3: ... and then to its maildrop. + +Normal users might simply have one mailacceptinggeneralid and maildrop, e.g. +"normaluser@fake.dom" and "normaluser@real.dom". + +OOtthheerr uusseess ooff LLDDAAPP llooookkuuppss + +Other common uses for LDAP lookups include rewriting senders and recipients +with Postfix's canonical lookups, for example in order to make mail leaving +your site appear to be coming from "First.Last@site.dom" instead of +"userid@site.dom". + +NNootteess aanndd tthhiinnggss ttoo tthhiinnkk aabboouutt + + * The bits of schema and attribute names used in this document are just + examples. There's nothing special about them, other than that some are the + defaults in the LDAP configuration parameters. You can use whatever schema + you like, and configure Postfix accordingly. + + * You probably want to make sure that mailacceptinggeneralids are unique, and + that not just anyone can specify theirs as postmaster or root, say. + + * An entry can have an arbitrary number of mailacceptinggeneralids or + maildrops. Maildrops can also be comma-separated lists of addresses. They + will all be found and returned by the lookups. For example, you could + define an entry intended for use as a mailing list that looks like this + (Warning! Schema made up just for this example): + + dn: cn=Accounting Staff List, dc=my, dc=com + cn: Accounting Staff List + o: my.com + objectclass: maillist + mailacceptinggeneralid: accountingstaff + mailacceptinggeneralid: accounting-staff + maildrop: mylist-owner + maildrop: an-accountant + maildrop: some-other-accountant + maildrop: this, that, theother + + * If you use an LDAP map for lookups other than aliases, you may have to make + sure the lookup makes sense. In the case of virtual lookups, maildrops + other than mail addresses are pretty useless, because Postfix can't know + how to set the ownership for program or file delivery. Your query_filter + should probably look something like this: + + query_filter = (&(mailacceptinggeneralid=%s)(!(|(maildrop="*|*") + (maildrop="*:*")(maildrop="*/*")))) + + * And for that matter, even for aliases, you may not want users able to + specify their maildrops as programs, includes, etc. This might be + particularly pertinent on a "sealed" server where they don't have local + UNIX accounts, but exist only in LDAP and Cyrus. You might allow the fun + stuff only for directory entries owned by an administrative account, so + that if the object had a program as its maildrop and weren't owned by + "cn=root" it wouldn't be returned as a valid local user. This will require + some thought on your part to implement safely, considering the + ramifications of this type of delivery. You may decide it's not worth the + bother to allow any of that nonsense in LDAP lookups, ban it in the + query_filter, and keep things like majordomo lists in local alias + databases. + + query_filter = (&(mailacceptinggeneralid=%s)(!(|(maildrop="*|*") + (maildrop="*:*")(maildrop="*/*"))(owner=cn=root, dc=your, dc=com))) + + * LDAP lookups are slower than local DB or DBM lookups. For most sites they + won't be a bottleneck, but it's a good idea to know how to tune your + directory service. + + * Multiple LDAP maps share the same LDAP connection if they differ only in + their query related parameters: base, scope, query_filter, and so on. To + take advantage of this, avoid spurious differences in the definitions of + LDAP maps: host selection order, version, bind, tls parameters, ... should + be the same for multiple maps whenever possible. + +FFeeeeddbbaacckk + +If you have questions, send them to postfix-users@postfix.org. Please include +relevant information about your Postfix setup: LDAP-related output from +postconf, which LDAP libraries you built with, and which directory server +you're using. If your question involves your directory contents, please include +the applicable bits of some directory entries. + +CCrreeddiittss + + * Manuel Guesdon: Spotted a bug with the timeout attribute. + * John Hensley: Multiple LDAP sources with more configurable attributes. + * Carsten Hoeger: Search scope handling. + * LaMont Jones: Domain restriction, URL and DN searches, multiple result + attributes. + * Mike Mattice: Alias dereferencing control. + * Hery Rakotoarisoa: Patches for LDAPv3 updating. + * Prabhat K Singh: Wrote the initial Postfix LDAP lookups and connection + caching. + * Keith Stevenson: RFC 2254 escaping in queries. + * Samuel Tardieu: Noticed that searches could include wildcards, prompting + the work on RFC 2254 escaping in queries. Spotted a bug in binding. + * Sami Haahtinen: Referral chasing and v3 support. + * Victor Duchovni: ldap_bind() timeout. With fixes from LaMont Jones: + OpenLDAP cache deprecation. Limits on recursion, expansion and query + results size. LDAP connection sharing for maps differing only in the query + parameters. + * Liviu Daia: Support for SSL/STARTTLS. Support for storing map definitions + in external files (ldap:/path/ldap.cf) needed to securely store passwords + for plain auth. And of course Wietse. + diff --git a/postfix/README_FILES/LINUX_README b/postfix/README_FILES/LINUX_README index 410cd7f08..395331c9e 100644 --- a/postfix/README_FILES/LINUX_README +++ b/postfix/README_FILES/LINUX_README @@ -1,20 +1,31 @@ -LINUX PORTABILITY -================= +PPoossttffiixx aanndd LLiinnuuxx -On RedHat Linux 7.0 you must install the db3-devel RPM before you -can compile the Postfix source code. +------------------------------------------------------------------------------- -On RedHat Linux 7.1 procmail no longer has permission to write the -mail spool directory. Workaround: chmod 1777 /var/spool/mail. +BBeerrkkeelleeyy DDBB iissssuueess -LINUX SYSLOGD PERFORMANCE -========================= +On RedHat Linux 7.0 you must install the db3-devel RPM before you can compile +the Postfix source code. -LINUX syslogd uses synchronous writes by default. Because of this, -syslogd can actually use more system resources than Postfix. To -avoid such madness, disable synchronous mail logfile writes by -editing /etc/syslog.conf and by prepending a - to the logfile name: +Warning: do not use multiple Berkeley DB versions. Every Postfix program will +dump core when it is built with a different Berkeley DB version than the +version that is used by the system library routines. See the DB_README file for +further information. - mail.* -/var/log/mail.log +PPrrooccmmaaiill iissssuueess + +On RedHat Linux 7.1 pprrooccmmaaiill no longer has permission to write the mail spool +directory. Workaround: chmod 1777 /var/spool/mail. + +SSyyssllooggdd ppeerrffoorrmmaannccee + +LINUX ssyyssllooggdd uses synchronous writes by default. Because of this, ssyyssllooggdd can +actually use more system resources than Postfix. To avoid such badness, disable +synchronous mail logfile writes by editing /etc/syslog.conf and by prepending a +- to the logfile name: + + /etc/syslog.conf: + mail.* -/var/log/mail.log + +Send a "kkiillll --HHUUPP" to the ssyyssllooggdd to make the change effective. -Send a "kill -HUP" to the syslogd to make the change effective. diff --git a/postfix/README_FILES/LMTP_README b/postfix/README_FILES/LMTP_README index 4f511e9b7..256bf4667 100644 --- a/postfix/README_FILES/LMTP_README +++ b/postfix/README_FILES/LMTP_README @@ -1,552 +1,5 @@ -This document describes mail delivery via LMTP including Cyrus. -For an overview of all methods to host domains with Postfix, see -the HOSTING_README file. +PPoossttffiixx LLMMTTPP HHoowwttoo -1 - Postfix LMTP support -======================== +------------------------------------------------------------------------------- +This document will be made available via http://www.postfix.org/. -LMTP stands for Local Mail Transfer Protocol, and is detailed in -RFC2033. Postfix uses this protocol to communicate with the final -delivery agent, which may run on the local host or a remote host. - -This protocol opens up interesting possibilities: one Postfix front -end machine can drive multiple mailbox back end machines over LMTP. -As the mail load increases, you add more Postfix front end systems -and more LMTP mailbox back end systems. This is the model that -Wietse had in mind when he began drafting the design for Postfix -- a scalable architecture that allows you to keep adding SMTP -servers and mailbox servers painlessly. - -Such a distributed architecture needs glue to keep things together. -You can use a networked database (LDAP or mysql) to share the user -database among the front end and back end systems. Use a replicated -database so that no machine becomes a single point of failure for -the entire mail infrastructure. Or you can use rsync when files -are small and/or when information does not change often. - -Postfix LMTP support is based on a modified version of the Postfix -SMTP client. The initial version was by Philip A. Prindeville of -Mirapoint, Inc., USA. This code was modified further by Amos Gouaux -of University of Texas at Dallas, Richardson, USA, who also revised -much of the documentation. Wietse Venema reduced the code to its -present shape. - - -2 - Overview -============ - -Most of the examples in this document involve the CMU Cyrus IMAP/POP -server, available from: - - http://asg.web.cmu.edu/cyrus/ - -While certainly not the only application that could make use of -LMTP, it tends to be the most discussed. These examples are based -on Cyrus 2.1.5. The 2.x branch of Cyrus places greater emphasis on -LMTP delivery than the previous releases. Those using older releases -of Cyrus can find a discussion in the appendix of this document. - -There are a variety of ways LMTP delivery can be configured in -Postfix. The two basic flavors are delivery over UNIX-domain -sockets and delivery over TCP sockets. - - o Connections from the Postfix LMTP client over UNIX-domain - sockets allow you to deliver to non-Postfix LMTP servers running - on the same machine. - - o Connections from the Postfix LMTP client over TCP sockets allow - you to deliver to non-Postfix LMTP servers across a local - network. - -Note: the above is not to be confused with the UNIX-domain sockets -that Postfix uses internally to speak its own protocols with the -Postfix LMTP client. - -The precise syntax for UNIX-domain and TCP connection endpoints is -given in the lmtp(8) manual page. Examples are also given in the -text below. - -Both socket flavors can be specified in either the Postfix main.cf -file (see section 5) or in a Postfix transport map (section 6). -What is the best approach for you depends upon the arrangement of -your servers. - - -3 - LMTP over UNIX-domain sockets -================================= - -Use this to deliver mail from the Postfix LMTP client to an LMTP -server that is running on the same system. - -A UNIX-domain socket is specified as the socket type ("unix") and -a name in the local file system: - - unix:/path/name - -The "/path/name" part should be the name of a socket created by -the LMTP server on the local machine. See the specific examples -later in this document. - -NOTE: - - If you run the Postfix LMTP client chrooted, the interpretation - of the /path/name is relative to the Postfix queue directory - (typically, /var/spool/postfix). - - By default, the Postfix LMTP client does not run chrooted. - With LMTP delivery to the local machine there is no good reason - to run the Postfix LMTP client chrooted. - - -4 - LMTP over TCP sockets -========================= - -Use this to deliver mail from the Postfix LMTP client to an LMTP -server that is running on the same system or on a different system. - -A TCP destination is specified as the socket type ("inet"), the -destination hostname and the TCP port: - - inet:hostname:port - -The "inet:" part can be omitted, as it is the default socket type. - -The destination port can be omitted as well. Currently the default -TCP port number for this type of connection is 24, but this can be -customized in the /etc/services file. Specific examples are -given later in this document. - -NOTE: - - With connections over TCP sockets, Cyrus 2.0.x LMTP server - implementations insisted on SASL-style authentication. This - meant that Postfix had to be built with SASL support (see - SASL_README). While newer Cyrus releases offer an option to - turn off this requirement, you must exercise great care in - both determining the approach used and the configuration of - your selection. It is imperative that you do not allow - unauthorized access to your LMTP server. The examples below - show both approaches. - - Some Cyrus LMTP server implementations do not allow SASL-style - authentication via plaintext passwords over unencrypted - connections. This is not the case with 2.1.5. However, you - must realize that this could make your LMTP link vulnerable. - If your LMTP communications traverse exposed networks, you - should either use an encrypted connection or enable MD5 SASL - mechanisms. - - -5 - Configuring LMTP using main.cf configuration -================================================ - -This is the simplest LMTP configuration. - -5.1 - Delivery mechanisms -------------------------- - -Postfix main.cf supports three mechanisms to deliver mail to an -LMTP server. Each method can use UNIX-domain or TCP sockets as -described in a later section. - -main.cf mechanism 1 -------------------- - -mailbox_transport = lmtp:unix:/path/name (UNIX-domain socket example) -mailbox_transport = lmtp:hostname:port (TCP socket example) - -Mail that resolves as local (domain is listed in $mydestination) -is given to the Postfix local delivery agent. The Postfix local -delivery agent expands aliases and .forward files, and delegates -mailbox delivery to the Postfix LMTP client which then sends it to -the non-Postfix LMTP server. - -main.cf mechanism 2 -------------------- - -local_transport = lmtp:unix:/path/name (UNIX-domain socket example) -local_transport = lmtp:hostname:port (TCP socket example) - -Mail that resolves as local (domain is listed in $mydestination) -is directly given to the Postfix LMTP client which then sends it -to the non-Postfix LMTP server. The mail is not processed by the -Postfix local delivery agent; therefore aliases and .forward files -are not processed. - -main.cf mechanism 3 -------------------- - -fallback_transport = lmtp:unix:/path/name (UNIX-domain socket example) -fallback_transport = lmtp:hostname:port (TCP socket example) - -Mail that resolves as local (domain is listed in $mydestination) -is given to the Postfix local delivery agent. The Postfix local -delivery agent processes aliases and .forward files, and delivers -to /var[/spool]/mail/$user for users that have a UNIX account. -Mail for other local users is delegated to the Postfix LMTP client -which then sends it to the non-Postfix LMTP server. - -5.2 - Examples --------------- - -5.2.1 - LMTP over UNIX-domain sockets -------------------------------------- - -To utilize UNIX-domain sockets for the communication between -Postfix and Cyrus, the corresponding configuration files should -look something like this: - - /etc/cyrus.conf: - SERVICES { - ... - lmtpunix cmd="lmtpd" listen="/var/imap/socket/lmtp" prefork=1 - ... - } - - /etc/postfix/main.cf: - mailbox_transport = lmtp:unix:/var/imap/socket/lmtp - - /etc/postfix/master.cf: - lmtp unix - - n - - lmtp - -In this case, the Postfix local delivery agent expands aliases -and .forward files, and delegates mailbox delivery to the Cyrus -lmtpd server via the socket "/var/imap/socket/lmtp". - -NOTE: - - Make sure that both the user id that Cyrus runs under and the - Postfix user id can access the socket "/var/imap/socket/lmtp". - While this is implied by the example above, it is often - overlooked and so warrants emphasis. - -5.2.2 - LMTP over TCP sockets (non-SASL) ----------------------------------------- - -For this example, suppose the following files are configured -thusly: - - /etc/cyrus.conf: - SERVICES { - ... - lmtp cmd="lmtpd -a" listen="127.0.0.1:lmtp" prefork=1 - ... - } - - /etc/services: - lmtp 2003/tcp - - /etc/postfix/main.cf: - mailbox_transport = lmtp:localhost - - /etc/postfix/master.cf: - lmtp unix - - n - - lmtp - -With the above settings, the Postfix local delivery agent expands -aliases and .forward files, and delegates mailbox delivery to the -Cyrus LMTP server. Postfix makes a connection to port 2003 on the -local host, subsequently transmitting the message to the lmtpd -server managed by the Cyrus master process. The port number has -been changed in /etc/services from 24 to 2003 as that is what the -Cyrus LMTP server is now using. - -See the Cyrus lmtpd(8) man page to verify that the version you -have supports the "-a" option. - -NOTE: - - Consider this approach if and only if this particular host - does not allow direct user logins or user-controlled - processes. Otherwise, this LMTP server may be abused! - - If the Cyrus lmtp service is to listen on a network other - than the local loop-back (127.0.0.1), be sure to install - Cyrus with tcp_wrappers support. Then use tcp_wrappers - to only allow access to the "lmtp" service from trusted - hosts. Otherwise, this LMTP server may be abused! - - Section 10 contains an example using tcp_wrappers. For the - configuration above, replace "deliver" with "lmtp" in the - /etc/hosts.allow shown in that example. - -5.2.3 - LMTP over TCP sockets (SASL) ------------------------------------- - -In the following example "cyhost.my.domain" is the name of the Cyrus -IMAP/POP server. It is important that you use this name consistently -in the Postfix configuration settings. The first approach uses the -PLAIN authentication mechanism (see the Cyrus SASL documentation.) - -Suppose the Cyrus server has the following files configured thusly: - - /etc/cyrus.conf: - SERVICES { - ... - lmtp cmd="lmtpd" listen="cyhost.my.domain:lmtp" prefork=1 - ... - } - - /etc/imapd.conf: - lmtp_admins: lmtpuser - - /etc/services: - lmtp 2003/tcp - -The Postfix host (may be same box) has the following configuration: - - /etc/postfix/main.cf: - mailbox_transport = lmtp:cyhost.my.domain - lmtp_sasl_auth_enable = yes - lmtp_sasl_password_maps = hash:/etc/postfix/lmtp_sasl_pass - lmtp_sasl_security_options = noanonymous - - /etc/postfix/lmtp_sasl_pass: - cyhost.my.domain lmtpuser:password - - /etc/services: - lmtp 2003/tcp - - /etc/postfix/master.cf: - lmtp unix - - n - - lmtp - -Instead of "hash", use the map type of your choice. Some systems -use "dbm" instead. Use "postconf -m" to find out what map types -are supported. - -If your version of Cyrus does not support "lmtp_admins" as a -setting in imapd.conf, use "admins" instead. - -With the above settings, the Postfix local delivery agent expands -aliases and .forward files, and delegates mailbox delivery to the -Cyrus LMTP server. Postfix makes a connection to port 2003 on the -local host, subsequently transmitting the message to the lmtpd -server managed by the Cyrus master process. The port number has -been changed in /etc/services from 24 to 2003 as that is what the -Cyrus LMTP server is now using. The SASL configuration on the Cyrus -server will need to accept the user "lmtpuser" using the password -specified in /etc/postfix/lmtp_sasl_pass on the Postfix host. - -If this LMTP conduit exists over an exposed network, you should -compile Postfix with MD5 (CRAM or DIGEST) password support. See -SASL_README for more details. Then configure Postfix as follows: - - /etc/postfix/main.cf: - lmtp_sasl_security_options = noanonymous, noplaintext - -On the Cyrus host you should also set: - - /etc/imapd.conf: - lmtp_allowplaintext: no - -You will need to make sure the "lmtpuser" is in the appropriate -SASL database. As an example, the following would add "lmtpuser" -to /etc/sasldb2: - - saslpasswd2 -c -u cyhost.my.domain lmtpuser - -If you encounter difficulties with "lmtpuser" not being permitted -to authenticate to the LMTP server, try the above command with the -un-qualified hostname: - - saslpasswd2 -c -u cyhost lmtpuser - -Also make sure the Cyrus user has read permission of the SASL -database, /etc/sasldb2 in the example above. - -Incidentally, it is very likely that the Cyrus server and the -Postfix server will need to use the same SASL backend databases -(e.g., auxprop or saslauthd.) Currently it is not possible to -assign different SASL backends for different Cyrus services. -Only TLS (SSL) or STARTTLS can be used in conjunction with -saslauthd. Since none of these encryption methods are available -for LMTP, if you need to encrypt your LMTP connections, you will -very likely have to use auxprop throughout. - - -6 - Configuring LMTP using transport map configuration -====================================================== - -This approach is quite similar to specifying the LMTP service in -the Postfix main.cf configuration file. However, now we will use -a transport map to route mail to the appropriate LMTP server, -instead of depending on delegation by the Postfix local delivery -agent. - -Why might this approach be useful? This could be handy if you wish -to route mail for multiple domains to their respective mail retrieval -(IMAP/POP) server. Example: - - /etc/postfix/transport: - domain1.tld lmtp1:unix:/path/name - domain2.tld lmtp2:lmtp2host - - /etc/postfix/master.cf: - lmtp1 unix - - n - - lmtp - lmtp2 unix - - n - - lmtp - - /etc/postfix/main.cf: - transport_maps = hash:/etc/postfix/transport - -For details of the Cyrus LMTP server configuration, see section 5. - -Instead of "hash", use the map type of your choice. Some systems use -"dbm" instead. Use "postconf -m" to find out what map types are -supported. - - -7 - Performance considerations -============================== - -Hopefully the preceding discussion has seemed pretty straight -forward. Now things get interesting. After reading the following -you will see that there are more factors to consider when setting -up LMTP services. - - -8 - Single instance message store -================================= - -Presently this topic is more pertinent to sites running Cyrus, but -may be a factor with other applications as well. - -Since 1.6.22, Cyrus has had the feature that if a message containing -multiple recipients is received via the LMTP protocol, and all -these recipients were on the same Cyrus partition, only one instance -of this message would be written to the file system. The other -recipients would then see a hard link of this single instance. -Depending on your user base, this can be considerable motivation -to using LMTP. - -With the examples in section 5.2, we can increase the number of -recipients (to $mydestination) that can be handled at once: - - /etc/postfix/main.cf: - local_destination_recipient_limit = 300 - -The 300 was arbitrarily chosen for this example. Be sure to pick a -number that is appropriate for the capabilities of your hardware. -The bigger the number, the more you can leverage the single instance -message store. However, if it is too big the LMTP server will need -too much time to deliver a message and Postfix will experience -timeout errors. Choose this value very carefully. - -NOTE: - - Not all local delivery agent transports can support a recipient - limit greater than 1. Be sure to check the man page of the - specific transport before attempting this with anything but the - Postfix LMTP client. - -If we wish to apply this single instance message store technique -with the configuration example in section 6, the setting would be: - - /etc/postfix/main.cf: - lmtp1_destination_recipient_limit = 300 - lmtp2_destination_recipient_limit = 300 - -As previously mentioned, exercise tremendous care backed by -extensive analysis of your systems before setting the recipient -limit like this. - - -9 - Improving connection caching performance -============================================ - -After delivering a message via LMTP, Postfix will keep the connection -open for a while, so that it can be reused for a subsequent delivery. -This reduces overhead of LMTP servers that create one process per -connection. - -For LMTP connection caching to work, the Postfix LMTP client should -not switch destination hosts. This is no problem when you run only -one LMTP server. However, if you run multiple LMTP servers, this -can be an issue. - -You can prevent the LMTP client from switching between servers by -configuring a separate LMTP delivery transport for each LMTP server: - - /etc/postfix/master.cf: - lmtp1 unix - - n - - lmtp - lmtp2 unix - - n - - lmtp - . . . . . . . . - -Configure transport table entries such that the lmtp1 mail delivery -transport is used for all deliveries to the LMTP server #1, the -mail lmtp2 transport for the LMTP server #2, and so on. - - /etc/postfix/transport: - foo.com lmtp1:lmtp1host - bar.com lmtp2:lmtp2host - - -10 - Appendix: Older Cyrus versions -=================================== - -First of all, if you are using a Cyrus 2.x version prior to 2.1.4, -you should really consider upgrading. There have been numerous bug -fixes and performance improvements since the early 2.0 releases. - -Further back, 1.6.24 was the last pre-2.x production release. -(Actually, there was a 1.6.25-BETA, but it is uncertain whether this -will be released officially as CMU is now focusing support on the 2.x -branch.) The following discussion touches on how to configure the -Postfix LMTP facilities with Cyrus 1.6.24. - -One of the significant differences between Cyrus 1.x and 2.x is the -inclusion of the "master" process in 2.x. This "master" process is -responsible for running the various components of Cyrus, such as -imapd, pop3d, and lmtpd. Prior to 2.x, these services were managed -by inetd, the Internet services daemon. - -To utilize LMTP delivery with Cyrus 1.6.24, the first thing to do is -configure inetd. This involves the following file edits: - - /etc/services: - lmtp 2003/tcp - - /etc/inetd.conf: - lmtp stream tcp nowait cyrus /usr/sbin/tcpd /usr/cyrus/bin/deliver -e -l - - /etc/hosts.allow: - deliver : localhost : ALLOW - deliver : ALL@ALL : DENY - -The "/usr/sbin/tcpd" is from the tcp_wrappers package, which is -discussed in the example "LMTP over TCP sockets, using hosts.allow." -It is important that you wrap this LMTP port to protect it from -unauthorized access. - -On some systems, tcpd is built into inetd, so you do not have to -specify tcpd in the inetd.conf file. Instead of tcpd/inetd, xinetd -can do a similar job of logging and access control. - -Now comes the Postfix configuration. Basically, the Cyrus 2.x -discussions regarding LMTP delivery over TCP are also applicable to -Cyrus 1.x, with the exception of the /etc/cyrus.conf file. A -typical Postfix configuration might look like this: - - /etc/postfix/master.cf: - lmtp unix - - n - - lmtp - - /etc/postfix/main.cf: - mailbox_transport = lmtp - -It is also possible to use the transport map to route mail to your -Cyrus 1.6.24 LMTP server: - - /etc/postfix/transport: - domain1.tld lmtp1:lmtp1host - domain2.tld lmtp2:lmtp2host - - /etc/postfix/master.cf: - lmtp1 unix - - n - - lmtp - lmtp2 unix - - n - - lmtp - - /etc/postfix/main.cf: - transport_maps = hash:/etc/postfix/transport - -If you have read the discussion covering the Cyrus 2.x installation, -you will notice the one significant difference with the Postfix -configuration is the lack of mention of the UNIX-domain sockets. -That is because delivery over UNIX-domain sockets is new with Cyrus -2.x, yet another reason to upgrade. :-) diff --git a/postfix/README_FILES/LOCAL_RECIPIENT_README b/postfix/README_FILES/LOCAL_RECIPIENT_README index f9a5ec1d8..51ae9b8f3 100644 --- a/postfix/README_FILES/LOCAL_RECIPIENT_README +++ b/postfix/README_FILES/LOCAL_RECIPIENT_README @@ -1,125 +1,113 @@ -Introduction -============ +RReejjeeccttiinngg UUnnkknnoowwnn LLooccaall RReecciippiieennttss wwiitthh PPoossttffiixx -As of Postfix version 2.0, the Postfix SMTP server now rejects mail -for recipients in $mydestination domains that it does not know about. -This feature was optional with previous Postfix versions. +------------------------------------------------------------------------------- -The benefit is that this keeps undeliverable mail out of your queue. -The downside is that it may cause mail to be rejected when you -upgrade from a Postfix system that was not configured to reject -mail for unknown local recipients. +IInnttrroodduuccttiioonn -This document describes what steps you may need to take in order -to not have Postfix reject mail incorrectly. +As of Postfix version 2.0, the Postfix SMTP server rejects mail for unknown +recipients in local domains (domains that match $mydestination or the IP +addresses in $inet_interfaces or $proxy_interfaces) with "User unknown in local +recipient table". This feature was optional with earlier Postfix versions. -For safety's sake, if you upgrade from a Postfix version that did -not use this feature, the Postfix SMTP server replies with a 450 -(try again later) status code for users it does not know about. +The good news is that this keeps undeliverable mail out of your queue, so that +your mail queue is not clogged up with undeliverable MAILER-DAEMON messages. -Configuring the local_recipient_maps parameter -============================================== +The bad news is that it may cause mail to be rejected when you upgrade from a +Postfix system that was not configured to reject mail for unknown local +recipients. -The local_recipient_maps parameter specifies lookup tables with -all names or addresses of local recipients. A recipient address is -local when the address domain matches $mydestination, $inet_interfaces -or $proxy_interfaces. +This document describes what steps are needed in order to reject unknown local +recipients correctly. -The right-hand side of the lookup tables is conveniently ignored. -In the left-hand side, specify a bare username, an @domain.tld -wild-card, or specify a user@domain.tld address. + * Configuring local_recipient_maps in main.cf + * When you need to change the local_recipient_maps setting in main.cf + * Local recipient table format -If the local_recipient_maps parameter value is non-empty, then the -SMTP server will reject for an unknown local recipient mail with -"User unknown in local recipient table". +CCoonnffiigguurriinngg llooccaall__rreecciippiieenntt__mmaappss iinn mmaaiinn..ccff -To turn off unknown local recipient rejects by the SMTP server, specify: - - /etc/postfix/main.cf: - local_recipient_maps = +The local_recipient_maps parameter specifies lookup tables with all names or +addresses of local recipients. A recipient address is local when its domain +matches $mydestination, $inet_interfaces or $proxy_interfaces. If a local +username or address is not listed in $local_recipient_maps, then the Postfix +SMTP server will reject the address with "User unknown in local recipient +table". -That is, an empty value. With this setting, the Postfix SMTP server -will not reject mail with "User unknown in local recipient table". - -The default setting assumes that you use the default Postfix local -delivery agent for local delivery, where recipients are either UNIX +The default setting, shown below, assumes that you use the default Postfix +local(8) delivery agent for local delivery, where recipients are either UNIX accounts or local aliases: /etc/postfix/main.cf: - local_recipient_maps = proxy:unix:passwd.byname $alias_maps - -You need to update the local_recipient_maps setting if one of the -following is true: + local_recipient_maps = proxy:unix:passwd.byname $alias_maps -1 - You define your $mydestination domain recipients in files other - than /etc/passwd or /etc/aliases. +To turn off unknown local recipient rejects by the SMTP server, specify: - For example, you define $mydestination domain recipients in the - $virtual_mailbox_maps files. In that case, you specify your local - recipients as follows: + /etc/postfix/main.cf: + local_recipient_maps = - /etc/postfix/main.cf: - local_recipient_maps = $virtual_mailbox_maps +That is, an empty value. With this setting, the Postfix SMTP server will not +reject mail with "User unknown in local recipient table". - For non-Postfix delivery agents (i.e. not "local" or "virtual"), - see further down this document. +WWhheenn yyoouu nneeeedd ttoo cchhaannggee tthhee llooccaall__rreecciippiieenntt__mmaappss sseettttiinngg iinn mmaaiinn..ccff -2 - You run the Postfix SMTP server chrooted (specified in master.cf). + * Problem: you don't use the default Postfix local(8) delivery agent for + domains matching $mydestination, $inet_interfaces, or $proxy_interfaces. + For example, you redefined the "local_transport" setting in main.cf. - On many systems you will have to copy the passwd file into the - chroot environment. + Solution: your local_recipient_maps setting needs to specify a database + that lists all the known user names or addresses for that delivery agent. + For example, if you deliver users in $mydestination etc. domains via the + virtual(8) delivery agent, specify: - For example, on 4.4 BSD systems one would do the following: + /etc/postfix/main.cf + mydestination = $myhostname localhost.$mydomain localhost ... + local_transport = virtual + local_recipient_maps = $virtual_mailbox_maps - # mkdir /var/spool/postfix/etc - # cp /etc/pwd.db /var/spool/postfix/etc + If you use a different delivery agent for $mydestination etc. domains, see + the section "Local recipient table format" below for a description of how + the table should be populated. - On other systems one would do: + * Problem: you use the mailbox_transport or fallback_transport feature of the + Postfix local(8) delivery agent in order to deliver mail to non-UNIX + accounts. - # mkdir /var/spool/postfix/etc - # cp /etc/pwd.db /var/spool/postfix/etc + Solution: you need to add the database that lists the non-UNIX users: - You may also have to copy /etc/nsswitch.conf, as well as files - that are referenced by /etc/nsswitch.conf, but that is unlikely. + /etc/postfix/main.cf + local_recipient_maps = proxy:unix:passwd.byname, $alias_maps, + - The Postfix SMTP server has a safety net in place in case of a - missing or inaccessible passwd file and will reply with a 450 - status code (try again) instead of losing your mail. Watch your - maillog file for the obvious error messages. + See the section "Local recipient table format" below for a description of + how the table should be populated. -3 - You redefined the local delivery agent in master.cf, or you - redefined the "local_transport" setting in main.cf, so that - mail for $mydestination domain recipients is delivered by - something else than the default Postfix local delivery agent. + * Problem: you use the luser_relay feature of the Postfix local delivery + agent. - Your local_recipient_maps setting needs to specify a database - that lists all the known user names or addresses for that - delivery agent. For example, if you deliver users in $mydestination - domains via the virtual delivery agent, specify: + Solution: you must disable the local_recipient_maps feature completely, so + that Postfix accepts mail for all local addresses: - /etc/postfix/main.cf - local_recipient_maps = $virtual_mailbox_maps + /etc/postfix/main.cf + local_recipient_maps = - Your user database will be searched for the user@domain address - as well as for the bare username. +LLooccaall rreecciippiieenntt ttaabbllee ffoorrmmaatt -4 - You use the mailbox_transport or fallback_transport feature of - the Postfix local delivery agent in order to deliver mail non-UNIX - accounts. +If you use local files in postmap(1) format, then local_recipient_maps expects +the following table format: - You need to add the database that lists the non-UNIX users: + * In the left-hand side, specify a bare username, an "@domain.tld" wild-card, + or specify a complete "user@domain.tld" address. - /etc/postfix/main.cf - local_recipient_maps = unix:passwd.byname, $alias_maps, - + * You have to specify something on the right-hand side of the table, but the + value is ignored by local_recipient_maps. - Your database will be searched for the user@domain address as - well as for the bare username. +If you use lookup tables based on NIS, LDAP, MYSQL, or PGSQL, then +local_recipient_maps does the same queries as for local files in postmap(1) +format, and expects the same results. -5 - You use the luser_relay feature of the Postfix local delivery agent. +With regular expression tables, Postfix only queries with the full recipient +address, and not with the bare username or the "@domain.tld" wild-card. - In this case, you must disable the local_recipient_maps feature - completely, so that Postfix accepts mail for all local addresses: +NOTE: a lookup table should always return a result when the address exists, and +should always return "not found" when the address does not exist. In +particular, a zero-length result does not count as a "not found" result. - /etc/postfix/main.cf - local_recipient_maps = diff --git a/postfix/README_FILES/MAILDROP_README b/postfix/README_FILES/MAILDROP_README index 4a82054b5..36afd1e06 100644 --- a/postfix/README_FILES/MAILDROP_README +++ b/postfix/README_FILES/MAILDROP_README @@ -1,39 +1,120 @@ -The following information was kindly provided by Russell Mosemann, -with tips by Victor Duchovni for supporting user+foo@domain addresses. +PPoossttffiixx ++ MMaaiillddrroopp HHoowwttoo -In order to use the maildrop transport for some domain, add an entry -to transport_maps for each domain similar to the following. +------------------------------------------------------------------------------- -/etc/postfix/transport: - some.domain maildrop: - someother.domain maildrop: +IInnttrroodduuccttiioonn -Define the following variable in main.cf so that pipe will provide one -recipient at a time to maildrop. +This document discusses various options to plug the maildrop delivery agent +into Postfix: -/etc/postfix/main.cf: - maildrop_destination_recipient_limit = 1 + * Direct delivery without the local delivery agent + * Indirect delivery via the local delivery agent + * Credits -The vmail userid as used below is the user that maildrop should -run as. This would be the owner of the virtual mailboxes if they -all have the same owner. If maildrop is suid (see maildrop -documentation), then maildrop will change to the appropriate owner -to deliver the mail. Do not use the postfix user as the maildrop -user. +DDiirreecctt ddeelliivveerryy wwiitthhoouutt tthhee llooccaall ddeelliivveerryy aaggeenntt -/etc/postfix/master.cf: - maildrop unix - n n - - pipe - flags=DRhu user=vmail argv=/usr/local/bin/maildrop -d ${recipient} +Postfix can be configured to deliver mail directly to maildrop, without using +the local(8) delivery agent as an intermediate. This means that you do not get +local aliases(5) expansion or $HOME/.forward file processing. You would +typically do this for hosted domains with recipients that don't have UNIX home +directories. -If you want to support user+extension@domain style addresses, use -the following instead: +The following example shows how to use maildrop for some.domain and for +someother.domain. -/etc/postfix/master.cf: - maildrop unix - n n - - pipe - flags=DRhu user=vmail argv=/usr/local/bin/maildrop - -d ${user}@${nexthop} ${extension} ${recipient} ${user} ${nexthop} + 1 /etc/postfix/main.cf: + 2 maildrop_destination_recipient_limit = 1 + 3 virtual_mailbox_domains = some.domain someother.domain + 4 virtual_transport = maildrop + 5 virtual_mailbox_maps = hash:/etc/postfix/virtual_mailbox + 6 virtual_alias_maps = hash:/etc/postfix/virtual_alias + 7 + 8 /etc/postfix/virtual_mailbox: + 9 user1@some.domain ...text here does not matter... + 10 user2@some.domain ...text here does not matter... + 11 user3@someother.domain ...text here does not matter... + 12 + 13 /etc/postfix/virtual_alias: + 14 postmaster@some.domain postmaster + 15 postmaster@someother.domain postmaster + + * Line 2 is needed so that Postfix will provide one recipient at a time to + the maildrop delivery agent. + + * Line 3 informs Postfix that some.domain and someother.domain are so-called + virtual mailbox domains. Instead of listing the names in main.cf you can + also list them in a file; see the virtual_mailbox_domains documentation for + details. + + * Line 4 specifies that mail for some.domain and someother.domain should be + delivered by the maildrop delivery agent. + + * Lines 5 and 8-11 specify what recipients the Postfix SMTP server should + receive mail for. This prevents the mail queue from becoming clogged with + undeliverable messages. Specify an empty value ("virtual_mailbox_maps =") + to disable this feature. + + * Lines 6 and 13-15 redirect mail for postmaster to the local postmaster. RFC + 821 requires that every domain has a postmaster address. + +The vmail userid as used below is the user that maildrop should run as. This +would be the owner of the virtual mailboxes if they all have the same owner. If +maildrop is suid (see maildrop documentation), then maildrop will change to the +appropriate owner to deliver the mail. + +Note: Do not use the postfix user as the maildrop user. + + /etc/postfix/master.cf: + maildrop unix - n n - - pipe + flags=DRhu user=vmail argv=/path/to/maildrop -d ${recipient} + +If you want to support user+extension@domain style addresses, use the following +instead: + + /etc/postfix/master.cf: + maildrop unix - n n - - pipe + flags=DRhu user=vmail argv=/path/to/maildrop + -d ${user}@${nexthop} ${extension} ${recipient} ${user} ${nexthop} + +The mail is delivered to ${user}@${nexthop} (match key for maildrop userdb +lookup). The ${extension} and the other address components are available to +maildrop rules as $1, $2, $3, ... and can be omitted from master.cf or ignored +by maildrop when not needed. + +IInnddiirreecctt ddeelliivveerryy vviiaa tthhee llooccaall ddeelliivveerryy aaggeenntt + +Postfix can be configured to deliver mail to maildrop via the local delivery +agent. This is slightly less efficient than the "direct" approach discussed +above, but gives you the convenience of local aliases(5) expansion and +$HOME/.forward file processing. You would typically use this for domains that +are listed in mydestination and that have users with a UNIX system account. + +To configure maildrop delivery for all UNIX system accounts: + + /etc/postfix/main.cf: + mailbox_command = /path/to/maildrop -d ${USER} + +Note: ${USER} is spelled in upper case. + +To enable maildrop delivery for specific users only, you can use the Postfix +local(8) delivery agent's mailbox_command_maps feature: + + /etc/postfix/main.cf: + mailbox_command_maps = /etc/postfix/mailbox_commands + + /etc/postfix/mailbox_commands: + you /path/to/maildrop -d ${USER} + +Maildrop delivery for specific users is also possible by invoking it from the +user's $HOME/.forward file: + + /home/you/.forward: + "|/path/to/maildrop -d ${USER}" + +CCrreeddiittss + + * The original text was kindly provided by Russell Mosemann. + * Victor Duchovni provided tips for supporting user+foo@domain addresses. + * Tonni Earnshaw contributed text about delivery via the local(8) delivery + agent. -The mail is delivered to ${user}@${nexthop} (match key for maildrop -userdb lookup). The ${extension} and the other address components -are available to maildrop rules as $1, $2, $3, ... and can be -omitted from master.cf or ignored by maildrop when not needed. diff --git a/postfix/README_FILES/MYSQL_README b/postfix/README_FILES/MYSQL_README index 3d68a5cec..d5b7e27c5 100644 --- a/postfix/README_FILES/MYSQL_README +++ b/postfix/README_FILES/MYSQL_README @@ -1,114 +1,103 @@ -[Code contributed by Scott Cotton and Joshua Marcus, IC Group, Inc.] +PPoossttffiixx MMyySSQQLL HHoowwttoo -We've written code to add a mysql map type. It utilizes the mysql -client library, which can be obtained from: +------------------------------------------------------------------------------- - http://www.mysql.com/downloads/ - http://sourceforge.net/projects/mysql/ +IInnttrroodduuccttiioonn -In order to build postfix with mysql map support, you will need to add --DHAS_MYSQL and -I for the directory containing the mysql headers, and -the mysqlclient library (and libm) to AUXLIBS, for example: +The Postfix mysql map type allows you to hook up Postfix to a MySQL database. +This implementation allows for multiple mysql databases: you can use one for a +virtual(5) table, one for an access(5) table, and one for an aliases(5) table +if you want. You can specify multiple servers for the same database, so that +Postfix can switch to a good database server if one goes bad. -make -f Makefile.init makefiles \ - 'CCARGS=-DHAS_MYSQL -I/usr/local/mysql/include' \ - 'AUXLIBS=-L/usr/local/mysql/lib -lmysqlclient -lz -lm' +Busy mail servers using mysql maps will generate lots of concurrent mysql +clients, so the mysql server(s) should be run with this fact in mind. You can +reduce the number of concurrent mysql clients by using the Postfix proxymap(8) +service. -then, just run 'make'. This requires libz, the compression library. -Older mysql implementations build without libz. +BBuuiillddiinngg PPoossttffiixx wwiitthh MMyySSQQLL ssuuppppoorrtt -Postfix installations which may benefit from using mysql map types -include sites that have a need for instantaneous updates of -forwarding, and sites that may benefit from having mail exchangers -reference a networked database, possibly working in conjunction with a -customer database of sorts. +Note: to use mysql with Debian GNU/Linux's Postfix, all you need is to install +the postfix-mysql package and you're done. There is no need to recompile +Postfix. -Once postfix is built with mysql support, you can specify a map type -in main.cf like this: +The Postfix MySQL client utilizes the mysql client library, which can be +obtained from: -alias_maps = mysql:/etc/postfix/mysql-aliases.cf + http://www.mysql.com/downloads/ + http://sourceforge.net/projects/mysql/ -The file /etc/postfix/mysql-aliases.cf specifies lots of information -telling postfix how to reference the mysql database. An example mysql -map config file follows: +In order to build Postfix with mysql map support, you will need to add - +DHAS_MYSQL and -I for the directory containing the mysql headers, and the +mysqlclient library (and libm) to AUXLIBS, for example: + + make -f Makefile.init makefiles \ + 'CCARGS=-DHAS_MYSQL -I/usr/local/mysql/include' \ + 'AUXLIBS=-L/usr/local/mysql/lib -lmysqlclient -lz -lm' + +Then, just run 'make'. This requires libz, the compression library. Older mysql +implementations build without libz. + +UUssiinngg MMyySSQQLL ttaabblleess + +Once Postfix is built with mysql support, you can specify a map type in main.cf +like this: + + alias_maps = mysql:/etc/postfix/mysql-aliases.cf + +The file /etc/postfix/mysql-aliases.cf specifies lots of information telling +Postfix how to reference the mysql database. For a complete description, see +the mysql_table(5) manual page. + +EExxaammppllee:: llooccaall aalliiaasseess # -# mysql config file for alias lookups on postfix -# comments are ok. +# mysql config file for local(8) aliases(5) lookups # -# the user name and password to log into the mysql server +# The user name and password to log into the mysql server. user = someone password = some_password -# the database name on the servers +# The database name on the servers. dbname = customer_database -# the table name +# The table name. table = mxaliases -# +# Query components, see below. select_field = forw_addr where_field = alias -# you may specify additional_conditions here +# You may specify additional_conditions or leave this empty. additional_conditions = and status = 'paid' -# the above variables will result in a query of -# the form: +# The above variables will result in a query of the form: +# # select forw_addr from mxaliases where alias = '$lookup' and status = 'paid' -# ($lookup is escaped so if it contains single quotes or other odd -# characters, it will not cause a parse error in the sql). # -# the hosts that postfix will try to connect to -# and query from (in the order listed) -# specify unix: for unix-domain sockets, inet: for TCP connections (default) -hosts = host1.some.domain host2.some.domain unix:/file/name - -# end mysql config file - -Alternatively, these parameters can be defined in main.cf. To that -effect, the map should be specified as "mysql:name", and the parameters -should be prefixed with the name you've given the map in its definition, -and an underscore. For example, the above settings can also be written -in main.cf as: - -# mysql definitions in main.cf - -alias_maps = mysql:mysqlsource - -mysqlsource_user = someone -mysqlsource_password = some_password -mysqlsource_dbname = customer_database -mysqlsource_table = mxaliases -mysqlsource_select_field = forw_addr -mysqlsource_where_field = alias -mysqlsource_additional_conditions = and status = 'paid' -mysqlsource_hosts = host1.some.domain host2.some.domain unix:/file/name - -# end mysql definitions - - -Some notes: - -This configuration interface setup allows for multiple mysql -databases: you can use one for a virtual table, one for an access -table, and one for an aliases table if you want. - -Since sites that have a need for multiple mail exchangers may enjoy -the convenience of using a networked mailer database, but do not want -to introduce a single point of failure to their system, we've included -the ability to have postfix reference multiple hosts for access to a -single mysql map. This will work if sites set up mirrored mysql -databases on two or more hosts. Whenever queries fail with an error -at one host, the rest of the hosts will be tried in order. Each host -that is in an error state will undergo a reconnection attempt every so -often, and if no mysql server hosts are reachable, then mail will be +# ($lookup is escaped so if it contains single quotes or other odd +# characters, it will not cause trouble). + +AAddddiittiioonnaall nnootteess + +The MySQL configuration interface setup allows for multiple mysql databases: +you can use one for a virtual table, one for an access table, and one for an +aliases table if you want. + +Since sites that have a need for multiple mail exchangers may enjoy the +convenience of using a networked mailer database, but do not want to introduce +a single point of failure to their system, we've included the ability to have +Postfix reference multiple hosts for access to a single mysql map. This will +work if sites set up mirrored mysql databases on two or more hosts. Whenever +queries fail with an error at one host, the rest of the hosts will be tried in +random order. If no mysql server hosts are reachable, then mail will be deferred until at least one of those hosts is reachable. -Performance of postfix with mysql has not been thoroughly tested, -however, we have found it to be stable. Busy mail servers using mysql -maps will generate lots of concurrent mysql clients, so the mysql -server(s) should be run with this fact in mind. Any further -performance information, in addition to any feedback is most welcome. +CCrreeddiittss + + * The initial version was contributed by Scott Cotton and Joshua Marcus, IC + Group, Inc. + * Liviu Daia revised the configuration interface and added the main.cf + configuration feature. diff --git a/postfix/README_FILES/NFS_README b/postfix/README_FILES/NFS_README index 06ce4ecb8..196252de5 100644 --- a/postfix/README_FILES/NFS_README +++ b/postfix/README_FILES/NFS_README @@ -1,32 +1,39 @@ -> Also, what considerations are there for file locking or other potential -> problems when running Postfix with a Netapp-style box for /var/mail -> delivery? I know that FreeBSD has broken NFS file locking (both client -> and server?) but I'm not sure if this is something Postfix can work around -> or not. +PPoossttffiixx aanndd NNFFSS -Postfix jumps several hoops in order to deal with NFS-specific -problems. Thus, Postfix on NFS is slightly less reliable than -Postfix on a local disk. That is not a problem in Postfix; the -problem is in NFS and affects other MTAs as well. +------------------------------------------------------------------------------- +This question was asked on the postfix-users mailing list a while ago: -For queue locking, NFS is not an issue because you cannot share -Postfix queues with other Postfix instances. + Also, what considerations are there for file locking or other potential + problems when running Postfix with a Netapp-style box for /var/mail + delivery? I know that FreeBSD has broken NFS file locking (both client and + server?) but I'm not sure if this is something Postfix can work around or + not. -In order to have mailbox locking over NFS you have to configure -everything to use fcntl() locks for mailbox access (or switch to -maildir style, which needs no application-level lock controls). +Postfix jumps several hoops in order to deal with NFS-specific problems. Thus, +Postfix on NFS is slightly less reliable than Postfix on a local disk. That is +not a problem in Postfix; the problem is in NFS and affects other MTAs as well. -To turn on fcntl mailbox locks with Postfix you specify: +For queue locking within Postfix, NFS is not an issue because you cannot share +Postfix queues among multiple Postfix instances. - virtual_mailbox_lock = fcntl - mailbox_delivery_lock = fcntl +In order to have mailbox locking over NFS, you have to configure everything to +use fcntl() locks for mailbox access (or switch to maildir style, which needs +no application-level lock controls). -This is useful only if all mailbox access software uses fcntl() -locks. +To turn on fcntl() mailbox locks with Postfix you specify: + + /etc/postfix/main.cf: + virtual_mailbox_lock = fcntl + mailbox_delivery_lock = fcntl + +Obviously, this approach is useful only if all other mailbox access software +also uses fcntl() locks. You can also "play safe" and throw in username.lock files: - virtual_mailbox_lock = fcntl, dotlock - mailbox_delivery_lock = fcntl, dotlock + /etc/postfix/main.cf: + virtual_mailbox_lock = fcntl, dotlock + mailbox_delivery_lock = fcntl, dotlock + +This is the combination that many applications end up using. -this is the mix that many applications end up using. diff --git a/postfix/README_FILES/OVERVIEW b/postfix/README_FILES/OVERVIEW new file mode 100644 index 000000000..22c426937 --- /dev/null +++ b/postfix/README_FILES/OVERVIEW @@ -0,0 +1,344 @@ +PPoossttffiixx AArrcchhiitteeccttuurree OOvveerrvviieeww + +------------------------------------------------------------------------------- + +IInnttrroodduuccttiioonn + +This document presents an overview of the Postfix architecture, and is the +place where you find a pointer to every Postfix command or server program. The +text gives the general context in which each command or server program is used, +and provides pointers to documents with specific usage examples and background +information. + +Topics covered by this document: + + * How Postfix receives mail + * How Postfix delivers mail + * Postfix behind the scenes + * Postfix support commands + +HHooww PPoossttffiixx rreecceeiivveess mmaaiill + +When a message enters the Postfix mail system, the first stop on the inside is +the incoming queue. The figure below shows the main processes that are involved +with new mail. Names followed by a number are Postfix commands or server +programs, while unnumbered names inside shaded areas represent Postfix queues. + + trivial- + rewrite(8) + + Network -> smtpd(8) + + ^ | + \ | v + + Network -> qmqpd(8) -> cleanup(8) -> incoming + + / + + pickup(8) <- maildrop + + ^ + | + + Local -> sendmail(1) -> postdrop(1) + + * Network mail enters Postfix via the smtpd(8) or qmqpd(8) servers. These + servers remove the SMTP or QMQP protocol encapsulation, enforce some sanity + checks to protect Postfix, and give the sender, recipients and message + content to the cleanup(8) server. The smtpd(8) server can be configured to + block unwanted mail, as described in the SMTPD_ACCESS_README document. + + * Local submissions are received with the Postfix sendmail(1) compatibility + command, and are queued in the maildrop queue by the privileged postdrop(1) + command. This arrangement even works while the Postfix mail system is not + running. The local pickup(8) server picks up local submissions, enforces + some sanity checks to protect Postfix, and gives the sender, recipients and + message content to the cleanup(8) server. + + * Mail from internal sources is given directly to the cleanup(8) server. + These sources are not shown in the figure, and include: mail that is + forwarded by the local(8) delivery agent (see next section), messages that + are returned to the sender by the bounce(8) server (see second-next + section), and postmaster notifications about problems with Postfix. + + * The cleanup(8) server implements the final processing stage before mail is + queued. It adds missing From: and other message headers, transforms + addresses as described in the ADDRESS_REWRITING_README document. + Optionally, the cleanup(8) server can be configured to do light-weight + content inspection with regular expressions as described in the + BUILTIN_FILTER_README document. The cleanup(8) server places the result as + a single file into the incoming queue, and notifies the queue manager (see + next section) of the arrival of new mail. + + * The trivial-rewrite(8) server rewrites addresses to the standard + "user@fully.qualified.domain" form, as described in the + ADDRESS_REWRITING_README document. Postfix currently does not implement a + rewriting language, but a lot can be done via table lookups and, if need + be, regular expressions. + +HHooww PPoossttffiixx ddeelliivveerrss mmaaiill + +Once a message has reached the incoming queue the next step is to deliver it. +The figure shows the main components of the Postfix mail delivery apparatus. +Names followed by a number are Postfix commands or server programs, while +unnumbered names inside shaded areas represent Postfix queues. + + trivial- smtp(8) -> Network + rewrite(8) + / + + - lmtp(8) -> Network + ^ | + | v / + + incoming -> active -> qmgr(8) --- local(8) -> File, command + + \ + ^ | + | v - virtual(8) -> File + + deferred \ + + pipe(8) -> Command + + * The queue manager (the qmgr(8) server process in the figure) is the heart + of Postfix mail delivery. It contacts the smtp(8), lmtp(8), local(8), + virtual(8), pipe(8), or error(8) delivery agents, and sends a delivery + request for one or more recipient addresses. The error(8) delivery agent is + special: it always declares mail as undeliverable. It is not shown in the + figure above. + + The queue manager maintains a small active queue with the messages that it + has opened for delivery. The active queue acts as a limited window on + potentially large incoming or deferred queues. The limited active queue + prevents the queue manager from running out of memory under heavy load. + + The queue manager maintains a separate deferred queue for mail that cannot + be delivered, so that a large mail backlog will not slow down normal queue + accesses. The queue manager's strategy for delayed mail delivery attempts + is described in the QSHAPE_README and TUNING_README documents. + + * The trivial-rewrite(8) server resolves each recipient address according to + its local and remote address class, as defined in the ADDRESS_CLASS_README + document. Additional routing information can be specified with the optional + transport(5) table. The trivial-rewrite(8) server optionally queries the + relocated(5) table for recipients whose address has changed; mail for such + recipients is returned to the sender with an explanation. + + * The smtp(8) client looks up a list of mail exchangers for the destination + host, sorts the list by preference, and tries each server in turn until it + finds a server that responds. It then encapsulates the sender, recipient + and message content as required by the SMTP protocol; this includes + conversion of 8-bit MIME to 7-bit encoding. + + * The lmtp(8) client speaks a protocol similar to SMTP that is optimized for + delivery to mailbox servers such as Cyrus. The advantage of this setup is + that one Postfix machine can feed multiple mailbox servers over LMTP. The + opposite is true as well: one mailbox server can be fed over LMTP by + multiple Postfix machines. The LMTP_README document gives examples of how + to use the lmtp(8) client. + + * The local(8) delivery agent understands UNIX-style mailboxes, qmail- + compatible maildir files, Sendmail-style system-wide aliases(5) databases, + and Sendmail-style per-user .forward files. Multiple local delivery agents + can be run in parallel, but parallel delivery to the same user is usually + limited. + + The local(8) delivery agent has hooks for alternative forms of local + delivery: you can configure it to deliver to mailbox files in user home + directories, you can configure it to delegate mailbox delivery to an + external command such as procmail, or you can delegate delivery to a + different Postfix delivery agent. + + * The virtual(8) delivery agent is a bare-bones delivery agent that delivers + to UNIX-style mailbox or qmail-style maildir files only. This delivery + agent can deliver mail for multiple domains, which makes it especially + suitable for hosting lots of small domains on a single machine. This is + described in the VIRTUAL_README document. + + * The pipe(8) mailer is the outbound interface to other mail processing + systems (the Postfix sendmail(1) command being the inbound interface). The + interface is UNIX compatible: it provides information on the command line + and on the standard input stream, and expects a process exit status code as + defined in . Examples of delivery via the pipe(8) mailer are in + the MAILDROP_README and UUCP_README documents. + +PPoossttffiixx bbeehhiinndd tthhee sscceenneess + +The previous sections gave an overview of how Postfix server processes send and +receive mail. These server processes rely on other server processes that do +things behind the scenes. Where practical, each service will be visualized in +its own context. As before, names followed by a number are Postfix commands or +server programs, while unnumbered names inside shaded areas represent Postfix +queues. + + * The resident master(8) server is the supervisor that keeps an eye on the + well-being of the Postfix mail system. It is typically started at system + boot time with the "postfix start" command, and keeps running until the + system goes down. The master(8) server is responsible for starting Postfix + server processes to receive and deliver mail, and for restarting servers + that terminate prematurely because of some problem. The master(8) server is + also responsible for enforcing the server process count limits as specified + in the mmaasstteerr..ccff configuration file. The picture below gives the program + hierarchy when Postfix is started up. Only some of the mail handling daemon + processes are shown. + + postfix(1) + + | + | + + postfix-script(1) + + / | \ + | + / \ + + postsuper(1) master(8) postlog(1) + + / | \ + | + / \ + + smtpd(8) qmgr(8) local(8) + + * The anvil(8) server implements client connection and rate limiting for all + smtpd(8) servers. The TUNING_README document provides guidance for dealing + with mis-behaving SMTP clients. The anvil(8) service is not included with + Postfix version 2.1 or earlier. + + Network -> smtpd(8) <-> anvil(8) + + * The bounce(8), defer(8) and trace(8) servers each maintain their own queue + directory trees with per-message logfiles. This information is used to send + delivery or non-delivery notifications to the sender. + + The trace(8) service implements support for the Postfix "sendmail -bv" and + "sendmail -v" commands which produce reports about how Postfix delivers + mail, and is available with Postfix version 2.1 and later. See DEBUG_README + for examples. + + qmgr(8) Delivery + cleanup(8) -> Postfix -> agents + queue + + ^ | | + | v v + + (Non-) bounce(8) Queue id, + delivery <- defer(8) <- recipient, + notice trace(8) status + + ^ | + | v + + Per- + message + logfiles + + * The flush(8) servers maintain per-destination logs and implement both ETRN + and "sendmail -qRdestination", as described in the ETRN_README document. + This moves selected queue files from the deferred queue back to the + incoming queue and requests their delivery. The flush(8) service is + available with Postfix version 1.0 and later. + + incoming + ^ + deferred + + ^ + | + + smtpd(8) Destination Deferred Delivery + sendmail(1) - to flush -> flush(8) <- destination, - agents, + postqueue(1) queue id qmgr(8) + + ^ | + | v + + Per-dest- + ination + logs + + * The proxymap(8) servers provide read-only table lookup service to Postfix + processes. This overcomes chroot restrictions, and reduces the number of + open lookup tables by sharing one open table among multiple processes. + + * The showq(8) servers list the Postfix queue status. This is the queue + listing service that does the work for the mailq(1) and postqueue(1) + commands. + + mailq(1) Postfix + Output <- post- <- showq(8) <- queue + queue(1) + + * The spawn(8) servers run non-Postfix commands on request, with the client + connected via socket or FIFO to the command's standard input, output and + error streams. You can find examples of its use in the SMTPD_POLICY_README + document. + + * 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 + \ / + <- <- + +PPoossttffiixx ssuuppppoorrtt ccoommmmaannddss + +The Postfix architecture overview ends with a summary of command-line utilities +for day-to-day use of the Postfix mail system. Besides the Sendmail-compatible +sendmail(1), mailq(1), and newaliases(1) commands, the Postfix system comes +with it own collection of command-line utilities. For consistency, these are +all named postsomething. + + * The postfix(1) command controls the operation of the mail system. It is the + interface for starting, stopping, and restarting the mail system, as well + as for some other administrative operations. This command is reserved to + the super-user. + + * The postalias(1) command maintains Postfix aliases(5) type databases. This + is the program that does the work for the newaliases(1) command. + + * The postcat(1) command displays the contents of Postfix queue files. This + is a limited, preliminary utility. This program is likely to be superseded + by something more powerful that can also edit Postfix queue files. + + * The postconf(1) command displays or updates Postfix main.cf parameters and + displays system dependent information about the supported file locking + methods, and the supported types of lookup tables. + + * The postdrop(1) command is the mail posting utility that is run by the + Postfix sendmail(1) command in order to deposit mail into the maildrop + queue directory. + + * The postkick(1) command makes some Postfix internal communication channels + available for use in, for example, shell scripts. + + * The postlock(1) command provides Postfix-compatible mailbox locking for use + in, for example, shell scripts. + + * The postlog(1) command provides Postfix-compatible logging for shell + scripts. + + * The postmap(1) command maintains Postfix lookup tables such as canonical + (5), virtual(5) and others. It is a cousin of the UNIX makemap command. + + * The postqueue(1) command is the privileged command that is run by Postfix + sendmail(1) and mailq(1) in order to flush or list the mail queue. + + * The postsuper(1) command maintains the Postfix queue. It removes old + temporary files, and moves queue files into the right directory after a + change in the hashing depth of queue directories. This command is run at + mail system startup time and when Postfix is restarted. + diff --git a/postfix/README_FILES/PACKAGE_README b/postfix/README_FILES/PACKAGE_README index f92983822..dcbb679f9 100644 --- a/postfix/README_FILES/PACKAGE_README +++ b/postfix/README_FILES/PACKAGE_README @@ -1,71 +1,66 @@ -Purpose of this document -======================== +GGuuiiddeelliinneess ffoorr PPaacckkaaggee BBuuiillddeerrss -This document has hints and tips for those who manage their own -Postfix distribution for internal use, and for those who maintain -Postfix distributions for general use. +------------------------------------------------------------------------------- -General distributions: please provide a small default main.cf file -================================================================== +PPuurrppoossee ooff tthhiiss ddooccuummeenntt -The installed main.cf file must be small. PLEASE resist the temptation -to list all 100 million Postfix parameters in the main.cf file. -Postfix is supposed to be easy to configure. Listing all 100 million -parameters in main.cf defeats the purpose. +This document has hints and tips for those who manage their own Postfix +distribution for internal use, and for those who maintain Postfix distributions +for general use. -General distributions: please include the sample configuration files -==================================================================== +GGeenneerraall ddiissttrriibbuuttiioonnss:: pplleeaassee pprroovviiddee aa ssmmaallll ddeeffaauulltt mmaaiinn..ccff ffiillee -Please provide the sample-xxx files. If these files are not installed -in the same directory as main.cf, PLEASE update the notice at the -top of main.cf that advises the user of the existence of the -sample-xxx files. Without the sample-xxx files, Postfix will be -much more difficult to configure. +The installed main.cf file must be small. PLEASE resist the temptation to list +all 300+ parameters in the main.cf file. Postfix is supposed to be easy to +configure. Listing all 300+ in main.cf defeats the purpose. It is an invitation +for hobbyists to make random changes without understanding what they do, and +gets them into endless trouble. -Postfix Installation parameters -=============================== +GGeenneerraall ddiissttrriibbuuttiioonnss:: pplleeaassee iinncclluuddee RREEAADDMMEE oorr HHTTMMLL ffiilleess -Postfix installation is controlled by a dozen installation parameters. -See the postfix-install and post-install files for details. Most -parameters have system-dependent default settings that are configurable -at compile time, as described in the INSTALL file. +Please provide the applicable README or HTML files. They are referenced by the +Postfix manual pages and by other files. Without README or HTML files, Postfix +will be difficult if not impossible to configure. -Preparing a pre-built package for distribution to other systems -=============================================================== +PPoossttffiixx IInnssttaallllaattiioonn ppaarraammeetteerrss -You can build a Postfix package on a machine that does not have -Postfix installed on it. All you need is Postfix source code and -a compilation environment that is compatible with the target system. +Postfix installation is controlled by a dozen installation parameters. See the +postfix-install and post-install files for details. Most parameters have +system-dependent default settings that are configurable at compile time, as +described in the INSTALL file. + +PPrreeppaarriinngg aa pprree--bbuuiilltt ppaacckkaaggee ffoorr ddiissttrriibbuuttiioonn ttoo ootthheerr ssyysstteemmss + +You can build a Postfix package on a machine that does not have Postfix +installed on it. All you need is Postfix source code and a compilation +environment that is compatible with the target system. You can build a pre-built Postfix package as an unprivileged user. First compile Postfix. After successful compilation, execute: - % sh postfix-install + % sh postfix-install -You will be prompted for installation parameters. Specify an -install_root directory other than /. The mail_owner and setgid_group -installation parameter settings will be recorded in the main.cf -file, but they won't take effect until the package is unpacked and -installed on the destination machine. +You will be prompted for installation parameters. Specify an install_root +directory other than /. The mail_owner and setgid_group installation parameter +settings will be recorded in the main.cf file, but they won't take effect until +the package is unpacked and installed on the destination machine. -If you want to fully automate this process, specify all the -non-default installation parameters on the command line: +If you want to fully automate this process, specify all the non-default +installation parameters on the command line: - % sh postfix-install -non-interactive install_root=/some/where ... + % sh postfix-install -non-interactive + install_root=/some/where ... -Begin Security Alert. ---------------------- +BBeeggiinn SSeeccuurriittyy AAlleerrtt -When building an archive for distribution, be sure to archive only -files and symbolic links, not their parent directories. Otherwise, -unpacking a pre-built Postfix package may mess up permission and/or -ownership of system directories such as / /etc /usr /usr/bin /var -/var/spool and so on. This is especially an issue if you executed -postfix-install (see above) as an unprivileged user. +WWhheenn bbuuiillddiinngg aann aarrcchhiivvee ffoorr ddiissttrriibbuuttiioonn,, bbee ssuurree ttoo aarrcchhiivvee oonnllyy ffiilleess aanndd +ssyymmbboolliicc lliinnkkss,, nnoott tthheeiirr ppaarreenntt ddiirreeccttoorriieess.. OOtthheerrwwiissee,, uunnppaacckkiinngg aa pprree--bbuuiilltt +PPoossttffiixx ppaacckkaaggee mmaayy mmeessss uupp ppeerrmmiissssiioonn aanndd//oorr oowwnneerrsshhiipp ooff ssyysstteemm ddiirreeccttoorriieess +ssuucchh aass // //eettcc //uussrr //uussrr//bbiinn //vvaarr //vvaarr//ssppooooll aanndd ssoo oonn.. TThhiiss iiss eessppeecciiaallllyy aann +iissssuuee iiff yyoouu eexxeeccuutteedd ppoossttffiixx--iinnssttaallll ((sseeee aabboovvee)) aass aann uunnpprriivviilleeggeedd uusseerr.. -End Security Alert. -------------------- +EEnndd SSeeccuurriittyy AAlleerrtt Thus, to tar up the pre-built package, take the following steps: @@ -74,28 +69,28 @@ Thus, to tar up the pre-built package, take the following steps: % find . \! -type d -print | xargs tar cf SOMEWHERE/outputfile % gzip SOMEWHERE/outputfile -This way you will not include any directories that might cause trouble -upon extraction. +This way you will not include any directories that might cause trouble upon +extraction. -Installing a pre-built Postfix package -====================================== +IInnssttaalllliinngg aa pprree--bbuuiilltt PPoossttffiixx ppaacckkaaggee -To unpack a pre-built Postfix package, execute the equivalent of: + * To unpack a pre-built Postfix package, execute the equivalent of: # umask 022 # gzip -d . +PPoossttffiixx PPoossttggrreeSSQQLL HHoowwttoo -This implementation allows for multiple pgsql databases: you can -use one for a virtual table, one for an access table, and one for -an aliases table if you want. +------------------------------------------------------------------------------- -You can specify multiple servers for the same database, so that -Postfix can switch to a good database server if one goes bad. +IInnttrroodduuccttiioonn -Performance of postfix with pgsql has not been thoroughly tested, -however, we have found it to be stable. Busy mail servers using -pgsql maps will generate lots of concurrent pgsql clients, so the -pgsql server(s) should be run with this fact in mind. Any further -performance information, in addition to any feedback is most welcome. +The Postfix pgsql map type allows you to hook up Postfix to a PostgreSQL +database. This implementation allows for multiple pgsql databases: you can use +one for a virtual(5) table, one for an access(5) table, and one for an aliases +(5) table if you want. You can specify multiple servers for the same database, +so that Postfix can switch to a good database server if one goes bad. -This is based upon code written by Scott Cotton and Joshua Marcus, -IC Group, Inc. The PostgreSQL changes were done by Aaron Sethman -. Updates for Postfix 1.1.x and PostgreSQL -7.1+, and support for calling stored procedures were added by Philip -Warner (pjw@rhyme.com.au). +Busy mail servers using pgsql maps will generate lots of concurrent pgsql +clients, so the pgsql server(s) should be run with this fact in mind. You can +reduce the number of concurrent pgsql clients by using the Postfix proxymap(8) +service. -Building Postfix with PostgreSQL support -======================================== +BBuuiillddiinngg PPoossttffiixx wwiitthh PPoossttggrreeSSQQLL ssuuppppoorrtt -To use pgsql with Postfix on Debian GNU/Linux, you must install -the postfix-pgsql package. +Note: to use pgsql with Debian GNU/Linux's Postfix, all you need to do is to +install the postfix-pgsql package and you're done. There is no need to +recompile Postfix. -In order to build Postfix with pgsql map support, you specify --DHAS_PGSQL, the directory with the PostgreSQL header files, and -the location of the libpq library file. +In order to build Postfix with pgsql map support, you specify -DHAS_PGSQL, the +directory with the PostgreSQL header files, and the location of the libpq +library file. For example: - make tidy - make -f Makefile.init makefiles \ + % make tidy + % make -f Makefile.init makefiles \ 'CCARGS=-DHAS_PGSQL -I/usr/local/include/pgsql' \ 'AUXLIBS=-L/usr/local/lib -lpq' Then just run 'make'. -Configuring PostgreSQL lookup tables -==================================== +CCoonnffiigguurriinngg PPoossttggrreeSSQQLL llooookkuupp ttaabblleess -Once postfix is built with pgsql support, you can specify a map type -in main.cf like this: +Once Postfix is built with pgsql support, you can specify a map type in main.cf +like this: -alias_maps = pgsql:/etc/postfix/pgsql-aliases.cf + /etc/postfix/main.cf: + alias_maps = pgsql:/etc/postfix/pgsql-aliases.cf -The file /etc/postfix/pgsql-aliases.cf specifies lots of information -telling postfix how to reference the pgsql database. An example -pgsql map config file follows: +The file /etc/postfix/pgsql-aliases.cf specifies lots of information telling +postfix how to reference the pgsql database. For a complete description, see +the pgsql_table(5) manual page. +EExxaammppllee:: llooccaall aalliiaasseess + +# +# pgsql config file for local(8) aliases(5) lookups # -# pgsql config file for alias lookups on postfix -# comments are ok. + # +# The hosts that Postfix will try to connect to +hosts = host1.some.domain host2.some.domain -# the user name and password to log into the pgsql server +# The user name and password to log into the pgsql server. user = someone -password = some_password +password = some_password -# the database name on the servers +# The database name on the servers. dbname = customer_database -# the table name +# The table name. table = mxaliases -# these should be obvious :-) +# Query components, see below. select_field = forw_addr where_field = alias -# you may specify additional_conditions here +# You may specify additional_conditions or leave this empty. additional_conditions = and status = 'paid' -# the above variables will result in a query of the form: +# The above variables will result in a query of the form: # # select forw_addr from mxaliases where alias = '$lookup' and status = 'paid' # # ($lookup is escaped so if it contains single quotes or other odd -# characters, it will not cause a parse error in the sql). - -# Alternatively, you can override the default SELECT statement (and the -# above table, select_field, where_field, and additional_conditions) by -# specifying the query: - -#query = select forw_addr from mxaliases where alias = '%s' and status = 'paid' - -# Before the query is actually issued, all occurences of %s are replaced -# with the address to look up, %u are replaced with the user portion, -# and %d with the domain portion. - -# If you just want to use a PostgreSQL function, you can ignore the -# table name, select_field, where_field and additional_conditions, and -# just specify a database function to call: - -#select_function = my_lookup_user_alias - -# This is equivalent to: -# -#query = select my_lookup_user_alias('%s') +# characters, it will not cause problems). # -# and overrides both the query parameter and the table-related fields -# above. -# -# As of 25-Jun-2002, if the function returns a single row and a single -# column AND that value is NULL, then the result will be treated as -# if the key was not in the dictionary. -# -# Future versions of PG will allow functions to return result sets. -# - -# -# the hosts that postfix will try to connect to -# and query from (in the order listed) -# specify unix: for unix-domain sockets, inet: for TCP connections (default) -hosts = host1.some.domain host2.some.domain unix:/file/name - -# end pgsql config file - -Alternatively, these parameters can be defined in main.cf. To that -effect, the map should be specified as "pgsql:name", and the parameters -should be prefixed with the name you've given the map in its definition, -and an underscore. For example, the above settings can also be written -in main.cf as: - -# pgsql definitions in main.cf - -alias_maps = pgsql:pgsqlsource +# You may also override the built-in SELECT template. See pgsql_table(5) +# for details. -pgsqlsource_user = someone -pgsqlsource_password = some_password -pgsqlsource_dbname = customer_database -pgsqlsource_table = mxaliases -pgsqlsource_select_field = forw_addr -pgsqlsource_where_field = alias -pgsqlsource_additional_conditions = and status = 'paid' -#pgsqlsource_select_function = my_lookup_user_alias -pgsqlsource_hosts = host1.some.domain host2.some.domain unix:/file/name +UUssiinngg mmiirrrroorreedd ddaattaabbaasseess -# end mysql definitions +Sites that have a need for multiple mail exchangers may enjoy the convenience +of using a networked mailer database, but do not want to introduce a single +point of failure to their system. +For this reason we've included the ability to have Postfix reference multiple +hosts for access to a single pgsql map. This will work if sites set up mirrored +pgsql databases on two or more hosts. -Using mirrored databases -======================== +Whenever queries fail with an error at one host, the rest of the hosts will be +tried in random order. If no pgsql server hosts are reachable, then mail will +be deferred until at least one of those hosts is reachable. -Sites that have a need for multiple mail exchangers may enjoy the -convenience of using a networked mailer database, but do not want -to introduce a single point of failure to their system. +CCrreeddiittss -For this reason we've included the ability to have Postfix reference -multiple hosts for access to a single pgsql map. This will work -if sites set up mirrored pgsql databases on two or more hosts. + * This code is based upon the Postfix mysql map by Scott Cotton and Joshua + Marcus, IC Group, Inc. + * The PostgreSQL changes were done by Aaron Sethman. + * Updates for Postfix 1.1.x and PostgreSQL 7.1+ and support for calling + stored procedures were added by Philip Warner. + * LaMont Jones was the initial Postfix pgsql maintainer. + * Liviu Daia revised the configuration interface and added the main.cf + configuration feature. -Whenever queries fail with an error at one host, the rest of the -hosts will be tried in order. Each host that is in an error state -will undergo a reconnection attempt every so often, and if no pgsql -server hosts are reachable, then mail will be deferred until at -least one of those hosts is reachable. diff --git a/postfix/README_FILES/QMQP_README b/postfix/README_FILES/QMQP_README index a23e1a3ef..6bb664ffd 100644 --- a/postfix/README_FILES/QMQP_README +++ b/postfix/README_FILES/QMQP_README @@ -1,73 +1,5 @@ -Postfix QMQP server support -=========================== +PPoossttffiixx qqmmaaiill aanndd eezzmmllmm ssuuppppoorrtt -Postfix has preliminary server support for the QMQP protocol, so -that Postfix can be used as a backend for the Ezmlm-idx mailing -list manager. This support includes the qmqp-source and qmqp-sink -programs for protocol stress testing. +------------------------------------------------------------------------------- +This document will be made available via http://www.postfix.org/. -Turning on the Postfix QMQP service -=================================== - -To enable QMQP server support on an existing Postfix system you -have to add the following line to /etc/postfix/master.cf: - -628 inet n - n - - qmqpd - -A "postfix reload" command is necessary to enable the service. - -Postfix QMQP server access control -================================== - -By default, the QMQP server does not accept mail from any client. -This is because the QMQP server relays mail to any destination -(the "protocol" has no provision to reject specific recipients). - -To authorize QMQP clients, edit /etc/postfix/main.cf and specify -a list of client patterns. - -qmqpd_authorized_clients = client, client, ... - -Example: - -qmqpd_authorized_clients = $mynetworks - -A list pattern specifies a host name, a domain name, an internet -address, or a network/mask pattern, where the mask specifies the -number of bits in the network part. When a pattern specifies a -file name, its contents are substituted for the file name; when a -pattern is a type:name table specification, table lookup is used -instead. This allows you to administer the trusted clients in LDAP -or regular expression maps, both of which are probably overkill. - -Patterns are separated by whitespace and/or commas. In order to -reverse the result, precede a non-file name pattern with an -exclamation point (!). - -Setting up ezmlm-idx to use Postfix QMQP support -================================================ - -Note: you still need qmail to feed the messages INTO ezmlm-idx. -Postfix presently only supports distribution of mailing list traffic -FROM ezmlm-idx. - -http://www.ezmlm.org/faq-0.40/FAQ-4.html#ss4.19 describes how to -make ezmlm-idx work over QMQP. - -The following is based on hearsay. Do not ask Wietse how to make -ezmlm-idx work. Wietse does not have the time to personally install -and play with every mailing list manager. - -1 - You must list QMQP servers with numerical IP address. Hostnames - do not work. This means you cannot DNS-based load balancing to - spread the load over multiple QMQP servers. - -2 - QMQP support is incomplete with ezmlm-idx-0.40. - - - ezmlm-send will use QMQP if you specify the undocumented -Q - command-line option in your .qmail-listname file. - - - ezmlm-get will use QMQP if the file qmpqservers/0 exists. - - - ezmlm-moderate does not support QMQP. This is not a problem - if you only use unmoderated mailing lists. diff --git a/postfix/README_FILES/QSHAPE_README b/postfix/README_FILES/QSHAPE_README new file mode 100644 index 000000000..0a0c8f961 --- /dev/null +++ b/postfix/README_FILES/QSHAPE_README @@ -0,0 +1,602 @@ +PPoossttffiixx BBoottttlleenneecckk AAnnaallyyssiiss + +------------------------------------------------------------------------------- + +PPuurrppoossee ooff tthhiiss ddooccuummeenntt + +This document describes the "qshape" program which helps the administrator +understand the Postfix queue message distribution sorted by time and by sender +or recipient domain. qshape is bundled with the Postfix 2.1 source under the +"auxiliary" directory. In order to understand the output of qshape, it useful +to understand the various Postfix queues. To this end the role of each Postfix +queue directory is described briefly in the "Background info: Postfix queue +directories" section near the end of this document. + +This document covers the following topics: + + * Introducing the qshape tool + * Trouble shooting with qshape + * Example 1: Healthy queue + * Example 2: Deferred queue full of dictionary attack bounces + * Example 3: Congestion in the active queue + * Example 4: High volume destination backlog + * Background info: Postfix queue directories + + o The "maildrop" queue + o The "hold" queue + o The "incoming" queue + o The "active" queue + o The "deferred" queue + + * Credits + +IInnttrroodduucciinngg tthhee qqsshhaappee ttooooll + +When mail is draining slowly or the queue is unexpectedly large, run "qshape" +as the super-user (root) to help zero in on the problem. The "qshape" program +displays a tabular view of the Postfix queue contents. + + * On the horizontal axis, it displays the queue age with fine granularity for + recent messages and (geometrically) less fine granularity for older + messages. + + * The vertical axis displays the destination (or with the "-s" switch the + sender) domain. Domains with the most messages are listed first. + +For example, in the output below we see the top 10 lines of the (mostly forged) +sender domain distribution for captured spam in the "hold" queue: + + $ qshape -s hold | head + T 5 10 20 40 80 160 320 640 1280 1280+ + TOTAL 486 0 0 1 0 0 2 4 20 40 419 + yahoo.com 14 0 0 1 0 0 0 0 1 0 12 + extremepricecuts.net 13 0 0 0 0 0 0 0 2 0 11 + ms35.hinet.net 12 0 0 0 0 0 0 0 0 1 11 + winnersdaily.net 12 0 0 0 0 0 0 0 2 0 10 + hotmail.com 11 0 0 0 0 0 0 0 0 1 10 + worldnet.fr 6 0 0 0 0 0 0 0 0 0 6 + ms41.hinet.net 6 0 0 0 0 0 0 0 0 0 6 + osn.de 5 0 0 0 0 0 1 0 0 0 4 + + * The "T" column shows the total (in this case sender) count for each domain. + The columns with numbers above them, show counts for messages aged fewer + than that many minutes, but not younger than the age limit for the previous + column. The row labeled "TOTAL" shows the total count for all domains. + + * In this example, there are 14 messages allegedly from yahoo.com, 1 between + 10 and 20 minutes old, 1 between 320 and 640 minutes old and 12 older than + 1280 minutes (1440 minutes in a day). + +By default, qshape shows statistics for the union of both the incoming and +active queues which are the most relevant queues to look at when analyzing +performance. + +One can request an alternate list of queues: + + $ qshape deferred | less + $ qshape incoming active deferred | less + +this will show the age distribution of the deferred queue or the union of the +incoming active and deferred queues. + +Command line options control the number of display "buckets", the age limit for +the smallest bucket, display of parent domain counts and so on. The "-h" option +outputs a summary of the available switches. + +TTrroouubbllee sshhoooottiinngg wwiitthh qqsshhaappee + +Large numbers in the qshape output represent a large number of messages that +are destined to (or alleged to come from) a particular domain. It should be +possible to tell at a glance which domains dominate the queue sender or +recipient counts, approximately when a burst of mail started, and when it +stopped. + +The problem destinations or sender domains appear near the top left corner of +the output table. Remember that the active queue can accommodate up to 20000 +($qmgr_message_active_limit) messages. To check wether this limit has been +reached, use: + + $ qshape -s active | head (show sender statistics) + +If the total sender count is below 20000 the active queue is not yet saturated, +any high volume sender domains show near the top of the output. + +The active queue is also limited to at most 20000 recipient addresses +($qmgr_message_recipient_limit). To check for exhaustion of this limit use: + + $ qshape active | head (show recipient statistics) + +Having found the high volume domains, it is often useful to search the logs for +recent messages pertaining to the domains in question. + + # Find deliveries to example.com + # + $ tail -10000 /var/log/maillog | + egrep -i ': to=<.*@example\.com>,' | + less + + # Find messages from example.com + # + $ tail -10000 /var/log/maillog | + egrep -i ': from=<.*@example\.com>,' | + less + +You may want to drill in on some specific queue ids: + + # Find all messages for a specific queue id. + # + $ tail -10000 /var/log/maillog | egrep ': 2B2173FF68: ' + +Also look for queue manager warning messages in the log. These warnings can +suggest strategies to reduce congestion. + + $ egrep 'qmgr.*(panic|fatal|error|warning):' /var/log/maillog + +When all else fails try the Postfix mailing list for help, but please don't +forget to include the top 10 or 20 lines of "qshape" output. + +EExxaammppllee 11:: HHeeaalltthhyy qquueeuuee + +When looking at just the incoming and active queues, under normal conditions +(no congestion) the incoming and active queues are nearly empty. Mail leaves +the system almost as quickly as it comes in or is deferred without congestion +in the active queue. + + $ qshape (show incoming and active queue status) + + T 5 10 20 40 80 160 320 640 1280 1280+ + TOTAL 5 0 0 0 1 0 0 0 1 1 2 + meri.uwasa.fi 5 0 0 0 1 0 0 0 1 1 2 + +If one looks at the two queues separately, the incoming queue is empty or +perhaps briefly has one or two messages, while the active queue holds more +messages and for a somewhat longer time: + + $ qshape incoming + + T 5 10 20 40 80 160 320 640 1280 1280+ + TOTAL 0 0 0 0 0 0 0 0 0 0 0 + + $ qshape active + + T 5 10 20 40 80 160 320 640 1280 1280+ + TOTAL 5 0 0 0 1 0 0 0 1 1 2 + meri.uwasa.fi 5 0 0 0 1 0 0 0 1 1 2 + +EExxaammppllee 22:: DDeeffeerrrreedd qquueeuuee ffuullll ooff ddiiccttiioonnaarryy aattttaacckk bboouunncceess + +This is from a server where recipient validation is not yet available for some +of the hosted domains. Dictionary attacks on the unvalidated domains result in +bounce backscatter. The bounces dominate the queue, but with proper tuning they +do not saturate the incoming or active queues. The high volume of deferred mail +is not a direct cause for alarm. + + $ qshape deferred | head + + T 5 10 20 40 80 160 320 640 1280 1280+ + TOTAL 2234 4 2 5 9 31 57 108 201 464 1353 + heyhihellothere.com 207 0 0 1 1 6 6 8 25 68 92 + pleazerzoneprod.com 105 0 0 0 0 0 0 0 5 44 56 + groups.msn.com 63 2 1 2 4 4 14 14 14 8 0 + orion.toppoint.de 49 0 0 0 1 0 2 4 3 16 23 + kali.com.cn 46 0 0 0 0 1 0 2 6 12 25 + meri.uwasa.fi 44 0 0 0 0 1 0 2 8 11 22 + gjr.paknet.com.pk 43 1 0 0 1 1 3 3 6 12 16 + aristotle.algonet.se 41 0 0 0 0 0 1 2 11 12 15 + +The domains shown are mostly bulk-mailers and all the volume is the tail end of +the time distribution, showing that short term arrival rates are moderate. +Larger numbers and lower message ages are more indicative of current trouble. +Old mail still going nowhere is largely harmless so long as the active and +incoming queues are short. We can also see that the groups.msg.com +undeliverables are low rate steady stream rather than a concentrated dictionary +attack that is now over. + + $ qshape -s deferred | head + + T 5 10 20 40 80 160 320 640 1280 1280+ + TOTAL 2193 4 4 5 8 33 56 104 205 465 1309 + MAILER-DAEMON 1709 4 4 5 8 33 55 101 198 452 849 + example.com 263 0 0 0 0 0 0 0 0 2 261 + example.org 209 0 0 0 0 0 1 3 6 11 188 + example.net 6 0 0 0 0 0 0 0 0 0 6 + example.edu 3 0 0 0 0 0 0 0 0 0 3 + example.gov 2 0 0 0 0 0 0 0 1 0 1 + example.mil 1 0 0 0 0 0 0 0 0 0 1 + +Looking at the sender distribution, we see that as expected most of the +messages are bounces. + +EExxaammppllee 33:: CCoonnggeessttiioonn iinn tthhee aaccttiivvee qquueeuuee + +This example is taken from a Feb 2004 discussion on the Postfix Users list. +Congestion was reported with the active and incoming queues large and not +shrinking despite very large delivery agent process limits. The thread is +archived at: http://groups.google.com/groups?th=636626c645f5bbde + +Using an older version of "qshape" it was quickly determined that all the +messages were for just a few destinations: + + $ qshape (show incoming and active queue status) + + T A 5 10 20 40 80 160 320 320+ + TOTAL 11775 9996 0 0 1 1 42 94 221 1420 + user.sourceforge.net 7678 7678 0 0 0 0 0 0 0 0 + lists.sourceforge.net 2313 2313 0 0 0 0 0 0 0 0 + gzd.gotdns.com 102 0 0 0 0 0 0 0 2 100 + +The "A" column showed the count of messages in the active queue, and the +numbered columns showed totals for the deferred queue. At 10000 messages +(Postfix 1.x active queue size limit) the active queue is full. The incoming +was growing rapidly. + +With the trouble destinations clearly identified, the administrator quickly +found and fixed the problem. It is substantially harder to glean the same +information from the logs. While a careful reading of mailq(1) output should +yield similar results, it is much harder to gauge the magnitude of the problem +by looking at the queue one message at a time. + +EExxaammppllee 44:: HHiigghh vvoolluummee ddeessttiinnaattiioonn bbaacckklloogg + +When a site you send a lot of email to is down or slow, mail messages will +rapidly build up in the deferred queue, or worse, in the active queue. The +qshape output will show large numbers for the destination domain in all age +buckets that overlap the starting time of the problem: + + $ qshape deferred | head + + T 5 10 20 40 80 160 320 640 1280 1280+ + TOTAL 5000 200 200 400 800 1600 1000 200 200 200 200 + highvolume.com 4000 160 160 320 640 1280 1440 0 0 0 0 + ... + +Here the "highvolume.com" destination is continuing to accumulate deferred +mail. The incoming and active queues are fine, but the deferred queue started +growing some time between 1 and 2 hours ago and continues to grow. + +If the high volume destination is not down, but is instead slow, one might see +similar congestion in the active queue. Active queue congestion is a greater +cause for alarm; one might need to take measures to ensure that the mail is +deferred instead or even add an access(5) rule asking the sender to try again +later. + +If a high volume destination exhibits frequent bursts of consecutive +connections refused by all MX hosts or "421 Server busy errors", it is possible +for the queue manager to mark the destination as "dead" despite the transient +nature of the errors. The destination will be retried again after the +expiration of a $minimal_backoff_time timer. If the error bursts are frequent +enough it may be that only a small quantity of email is delivered before the +destination is again marked "dead". + +The MTA that has been observed most frequently to exhibit such bursts of errors +is Microsoft Exchange, which refuses connections under load. Some proxy virus +scanners in front of the Exchange server propagate the refused connection to +the client as a "421" error. + +Note that it is now possible to configure Postfix to exhibit similarly erratic +behavior by misconfiguring the anvil(8) server (not included in Postfix 2.1.). +Do not use anvil(8) for steady-state rate limiting, its purpose is DoS +prevention and the rate limits set should be very generous! + +In the long run it is hoped that the Postfix dead host detection and +concurrency control mechanism will be tuned to be more "noise" tolerant. If one +finds oneself needing to deliver a high volume of mail to a destination that +exhibits frequent brief bursts of errors, there is a subtle workaround. + + * In master.cf set up a dedicated clone of the "smtp" transport for the + destination in question. + + * In master.cf configure a reasonable process limit for the transport (a + number in the 10-20 range is typical). + + * IMPORTANT!!! In main.cf configure a very large initial and destination + concurrency limit for this transport (say 200). + + /etc/postfix/main.cf: + initial_destination_concurrency = 200 + transportname_destination_concurrency_limit = 200 + + Where transportname is the name of the master.cf entry in question. + +The effect of this surprising configuration is that up to 200 consecutive +errors are tolerated without marking the destination dead, while the total +concurrency remains reasonable (10-20 processes). This trick is only for a very +specialized situation: high volume delivery into a channel with multi-error +bursts that is capable of high throughput, but is repeatedly throttled by the +bursts of errors. + +When a destination is unable to handle the load even after the Postfix process +limit is reduced to 1, a desperate measure is to insert brief delays between +delivery attempts. + + * In the transport map entry for the problem destination, specify a dead host + as the primary nexthop. + + * In the master.cf entry for the transport specify the problem destination as + the fallback_relay and specify a small smtp_connect_timeout value. + + /etc/postfix/transport: + problem.example.com slow:[dead.host] + + /etc/postfix/master.cf: + # service type private unpriv chroot wakeup maxproc command + slow unix - - n - 1 smtp + -o fallback_relay=problem.example.com + -o smtp_connect_timeout=1 + +This solution forces the Postfix smtp(8) client to wait for +$smtp_connect_timeout seconds between deliveries. The solution depends on +Postfix connection management details, and needs to be updated when SMTP +connection caching is introduced. + +Hopefully a more elegant solution to these problems will be found in the +future. + +BBaacckkggrroouunndd iinnffoo:: PPoossttffiixx qquueeuuee ddiirreeccttoorriieess + +The following sections describe Postfix queues: their purpose, what normal +behavior looks like, and how to diagnose abnormal behavior. + +TThhee ""mmaaiillddrroopp"" qquueeuuee + +Messages that have been submitted via the Postfix sendmail(1) command, but not +yet brought into the main Postfix queue by the pickup(8) service, await +processing in the "maildrop" queue. Messages can be added to the "maildrop" +queue even when the Postfix system is not running. They will begin to be +processed once Postfix is started. + +The "maildrop" queue is drained by the single threaded pickup(8) service +scanning the queue directory periodically or when notified of new message +arrival by the postdrop(1) program. The postdrop(1) program is a setgid helper +that allows the unprivileged Postfix sendmail(1) program to inject mail into +the "maildrop" queue and to notify the pickup(8) service of its arrival. + +All mail that enters the main Postfix queue does so via the cleanup(8) service. +The cleanup service is responsible for envelope and header rewriting, header +and body regular expression checks, automatic bcc recipient processing and +guaranteed insertion of the message into the Postfix "incoming" queue. + +In the absence of excessive CPU consumption in cleanup(8) header or body +regular expression checks or other software consuming all available CPU +resources, Postfix performance is disk I/O bound. The rate at which the pickup +(8) service can inject messages into the queue is largely determined by disk +access times, since the cleanup(8) service must commit the message to stable +storage before returning success. The same is true of the postdrop(1) program +writing the message to the "maildrop" directory. + +As the pickup service is single threaded, it can only deliver one message at a +time at a rate that does not exceed the reciprocal disk I/O latency (+ CPU if +not negligible) of the cleanup service. + +Congestion in this queue is indicative of an excessive local message submission +rate or perhaps excessive CPU consumption in the cleanup(8) service due to +excessive body_checks. + +Note, that once the active queue is full, the cleanup service will attempt to +slow down message injection by pausing $in_flow_delay for each message. In this +case "maildrop" queue congestion may be a consequence of congestion downstream, +rather than a problem in its own right. + +Note also, that one should not attempt to deliver large volumes of mail via the +pickup(8) service. High volume sites must avoid using content filters that +reinject scanned mail via Postfix sendmail(1) and postdrop(1). + +A high arrival rate of locally submitted mail may be an indication of an +uncaught forwarding loop, or a run-away notification program. Try to keep the +volume of local mail injection to a moderate level. + +The "postsuper -r" command can place selected messages into the "maildrop" +queue for reprocessing. This is most useful for resetting any stale +content_filter settings. Requeuing a large number of messages using "postsuper +-r" can clearly cause a spike in the size of the "maildrop" queue. + +TThhee ""hhoolldd"" qquueeuuee + +The administrator can define "smtpd" access(5) policies, or cleanup(8) header/ +body checks that cause messages to be automatically diverted from normal +processing and placed indefinitely in the "hold" queue. Messages placed in the +"hold" queue stay there until the administrator intervenes. No periodic +delivery attempts are made for messages in the "hold" queue. The postsuper(1) +command can be used to manually release messages into the "deferred" queue. + +Messages can potentially stay in the "hold" queue for a time exceeding the +normal maximal queue lifetime (after which undelivered messages are bounced +back to the sender). If such "old" messages need to be released from the "hold" +queue, they should typically be moved into the "maildrop" queue, so that the +message gets a new timestamp and is given more than one opportunity to be +delivered. Messages that are "young" can be moved directly into the "deferred" +queue. + +The "hold" queue plays little role in Postfix performance, and monitoring of +the "hold" queue is typically more closely motivated by tracking spam and +malware, than by performance issues. + +TThhee ""iinnccoommiinngg"" qquueeuuee + +All new mail entering the Postfix queue is written by the cleanup(8) service +into the "incoming" queue. New queue files are created owned by the "postfix" +user with an access bitmask (or mode) of 0600. Once a queue file is ready for +further processing the cleanup(8) service changes the queue file mode to 0700 +and notifies the queue manager of new mail arrival. The queue manager ignores +incomplete queue files whose mode is 0600, as these are still being written by +cleanup. + +The queue manager scans the incoming queue bringing any new mail into the +"active" queue if the active queue resource limits have not been exceeded. By +default, the active queue accommodates at most 20000 messages. Once the active +queue message limit is reached, the queue manager stops scanning the incoming +(and deferred, see below) queue. + +Under normal conditions the incoming queue is nearly empty (has only mode 0600 +files), with the queue manager able to import new messages into the active +queue as soon as they become available. + +The incoming queue grows when the message input rate spikes above the rate at +which the queue manager can import messages into the active queue. The main +factor slowing down the queue manager is transport queries to the trivial- +rewrite service. If the queue manager is routinely not keeping up, consider not +using "slow" lookup services (MySQL, LDAP, ...) for transport lookups or +speeding up the hosts that provide the lookup service. + +The in_flow_delay parameter is used to clamp the input rate when the queue +manager starts to fall behind. The cleanup(8) service will pause for +$in_flow_delay seconds before creating a new queue file if it cannot obtain a +"token" from the queue manager. + +Since the number of cleanup(8) processes is limited in most cases by the SMTP +server concurrency, the input rate can exceed the output rate by at most "SMTP +connection count" / $in_flow_delay messages per second. + +With a default process limit of 100, and an in_flow_delay of 1s, the coupling +is strong enough to limit a single run-away injector to 1 message per second, +but is not strong enough to deflect an excessive input rate from many sources +at the same time. + +If a server is being hammered from multiple directions, consider raising the +in_flow_delay to 10 seconds, but only if the incoming queue is growing even +while the active queue is not full and the trivial-rewrite service is using a +fast transport lookup mechanism. + +TThhee ""aaccttiivvee"" qquueeuuee + +The queue manager is a delivery agent scheduler; it works to ensure fast and +fair delivery of mail to all destinations within designated resource limits. + +The active queue is somewhat analogous to an operating system's process run +queue. Messages in the active queue are ready to be sent (runnable), but are +not necessarily in the process of being sent (running). + +While most Postfix administrators think of the "active" queue as a directory on +disk, the real "active" queue is a set of data structures in the memory of the +queue manager process. + +Messages in the "maildrop", "hold", "incoming" and "deferred" queues (see +below) do not occupy memory; they are safely stored on disk waiting for their +turn to be processed. The envelope information for messages in the "active" +queue is managed in memory, allowing the queue manager to do global scheduling, +allocating available delivery agent processes to an appropriate message in the +active queue. + +Within the active queue, (multi-recipient) messages are broken up into groups +of recipients that share the same transport/nexthop combination; the group size +is capped by the transport's recipient concurrency limit. + +Multiple recipient groups (from one or more messages) are queued for delivery +via the common transport/nexthop combination. The destination concurrency limit +for the transports caps the number of simultaneous delivery attempts for each +nexthop. Transports with a recipient concurrency limit of 1 are special: these +are grouped by the actual recipient address rather than the nexthop, thereby +enabling per-recipient concurrency limits rather than per-domain concurrency +limits. Per-recipient limits are appropriate when performing final delivery to +mailboxes rather than when relaying to a remote server. + +Congestion occurs in the active queue when one or more destinations drain +slower than the corresponding message input rate. If a destination is down for +some time, the queue manager will mark it dead, and immediately defer all mail +for the destination without trying to assign it to a delivery agent. In this +case the messages will quickly leave the active queue and end up in the +deferred queue. If the destination is instead simply slow, or there is a +problem causing an excessive arrival rate the active queue will grow and will +become dominated by mail to the congested destination. + +The only way to reduce congestion is to either reduce the input rate or +increase the throughput. Increasing the throughput requires either increasing +the concurrency or reducing the latency of deliveries. + +For high volume sites a key tuning parameter is the number of "smtp" delivery +agents allocated to the "smtp" and "relay" transports. High volume sites tend +to send to many different destinations, many of which may be down or slow, so a +good fraction of the available delivery agents will be blocked waiting for slow +sites. Also mail destined across the globe will incur large SMTP command- +response latencies, so high message throughput can only be achieved with more +concurrent delivery agents. + +The default "smtp" process limit of 100 is good enough for most sites, and may +even need to be lowered for sites with low bandwidth connections (no use +increasing concurrency once the network pipe is full). When one finds that the +queue is growing on an "idle" system (CPU, disk I/O and network not exhausted) +the remaining reason for congestion is insufficient concurrency in the face of +a high average latency. If the number of outbound SMTP connections (either +ESTABLISHED or SYN_SENT) reaches the process limit, mail is draining slowly and +the system and network are not loaded, raise the "smtp" and/or "relay" process +limits! + +Especially for the "relay" transport, consider lower SMTP connection timeouts +(1-5 seconds) and higher than default destination concurrency limits. Compute +the expected latency when 1 out of N of the MX hosts for a high volume site is +down and not responding, and make sure that the configured concurrency divided +by this latency exceeds the required steady-state message rate. If the +destination is managed by you, consider load balancers in front of groups of MX +hosts. Load balancers have higher uptime and will be able to hide individual MX +host failures. + +If necessary, dedicate and tune custom transports for high volume destinations. + +Another common cause of congestion is unwarranted flushing of the entire +deferred queue. The deferred queue holds messages that are likely to fail to be +delivered and are also likely to be slow to fail delivery (timeouts). This +means that the most common reaction to a large deferred queue (flush it!) is +more than likely counter- productive, and is likely to make the problem worse. +Do not flush the deferred queue unless you expect that most of its content has +recently become deliverable (e.g. relayhost back up after an outage)! + +Note that whenever the queue manager is restarted, there may already be +messages in the active queue directory, but the "real" active queue in memory +is empty. In order to recover the in-memory state, the queue manager moves all +the active queue messages back into the incoming queue, and then uses its +normal incoming queue scan to refill the active queue. The process of moving +all the messages back and forth, redoing transport table (trivial-rewrite(8) +resolve service) lookups, and re-importing the messages back into memory is +expensive. At all costs, avoid frequent restarts of the queue manager. + +TThhee ""ddeeffeerrrreedd"" qquueeuuee + +When all the deliverable recipients for a message are delivered, and for some +recipients delivery failed for a transient reason (it might succeed later), the +message is placed in the deferred queue. + +The queue manager scans the deferred queue periodically. The scan interval is +controlled by the queue_run_delay parameter. While a deferred queue scan is in +progress, if an incoming queue scan is also in progress (ideally these are +brief since the incoming queue should be short), the queue manager alternates +between bringing a new "incoming" message and a new "deferred" message into the +queue. This "round-robin" strategy prevents starvation of either the incoming +or the deferred queues. + +Each deferred queue scan only brings a fraction of the deferred queue back into +the active queue for a retry. This is because each message in the deferred +queue is assigned a "cool-off" time when it is deferred. This is done by time- +warping the modification times of the queue file into the future. The queue +file is not eligible for a retry if its modification time is not yet reached. + +The "cool-off" time is at least $minimal_backoff_time and at most +$maximal_backoff_time. The next retry time is set by doubling the message's age +in the queue, and adjusting up or down to lie within the limits. This means +that young messages are initially retried more often than old messages. + +If a high volume site routinely has large deferred queues, it may be useful to +adjust the queue_run_delay, minimal_backoff_time and maximal_backoff_time to +provide short enough delays on first failure, with perhaps longer delays after +multiple failures, to reduce the retransmission rate of old messages and +thereby reduce the quantity of previously deferred mail in the active queue. + +One common cause of large deferred queues is failure to validate recipients at +the SMTP input stage. Since spammers routinely launch dictionary attacks from +unrepliable sender addresses, the bounces for invalid recipient addresses clog +the deferred queue (and at high volumes proportionally clog the active queue). +Recipient validation is strongly recommended through use of the +local_recipient_maps and relay_recipient_maps parameters. + +When a host with lots of deferred mail is down for some time, it is possible +for the entire deferred queue to reach its retry time simultaneously. This can +lead to a very full active queue once the host comes back up. The phenomenon +can repeat approximately every maximal_backoff_time seconds if the messages are +again deferred after a brief burst of congestion. Ideally, in the future +Postfix will add a random offset to the retry time (or use a combination of +strategies) to reduce the chances of repeated complete deferred queue flushes. + +CCrreeddiittss + +The "qshape" program was developed by Victor Duchovni of Morgan Stanley, who +also wrote the initial version of this document. + diff --git a/postfix/README_FILES/RESTRICTION_CLASS_README b/postfix/README_FILES/RESTRICTION_CLASS_README index f623d2878..7b62659ce 100644 --- a/postfix/README_FILES/RESTRICTION_CLASS_README +++ b/postfix/README_FILES/RESTRICTION_CLASS_README @@ -1,24 +1,156 @@ -Per client/helo/sender/recipient UCE restrictions -================================================= - -The Postfix SMTP server allows you to specify UCE restrictions on -the right-hand side of SMTPD access tables, so that you can have -different UCE restrictions for different clients or users. - -The only anomalies in this scheme are that (1) message header_checks -and body_checks are still the same for every message, and (2) you -must use a restriction class name (see below) if you want to specify -a lookup table on the right-hand side of an access table (this is -because Postfix needs to open those tables ahead of time). - -Restriction classes allow you to give easy-to-remember names to -groups of UCE restrictions (such as permissive, restrictive, and -so on). For example in main.cf: - - smtpd_restriction_classes = restrictive, permissive - restrictive = reject_unknown_sender reject_unknown_client ... - permissive = permit - -With this in place, you can use "restrictive" or "permissive" on -the right-hand side of your per-client/helo/sender/recipient SMTPD -access tables. +PPoossttffiixx PPeerr--CClliieenntt//UUsseerr//eettcc.. AAcccceessss CCoonnttrrooll + +------------------------------------------------------------------------------- + +PPoossttffiixx rreessttrriiccttiioonn ccllaasssseess + +The Postfix SMTP server supports access restrictions such as reject_rbl_client +or reject_unknown_client on the right-hand side of SMTP server access(5) +tables. This allows you to implement different junk mail restrictions for +different clients or users. + +Having to specify lists of access restrictions for every recipient becomes +tedious quickly. Postfix restriction classes allow you to give easy-to-remember +names to groups of UCE restrictions (such as "permissive", "restrictive", and +so on). + +The real reason for the existence of Postfix restriction classes is more +mundane: you can't specify a lookup table on the right-hand side of a Postfix +access table. This is because Postfix needs to open lookup tables ahead of +time, but the reader probably does not care about these low-level details. + +Example: + + /etc/postfix/main.cf: + smtpd_restriction_classes = restrictive, permissive + restrictive = reject_unknown_sender_domain reject_unknown_client ... + permissive = permit + + smtpd_recipient_restrictions = + permit_mynetworks + reject_unauth_destination + hash:/etc/postfix/recipient_access + + /etc/postfix/recipient_access: + joe@my.domain permissive + jane@my.domain restrictive + +With this in place, you can use "restrictive" or "permissive" on the right-hand +side of your per-client, helo, sender, or recipient SMTPD access tables. + +The remainder of this document gives examples of how Postfix access restriction +classes can be used to: + + * Shield an internal mailing list from outside posters, + * Prevent external access by internal senders. + +These questions come up frequently, and the examples hopefully make clear that +Postfix restriction classes aren't really the right solution. They should be +used for what they were designed to do, different junk mail restrictions for +different clients or users. + +PPrrootteeccttiinngg iinntteerrnnaall eemmaaiill ddiissttrriibbuuttiioonn lliissttss + + We want to implement an internal email distribution list. Something like + all@our.domain.com, which aliases to all employees. My first thought was to + use the aliases map, but that would lead to "all" being accessible from the + "outside", and this is not desired... :-) + +Postfix can implement per-address access controls. What follows is based on the +SMTP client IP address, and therefore is subject to IP spoofing. + + /etc/postfix/main.cf: + smtpd_recipient_restrictions = + hash:/etc/postfix/access + ...the usual stuff... + + /etc/postfix/access: + all permit_mynetworks,reject + +Specify ddbbmm instead of hhaasshh if your system uses ddbbmm files instead of ddbb files. +To find out what map types Postfix supports, use the command ppoossttccoonnff --mm. + +Now, that would be sufficient when your machine receives all Internet mail +directly from the Internet. That's unlikely if your network is a bit larger +than an office. For example, your backup MX hosts would "launder" the client IP +address of mail from the outside so it would appear to come from a trusted +machine. + +In the general case you need two lookup tables: one table that lists +destinations that need to be protected, and one table that lists domains that +are allowed to send to the protected destinations. + +What follows is based on the sender SMTP envelope address, and therefore is +subject to SMTP sender spoofing. + + /etc/postfix/main.cf: + smtpd_recipient_restrictions = + hash:/etc/postfix/protected_destinations + ...the usual stuff... + + smtpd_restriction_classes = insiders_only + insiders_only = check_sender_access hash:/etc/postfix/insiders, reject + + /etc/postfix/protected_destinations: + all@my.domain insiders_only + all@my.hostname insiders_only + + /etc/postfix/insiders: + my.domain OK matches my.domain and subdomains + another.domain OK matches another.domain and subdomains + +Getting past this scheme is relatively easy, because all one has to do is to +spoof the SMTP sender address. + +If the internal list is a low-volume one, perhaps it makes more sense to make +it moderated. + +RReessttrriiccttiinngg wwhhaatt uusseerrss ccaann sseenndd mmaaiill ttoo ooffff--ssiittee ddeessttiinnaattiioonnss + + How can I configure Postfix in a way that some users can send mail to the + internet and other users not. The users with no access should receive a + generic bounce message. Please don't discuss whether such access + restrictions are necessary, it was not my decision. + +Postfix has support for per-user restrictions. The restrictions are implemented +by the SMTP server. Thus, users that violate the policy have their mail +rejected by the SMTP server. Like this: + + 554 : Access denied + +The implementation uses two lookup tables. One table defines what users are +restricted in where they can send mail, and the other table defines what +destinations are local. It is left as an exercise for the reader to change this +into a scheme where only some users have permission to send mail to off-site +destinations, and where most users are restricted. + +The example assumes DB/DBM files, but this could also be done with LDAP or SQL. + + /etc/postfix/main.cf: + smtpd_recipient_restrictions = + check_sender_access hash:/etc/postfix/restricted_senders + ...other stuff... + + smtpd_restriction_classes = local_only + local_only = + check_recipient_access hash:/etc/postfix/local_domains, reject + + /etc/postfix/restricted_senders: + foo@domain local_only + bar@domain local_only + + /etc/postfix/local_domains: + this.domain OK matches this.domain and subdomains + that.domain OK matches that.domain and subdomains + +Specify ddbbmm instead of hhaasshh if your system uses ddbbmm files instead of ddbb files. +To find out what map types Postfix supports, use the command ppoossttccoonnff --mm. + +Note: this scheme does not authenticate the user, and therefore it can be +bypassed in several ways: + + * By sending mail via a less restrictive mail relay host. + + * By sending mail as someone else who does have permission to send mail to + off-site destinations. + diff --git a/postfix/README_FILES/SASL_README b/postfix/README_FILES/SASL_README index a31496690..fb9023799 100644 --- a/postfix/README_FILES/SASL_README +++ b/postfix/README_FILES/SASL_README @@ -1,279 +1,336 @@ -WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING -=============================================================== - -This code is not blessed by Wietse. - -People who go to the trouble of installing Postfix may have the -expectation that Postfix is more secure than some other mailers. - -With SASL authentication enabled in the Postfix SMTP client and -SMTP server, Postfix becomes no more secure than other mail systems -that use the Cyrus SASL library. - -The Cyrus SASL library has too little documentation about how the -software is supposed to work; and it is too much code to be used -in a security-sensitive program such as an SMTP client or server. - -However, you are pretty much required to build with SASL support -if you are going to use the LMTP interface of the Cyrus delivery -agent. This interface is much faster than forking a new process -for every message delivery. - -Postfix+SASL 1.5.5 appears to work on RedHat 6.1 (pwcheck_method -set to shadow or sasldb), Solaris 2.7 (pwcheck_method set to shadow -or sasldb), and FreeBSD 3.4 (pwcheck_method set to sasldb). On -RedHat 6.1, SASL 1.5.5 insisted on write access to /etc/sasldb. -Note that this seems to be related to the auto_transition switch in -SASL. Note also that the Cyrus SASL documentation says that it is -pointless to enable that if you use "sasldb" for "pwcheck_method". -Later versions of the SASL 1.5.x series should also work. - -Postfix+SASL 2.1.1 appears to work on Mandrake Linux 8.1 (pwcheck_method -set to saslauthd or auxprop). Note that the 'auxprop' pwcheck_method -replaces the 'sasldb' method from SASL 1.5.x. Postfix may need -write access to /etc/sasldb2 if you use the auto_transition feature, -or if you use an authentication mechanism such as OTP (one-time -passwords) that needs to update secrets in the database. - -Introduction -============ - -The Postfix SASL support (RFC 2554) was originally implemented by -Till Franke of SuSE Rhein/Main AG. The present code is a trimmed-down -version with only the bare necessities. Support for SASL version 2 -was contributed by Jason Hoos. - -When receiving mail, Postfix 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. - -SASL authentication information is not passed on via message headers -or via SMTP. It is no-one's business what username and authentication -method the poster was using in order to access the mail server. The -people who need to know can find the information in the maillog file. - -When sending mail, Postfix looks up the server hostname or destination -domain (the address remote part) in a table, and if a username/password -is found, it will use that username and password to authenticate -to the server. - -Building the SASL library -========================= - -Postfix appears to work with cyrus-sasl-1.5.5 or cyrus-sasl-2.1.1, -which are available from: - - ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/ - -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.5 or /usr/lib/sasl2 -> /usr/local/lib/sasl2 for -version 2.1.1. - -Reportedly, Microsoft Internet Explorer version 5 requires the -non-standard SASL LOGIN authentication method. To enable this -authentication method, specify ``./configure --enable-login''. - -Building Postfix with SASL authentication support -================================================= - -To build Postfix with SASL authentication support, 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. +PPoossttffiixx SSAASSLL HHoowwttoo + +------------------------------------------------------------------------------- + +WWAARRNNIINNGG WWAARRNNIINNGG WWAARRNNIINNGG + +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 SASL authentication enabled in the Postfix SMTP client and +SMTP server, Postfix becomes as secure as other mail systems that use the Cyrus +SASL library. + +HHooww PPoossttffiixx uusseess SSAASSLL aauutthheennttiiccaattiioonn iinnffoorrmmaattiioonn + +Postfix SASL support (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, Postfix 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. + +Postfix does not record the client's SASL authentication information in message +headers, and does not pass it on via SMTP commands when forwarding mail, +because it is no-one else's business to know the client username and +authentication method. People who need to know can find the information in the +local Postfix maillog file. Some day, Postfix message headers will be +configurable and then one can record the SASL username without having to edit C +code. + +This document covers the following topics: + + * What SASL versions are supported + * Building the SASL library + * Building Postfix with SASL authentication support + * Enabling SASL authentication in 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 + * Credits + +When sending mail, Postfix can look up the server hostname or destination +domain (the address right-hand part) in a table, and if a username/password is +found, it will use that username and password to authenticate to the server. + +WWhhaatt SSAASSLL vveerrssiioonnss aarree ssuuppppoorrtteedd + +Postfix+SASL 1.5.5 was seen working on RedHat 6.1 (pwcheck_method set to shadow +or sasldb), Solaris 2.7 (pwcheck_method set to shadow or sasldb), and FreeBSD +3.4 (pwcheck_method set to sasldb). On RedHat 6.1, SASL 1.5.5 insisted on write +access to /etc/sasldb. Note that this seems to be related to the +auto_transition switch in SASL. Note also that the Cyrus SASL documentation +says that it is pointless to enable that if you use "sasldb" for +"pwcheck_method". Later versions of the SASL 1.5.x series should also work. + +Postfix+SASL 2.1.1 appears to work on Mandrake Linux 8.1 (pwcheck_method set to +saslauthd or auxprop). Note that the 'auxprop' pwcheck_method replaces the +'sasldb' method from SASL 1.5.x. Postfix may need write access to /etc/sasldb2 +if you use the auto_transition feature, or if you use an authentication +mechanism such as OTP (one-time passwords) that needs to update secrets in the +database. + +BBuuiillddiinngg tthhee SSAASSLL lliibbrraarryy + +Postfix appears to work with cyrus-sasl-1.5.5 or cyrus-sasl-2.1.1, which are +available from: + + ftp://ftp.andrew.cmu.edu/pub/cyrus-mail/. + +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.5 or /usr/ +lib/sasl2 -> /usr/local/lib/sasl2 for version 2.1.1. + +Reportedly, Microsoft Internet Explorer version 5 requires the non-standard +SASL LOGIN authentication method. To enable this authentication method, specify +``./configure --enable-login''. + +BBuuiillddiinngg PPoossttffiixx wwiitthh SSAASSLL aauutthheennttiiccaattiioonn ssuuppppoorrtt + +To build Postfix with SASL authentication support, 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: (for SASL version 1.5.5): + % make tidy # if you have left-over files from a previous build % make makefiles CCARGS="-DUSE_SASL_AUTH -I/usr/local/include" \ - AUXLIBS="-L/usr/local/lib -lsasl" + AUXLIBS="-L/usr/local/lib -lsasl" (for SASL version 2.1.1): + % make tidy # if you have left-over files from a previous build % make makefiles CCARGS="-DUSE_SASL_AUTH -I/usr/local/include/sasl" \ - AUXLIBS="-L/usr/local/lib -lsasl2" + AUXLIBS="-L/usr/local/lib -lsasl2" -On Solaris 2.x you need to specify run-time link information, -otherwise ld.so will not find the SASL shared library: +On Solaris 2.x you need to specify run-time link information, otherwise ld.so +will not find the SASL shared library: (for SASL version 1.5.5): + % make tidy # if you have left-over files from a previous build % make makefiles CCARGS="-DUSE_SASL_AUTH -I/usr/local/include" \ - AUXLIBS="-L/usr/local/lib -R/usr/local/lib -lsasl" + AUXLIBS="-L/usr/local/lib -R/usr/local/lib -lsasl" (for SASL version 2.1.1): + % make tidy # if you have left-over files from a previous build % make makefiles CCARGS="-DUSE_SASL_AUTH -I/usr/local/include/sasl" \ - AUXLIBS="-L/usr/local/lib -R/usr/local/lib -lsasl2" + AUXLIBS="-L/usr/local/lib -R/usr/local/lib -lsasl2" -Enabling SASL authentication in the Postfix SMTP server -======================================================= - -See conf/sample-auth.cf for examples. +EEnnaabblliinngg SSAASSLL aauutthheennttiiccaattiioonn iinn tthhee PPoossttffiixx SSMMTTPP sseerrvveerr In order to enable SASL support in the SMTP server: /etc/postfix/main.cf: - smtpd_sasl_auth_enable = yes + smtpd_sasl_auth_enable = yes In order to allow mail relaying by authenticated clients: /etc/postfix/main.cf: - smtpd_recipient_restrictions = - permit_mynetworks permit_sasl_authenticated ... - -In /usr/local/lib/sasl/smtpd.conf (SASL version 1.5.5) or -/usr/local/lib/sasl2/smtpd.conf (SASL version 2.1.1) you need to -specify how the server should validate client passwords. + smtpd_recipient_restrictions = + permit_mynetworks permit_sasl_authenticated ... -IMPORTANT: If you configure SASL to use PAM (pluggable authentication -modules) authentication, the Postfix SMTP server will abort because -the SASL password file does not exist (default: /etc/sasldb in -version 1.5.5, or /etc/sasldb2 in version 2.1.1), To fix, disable -CRAM-MD5 authentication by deleting /usr/lib/sasl/libcrammd5.so or -/usr/lib/sasl2/libcrammd5.so depending on your SASL library version. +In /usr/local/lib/sasl/smtpd.conf (SASL version 1.5.5) or /usr/local/lib/sasl2/ +smtpd.conf (SASL version 2.1.1) you need to specify how the server should +validate client passwords. In order to authenticate against the UNIX password database, try: (SASL version 1.5.5) + /usr/local/lib/sasl/smtpd.conf: - pwcheck_method: pwcheck + pwcheck_method: pwcheck (SASL version 2.1.1) + /usr/local/lib/sasl2/smtpd.conf: - pwcheck_method: pwcheck + pwcheck_method: pwcheck + +The name of the file in /usr/local/lib/sasl (SASL version 1.5.5) or /usr/local/ +lib/sasl2 (SASL version 2.1.1) used by the SASL library for configuration can +be set with: + + /etc/postfix/main.cf: + smtpd_sasl_application_name = smtpd The pwcheck daemon is contained in the cyrus-sasl source tarball. -IMPORTANT: postfix processes need to have group read+execute -permission for the /var/pwcheck directory, otherwise authentication -attempts will fail. -Alternately, in SASL 1.5.5 and later (including 2.1.1), try: +IMPORTANT: postfix processes need to have group read+execute permission for the +/var/pwcheck directory, otherwise authentication attempts will fail. -(SASL version 1.5.5) - /usr/local/lib/sasl/smtpd.conf: - pwcheck_method: saslauthd +Alternately, in SASL 1.5.26 and later (including 2.1.1), try: + +(SASL version 1.5.26) + + /usr/local/lib/sasl/smtpd.conf: + pwcheck_method: saslauthd (SASL version 2.1.1) - /usr/local/lib/sasl2/smtpd.conf: - pwcheck_method: saslauthd -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". + /usr/local/lib/sasl2/smtpd.conf: + pwcheck_method: saslauthd + +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". In order to authenticate against SASL's own password database: (SASL version 1.5.5) + /usr/local/lib/sasl/smtpd.conf: - pwcheck_method: sasldb + pwcheck_method: sasldb (SASL version 2.1.1) + /usr/local/lib/sasl2/smtpd.conf: - pwcheck_method: auxprop + pwcheck_method: auxprop + +This will use the SASL password file (default: /etc/sasldb in version 1.5.5, or +/etc/sasldb2 in version 2.1.1), 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 SMTP server also needs write access to /etc/ +sasldb2 or /etc/sasldb (or the back end SQL database, if used). + +IMPORTANT: all users must be able to authenticate using ALL authentication +mechanisms advertised by Postfix, otherwise the negotiation might end up with +an unsupported mechanism, and authentication would fail. For example if you +configure SASL to use saslauthd for authentication against PAM (pluggable +authentication modules), only the PLAIN and LOGIN mechanisms are supported and +stand a chance to succeed, yet the SASL library would also advertise other +mechanisms, such as DIGEST-MD5. This happens because those mechanisms are made +available by other plugins, and the SASL library have no way to know that your +only valid authentication source is PAM. Thus you might need to limit the list +of mechanisms advertised by Postfix. This is only possible with SASL version +2.1.1 or later: -This will use the SASL password file (default: /etc/sasldb in -version 1.5.5, or /etc/sasldb2 in version 2.1.1), 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. On RedHat 6.1, -SASL 1.5.5 insists on write access to /etc/sasldb. + /usr/local/lib/sasl2/smtpd.conf: + mech_list: plain login + +For the same reasons you might want to limit the list of plugins used for +authentication. With SASL version 1.5.5 your only choice is to delete the +corresponding libraries from /usr/local/lib/sasl. With SASL version 2.1.1: + + /usr/local/lib/sasl2/smtpd.conf: + pwcheck_method: auxprop + auxprop_plugin: sql IMPORTANT: To get sasldb running, make sure that you set the SASL domain -(realm) to a fully qualified domain name. +(realm) to a fully qualified domain name. -EXAMPLE: saslpasswd -c -u `postconf -h myhostname` exampleuser +EXAMPLE: -To run software chrooted with SASL support is an interesting -exercise. It probably is not worth the trouble. +(SASL version 1.5.5) + + % saslpasswd -c -u `postconf -h myhostname` exampleuser + +(SASL version 2.1.1) + + % saslpasswd2 -c -u `postconf -h myhostname` exampleuser + +You can find out SASL's idea about the realms of the users in sasldb with +sasldblistusers (SASL version 1.5.5) or sasldblistusers2 (SASL version 2.1.1). + +On the Postfix side, you can have only one realm per smtpd 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: -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=stuff" instead of "250 AUTH -stuff". To accommodate such clients in addition to conformant -clients, set "broken_sasl_auth_clients = yes" in the main.cf file. + /etc/postfix/main.cf: + smtpd_sasl_local_domain = $myhostname + +To run software chrooted with SASL support is an interesting exercise. It +probably is not worth the trouble. -Testing SASL authentication in the Postfix SMTP server -====================================================== +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=stuff" instead of "250 AUTH stuff". To accommodate such clients in +addition to conformant clients, set "broken_sasl_auth_clients = yes" in the +main.cf file. -To test the whole mess, connect to the SMTP server, and you should -be able to have a conversation like this: +TTeessttiinngg SSAASSLL aauutthheennttiiccaattiioonn iinn tthhee PPoossttffiixx SSMMTTPP sseerrvveerr + +To test the server side, connect to the SMTP server, and you should be able to +have a conversation as shown below. Information sent by the client is shown in +bold font. 220 server.host.tld ESMTP Postfix - EHLO client.host.tld + EEHHLLOO cclliieenntt..hhoosstt..ttlldd 250-server.host.tld 250-PIPELINING 250-SIZE 10240000 250-ETRN 250-AUTH DIGEST-MD5 PLAIN CRAM-MD5 250 8BITMIME - AUTH PLAIN dGVzdAB0ZXN0AHRlc3RwYXNz + AAUUTTHH PPLLAAIINN ddGGVVzzddAABB00ZZXXNN00AAHHRRllcc33RRwwYYXXNNzz 235 Authentication successful -Instead of dGVzdAB0ZXN0AHRlc3RwYXNz, specify the base64 encoded -form of username\0username\0password (the \0 is a null byte). The -example above is for a user named `test' with password `testpass'. +Instead of dGVzdAB0ZXN0AHRlc3RwYXNz, specify the base64 encoded form of +username\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: +In order to generate base64 encoded authentication information you can use one +of the following commands: - % printf 'username\0username\0password' | mmencode + % printf 'username\0username\0password' | mmencode % perl -MMIME::Base64 -e \ - 'print encode_base64("username\0username\0password");' + 'print encode_base64("username\0username\0password");' + +The mmencode command is part of the metamail software. MIME::Base64 is +available from http://www.cpan.org/. -mmencode is part of the metamail software. -MIME::Base64 is available from www.cpan.org. +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. -Trouble shooting the SASL internals -=================================== +TTrroouubbllee sshhoooottiinngg tthhee SSAASSLL iinntteerrnnaallss -[based on text by Liviu Daia] +In the Cyrus SASL sources you'll find a subdirectory named "sample". Run make +there, "su" to the user postfix (or whatever your mail_owner directive is set +to): -In the Cyrus SASL sources you'll find a subdirectory named "sample". -Run make there, then run the resulting sample server and client in -separate terminals. Strace / ktrace / truss the server to see what -makes it unhappy, fix the problem, then write the authors thanking -them for providing such useful logging. Repeat the previous step -until you can successfully authenticate with the sample client. -Only then get back to Postfix. + % su postfix -Enabling SASL authentication in the Postfix SMTP client -======================================================= +then run the resulting sample server and client in separate terminals. Strace / +ktrace / truss the server to see what makes it unhappy, and fix the problem. +Repeat the previous step until you can successfully authenticate with the +sample client. Only then get back to Postfix. -Turn on client-side SASL authentication, and specify a table with -per-host or per-destination username and password information. -Postfix first looks up the server hostname; if no entry is found, -then Postfix looks up the destination domain name (usually, the -remote part of an email address). +EEnnaabblliinngg SSAASSLL aauutthheennttiiccaattiioonn iinn tthhee PPoossttffiixx SSMMTTPP cclliieenntt + +Turn on client-side SASL authentication, and specify a table with per-host or +per-destination username and password information. Postfix first looks up the +server hostname; if no entry is found, then Postfix looks up the destination +domain name (usually, the right-hand part of an email address). /etc/postfix/main.cf: - smtp_sasl_auth_enable = yes - smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd + smtp_sasl_auth_enable = yes + smtp_sasl_password_maps = hash:/etc/postfix/sasl_passwd /etc/postfix/sasl_passwd: - foo.com username:password - bar.com username + foo.com username:password + bar.com username -Note: some 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: +Note: some 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: /etc/postfix/main.cf: - smtp_sasl_security_options = + smtp_sasl_security_options = + +The SASL client password file is opened before the SMTP server enters the +optional chroot jail, so you can keep the file in /etc/postfix. + +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. -The SASL client password file is opened before the SMTP server -enters the optional chroot jail, so you can keep the file in -/etc/postfix. +CCrreeddiittss -The Postfix SMTP client is backwards compatible with SMTP servers -that use the non-standard AUTH=stuff... syntax in response to the -EHLO command. + * 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 SASL version 2 was contributed by Jason Hoos. + * 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. diff --git a/postfix/README_FILES/SCHEDULER_README b/postfix/README_FILES/SCHEDULER_README index 2d7fa28bd..ec924e906 100644 --- a/postfix/README_FILES/SCHEDULER_README +++ b/postfix/README_FILES/SCHEDULER_README @@ -1,99 +1,94 @@ -What this file is about -======================= - -This is the beginning of documentation for the clever queue manager -scheduling algorithm by Patrik Rak. For a long time, this code was -made available under the name "nqmgr" (new queue manager), as an -optional module. It now become the default queue manager, which is -always called "qmgr". The old queue manager will for some time will -be available under the name of "oqmgr". - -Why the old Postfix queue manager was replaced -============================================== - -The old Postfix scheduler had several limitations due to unfortunate -choices in its design. - -1 - Round-robin selection by destination for mail that is delivered - via the same message delivery transport. The round-robin strategy - was chosen with the intention to prevent a single (destination) - site from using up too many mail delivery resources. However, - that strategy penalized inbound mail on bi-directional gateways. - The poor suffering inbound destination would be selected only - 1/number-of-destinations of the time, even when it had more +PPoossttffiixx QQuueeuuee SScchheedduulleerr + +------------------------------------------------------------------------------- + +WWhhaatt tthhiiss ffiillee iiss aabboouutt + +This is the beginning of documentation for the clever queue manager scheduling +algorithm by Patrik Rak. For a long time, this code was made available under +the name "nqmgr(8)" (new queue manager), as an optional module. As of Postfix +2.1 this is the default queue manager, which is always called "qmgr(8)". The +old queue manager will for some time will be available under the name of "oqmgr +(8)". + +WWhhyy tthhee oolldd PPoossttffiixx qquueeuuee mmaannaaggeerr wwaass rreeppllaacceedd + +The old Postfix scheduler had several limitations due to unfortunate choices in +its design. + + 1. Round-robin selection by destination for mail that is delivered via the + same message delivery transport. The round-robin strategy was chosen with + the intention to prevent a single (destination) site from using up too many + mail delivery resources. However, that strategy penalized inbound mail on + bi-directional gateways. The poor suffering inbound destination would be + selected only 1/number-of-destinations of the time, even when it had more mail than other destinations, and thus mail could be delayed. - Victor Duchovni found a workaround: use different message - delivery transports, and thus avoid the starvation problem. - The Patrik Rak scheduler solves this problem by using FIFO - selection. - -2 - A second limitation of the old Postfix scheduler was that - delivery of bulk mail would block all other deliveries, causing - large delays. Patrik Rak's scheduler allows mail with fewer - recipients to slip past bulk mail in an elegant manner. - -How the queue manager scheduler works -===================================== - -[The following text is from Patrik Rak and should be read together -with the sample-scheduler.cf file] - -From user's point of view, qmgr and nqmgr are both the same, except -for how next message is chosen when delivery agent becomes available. -You already know that qmgr uses round-robin by destination while -nqmgr uses simple FIFO, except for some preemptive magic. The -[sample-scheduler.cf file] documents all the knobs the user can -use to control this preemptive magic - there is nothing else to -the preemption than the quite simple conditions described below. - -As for programmer-level documentation, this will have to be extracted -from all those emails we have exchanged with Wietse [rats! I hoped -that Patrik would do the work for me -- Wietse] But I think there -are no missing bits which we have not mentioned in our conversations. - -However, even from programmer's point of view, there is nothing -more to add to the message scheduling idea itself. There are few -things which make it look more complicated than it is, but the -algorithm is the same as the user percieves it. The summary of the -differences of the programmer's view from the user's view are: - -1) Simplification of terms for users: The user knows about messages -and recipients. The program itself works with jobs (one message is -split among several jobs, one per each transport needed to deliver -the message) and queue entries (each entry may group several -recipients for same destination). Then there is the peer structure -introduced by nqmgr which is simply per-job analog of the queue -structure. - -2) Dealing with concurrency limits: The actual implementation is -complicated by the fact that the messages (resp. jobs) may not be -delivered in the exactly scheduled order because of the concurrency -limits. It is necessary to skip some "blocker" jobs when the -concurrency limit is reached and get back to them again when the -limit permits. - -3) Dealing with resource limits: The actual implementation is -complicated by the fact that not all recipients may be read in-core. -Therefore each message has some recipients in-core and some may -remain on-file. This means that a) the preemptive algorithm needs -to work with recipient count estimates instead of exact counts, b) -there is extra code which needs to manipulate the per-transport -pool of recipients which may be read in-core at the same time, and -c) there is extra code which needs to be able to read recipients -into core in batches and which is triggered at appropriate moments. - -4) Doing things efficiently: All important things I am aware of -are done in the minimum time possible (either directly or at least -when amortized complexity is used), but to choose which job is -the best candidate for preempting the current job requires linear -search of up to all transport jobs (the worst theoretical case - -the reality is much better). As this is done every time the next -queue entry to be delivered is about to be chosen, it seemed -reasonable to add cache which minimizes the overhead. Maintenance -of this candidate cache slightly obfuscates things. - -The points 2 and 3 are those which made the implementation (look) -complicated and were the real coding work, but I believe that to -understand the scheduling algorithm itself (which was the real -thinking work) is fairly easy. + Victor Duchovni found a workaround: use different message delivery + transports, and thus avoid the starvation problem. The Patrik Rak scheduler + solves this problem by using FIFO selection. + + 2. A second limitation of the old Postfix scheduler was that delivery of bulk + mail would block all other deliveries, causing large delays. Patrik Rak's + scheduler allows mail with fewer recipients to slip past bulk mail in an + elegant manner. + +HHooww tthhee qquueeuuee mmaannaaggeerr sscchheedduulleerr wwoorrkkss + +The following text is from Patrik Rak and should be read together with the +postconf(5) manual that describes each configuration parameter in detail. + +From user's point of view, oqmgr(8) and qmgr(8) are both the same, except for +how next message is chosen when delivery agent becomes available. You already +know that oqmgr(8) uses round-robin by destination while qmgr(8) uses simple +FIFO, except for some preemptive magic. The postconf(5) manual documents all +the knobs the user can use to control this preemptive magic - there is nothing +else to the preemption than the quite simple conditions described below. + +As for programmer-level documentation, this will have to be extracted from all +those emails we have exchanged with Wietse [rats! I hoped that Patrik would do +the work for me -- Wietse] But I think there are no missing bits which we have +not mentioned in our conversations. + +However, even from programmer's point of view, there is nothing more to add to +the message scheduling idea itself. There are few things which make it look +more complicated than it is, but the algorithm is the same as the user +perceives it. The summary of the differences of the programmer's view from the +user's view are: + + 1. Simplification of terms for users: The user knows about messages and + recipients. The program itself works with jobs (one message is split among + several jobs, one per each transport needed to deliver the message) and + queue entries (each entry may group several recipients for same + destination). Then there is the peer structure introduced by qmgr(8) which + is simply per-job analog of the queue structure. + + 2. Dealing with concurrency limits: The actual implementation is complicated + by the fact that the messages (resp. jobs) may not be delivered in the + exactly scheduled order because of the concurrency limits. It is necessary + to skip some "blocker" jobs when the concurrency limit is reached and get + back to them again when the limit permits. + + 3. Dealing with resource limits: The actual implementation is complicated by + the fact that not all recipients may be read in-core. Therefore each + message has some recipients in-core and some may remain on-file. This means + that a) the preemptive algorithm needs to work with recipient count + estimates instead of exact counts, b) there is extra code which needs to + manipulate the per-transport pool of recipients which may be read in-core + at the same time, and c) there is extra code which needs to be able to read + recipients into core in batches and which is triggered at appropriate + moments. + + 4. Doing things efficiently: All important things I am aware of are done in + the minimum time possible (either directly or at least when amortized + complexity is used), but to choose which job is the best candidate for + preempting the current job requires linear search of up to all transport + jobs (the worst theoretical case - the reality is much better). As this is + done every time the next queue entry to be delivered is about to be chosen, + it seemed reasonable to add cache which minimizes the overhead. Maintenance + of this candidate cache slightly obfuscates things. + +The points 2 and 3 are those which made the implementation (look) complicated +and were the real coding work, but I believe that to understand the scheduling +algorithm itself (which was the real thinking work) is fairly easy. + diff --git a/postfix/README_FILES/SMTPD_ACCESS_README b/postfix/README_FILES/SMTPD_ACCESS_README new file mode 100644 index 000000000..26fcbe611 --- /dev/null +++ b/postfix/README_FILES/SMTPD_ACCESS_README @@ -0,0 +1,259 @@ +PPoossttffiixx SSMMTTPP rreellaayy aanndd aacccceessss ccoonnttrrooll + +------------------------------------------------------------------------------- + +IInnttrroodduuccttiioonn + +The Postfix SMTP server receives mail from the network and is exposed to the +big bad world of junk email and viruses. This document introduces the built-in +and external methods that control what SMTP mail Postfix will accept, what +mistakes to avoid, and how to test your configuration. + +Topics covered in this document: + + * Relay control, junk mail control, and per-user policies + * Restrictions that apply to all SMTP mail + * Getting selective with SMTP access restriction lists + * Delayed evaluation of SMTP access restriction lists + * Dangerous use of smtpd_recipient_restrictions + * SMTP access rule testing + +RReellaayy ccoonnttrrooll,, jjuunnkk mmaaiill ccoonnttrrooll,, aanndd ppeerr--uusseerr ppoolliicciieess + +In a distant past, the Internet was a friendly environment. Mail servers +happily forwarded mail on behalf of anyone towards any destination. On today's +Internet, spammers abuse servers that forward mail from arbitrary systems, and +abused systems end up on anti-spammer blacklists. See, for example, the +information on http://www.mail-abuse.org/ and other websites. + +By default, Postfix has a moderately restrictive approach to mail relaying. +Postfix forwards mail only from clients in trusted networks, or to domains that +are configured as authorized relay destinations. For a description of the +default policy, see the smtpd_recipient_restrictions parameter in the postconf +(5) manual page, and the information that is referenced from there. + +Most of the Postfix SMTP server access controls are targeted at stopping junk +email. + + * Protocol oriented: some SMTP server access controls block mail by being + very strict with respect to the SMTP protocol; these catch poorly + implemented and/or poorly configured junk email software, as well as email + worms that come with their own non-standard SMTP client implementations. + Protocol-oriented access controls become less useful over time as spammers + and worm writers learn to read RFC documents. + + * Blacklist oriented: some SMTP server access controls query blacklists with + known to be bad sites such as open mail relays, open web proxies, and home + computers that have been compromised and that are under remote control by + criminals. The effectiveness of these blacklists depends on how complete + and how up to date they are. + + * Threshold oriented: some SMTP server access controls attempt to raise the + bar by either making the client do more work (greylisting) or by asking for + a second opinion (SPF and sender/recipient address verification). The + greylisting and SPF policies are implemented externally, and are the + subject of the SMTPD_POLICY_README document. Sender/recipient address + verification is the subject of the ADDRESS_VERIFICATION_README document. + +Unfortunately, all junk mail controls have the possibility of falsely rejecting +legitimate mail. This can be a problem for sites with many different types of +users. For some users it is unacceptable when any junk email slips through, +while for other users the world comes to an end when a single legitimate email +message is blocked. Because there is no single policy that is "right" for all +users, Postfix supports different SMTP access restrictions for different users. +This is described in the RESTRICTION_CLASS_README document. + +RReessttrriiccttiioonnss tthhaatt aappppllyy ttoo aallll SSMMTTPP mmaaiill + +Besides the restrictions that can be made configurable per client or per user +as described in the next section, Postfix implements a few restrictions that +apply to all SMTP mail. + + * The built-in header_checks and body_checks content restrictions, as + described in the BUILTIN_FILTER_README document. This happens while Postfix + receives mail, before it is stored in the incoming queue. + + * The external before-queue content restrictions, as described in the + SMTPD_PROXY_README document. This happens while Postfix receives mail, + before it is stored in the incoming queue. + + * Require that the client sends the HELO or EHLO command before sending the + MAIL FROM or ETRN command. This may cause problems with home-grown + applications that send mail. For this reason, the requirement is disabled + by default ("smtpd_helo_required = no"). + + * Disallow illegal syntax in MAIL FROM or RCPT TO commands. This may cause + problems with home-grown applications that send mail, and with ancient PC + mail clients. For this reason, the requirement is disabled by default + ("strict_rfc821_envelopes = no"). + + o Disallow RFC 822 address syntax (example: "MAIL FROM: the dude + "). + + o Disallow addresses that are not enclosed with <> (example: "MAIL FROM: + dude@example.com"). + + * Reject mail from a non-existent sender address. This form of egress + filtering helps to slow down worms and other malware, but may cause + problems with home-grown software that sends out mail software with an + unreplyable address. For this reason the requirement is disabled by default + ("smtpd_reject_unlisted_sender = no"). + + * Reject mail for a non-existent recipient address. This form of ingress + filtering helps to keep the mail queue free of undeliverable MAILER-DAEMON + messages. This requirement is enabled by default + ("smtpd_reject_unlisted_recipient = yes"). + +GGeettttiinngg sseelleeccttiivvee wwiitthh SSMMTTPP aacccceessss rreessttrriiccttiioonn lliissttss + +Postfix allows you to specify lists of access restrictions for each stage of +the SMTP conversation. Individual restrictions are described in the postconf(5) +manual page. + +Examples of simple restriction lists are: + +/etc/postfix/main.cf: + # Allow connections from trusted networks only. + smtpd_client_restrictions = permit_mynetworks, reject + + # Don't talk to mail systems that don't know their own hostname. + smtpd_helo_restrictions = reject_unknown_hostname + + # Don't accept mail from domains that don't exist. + smtpd_sender_restrictions = reject_unknown_sender_domain + + # Whitelisting: local clients may specify any destination. Others may not. + smtpd_recipient_restrictions = permit_mynetworks, reject_unauth_destination + +Each restriction list is evaluated from left to right until some restriction +produces a result of PERMIT, REJECT or DEFER (try again later). The end of the +list is equivalent to a PERMIT result. By placing a PERMIT restriction before a +REJECT restriction you can make exceptions for specific clients or users. This +is called whitelisting; the last example above allows mail from local networks +but otherwise rejects mail to arbitrary destinations. + +The table below summarizes the purpose of each SMTP access restriction list. +All lists use the exact same syntax; they differ only in the time of evaluation +and in the effect of a REJECT or DEFER result. + + _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ + |RReessttrriiccttiioonn lliisstt nnaammee |SSttaattuuss |EEffffeecctt ooff RREEJJEECCTT oorr DDEEFFEERR rreessuulltt| + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |smtpd_client_restrictions |Optional|Reject all client commands | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |smtpd_helo_restrictions |Optional|Reject HELO/EHLO information | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |smtpd_sender_restrictions |Optional|Reject MAIL FROM information | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |smtpd_recipient_restrictions|Required|Reject RCPT TO information | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |smtpd_data_restrictions |Optional|Reject DATA command | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |smtpd_etrn_restrictions |Optional|Reject ETRN command | + |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + +DDeellaayyeedd eevvaalluuaattiioonn ooff SSMMTTPP aacccceessss rreessttrriiccttiioonn lliissttss + +Early Postfix versions evaluated SMTP access restrictions lists as early as +possible. The client restriction list was evaluated before Postfix sent the +"220 $myhostname..." greeting banner to the SMTP client, the helo restriction +list was evaluated before Postfix replied to the HELO (EHLO) command, the +sender restriction list was evaluated before Postfix replied to the MAIL FROM +command, and so on. This approach turned out to be difficult to use. + +Current Postfix versions postpone the evaluation of client, helo and sender +restriction lists until the RCPT TO or ETRN command. This behavior is +controlled by the smtpd_delay_reject parameter. Restriction lists are still +evaluated in the proper order of (client, helo, etrn) or (client, helo, sender, +recipient, data) restrictions. When a restriction list (example: client) +evaluates to REJECT or DEFER the other restriction lists (example: helo, +sender, etc.) are skipped. + +Around the time that smtpd_delay_reject was introduced, Postfix was also +changed to support mixed restriction lists that combine information about the +client, helo, sender and recipient or etrn command. + +Benefits of delayed restriction evaluation, and of restriction mixing: + + * Some SMTP clients do not expect a negative reply early in the SMTP session. + When the bad news is postponed until the RCPT TO reply, the client goes + away as it is supposed to, instead of hanging around until a timeout + happens, or worse, going into an endless connect-reject-connect loop. + + * Postfix can log more useful information. For example, when Postfix rejects + a client name or address and delays the action until the RCPT TO command, + it can log the sender and the recipient address. This is more useful than + logging only the client hostname and IP address and not knowing whose mail + was being blocked. + + * Mixing is needed for complex whitelisting policies. For example, in order + to reject local sender addresses in mail from non-local clients, you need + to be able to mix restrictions on client information with restrictions on + sender information in the same restriction list. Without this ability, many + per-user access restrictions would be impossible to express. + +DDaannggeerroouuss uussee ooff ssmmttppdd__rreecciippiieenntt__rreessttrriiccttiioonnss + +By now the reader may wonder why we need smtpd client, helo or sender +restrictions, when their evaluation is postponed until the RCPT TO or ETRN +command. Some people recommend placing ALL the access restrictions in the +smtpd_recipient_restrictions list. Unfortunately, this can result in too +permissive access. How is this possible? + +The purpose of the smtpd_recipient_restrictions feature is to control how +Postfix replies to the RCPT TO command. If the restriction list evaluates to +REJECT or DEFER, the recipient address is rejected; no surprises here. If the +result is PERMIT, then the recipient address is accepted. And this is where +surprises can happen. + +Here is an example that shows when a PERMIT result can result in too much +access permission: + +1 /etc/postfix/main.cf: +2 smtpd_recipient_restrictions = +3 permit_mynetworks +4 check_helo_access hash:/etc/postfix/helo_access +5 reject_unknown_hostname +6 reject_unauth_destination +7 +8 /etc/postfix/helo_access: +9 localhost.localdomain PERMIT + +Line 5 rejects mail from hosts that don't specify a proper hostname in the HELO +command. Lines 4 and 9 make an exception to allow mail from some machine that +announces itself with "HELO localhost.localdomain". + +The problem with this configuration is that smtpd_recipient_restrictions +evaluates to PERMIT for EVERY host that announces itself as +"localhost.localdomain", making Postfix an open relay for all such hosts. + +In order to avoid surprises like these with smtpd_recipient_restrictions, you +should place non-recipient restrictions AFTER the reject_unauth_destination +restriction, not before. In the above example, the HELO based restrictions +should be placed AFTER reject_unauth_destination, or better, the HELO based +restrictions should be placed under smtpd_helo_restrictions where they can do +no harm. + +SSMMTTPP aacccceessss rruullee tteessttiinngg + +Postfix has several features that aid in SMTP access rule testing: + +soft_bounce + This is a safety net that changes SMTP server REJECT actions into DEFER + (try again later) actions. This keeps mail queued that would otherwise be + returned to the sender. Specify "soft_bounce = yes" in the main.cf file to + prevent the Postfix SMTP server from rejecting mail permanently, by + changing all 5xx SMTP reply codes into 4xx. + +warn_if_reject + This is a different safety net that changes SMTP server REJECT actions into + warnings. Instead of rejecting a command, Postfix logs what it would + reject. Specify "warn_if_reject" in an SMTP access restriction list, before + the restriction that you want to test without actually rejecting mail. + +XCLIENT + With this Postfix 2.1 feature, authorized SMTP clients can impersonate + other systems, so that you can do realistic SMTP access rule tests. + Examples of how to impersonate other systems for access rule testing are + given at the end of the XCLIENT_README document. + diff --git a/postfix/README_FILES/SMTPD_POLICY_README b/postfix/README_FILES/SMTPD_POLICY_README index b22693dbc..d962d8c87 100644 --- a/postfix/README_FILES/SMTPD_POLICY_README +++ b/postfix/README_FILES/SMTPD_POLICY_README @@ -1,28 +1,43 @@ -POLICY DELEGATION PROTOCOL -========================== +PPoossttffiixx SSMMTTPP AAcccceessss PPoolliiccyy DDeelleeggaattiioonn -The Postfix SMTP server has a number of built-in mechanisms to -block or accept mail at specific SMTP protocol stages. Optionally, -it can be configured to delegate policy decisions to an external -server that runs outside Postfix. A simple greylist policy can be -implemented with only a dozen lines of PERL. +------------------------------------------------------------------------------- -This document describes the following: +PPuurrppoossee ooff PPoossttffiixx SSMMTTPP aacccceessss ppoolliiccyy ddeelleeggaattiioonn -- The Postfix policy delegation protocol. +The Postfix SMTP server has a number of built-in mechanisms to block or accept +mail at specific SMTP protocol stages. As of version 2.1, Postfix can delegate +policy decisions to an external server that runs outside Postfix. -- Using the example greylist policy server. +With this policy delegation mechanism, a simple greylist policy can be +implemented with only a dozen lines of Perl, as is shown at the end of this +document. Another example of policy delegation is the SPF policy server by Meng +Wong at http://spf.pobox.com/. Examples of both policies can be found in the +Postfix source code, in the directory examples/smtpd-policy. -PROTOCOL DESCRIPTION -==================== +Policy delegation is now the preferred method for adding policies to Postfix. +It's much easier to develop a new feature in few lines of Perl, than trying to +do the same in C code. The difference in performance will be unnoticeable +except in the most demanding environments. -The Postfix policy delegation protocol is really simple. The client -request is a sequence of name=value attributes separated by newline, -and is terminated by an empty line. The server reply is one name=value -attribute and it, too, is terminated by an empty line. +This document covers the following topics: -Here is an example of all the attributes that the Postfix SMTP -server sends in a delegated SMTPD access policy request: + * Policy protocol description + * Policy client/server configuration + * Example: greylist policy server + * Greylisting mail from frequently forged domains + * Greylisting all your mail + * Routine greylist maintenance + * Example Perl greylist server + +PPrroottooccooll ddeessccrriippttiioonn + +The Postfix policy delegation protocol is really simple. The client request is +a sequence of name=value attributes separated by newline, and is terminated by +an empty line. The server reply is one name=value attribute and it, too, is +terminated by an empty line. + +Here is an example of all the attributes that the Postfix SMTP server sends in +a delegated SMTPD access policy request: request=smtpd_access_policy protocol_state=RCPT @@ -33,227 +48,289 @@ server sends in a delegated SMTPD access policy request: recipient=bar@foo.tld client_address=1.2.3.4 client_name=another.domain.tld + instance=123.456.7 + sasl_method=plain + sasl_username=you + sasl_sender= + size=12345 [empty line] -- The "request" attribute is required. In this example the request - type is "smtpd_access_policy". -- The order of the attributes does not matter. The policy server - should ignore any attributes that it does not care about. -- When the same attribute name is sent more than once, the server - may keep the first value or the last attribute value. -- An attribute name must not contain "=", null or newline, and an - attribute value must not contain null or newline. +Notes: + + * The "request" attribute is required. In this example the request type is + "smtpd_access_policy". + + * The order of the attributes does not matter. The policy server should + ignore any attributes that it does not care about. + + * When the same attribute name is sent more than once, the server may keep + the first value or the last attribute value. + + * When an attribute value is unavailable, the client either does not send the + attribute, or sends the attribute with an empty value ("name="). + + * An attribute name must not contain "=", null or newline, and an attribute + value must not contain null or newline. + + * The "instance" attribute value can be used to correlate different requests + regarding the same message delivery. The following is specific to SMTPD delegated policy requests: -- Protocol names are ESMTP or SMTP. -- Protocol states are CONNECT, EHLO, HELO, MAIL, RCPT, DATA, VRFY - or ETRN; these are the SMTP protocol states where the Postfix - SMTP server makes an OK/REJECT/HOLD/etc. decision. + * Protocol names are ESMTP or SMTP. -The policy server replies with any action that is allowed in a -Postfix SMTPD access table. Example: + * Protocol states are CONNECT, EHLO, HELO, MAIL, RCPT, DATA, VRFY or ETRN; + these are the SMTP protocol states where the Postfix SMTP server makes an + OK/REJECT/HOLD/etc. decision. - action=450 Service temporarily unavailable + * The SASL attributes are sent only when SASL support is built into Postfix. + +The policy server replies with any action that is allowed in a Postfix SMTPD +access(5) table. Example: + + action=defer_if_permit Service temporarily unavailable [empty line] -This causes Postfix to reject the request with a 450 temporary -error code and with text "Service temporarily unavailable". +This causes the Postfix SMTP server to reject the request with a 450 temporary +error code and with text "Service temporarily unavailable", if the Postfix SMTP +server finds no reason to reject the request permanently. -In case of trouble the policy server must log a warning and -disconnect. Postfix will retry the request at some later time. +In case of trouble the policy server must not send a reply. Instead the server +must log a warning and disconnect. Postfix will retry the request at some later +time. -CLIENT SIDE CONFIGURATION -========================= +PPoolliiccyy cclliieenntt//sseerrvveerr ccoonnffiigguurraattiioonn -The delegated policy client can connect to a TCP socket or to a -UNIX-domain socket. Examples: +The Postfix delegated policy client can connect to a TCP socket or to a UNIX- +domain socket. Examples: - inet:localhost:9998 + inet:127.0.0.1:9998 unix:/some/where/policy unix:private/policy -The first example specifies that the policy server listens on -localhost port 9998. The second example specifies an absolute -pathname of a UNIX-domain socket. The third example specifies a -pathname relative to the Postfix queue directory; use this for -policy servers that are spawned by the Postfix master daemon. - -To use the delegated policy service for SMTPD access control, -specify "check_policy_service" anywhere in the list of -smtpd_recipient_restrictions: - -/etc/postfix/main.cf: - smtpd_recipient_restrictions = - ... - reject_unauth_destination - check_policy_service unix:private/policy - ... - policy_time_limit = 3600 - -NOTE: specify "check_policy_service" AFTER "reject_unauth_destination" -or else your system could become an open relay. - -NOTE: Postfix by default kills a command after 1000 seconds. This -is too short for a policy daemon that may run for as long as an -SMTP client is connected to an SMTP server process. The default -time limit is overruled with an explicit policy_time_limit setting. - -NOTE: Solaris UNIX-domain sockets do not work reliably. Use TCP -sockets instead: - -/etc/postfix/main.cf: - smtpd_recipient_restrictions = - ... - reject_unauth_destination - check_policy_service inet:localhost:9998 - ... - localhost:9998_time_limit = 3600 - -Other client-side configuration parmeters: - -- smtpd_policy_service_max_idle (default: 300s): the amount of time - before the Postfix SMTP server closes an unused policy client - connection. The socket is closed while the SMTP server waits - for new a SMTP client. - -- smtpd_policy_service_max_ttl (default: 1000s): the amount of time - before the Postfix SMTP server closes an active policy client - connection. The socket is closed while the SMTP server waits for - new a SMTP client. - -- smtpd_policy_service_timeout (default: 100s): the time limit to - connect to, send to or receive from a policy server. - -EXAMPLE: GREYLIST POLICY SERVER -=============================== - -The file examples/smtpd-policy/smtpd-policy.pl in the Postfix source -tree implements an example greylist policy server. This server -stores a time stamp for every (client, sender, recipient) triple. -By default, mail is not accepted until a time stamp is more than -60 seconds old. This stops junk mail with randomly selected sender -addresses, and mail that is sent through randomly selected open -proxies. It also stops junk mail from spammers that change their +The first example specifies that the policy server listens on a TCP socket at +127.0.0.1 port 9998. The second example specifies an absolute pathname of a +UNIX-domain socket. The third example specifies a pathname relative to the +Postfix queue directory; use this for policy servers that are spawned by the +Postfix master daemon. + +To create a policy service that listens on a UNIX-domain socket called +"policy", and that runs under control of the Postfix spawn(8) daemon, you would +use something like this: + + 1 /etc/postfix/master.cf: + 2 policy unix - n n - - spawn + 3 user=nobody argv=/some/where/policy-server + 4 + 5 /etc/postfix/main.cf: + 6 smtpd_recipient_restrictions = + 7 ... + 8 reject_unauth_destination + 9 check_policy_service unix:private/policy + 10 ... + 11 policy_time_limit = 3600 + +NOTES: + + * Lines 2, 11: the Postfix spawn(8) daemon by default kills its child process + after 1000 seconds. This is too short for a policy daemon that may run for + as long as an SMTP client is connected to an SMTP server process. The + default time limit is overruled in main.cf with an explicit + "policy_time_limit" setting. The name of the parameter is the name of the + master.cf entry ("policy") concatenated with the "_time_limit" suffix. + + * Lines 8, 9: always specify "check_policy_service" AFTER + "reject_unauth_destination" or else your system could become an open relay. + + * Solaris UNIX-domain sockets do not work reliably. Use TCP sockets instead: + + 1 /etc/postfix/master.cf: + 2 127.0.0.1:9998 unix - n n - - spawn + 3 user=nobody argv=/some/where/policy-server + 4 + 5 /etc/postfix/main.cf: + 6 smtpd_recipient_restrictions = + 7 ... + 8 reject_unauth_destination + 9 check_policy_service inet:127.0.0.1:9998 + 10 ... + 11 127.0.0.1:9998_time_limit = 3600 + +Other configuration parameters that control the client side of the policy +delegation protocol: + + * smtpd_policy_service_max_idle (default: 300s): The amount of time before + the Postfix SMTP server closes an unused policy client connection. + + * smtpd_policy_service_max_ttl (default: 1000s): The amount of time before + the Postfix SMTP server closes an active policy client connection. + + * smtpd_policy_service_timeout (default: 100s): The time limit to connect to, + send to or receive from a policy server. + +EExxaammppllee:: ggrreeyylliisstt ppoolliiccyy sseerrvveerr + +Greylisting is a defense against junk email that is described at http:// +www.greylisting.org/. The idea was discussed on the postfix-users mailing list +one year before it was popularized. + +The file examples/smtpd-policy/greylist.pl in the Postfix source tree +implements a simplified greylist policy server. This server stores a time stamp +for every (client, sender, recipient) triple. By default, mail is not accepted +until a time stamp is more than 60 seconds old. This stops junk mail with +randomly selected sender addresses, and mail that is sent through randomly +selected open proxies. It also stops junk mail from spammers that change their IP address frequently. -Copy examples/smtpd-policy/smtpd-policy.pl to /usr/libexec/postfix -or whatever location is appropriate for your system. +Copy examples/smtpd-policy/greylist.pl to /usr/libexec/postfix or whatever +location is appropriate for your system. -In the smtpd-policy.pl PERL script you need to specify the location -of the greylist database file. The default location is: +In the greylist.pl Perl script you need to specify the location of the greylist +database file, and how long mail will be delayed before it is accepted. The +default settings are: - $database_name="/var/mta/smtpd-policy.db"; + $database_name="/var/mta/greylist.db"; + $greylist_delay=60; -The /var/mta directory (or whatever you choose) should be writable -by "nobody", or by whatever username you configure below in master.cf -for the policy service. +The /var/mta directory (or whatever you choose) should be writable by "nobody", +or by whatever username you configure below in master.cf for the policy +service. Example: # mkdir /var/mta # chown nobody /var/mta -Note: DO NOT create the greylist database in a world-writable -directory such as /tmp or /var/tmp, and DO NOT create the greylist -database in a file system that can run out of space easily. If the -file becomes corrupted you will not be able to receive mail until -you delete the file by hand. - -The smtpd-policy.pl PERL script can be run under control by the -Postfix master daemon. For example, to run the script as user -"nobody", using a UNIX-domain socket that is accessible by Postfix -processes only: - -/etc/postfix/master.cf: - policy unix - n n - - spawn - user=nobody argv=/usr/bin/perl /usr/libexec/postfix/smtpd-policy.pl - -Specify "...postfix/smtpd-policy.pl -v" for verbose logging of each -request and reply. - -Greylisting mail from frequently forged domains ------------------------------------------------ - -It is relatively safe to turn on greylisting for specific domains -that often appear in forged email. However, sites like AOL may -blacklist you when they find that you are probing them too often, -or when you're probing them too often for non-existent addresses. - -/etc/postfix/main.cf: - smtpd_recipient_restrictions = - reject_unlisted_recipient - ... - reject_unauth_destination - check_sender_access hash:/etc/postfix/sender_access - ... - restriction_classes = greylist - greylist = check_policy_service unix:private/policy - policy_time_limit = 3600 - -/etc/postfix/sender_access: - aol.com greylist - hotmail.com greylist - bigfoot.com greylist - ... etcetera ... - -Be sure to specify check_sender_access AFTER reject_unauth_destination -or else your system could become an open mail relay. - -The greylist database gets polluted quickly with bogus addresses. -It can help if you protect greylist lookups with restrictions that -reject unknown senders and/or recipients. - -A list of frequently forged MAIL FROM domains can be found at -http://www.monkeys.com/anti-spam/filtering/sender-domain-validate.in - -Greylisting all your mail -------------------------- - -If you turn on greylisting for all mail you will almost certainly -want to make exceptions for mailing lists that use one-time sender -addresses, because such mailing lists can pollute your greylist -database relatively quickly. - -/etc/postfix/main.cf: - smtpd_recipient_restrictions = - reject_unlisted_recipient - ... - reject_unauth_destination - check_sender_access hash:/etc/postfix/sender_access - check_policy_service unix:private/policy - ... - policy_time_limit = 3600 - -/etc/postfix/sender_access: - securityfocus.com OK - ... - -Be sure to specify check_sender_access and check_policy_service -AFTER reject_unauth_destination or else your system could become -an open mail relay. - -The greylist database gets polluted quickly with bogus addresses. -It can help if you protect greylist lookups with restrictions that -reject unknown senders and/or recipients. - -ROUTINE MAINTENANCE -=================== - -The greylist database grows over time, because the greylist server -never removes database entries. If left unattended, the greylist -database will eventually run your file system out of space. - -When the status file size exceeds some threshold you can simply -rename or remove the file without adverse effects. In the worst -case, new mail will be delayed by an hour or so. To lessen the -impact, rename or remove the file in the middle of the night at -the beginning of a weekend. - -SAMPLE POLICY ROUTINE -===================== - -This is the PERL subroutine that implements the example greylist policy. +Note: DO NOT create the greylist database in a world-writable directory such as +/tmp or /var/tmp, and DO NOT create the greylist database in a file system that +may run out of space. Postfix can survive "out of space" conditions with the +mail queue and with the mailbox store, but it cannot survive a corrupted +greylist database. If the file becomes corrupted you may not be able to receive +mail at all until you delete the file by hand. + +The greylist.pl Perl script can be run under control by the Postfix master +daemon. For example, to run the script as user "nobody", using a UNIX-domain +socket that is accessible by Postfix processes only: + + 1 /etc/postfix/master.cf: + 2 policy unix - n n - - spawn + 3 user=nobody argv=/usr/bin/perl /usr/libexec/postfix/greylist.pl + 4 + 5 /etc/postfix/main.cf: + 6 policy_time_limit = 3600 + +Notes: + + * Line 3: Specify "greylist.pl -v" for verbose logging of each request and + reply. + + * Lines 2, 6: the Postfix spawn(8) daemon by default kills its child process + after 1000 seconds. This is too short for a policy daemon that may run for + as long as an SMTP client is connected to an SMTP server process. The + default time limit is overruled in main.cf with an explicit + "policy_time_limit" setting. The name of the parameter is the name of the + master.cf entry ("policy") concatenated with the "_time_limit" suffix. + +On Solaris you must use inet: style sockets instead of unix: style, as detailed +in the "Policy client/server configuration" section above. + + 1 /etc/postfix/master.cf: + 2 127.0.0.1:9998 unix - n n - - spawn + 3 user=nobody argv=/usr/bin/perl /usr/libexec/postfix/greylist.pl + 4 + 5 /etc/postfix/main.cf: + 6 127.0.0.1:9998_time_limit = 3600 + +To invoke this service you would specify "check_policy_service inet:127.0.0.1: +9998". + +GGrreeyylliissttiinngg mmaaiill ffrroomm ffrreeqquueennttllyy ffoorrggeedd ddoommaaiinnss + +It is relatively safe to turn on greylisting for specific domains that often +appear in forged email. A list of frequently forged MAIL FROM domains can be +found at http://www.monkeys.com/anti-spam/filtering/sender-domain-validate.in. + + 1 /etc/postfix/main.cf: + 2 smtpd_recipient_restrictions = + 3 reject_unlisted_recipient + 4 ... + 5 reject_unauth_destination + 6 check_sender_access hash:/etc/postfix/sender_access + 7 ... + 8 restriction_classes = greylist + 9 greylist = check_policy_service unix:private/policy + 10 + 11 /etc/postfix/sender_access: + 12 aol.com greylist + 13 hotmail.com greylist + 14 bigfoot.com greylist + 15 ... etcetera ... + +NOTES: + + * Line 9: On Solaris you must use inet: style sockets instead of unix: style, + as detailed in the "Example: greylist policy server" section above. + + * Line 6: Be sure to specify "check_sender_access" AFTER + "reject_unauth_destination" or else your system could become an open mail + relay. + + * Line 3: With Postfix 2.0 snapshot releases, "reject_unlisted_recipient" is + called "check_recipient_maps". Postfix 2.1 understands both forms. + + * Line 3: The greylist database gets polluted quickly with bogus addresses. + It helps if you protect greylist lookups with other restrictions that + reject unknown senders and/or recipients. + +GGrreeyylliissttiinngg aallll yyoouurr mmaaiill + +If you turn on greylisting for all mail you will almost certainly want to make +exceptions for mailing lists that use one-time sender addresses, because such +mailing lists can pollute your greylist database relatively quickly. + + 1 /etc/postfix/main.cf: + 2 smtpd_recipient_restrictions = + 3 reject_unlisted_recipient + 4 ... + 5 reject_unauth_destination + 6 check_sender_access hash:/etc/postfix/sender_access + 7 check_policy_service unix:private/policy + 8 ... + 9 + 10 /etc/postfix/sender_access: + 11 securityfocus.com OK + 12 ... + +NOTES: + + * Line 7: On Solaris you must use inet: style sockets instead of unix: style, + as detailed in the "Example: greylist policy server" section above. + + * Lines 6-7: Be sure to specify check_sender_access and check_policy_service + AFTER reject_unauth_destination or else your system could become an open + mail relay. + + * Line 3: The greylist database gets polluted quickly with bogus addresses. + It helps if you precede greylist lookups with restrictions that reject + unknown senders and/or recipients. + +RRoouuttiinnee ggrreeyylliisstt mmaaiinntteennaannccee + +The greylist database grows over time, because the greylist server never +removes database entries. If left unattended, the greylist database will +eventually run your file system out of space. + +When the status file size exceeds some threshold you can simply rename or +remove the file without adverse effects; Postfix automatically creates a new +file. In the worst case, new mail will be delayed by an hour or so. To lessen +the impact, rename or remove the file in the middle of the night at the +beginning of a weekend. + +EExxaammppllee PPeerrll ggrreeyylliisstt sseerrvveerr + +This is the Perl subroutine that implements the example greylist policy. It is +part of a general purpose sample policy server that is distributed with the +Postfix source as examples/smtpd-policy/greylist.pl. # # greylist status database and greylist time interval. DO NOT create the @@ -261,7 +338,7 @@ This is the PERL subroutine that implements the example greylist policy. # or /var/tmp. DO NOT create the greylist database in a file system # that can run out of space. # -$database_name="/var/mta/smtpd-policy.db"; +$database_name="/var/mta/greylist.db"; $greylist_delay=60; # @@ -277,7 +354,7 @@ sub smtpd_access_policy { # Lookup the time stamp for this client/sender/recipient. $key = - lc $attr{"client_address"}."/".$attr{"sender"}."/".$attr{"recipient"}; + lc $attr{"client_address"}."/".$attr{"sender"}."/".$attr{"recipient"}; $time_stamp = read_database($key); $now = time(); @@ -287,10 +364,16 @@ sub smtpd_access_policy { update_database($key, $time_stamp); } - # In case of success, return DUNNO instead of OK so that the + # The result can be any action that is allowed in a Postfix access(5) map. + # + # To label the mail, return ``PREPEND headername: headertext'' + # + # In case of success, return ``DUNNO'' instead of ``OK'', so that the # check_policy_service restriction can be followed by other restrictions. - # In case of failure, specify DEFER_IF_PERMIT so that mail can - # still be blocked by other access restrictions. + # + # In case of failure, return ``DEFER_IF_PERMIT optional text...'', + # so that mail can still be blocked by other access restrictions. + # syslog $syslog_priority, "request age %d", $now - $time_stamp if $verbose; if ($now - $time_stamp > $greylist_delay) { return "dunno"; @@ -298,3 +381,4 @@ sub smtpd_access_policy { return "defer_if_permit Service temporarily unavailable"; } } + diff --git a/postfix/README_FILES/SMTPD_PROXY_README b/postfix/README_FILES/SMTPD_PROXY_README index a951d221b..812569931 100644 --- a/postfix/README_FILES/SMTPD_PROXY_README +++ b/postfix/README_FILES/SMTPD_PROXY_README @@ -1,238 +1,236 @@ -WARNING WARNING WARNING WARNING WARNING WARNING WARNING WARNING -=============================================================== -The content filtering approach described in this document is suitable -only for low-traffic sites. See the "Pros ans Cons" section below -for details. +PPoossttffiixx BBeeffoorree--QQuueeuuee CCoonntteenntt FFiilltteerr -Purpose of the before-queue content filter feature -================================================== +------------------------------------------------------------------------------- -The Postfix SMTP server can be configured to forward all incoming -mail to a content filter (for example, a real-time SPAM filter) -that inspects all mail BEFORE it is stored in the Postfix mail -queue. +WWAARRNNIINNGG WWAARRNNIINNGG WWAARRNNIINNGG + +The before-queue content filtering feature described in this document is +suitable only for low-traffic sites. See the "Pros and Cons" section below for +details. + +TThhee PPoossttffiixx bbeeffoorree--qquueeuuee ccoonntteenntt ffiilltteerr ffeeaattuurree + +As of version 2.1, the Postfix SMTP server can forward all incoming mail to a +content filtering proxy server that inspects all mail BEFORE it is stored in +the Postfix mail queue. The before-queue content filter is meant to be used as follows: - BEFORE / smtp - Internet -> smtpd -> QUEUE -> smtpd -> cleanup -> queue -> local - Postfix FILTER Postfix \ virtual etc. + Postfix BBeeffoorree Postfix Postfix Postfix smtp + Internet -> SMTP -> qquueeuuee -> SMTP -> cleanup -> queue -< local + server ffiilltteerr server server virtual -The before-queue content filter is not to be confused with the -approach described in the FILTER_README document, where mail is -filtered AFTER it is stored in the Postfix mail queue. +The before-queue content filter is not to be confused with the approach +described in the FILTER_README document, where mail is filtered AFTER it is +stored in the Postfix mail queue. -Principles of operation -======================= +This document describes the following topics: -The filter receives unfiltered SMTP mail from Postfix and does one -of the following: + * Principles of operation + * Pros and cons of before-queue content filtering + * Configuring the Postfix SMTP pass-through proxy feature + * Configuration parameters + * How Postfix talks to the before-queue content filter + * Transparency -1 - Re-inject the mail back into Postfix via SMTP, perhaps after - changing content. +PPrriinncciipplleess ooff ooppeerraattiioonn -2 - Reject the mail by sending a suitable SMTP status code back - to Postfix. Postfix passes the status back to the remote SMTP - client. This way, Postfix does not have to send a bounce message. +The before-filter Postfix SMTP server receives mail from the Internet and does +the usual relay access control, SASL authentication, RBL lookups, rejecting +non-existent sender or recipient addresses, etc. The before-queue filter +receives unfiltered mail content from Postfix and does one of the following: -3 - Send the mail somewhere else, or discard the mail. + 1. Re-inject the mail back into Postfix via SMTP, perhaps after changing its + content and/or destination. -The before-queue content filter functions just like the after-queue -content filter. In many cases you can use the same content filtering -software, within the limitations as discussed in the "Pros and Cons" -section below. + 2. Reject the mail by sending a suitable SMTP status code back to Postfix. + Postfix passes the status back to the remote SMTP client. This way, Postfix + does not have to send a bounce message. -Using the SMTP pass-through proxy feature -========================================= +The after-filter Postfix SMTP server receives mail from the content filter. +From then on Postfix processes the mail as usual. -In the following example, the Postfix SMTP server gives mail to a -content filter that listens on localhost port 10025, and receives -mail from the content filter via localhost port 10026. From then -on mail is processed as usual. +The before-queue content filter described here works just like the after-queue +content filter described in the FILTER_README document. In many cases you can +use the same software, within the limitations as discussed in the "Pros and +Cons" section below. -The result looks as follows: +PPrrooss aanndd ccoonnss ooff bbeeffoorree--qquueeuuee ccoonntteenntt ffiilltteerriinngg - Internet - -> Postfix SMTP server on port 25 - -> filter on localhost port 10025 - -> Postfix SMTP server on localhost port 26 - -> cleanup - -> queue + * Pro: Postfix can reject mail before the incoming SMTP mail transfer + completes, so that Postfix does not have to send rejected mail back to the + sender (which is usually forged anyway). Mail that is not accepted remains + the responsibility of the remote SMTP client. -This is configured by editing the master.cf file: + * Con: The remote SMTP client expects an SMTP reply within a deadline. As the + system load increases, fewer and fewer CPU cycles remain available to + answer within the deadline, and eventually you either have to stop + accepting mail or you have to stop filtering mail. It is for this reason + that the before-queue content filter can be used only on low-traffic sites. -/etc/postfix/master.cf: - # ============================================================= - # service type private unpriv chroot wakeup maxproc command - # (yes) (yes) (yes) (never) (100) - # ============================================================= - # - # Before-filter SMTP server. Receive mail from the network and - # pass it to the content filter on localhost port 10025. - # - smtp inet n - n - 20 smtpd - -o smtpd_proxy_filter=localhost:10025 - -o smtpd_client_connection_count_limit=10 - # - # After-filter SMTP server. Receive mail from the content filter - # on localhost port 10026. - # - :10026 inet n - n - - smtpd - -o smtpd_authorized_xforward_hosts=127.0.0.0/8 - -o smtpd_client_restrictions= - -o smtpd_helo_restrictions= - -o smtpd_sender_restrictions= - -o smtpd_recipient_restrictions=permit_mynetworks,reject - -o mynetworks=127.0.0.0/8 - -o receive_override_options=no_unknown_recipient_checks + * Con: Content filtering software can use lots of memory resources. In order + to not run out of memory you have to reduce the number of before-filter + SMTP server processes so that a burst of mail will not drive your system + into the ground with too many content filter processes. This, in turn, + means that SMTP clients have to wait for a long time before they receive + service. -Note: do not specify spaces around the "=" or "," characters. +CCoonnffiigguurriinngg tthhee PPoossttffiixx SSMMTTPP ppaassss--tthhrroouugghh pprrooxxyy ffeeaattuurree -The before-filter SMTP server entry is a modified version of the -default Postfix SMTP server entry that is normally configured at -the top of the master.cf file: +In the following example, the before-filter Postfix SMTP server gives mail to a +content filter that listens on localhost port 10025. The after-filter Postfix +SMTP server receives mail from the content filter via localhost port 10026. +From then on mail is processed as usual. -- The number of SMTP sessions is reduced from the default 100 to - only 20. This prevents a burst of mail from running your system - into the ground with too many content filter processes. +The content filter itself is not described here. You can use any filter that is +SMTP enabled. For non-SMTP capable content filtering software, Bennett Todd's +SMTP proxy implements a nice PERL/SMTP content filtering framework. See: http:/ +/bent.latency.net/smtpprox/. -- The "-o smtpd_client_connection_count_limit=10" prevents one - SMTP client from using up all 20 SMTP server processes. This - limit is not necessary if you receive all mail from a trusted - relay host. + Postfix + Postfix filter on SMTP server Postfix Postfix + Internet -> SMTP server -> localhost -> on -> cleanup -> incoming + on port 25 port 10025 localhost server queue + port 10026 -- The "-o smtpd_proxy_filter=localhost:10025" tells the before - filter SMTP server that it should give incoming mail to the - content filter that listens on localhost port 10025. +This is configured by editing the master.cf file: -The after-filter SMTP server is a new master.cf entry: + /etc/postfix/master.cf: + # ============================================================= + # service type private unpriv chroot wakeup maxproc command + # (yes) (yes) (yes) (never) (100) + # ============================================================= + # + # Before-filter SMTP server. Receive mail from the network and + # pass it to the content filter on localhost port 10025. + # + smtp inet n - n - 20 smtpd + -o smtpd_proxy_filter=127.0.0.1:10025 + -o smtpd_client_connection_count_limit=10 + # + # After-filter SMTP server. Receive mail from the content filter + # on localhost port 10026. + # + :10026 inet n - n - - smtpd + -o smtpd_authorized_xforward_hosts=127.0.0.0/8 + -o smtpd_client_restrictions= + -o smtpd_helo_restrictions= + -o smtpd_sender_restrictions= + -o smtpd_recipient_restrictions=permit_mynetworks,reject + -o smtpd_data_restrictions= + -o mynetworks=127.0.0.0/8 + -o receive_override_options=no_unknown_recipient_checks -- The ":10026" makes the after-filter SMTP server listen on the - localhost address only, without exposing it to the network. - NEVER expose the after-filter SMTP server to the Internet :-) - -- The "-o smtpd_authorized_xforward_hosts=127.0.0.0/8" allows the - after-filter SMTP server to receive remote SMTP client information - from the before filter SMTP server, so that the after-filter - Postfix daemons log the remote SMTP client information instead - of logging localhost[127.0.0.1]. - -- The other after-filter SMTP server settings avoid duplication of - work that is already done in the "before filter" SMTP server. - -The filter itself is not described here. You can use any filter -that is SMTP enabled. For non-SMTP capable content filtering -software, Bennett Todd's SMTP proxy implements a nice PERL/SMTP -content filtering framework. See: http://bent.latency.net/smtpprox/ - -By default, the filter has 100 seconds to do its work. If it takes -longer then Postfix gives up and reports an error to the remote -SMTP client. You can increase this time limit (see configuration -parameter section below) but doing so is pointless because you -can't control when the remote SMTP client times out. - -Pros and Cons -============= - -The before-queue content filter allows Postfix to reject mail before -the incoming SMTP mail transfer completes, so that Postfix does -not have to send rejected mail back to the sender. Mail that is -not accepted remains the responsibility of the remote SMTP client. - -The problem with before-queue content filtering is that the remote -SMTP client expects an SMTP reply within a deadline. As the system -load increases, fewer and fewer CPU cycles remain available to -answer within the deadline, and eventually you either have to stop -accepting mail or you have to stop filtering the mail. - -Another problem is that content filtering software can use lots of -memory resources. In order to not run out of memory you have to -reduce the number of before-filter SMTP server processes so that -a burst of mail will not drive your system into the ground with -too many content filter processes. This, in turn, means that SMTP -clients have to wait for a long time before they receive service. - -How Postfix talks to the before-queue content filter -================================================== - -The before-filter Postfix SMTP server connects to the content -filter, delivers one message, and disconnects. While sending mail -into the content filter, Postfix speaks ESMTP but uses no command -pipelining. Postfix generates its own EHLO, XFORWARD (for logging -the remote client IP address instead of localhost[127.0.0.1]), DATA -and QUIT commands, and forwards unmodified copies of all the MAIL -FROM and RCPT TO commands that the before-filter Postfix SMTP server -didn't reject itself. The SMTP proxy server should accept the same -MAIL FROM and RCPT TO command syntax as the Postfix SMTP server. -Postfix sends no other SMTP commands. - -The content filter is expected to pass on unmodified SMTP commands -from a before-filter Postfix SMTP server to an after-filter Postfix -SMTP server that usually listens on a non-standard port. When the -filter rejects content, it should send a negative SMTP response -back to the before-filter Postfix SMTP server, and it should abort -the connection with the after-filter Postfix SMTP server without -completing the SMTP conversation with the after-filter Postfix SMTP -server. - -More details on the postfix-to-proxy interaction is at the end of -this document, in the section titled "Transparency". - -Configuration parameters -======================== +Note: do not specify spaces around the "=" or "," characters. -Parameters that control proxying: +The before-filter SMTP server entry is a modified version of the default +Postfix SMTP server entry that is normally configured at the top of the +master.cf file: -smtpd_proxy_filter (syntax: host:port) + * The number of SMTP sessions is reduced from the default 100 to only 20. + This prevents a burst of mail from running your system into the ground with + too many content filter processes. - The host and TCP port of the before-queue content filter. When - no host or host: is specified, localhost is assumed. + * The "-o smtpd_client_connection_count_limit=10" prevents one SMTP client + from using up all 20 SMTP server processes. This limit is not necessary if + you receive all mail from a trusted relay host. -smtpd_proxy_timeout (default: 100s) + Note: this setting is ignored by the stable Postfix 2.1 release. The + feature will be available only in the experimental release until Postfix + 2.2. - Timeout for connecting to the before-queue content filter and - for sending and receiving commands and data. All proxy errors - are logged to the maillog file. For privacy reasons, all the - remote SMTP client sees is "451 Error: queue file write error". + * The "-o smtpd_proxy_filter=127.0.0.1:10025" tells the before filter SMTP + server that it should give incoming mail to the content filter that listens + on localhost port 10025. -smtpd_proxy_ehlo (default: $myhostname) +The after-filter SMTP server is a new master.cf entry: - The hostname to use when sending an EHLO command to the - before-queue content filter. + * The ":10026" makes the after-filter SMTP server listen on the localhost + address only, without exposing it to the network. NEVER expose the after- + filter SMTP server to the Internet :-) -Transparency -============ + * The "-o smtpd_authorized_xforward_hosts=127.0.0.0/8" allows the after- + filter SMTP server to receive remote SMTP client information from the + before filter SMTP server, so that the after-filter Postfix daemons log the + remote SMTP client information instead of logging localhost[127.0.0.1]. -The before-filter Postfix SMTP server forwards the MAIL FROM, RCPT -TO and DATA commands that it has approved, but it does not forward -other commands such as TLS or SASL commands. It can therefore not -be transparent. + * The other after-filter SMTP server settings avoid duplication of work that + is already done in the "before filter" SMTP server. -The real-time content filter, on the other hand, has to be transparent. -In order to support non-transparent real-time content filters, -Postfix would have to reconcile the before-filter Postfix ESMTP -feature set with the feature set that Postfix receives from the -real-time content filter. +By default, the filter has 100 seconds to do its work. If it takes longer then +Postfix gives up and reports an error to the remote SMTP client. You can +increase this time limit (see configuration parameter section below) but doing +so is pointless because you can't control when the remote SMTP client times +out. -- When a future Postfix version supports DSN, but the content filter - does not announce DSN support in the EHLO reply, then the - before-filter SMTP server would have to either 1) suppress the - DSN feature in its EHLO announcement, or 2) duplicate all the - work that needs to be done when delivering DSN-aware mail to a - non-DSN destination. +CCoonnffiigguurraattiioonn ppaarraammeetteerrss -- When the content filter does not announce 8BITMIME support in - the EHLO reply, then the before-filter SMTP server would have to - either 1) suppress the 8BITMIME feature in its EHLO announcement, - or 2) convert the content to quoted-printable before giving it - to the content filter. +Parameters that control proxying: -- Performance: when Postfix has to suppress elements from the - before-filter EHLO reply because they are incompatible with the - real-time content filter, then Postfix has to connect to the - content filter as soon as the client sends a valid EHLO command. - This wastes a lot of resources when all the MAIL FROM or RCPT TO - commands are rejected. + * smtpd_proxy_filter (syntax: host:port): The host and TCP port of the + before-queue content filter. When no host or host: is specified, localhost + is assumed. + + * smtpd_proxy_timeout (default: 100s): Timeout for connecting to the before- + queue content filter and for sending and receiving commands and data. All + proxy errors are logged to the maillog file. For privacy reasons, all the + remote SMTP client sees is "451 Error: queue file write error". It would + not be right to disclose internal details to strangers. + + * smtpd_proxy_ehlo (default: $myhostname): The hostname to use when sending + an EHLO command to the before-queue content filter. + +HHooww PPoossttffiixx ttaallkkss ttoo tthhee bbeeffoorree--qquueeuuee ccoonntteenntt ffiilltteerr + +The before-filter Postfix SMTP server connects to the content filter, delivers +one message, and disconnects. While sending mail into the content filter, +Postfix speaks ESMTP but uses no command pipelining. Postfix generates its own +EHLO, XFORWARD (for logging the remote client IP address instead of localhost +[127.0.0.1]), DATA and QUIT commands, and forwards unmodified copies of all the +MAIL FROM and RCPT TO commands that the before-filter Postfix SMTP server +didn't reject itself. The SMTP proxy server should accept the same MAIL FROM +and RCPT TO command syntax as the Postfix SMTP server. Postfix sends no other +SMTP commands. + +The content filter is expected to pass on unmodified SMTP commands from a +before-filter Postfix SMTP server to an after-filter Postfix SMTP server that +usually listens on a non-standard port. When the filter rejects content, it +should send a negative SMTP response back to the before-filter Postfix SMTP +server, and it should abort the connection with the after-filter Postfix SMTP +server without completing the SMTP conversation with the after-filter Postfix +SMTP server. + +More detail on the postfix-to-proxy interaction is in the section titled +"Transparency". + +TTrraannssppaarreennccyy + +The before-filter Postfix SMTP server forwards the MAIL FROM, RCPT TO and DATA +commands that it has approved, but it does not forward other commands such as +TLS or SASL commands. It can therefore not be transparent. + +The real-time content filter, on the other hand, has to be transparent. In +order to support non-transparent real-time content filters, Postfix would have +to reconcile the before-filter Postfix ESMTP feature set with the feature set +that Postfix receives from the real-time content filter. + + * When a future Postfix version supports DSN, but the content filter does not + announce DSN support in the EHLO reply, then the before-filter SMTP server + would have to either 1) suppress the DSN feature in its EHLO announcement, + or 2) duplicate all the work that needs to be done when delivering DSN- + aware mail to a non-DSN destination. + + * When the content filter does not announce 8BITMIME support in the EHLO + reply, then the before-filter SMTP server would have to either 1) suppress + the 8BITMIME feature in its EHLO announcement, or 2) convert the content to + quoted-printable before giving it to the content filter. + + * Performance: when Postfix has to suppress elements from the before-filter + EHLO reply because they are incompatible with the real-time content filter, + then Postfix has to connect to the content filter as soon as the client + sends a valid EHLO command. This wastes a lot of resources when all the + MAIL FROM or RCPT TO commands are rejected. + +Therefore, the Postfix SMTP server cannot be transparent with respect to the +before-queue content filter. -Therefore, the Postfix SMTP server cannot be transparent with -respect to the before-queue content filter. diff --git a/postfix/README_FILES/STANDARD_CONFIGURATION_README b/postfix/README_FILES/STANDARD_CONFIGURATION_README new file mode 100644 index 000000000..b8ac38956 --- /dev/null +++ b/postfix/README_FILES/STANDARD_CONFIGURATION_README @@ -0,0 +1,528 @@ +PPoossttffiixx SSttaannddaarrdd CCoonnffiigguurraattiioonn EExxaammpplleess + +------------------------------------------------------------------------------- + +PPuurrppoossee ooff tthhiiss ddooccuummeenntt + +This document presents a number of typical Postfix configurations. This +document should be reviewed after you have followed the basic configuration +steps as described in the BASIC_CONFIGURATION_README document. In particular, +do not proceed here if you don't already have Postfix working for local mail +submission and for local mail delivery. + +The first part of this document presents standard configurations that each +solve one specific problem. + + * Postfix on a stand-alone Internet host + * Postfix on a null client + * Postfix on a local network + * Postfix email firewall/gateway + +The second part of this document presents additional configurations for hosts +in specific environments. + + * Delivering some but not all accounts locally + * Running Postfix behind a firewall + * Configuring Postfix as MX host for a remote site + * Postfix on a dialup machine + * Postfix on hosts without a real hostname + +PPoossttffiixx oonn aa ssttaanndd--aalloonnee IInntteerrnneett hhoosstt + +Postfix should work out of the box without change on a stand-alone machine that +has direct Internet access. At least, that is how Postfix installs when you +download the Postfix source code via http://www.postfix.org/. + +You can use the command "postconf -n" to find out what settings are overruled +by your main.cf. Besides a few pathname settings, few parameters should be set +on a stand-alone box, beyond what is covered in the BASIC_CONFIGURATION_README +document: + + /etc/postfix/main.cf: + # Optional: send mail as user@domainname instead of user@hostname. + #myorigin = $mydomain + + # Optional: specify NAT/proxy external address. + #proxy_interfaces = 1.2.3.4 + + # Don't relay mail from other hosts. + mynetworks_style = host + relay_domains = + +See also the section "Postfix on hosts without a real hostname" if this is +applicable to your configuration. + +PPoossttffiixx oonn aa nnuullll cclliieenntt + +A null client is a machine that can only send mail. It receives no mail from +the network, and it does not deliver any mail locally. A null client typically +uses POP, IMAP or NFS for mailbox access. + +In this example we assume that the Internet domain name is "example.com" and +that the machine is named "nullclient.example.com". As usual, the examples show +only parameters that are not left at their default settings. + + 1 /etc/postfix/main.cf: + 2 myorigin = $mydomain + 3 relayhost = $mydomain + 4 inet_interfaces = 127.0.0.1 + 5 local_transport = error:local delivery is disabled + 6 + 7 /etc/postfix/master.cf: + 8 Comment out the local delivery agent entry + +Translation: + + * Line 2: Send mail as "user@example.com" (instead of + "user@nullclient.example.com"), so that nothing ever has a reason to send + mail to "user@nullclient.example.com". + + * Line 3: Forward all mail to the mail server that is responsible for the + "example.com" domain. This prevents mail from getting stuck on the null + client if it is turned off while some remote destination is unreachable. + + * Line 4: Do not accept mail from the network. + + * Lines 5-8: Disable local mail delivery. All mail goes to the mail server as + specified in line 3. + +PPoossttffiixx oonn aa llooccaall nneettwwoorrkk + +This section describes a local area network environment of one main server and +multiple other systems that send and receive email. As usual we assume that the +Internet domain name is "example.com". All systems are configured to send mail +as "user@example.com", and all systems receive mail for +"user@hostname.example.com". The main server also receives mail for +"user@example.com". We call this machine by the name of mailhost.example.com. + +A drawback of sending mail as "user@example.com" is that mail for "root" and +other system accounts is also sent to the central mailhost. See the section +"Delivering some but not all accounts locally" below for possible solutions. + +As usual, the examples show only parameters that are not left at their default +settings. + +First we present the non-mailhost configuration, because it is the simpler one. +This machine sends mail as "user@example.com" and is final destination for +"user@hostname.example.com". + + 1 /etc/postfix/main.cf: + 2 myorigin = $mydomain + 3 mynetworks = 127.0.0.0/8 10.0.0.0/24 + 4 relay_domains = + 5 # Optional: forward all non-local mail to mailhost + 6 #relayhost = $mydomain + +Translation: + + * Line 2: Send mail as "user@example.com". + + * Line 3: Specify the trusted networks. + + * Line 4: This host does not relay mail from untrusted networks. + + * Line 6: This is needed if no direct Internet access is available. See also + below, "Postfix behind a firewall". + +Next we present the mailhost configuration. This machine sends mail as +"user@example.com" and is final destination for "user@hostname.example.com" as +well as "user@example.com". + + 1 DNS: + 2 example.com IN MX 10 mailhost.example.com. + 3 + 4 /etc/postfix/main.cf: + 5 myorigin = $mydomain + 6 mydestination = $myhostname localhost.$mydomain localhost $mydomain + 7 mynetworks = 127.0.0.0/8 10.0.0.0/24 + 8 relay_domains = + 9 # Optional: forward all non-local mail to firewall + 10 #relayhost = [firewall.example.com] + +Translation: + + * Line 2: Send mail for the domain "example.com" to the machine + mailhost.example.com. Remember to specify the "." at the end of the line. + + * Line 5: Send mail as "user@example.com". + + * Line 6: This host is the final mail destination for the "example.com" + domain, in addition to the names of the machine itself. + + * Line 7: Specify the trusted networks. + + * Line 8: This host does not relay mail from untrusted networks. + + * Line 10: This is needed only when the mailhost has to forward non-local + mail via a mail server on a firewall. The [] forces Postfix to do no MX + record lookups. + +In an environment like this, users access their mailbox in one or more of the +following ways: + + * Mailbox access via NFS or equivalent. + + * Mailbox access via POP or IMAP. + + * Mailbox on the user's preferred machine. + +In the latter case, each user has an alias on the mailhost that forwards mail +to her preferred machine: + + /etc/aliases: + joe: joe@joes.preferred.machine + jane: jane@janes.preferred.machine + +On some systems the alias database is not in /etc/aliases. To find out the +location for your system, execute the command "postconf alias_maps". + +Execute the command "newaliases" whenever you change the aliases file. + +PPoossttffiixx eemmaaiill ffiirreewwaallll//ggaatteewwaayy + +The idea is to set up a Postfix email firewall/gateway that forwards mail for +"example.com" to an inside gateway machine but rejects mail for +"anything.example.com". There is only one problem: with "relay_domains = +example.com", the firewall normally also accepts mail for +"anything.example.com". That would not be right. + +Note: this example requires Postfix version 2.0 and later. To find out what +Postfix version you have, execute the command "postconf mail_version". + +The solution is presented in multiple parts. This first part gets rid of local +mail delivery on the firewall, making the firewall harder to break. + + 1 /etc/postfix/main.cf: + 2 myorigin = example.com + 3 mydestination = + 4 local_recipient_maps = + 5 local_transport = error:local mail delivery is disabled + 6 + 7 /etc/postfix/master.cf: + 8 Comment out the local delivery agent + +Translation: + + * Line 2: Send mail from this machine as "user@example.com", so that no + reason exists to send mail to "user@firewall.example.com". + + * Lines 3-8: Disable local mail delivery on the firewall machine. + +For the sake of technical correctness the firewall must be able to receive mail +for postmaster@[firewall ip address]. Reportedly, some things actually expect +this ability to exist. The second part of the solution therefore adds support +for postmaster@[firewall ip address], and as a bonus we do abuse@[firewall ip +address] as well. All the mail to these two accounts is forwarded to an inside +address. + + 1 /etc/postfix/main.cf: + 2 virtual_alias_maps = hash:/etc/postfix/virtual + 3 + 4 /etc/postfix/virtual: + 5 postmaster postmaster@example.com + 6 abuse abuse@example.com + +Translation: + + * Because mydestination is empty (see the previous example), only address + literals matching $inet_interfaces or $proxy_interfaces are deemed local. + So "localpart@[a.d.d.r]" can be matched as simply "localpart" in canonical + (5) and virtual(5). This avoids the need to specify firewall IP addresses + into Postfix configuration files. + +The last part of the solution does the email forwarding, which is the real +purpose of the firewall email function. + + 1 /etc/postfix/main.cf: + 2 mynetworks = 127.0.0.0/8 12.34.56.0/24 + 3 relay_domains = example.com + 4 parent_domain_matches_subdomains = + 5 debug_peer_list smtpd_access_maps + 6 smtpd_recipient_restrictions = + 7 permit_mynetworks reject_unauth_destination + 8 + 9 relay_recipient_maps = hash:/etc/postfix/relay_recipients + 10 transport_maps = hash:/etc/postfix/transport + 11 + 12 /etc/postfix/relay_recipients: + 13 user1@example.com x + 14 user2@example.com x + 15 . . . + 16 + 17 /etc/postfix/transport: + 18 example.com smtp:[inside-gateway.example.com] + +Translation: + + * Lines 1-7: Accept mail from local systems in $mynetworks, and accept mail + from outside for "user@example.com" but not for + "user@anything.example.com". The magic is in lines 4-5. + + * Lines 9, 12-14: Define the list of valid addresses in the "example.com" + domain that can receive mail from the Internet. This prevents the mail + queue from filling up with undeliverable MAILER-DAEMON messages. If you + can't maintain a list of valid recipients then you must specify + "relay_recipient_maps =" (that is, an empty value), or you must specify an + "@example.com x" wild-card in the relay_recipients table. + + * Lines 10, 17-18: Route mail for "example.com" to the inside gateway + machine. The [] forces Postfix to do no MX lookup. + +Specify dbm instead of hash if your system uses dbm files instead of db. To +find out what lookup tables Postfix supports, use the command "postconf -m". + +Execute the command "postmap /etc/postfix/relay_recipients" whenever you change +the relay_recipients table. + +Execute the command "postmap /etc/postfix/transport" whenever you change the +transport table. + +DDeelliivveerriinngg ssoommee bbuutt nnoott aallll aaccccoouunnttss llooccaallllyy + +A drawback of sending mail as "user@example.com" (instead of +"user@hostname.example.com") is that mail for "root" and other system accounts +is also sent to the central mailhost. In order to deliver such accounts +locally, you can set up virtual aliases as follows: + + 1 /etc/postfix/main.cf: + 2 virtual_alias_maps = hash:/etc/postfix/virtual + 3 + 4 /etc/postfix/virtual: + 5 root root@localhost + 6 . . . + +Translation: + + * Line 5: As described in the virtual(5) manual page, the bare name "root" + matches "root@site" when "site" is equal to $myorigin, when "site" is + listed in $mydestination, or when it matches $inet_interfaces or + $proxy_interfaces. + +RRuunnnniinngg PPoossttffiixx bbeehhiinndd aa ffiirreewwaallll + +The simplest way to set up Postfix on a host behind a firewalled network is to +send all mail to a gateway host, and to let that mail host take care of +internal and external forwarding. Examples of that are shown in the local area +network section above. A more sophisticated approach is to send only external +mail to the gateway host, and to send intranet mail directly. That's what +Wietse does at work. + +Note: this example requires Postfix version 2.0 and later. To find out what +Postfix version you have, execute the command "postconf mail_version". + +The following example presents additional configuration. You need to combine +this with basic configuration information as discussed the first half of this +document. + + 1 /etc/postfix/main.cf: + 2 transport_maps = hash:/etc/postfix/transport + 3 relayhost = + 4 # Optional for a machine that isn't "always on" + 5 #fallback_relay = [gateway.example.com] + 6 + 7 /etc/postfix/transport: + 8 # Internal delivery. + 9 example.com : + 10 .example.com : + 11 # External delivery. + 12 * smtp:[gateway.example.com] + +Translation: + + * Lines 2, 7-12: Request that intranet mail is delivered directly, and that + external mail is given to a gateway. Obviously, this example assumes that + the organization uses DNS MX records internally. The [] forces Postfix to + do no MX lookup. + + * Line 3: IMPORTANT: do not specify a relayhost in main.cf. + + * Line 5: This prevents mail from being stuck in the queue when the machine + is turned off. Postfix tries to deliver mail directly, and gives + undeliverable mail to a gateway. + +Specify dbm instead of hash if your system uses dbm files instead of db. To +find out what lookup tables Postfix supports, use the command "postconf -m". + +Execute the command "postmap /etc/postfix/transport" whenever you edit the +transport table. + +CCoonnffiigguurriinngg PPoossttffiixx aass MMXX hhoosstt ffoorr aa rreemmoottee ssiittee + +This section presents additional configuration. You need to combine this with +basic configuration information as discussed the first half of this document. + +When your system is SECONDARY MX host for a remote site this is all you need: + + 1 DNS: + 2 the.backed-up.domain.tld IN MX 100 your.machine.tld. + 3 + 4 /etc/postfix/main.cf: + 5 relay_domains = . . . the.backed-up.domain.tld + 6 smtpd_recipient_restrictions = + 7 permit_mynetworks reject_unauth_destination + 8 + 9 # You must specify your NAT/proxy external address. + 10 #proxy_interfaces = 1.2.3.4 + 11 + 12 relay_recipient_maps = hash:/etc/postfix/relay_recipients + 13 + 14 /etc/postfix/relay_recipients: + 15 user1@the.backed-up.domain.tld x + 16 user2@the.backed-up.domain.tld x + 17 . . . + +When your system is PRIMARY MX host for a remote site you need the above, plus: + + 18 /etc/postfix/main.cf: + 19 transport_maps = hash:/etc/postfix/transport + 20 + 21 /etc/postfix/transport: + 22 the.backed-up.domain.tld relay:[their.mail.host.tld] + +Important notes: + + * Do not list the.backed-up.domain.tld in mydestination. + + * Do not list the.backed-up.domain.tld in virtual_alias_domains. + + * Do not list the.backed-up.domain.tld in virtual_mailbox_domains. + + * Lines 1-7: Forward mail from the Internet for "the.backed-up.domain.tld" to + the primary MX host for that domain. + + * Line 10: This is a must if Postfix receives mail via a NAT relay or proxy + that presents a different IP address to the world than the local machine. + + * Lines 12-16: Define the list of valid addresses in the "the.backed- + up.domain.tld" domain. This prevents your mail queue from filling up with + undeliverable MAILER-DAEMON messages. If you can't maintain a list of valid + recipients then you must specify "relay_recipient_maps =" (that is, an + empty value), or you must specify an "@example.com x" wild-card in the + relay_recipients table. + + * Line 22: The [] forces Postfix to do no MX lookup. + +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". + +Execute the command "postmap /etc/postfix/transport" whenever you change the +transport table. + +PPoossttffiixx oonn aa ddiiaalluupp mmaacchhiinnee + +This section applies to dialup connections that are down most of the time. For +dialup connections that are up 24x7, see the local area network section above. + +This section presents additional configuration. You need to combine this with +basic configuration information as discussed the first half of this document. + +If you do not have your own hostname (as with dynamic IP addressing) then you +should also study the section on "Postfix on hosts without a real hostname". + + * Route all outgoing mail to your network provider. + If your machine is disconnected most of the time, there isn't a lot of + opportunity for Postfix to deliver mail to hard-to-reach corners of the + Internet. It's better to give the mail to a machine that is connected all + the time. In the example below, the [] prevents Postfix from trying to look + up DNS MX records. + + /etc/postfix/main.cf: + relayhost = [smtprelay.someprovider.com] + + * Disable spontaneous SMTP mail delivery (if using on-demand dialup IP only). + + Normally, Postfix attempts to deliver outbound mail at its convenience. If + your machine uses on-demand dialup IP, this causes your system to place a + telephone call whenever you submit new mail, and whenever Postfix retries + to deliver delayed mail. To prevent such telephone calls from being placed, + disable spontaneous SMTP mail deliveries. + + /etc/postfix/main.cf: + defer_transports = smtp (Only for on-demand dialup IP hosts) + + * Disable SMTP client DNS lookups (dialup LAN only). + + /etc/postfix/main.cf: + disable_dns_lookups = yes (Only for on-demand dialup IP hosts) + + * Flush the mail queue whenever the Internet link is established. + Put the following command into your PPP or SLIP dialup scripts: + + /usr/sbin/sendmail -q (whenever the Internet link is up) + + The exact location of the sendmail command is system-specific. Use the + command "postconf sendmail_path" to find out where the Postfix sendmail + command is located on your machine. + + In order to find out if the mail queue is flushed, use something like: + + #!/bin/sh + + # Start mail deliveries. + /usr/sbin/sendmail -q + + # Allow deliveries to start. + sleep 10 + + # Loop until all messages have been tried at least once. + while mailq | grep '^[^ ]*\*' >/dev/null + do + sleep 10 + done + + If you have disabled spontaneous SMTP mail delivery, you also need to run + the "sendmail -q" command every now and then while the dialup link is up, + so that newly-posted mail is flushed from the queue. + +PPoossttffiixx oonn hhoossttss wwiitthhoouutt aa rreeaall hhoossttnnaammee + +This section is for hosts that don't have an Internet hostname. Typically these +are systems that get a dynamic IP address via DHCP or via dialup. Postfix will +let you send and receive mail just fine between accounts on a machine with a +fantasy name. However, you cannot use a fantasy hostname in your email address +when sending mail into the Internet, because no-one would be able to reply to +your mail. In fact, more and more sites refuse mail from non-existent domain +names. + +The perfect solution would be for Postfix to do a mapping from local fantasy +email addresses to valid Internet addresses when mail leaves the machine +(similar to Sendmail's generics table). This is planned for the near future. + +In the mean time, the solution with Postfix is to use valid Internet addresses +where possible, and to let Postfix map valid Internet addresses to local +fantasy addresses. With this, you can send mail to the Internet and to local +fantasy addresses, including mail to local fantasy addresses that don't have a +valid Internet address of their own. + +The following example presents additional configuration. You need to combine +this with basic configuration information as discussed the first half of this +document. + + 1 /etc/postfix/main.cf: + 2 myhostname = hostname.localdomain + 3 mydomain = localdomain + 4 + 5 canonical_maps = hash:/etc/postfix/canonical + 6 + 7 virtual_alias_maps = hash:/etc/postfix/virtual + 8 + 9 /etc/postfix/canonical: + 10 your-login-name your-account@your-isp.com + 11 + 12 /etc/postfix/virtual: + 13 your-account@your-isp.com your-login-name + +Translation: + + * Lines 2-3: Substitute your fantasy hostname here. Do not use a domain name + that is already in use by real organizations on the Internet. See RFC 2606 + for examples of domain names that are guaranteed not to be owned by anyone. + + * Lines 5, 9, 10: This provides the mapping from "your-login- + name@hostname.localdomain" to "your-account@your-isp.com". This part is + required. + + * Lines 7, 12, 13: Deliver mail for "your-account@your-isp.com" locally, + instead of sending it to the ISP. This part is not required but is + convenient. + diff --git a/postfix/README_FILES/TUNING_README b/postfix/README_FILES/TUNING_README new file mode 100644 index 000000000..0eff51856 --- /dev/null +++ b/postfix/README_FILES/TUNING_README @@ -0,0 +1,443 @@ + PPoossttffiixx PPeerrffoorrmmaannccee TTuunniinngg + +------------------------------------------------------------------------------- + +PPuurrppoossee ooff PPoossttffiixx ppeerrffoorrmmaannccee ttuunniinngg + +The hints and tips in this document help you improve the performance of Postfix +systems that already work. If your Postfix system is unable to receive or +deliver mail, then you need to solve those problems first, using the +DEBUG_README document as guidance. + +For tuning external content filter performance, first read the respective +information in the FILTER_README and SMTPD_PROXY_README documents. Then make +sure to avoid latency in the content filter code. As much as possible avoid +performing queries against external data sources with a high or highly variable +delay. Your content filter will run with a small concurrency to avoid CPU/ +memory starvation, and if any latency creeps in, content filter throughput will +suffer. High volume environments should avoid RBL lookups, complex database +queries and so on. + +Topics on mail receiving performance: + + * General mail receiving performance tips + * Doing more work with your SMTP server processes + * Slowing down SMTP clients that make many errors + * Measures against clients that make too many connections + +Topics on mail delivery performance: + + * General mail delivery performance tips + * Tuning the frequency of deferred mail delivery attempts + * Tuning the number of simultaneous deliveries + * Tuning the number of recipients per delivery + +Other Postfix performance tuning topics: + + * Tuning the number of Postfix processes + * Tuning the number of open files or sockets + +The following tools can be used to measure mail system performance under +artificial loads. They are normally not installed with Postfix. + + * smtp-source, SMTP/LMTP message generator + * smtp-sink, SMTP/LMTP message dump + * qmqp-source, QMQP message generator + * qmqp-sink, QMQP message dump + +GGeenneerraall mmaaiill rreecceeiivviinngg ppeerrffoorrmmaannccee ttiippss + + * Read and understand the maildrop queue, incoming queue, and active queue + discussions in the QSHAPE_README document. + + * Run a local name server to reduce slow-down due to DNS lookups. If you run + multiple Postfix systems, point each local name server to a shared + forwarding server to reduce the number of lookups across the upstream + network link. + + * Eliminate unnecessary LDAP lookups, by specifying a domain filter. This + eliminates lookups for addresses in remote domains, and eliminates lookups + of partial addresses. See ldap_table(5) for details. + +When Postfix responds slowly to SMTP clients: + + * Look for obvious signs of trouble as described in the DEBUG_README + document, and eliminate those problems first. + + * Turn off your header_checks and body_checks patterns and see if the problem + goes away. + + * Turn off chroot operation as described in the DEBUG_README document and see + if the problem goes away. + + * If Postfix logs the SMTP client as "unknown" then you have a name service + problem: the name server is bad, or the resolv.conf file contains bad + information, or some packet filter is blocking the DNS requests or replies. + + * If the number of smtpd(8) processes has reached the process limit as + specified in master.cf, new SMTP clients must wait until a process becomes + available. Increase the number of processes if memory permits. See the + instructions given under "Tuning the number of Postfix processes". + +DDooiinngg mmoorree wwoorrkk wwiitthh yyoouurr SSMMTTPP sseerrvveerr pprroocceesssseess + +With Postfix versions 2.0 and earlier, the smtpd(8) server pauses before +reporting an error to an SMTP client. The idea is called tar pitting. However, +these delays also slow down Postfix. When the smtpd(8) server replies slowly, +sessions take more time, so that more smtpd(8) server processes are needed to +handle the load. When your Postfix smtpd(8) server process limit is reached, +new clients must wait until a server process becomes available. This means that +all clients experience poor performance. + +You can speed up the handling of smtpd(8) server error replies by turning off +the delay: + + /etc/postfix/main.cf: + # Not needed with Postfix 2.1 + smtpd_error_sleep_time = 0 + +With the above setting, Postfix 2.0 and earlier can serve more SMTP clients +with the same number SMTP server processes. The next section describes how +Postfix deals with clients that make a large number of errors. + +SSlloowwiinngg ddoowwnn SSMMTTPP cclliieennttss tthhaatt mmaakkee mmaannyy eerrrroorrss + +The Postfix smtpd(8) server maintains a per-session error count. The error +count is reset when a message is transferred successfully, and is incremented +when a client request is unrecognized or unimplemented, when a client request +violates access restrictions, or when some other error happens. + +As the per-session error count increases, the smtpd(8) server changes behavior +and begins to insert delays into the responses. The idea is to slow down a run- +away client in order to limit resource usage. The behavior is Postfix version +dependent. + +IMPORTANT: These delays slow down Postfix, too. When too much delay is +configured, the number of simultaneous SMTP sessions will increase until it +reaches the smtpd(8) server process limit, and new SMTP clients must wait until +an smtpd(8) server process becomes available. + +Postfix version 2.1 and later: + + * When the error count reaches $smtpd_soft_error_limit (default: 10), the + Postfix smtpd(8) server delays all non-error and error responses by + $smtpd_error_sleep_time seconds (default: 1 second). + + * When the error count reaches $smtpd_hard_error_limit (default: 20) the + Postfix smtpd(8) server breaks the connection. + +Postfix version 2.0 and earlier: + + * When the error count is less than $smtpd_soft_error_limit (default: 10) the + Postfix smtpd(8) server delays all error replies by $smtpd_error_sleep_time + (1 second with Postfix 2.0, 5 seconds with Postfix 1.1 and earlier). + + * When the error count reaches $smtpd_soft_error_limit, the Postfix smtpd(8) + server delays all responses by "error count" seconds or + $smtpd_error_sleep_time, whichever is more. + + * When the error count reaches $smtpd_hard_error_limit (default: 20) the + Postfix smtpd(8) server breaks the connection. + +MMeeaassuurreess aaggaaiinnsstt cclliieennttss tthhaatt mmaakkee ttoooo mmaannyy ccoonnnneeccttiioonnss + +Note: this feature is not included with Postfix version 2.1. + +The Postfix smtpd(8) server can limit the number of simultaneous connections +from the same SMTP client, as well as the number of connections that a client +is allowed to make per unit time. These statistics are maintained by the anvil +(8) server (translation: if anvil(8) breaks, then connection limits stop +working). + +IMPORTANT: These limits are designed to protect the smtpd(8) server against +flagrant abuse. Do not use these limits to regulate legitimate traffic: mail +will suffer grotesque delays if you do so. + + * An SMTP client may make up to $smtpd_client_connection_count_limit + simultaneous connections (default: 50). This is half the default process + limit. + + * An SMTP client may make up to $smtpd_client_connection_rate_limit + connections per unit time (default: no limit). + + * These limits are not applied to SMTP clients in the networks specified with + $smtpd_client_connection_limit_exceptions (default: clients in $mynetworks + may make an unlimited number of connections). + + * The anvil_rate_time_unit parameter specifies the time unit over which + client connection rates are computed (default: 60s). + +GGeenneerraall mmaaiill ddeelliivveerryy ppeerrffoorrmmaannccee ttiippss + + * Read and understand the maildrop queue, incoming queue, active queue and + deferred queue discussions in the QSHAPE_README document. + + * In case of slow delivery, run the qshape tool as described in the + QSHAPE_README document. + + * Submit multiple recipients per message instead of submitting messages with + only a few recipients. + + * Submit mail via SMTP instead of /usr/sbin/sendmail. You may have to adjust + the smtpd_recipient_limit parameter setting. + + * Don't overwhelm the disk with mail submissions. Optimize the mail + submission rate by tuning the number of parallel submissions and/or by + tuning the Postfix in_flow_delay parameter setting. + + * Run a local name server to reduce slow-down due to DNS lookups. If you run + multiple Postfix systems, point each local name server to a shared + forwarding server to reduce the number of lookups across the upstream + network link. + + * Reduce the smtp_connect_timeout and smtp_helo_timeout values so that + Postfix does not waste lots of time connecting to non-responding smtpd(8) + servers. + + * Use a dedicated mail delivery transport for problematic destinations, with + reduced timeouts and with adjusted concurrency. See "Tuning the number of + simultaneous deliveries" below. + + * Use a fallback_relay host for mail that cannot be delivered upon the first + attempt. This "graveyard" machine can use shorter retry times for difficult + to reach destinations. See "Tuning the frequency of deferred mail delivery + attempts" below. + + * Speed up disk updates with a large (64MB) persistent write cache. This + allows disk updates to be sorted for optimal access speed without + compromising file system integrity when the system crashes. + + * Use a solid-state disk (a persistent RAM disk). This is an expensive + solution that should be used in combination with short SMTP timeouts and a + fallback_relay "graveyard" machine that delivers mail for problem + destinations. + +TTuunniinngg tthhee nnuummbbeerr ooff ssiimmuullttaanneeoouuss ddeelliivveerriieess + +Although Postfix can be configured to run 1000 SMTP client processes at the +same time, it is rarely desirable that it makes 1000 simultaneous connections +to the same remote system. For this reason, Postfix has safety mechanisms in +place to avoid this so-called "thundering herd" problem. + +The Postfix queue manager implements the analog of the TCP slow start flow +control strategy: when delivering to a site, send a small number of messages +first, then increase the concurrency as long as all goes well; reduce +concurrency in the face of congestion. + + * The initial_destination_concurrency parameter (default: 5) controls how + many messages are initially sent to the same destination before adapting + delivery concurrency. Of course, this setting is effective only as long as + it does not exceed the process limit and the destination concurrency limit + for the specific mail transport channel. + + * The default_destination_concurrency_limit parameter (default: 20) controls + how many messages may be sent to the same destination simultaneously. You + can override this setting for specific message delivery transports by + taking the name of the master.cf entry and appending + "_destination_concurrency_limit". + +Examples of transport specific concurrency limits are: + + * The local_destination_concurrency_limit parameter (default: 2) controls how + many messages are delivered simultaneously to the same local recipient. The + recommended limit is low because delivery to the same mailbox must happen + sequentially, so massive parallelism is not useful. Another good reason to + limit delivery concurrency to the same recipient: if the recipient has an + expensive shell command in her .forward file, or if the recipient is a + mailing list manager, you don't want to run too many instances of those + processes the same time. + + * The default smtp_destination_concurrency_limit of 20 seems enough to + noticeably load a system without bringing it to its knees. Be careful when + changing this to a much larger number. + +The above default values of the concurrency limits work well in a broad range +of situations. Knee-jerk changes to these parameters in the face of congestion +can actually make problems worse. Specifically, large destination concurrencies +should never be the default. They should be used only for transports that +deliver mail to a small number of high volume domains. + +A common situation where high concurrency is called for is on gateways relaying +a high volume of mail from between the Internet and an intranet mail +environment. Approximately half the mail (assuming equal volumes inbound and +outbound) will be destined for the internal mail hubs. Since the internal mail +hubs will be receiving all external mail exclusively from the gateway, it is +reasonable to configure the gateway to make greater demands on the capacity of +the internal SMTP servers. + +The tuning of the inbound concurrency limits need not be trial and error. A +high volume capable mailhub should be able to easily handle 50 or 100 (rather +than the default 20) simultaneous connections, especially if the gateway +forwards to multiple MX hosts. When all MX hosts are up and accepting +connections in a timely fashion, throughput will be high. If any MX host is +down and completely unresponsive, the average connection latency rises to at +least 1/N * $smtp_connection_timeout, if there are N MX hosts. This limits +throughput to at most the destination concurrency * N / +$smtp_connection_timeout. + +For example, with a destination concurrency of 100 and 2 MX hosts, each host +will handle up to 50 simultaneous connections. If one MX host is down and the +default SMTP connection timeout is 30s, the throughput limit is 100 * 2 / 30 ~= +6 messages per second. This suggests that high volume destinations with good +connectivity and multiple MX hosts need a lower connection timeout, values as +low as 5s or even 1s can be used to prevent congestion when one or more, but +not all MX hosts are down. + +If necessary, set a higher transport_destination_concurrency_limit (in main.cf +since this is a queue manager parameter) and a lower smtp_connection_timeout +(with a "-o" override in master.cf since this parameter has no per-transport +name) for the relay transport and any transports dedicated for specific high +volume destinations. + +TTuunniinngg tthhee nnuummbbeerr ooff rreecciippiieennttss ppeerr ddeelliivveerryy + +The default_destination_recipient_limit parameter (default: 50) controls how +many recipients a Postfix delivery agent will send with each copy of an email +message. You can override this setting for specific Postfix delivery agents. +For example, "uucp_destination_recipient_limit = 100" would limit the number of +recipients per UUCP delivery to 100. + +If an email message exceeds the recipient limit for some destination, the +Postfix queue manager breaks up the list of recipients into smaller lists. +Postfix will attempt to send multiple copies of the message in parallel. + +IMPORTANT: Be careful when increasing the recipient limit per message delivery; +some smtpd(8) servers abort the connection when they run out of memory or when +a hard recipient limit is reached, so that the message will never be delivered. + +The smtpd_recipient_limit parameter (default: 1000) controls how many +recipients the Postfix smtpd(8) server will take per delivery. The default +limit is more than any reasonable SMTP client would send. The limit exists to +protect the local mail system against a run-away client. + +TTuunniinngg tthhee ffrreeqquueennccyy ooff ddeeffeerrrreedd mmaaiill ddeelliivveerryy aatttteemmppttss + +When a Postfix delivery agent (smtp(8), local(8), etc.) is unable to deliver a +message it may blame the message itself, or it may blame the receiving party. + + * When the delivery agent blames the message, the queue manager gives the + queue file a time stamp into the future, so it won't be looked at for a + while. By default, the amount of time to cool down is the amount of time + that has passed since the message arrived. This results in so-called + exponential backoff behavior. + + * When the delivery agent blames the receiving party (for example a local + recipient user, or a remote host), the queue manager not only advances the + queue file time stamp, but also puts the receiving party on a "dead" list + so that it will be skipped for some amount of time. + +This process is governed by a bunch of little parameters. + + queue_run_delay (default: 1000 seconds) + How often the queue manager scans the queue for deferred mail. + minimal_backoff_time (default: 1000 seconds) + The minimal amount of time a message won't be looked at, and the + minimal amount of time to stay away from a "dead" destination. + maximal_backoff_time (default: 4000 seconds) + The maximal amount of time a message won't be looked at after a + delivery failure. + maximal_queue_lifetime (default: 5 days) + How long a message stays in the queue before it is sent back as + undeliverable. Specify 0 for mail that should be returned immediately + after the first unsuccessful delivery attempt. + bounce_queue_lifetime (default: 5 days, available with Postfix version 2.1 + and later) + How long a MAILER-DAEMON message stays in the queue before it is + considered undeliverable. Specify 0 for mail that should be tried only + once. + qmgr_message_recipient_limit (default: 20000) + The size of many in-memory queue manager data structures. Among others, + this parameter limits the size of the short-term, in-memory list of + "dead" destinations. Destinations that don't fit the list are not + added. + +IMPORTANT: If you increase the frequency of deferred mail delivery attempts, or +if you flush the deferred mail queue frequently, then you may find that Postfix +mail delivery performance actually becomes worse. The symptoms are as follows: + + * The active queue becomes saturated with mail that has delivery problems. + New mail enters the active queue only when an old message is deferred. This + is a slow process that usually requires timing out one or more SMTP + connections. + + * All available Postfix delivery agents become occupied trying to connect to + unreachable sites etc. New mail has to wait until a delivery agent becomes + available. This is a slow process that usually requires timing out one or + more SMTP connections. + +When mail is being deferred frequently, fixing the problem is always better +than increasing the frequency of delivery attempts. However, if you can control +only the delivery attempt frequency, consider using a dedicated fallback_relay +"graveyard" machine for bad destinations so that they do not ruin the +performance of normal mail deliveries. + +TTuunniinngg tthhee nnuummbbeerr ooff PPoossttffiixx pprroocceesssseess + +The default_process_limit configuration parameter gives direct control over how +many daemon processes Postfix will run. As of Postfix 2.0 the default limit is +100 smtp client processes, 100 smtp server processes, and so on. This may +overwhelm systems with little memory, as well as networks with low bandwidth. + +You can change the global process limit by specifying a non-default +default_process_limit in the main.cf file. For example, to run up to 10 smtp +client processes, 10 smtp server processes, and so on: + + /etc/postfix/main.cf: + default_process_limit = 10 + +You need to execute "postfix reload" to make the change effective. The limits +are enforced by the Postfix master(8) daemon which does not automatically read +main.cf when it changes. + +You can override the process limit for specific Postfix daemons by editing the +master.cf file. For example, if you do not wish to receive 100 SMTP messages at +the same time, but do not want to change the process limits for local mail +deliveries, you could specify: + + /etc/postfix/master.cf: + # ==================================================================== + # service type private unpriv chroot wakeup maxproc command + args + # (yes) (yes) (yes) (never) (100) + # ==================================================================== + . . . + smtp inet n - - - 10 smtpd + . . . + +TTuunniinngg tthhee nnuummbbeerr ooff ooppeenn ffiilleess oorr ssoocckkeettss + +When Postfix opens too many files or sockets, processes will abort with fatal +errors, and the system may log "file table full" errors. + + * Reduce the number of processes as described under "Tuning the number of + Postfix processes" above. Fewer processes need fewer open files and + sockets. + + * Configure the kernel for more open files and sockets. The details are + extremely system dependent and change with the operating system version. Be + sure to verify the following information with your system tuning guide: + + o Some FreeBSD kernel parameters can be specified in /boot/loader.conf, + and some can be changed with sysctl commands. Which is which depends on + the version. + + kern.ipc.maxsockets="5000" + kern.ipc.nmbclusters="65536" + kern.maxproc="2048" + kern.maxfiles="16384" + kern.maxfilesperproc="16384" + + o Linux kernel parameters can be specified in /etc/sysctl.conf and can + also be changed with sysctl commands: + + fs.file-max=16384 + kernel.threads-max=2048 + + o Solaris kernel parameters can be specified in /etc/system, as described + in the Solaris FAQ entry titled "How can I increase the number of file + descriptors per process?" + + * set hard limit on file descriptors + set rlim_fd_max = 4096 + * set soft limit on file descriptors + set rlim_fd_cur = 1024 + diff --git a/postfix/README_FILES/ULTRIX_README b/postfix/README_FILES/ULTRIX_README index ef43fe6d0..98078d1d9 100644 --- a/postfix/README_FILES/ULTRIX_README +++ b/postfix/README_FILES/ULTRIX_README @@ -1,34 +1,45 @@ -To: wietse@porcupine.org (Wietse Venema) -Subject: postfix-19990317-pl05 on Ultrix4.3a -From: Christian von Roques -Date: 02 Jun 1999 18:44:34 +0200 -Message-ID: <87iu96wo0d.fsf_-_@scalar.pond.sub.org> +PPoossttffiixx aanndd UUllttrriixx -I've upgraded the MTA of our DECstation-3100 running Ultrix4.3a to -postfix-19990317-pl05 and am sending you the patches I needed to get -it running under Ultrix. +------------------------------------------------------------------------------- - ... +PPoossttffiixx oonn UUllttrriixx - o One of the bugs of Ultrix's /bin/sh is that shell-variables set in - arguments of `:' expand to garbage if expanded in here-documents. - Using a different shell helps. I needed to replace all calls of - ``sh .../makedefs'' by ``$(SHELL) .../makedefs'' in all the - Makefile.in and am now able to use +This document is probably only of historical value, because Ultrix version 4 +dates from the early 1990s. However, as long as Wietse keeps Postfix alive for +SunOS 4, it is likely to run on Ultrix 4 with very little change. Feedback is +welcome if anyone actually still uses Postfix on any version of Ultrix. - make SHELL=/bin/sh5 or zsh. +The source of this document is an email message by Christian von Roques that +was sent on Jun 2, 1999. - ... + I've upgraded the MTA of our DECstation-3100 running Ultrix4.3a to postfix- + 19990317-pl05 and am sending you the patches I needed to get it running + under Ultrix. - o Ultrix's FD_SET_SIZE is 4096, but getdtablesize() returns 64 by - default, if not increased when building a new kernel. getrlimit() - doesn't know RLIMIT_NOFILE. This makes event_init() always log - the warning: `could allocate space for only 64 open files'. + . . . - I just reduced the threshold from 256 to 64, but this is not good. - The initial problem still remains: How to disable this warning on - Ultrix without making the source ugly? + One of the bugs of Ultrix's /bin/sh is that shell-variables set in + arguments of `:' expand to garbage if expanded in here-documents. Using a + different shell helps. I needed to replace all calls of ``sh .../makedefs'' + by ``$(SHELL) .../makedefs'' in all the Makefile.in and am now able to use + ``make SHELL=/bin/sh5'' or zsh. + + . . . + + Ultrix's FD_SET_SIZE is 4096, but getdtablesize() returns 64 by default, if + not increased when building a new kernel. getrlimit() doesn't know + RLIMIT_NOFILE. This makes event_init() always log the warning: `could + allocate space for only 64 open files'. + + I just reduced the threshold from 256 to 64, but this is not good. The + initial problem still remains: How to disable this warning on Ultrix + without making the source ugly? + +To work around the first problem, all the Makefile.in files have been updated +to use `$(SHELL)' instead of `sh'. So you only need to supply a non-default +shell in order to eliminate Ultrix shell trouble. + +To work around the latter, util/sys_defs.h was updated for Ultrix, with a +default FD_SETSIZE of 100. This should be sufficient for a workstation. Even in +1999, no-one would run a major mail hub on Ultrix 4. -[I have updated util/sys_defs.h, and by default set FD_SETSIZE to -100. This should be sufficient for a workstation. No-one would -run a major mail hub on Ultrix 4. -- Wietse] diff --git a/postfix/README_FILES/UUCP_README b/postfix/README_FILES/UUCP_README index 6009a16c1..3fb457280 100644 --- a/postfix/README_FILES/UUCP_README +++ b/postfix/README_FILES/UUCP_README @@ -1,8 +1,121 @@ -In order to receive mail via UUCP, your system needs to have an -rmail command installed. A minimal rmail command can be found in -the "auxiliary/rmail" directory of the Postfix source code -distribution. Install the command, mode 755, in a place that can -be found by the UUCP "uuxqt" command. - -In order to send mail via UUCP, see html/faq.html in the Postfix -source code distribution, or http://www.postfix.org/faq.html. +PPoossttffiixx aanndd UUUUCCPP + +------------------------------------------------------------------------------- + +UUssiinngg UUUUCCPP oovveerr TTCCPP + +Despite a serious lack of sex-appeal, email via UUCP over TCP is a practical +option for sites without permanent Internet connection, and for sites without a +fixed IP address. For first-hand information, see the following guides: + + * Jim Seymour's guide for using UUCP over TCP at http://jimsun.LinxNet.com/ + jdp/uucp_over_tcp/index.html, + * Craig Sanders's guide for SSL-encrypted UUCP over TCP using stunnel at + http://taz.net.au/postfix/uucp/. + +Here's a graphical description of what this document is about: + + LAN to Internet + Local network <---> UUCP <--- UUCP ---> to UUCP <---> Internet + Gateway Gateway + +And here's the table of contents of this document: + + * Setting up a Postfix Internet to UUCP gateway + * Setting up a Postfix LAN to UUCP gateway + +SSeettttiinngg uupp aa PPoossttffiixx IInntteerrnneett ttoo UUUUCCPP ggaatteewwaayy + +Here is how to set up a machine that sits on the Internet and that forwards +mail to a LAN that is connected via UUCP. See the LAN to UUCP gateway section +for the other side of the story. + + * You need an rrmmaaiill program that extracts the sender address from mail that + arrives via UUCP, and that feeds the mail into the Postfix sseennddmmaaiill + command. Most UNIX systems come with an rrmmaaiill utility. If you're in a + pinch, try the one bundled with the Postfix source code in the aauuxxiilliiaarryy// + rrmmaaiill directory. + + * Define a pipe(8) based mail delivery transport for delivery via UUCP: + + /etc/postfix/master.cf: + uucp unix - n n - - pipe + flags=F user=uucp argv=uux -r -n -z -a$sender - $nexthop!rmail + ($recipient) + + This runs the uuuuxx command to place outgoing mail into the UUCP queue after + replacing $nexthop by the next-hop hostname (the receiving UUCP host) and + after replacing $recipient by the recipients. The pipe(8) delivery agent + executes the uuuuxx command without assistance from the shell, so there are no + problems with shell meta characters in command-line parameters. + + * Specify that mail for example.com, should be delivered via UUCP, to a host + named uucp-host: + + /etc/postfix/transport: + example.com uucp:uucp-host + .example.com uucp:uucp-host + + See the transport(5) manual page for more details. + + * Execute the command "ppoossttmmaapp //eettcc//ppoossttffiixx//ttrraannssppoorrtt" whenever you change + the ttrraannssppoorrtt file. + + * Enable ttrraannssppoorrtt table lookups: + + /etc/postfix/main.cf: + transport_maps = hash:/etc/postfix/transport + + Specify ddbbmm instead of hhaasshh if your system uses ddbbmm files instead of ddbb + files. To find out what map types Postfix supports, use the command + "ppoossttccoonnff --mm". + + * Add example.com to the list of domains that your site is willing to relay + mail for. + + /etc/postfix/main.cf: + relay_domains = example.com ...other relay domains... + + See the relay_domains configuration parameter description for details. + + * Execute the command "ppoossttffiixx rreellooaadd" to make the changes effective. + +SSeettttiinngg uupp aa PPoossttffiixx LLAANN ttoo UUUUCCPP ggaatteewwaayy + +Here is how to relay mail from a LAN via UUCP to the Internet. See the Internet +to UUCP gateway section for the other side of the story. + + * You need an rrmmaaiill program that extracts the sender address from mail that + arrives via UUCP, and that feeds the mail into the Postfix sseennddmmaaiill + command. Most UNIX systems come with an rrmmaaiill utility. If you're in a + pinch, try the one bundled with the Postfix source code in the aauuxxiilliiaarryy// + rrmmaaiill directory. + + * Specify that all remote mail must be sent via the uuuuccpp mail transport to + your UUCP gateway host, say, uucp-gateway: + + /etc/postfix/main.cf: + relayhost = uucp-gateway + default_transport = uucp + + Postfix 2.0 and later also allows the following more succinct form: + + /etc/postfix/main.cf: + default_transport = uucp:uucp-gateway + + * Define a pipe(8) based message delivery transport for mail delivery via + UUCP: + + /etc/postfix/master.cf: + uucp unix - n n - - pipe + flags=F user=uucp argv=uux -r -n -z -a$sender - $nexthop!rmail + ($recipient) + + This runs the uuuuxx command to place outgoing mail into the UUCP queue. It + substitutes the next-hop hostname (uucp-gateway, or whatever you specified) + and the recipients before executing the command. The uuuuxx command is + executed without assistance from the shell, so there are no problems with + shell meta characters. + + * Execute the command "ppoossttffiixx rreellooaadd" to make the changes effective. + diff --git a/postfix/README_FILES/VERP_README b/postfix/README_FILES/VERP_README index 45059a703..4d57419f2 100644 --- a/postfix/README_FILES/VERP_README +++ b/postfix/README_FILES/VERP_README @@ -1,142 +1,159 @@ -[Note: this document still needs more examples] +PPoossttffiixx VVEERRPP HHoowwttoo -Postfix VERP support -==================== +------------------------------------------------------------------------------- -Postfix supports variable envelope return path addresses on request. -When VERP style delivery is requested, each recipient of a message -receives a customized copy of the message, with his/her own recipient -address encoded in the envelope sender address. +PPoossttffiixx VVEERRPP ssuuppppoorrtt -For example, when VERP style delivery is requested, Postfix delivers -mail from owner-listname@origin for a recipient user@domain, with -a sender address that encodes the recipient as follows: +Postfix versions 1.1 and later support variable envelope return path addresses +on request. When VERP style delivery is requested, each recipient of a message +receives a customized copy of the message, with his/her own recipient address +encoded in the envelope sender address. + +For example, when VERP style delivery is requested, Postfix delivers mail from +"owner-listname@origin" for a recipient "user@domain", with a sender address +that encodes the recipient as follows: owner-listname+user=domain@origin -Thus, undeliverable mail can reveal the undeliverable recipient -address without requiring the list owner to parse bounce messages. +Thus, undeliverable mail can reveal the undeliverable recipient address without +requiring the list owner to parse bounce messages. + +The VERP concept was popularized by the qmail MTA and by the ezmlm mailing list +manager. See http://cr.yp.to/proto/verp.txt for the ideas behind this concept. + +Topics covered in this document: + + * Postfix VERP configuration parameters + * Using VERP with majordomo etc. mailing lists + * VERP support in the Postfix SMTP server + * VERP support in the Postfix sendmail command + * VERP support in the Postfix QMQP server -The VERP concept was popularized by the qmail MTA and by the ezmlm -mailing list manager. +PPoossttffiixx VVEERRPP ccoonnffiigguurraattiioonn ppaarraammeetteerrss -The whole process is controlled by four configuration parameters. +With Postfix, the whole process is controlled by four configuration parameters. -- default_verp_delimiters (default value: +=) controls what VERP -delimiter characters Postfix uses when VERP style delivery is -requested but no explicit delimiters are specified. +default_verp_delimiters (default value: +=) + What VERP delimiter characters Postfix uses when VERP style delivery is + requested but no explicit delimiters are specified. -- verp_delimiter_filter (default: -+=) controls what characters -Postfix accepts as VERP delimiter characters on the sendmail command -line and in SMTP commands. Many characters must not be used as VERP -delimiter characters, either because they already have a special -meaning in email addresses (such as the @ or the %), because they -are used as part of a username or domain name (such as alphanumerics), -or because they are non-ASCII or control characters. And who knows, -some characters may tickle bugs in vulnerable software. +verp_delimiter_filter (default: -+=) + What characters Postfix accepts as VERP delimiter characters on the + sendmail command line and in SMTP commands. Many characters must not be + used as VERP delimiter characters, either because they already have a + special meaning in email addresses (such as the @ or the %), because they + are used as part of a username or domain name (such as alphanumerics), or + because they are non-ASCII or control characters. And who knows, some + characters may tickle bugs in vulnerable software, and we would not want + that to happen. -- smtpd_authorized_verp_clients (default value: none) controls -what SMTP clients are allowed to request VERP style delivery. -Exceptions: the Postfix QMQP server uses its own access control -mechanism, and local submission (via /usr/sbin/sendmail etc.) is -always authorized. To authorize a host, list its name, IP address, -subnet (net/mask) or parent .domain. +smtpd_authorized_verp_clients (default value: none) + What SMTP clients are allowed to request VERP style delivery. The Postfix + QMQP server uses its own access control mechanism, and local submission + (via /usr/sbin/sendmail etc.) is always authorized. To authorize a host, + list its name, IP address, subnet (net/mask) or parent .domain. -- disable_verp_bounces (default: no) controls if Postfix sends one -bounce report for multi-recipient VERP mail, or one bounce report -per recipient. The default, one per recipient, is what ezmlm needs. + With Postfix versions 1.1 and 2.0, this parameter is called + authorized_verp_clients (default: $mynetworks). -Using VERP with majordomo etc. mailing lists -============================================ +disable_verp_bounces (default: no) + if Postfix sends one bounce report for multi-recipient VERP mail, or one + bounce report per recipient. The default, one per recipient, is what ezmlm + needs. -In order to make VERP useful with majordomo etc. mailing lists, -you would configure the list manager to submit mail according -to one of the following two forms: +UUssiinngg VVEERRPP wwiitthh mmaajjoorrddoommoo eettcc.. mmaaiilliinngg lliissttss - sendmail -V -f owner-listname other-arguments... +In order to make VERP useful with majordomo etc. mailing lists, you would +configure the list manager to submit mail according to one of the following two +forms: - sendmail -V+= -f owner-listname other-arguments... + % sendmail -V -f owner-listname other-arguments... -The first form uses the default main.cf VERP delimiter characters. -The second form allows you to explicitly specify the VERP delimiter -characters. The example shows the recommended values. + % sendmail -V+= -f owner-listname other-arguments... -This text assumes that you have set up an owner-listname alias that -routes undeliverable mail to a real person: +The first form uses the default main.cf VERP delimiter characters. The second +form allows you to explicitly specify the VERP delimiter characters. The +example shows the recommended values. + +This text assumes that you have set up an owner-listname alias that routes +undeliverable mail to a real person: /etc/aliases: - owner-listname: yourname+listname + owner-listname: yourname+listname -In order to process bounces we are going to make extensive use of -address extension tricks. +In order to process bounces we are going to make extensive use of address +extension tricks. -You need to tell Postfix that + is the separator between an address -and its optional address extension, that address extensions are -appended to .forward file names, and that address extensions are -to be discarded when doing alias expansions: +You need to tell Postfix that + is the separator between an address and its +optional address extension, that address extensions are appended to .forward +file names, and that address extensions are to be discarded when doing alias +expansions: /etc/postfix/main.cf: - recipient_delimiter = + - forward_path = $home/.forward${recipient_delimiter}${extension},$home/.forward - propagate_unmatched_extensions = canonical, virtual + recipient_delimiter = + + forward_path = $home/.forward${recipient_delimiter}${extension}, + $home/.forward + propagate_unmatched_extensions = canonical, virtual (the last two parameter settings are default settings). -You need to set up a file named .forward+listname with the commands -that process all the mail that is sent to the owner-listname address: +You need to set up a file named .forward+listname with the commands that +process all the mail that is sent to the owner-listname address: - ~/.forward+listname: - "|/some/where/command ..." + ~/.forward+listname: + "|/some/where/command ..." -With this set up, undeliverable mail for user@domain will be returned -to the following address: +With this set up, undeliverable mail for user@domain will be returned to the +following address: owner-listname+user=domain@your.domain -which is processed by the command in your .forward+listname file. -The message should contain, among others, a To: header with the -encapsulated recipient sender address: +which is processed by the command in your .forward+listname file. The message +should contain, among others, a To: header with the encapsulated recipient +sender address: To: owner-listname+user=domain@your.domain -It is left as an exercise for the reader to parse the To: header -line and to pull out the user=domain part from the recipient address. +It is left as an exercise for the reader to parse the To: header line and to +pull out the user=domain part from the recipient address. -VERP support in the Postfix SMTP server -======================================= +VVEERRPP ssuuppppoorrtt iinn tthhee PPoossttffiixx SSMMTTPP sseerrvveerr -The Postfix SMTP server has a new command XVERP to enable VERP -style delivery. The syntax allows two forms: +The Postfix SMTP server implements a command XVERP to enable VERP style +delivery. The syntax allows two forms: MAIL FROM: XVERP MAIL FROM: XVERP=+= -The first form uses the default main.cf VERP delimiters, the second -form overrides them explicitly. The values shown are the recommended -ones. +The first form uses the default main.cf VERP delimiters, the second form +overrides them explicitly. The values shown are the recommended ones. -VERP support in the Postfix sendmail command -============================================ +VVEERRPP ssuuppppoorrtt iinn tthhee PPoossttffiixx sseennddmmaaiill ccoommmmaanndd -The Postfix sendmail command has a -V flag to request VERP style -delivery. Specify one of the following two forms: +The Postfix sendmail command has a -V flag to request VERP style delivery. +Specify one of the following two forms: - sendmail -V -f owner-listname .... + % sendmail -V -f owner-listname .... - sendmail -V+= -f owner-listname .... + % sendmail -V+= -f owner-listname .... -The first form uses the default main.cf VERP delimiters, the second -form overrides them explicitly. The values shown are the recommended -ones. +The first form uses the default main.cf VERP delimiters, the second form +overrides them explicitly. The values shown are the recommended ones. -VERP support in the Postfix QMQP server -======================================= +VVEERRPP ssuuppppoorrtt iinn tthhee PPoossttffiixx QQMMQQPP sseerrvveerr -When the Postfix QMQP server receives mail with an envelope sender -address of the form: +When the Postfix QMQP server receives mail with an envelope sender address of +the form: listname-@your.domain-@[] -Postfix generates sender addresses listname-user=domain@your.domain, -using "-=" as the VERP delimiters because qmail/ezmlm expect this. +Postfix generates sender addresses "listname-user=domain@your.domain", using "- +=" as the VERP delimiters because qmail/ezmlm expect this. + +More generally, a sender address of "prefix@origin-@[]" requests VERP style +delivery with sender addresses of the form "prefixuser=domain@origin". However, +Postfix allows only VERP delimiters that are specified with the +verp_delimiter_filter parameter. In particular, the "=" delimiter is required +for qmail compatibility (see the qmail addresses(5) manual page for details). + diff --git a/postfix/README_FILES/VIRTUAL_README b/postfix/README_FILES/VIRTUAL_README index fc65ddf3a..25d634a5e 100644 --- a/postfix/README_FILES/VIRTUAL_README +++ b/postfix/README_FILES/VIRTUAL_README @@ -1,375 +1,478 @@ -This document describes the Postfix virtual delivery agent. See -the HOSTING_README file for an overview of all methods to host -multiple domains with one Postfix system. +PPoossttffiixx VViirrttuuaall DDoommaaiinn HHoossttiinngg HHoowwttoo -The virtual delivery was created by Andrew McNamara and adapted by -Xavier Beaudouin. It was merged with mainstream Postfix by Wietse. +------------------------------------------------------------------------------- -Purpose of this software -======================== +PPuurrppoossee ooff tthhiiss ddooccuummeenntt -You can use the virtual delivery agent for mailbox delivery of some -or all domains that are handled by a machine. +This document requires Postfix version 2.0 or later. -With the virtual delivery agent, every recipient adress can have -its own mailbox. There is no translation from recipient addresses -into other mail addresses. +This document gives an overview of how Postfix can be used for hosting multiple +Internet domains, both for final delivery on the machine itself and for the +purpose of forwarding to destinations elsewhere. -This mechanism is different from virtual alias domains (described -in virtual(5)). Those are implemented by translating every recipient -address into a different address. +The text not only describes delivery mechanisms that are built into Postfix, +but also gives pointers for using non-Postfix mail delivery software. -This an updated version of what Andrew McNamara wrote when he made -the virtual delivery agent available. +The following topics are covered: -"This code is designed for ISP's who offer virtual mail hosting. -It looks up the user mailbox location, uid and gid via separate -maps, and the mailbox location map can specify either mailbox or -maildir delivery (controlled by trailing slash on mailbox name). + * Canonical versus hosted versus other domains + * Local files versus network databases + * As simple as can be: shared domains, UNIX system accounts + * Postfix virtual ALIAS example: separate domains, UNIX system accounts + * Postfix virtual MAILBOX example: separate domains, non-UNIX accounts + * Non-Postfix mailbox store: separate domains, non-UNIX accounts + * Mail forwarding domains + * Mailing lists + * Autoreplies -The agent does support user+foo address extensions, but does not -support aliases or .forward files (use the virtual table instead), -and therefore doesn't support file or program aliases. This choice -was made to simplify and streamline the code (it allowed me to -dispense with 70% of local's code - mostly the bits that are a -security headache) - if you need this functionality, this agent -isn't for you. +CCaannoonniiccaall vveerrssuuss hhoosstteedd vveerrssuuss ootthheerr ddoommaaiinnss -It also doesn't support writing to a common spool as root and then -chowning the mailbox to the user - I felt this functionality didn't -fit with my overall aims." +Most Postfix systems are ffiinnaall ddeessttiinnaattiioonn for only a few domain names. These +include the hostnames and [the IP addresses] of the machine that Postfix runs +on, and sometimes also include the parent domain of the hostname. The remainder +of this document will refer to these domains as the canonical domains. They are +usually implemented with the Postfix local domain address class, as defined in +the ADDRESS_CLASS_README file. -[End of Andrew McNamara's words] +Besides the canonical domains, Postfix can be configured to be ffiinnaall +ddeessttiinnaattiioonn for any number of additional domains. These domains are called +hosted, because they are not directly associated with the name of the machine +itself. Hosted domains are usually implemented with the virtual alias domain +address class and/or with the virtual mailbox domain address class, as defined +in the ADDRESS_CLASS_README file. -The result is the most secure local delivery agent that you will -find with Postfix. +But wait! There is more. Postfix can be configured as a backup MX host for +other domains. In this case Postfix is nnoott tthhee ffiinnaall ddeessttiinnaattiioonn for those +domains. It merely queues the mail when the primary MX host is down, and +forwards the mail when the primary MX host becomes available. This function is +implemented with the relay domain address class, as defined in the +ADDRESS_CLASS_README file. -This delivery agent requires three different lookup tables in order -to define its recipients as (mailbox path, user ID, group ID). This -is because Postfix table lookups can't return multiple results. +Finally, Postfix can be configured as a transit host for sending mail across +the internet. Obviously, Postfix is not final destination for such mail. This +function is available only for authorized clients and/or users, and is +implemented by the default domain address class, as defined in the +ADDRESS_CLASS_README file. -If your virtual mailboxes are all owned by the same user/group ID, -just specify "static" maps that always return the same result. See -below for examples. +LLooccaall ffiilleess vveerrssuuss nneettwwoorrkk ddaattaabbaasseess -If your virtual mailboxes must be owned by different user/group -IDs, and if it is too inconvenient for you to maintain three parallel -tables, use an LDAP or MYSQL database (or generate the three parallel -tables from one common template). +The examples in this text use table lookups from local files such as DBM or +berkeley DB. These are easy to debug with the ppoossttmmaapp command: -Configuration parameters -======================== + Example: postmap -q info@example.com hash:/etc/postfix/virtual -virtual_mailbox_base +See the documentation in LDAP_README, MYSQL_README and PGSQL_README for how to +replace local files by databases. The reader is strongly advised to make the +system work with local files before migrating to network databases, and to use +the ppoossttmmaapp command to verify that network database lookups produce the exact +same results as local file lookup. - Specifies a path that is prepended to all mailbox paths. This - is a safety measure to ensure an that out of control map doesn't - litter the filesystem with mailboxes (or worse). While it could - be set to "/", this isn't recommended. + Example: postmap -q info@example.com ldap:/etc/postfix/virtual.cf -virtual_mailbox_domains +AAss ssiimmppllee aass ccaann bbee:: sshhaarreedd ddoommaaiinnss,, UUNNIIXX ssyysstteemm aaccccoouunnttss - Specifies the list of domains that should be delivered to the - $virtual_transport delivery agent (default: virtual). As of - version 2.0, Postfix is smart enough that you don't have to - list every virtual domain in a Postfix transport map. +The simplest method to host an additional domain is to add the domain name to +the domains listed in the Postfix mydestination configuration parameter, and to +add the user names to the UNIX password file. -virtual_mailbox_maps +This approach makes no distinction between canonical and hosted domains. Each +username can receive mail in every domain. - Recipients are looked up in this map to determine the path to - their mailbox. If the returned path ends in a slash ("/"), - maildir-style delivery is carried out, otherwise the path is - assumed to specify a mailbox file. The virtual_mailbox_base - directory is unconditionally prepended to this path. If the - recipient is not found the mail is bounced. - - In a lookup table, specify a left-hand side of @domain.tld to - match any user in the specified domain that does not have her - own user@domain.tld entry. While searching a lookup table, an - extended address (user+foo@domain.tld) is searched before the - bare address (user@domain.tld). - - If a recipient is not found the mail is returned to the sender. - - Regular expression maps are allowed. For security reasons, - regular expression substitution of $1 etc. is disallowed, - because that would open a security hole. - - The mail administrator is expected to create and chown recipient - mailbox files or maildir directories ahead of time. - -virtual_minimum_uid - - Specifies a minimum uid that will be accepted as a return from - a virtual_uid_maps lookup. Returned values less than this will - be rejected, and the message will be deferred. - -virtual_uid_maps - - Recipients are looked up in this map to determine the UID (owner - privileges) to be used when writing to the target mailbox. - - In a lookup table, specify a left-hand side of @domain.tld to - match any user in the specified domain that does not have a - specific user@domain.tld entry. While searching a lookup table, - an address extension (user+foo@domain.tld) is ignored. - - Regular expression maps are allowed. For security reasons, - regular expression substitution of $1 etc. is disallowed, - because that would open a security hole. - - Specify a static map if all mailboxes should be owned by the same - UID. For example, to specify that all mailboxes are owned by the - UID 5000, specify: - - virtual_uid_maps = static:5000 - -virtual_gid_maps - - Recipients are looked up in this map to determine the GID (group - privileges) to be used when writing to the target mailbox. - - In a lookup table, specify a left-hand side of @domain.tld to - match any user in the specified domain that does not have a - specific user@domain.tld entry. While searching a lookup table, - an address extension (user+foo@domain.tld) is ignored. - - Regular expression maps are allowed. For security reasons, - regular expression substitution of $1 etc. is disallowed, - because that would open a security hole. - - Specify a static map if all mailboxes should be owned by the same - GID. For example, to specify that all mailboxes are owned by the - GID 5000, specify: - - virtual_gid_maps = static:5000 - -virtual_mailbox_lock - - This setting is ignored in case of maildir delivery. - - Locking method to use when updating a mailbox. Defaults to - fcntl or flock depending on the system. Depending on the POP - or IMAP server you may have to specify dotlock locking, which - requires that the recipient UID or GID has write access to the - parent directory of the mailbox file. - - Use the "postconf -l" command to find out what locking methods - Postfix supports on your system. - -virtual_mailbox_limit - - An upper limit on the size of a mailbox file or maildir file. - -Example 1: using the virtual delivery agent for all local mail -============================================================== - -This example does not use the Postfix local delivery agent at all. -With this configuration Postfix does no alias expansion, no .forward -file expansion, no lookups of recipients in /etc/passwd, and allows -but ignores user+foo address extensions. - -Instead of "hash" specify "dbm" or "btree", depending on your system -type. The command "postconf -m" displays possible lookup table -types. +In the examples we will use "example.com" as the domain that is being hosted on +the local Postfix machine. /etc/postfix/main.cf: - # Don't send mail to the local delivery agent. - mydestination = - - # All domains that are listed in $virtual_mailbox_domains - # are delivered via $virtual_transport, which is the virtual - # delivery agent by default. - virtual_mailbox_domains = - $myhostname localhost.$mydomain virtual1.domain virtual2.domain - - virtual_transport = virtual - virtual_mailbox_base = /var/mail/vhosts - virtual_mailbox_maps = hash:/etc/postfix/vmailbox - virtual_minimum_uid = 100 - virtual_uid_maps = hash:/etc/postfix/vuid - virtual_gid_maps = hash:/etc/postfix/vgid - -Define a virtual delivery agent if the entry doesn't already exist: - - /etc/postfix/master.cf: - virtual unix - n n - - virtual - -Example recipients, one UNIX-style mailbox, one qmail-style maildir: - - /etc/postfix/vmailbox: - test1@virtual1.domain test1 - test2@virtual2.domain test2/ - - /etc/postfix/vuid: - test1@virtual1.domain 5001 - test2@virtual2.domain 5002 - - /etc/postfix/vgid: - test1@virtual1.domain 5001 - test2@virtual2.domain 5002 - -Execute something like the following commands for each mailbox recipient: - - # touch /var/mail/vhosts/test1 - # chown 5001:5001 /var/mail/vhosts/test1 - -Execute something like the following commands for each maildir recipient: - - # mkdir /var/mail/vhosts/test2 - # chown 5002:5002 /var/mail/vhosts/test2 - -Be sure to make the necessary entries for root@$myhostname, -postmaster@$myhostname and for any other necessary addresses. - -Example 2: co-existing with the default local delivery agent -============================================================ - -In this example, the default Postfix local delivery agent handles -the mail for non-virtual recipients; the virtual delivery agent -handles virtual recipients, and all virtual mailboxes are owned -by user ID 5000, group ID 5000. - -Instead of "hash" specify "dbm" or "btree", depending on your system -type. The command "postconf -m" displays possible lookup table -types. + mydestination = $myhostname localhost.$mydomain ... example.com + +The limitations of this approach are: + + * A total lack of separation: mail for info@my.host.name is delivered to the + same UNIX system account as mail for info@example.com. + * With users in the UNIX password file, administration of large numbers of + users becomes inconvenient. + +The examples that follow provide solutions for both limitations. + +PPoossttffiixx vviirrttuuaall AALLIIAASS eexxaammppllee:: sseeppaarraattee ddoommaaiinnss,, UUNNIIXX ssyysstteemm aaccccoouunnttss + +With the approach described in this section, every hosted domain can have its +own info etc. email address. However, it still uses UNIX system accounts for +local mailbox deliveries. + +With virtual alias domains, each hosted address is aliased to a local UNIX +system account or to a remote address. The example below shows how to use this +mechanism for the example.com domain. + + 1 /etc/postfix/main.cf: + 2 virtual_alias_domains = example.com ...other hosted domains... + 3 virtual_alias_maps = hash:/etc/postfix/virtual + 4 + 5 /etc/postfix/virtual: + 6 postmaster@example.com postmaster + 7 info@example.com joe + 8 sales@example.com jane + 9 # Uncomment entry below to implement a catch-all address + 10 # @example.com jim + 11 ...virtual aliases for more domains... + +Notes: + + * Line 2: the virtual_alias_domains setting tells Postfix that example.com is + a so-called virtual alias domain. If you omit this setting then Postfix + will reject mail (relay access denied) or will not be able to deliver it + (mail for example.com loops back to myself). + + NEVER list a virtual alias domain name as a mydestination domain! + + * Lines 3-8: the /etc/postfix/virtual file contains the virtual aliases. With + the example above, mail for postmaster@example.com goes to the local + postmaster, while mail for info@example.com goes to the UNIX account joe, + and mail for sales@example.com goes to the UNIX account jane. Mail for all + other addresses in example.com is rejected with the error message "User + unknown". + + * Line 10: the commented out entry (text after #) shows how one would + implement a catch-all virtual alias that receives mail for every + example.com address not listed in the virtual alias file. This is not + without risk. Spammers nowadays try to send mail from (or mail to) every + possible name that they can think of. A catch-all mailbox is likely to + receive many spam messages, and many bounces for spam messages that were + sent in the name of anything@example.com. + +Execute the command "ppoossttmmaapp //eettcc//ppoossttffiixx//vviirrttuuaall" after changing the virtual +file, and execute the command "ppoossttffiixx rreellooaadd" after changing the main.cf file. + +Note: virtual aliases can resolve to a local address or to a remote address, or +both. They don't have to resolve to UNIX system accounts on your machine. + +More details about the virtual alias file are given in the virtual(5) manual +page, including multiple addresses on the right-hand side. + +Virtual aliasing solves one problem: it allows each domain to have its own info +mail address. But there still is one drawback: each virtual address is aliased +to a UNIX system account. As you add more virtual addresses you also add more +UNIX system accounts. The next section eliminates this problem. + +PPoossttffiixx vviirrttuuaall MMAAIILLBBOOXX eexxaammppllee:: sseeppaarraattee ddoommaaiinnss,, nnoonn--UUNNIIXX aaccccoouunnttss + +As a system hosts more and more domains and users, it becomes less desirable to +give every user their own UNIX system account. + +With the Postfix virtual(8) mailbox delivery agent, every recipient address can +have its own virtual mailbox. Unlike virtual alias domains, virtual mailbox +domains do not need the clumsy translation from each recipient addresses into a +different address, and owners of a virtual mailbox address do not need to have +a UNIX system account. + +The Postfix virtual(8) mailbox delivery agent looks up the user mailbox +pathname, uid and gid via separate tables that are searched with the +recipient's mail address. Maildir style delivery is turned on by terminating +the mailbox pathname with "/". + +If you find the idea of multiple tables bothersome, remember that you can +migrate the information (once it works), to an SQL database. If you take that +route, be sure to review the "local files versus databases" section at the top +of this document. + +Here is an example of a virtual mailbox domain "example.com": + + 1 /etc/postfix/main.cf: + 2 virtual_mailbox_domains = example.com ...more domains... + 3 virtual_mailbox_base = /var/mail/vhosts + 4 virtual_mailbox_maps = hash:/etc/postfix/vmailbox + 5 virtual_minimum_uid = 100 + 6 virtual_uid_maps = static:5000 + 7 virtual_gid_maps = static:5000 + 8 virtual_alias_maps = hash:/etc/postfix/virtual + 9 + 10 /etc/postfix/vmailbox: + 11 info@example.com example.com/info + 12 sales@example.com example.com/sales/ + 13 # Comment out the entry below to implement a catch-all. + 14 # @example.com example.com/catchall + 15 ...virtual mailboxes for more domains... + 16 + 17 /etc/postfix/virtual: + 18 postmaster@example.com postmaster + +Notes: + + * Line 2: The virtual_mailbox_domains setting tells Postfix that example.com + is a so-called virtual mailbox domain. If you omit this setting then + Postfix will reject mail (relay access denied) or will not be able to + deliver it (mail for example.com loops back to myself). + + NEVER list a virtual MAILBOX domain name as a mydestination domain! + + NEVER list a virtual MAILBOX domain name as a virtual ALIAS domain! + + * Line 3: The virtual_mailbox_base parameter specifies a prefix for all + virtual mailbox pathnames. This is a safety mechanism in case someone makes + a mistake. It prevents mail from being delivered all over the file system. + + * Lines 4, 10-15: The virtual_mailbox_maps parameter specifies the lookup + table with mailbox (or maildir) pathnames, indexed by the virtual mail + address. In this example, mail for info@example.com goes to the mailbox at + /var/mail/vhosts/example.com/info while mail for sales@example.com goes to + the maildir located at /var/mail/vhosts/example.com/sales/. + + * Line 5: The virtual_minimum_uid specifies a lower bound on the mailbox or + maildir owner's UID. This is a safety mechanism in case someone makes a + mistake. It prevents mail from being written to sensitive files. + + * Lines 6, 7: The virtual_uid_maps and virtual_gid_maps parameters specify + that all the virtual mailboxes are owned by a fixed uid and gid 5000. If + this is not what you want, specify lookup tables that are searched by the + recipient's mail address. + + * Line 14: The commented out entry (text after #) shows how one would + implement a catch-all virtual mailbox address. Be prepared to receive a lot + of spam, as well as bounced spam that was sent in the name of + anything@example.com. + + NEVER put a virtual MAILBOX wild-card in the virtual ALIAS file!! + + * Lines 8, 17, 18: As you see, it is possible to mix virtual aliases with + virtual mailboxes. We use this feature to redirect mail for example.com's + postmaster address to the local postmaster. You can use the same mechanism + to redirect an address to a remote address. + + * Line 18: This example assumes that in main.cf, $myorigin is listed under + the mydestination parameter setting. If that is not the case, specify an + explicit domain name on the right-hand side of the virtual alias table + entries or else mail will go to the wrong domain. + +Execute the command "ppoossttmmaapp //eettcc//ppoossttffiixx//vviirrttuuaall" after changing the virtual +file, execute "ppoossttmmaapp //eettcc//ppoossttffiixx//vvmmaaiillbbooxx" after changing the vmailbox file, +and execute the command "ppoossttffiixx rreellooaadd" after changing the main.cf file. + +Note: mail delivery happens with the recipient's UID/GID privileges specified +with virtual_uid_maps and virtual_gid_maps. Postfix 2.0 and earlier will not +create mailDIRs in world-writable parent directories; you must create them in +advance before you can use them. Postfix may be able to create mailBOX files by +itself, depending on parent directory write permissions, but it is safer to +create mailBOX files ahead of time. + +More details about the virtual mailbox delivery agent are given in the virtual +(8) manual page. + +NNoonn--PPoossttffiixx mmaaiillbbooxx ssttoorree:: sseeppaarraattee ddoommaaiinnss,, nnoonn--UUNNIIXX aaccccoouunnttss + +This is a variation on the Postfix virtual mailbox example. Again, every hosted +address can have its own mailbox. + +While non-Postfix software is being used for final delivery, some Postfix +concepts are still needed in order to glue everything together. For additional +background on this glue you may want to take a look at the virtual mailbox +domain class as defined in the ADDRESS_CLASS_README file. + +The text in this section describes what things should look like from Postfix's +point of view. See LMTP_README or MAILDROP_README for specific information +about Cyrus or about Courier maildrop. + +Here is an example for a hosted domain example.com that delivers to a non- +Postfix delivery agent: + + 1 /etc/postfix/main.cf: + 2 virtual_transport = ...see below... + 3 virtual_mailbox_domains = example.com ...more domains... + 4 virtual_mailbox_maps = hash:/etc/postfix/vmailbox + 5 virtual_alias_maps = hash:/etc/postfix/virtual + 6 + 7 /etc/postfix/vmailbox: + 8 info@example.com whatever + 9 sales@example.com whatever + 10 # Comment out the entry below to implement a catch-all. + 11 # Configure the mailbox store to accept all addresses. + 12 # @example.com whatever + 13 ...virtual mailboxes for more domains... + 14 + 15 /etc/postfix/virtual: + 16 postmaster@example.com postmaster + +Notes: + + * Line 2: With delivery to a non-Postfix mailbox store for hosted domains, + the virtual_transport parameter usually specifies the Postfix LMTP client, + or the name of a master.cf entry that executes non-Postfix software via the + pipe delivery agent. Typical examples (use only one): + + virtual_transport = lmtp:unix:/path/name (uses UNIX-domain socket) + virtual_transport = lmtp:hostname:port (uses TCP socket) + virtual_transport = maildrop: (uses pipe(8) to command) + + Postfix comes ready with support for LMTP. And an example maildrop delivery + method is already defined in the default Postfix master.cf file. See the + MAILDROP_README document for more details. + + * Line 3: The virtual_mailbox_domains setting tells Postfix that example.com + is delivered via the virtual_transport that was discussed in the previous + paragraph. If you omit this virtual_mailbox_domains setting then Postfix + will either reject mail (relay access denied) or will not be able to + deliver it (mail for example.com loops back to myself). + + NEVER list a virtual MAILBOX domain name as a mydestination domain! + + NEVER list a virtual MAILBOX domain name as a virtual ALIAS domain! + + * Lines 4, 7-13: The virtual_mailbox_maps parameter specifies the lookup + table with all valid recipient addresses. The lookup result is ignored by + Postfix. In the above example, info@example.com and sales@example.com are + listed as valid addresses, and mail for anything else is rejected with + "User unknown". If you intend to use LDAP, MySQL or PgSQL instead of local + files, be sure to review the "local files versus databases" section at the + top of this document! + + * Line 12: The commented out entry (text after #) shows how one would inform + Postfix of the existence of a catch-all address. Again, the lookup result + is ignored by Postfix. + + NEVER put a virtual MAILBOX wild-card in the virtual ALIAS file!! + + Note: if you specify a wildcard in virtual_mailbox_maps, then you still + need to configure the non-Postfix mailbox store to receive mail for any + address in that domain. + + * Lines 5, 15, 16: As you see above, it is possible to mix virtual aliases + with virtual mailboxes. We use this feature to redirect mail for + example.com's postmaster address to the local postmaster. You can use the + same mechanism to redirect any addresses to a local or remote address. + + * Line 16: This example assumes that in main.cf, $myorigin is listed under + the mydestination parameter setting. If that is not the case, specify an + explicit domain name on the right-hand side of the virtual alias table + entries or else mail will go to the wrong domain. + +Execute the command "ppoossttmmaapp //eettcc//ppoossttffiixx//vviirrttuuaall" after changing the virtual +file, execute "ppoossttmmaapp //eettcc//ppoossttffiixx//vvmmaaiillbbooxx" after changing the vmailbox file, +and execute the command "ppoossttffiixx rreellooaadd" after changing the main.cf file. + +MMaaiill ffoorrwwaarrddiinngg ddoommaaiinnss + +Some providers host domains that have no (or only a few) local mailboxes. The +main purpose of these domains is to forward mail elsewhere. The following +example shows how to set up example.com as a mail forwarding domain: + + 1 /etc/postfix/main.cf: + 2 virtual_alias_domains = example.com ...other hosted domains... + 3 virtual_alias_maps = hash:/etc/postfix/virtual + 4 + 5 /etc/postfix/virtual: + 6 postmaster@example.com postmaster + 7 joe@example.com joe@somewhere + 8 jane@example.com jane@somewhere-else + 9 # Uncomment entry below to implement a catch-all address + 10 # @example.com jim@yet-another-site + 11 ...virtual aliases for more domains... + +Notes: + + * Line 2: The virtual_alias_domains setting tells Postfix that example.com is + a so-called virtual alias domain. If you omit this setting then Postfix + will reject mail (relay access denied) or will not be able to deliver it + (mail for example.com loops back to myself). + + NEVER list a virtual alias domain name as a mydestination domain! + + * Lines 3-11: The /etc/postfix/virtual file contains the virtual aliases. + With the example above, mail for postmaster@example.com goes to the local + postmaster, while mail for joe@example.com goes to the remote address + joe@somewhere, and mail for jane@example.com goes to the remote address + jane@somewhere-else. Mail for all other addresses in example.com is + rejected with the error message "User unknown". + + * Line 10: The commented out entry (text after #) shows how one would + implement a catch-all virtual alias that receives mail for every + example.com address not listed in the virtual alias file. This is not + without risk. Spammers nowadays try to send mail from (or mail to) every + possible name that they can think of. A catch-all mailbox is likely to + receive many spam messages, and many bounces for spam messages that were + sent in the name of anything@example.com. + +Execute the command "ppoossttmmaapp //eettcc//ppoossttffiixx//vviirrttuuaall" after changing the virtual +file, and execute the command "ppoossttffiixx rreellooaadd" after changing the main.cf file. + +More details about the virtual alias file are given in the virtual(5) manual +page, including multiple addresses on the right-hand side. + +MMaaiilliinngg lliissttss + +The examples that were given above already show how to direct mail for virtual +postmaster addresses to a local postmaster. You can use the same method to +direct mail for any address to a local or remote address. + +There is one major limitation: virtual aliases and virtual mailboxes can't +directly deliver to mailing list managers such as majordomo. The solution is to +set up virtual aliases that direct virtual addresses to the local delivery +agent: /etc/postfix/main.cf: - # All domains and users delivered by the virtual local delivery agent. - - virtual_transport = virtual - virtual_mailbox_base = /var/mail/vhosts - virtual_mailbox_maps = hash:/etc/postfix/vmailbox - virtual_mailbox_domains = $virtual_mailbox_maps - virtual_minimum_uid = 100 - virtual_uid_maps = static:5000 - virtual_gid_maps = static:5000 + virtual_alias_maps = hash:/etc/postfix/virtual - # All domains and users delivered by the local delivery agent. - # local_recipient_maps is used by the SMTP server to reject mail - # for unknown users. - - local_transport = local - mydestination = $myhostname $localhost.$mydomain - local_recipient_maps = unix:passwd.byname $alias_maps - -Define a virtual delivery agent if the entry doesn't already exist: - - /etc/postfix/master.cf: - virtual unix - n n - - virtual - -Example recipients, one UNIX-style mailbox, one qmail-style maildir: - - /etc/postfix/vmailbox: - test1@virtual1.domain test1 - test2@virtual2.domain test2/ - - /etc/postfix/vmaildomains: - virtual1.domain required to prevent relay access denied errors - virtual2.domain required to prevent relay access denied errors - -Execute something like the following commands for each mailbox recipient: + /etc/postfix/virtual: + listname-request@example.com listname-request + listname@example.com listname + owner-listname@example.com owner-listname - # touch /var/mail/vhosts/test1 - # chown 5000:5000 /var/mail/vhosts/test1 + /etc/aliases: + listname: "|/some/where/majordomo/wrapper ..." + owner-listname: ... + listname-request: ... -Execute something like the following commands for each maildir recipient: +This example assumes that in main.cf, $myorigin is listed under the +mydestination parameter setting. If that is not the case, specify an explicit +domain name on the right-hand side of the virtual alias table entries or else +mail will go to the wrong domain. - # mkdir /var/mail/vhosts/test2 - # chown 5000:5000 /var/mail/vhosts/test2 +More information about the Postfix local delivery agent can be found in the +local(8) manual page. -Remember that each domain is required to have a postmaster contact -address. +Why does this example use a clumsy virtual alias instead of a more elegant +transport mapping? The reason is that mail for the virtual mailing list would +be rejected with "User unknown". In order to make the transport mapping work +one would still need a bunch of virtual alias or virtual mailbox table entries. -Example 3: hosting many virtual users -===================================== + * In case of a virtual alias domain, there would need to be one identity + mapping from each mailing list address to itself. + * In case of a virtual mailbox domain, there would need to be a dummy mailbox + for each mailing list address. -Example 2 is fine if you host only a few virtual users. With many -users you will want to separate the information that changes often -(the user addresses) from the information that changes rarely (the -names of hosted domains). +AAuuttoorreepplliieess -This example is the same as above, with co-existing local and -virtual domains, but it uses a separate table for specifying the -virtual domain names. +In order to set up an autoreply for virtual recipients while still delivering +mail as normal, set up a rule in a virtual alias table: /etc/postfix/main.cf: - # All domains and users delivered by the virtual local delivery agent. + virtual_alias_maps = hash:/etc/postfix/virtual - virtual_transport = virtual - virtual_mailbox_base = /var/mail/vhosts - virtual_mailbox_maps = hash:/etc/postfix/vmailbox - virtual_mailbox_domains = hash:/etc/postfix/vmaildomains - virtual_minimum_uid = 100 - virtual_uid_maps = static:5000 - virtual_gid_maps = static:5000 - - # All domains and users delivered by the local delivery agent. - # local_recipient_maps is used by the SMTP server to reject mail - # for unknown users. - - local_transport = local - mydestination = $myhostname $localhost.$mydomain - local_recipient_maps = unix:passwd.byname $alias_maps - -Define a virtual delivery agent if the entry doesn't already exist: - - /etc/postfix/master.cf: - virtual unix - n n - - virtual - -Example recipients, one UNIX-style mailbox, one qmail-style maildir: - - /etc/postfix/vmailbox: - test1@virtual1.domain test1 - test2@virtual2.domain test2/ - - /etc/postfix/vmaildomains: - virtual1.domain required to prevent relay access denied errors - virtual2.domain required to prevent relay access denied errors - -Execute something like the following commands for each mailbox recipient: - - # touch /var/mail/vhosts/test1 - # chown 5000:5000 /var/mail/vhosts/test1 - -Execute something like the following commands for each maildir recipient: - - # mkdir /var/mail/vhosts/test2 - # chown 5000:5000 /var/mail/vhosts/test2 - -Remember that each domain is required to have a postmaster contact -address. + /etc/postfix/virtual: + user@domain.tld user@domain.tld, user@domain.tld@autoreply.mydomain.tld -Example 4: forwarding mail for an old account to a new address -============================================================== +This delivers mail to the recipient, and sends a copy of the mail to the +address that produces automatic replies. The address can be serviced on a +different machine, or it can be serviced locally by setting up a transport map +entry that pipes all mail for autoreply.mydomain.tld into some script that +sends an automatic reply back to the sender. -In order to forward mail for a user who no longer exists, one would -set up a rule in a virtual table (please ignore the text in the -virtual configuration file about virtual domains): +DO NOT list autoreply.mydomain.tld in mydestination! /etc/postfix/main.cf: - virtual_maps = hash:/etc/postfix/virtual + transport_maps = hash:/etc/postfix/transport - /etc/postfix/virtual: - old_user@old.domain new_user@new.domain + /etc/postfix/transport: + autoreply.mydomain.tld autoreply: -Example 5: setting up a virtual vacation autoresponder -====================================================== + /etc/postfix/master.cf: + # ============================================================= + # service type private unpriv chroot wakeup maxproc command + # (yes) (yes) (yes) (never) (100) + # ============================================================= + autoreply unix - n n - - pipe + flags= user=nobody argv=/path/to/autoreply $sender $mailbox -In order to set up an autoreply for virtual recipients while still -delivering mail as normal, set up a rule in a virtual table (please -ignore the text in the virtual configuration file about virtual -domains): +This invokes /path/to/autoreply with the sender address and the user@domain.tld +recipient address on the command line. - /etc/postfix/main.cf: - virtual_maps = hash:/etc/postfix/virtual +For more information, see the pipe(8) manual page, and the comments in the +Postfix master.cf file. - /etc/postfix/virtual: - user@domain.tld user@domain.tld, user@autoreply.domain.tld - -This delivers mail to the recipient, and sends a copy of the mail -to the address that produces automatic replies. The address can be -serviced on a different machine, or it can be serviced locally by -setting up a transport map entry that pipes all mail for the -autoreply.domain.tld into some script that sends an automatic -reply back to the sender. diff --git a/postfix/README_FILES/XCLIENT_README b/postfix/README_FILES/XCLIENT_README index 2fe74bb0a..fc2f3a0a5 100644 --- a/postfix/README_FILES/XCLIENT_README +++ b/postfix/README_FILES/XCLIENT_README @@ -1,95 +1,151 @@ -Purpose of the XCLIENT extension to SMTP -======================================== +PPoossttffiixx XXCCLLIIEENNTT HHoowwttoo + +------------------------------------------------------------------------------- + +PPuurrppoossee ooff tthhee XXCCLLIIEENNTT eexxtteennssiioonn ttoo SSMMTTPP The XCLIENT command targets the following problems: -1 - Access control tests. SMTP server access rules are difficult -to verify when decisions can be triggered only by remote clients. -In order to facilitate access rule testing, an authorized SMTP -client test program needs the ability to override the SMTP server's -idea of the SMTP client hostname, network address, and other client -information, for the entire duration of an SMTP session. - -2 - Client software that downloads mail from an up-stream mail -server and injects it into a local MTA via SMTP. In order to take -advantage of the local MTA's SMTP server access rules, the client -software needs the ability to override the SMTP server's idea of -the remote client name, client address and other information. Such -information can typically be extracted from the up-stream mail -server's Received: message header. - -3 - Post-filter access control and logging. With Internet->filter->MTA -style content filter applications, the filter can be simplified if -it can delegate decisions concerning mail relay and other access -control to the MTA. This is especially useful when the filter acts -as a transparent proxy for SMTP commands. As in the other examples, -this requires that the filter can override the MTA's idea of the -SMTP client hostname, network address, and other information. - -Command syntax -============== - -In SMTP server EHLO replies, the keyword associated with this -extension is XCLIENT. It is followed by the names of the attributes -that the XCLIENT implementation supports. - -The general command syntax is described below. Upper case and -quoted strings specify terminals, lowercase strings specify meta -terminals, and SP is whitespace. Although command and attribute -names are shown in upper case, they are in fact case insensitive. - - xclient-command = XCLIENT 1*( SP name"="value ) - - name = ( NAME | ADDR | PROTO | HELO ) - -The XCLIENT command can be sent at any time except in the middle -of a mail delivery transaction (i.e. between MAIL and DOT). The -command may be pipelined if the server EHLO reply announces ESMTP -pipelining support. - -The XCLIENT reply codes are as follows: - - Code | Meaning - -----|------------ - 250 | success - 501 | bad command parameter syntax - 503 | mail transaction in progress - 421 | unable to proceed - -The NAME attribute specifies an SMTP client hostname (not an SMTP -client address), [UNAVAILABLE] when client hostname lookup failed -due to a permanent error, or [TEMPUNAVAIL] when the lookup error -condition was transient. - -The ADDR attribute specifies an SMTP client numerical IPv4 network -address, an IPv6 address prefixed with IPV6:, or [UNAVAILABLE] -when the address information is unavailable. Address information -is not enclosed with []. - -The PROTO attribute specifies either SMTP or ESMTP. - -The HELO attribute specifies an SMTP HELO parameter value, or the -value [UNAVAILABLE] when the information is unavailable. - -Note 1: syntactically valid NAME and HELO attributes can be up to -255 characters long. The client must not send XCLIENT commands that -exceed the 512 character limit for SMTP commands. - -Note 2: [UNAVAILABLE], [TEMPUNAVAIL] and IPV6: may be specified in -upper case, lower case or mixed case. - -Security -======== - -The XCLIENT command changes audit trails and/or SMTP client access -permissions. Use of this command must be restricted to authorized -SMTP clients. However, the XCLIENT command should not override its -own access control mechanism. - -SMTP connection caching -======================= - -XCLIENT attributes persist until the end of an SMTP session. If -one session is used to deliver mail from different SMTP clients, -the XCLIENT attributes need to be reset as appropriate in between -deliveries. + 1. Access control tests. SMTP server access rules are difficult to verify when + decisions can be triggered only by remote clients. In order to facilitate + access rule testing, an authorized SMTP client test program needs the + ability to override the SMTP server's idea of the SMTP client hostname, + network address, and other client information, for the entire duration of + an SMTP session. + + 2. Client software that downloads mail from an up-stream mail server and + injects it into a local MTA via SMTP. In order to take advantage of the + local MTA's SMTP server access rules, the client software needs the ability + to override the SMTP server's idea of the remote client name, client + address and other information. Such information can typically be extracted + from the up-stream mail server's Received: message header. + + 3. Post-filter access control and logging. With Internet->filter->MTA style + content filter applications, the filter can be simplified if it can + delegate decisions concerning mail relay and other access control to the + MTA. This is especially useful when the filter acts as a transparent proxy + for SMTP commands. This requires that the filter can override the MTA's + idea of the SMTP client hostname, network address, and other information. + +XXCCLLIIEENNTT CCoommmmaanndd ssyynnttaaxx + +Examples of client-server conversations are given at the end of this document. + +In SMTP server EHLO replies, the keyword associated with this extension is +XCLIENT. It is followed by the names of the attributes that the XCLIENT +implementation supports. + +The XCLIENT command may be sent at any time except in the middle of a mail +delivery transaction (i.e. between MAIL and DOT). The XCLIENT command may be +pipelined when the server supports ESMTP command pipelining. + +The syntax of XCLIENT requests is described below. Upper case and quoted +strings specify terminals, lowercase strings specify meta terminals, and SP is +whitespace. Although command and attribute names are shown in upper case, they +are in fact case insensitive. + + xclient-command = XCLIENT 1*( SP attribute-name"="attribute-value ) + + attribute-name = ( NAME | ADDR | PROTO | HELO ) + + * The NAME attribute specifies an SMTP client hostname (not an SMTP client + address), [UNAVAILABLE] when client hostname lookup failed due to a + permanent error, or [TEMPUNAVAIL] when the lookup error condition was + transient. + + * The ADDR attribute specifies an SMTP client numerical IPv4 network address, + an IPv6 address prefixed with IPV6:, or [UNAVAILABLE] when the address + information is unavailable. Address information is not enclosed with []. + + * The PROTO attribute specifies either SMTP or ESMTP. + + * The HELO attribute specifies an SMTP HELO parameter value, or the value + [UNAVAILABLE] when the information is unavailable. + +Note 1: syntactically valid NAME and HELO attributes can be up to 255 +characters long. The client must not send XCLIENT commands that exceed the 512 +character limit for SMTP commands. To avoid exceeding the limit the client +should send the information in multiple XCLIENT commands. + +Note 2: [UNAVAILABLE], [TEMPUNAVAIL] and IPV6: may be specified in upper case, +lower case or mixed case. + +The XCLIENT server reply codes are as follows: + + _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ + |CCooddee|MMeeaanniinngg | + |_ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |250 |success | + |_ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |501 |bad command parameter syntax | + |_ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |503 |mail transaction in progress | + |_ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |421 |unable to proceed, disconnecting| + |_ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + +XXCCLLIIEENNTT EExxaammpplleess + +In the first example, the client impersonates a mail originating system by +passing all SMTP session information via XCLIENT commands. Information sent by +the client is shown in bold font. + + 220 server.example.com ESMTP Postfix + EEHHLLOO cclliieenntt..eexxaammppllee..ccoomm + 250-server.example.com + 250-PIPELINING + 250-SIZE 10240000 + 250-VRFY + 250-ETRN + 250-XCLIENT NAME ADDR PROTO HELO + 250 8BITMIME + XXCCLLIIEENNTT NNAAMMEE==ssppiikkee..ppoorrccuuppiinnee..oorrgg AADDDDRR==116688..110000..118899..22 PPRROOTTOO==EESSMMTTPP + 250 Ok + XXCCLLIIEENNTT HHEELLOO==ssppiikkee..ppoorrccuuppiinnee..oorrgg + 250 Ok + MMAAIILL FFRROOMM::<> + 250 Ok + RRCCPPTT TTOO::<> + 250 Ok + DDAATTAA + 354 End data with . + .. .. ..mmeessssaaggee ccoonntteenntt.. .. .. + .. + 250 Ok: queued as 763402AAE6 + QQUUIITT + 221 Bye + +In the second example, the client impersonates a mail originating system by +sending the XCLIENT command before the EHLO or HELO command. This increases the +realism of impersonation, but requires that the client knows ahead of time what +XCLIENT options the server supports. + + 220 server.example.com ESMTP Postfix + XXCCLLIIEENNTT NNAAMMEE==ssppiikkee..ppoorrccuuppiinnee..oorrgg AADDDDRR==116688..110000..118899..22 + 250 Ok + HHEELLOO ssppiikkee..ppoorrccuuppiinnee..oorrgg + 250 server.example.com + MMAAIILL FFRROOMM::<> + 250 Ok + RRCCPPTT TTOO::<> + 250 Ok + DDAATTAA + 354 End data with . + .. .. ..mmeessssaaggee ccoonntteenntt.. .. .. + .. + 250 Ok: queued as CF1E52AAE7 + QQUUIITT + 221 Bye + +SSeeccuurriittyy + +The XCLIENT command changes audit trails and/or SMTP client access permissions. +Use of this command must be restricted to authorized SMTP clients. However, the +XCLIENT command should not override its own access control mechanism. + +SSMMTTPP ccoonnnneeccttiioonn ccaacchhiinngg + +XCLIENT attributes persist until the end of an SMTP session. If one session is +used to deliver mail on behalf of different SMTP clients, the XCLIENT +attributes need to be reset as appropriate before each MAIL FROM command. + diff --git a/postfix/README_FILES/XFORWARD_README b/postfix/README_FILES/XFORWARD_README index fffe00223..91a145277 100644 --- a/postfix/README_FILES/XFORWARD_README +++ b/postfix/README_FILES/XFORWARD_README @@ -1,101 +1,130 @@ -Purpose of the XFORWARD extension to SMTP -======================================== +PPoossttffiixx XXFFOORRWWAARRDD HHoowwttoo + +------------------------------------------------------------------------------- + +PPuurrppoossee ooff tthhee XXFFOORRWWAARRDD eexxtteennssiioonn ttoo SSMMTTPP The XFORWARD command targets the following problem: -- Logging after SMTP-based content filter. With the deployment of -Internet->MTA1->filter->MTA2 style content filter applications, -the logging of client and message identifying information changes -when MTA1 gives the mail to the content filter. To simplify the -interpretation of MTA2 logging, it would help if MTA1 could forward -remote client and/or message identifying information through the -content filter to MTA2, so that the information could be logged as -part of mail handling transactions. - -This extension is implemented as a separate command, and can be -used to transmit client or message attributes incrementally. It -is not implemented by passing additional parameters via the MAIL -FROM command, because doing so would require extending the MAIL -FROM command length limit by another 600 or more characters beyond -the space needed by other extensions such as AUTH. - -Command syntax -============== - -In SMTP server EHLO replies, the keyword associated with this -extension is XFORWARD. The keyword is followed by the names of the -attributes that the XFORWARD implementation supports. - -The general command syntax is described below. Upper case and -quoted strings specify terminals, lowercase strings specify meta -terminals, and SP is whitespace. Although command and attribute -names are shown in upper case, they are in fact case insensitive. - - xforward-command = XFORWARD 1*( SP name"="value ) - - name = ( NAME | ADDR | PROTO | HELO ) - -The XFORWARD command can be sent at any time except in the middle -of a mail delivery transaction (i.e. between MAIL and DOT). The -command may be pipelined if the server EHLO reply announces ESMTP -pipelining support. - -The XFORWARD reply codes are as follows: - - Code | Meaning - -----|------------ - 250 | success - 501 | bad command parameter syntax - 503 | mail transaction in progress - 421 | unable to proceed - -The information specified with XFORWARD attributes is not limited -to DNS hostnames, IP addresses or SMTP protocol names. Attribute -values may contain arbitrary text, must not be longer than 255 -characters (specific attributes may imposer shorter lengths), must -not contain control characters, non-ASCII characters, whitespace, -or other characters that are special in message headers. - -The NAME attribute specifies the up-stream hostname, or [UNAVAILABLE] -when the information is unavailable. The hostname may be a non-DNS -hostname. - -The ADDR attribute specifies the up-stream network address, or -[UNAVAILABLE] when the information is unavailable. Address -information is not enclosed with []. The address may be a non-IP -address. - -The PROTO attribute specifies the mail protocol for receiving mail -from the up-stream host. This may be an SMTP non-SMTP protocol name -of up to 64 characters, or [UNAVAILABLE] when the information is -unavailable. - -The HELO attribute specifies the hostname that the up-stream host -announced itself with (not necessarily via the SMTP HELO command), -or [UNAVAILABLE] when the information is unavailable. The hostname -may be a non-DNS hostname. - -Note 1: DNS hostnames can be up to 255 characters long. The XFORWARD -client implementation must not send XFORWARD commands that exceed -the 512 character limit for SMTP commands. - -Note 2: [UNAVAILABLE] may be specified in upper case, lower case -or mixed case. - -Note 3: the XFORWARD server implementation must not mix information -from the current SMTP session with forwarded information from an -up-stream session. - -Security -======== - -The XFORWARD command changes audit trails. Use of this command -must be restricted to authorized clients. - -SMTP connection caching -======================= - -SMTP connection caching makes it possible to deliver multiple -messages within the same SMTP session. The XFORWARD attributes are -reset after the MAIL FROM command completes, so there is no risk -of information leakage. + * Logging after SMTP-based content filter. With the deployment of Internet- + >MTA1->filter->MTA2 style content filter applications, the logging of + client and message identifying information changes when MTA1 gives the mail + to the content filter. To simplify the interpretation of MTA2 logging, it + would help if MTA1 could forward remote client and/or message identifying + information through the content filter to MTA2, so that the information + could be logged as part of mail handling transactions. + +This extension is implemented as a separate command, and can be used to +transmit client or message attributes incrementally. It is not implemented by +passing additional parameters via the MAIL FROM command, because doing so would +require extending the MAIL FROM command length limit by another 600 or more +characters beyond the space that is already needed in order to support other +extensions such as AUTH. + +XXFFOORRWWAARRDD CCoommmmaanndd ssyynnttaaxx + +An example of a client-server conversation is given at the end of this +document. + +In SMTP server EHLO replies, the keyword associated with this extension is +XFORWARD. The keyword is followed by the names of the attributes that the +XFORWARD implementation supports. + +The client may send the XFORWARD request at any time except in the middle of a +mail delivery transaction (i.e. between MAIL and DOT). The command may be +pipelined when the server supports ESMTP command pipelining. + +The syntax of XFORWARD requests is described below. Upper case and quoted +strings specify terminals, lowercase strings specify meta terminals, and SP is +whitespace. Although command and attribute names are shown in upper case, they +are in fact case insensitive. + + xforward-command = XFORWARD 1*( SP attribute-name"="attribute-value ) + + attribute-name = ( NAME | ADDR | PROTO | HELO ) + + * The NAME attribute specifies the up-stream hostname, or [UNAVAILABLE] when + the information is unavailable. The hostname may be a non-DNS hostname. + + * The ADDR attribute specifies the up-stream network address, or + [UNAVAILABLE] when the information is unavailable. Address information is + not enclosed with []. The address may be a non-IP address. + + * The PROTO attribute specifies the mail protocol for receiving mail from the + up-stream host. This may be an SMTP non-SMTP protocol name of up to 64 + characters, or [UNAVAILABLE] when the information is unavailable. + + * The HELO attribute specifies the hostname that the up-stream host announced + itself with (not necessarily via the SMTP HELO command), or [UNAVAILABLE] + when the information is unavailable. The hostname may be a non-DNS + hostname. + +Note 1: Attribute values must not be longer than 255 characters (specific +attributes may impose shorter lengths), must not contain control characters, +non-ASCII characters, whitespace, or other characters that are special in +message headers. Future attributes that may violate this should use xtext +encoding as described in RFC 1891. + +Note 2: DNS hostnames can be up to 255 characters long. The XFORWARD client +implementation must not send XFORWARD commands that exceed the 512 character +limit for SMTP commands. + +Note 3: [UNAVAILABLE] may be specified in upper case, lower case or mixed case. + +Note 4: the XFORWARD server implementation must not mix information from the +current SMTP session with forwarded information from an up-stream session. + +The XFORWARD server reply codes are as follows: + + _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ + |CCooddee|MMeeaanniinngg | + |_ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |250 |success | + |_ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |501 |bad command parameter syntax | + |_ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |503 |mail transaction in progress | + |_ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + |421 |unable to proceed, disconnecting| + |_ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ | + +XXFFOORRWWAARRDD EExxaammppllee + +In the following example, information sent by the client is shown in bold font. + + 220 server.example.com ESMTP Postfix + EEHHLLOO cclliieenntt..eexxaammppllee..ccoomm + 250-server.example.com + 250-PIPELINING + 250-SIZE 10240000 + 250-VRFY + 250-ETRN + 250-XFORWARD NAME ADDR PROTO HELO + 250 8BITMIME + XXFFOORRWWAARRDD NNAAMMEE==ssppiikkee..ppoorrccuuppiinnee..oorrgg AADDDDRR==116688..110000..118899..22 PPRROOTTOO==EESSMMTTPP + 250 Ok + XXFFOORRWWAARRDD HHEELLOO==ssppiikkee..ppoorrccuuppiinnee..oorrgg + 250 Ok + MMAAIILL FFRROOMM::<> + 250 Ok + RRCCPPTT TTOO::<> + 250 Ok + DDAATTAA + 354 End data with . + .. .. ..mmeessssaaggee ccoonntteenntt.. .. .. + .. + 250 Ok: queued as 3CF6B2AAE8 + QQUUIITT + 221 Bye + +SSeeccuurriittyy + +The XFORWARD command changes audit trails. Use of this command must be +restricted to authorized clients. + +SSMMTTPP ccoonnnneeccttiioonn ccaacchhiinngg + +SMTP connection caching makes it possible to deliver multiple messages within +the same SMTP session. The XFORWARD attributes are reset after the MAIL FROM +command completes, so there is no risk of information leakage. + diff --git a/postfix/RELEASE_NOTES b/postfix/RELEASE_NOTES index d576caa19..8a0050609 100644 --- a/postfix/RELEASE_NOTES +++ b/postfix/RELEASE_NOTES @@ -1,649 +1,10 @@ -In the text below, incompatible changes are labeled with the Postfix -snapshot that introduced the change. If you upgrade from a later -Postfix version, then you do not have to worry about that particular -incompatibility. - -Official Postfix releases are called a.b.c where a=major release -number, b=minor release number, c=patchlevel. Snapshot releases -are now called a.b.c-yyyymmdd where yyyymmdd is the release date +The official Postfix release is called 2.1.x where 2=major release +number, 1=minor release number, x=patchlevel. Snapshot releases +are now called 2.2-yyyymmdd where yyyymmdd is the release date (yyyy=year, mm=month, dd=day). The mail_release_date configuration parameter contains the release date (both for official release and -snapshot release). Patches change the patchlevel and the release -date. Snapshots change only the release date, unless they include -the same bugfixes as a patch release. - -Incompatible changes with Postfix snapshot 2.0.18-2004122 -========================================================== - -This release undoes the snapshot 2004120 changes to the Postfix -line reading routines. These changes caused surprises with lines -ending in EOF. - -Major changes with Postfix snapshot 2.0.18-20040122 -=================================================== - -New "PREPEND headername: headervalue" action in Postfix access maps -that can be used by external SMTPD policy servers in order to label -mail instead of rejecting it. - -Incompatible changes with Postfix snapshot 2.0.17-2004120 -========================================================== - -The new queue manager nqmgr has become the default qmgr queue -manager. For a limited time the old queue manager remains available -under the name oqmgr. The name nqmgr still works but will cause a -warning to be logged. - -Queue files creates with "sendmail -v" are no longer compatible -with earlier Postfix 2.x versions. A new record type, "killed", -was introduced in order to avoid repeated mail delivery reports -from mail that could not be delivered due to a temporary error -condition. - -The format of the postfix-files file has changed. There is a new -type for hard links. With hard or symbolic link entries, the first -field is now the destination pathname and the "owner" field is now -the origin pathname, while "group" and "permissions" are ignored. - -The SMTP server now rejects non-existent sender addresses in a -local, virtual or relay domain; that is, a sender address must -pass the same "user unknown" test as a recipient would have to -pass. This is not configurable. - -Support for the non-standard Errors-To: message header is removed. -This also helps to stop potential attacks that rely on bouncing -mail to a destination that is not directly reachable by the attacker. - -The sample-regexp/pcre-* files are replaced by header_checks(5) -and body_checks(5) manual pages that give more complete information. - -The LDAP and SQL clients have been moved to the global directory -in order to eliminate reversed dependencies. - -Major changes with Postfix snapshot 2.0.17-20040120 -=================================================== - -The new queue manager nqmgr has become the default qmgr queue -manager. For a limited time the old queue manager remains available -under the name oqmgr. The name nqmgr still works but will cause a -warning to be logged. - -The HOSTING_README file now documents most of the methods that can -be used to host domains with a Postfix MTA. - -New header_checks(5) and body_checks(5) manual pages that give a -more complete description than the old sample configuration files. - -Slightly more agressive delivery to sites that defer a lot of mail. - -Incompatible changes with Postfix snapshot 2.0.16-20031226 -========================================================== - -Postfix no longer allows mail addresses with bare numeric IP -addresses (user@1.2.3.4). This is not configurable. The form -user@[ipaddress] is still allowed. - -Bounce messages now have a separate queue life time. This is -controlled by the bounce_queue_lifetime parameter. - -Incompatible changes with Postfix snapshot 2.0.16-20031223 -========================================================== - -In mailq (queue listing) output, there no longer is space between -a short queue ID and the "*" (delivery in progress) or ! (mail on -hold) status indicator. This makes the output easier to parse. - -The SMTP client now tries to connect to an alternate MX address -when a delivery attempt fails **after the initial SMTP handshake**. -This includes both broken connections and 4XX SMTP replies. To -get the old behavior, specify "smtp_mx_session_limit = 1" in main.cf. - -After delivery failure due to a temporary error condition, the SMTP -client now always connects to the fall-back relay if specified. - -Major changes with Postfix snapshot 2.0.16-20031223 -=================================================== - -The SMTP client now tries to connect to an alternate MX address -when a delivery attempt fails **after the initial SMTP handshake**. -This includes both broken connections and 4XX SMTP replies. - -Finally, fallback_relay works as promised. - -The new SMTP client connection management is controlled by two new -configuration parameters: - -- smtp_mx_address_limit (default unlimited): the number of MX (mail -exchanger) IP addresses that can result from mail exchanger lookups. - -- smtp_mx_session_limit (default 2): the number of SMTP sessions -per delivery request before giving up or delivering to a fall-back -relay, ignoring IP addresses that fail to complete the SMTP initial -handshake. - -Incompatible changes with Postfix snapshot 2.0.16-20031215 -========================================================== - -XCLIENT is approaching completion. - -Major changes with Postfix snapshot 2.0.16-20031215 -=================================================== - -The XCLIENT extension to SMTP implements SMTP client impersonation -for SMTP server access rule testing. Send "xclient name=xxx addr=yyy" -in SMTP sessions and pretend that you are connecting as the specified -client. More details are in the XCLIENT_README file. - -The XFORWARD extension to SMTP forwards up-stream MTA information -(and in the future, message identifying information) to improve -the logging by down-stream mail software. Send "xclient name=xxx -addr=yyy proto=aaa helo=bbb" to specify the original SMTP client -information that should be recorded with the next MAIL FROM -transaction. More details are in the XFORWARD_README file. - -The reject_sender_login_mismatch feature is now implemented in -terms of more basic restrictions: reject_unauth_sender_login_mismatch -(reject mail when $sender_login_maps lists an owner for the sender -address but the SMTP client is not SASL authenticated) and -reject_auth_sender_login_mismatch (reject mail when the sender -address is not owned by the SASL authenticated user). The -sender_login_maps now support multiple owners per sender address. - -Incompatible changes with Postfix snapshot 2.0.16-20031203 -========================================================== - -Many SMTPD reject logfile entries now show NOQUEUE instead of a -queue ID. This is because Postfix no longer creates a queue file -before the SMTP server has received a valid recipient. - -The experimental XADDR and XLOGINFO extensions to SMTP are now -replaced by XCLIENT. - -Major changes with Postfix snapshot 2.0.16-20031203 -=================================================== - -The XCLIENT extension to SMTP replaces the short-lived XADDR and -XLOGINFO extensions. Details are given in the XCLIENT_README file. - -XCLIENT supports the following features: - -- SMTPD access rule testing. Send "xclient override client_name=xxx -client_addr=yyy" in SMTP sessions and pretend that you are sending -mail as the specified client. - -- Remote client information forwarding through a content filter to -improve logging by down-stream mail software. Send "xclient forward -client_name=xxx client_addr=yyy client_proto=aaa client_helo=bbb" -to specify the original client information that should be logged -and stored with the next MAIL FROM transaction. - -Incompatible changes with Postfix snapshot 2.0.16-20031111 -========================================================== - -The demo greylist policy server is now case insensitive. - -The demo greylist policy server now uses BTREE files which greatly -improves stability. - -Major changes with Postfix snapshot 2.0.16-20031111 -=================================================== - -Preliminary defense against SMTP clients that hammer an SMTP server -with too many connections. By default, the number of simultaneous -connections per client is limited to half the default process limit, -and no limit is imposed on the number of successive connections -per time unit that a client is allowed to make. - -The new anvil server maintains the connection statistics, and logs -the maximum connection count and connection rate per client every -client_connection_status_update_time seconds (10 minutes), or when -it terminates (when there is no work to be done, or when "postfix -reload" was issued). Once you have an idea what the numbers look -like, you can clamp down the limits for your system. - -The relevant main.cf configuration parameters are: smtpd_client_- -connection_count_limit for the number of simultaneous connections -per client, and smtpd_client_connection_rate_limit for the number -of successive connections per unit time and client. The time unit -is specified with the client_connection_rate_time_unit parameter, -and is one minute by default. - -When Postfix rejects a client, it sends a 450 status code and -disconnects, and logs a warning with the client name/address and -the service name from master.cf. You can, for example, capture this -information with a logfile watching program that updates a firewall -rule (such a watcher program is not included with Postfix). - -To avoid rejecting authorized hosts, the smtpd_client_connection_- -limit_exceptions parameter takes a list of network/netmask expressions, -hostnames or .domain names that are excluded from these restrictions. -By default, all clients in $mynetworks are excluded; you will -probably want to use a more restrictive setting. - -See also: sample-smtpd.cf, smtpd(8), and anvil(8). - -Incompatible changes with Postfix snapshot 2.0.16-20031022 -========================================================== - -Postfix no longer retries delivery when no MX host has a valid A -record, for compatibility with most other MTAs. This change is made -in anticipation of a possible Verisign "wild-card MX record without -A record" for unregistered domains. To get the old behavior, specify -"smtp_defer_if_no_mx_address_found = yes". - -The Postfix SMTP client no longer looks in /etc/hosts by default. -To get the old behavior, specify "smtp_host_lookup = dns, native". - -The authorized_verp_clients configuration parameter has been renamed -to smtpd_authorized_verp_clients. This is for consistency with the -new smtpd_authorized_xaddr_clients and smtpd_authorized_xloginfo_clients -configuration parameters that control the use of the new XADDR and -XLOGINFO commands. - -The smtpd_authorized_verp_clients parameter now defaults to nothing -(no XVERP command is accepted). - -The Postfix SMTP server no longer allows queue_minfree values that -are less than twice the message_size_limit value. - -The Postfix SMTP server no longer accepts mail when the amount of -free queue space is less than twice the message_size_limit value. - -Major changes with Postfix snapshot 2.0.16-20031022 -=================================================== - -Easier debugging of SMTPD access restrictions. The SMTP command -"XADDR client-address client-hostname" changes Postfix's idea of -the remote client name and address, so that you can pretend to -connect from anywhere on the Internet. Use of this command is -restricted to clients that match the list of names or addresses -specified with the smtpd_authorized_xaddr_clients parameter. By -default, XADDR is not accepted from anywhere. - -More useful logging by Postfix daemons behind a real-time SMTP -proxy filter (the logging now shows the remote client name and -address, instead of localhost[127.0.0.1]). This uses the new SMTP -command "XLOGINFO client-address client-hostname", which specifies -the client name and address for logging purposes without changing -the name/address that are used for SMTPD access control. Use of -this command is restricted to clients that match the list of names -or addresses specified with the smtpd_authorized_xloginfo_clients -parameter. By default, XLOGINFO is not accepted from anywhere. -For an example, see the updated SMTPD_PROXY_README file. - -Major changes with Postfix snapshot 2.0.16-20030917 -=================================================== - -New check_{helo,sender,recipient}_{ns,mx}_access maptype:mapname -restriction that applies the specified access table to the NS or -MX hosts of the host/domain given in HELO, EHLO, MAIL FROM or RCPT -TO commands. - -This can be used to block mail from so-called spammer havens, from -sender addresses that resolve to Verisign's wild-card mail responder, -or from domains that claim to have mail servers in reserved networks -such as 127.0.0.1. - - /etc/postfix/main.cf: - smtpd_mumble_restrictions = - ... - reject_unknown_sender_domain - check_sender_mx_access hash:/etc/postfix/mx_access - check_sender_mx_access cidr:/etc/postfix/mx_access.cidr - ... - - /etc/postfix/mx_access: - spammer.haven.tld reject spammer mx host - 64.94.110.11 reject mail server in verisign wild-card domain - - /etc/postfix/mx_access.cidr: - 0.0.0.0/8 reject mail server in broadcast network - 10.0.0.0/8 reject mail server in RFC 1918 private network - 127.0.0.0/8 reject mail server in loopback network - 169.254.0.0/16 reject mail server in link local network - 172.16.0.0/12 reject mail server in RFC 1918 private network - 192.0.2.0/24 reject mail server in TEST-NET network - 192.168.0/16 reject mail server in RFC 1918 private network - 224.0.0.0/4 reject mail server in class D multicast network - 240.0.0.0/5 reject mail server in class E reserved network - 248.0.0.0/5 reject mail server in reserved network - -Note: OK actions are not allowed for security reasons. Instead of -OK, use DUNNO in order to exclude specific hosts from blacklists. -If an OK result is found for an NS or MX host, Postfix rejects the -SMTP command with "451 Server configuration error". - -Incompatible changes with Postfix snapshot 2.0.16-20030915 -========================================================== - -In header/body_checks actions, the OK action is being phased out, -and the DUNNO action is being phased in. Both actions still work -and do the same thing, but hopefully DUNNO causes less confusion. - -Major changes with Postfix snapshot 2.0.16-20030915 -=================================================== - -LDAP parameters can now be defined in external files. Specify the -LDAP maps in main.cf as - - ldap:/path/to/ldap.cf - -and write the LDAP parameters in /path/to/ldap.cf, without the -"ldapsource_" prefix. This makes it possible to securely store -bind passwords for plain auth outside of main.cf (which must be -world readable). The old syntax still works, for backwards -compatibility. By Liviu Daia, based on a suggestion by Victor -Duchovni and Lamont Jones. - -Support for LDAP URLs in the LDAP parameter "server_host", if -Postfix is linked against OpenLDAP. LDAP hosts, ports, and connection -protocols to be used as LDAP sources can be specified as a -blank-separated list of LDAP URLs in "server_host". As with -OpenLDAP, specifying a port in a LDAP URL overrides "server_port". -Examples: - - server_host = ldap://ldap.itd.umich.edu - server_host = ldaps://ldap.itd.umich.edu:636 - server_host = ldapi://%2Fsome%2Fpath - -The LDAP SSL scheme ldaps:// is available if OpenLDAP was compiled -with SSL support. New parameters "tls_ca_cert_dir", "tls_ca_cert_file", -"tls_cert", "tls_key", "tls_require_cert", "tls_random_file", -"tls_cipher_suite" control the certificates, source of random -numbers, and cipher suites used for SSL connections. See LDAP_README -for further information. By Liviu Daia. - -Support for STARTTLS command in LDAP, if Postfix is linked against -OpenLDAP and OpenLDAP was compiled with SSL support. STARTTLS is -controlled by the "start_tls" parameter. The above parameters for -certificates, source of random numbers, and cipher suites also -apply. See LDAP_README for further information. By Liviu Daia, -amended by Victor Duchovni. - -Major changes with Postfix snapshot 2.0.13-20030715 -=================================================== - -Support for SMTP access policy delegation to an external server. -Greylisting is used as an example. See the SMTPD_POLICY_README -file for further information. - -Support for multi-valued RBL lookup results. For example, specify -"reject_rbl_client foo.bar.tld=127.0.0.3" to reject clients that -are listed with a "127.0.0.3" address record. - -Major changes with Postfix snapshot 2.0.13-20030706 -=================================================== - -New receive_override_options parameter that eliminates the need -for different cleanup service instances before and after an external -content filter. One parameter controls what happens before or after -the content filter: rejecting unknown recipients, canonical mapping, -virtual alias expansion, masquerading, automatic BCC recipients -and header/body checks. See sample-filter.cf for details. - -Incompatible changes with Postfix snapshot 2.0.13-20030704 -========================================================== - -Support for client side LDAP caching is gone. OpenLDAP 2.1.13 and -later no longer support it, and the feature never worked well. -Postfix now ignores cache controlling parameters in an LDAP -configuration file and logs a warning. Credits to Victor Duchovni -and Lamont Jones. - -Major changes with Postfix snapshot 2.0.13-20030704 -=================================================== - -The Postfix SMTP server can be configured to send all mail into a -proxy server, for example a real-time SPAM filter. This proxy is -expected to send the mail into another Postfix SMTP server process -for normal delivery. See the SMTPD_PROXY_README file for details. - -Improved LDAP client robustness. Given suitable invalid database -contents, LDAP lookups can produce too many results, enter an -infinite loop in the expansion of "special result attributes" (LDAP -DNs and LDAP URLs) or can simply consume excessive server resources. -Credits to Victor Duchovni and Lamont Jones. - -New CIDR-based lookup table, remotely based on code by Jozsef -Kadlecsik. For details and examples, see "man cidr_table". - -The TCP-based table lookup protocol is finished. For details and -examples, see "man tcp_table". This will allow you to implement -your own greylisting, or to do your own open proxy tests before -accepting mail. - -Support for !/pattern/ (negative matches) in PCRE lookup tables by -Victor Duchovni. See "man pcre_table" for more. - -New enable_original_recipient parameter (default: yes) to control -whether Postfix keeps track of original recipient address information. -If this is turned off Postfix produces no X-Original-To: headers -and ignores the original recipient when eliminating duplicates -after virtual alias expansion. Code by Victor Duchovni. - -Finer control over how long Postfix SMTPD waits for completion of -address verification probes: the address_verify_poll_{count,delay} -parameters control how often to query the verify server and how -long to wait between queries. Specify address_verify_poll_count=1 -to implement a crude form of greylisting. - -Major changes with Postfix snapshot 2.0.11-20030611 -=================================================== - -Better verify server performance on busy servers by avoiding some -operations that can block the verify server process temporarily. -Probe messages are no longer subject to cleanup server in_flow_delay -settings when message arrival rates exceed message delivery rates. -However, probe messages are still subject to trigger_timeout delays -when the queue manager FIFO fills up; this is hopefully very rare. - -Major changes with Postfix snapshot 2.0.11-20030609 -=================================================== - -Address verification probes can now follow a different route than -ordinary mail. To make this possible, the address resolver supports -multiple personalities. The regular personality is used for regular -mail, and the alternate personality is used for address verification -probes. The alternate personality is controlled by parameters named -address_verify_X with X = relayhost, transport_maps, local_transport, -virtual_transport, relay_transport, and default_transport. These -alternate parameters have by default the same values as the regular -parameters. For more detail see the ADDRESS_VERIFICATION_README file. - -Major changes with Postfix snapshot 2.0.11-20030606 -=================================================== - -Complete rewrite of the queue file record reading loops in the -pickup, cleanup and in the queue manager daemons. This code had -deteriorated over time. The new code eliminates an old problem -where the queue manager had to read most queue file records twice -in the case of an alias/include file expansion with more than -qmgr_message_recipient_limit recipients. - -Incompatible changes with Postfix snapshot 2.0.8-20030417 -========================================================= - -"sendmail -t" no longer complains when recipients are given on the -command line. Instead, it now adds recipients from headers to the -recipients from the command-line. - -Major changes with Postfix snapshot 2.0.8-20030417 -================================================== - -Automatic BCC recipients depending on sender or recipient address. -The configuration parameters in question are "sender_bcc_maps" and -"recipient_bcc_maps". See conf/sample-misc.cf for details. - -Support for sending mail to hosts not in the DNS, without having -to turn off DNS lookups. The "smtp_host_lookup" parameter controls -how the Postfix SMTP client looks up hosts. The default is to use -DNS and then the native mechanism. See conf/sample-smtp.cf. - -Incompatible changes with Postfix snapshot 2.0.8-20040415 -========================================================= - -Too many people mess up their net/mask patterns, causing open -mail relay problems. Postfix processes now abort when given a -net/mask pattern with a non-zero host portion (for example, -168.100.189.2/28), and suggest to specify the proper net/mask -pattern instead (for example, 168.100.189.0/28). - -Major changes with Postfix snapshot 2.0.8-20040415 -================================================== - -PostgreSQL table lookups. Specify "pgsql:/file/name" where "/file/name" -defines the database. See the sample-pgsql-aliases.cf file for -examples, and the PGSQL_README file for general information. - -Workaround for file system clock drift that caused Postfix to ignore -new mail (this could happen with file systems mounted from a server). -Postfix now logs a warning and proceeds with only slightly reduced -performance, instead of ignoring new mail. - -Incompatible changes with Postfix snapshot 2.0.6-20030305 -========================================================= - -Postfix truncates non-address information in message address headers -(comments, etc.) to 250 characters per address, in order to protect -vulnerable Sendmail systems against exploitation of a remote buffer -overflow problem (CERT advisory CA-2003-07). - -Incompatible changes with Postfix snapshot 2.0.3-20030227 -========================================================= - -The smtpd_hard_error_limit and smtpd_soft_error_limit values now -behave as documented, that is, smtpd_hard_error_limit=1 causes -Postfix to disconnect upon the first client error. Previously, -there was an off-by-one error causing Postfix to change behavior -after smtpd_hard/soft_error_limit+1 errors. - -Incompatible changes with Postfix snapshot 2.0.3-20030125 -========================================================= - -This release adds a new queue file record type for the address -specified in "REDIRECT user@domain" actions in access maps or -header/body_checks. - -Major changes with Postfix snapshot 2.0.3-20030125 -================================================== - -Code cleanup up of queue manager internals. Queue names are no -longer mixed up with the next-hop destination, and the address -resolver loop is now easier to understand. - -New "REDIRECT user@domain" action for access maps and header/body_checks -that overrides all the originally specified recipients of a message. -I would never recommend that people use this to redirect (bounced) -SPAM to the beneficiaries of an advertisement campaign. It would -have helped when someone began spamming the network with sender -addresses in one of my domains, and I got all the bounces. - -Incompatible changes with Postfix snapshot 2.0.3-20030126 -========================================================= - -The maildir file naming algorithm has changed in accordance with -an updated version of http://cr.yp.to/proto/maildir.html. The name -is now TIME.VdevIinum.HOST - -Incompatible changes with Postfix snapshot 2.0.3-20030124 -========================================================= - -The maildir file naming algorithm has changed. Pending a usable -version of http://cr.yp.to/proto/maildir.html, the name is now -TIME.DEV_INUM.HOST. - -Incompatible changes with Postfix snapshot 2.0.1-20030112 -========================================================= - -The Postfix build procedure now uses the pcre-config utility (part -of PCRE version 3) to find out the pathnames of the PCRE include -file and object library, instead of probing /usr/include and/or -/usr/lib. To build with PCRE version 2 support you will have to -specify pathnames as described in PCRE_README. To build without -PCRE support, specify: make Makefiles CCARGS="-DNO_PRCE". - -Incompatible changes with Postfix snapshot 2.0.0-20030104 -========================================================= - -This release adds the new proxymap service (table lookup via a -proxy process) to the master.cf file. If you get warnings about -problems connecting to the proxymap service, then you did not -properly upgrade Postfix. - -Major changes with Postfix snapshot 2.0.0-20030104 -================================================== - -This release introduces the proxymap service for Postfix lookup -table access. This can be used to overcome chroot restrictions in -the Postfix SMTP server (specify proxy:unix:passwd.byname for -password file lookup through the proxymap server) and can be used -to consolidate the number of open tables by sharing one open table -among multiple processes (specify proxy:mysql:/file/name to avoid -"too many connections" conditions). The proxy_read_maps parameter -specifies what maps are approved for access via the proxy service -(only map references starting with "proxy:" are considered approved). - -Multi-server daemons (servers that accept simultaneous connections -from multiple clients) will now stop accepting new connections -after serving $max_use clients. This allows multi-server daemons -to automatically restart even on busy mail systems. - -Clients of multi-server daemons such as trivial-rewrite and the -new proxymap service now automatically disconnect after $ipc_ttl -seconds of activity (default: 1000s). This allows multi-server -daemons to automatically restart even on busy mail systems. - -Incompatible changes with Postfix snapshot 1.1.11-trace-20021119 -================================================================ - -After upgrading an existing system you must use "postfix reload". -This is because many internal protocols have changed. - -The file format of bounce/defer logfiles has changed from the old -one-line ad-hoc format to a more structured multi-line format. For -backwards compatibility, Postfix now creates bounce/defer logfile -entries that contain both the old and the new format, so that you -can go back to an older Postfix release without losing information. -Old Postfix versions will warn about malformed logfile entries, -but should work properly. To disable backwards compatibility specify -"backwards_bounce_logfile_compatibility = no" in main.cf. - -The behavior of "sendmail -v" has changed. One -v option now sends -an email report with the status of each delivery attempt. Multiple --v options behave as before: turn on verbose logging in the sendmail -and postdrop commands. - -The Postfix upgrade procedure will add two new services to your -master.cf file: "trace" and "verify". These servers can run inside -a chroot jail, have no interaction with users, and don't talk to -the network. - -Major changes with Postfix snapshot 1.1.11-trace-20021119 -========================================================= - -New sender address verification blocks mail from addresses that -are not deliverable. This is turned on with the reject_unverified_sender -UCE restriction. Addresses are verified by probing, that is, by -sending mail that is not actually delivered (SMTP interruptus). -Detailed information is in the SENDER_VERIFICATION_README file -and sample-verify.cf. - -Address verification uses the new "verify" daemon that maintains -a database. The necessary entry is automatically added to master.cf -when you upgrade. - -New "sendmail -bv" option. Postfix probes the specified recipient -addresses without actually delivering mail, and sends back an email -delivery report. This is useful for testing address rewriting and -address routing of both envelope and header addresses. This feature -currently does not access or update the sender address verification -database. - -Improved "sendmail -v" behavior. Postfix delivers mail as usual, -and emails a report of all the delivery attempts to the originator. - -Bounce reports now show the original recipient information in -addition to the final recipient that was already available. +snapshot release). Patches are issued for the official release +and change the patchlevel and the release date. Patches are never +issued for snapshot releases. -Both "sendmail -bv" and "sendmail -v" use the new "trace" daemon -that is automatically added to master.cf when you upgrade. +[nothing to report here, except great relief that 2.1 is frozen] diff --git a/postfix/RELEASE_NOTES-2.2 b/postfix/RELEASE_NOTES-2.2 new file mode 100644 index 000000000..ddc2aa428 --- /dev/null +++ b/postfix/RELEASE_NOTES-2.2 @@ -0,0 +1,578 @@ +In the text below, incompatible changes are labeled with the Postfix +snapshot that introduced the change. If you upgrade from a later +Postfix version, then you do not have to worry about that particular +incompatibility. + +The official Postfix release is called 2.1.x where 2=major release +number, 1=minor release number, x=patchlevel. Snapshot releases +are now called 2.2-yyyymmdd where yyyymmdd is the release date +(yyyy=year, mm=month, dd=day). The mail_release_date configuration +parameter contains the release date (both for official release and +snapshot release). Patches are issued for the official release +and change the patchlevel and the release date. Patches are never +issued for snapshot releases. + +Major changes - critical +------------------------ + +You must stop Postfix 1.x before upgrading. This is because the +master-child protocols have changed, and nothing will work with +the old master daemon process. + +[Incompat 20021119] You can upgrade Postfix 2.0 without stopping. +After upgrading an existing Postfix 2.0 system you must use "postfix +reload". Some internal protocols have changed, but the master-child +protocols are the same as with Postfix 2.0. + +[Incompat 20021119] The Postfix upgrade procedure will add two new +services to your master.cf file: "trace" and "verify". These servers +can run inside a chroot jail, have no interaction with users, and +don't talk to the network. If Postfix complains that "trace" and +"verify" are not found, you made the error of copying your old +Postfix configuration files over the new ones. Execute "postfix +upgrade-configuration" to repair the Postfix configuration files. + +[Incompat 20040331] Support for the non-standard Errors-To: message +header is removed. This also helps to stop potential attacks that +rely on bouncing mail to a destination that is not directly reachable +by the attacker. Specify "enable_errors_to = yes" to get the old +behavior. + +Queue files written by Postfix 2.1 may contain information that +is incompatible with older Postfix versions: + +[Incompat 20040120] Queue files creates with "sendmail -v" are no +longer compatible with Postfix versions 2.0 and earlier. A new +record type, "killed", was introduced in order to avoid repeated +mail delivery reports from mail that could not be delivered due to +a temporary error condition. + +[Incompat 20030125] This release adds a new queue file record type +for the address specified in "REDIRECT user@domain" actions in +access maps or header/body_checks. Queue files with these records +will be rejected by older Postfix versions. + +[Feature 20040120] The new queue manager nqmgr has become the +default qmgr queue manager. For a limited time the old queue manager +remains available under the name oqmgr. The name nqmgr still works +but will cause a warning to be logged. + +[Incompat 20040413] The Postfix SMTP server no longer accepts mail +from or to an address ending in "@", including address forms that +rewrite into an address that ends in "@"). Specify "resolve_null_domain += yes" to get the old behavior. + +[Incompat 20031226] Postfix no longer allows mail addresses with +bare numeric IP addresses (user@1.2.3.4). This is not configurable. +The form user@[ipaddress] is still allowed. + +[Incompat 20031226] Bounce messages now have a separate queue life +time. This is controlled by the bounce_queue_lifetime parameter. + +Major changes - build environment +--------------------------------- + +[Incompat 20030112] The Postfix build procedure now uses the +pcre-config utility (part of PCRE version 3) to find out the +pathnames of the PCRE include file and object library, instead of +probing /usr/include and/or /usr/lib. To build with PCRE version +2 support you will have to specify pathnames as described in +PCRE_README. To build without PCRE support, specify: make Makefiles +CCARGS="-DNO_PRCE". + +Major changes - documentation +----------------------------- + +[Feature 20040331] Complete documentation rewrite. All parameters +are now described in postconf(5), and all commands and daemons are +shown in their proper context in the OVERVIEW document. +- All documents come as HTML and ASCII text. +- All HTML documents have hyperlinks for every parameter name, + for every Postfix manual page, and for every README file. +- All documents specify what feature is available in what release. +- The sample-*.cf configuration files no longer exist. The information + is now available in HTML documents, README files and UNIX man pages). +- The mumble_table example configuration files no longer exist. + +[Incompat 20040413] The LMTP, Cyrus and Qmail related README files will +not be included in the Postfix version 2.1 distribution. They will +be made available via http://www.postfix.org/, and in Postfix 2.2 +snapshots. + +[Feature 20040413] You can install documentation in HTML format +besides the README files. Installation of README files is now +optional. + +Major changes - access control +------------------------------ + +[Feature 20031215] Easier debugging of SMTPD access restrictions. +The SMTP command "xclient name=xxx addr=yyy" changes Postfix's idea +of the remote client name and address, so that you can pretend to +connect from anywhere on the Internet. Use of this command is +restricted to clients that match the list of names or addresses +specified with the smtpd_authorized_xclient_hosts parameter. By +default, XCLIENT is not accepted from anywhere. More details are +in the XCLIENT_README file. + +[Feature 20030715] Support for multi-valued RBL lookup results. +For example, specify "reject_rbl_client foo.bar.tld=127.0.0.3" to +reject clients that are listed with a "127.0.0.3" address record. +More information is in the postconf(5) manual page. + +[Feature 20030917] New "check_{helo,sender,recipient}_{ns,mx}_access +type:table" restrictions that apply the specified access table to +the NS or MX hosts of the host/domain given in HELO, EHLO, MAIL +FROM or RCPT TO commands. More information is in the postconf(5) +manual page. + +This can be used to block mail from so-called spammer havens (all +domains that are served by the same DNS server, all domains that +resolve to the same MX host), from sender addresses that resolve +to Verisign's wild-card mail responder, or from domains that claim +to have mail servers in reserved networks such as 127.0.0.1. + +Note: OK actions are not allowed for security reasons. Instead of +OK, use DUNNO in order to exclude specific hosts from blacklists. +If an OK result is found for an NS or MX host, Postfix rejects the +SMTP command with "451 Server configuration error". + +[Feature 20040413] Support for a "WARN text..." feature in SMTPD +access tables, just like the WARN feature in header/body_checks. + +[Feature 20040122] New "PREPEND headername: headervalue" action in +Postfix access maps. Primarily intended for tagging mail by for +example, an external SMTPD policy server. See access(5). + +[Feature 20040124] New "PREPEND text" action in Postfix header/body_checks +maps. This action prepends a header or body line immediately before +the line that triggers the action. See header_checks(5) for details. + +[Feature 20030125] New "REDIRECT user@domain" action for access +maps and header/body_checks that overrides all the originally +specified recipients of a message. Wietse would never recommend +that people use this to redirect (bounced) SPAM to the beneficiaries +of an advertisement campaign. See access(5) and header_checks(5). + +[Feature 20031215] The reject_sender_login_mismatch feature (used +with SASL authenticated logins) is now implemented in terms of more +basic restrictions: reject_unauth_sender_login_mismatch (reject +mail when $sender_login_maps lists an owner for the sender address +but the SMTP client is not SASL authenticated) and +reject_auth_sender_login_mismatch (reject mail when the sender +address is not owned by the SASL authenticated user). The +sender_login_maps now support multiple owners per sender address. +See postconf(5) for details. + +Major changes - address verification +------------------------------------ + +[Feature 20021119] Address verification blocks mail from or to +addresses that are not deliverable. This is turned on with the +reject_unverified_sender UCE restriction. Addresses are verified +by probing, that is, by sending mail that is not actually delivered +(SMTP interruptus). Detailed information is in the +ADDRESS_VERIFICATION_README file. + +Address verification can follow a different route than ordinary +mail, typically to avoid sending probes to a relay host. To make +this possible, the address resolver supports multiple personalities. +For more detail see the ADDRESS_VERIFICATION_README file. + +New "sendmail -bv" option. Postfix probes the specified recipient +addresses without actually delivering mail, and sends back an email +delivery report. This is useful for testing address rewriting and +address routing, and shows the final envelope and header addresses. +This feature currently does not access or update the sender address +verification database. + +Major changes - content inspection +---------------------------------- + +[Feature 20030704] The Postfix SMTP server can be configured to +send all mail into a real-time content filter that inspects mail +BEFORE it is queued. See the SMTPD_PROXY_README file for details. + +[Feature 20031022] Improved logging by Postfix daemons behind an +SMTP-based proxy filter. The logging now shows the remote client +name and address, instead of localhost[127.0.0.1]. This uses the +new SMTP command "XFORWARD addr=client-address name=client-hostname", +which specifies remote client information for logging purposes. +This command is restricted to clients that match the list of names +or addresses specified with the smtpd_authorized_xforward_hosts +parameter. By default, XFORWARD is not accepted from anywhere. +For an example, see the SMTPD_PROXY_README file. + +[Feature 20030706] New receive_override_options parameter that +eliminates the need for different cleanup service instances before +and after an external content filter. One parameter controls what +happens before or after the content filter: rejecting unknown +recipients, canonical mapping, virtual alias expansion, masquerading, +automatic BCC recipients and header/body checks. See postconf(5) +for the fine details. + +[Feature 20040124] New "PREPEND text" action in Postfix header/body_checks +maps. This action prepends a header or body line immediately before +the line that triggers the action. See header_checks(5) for details. + +[Feature 20030125] New "REDIRECT user@domain" action for access maps +and header/body_checks that overrides all the originally specified +recipients of a message. Wietse would never recommend that people +use this to redirect (bounced) SPAM to the beneficiaries of an +advertisement campaign. See header_checks(5) and access(5). + +[Incompat 20030915] In header/body_checks actions, the OK action +is being phased out, and the DUNNO action is being phased in. Both +actions still work and do the same thing, but hopefully DUNNO causes +less confusion. See header_checks(5) for details. + +Major changes - policy delegation +--------------------------------- + +[Feature 20030715] Support for SMTP access policy delegation to an +external server. Greylisting and SPF are provided as examples. +See the SMTPD_POLICY_README file for further information. + +Major changes - client rate limiting +------------------------------------ + +Note: this feature is not included with Postfix 2.1, but it is +documented is here so that the information will not be lost. + +[Feature 20031111] Preliminary defense against SMTP clients that +hammer an SMTP server with too many connections. By default, the +number of simultaneous connections per client is limited to half +the default process limit, and no limit is imposed on the number +of successive connections per time unit that a client is allowed +to make. + +The new anvil server maintains the connection statistics, and logs +the maximum connection count and connection rate per client every +anvil_status_update_time seconds (10 minutes), or when it terminates +(when there is no work to be done, or when "postfix reload" was +issued). Once you have an idea what the numbers look like, you can +clamp down the limits for your system. + +The relevant main.cf configuration parameters are: smtpd_client- +connection_count_limit for the number of simultaneous connections +per client, and smtpd_client_connection_rate_limit for the number +of successive connections per unit time and client. The time unit +is specified with the anvil_rate_time_unit parameter, and is one +minute by default. + +When Postfix rejects a client, it sends a 450 status code and +disconnects, and logs a warning with the client name/address and +the service name from master.cf. You can, for example, capture this +information with a logfile watching program that updates a firewall +rule (such a watcher program is not included with Postfix). + +To avoid rejecting authorized hosts, the smtpd_client_connection- +limit_exceptions parameter takes a list of network/netmask expressions, +hostnames or .domain names that are excluded from these restrictions. +By default, all clients in $mynetworks are excluded; you will +probably want to use a more restrictive setting. + +For further information, see: smtpd(8) and anvil(8). + +Major changes - configuration management +---------------------------------------- + +[Feature 20040413] New postfix(1) command features: + +- "postfix set-permissions" corrects Postfix file and directory + permissions and allows you to change mail_owner or setgid_group + settings after Postfix is installed. + +- "postfix upgrade-configuration" fixes Postfix systems after people + copy over their old configuration files after installing a new + Postfix system. + +See postfix(1) for details. + +[Incompat 20040120] The format of the postfix-files file has changed. +There is a new type for hard links. With hard or symbolic link +entries, the first field is now the destination pathname and the +"owner" field is now the origin pathname, while "group" and +"permissions" are ignored. + +Major changes - core functionality +---------------------------------- + +[Feature 20030704] New enable_original_recipient parameter (default: +yes) to control whether Postfix keeps track of original recipient +address information. If this is turned off Postfix produces no +X-Original-To: headers and ignores the original recipient when +eliminating duplicates after virtual alias expansion. Code by Victor +Duchovni. + +[Feature 20030417] Automatic BCC recipients depending on sender or +recipient address. The configuration parameters in question are +"sender_bcc_maps" and "recipient_bcc_maps". See postconf(5). + +[Incompat 20030415] Too many people mess up their net/mask patterns, +causing open mail relay problems. Postfix processes now abort when +given a net/mask pattern with a non-zero host portion (for example, +168.100.189.2/28), and suggest to specify the proper net/mask +pattern instead (for example, 168.100.189.0/28). + +[Feature 20030415] Workaround for file system clock drift that +caused Postfix to ignore new mail (this could happen with file +systems mounted from a server). Postfix now logs a warning and +proceeds with only slightly reduced performance, instead of ignoring +new mail. + +Major changes - database support +-------------------------------- + +Liviu Daia took the lead in a revision of the LDAP, MySQL and +PostgreSQL clients. Credits also go to Victor Duchovni and to +Lamont Jones. + +[Feature 20030915] LDAP parameters can now be defined in external +files. Specify the LDAP maps in main.cf as + ldap:/path/to/ldap.cf +and write the LDAP parameters in /path/to/ldap.cf, without the +"ldapsource_" prefix. This makes it possible to securely store +bind passwords for plain auth outside of main.cf (which must be +world readable). The old syntax still works, for backwards +compatibility. + +[Feature 20030915] Support for LDAP URLs in the LDAP parameter +"server_host", if Postfix is linked against OpenLDAP. LDAP hosts, +ports, and connection protocols to be used as LDAP sources can be +specified as a blank-separated list of LDAP URLs in "server_host". +As with OpenLDAP, specifying a port in a LDAP URL overrides +"server_port". Examples: + server_host = ldap://ldap.itd.umich.edu + server_host = ldaps://ldap.itd.umich.edu:636 + server_host = ldapi://%2Fsome%2Fpath + +[Feature 20030915] The LDAP SSL scheme ldaps:// is available if +OpenLDAP was compiled with SSL support. New parameters "tls_ca_cert_dir", +"tls_ca_cert_file", "tls_cert", "tls_key", "tls_require_cert", +"tls_random_file", "tls_cipher_suite" control the certificates, +source of random numbers, and cipher suites used for SSL connections. +See LDAP_README for further information. + +[Feature 20030915] Support for STARTTLS command in LDAP, if Postfix +is linked against OpenLDAP and OpenLDAP was compiled with SSL +support. STARTTLS is controlled by the "start_tls" parameter. +The above parameters for certificates, source of random numbers, +and cipher suites also apply. See LDAP_README for further information. + +[Incompat 20030704] Support for client side LDAP caching is gone. +OpenLDAP 2.1.13 and later no longer support it, and the feature +never worked well. Postfix now ignores cache controlling parameters +in an LDAP configuration file and logs a warning. + +[Feature 20030415] PostgreSQL table lookups. Specify "pgsql:/file/name" +where "/file/name" defines the database. See "man pgsql_table" for +examples, and the PGSQL_README file for general information. + +Major changes - internals +------------------------- + +[Incompat 20040120] The format of the postfix-files file has changed. +There is a new type for hard links. With hard or symbolic link +entries, the first field is now the destination pathname and the +"owner" field is now the origin pathname, while "group" and +"permissions" are ignored. + +[Incompat 20040120] The LDAP and SQL client source code is moved +to the global directory in order to eliminate reversed dependencies. + +[Feature 20030606] Complete rewrite of the queue file record reading +loops in the pickup, cleanup and in the queue manager daemons. This +code had deteriorated over time. The new code eliminates an old +problem where the queue manager had to read most queue file records +twice in the case of an alias/include file expansion with more than +qmgr_message_recipient_limit recipients. + +[Feature 20030125] Code cleanup up of queue manager internals. +Queue names are no longer mixed up with the next-hop destination, +and the address resolver loop is now easier to understand. + +[Feature 20030104] Multi-server daemons (servers that accept +simultaneous connections from multiple clients) will now stop +accepting new connections after serving $max_use clients. This +allows multi-server daemons to automatically restart even on busy +mail systems. + +[Feature 20030104] Clients of multi-server daemons such as +trivial-rewrite and the new proxymap service now automatically +disconnect after $ipc_ttl seconds of activity (default: 1000s). +This allows multi-server daemons to automatically restart even on +busy mail systems. + +[Incompat 20021119] The file format of bounce/defer logfiles has +changed from the old one-line ad-hoc format to a more structured +multi-line format. For backwards compatibility, Postfix now creates +bounce/defer logfile entries that contain both the old and the new +format, so that you can go back to an older Postfix release without +losing information. Old Postfix versions will warn about malformed +logfile entries, but should work properly. To disable backwards +compatibility specify "backwards_bounce_logfile_compatibility = +no" in main.cf. + +[Feature 20021119] Both "sendmail -bv" and "sendmail -v" use the +new "trace" daemon that is automatically added to master.cf when +you upgrade. + +Major changes - logging +----------------------- + +[Incompat 20040413] The postmap and postalias commands now report +errors to syslogd in addition to reporting them to the standard +error output. This makes logfile analysis easier. + +[Incompat 20031203] Many SMTPD "reject" logfile entries now show +NOQUEUE instead of a queue ID. This is because Postfix no longer +creates a queue file before the SMTP server has received a valid +recipient. + +Major changes - lookup table support +------------------------------------ + +[Feature 20030704] New CIDR-based lookup table, remotely based on +code by Jozsef Kadlecsik. For details and examples, see "man +cidr_table". + +[Feature 20030704] The TCP-based table lookup protocol is finished. +For details and examples, see "man tcp_table". This will allow you +to implement your own greylisting, or to do your own open proxy +tests before accepting mail. This table will not be included with +Postfix 2.1 because the protocol is obsoleted by the policy delegation +(see elsewhere in this document) which does a much better job. + +[Feature 20030704] Support for !/pattern/ (negative matches) in +PCRE lookup tables by Victor Duchovni. See "man pcre_table" and +"man regexp_table" for more. + +Major changes - resource control +-------------------------------- + +[Incompat 20031022] The Postfix SMTP server no longer accepts mail +when the amount of free queue space is less than 1.5 times the +message_size_limit value. + +Major changes - security +------------------------ + +[Incompat 20040413] The Postfix SMTP server no longer accepts mail +from or to an address ending in "@", including address forms that +rewrite into an address that ends in "@"). Specify "resolve_null_domain += yes" to get the old behavior. + +[Incompat 20040331] Support for the non-standard Errors-To: message +header is removed. This also helps to stop potential attacks that +rely on bouncing mail to a destination that is not directly reachable +by the attacker. Specify ""enable_errors_to = yes" to get the old +behavior. + +[Incompat 20040331] Tarpit delays are reduced. The Postfix SMTP +server no longer delays responses until the client has made +$smtpd_soft_error_limit errors, and the delay is fixed at +$smtpd_error_sleep_time seconds. Postfix still disconnects after +$smtpd_hard_error_limit errors. + +[Incompat 20040120] The SMTP server can reject non-existent sender +addresses in a local, virtual or relay domain; specify +"reject_unlisted_sender=yes" in order to require that a sender +address passes the same "user unknown" test as a recipient would +have to pass. This is optional in Postfix 2.1, likely to be turned +on by default in Postfix 2.2. + +[Incompat 20031226] Postfix no longer allows mail addresses with +bare numeric IP addresses (user@1.2.3.4). This is not configurable. +The form user@[ipaddress] is still allowed. + +[Incompat 20030305] Postfix truncates non-address information in message +address headers (comments, etc.) to 250 characters per address, in +order to protect vulnerable Sendmail systems against exploitation +of a remote buffer overflow problem (CERT advisory CA-2003-07). + +[Incompat 20030227] The smtpd_hard_error_limit and smtpd_soft_error_limit +values now behave as documented, that is, smtpd_hard_error_limit=1 +causes Postfix to disconnect upon the first client error. Previously, +there was an off-by-one error causing Postfix to change behavior +after smtpd_hard/soft_error_limit+1 errors. + +Major changes - smtp client +--------------------------- + +[Incompat 20031223] The SMTP client now tries to connect to an +alternate MX address when a delivery attempt fails **after the +initial SMTP handshake**. This includes both broken connections +and 4XX SMTP replies. To get the old behavior, specify +"smtp_mx_session_limit = 1" in main.cf. + +[Feature 20031223] The SMTP client now tries to connect to an +alternate MX address when a delivery attempt fails after the +initial SMTP handshake. This includes both broken connections +and 4XX SMTP replies. + +As a benefit, fallback_relay now works as promised, not just for +sessions that fail during the initial handshake. + +The new SMTP client connection management is controlled by two new +configuration parameters: + +- smtp_mx_address_limit (default unlimited): the number of MX (mail + exchanger) IP addresses that can result from mail exchanger + lookups. + +- smtp_mx_session_limit (default 2): the number of SMTP sessions + per delivery request before giving up or delivering to a fall-back + relay, ignoring IP addresses that fail to complete the SMTP + initial handshake. + +[Incompat 20031022] Postfix no longer retries delivery when no MX +host has a valid A record, for compatibility with many other MTAs. +This change is made in anticipation of a possible Verisign "wild-card +MX record without A record" for unregistered domains. To get the +old behavior, specify "smtp_defer_if_no_mx_address_found = yes". + +[Incompat 20031022] The Postfix SMTP client no longer looks in +/etc/hosts by default. To get the old behavior, specify +"smtp_host_lookup = dns, native". + +[Feature 20030417] Support for sending mail to hosts not in the +DNS, without having to turn off DNS lookups. The "smtp_host_lookup" +parameter controls how the Postfix SMTP client looks up hosts. In +order to use /etc/hosts besides DNS, specify "smtp_host_lookup = +dns, native". The default is to use DNS only. + +Major changes - user interface +------------------------------ + +[Incompat 20040418] The non-delivery report format has changed. +The "sorry" message and the DSN formatted report now include the +original recipient address, when that address is different from +the final recipient address. This makes it easier to diagnose some +mail delivery problems that happen after mail forwarding. + +[Incompat 20031223] In mailq (queue listing) output, there no longer +is space between a short queue ID and the "*" (delivery in progress) +or ! (mail on hold) status indicator. This makes the output easier +to parse. + +[Incompat 20030417] "sendmail -t" no longer complains when recipients +are given on the command line. Instead, it now adds recipients from +headers to the recipients from the command-line. + +[Incompat 20030126] The maildir file naming algorithm has changed +according to an updated version of http://cr.yp.to/proto/maildir.html. +The name is now TIME.VdevIinum.HOST + +[Incompat 20021119] The behavior of "sendmail -v" has changed. One +-v option now produces one email report with the status of each +recipient. Multiple -v options behave as before: turn on verbose +logging in the sendmail and postdrop commands. + +[Feature 20021119] New "sendmail -bv" option. Postfix probes the +specified recipient addresses without actually delivering mail, +and sends back an email delivery report. This is useful for testing +address rewriting and address routing of both envelope and header +addresses. This feature currently does not access or update the +sender address verification database. + diff --git a/postfix/SNAPSHOT b/postfix/SNAPSHOT deleted file mode 100644 index 617eeba5a..000000000 --- a/postfix/SNAPSHOT +++ /dev/null @@ -1,6 +0,0 @@ -Features to be disabled for the stable 2.1 release: - -name #ifdef module man html config sample -====================================================== -tcp_table -anvil diff --git a/postfix/TODO-BEFORE-RELEASE b/postfix/TODO-BEFORE-RELEASE new file mode 100644 index 000000000..9a311b8ec --- /dev/null +++ b/postfix/TODO-BEFORE-RELEASE @@ -0,0 +1,28 @@ +Documentation needed before official release: +============================================= + +- RELEASE_NOTES file with all changes since Postfix version 2.0. + +Tools cleanup +============= + +Remove mantools script for 2.0 to 2.1 migration: + + docparam docuseparam double makepostconf makepostconflinks + readme2html specmiss spell useparam user2var var2user + +Functionality to be removed before official release: +==================================================== + +- The anvil daemon. Its user interface needs to evolve. + + find . type f -print | xargs grep -i anvil + +- The tcp_table dictionary type. It's a weak protocol, and the +SMTPD policy delegation protocol provides a superior mechanism. + + find . type f -print | xargs egrep -i 'tcp_table|tcp-based' + +- Change top-level Makefile.stable/snapshot, makedefs.stable/snapshot + +- Delete TODO-BEFORE-RELEASE :-) diff --git a/postfix/auxiliary/MacOSX/README-INSTALL.OSX b/postfix/auxiliary/MacOSX/README-INSTALL.OSX index 1a47721c4..aa8db9e5a 100644 --- a/postfix/auxiliary/MacOSX/README-INSTALL.OSX +++ b/postfix/auxiliary/MacOSX/README-INSTALL.OSX @@ -5,6 +5,10 @@ Let's start with the important warning: DO NOT USE THE MULTIPLE USERS APPLICATION TO CREATE THE POSTFIX USER! +NOTE: Mac OS X as of version 10.3 comes with Postfix as the standard mailer +and it is supported in Server Admin on Mac OS X 10.3 Server . The instructions +below therefore only apply for Mac OS X 10.2.8. + NOTE: As of 29 September 2002, these instructions and the scripts have changed to make the solution more robust for Apple updates. diff --git a/postfix/auxiliary/qshape/qshape.pl b/postfix/auxiliary/qshape/qshape.pl new file mode 100644 index 000000000..1f3e7552b --- /dev/null +++ b/postfix/auxiliary/qshape/qshape.pl @@ -0,0 +1,322 @@ +#! /usr/bin/perl -w + +# To view the formatted manual page of this file, type: +# POSTFIXSOURCE/mantools/srctoman - qshape | nroff -man + +#++ +# NAME +# qshape 1 +# SUMMARY +# Print Postfix queue domain and age distribution +# SYNOPSIS +# .fi +# \fBqshape\fR [\fB-s\fR] [\fB-p\fR] [\fB-m \fImin_subdomains\fR] +# [\fB-b \fIbucket_count\fR] [\fB-t \fIbucket_time\fR] +# [\fB-w \fIterminal_width\fR] +# [\fB-c \fIconfig_directory\fR] [\fIqueue_name\fR ...] +# DESCRIPTION +# The \fBqshape\fR program helps the administrator understand the +# Postfix queue message distribution in time and by sender domain +# or recipient domain. The program needs read access to the queue +# directories and queue files, so it must run as the superuser or +# the \fBmail_owner\fR specified in \fImain.cf\fR (typically +# \fBpostfix\fR). +# +# Options: +# .IP \fB-s\fR +# Display the sender domain distribution instead of the recipient +# domain distribution. By default the recipient distribution is +# displayed. There can be more recipients than messages, but as +# each message has only one sender, the sender distribution is a +# a message distribution. +# .IP \fB-p\fR +# Generate aggregate statistics for parent domains. Top level domains +# are not shown, nor are domains with fewer than \fImin_subdomains\fR +# subdomains. The names of parent domains are shown with a leading dot, +# (e.g. \fI.example.com\fR). +# .IP "\fB-m \fImin_subdomains\fR" +# When used with the \fB-p\fR option, sets the minimum subdomain count +# needed to show a separate line for a parent domain. The default is 5. +# .IP "\fB-b \fIbucket_count\fR" +# The age distribution is broken up into a sequence of geometrically +# increasing intervals. This option sets the number of intervals +# or "buckets". Each bucket has a maximum queue age that is twice +# as large as that of the previous bucket. The last bucket has no +# age limit. +# .IP "\fB-b \fIbucket_time\fR" +# The age limit in minutes for the first time bucket. The default +# value is 5, meaning that the first bucket counts messages between +# 0 and 5 minutes old. +# .IP "\fB-w \fIterminal_width\fR" +# The output is right justified, with the counts for the last +# bucket shown on the 80th column, the \fIterminal_width\fR can be +# adjusted for wider screens allowing more buckets to be displayed +# with truncating the domain names on the left. When a row for a +# full domain name and its counters does not fit in the specified +# number of columns, only the last 17 bytes of the domain name +# are shown with the prefix replaced by a '+' character. Truncated +# parent domain rows are shown as '.+' followed by the last 16 bytes +# of the domain name. If this is still too narrow to show the domain +# name and all the counters, the terminal_width limit is violated. +# .IP "\fB-c \fIconfig_directory\fR" +# The \fBmain.cf\fR configuration file is in the named directory +# instead of the default configuration directory. +# .PP +# Arguments: +# .IP \fIqueue_name\fR +# By default \fBqshape\fR displays the combined distribution of +# the incoming and active queues. To display a different set of +# queues, just list their directory names on the command line. +# Absolute paths are used as is, other paths are taken relative +# to the \fImain.cf\fR \fBqueue_directory\fR parameter setting. +# While \fImain.cf\fR supports the use of \fI$variable\fR expansion +# in the definition of the \fBqueue_directory\fR parameter, the +# \fBqshape\fR program does not. If you must use variable expansions +# in the \fBqueue_directory\fR setting, you must specify an explicit +# absolute path for each queue subdirectory even if you want the +# default incoming and active queue distribution. +# SEE ALSO +# mailq(1) List all messages in the queue. +# QSHAPE_README Examples and background material. +# FILES +# $config_directory/main.cf, Postfix installation parameters. +# $queue_directory/maildrop/, local submission directory. +# $queue_directory/incoming/, new message queue. +# $queue_directory/hold/, messages waiting for tech support. +# $queue_directory/active/, messages scheduled for delivery. +# $queue_directory/deferred/, messages postponed for later delivery. +# LICENSE +# .ad +# .fi +# The Secure Mailer license must be distributed with this software. +# AUTHOR(S) +# Victor Duchovni +# Morgan Stanley +#-- + +use strict; +use IO::File; +use File::Find; +use Getopt::Std; + +my %opts; # Command line switches +my %q; # domain counts for queues and buckets +my %sub; # subdomain counts for parent domains +my $now = time; # reference time +my $bnum = 10; # deferred queue bucket count +my $width = 80; # screen char width +my $dwidth = 18; # min width of domain field +my $tick = 5; # minutes +my $minsub = 5; # Show parent domains with at least $minsub subdomains +my @qlist = qw(incoming active); + +do { + local $SIG{__WARN__} = sub { + warn "$0: $_[0]" unless exists($opts{"h"}); + die "Usage: $0 [ -s ] [ -p ] [ -m ]\n". + "\t[ -b ] [ -t ] [ -w ]\n". + "\t[ -c ] [ ... ]\n". + "The 's' option shows sender domain counts.\n". + "The 'p' option shows address counts by for parent domains.\n". + "Parent domains are shown with a leading '.' before the domain name.\n". + "Parent domains are only shown if the the domain is not a TLD, and at\n". + "least (default 5) subdomains are shown in the output.\n\n". + + "The bucket age ranges in units of minutes are\n". + "[0,1), [1,2), [2,4), [4,8), [8, 16), ... i.e.:\n". + "\tthe first bucket is [0, bucket_time) minutes\n". + "\tthe second bucket is [bucket_time, 2*bucket_time) minutes\n". + "\tthe third bucket is [2*bucket_time, 4*bucket_time) minutes...\n". + "The number of buckets shown is .\n\n". + + "The default summary is for the incoming and active queues. An explicit\n". + "list of queue names can be given on the command line. Non-absolute queue\n". + "names are interpreted relative to the Postfix queue directory. Use\n". + " to specify a non-default Postfix instance. Values of\n". + "the main.cf queue_directory parameter that use variable expansions are\n". + "not supported. If necessary, use explicit absolute paths for all queues.\n"; + }; + + getopts("hc:psw:b:t:m:", \%opts); + warn "Help message" if (exists $opts{"h"}); + + @qlist = @ARGV if (@ARGV > 0); + + # The -c option specifies the configuration directory, + # it is not used if all queue names are absolute. + # + foreach (@qlist) { + next if (m{^/}); + + $ENV{q{MAIL_CONFIG}} = $opts{"c"} if (exists $opts{"c"}); + + chomp(my $qdir = qx{postconf -h queue_directory}); + die "$0: postconf failed\n" if ($? != 0); + warn "'queue_directory' variable expansion not supported: $qdir\n" + if ($qdir =~ /\$/); + chdir($qdir) or die "$0: chdir($qdir): $!\n"; + last; + } +}; + +$width = $opts{"w"} if (exists $opts{"w"} && $opts{"w"} > 80); +$bnum = $opts{"b"} if (exists $opts{"b"} && $opts{"b"} > 0); +$tick = $opts{"t"} if (exists $opts{"t"} && $opts{"t"} > 0); +$minsub = $opts{"m"} if (exists $opts{"m"} && $opts{"m"} > 0); + +sub rec_get { + my ($h) = @_; + my $r = getc($h) || return; + my $l = 0; + my $shift = 0; + while (defined(my $lb = getc($h))) { + my $o = ord($lb); + $l |= ($o & 0x7f) << $shift ; + last if (($o & 0x80) == 0); + $shift += 7; + return if ($shift > 14); # XXX: max rec len of 2097151 + } + my $d = ""; + return unless ($l == 0 || read($h,$d,$l) == $l); + ($r, $l, $d); +} + +sub qenv { + my ($qfile) = @_; + return unless $qfile =~ m{(^|/)[A-F0-9]{6,}$}; + my @st = lstat($qfile); + return unless (@st > 0 && -f _ && (($st[2] & 0733) == 0700)); + + my $h = new IO::File($qfile, "r") || return; + my ($t, $s, @r, $dlen); + my ($r, $l, $d) = rec_get($h); + + if ($r eq "C") { + # XXX: Sanity check, the first record type is REC_TYPE_SIZE (C) + # if the file is proper queue file written by "cleanup", in + # this case the second record is always REC_TYPE_TIME. + # + $dlen = $1 if ($d =~ /^\s*(\d+)\s+\d+\s+\d+/); + ($r, $l, $d) = rec_get($h); + return unless (defined $r && $r eq "T"); + $t = $d; + } elsif ($r eq "S" || $r eq "F") { + # For embryonic queue files in the "maildrop" directory the first + # record is either a REC_TYPE_FULL (F) followed by REC_TYPE_FROM + # or an immediate REC_TYPE_FROM (S). In either case there is no + # REC_TYPE_TIME and we get the timestamp via lstat(). + # + $t = $st[9]; + if ($r ne "S") { + ($r, $l, $d) = rec_get($h); + return unless (defined $r && $r eq "S"); + } + $s = $d; + } else { + # XXX: Not a valid queue file! + # + return undef; + } + while (my ($r, $l, $d) = rec_get($h)) { + if ($r eq "R") { push(@r, $d); } + elsif ($r eq "S") { $s = $d; } + elsif ($r eq "M") { + last unless (defined($s)); + if (defined($dlen)) { + seek($h, $dlen, 1); + ($r, $l, $d) = rec_get($h); + } else { + 1 while ((($r, $l, $d) = rec_get($h)) && ($r =~ /^[NL]$/)); + } + return unless (defined($r) && $r eq "X"); + } + elsif ($r eq "E") { + last unless (defined($t) && defined($s) && @r); + return ($t, $s, @r); + } + } + return (); +} + +# bucket 0 is the total over all the buckets. +# buckets 1 to $bnum contain the age breakdown. +# +sub bucket { + my ($qt, $now) = @_; + my $m = ($now - $qt) / (60 * $tick); + return 1 if ($m < 1); + my $b = 2 + int(log($m) / log(2)); + $b < $bnum ? $b : $bnum; +} + +# Collate by age of message in the selected queues. +# +sub wanted { + if (my ($t, $s, @r) = qenv($_)) { + my $b = bucket($t, $now); + foreach my $a (map {lc($_)} ($opts{"s"} ? ($s) : @r)) { + ++$q{"TOTAL"}->[0]; + ++$q{"TOTAL"}->[$b]; + $a = "MAILER-DAEMON" if ($a eq ""); + $a =~ s/.*\@\.*(.*[^.])?\.*$/$1/; + $a =~ s/\.\././g; + my $new = 0; + do { + my $old = (++$q{$a}->[0] > 1); + ++$q{$a}->[$b]; + ++$sub{$a} if ($new); + $new = ! $old; + } while ($opts{"p"} && $a =~ s/^(?:\.)?[^.]+\.(.*\.)/.$1/); + } + } +} +find(\&wanted, @qlist); + +my @heads; +my $fmt = ""; +my $dw = $width; + +for (my $i = 0, my $t = 0; $i <= $bnum; ) { + $q{"TOTAL"}->[$i] ||= 0; + my $l = length($q{"TOTAL"}->[$i]); + my $h = ($i == 0) ? "T" : $t; + $l = length($h) if (length($h) >= $l); + $l = ($l > 2) ? $l + 1 : 3; + push(@heads, $h); + $fmt .= sprintf "%%%ds", $l; + $dw -= $l; + if (++$i < $bnum) { $t += $t ? $t : $tick; } else { $t = "$t+"; } +} +$dw = $dwidth if ($dw < $dwidth); + +sub pdomain { + my ($d, @count) = @_; + foreach ((0 .. $bnum)) { $count[$_] ||= 0; } + my $len = length($d); + if ($len > $dw) { + if (substr($d, 0, 1) eq ".") { + print ".+",substr($d, $len-$dw+2, $dw-2); + } else { + print "+",substr($d, $len-$dw+1, $dw-1); + } + } else { + print (" " x ($dw - $len), $d); + } + printf "$fmt\n", @count; +} + +# Print headings +# +pdomain("", @heads); + +# Show per-domain totals +# +foreach my $d (sort { $q{$b}->[0] <=> $q{$a}->[0] || + length($a) <=> length($b) } keys %q) { + + # Skip parent domains with < $minsub subdomains. + # + next if ($d =~ /^\./ && $sub{$d} < $minsub); + + pdomain($d, @{$q{$d}}); +} diff --git a/postfix/conf/access b/postfix/conf/access index 65097cc9a..7396b479d 100644 --- a/postfix/conf/access +++ b/postfix/conf/access @@ -16,22 +16,25 @@ # allowed or denied for specific host names, domain names, # networks, host network addresses or mail addresses. # -# Normally, the access table is specified as a text file -# that serves as input to the postmap(1) command. The -# result, an indexed file in dbm or db format, is used for -# fast searching by the mail system. Execute the command -# postmap /etc/postfix/access in order to rebuild the +# For an example, see the EXAMPLE section at the end of this +# manual page. +# +# Normally, the access table is specified as a text file +# that serves as input to the postmap(1) command. The +# result, an indexed file in dbm or db format, is used for +# fast searching by the mail system. Execute the command +# postmap /etc/postfix/access in order to rebuild the # indexed file after changing the access table. # -# When the table is provided via other means such as NIS, -# LDAP or SQL, the same lookups are done as for ordinary +# When the table is provided via other means such as NIS, +# LDAP or SQL, the same lookups are done as for ordinary # indexed files. # -# Alternatively, the table can be provided as a regular- +# Alternatively, the table can be provided as a regular- # expression map where patterns are given as regular expres- -# sions, or lookups can be directed to TCP-based server. In -# that case, the lookups are done in a slightly different -# way as described below under "REGULAR EXPRESSION TABLES" +# sions, or lookups can be directed to TCP-based server. In +# that case, the lookups are done in a slightly different +# way as described below under "REGULAR EXPRESSION TABLES" # and "TCP-BASED TABLES". # # TABLE FORMAT @@ -42,53 +45,53 @@ # address, perform the corresponding action. # # blank lines and comments -# Empty lines and whitespace-only lines are ignored, -# as are lines whose first non-whitespace character +# Empty lines and whitespace-only lines are ignored, +# as are lines whose first non-whitespace character # is a `#'. # # multi-line text -# A logical line starts with non-whitespace text. A -# line that starts with whitespace continues a logi- +# A logical line starts with non-whitespace text. A +# line that starts with whitespace continues a logi- # cal line. # # EMAIL ADDRESS PATTERNS # With lookups from indexed files such as DB or DBM, or from -# networked tables such as NIS, LDAP or SQL, patterns are +# networked tables such as NIS, LDAP or SQL, patterns are # tried in the order as listed below: # # user@domain # Matches the specified mail address. # # domain.tld -# Matches domain.tld as the domain part of an email +# Matches domain.tld as the domain part of an email # address. # # The pattern domain.tld also matches subdomains, but # only when the string smtpd_access_maps is listed in -# the Postfix parent_domain_matches_subdomains con- -# figuration setting (note that this is the default -# for some versions of Postfix). Otherwise, specify -# .domain.tld (note the initial dot) in order to +# the Postfix parent_domain_matches_subdomains con- +# figuration setting (note that this is the default +# for some versions of Postfix). Otherwise, specify +# .domain.tld (note the initial dot) in order to # match subdomains. # -# user@ Matches all mail addresses with the specified user +# user@ Matches all mail addresses with the specified user # part. # -# Note: lookup of the null sender address is not possible -# with some types of lookup table. By default, Postfix uses -# <> as the lookup key for such addresses. The value is -# specified with the smtpd_null_access_lookup_key parameter +# Note: lookup of the null sender address is not possible +# with some types of lookup table. By default, Postfix uses +# <> as the lookup key for such addresses. The value is +# specified with the smtpd_null_access_lookup_key parameter # in the Postfix main.cf file. # # EMAIL ADDRESS EXTENSION # When a mail address localpart contains the optional recip- -# ient delimiter (e.g., user+foo@domain), the lookup order -# becomes: user+foo@domain, user@domain, domain, user+foo@, +# ient delimiter (e.g., user+foo@domain), the lookup order +# becomes: user+foo@domain, user@domain, domain, user+foo@, # and user@. # # HOST NAME/ADDRESS PATTERNS # With lookups from indexed files such as DB or DBM, or from -# networked tables such as NIS, LDAP or SQL, the following +# networked tables such as NIS, LDAP or SQL, the following # lookup patterns are examined in the order as listed: # # domain.tld @@ -96,9 +99,9 @@ # # The pattern domain.tld also matches subdomains, but # only when the string smtpd_access_maps is listed in -# the Postfix parent_domain_matches_subdomains con- +# the Postfix parent_domain_matches_subdomains con- # figuration setting. Otherwise, specify .domain.tld -# (note the initial dot) in order to match subdo- +# (note the initial dot) in order to match subdo- # mains. # # net.work.addr.ess @@ -107,31 +110,45 @@ # # net.work # -# net Matches any host address in the specified network. -# A network address is a sequence of one or more +# net Matches any host address in the specified network. +# A network address is a sequence of one or more # octets separated by ".". # -# NOTE: use the cidr lookup table type to specify +# NOTE: use the cidr lookup table type to specify # network/netmask patterns. See cidr_table(5) for # details. # -# ACTIONS -# [45]NN text -# Reject the address etc. that matches the pattern, -# and respond with the numerical code and text. +# ACCEPT ACTIONS +# OK Accept the address etc. that matches the pattern. +# +# all-numerical +# An all-numerical result is treated as OK. This for- +# mat is generated by address-based relay authoriza- +# tion schemes. +# +# REJECT ACTIONS +# 4NN text +# +# 5NN text +# Reject the address etc. that matches the pattern, +# and respond with the numerical three-digit code and +# text. 4NN means "try again later", while 5NN means +# "do not try again". # # REJECT optional text... -# Reject the address etc. that matches the pattern. -# Reply with $reject_code optional text... when the -# optional text is specified, otherwise reply with a +# Reject the address etc. that matches the pattern. +# Reply with $reject_code optional text... when the +# optional text is specified, otherwise reply with a # generic error response message. # # DEFER_IF_REJECT optional text... -# Defer the request if some later restriction would +# Defer the request if some later restriction would # result in a REJECT action. Reply with "450 optional # text... when the optional text is specified, other- # wise reply with a generic error response message. # +# This feature is available in Postfix 2.1 and later. +# # DEFER_IF_PERMIT optional text... # Defer the request if some later restriction would # result in a an explicit or implicit PERMIT action. @@ -139,69 +156,86 @@ # text is specified, otherwise reply with a generic # error response message. # -# OK Accept the address etc. that matches the pattern. +# This feature is available in Postfix 2.1 and later. # -# all-numerical -# An all-numerical result is treated as OK. This for- -# mat is generated by address-based relay authoriza- -# tion schemes. +# OTHER ACTIONS +# restriction... +# Apply the named UCE restriction(s) (permit, reject, +# reject_unauth_destination, and so on). +# +# DISCARD optional text... +# Claim successful delivery and silently discard the +# message. Log the optional text if specified, oth- +# erwise log a generic message. +# +# Note: this action currently affects all recipients +# of the message. +# +# This feature is available in Postfix 2.0 and later. # # DUNNO Pretend that the lookup key was not found. This # prevents Postfix from trying substrings of the # lookup key (such as a subdomain name, or a network # address subnetwork). # -# PREPEND headername: headervalue -# Prepend the specified message header to the mes- -# sage. When this action is used multiple times, the -# first prepended header appears before the second -# etc. prepended header. +# This feature is available in Postfix 2.0 and later. # -# Note: this action does not support multi-line mes- -# sage headers. +# FILTER transport:destination +# After the message is queued, send the entire mes- +# sage through the specified external content filter. +# The transport:destination syntax is described in +# the transport(5) manual page. More information +# about external content filters is in the Postfix +# FILTER_README file. +# +# Note: this action overrides the main.cf con- +# tent_filter setting, and currently affects all +# recipients of the message. +# +# This feature is available in Postfix 2.0 and later. # # HOLD optional text... -# Place the message on the hold queue, where it will -# sit until someone either deletes it or releases it -# for delivery. Log the optional text if specified, +# Place the message on the hold queue, where it will +# sit until someone either deletes it or releases it +# for delivery. Log the optional text if specified, # otherwise log a generic message. # -# Mail that is placed on hold can be examined with -# the postcat(1) command, and can be destroyed or +# Mail that is placed on hold can be examined with +# the postcat(1) command, and can be destroyed or # released with the postsuper(1) command. # -# Note: this action currently affects all recipients +# Note: this action currently affects all recipients # of the message. # -# DISCARD optional text... -# Claim successful delivery and silently discard the -# message. Log the optional text if specified, oth- -# erwise log a generic message. +# This feature is available in Postfix 2.0 and later. # -# Note: this action currently affects all recipients -# of the message. +# PREPEND headername: headervalue +# Prepend the specified message header to the mes- +# sage. When this action is used multiple times, the +# first prepended header appears before the second +# etc. prepended header. # -# FILTER transport:destination -# After the message is queued, send the entire mes- -# sage through the specified external content filter. -# More information about external content filters is -# in the Postfix FILTER_README file. +# Note: this action does not support multi-line mes- +# sage headers. # -# Note: this action overrides the main.cf con- -# tent_filter setting, and currently affects all -# recipients of the message. +# This feature is available in Postfix 2.1 and later. # # REDIRECT user@domain -# After the message is queued, send the message to +# After the message is queued, send the message to # the specified address instead of the intended # recipient(s). # -# Note: this action overrides the FILTER action, and +# Note: this action overrides the FILTER action, and # currently affects all recipients of the message. # -# restriction... -# Apply the named UCE restriction(s) (permit, reject, -# reject_unauth_destination, and so on). +# This feature is available in Postfix 2.1 and later. +# +# WARN optional text... +# Log a warning with the optional text, together with +# client information and if available, with helo, +# sender, recipient and protocol information. +# +# This feature is available in Postfix 2.1 and later. # # REGULAR EXPRESSION TABLES # This section describes how the table lookups change when @@ -230,28 +264,53 @@ # This section describes how the table lookups change when # lookups are directed to a TCP-based server. For a descrip- # tion of the TCP client/server lookup protocol, see -# tcp_table(5). +# tcp_table(5). This feature is not available in Postfix +# version 2.1. # -# Each lookup operation uses the entire query string once. -# Depending on the application, that string is an entire +# Each lookup operation uses the entire query string once. +# Depending on the application, that string is an entire # client hostname, an entire client IP address, or an entire -# mail address. Thus, no parent domain or parent network -# search is done, user@domain mail addresses are not broken -# up into their user@ and domain constituent parts, nor is +# mail address. Thus, no parent domain or parent network +# search is done, user@domain mail addresses are not broken +# up into their user@ and domain constituent parts, nor is # user+foo broken up into user and foo. # # Actions are the same as with indexed file lookups. # +# EXAMPLE +# The following example uses an indexed file, so that the +# order of table entries does not matter. The example per- +# mits access by the client at address 1.2.3.4 but rejects +# all other clients in 1.2.3.0/24. Instead of "hash" lookup +# tables, some systems use "dbm". Use the command "postconf +# -m" to find out what lookup tables Postfix supports on +# your system. +# +# /etc/postfix/main.cf: +# smtpd_client_restrictions = +# check_client_access hash:/etc/postfix/access +# +# /etc/postfix/access: +# 1.2.3 REJECT +# 1.2.3.4 OK +# +# Execute the command "postmap /etc/postfix/access" after +# editing the file. +# # BUGS -# The table format does not understand quoting conventions. +# The table format does not understand quoting conventions. # # SEE ALSO -# postmap(1) create lookup table -# smtpd(8) smtp server -# cidr_table(5) format of CIDR tables -# pcre_table(5) format of PCRE tables -# regexp_table(5) format of POSIX regular expression tables -# tcp_table(5) TCP client/server table lookup protocol +# postmap(1), Postfix lookup table manager +# smtpd(8), SMTP server +# postconf(5), configuration parameters +# transport(5), transport:nexthop syntax +# +# README FILES +# Use "postconf readme_directory" or "postconf html_direc- +# tory" to locate this information. +# SMTPD_ACCESS_README, built-in SMTP server access control +# DATABASE_README, Postfix lookup table overview # # LICENSE # The Secure Mailer license must be distributed with this diff --git a/postfix/conf/aliases b/postfix/conf/aliases index b5da8eef3..a6690b232 100644 --- a/postfix/conf/aliases +++ b/postfix/conf/aliases @@ -135,49 +135,58 @@ decode: root # address (e.g., user). # # CONFIGURATION PARAMETERS -# The following main.cf parameters are especially relevant -# to this topic. See the Postfix main.cf file for syntax -# details and for default values. Use the postfix reload -# command after a configuration change. +# The following main.cf parameters are especially relevant. +# The text below provides only a parameter summary. See +# postconf(5) for more details including examples. +# +# alias_database +# List of alias databases that are updated by the +# newaliases(1) command. # # alias_maps -# List of alias databases. +# List of alias databases queried by the local(8) +# delivery agent. # # allow_mail_to_commands -# Restrict the usage of mail delivery to external +# Restrict the usage of mail delivery to external # command. # # allow_mail_to_files -# Restrict the usage of mail delivery to external +# Restrict the usage of mail delivery to external # file. # # expand_owner_alias # When delivering to an alias that has an owner- com- -# panion alias, set the envelope sender address to -# the right-hand side of the owner alias, instead +# panion alias, set the envelope sender address to +# the right-hand side of the owner alias, instead # using of the left-hand side address. # # owner_request_special -# Give special treatment to owner-xxx and xxx-request -# addresses. +# Give special treatment to owner-listname and list- +# name-request addresses. # # recipient_delimiter -# Delimiter that separates recipients from address +# Delimiter that separates recipients from address # extensions. # # BUGS -# Regular expression alias lookup tables are allowed, but -# substitution of $1 etc. is forbidden because that would +# Regular expression alias lookup tables are allowed, but +# substitution of $1 etc. is forbidden because that would # open a security loophole. # # STANDARDS # RFC 822 (ARPA Internet Text Messages) # # SEE ALSO -# local(8) local delivery agent -# newaliases(1) alias database management -# regexp_table(5) POSIX regular expression table format -# pcre_table(5) Perl Compatible Regular Expression table format +# local(8), local delivery agent +# newaliases(1), create/update alias database +# postalias(1), create/update alias database +# postconf(5), configuration parameters +# +# README FILES +# Use "postconf readme_directory" or "postconf html_direc- +# tory" to locate this information. +# DATABASE_README, Postfix lookup table overview # # LICENSE # The Secure Mailer license must be distributed with this diff --git a/postfix/conf/canonical b/postfix/conf/canonical index 66ceacad9..2fb6ad24c 100644 --- a/postfix/conf/canonical +++ b/postfix/conf/canonical @@ -129,23 +129,23 @@ # This section describes how the table lookups change when # lookups are directed to a TCP-based server. For a descrip- # tion of the TCP client/server lookup protocol, see -# tcp_table(5). +# tcp_table(5). This feature is not available in Postfix +# version 2.1. # # Each lookup operation uses the entire address once. Thus, -# user@domain mail addresses are not broken up into their +# user@domain mail addresses are not broken up into their # user and @domain constituent parts, nor is user+foo broken # up into user and foo. # # Results are the same as with indexed file lookups. # # BUGS -# The table format does not understand quoting conventions. +# The table format does not understand quoting conventions. # # CONFIGURATION PARAMETERS -# The following main.cf parameters are especially relevant -# to this topic. See the Postfix main.cf file for syntax -# details and for default values. Use the postfix reload -# command after a configuration change. +# The following main.cf parameters are especially relevant. +# The text below provides only a parameter summary. See +# postconf(5) for more details including examples. # # canonical_maps # List of canonical mapping tables. @@ -202,15 +202,19 @@ # addresses. # # SEE ALSO -# cleanup(8) canonicalize and enqueue mail -# postmap(1) create mapping table -# virtual(5) virtual domain mapping -# pcre_table(5) format of PCRE tables -# regexp_table(5) format of POSIX regular expression tables -# tcp_table(5) TCP client/server table lookup protocol +# cleanup(8), canonicalize and enqueue mail +# postmap(1), Postfix lookup table manager +# postconf(5), configuration parameters +# virtual(5), virtual aliasing +# +# README FILES +# Use "postconf readme_directory" or "postconf html_direc- +# tory" to locate this information. +# DATABASE_README, Postfix lookup table overview +# ADDRESS_REWRITING_README, address rewriting guide # # LICENSE -# The Secure Mailer license must be distributed with this +# The Secure Mailer license must be distributed with this # software. # # AUTHOR(S) diff --git a/postfix/conf/header_checks b/postfix/conf/header_checks index f272874c0..dcb25d5ae 100644 --- a/postfix/conf/header_checks +++ b/postfix/conf/header_checks @@ -7,110 +7,124 @@ # header_checks = pcre:/etc/postfix/header_checks # mime_header_checks = pcre:/etc/postfix/mime_header_checks # nested_header_checks = pcre:/etc/postfix/nested_header_checks -# # body_checks = pcre:/etc/postfix/body_checks # -# postmap -q "string" pcre:/etc/postfix/filename -# postmap -q - pcre:/etc/postfix/filename $/ -# REJECT IFRAME vulnerability exploit +# /etc/postfix/main.cf: +# header_checks = regexp:/etc/postfix/header_checks +# +# /etc/postfix/header_checks: +# /^