Adding upstream version 3.8.5.upstream/3.8.5

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 492 insertions, 0 deletions

diff --git a/README_FILES/OVERVIEW b/README_FILES/OVERVIEW
new file mode 100644
index 0000000..71976d4
--- /dev/null
+++ b/README_FILES/OVERVIEW
@@ -0,0 +1,492 @@
+PPoossttffiixx AArrcchhiitteeccttuurree OOvveerrvviieeww
+
+-------------------------------------------------------------------------------
+
+IInnttrroodduuccttiioonn
+
+This document presents an overview of the Postfix architecture, and provides
+pointers to descriptions of 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, and 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), discard(8) or error(8) delivery agents, and sends a
+    delivery request for one or more recipient addresses. The discard(8) and
+    error(8) delivery agents are special: they discard or bounce all mail, and
+    are 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 or 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 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 <sysexits.h>. 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. The text below attempts to visualize each service 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 request 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 available
+    in Postfix version 2.2 and later.
+
+    Network -> smtpd(8) <-> anvil(8)
+
+  * The bounce(8), defer(8) and trace(8) services each maintain their own queue
+    directory trees with per-message logfiles. Postfix uses this information
+    when sending "failed", "delayed" or "success" delivery status notifications
+    to the sender.
+
+    The trace(8) service also 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 and read-write table lookup
+    service to Postfix processes. This overcomes chroot restrictions, reduces
+    the number of open lookup tables by sharing one open table among multiple
+    processes, and implements single-updater tables.
+
+  * The scache(8) server maintains the connection cache for the Postfix smtp(8)
+    client. When connection caching is enabled for selected destinations, the
+    smtp(8) client does not disconnect immediately after a mail transaction,
+    but gives the connection to the connection cache server which keeps the
+    connection open for a limited amount of time. The smtp(8) client continues
+    with some other mail delivery request. Meanwhile, any smtp(8) process can
+    ask the scache(8) server for that cached connection and reuse it for mail
+    delivery. As a safety measure, Postfix limits the number of times that a
+    connection may be reused.
+
+    When delivering mail to a destination with multiple mail servers,
+    connection caching can help to skip over a non-responding server, and thus
+    dramatically speed up delivery. SMTP connection caching is available in
+    Postfix version 2.2 and later. More information about this feature is in
+    the CONNECTION_CACHE_README document.
+
+            /--  smtp(8)  --> Internet
+
+    qmgr(8)
+                |
+            \-- |    smtp(8)
+                |
+                |     ^
+                v     |
+
+                scache(8)
+
+    A Postfix smtp(8) client can reuse a TLS-encrypted connection (with
+    "smtp_tls_connection_reuse = yes"). This can greatly reduce the overhead of
+    connection setup and improves message delivery rates. After a Postfix smtp
+    (8) client connects to a remote SMTP server and sends plaintext EHLO and
+    STARTTLS commands, the smtp(8) client inserts a tlsproxy(8) process into
+    the connection as shown below.
+
+    After the mail transaction completes, the Postfix smtp(8) client gives the
+    smtp(8)-to-tlsproxy(8) connection to the scache(8) server, which keeps the
+    connection open for a limited amount of time. The smtp(8) client continues
+    with some other mail delivery request. Meanwhile, any Postfix smtp(8)
+    client can ask the scache(8) server for that cached connection and reuse it
+    for mail delivery.
+
+            /--  smtp(8)  --> tlsproxy(8) --> Internet
+
+    qmgr(8)
+                |
+            \-- |    smtp(8)
+                |
+                |     ^
+                v     |
+
+                scache(8)
+
+  * 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 tlsmgr(8) server runs when TLS (Transport Layer Security, formerly
+    known as SSL) is turned on in the Postfix smtp(8) client or smtpd(8)
+    server. This process has two duties:
+
+      o Maintain the pseudo-random number generator (PRNG) that is used to seed
+        the TLS engines in Postfix smtp(8) client or smtpd(8) server processes.
+        The state of this PRNG is periodically saved to a file, and is read
+        when tlsmgr(8) starts up.
+
+      o Maintain the optional Postfix smtp(8) client or smtpd(8) server caches
+        with TLS session keys. Saved keys can improve performance by reducing
+        the amount of computation at the start of a TLS session.
+
+    TLS support is available in Postfix version 2.2 and later. Information
+    about the Postfix TLS implementation is in the TLS_README document.
+
+                        <---seed---            ---seed--->
+    Network-> smtpd(8)              tlsmgr(8)               smtp(8)  ->Network
+                        <-session->            <-session->
+
+                                  /       |    \
+                                          |
+                                /                \
+
+                         smtpd          PRNG        smtp
+                        session        state       session
+                         cache          file        cache
+
+  * The verify(8) server verifies that a sender or recipient address is
+    deliverable before the smtpd(8) server accepts it. The verify(8) server
+    queries a cache with address verification results. If a result is not
+    found, the verify(8) server injects a probe message into the Postfix queue
+    and processes the status update from a delivery agent or queue manager.
+    This process is described in the ADDRESS_VERIFICATION_README document. The
+    verify(8) service is available with Postfix version 2.1 and later.
+
+                                             probe     Postfix
+                                            message ->   mail
+    Network -> smtpd(8) <->   verify(8)  ->             queue
+
+                                                            |
+                                                            v
+
+                                         <-  probe     Postfix  -> Local
+                                            status  <- delivery -> Network
+                                    ^                   agents
+                                    |
+                                    v
+
+                              Address
+                            verification
+                               cache
+
+  * The postscreen(8) server can be put "in front" of Postfix smtpd(8)
+    processes. Its purpose is to accept connections from the network and to
+    decide what SMTP clients are allowed to talk to Postfix. According to the
+    2008 MessageLabs annual report, 81% of all email was spam, and 90% of that
+    was sent by botnets; by 2010, those numbers were 92% and 95%, respectively.
+    While postscreen(8) keeps the zombies away, more smtpd(8) processes remain
+    available for legitimate clients.
+
+    postscreen(8) maintains a temporary allowlist for clients that pass its
+    tests; by allowing allowlisted clients to skip tests, postscreen(8)
+    minimizes its impact on legitimate email traffic.
+
+    The postscreen(8) server is available with Postfix 2.8 and later. To keep
+    the implementation simple, postscreen(8) delegates DNS allow/denylist
+    lookups to dnsblog(8) server processes, and delegates TLS encryption/
+    decryption to tlsproxy(8) server processes. This delegation is invisible to
+    the remote SMTP client.
+
+                zombie
+
+                         \
+
+    zombie - tlsproxy(8) -                    - smtpd(8)
+
+                           \               /
+
+                 other   --- postscreen(8)
+
+                           /               \
+
+                 other   -                    - smtpd(8)
+
+                         /
+
+                zombie
+
+  * The postlogd(8) server provides an alternative to syslog logging, which
+    remains the default. This feature is available with Postfix version 3.4 or
+    later, and supports the following modes:
+
+      o Logging to file, which addresses a usability problem with MacOS, and
+        eliminates information loss caused by systemd rate limits.
+
+         commands    -> postlogd(8) -> /path/to/file
+        or daemons
+
+      o Logging to stdout, which eliminates a syslog dependency when Postfix
+        runs inside a container.
+
+         commands  -> postlogd(8) ->    stdout inherited
+        or daemons                   from "postfix start-fg"
+
+    See MAILLOG_README for details and limitations.
+
+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 postmulti(1) command repeats the "postfix start" etc. command for each
+    Postfix instance, and supports creation, deletion etc. of Postfix
+    instances. For a tutorial, see MULTI_INSTANCE_README.
+
+  * 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.
+