external/ibm-public/postfix/dist/README_FILES/SMTPD_PROXY_README

   1 P\bPo\bos\bst\btf\bfi\bix\bx B\bBe\bef\bfo\bor\bre\be-\b-Q\bQu\bue\beu\bue\be C\bCo\bon\bnt\bte\ben\bnt\bt F\bFi\bil\blt\bte\ber\br
   2
   3 -------------------------------------------------------------------------------
   4
   5 W\bWA\bAR\bRN\bNI\bIN\bNG\bG
   6
   7 The before-queue content filtering feature described in this document is
   8 suitable only for low-traffic sites. See the "Pros and Cons" section below for
   9 details.
  10
  11 T\bTh\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx b\bbe\bef\bfo\bor\bre\be-\b-q\bqu\bue\beu\bue\be c\bco\bon\bnt\bte\ben\bnt\bt f\bfi\bil\blt\bte\ber\br f\bfe\bea\bat\btu\bur\bre\be
  12
  13 As of version 2.1, the Postfix SMTP server can forward all incoming mail to a
  14 content filtering proxy server that inspects all mail BEFORE it is stored in
  15 the Postfix mail queue. It is roughly equivalent in capabilities to the
  16 approach described in MILTER_README, except that the latter uses a dedicated
  17 protocol instead of SMTP.
  18
  19 The before-queue content filter is meant to be used as follows:
  20
  21                 Postfix    B\bBe\bef\bfo\bor\bre\be    Postfix    Postfix    Postfix     smtp
  22     Internet ->  SMTP   -> q\bqu\bue\beu\bue\be  ->  SMTP   -> cleanup ->  queue  -<  local
  23                 server     f\bfi\bil\blt\bte\ber\br    server     server                virtual
  24
  25 The before-queue content filter is not to be confused with the approach
  26 described in the FILTER_README document, where mail is filtered AFTER it is
  27 stored in the Postfix mail queue.
  28
  29 This document describes the following topics:
  30
  31   * Principles of operation
  32   * Pros and cons of before-queue content filtering
  33   * Configuring the Postfix SMTP pass-through proxy feature
  34   * Configuration parameters
  35   * How Postfix talks to the before-queue content filter
  36
  37 P\bPr\bri\bin\bnc\bci\bip\bpl\ble\bes\bs o\bof\bf o\bop\bpe\ber\bra\bat\bti\bio\bon\bn
  38
  39 The before-filter Postfix SMTP server accepts connections from the Internet and
  40 does the usual relay access control, SASL authentication, TLS negotiation, RBL
  41 lookups, rejecting non-existent sender or recipient addresses, etc. The before-
  42 queue filter receives unfiltered mail content from Postfix and does one of the
  43 following:
  44
  45  1. Re-inject the mail back into Postfix via SMTP, perhaps after changing its
  46     content and/or destination.
  47
  48  2. Discard or quarantine the mail.
  49
  50  3. Reject the mail by sending a suitable SMTP status code back to Postfix.
  51     Postfix passes the status back to the remote SMTP client. This way, Postfix
  52     does not have to send a bounce message.
  53
  54 The after-filter Postfix SMTP server receives mail from the content filter.
  55 From then on Postfix processes the mail as usual.
  56
  57 The before-queue content filter described here works just like the after-queue
  58 content filter described in the FILTER_README document. In many cases you can
  59 use the same software, within the limitations as discussed in the "Pros and
  60 Cons" section below.
  61
  62 P\bPr\bro\bos\bs a\ban\bnd\bd c\bco\bon\bns\bs o\bof\bf b\bbe\bef\bfo\bor\bre\be-\b-q\bqu\bue\beu\bue\be c\bco\bon\bnt\bte\ben\bnt\bt f\bfi\bil\blt\bte\ber\bri\bin\bng\bg
  63
  64   * Pro: Postfix can reject mail before the incoming SMTP mail transfer
  65     completes, so that Postfix does not have to send rejected mail back to the
  66     sender (which is usually forged anyway). Mail that is not accepted remains
  67     the responsibility of the remote SMTP client.
  68
  69   * Con: The remote SMTP client expects an SMTP reply within a deadline. As the
  70     system load increases, fewer and fewer CPU cycles remain available to
  71     answer within the deadline, and eventually you either have to stop
  72     accepting mail or you have to stop filtering mail. It is for this reason
  73     that the before-queue content filter can be used only on low-traffic sites.
  74
  75   * Con: Content filtering software can use lots of memory resources. In order
  76     to not run out of memory you have to reduce the number of before-filter
  77     SMTP server processes so that a burst of mail will not drive your system
  78     into the ground with too many content filter processes. This, in turn,
  79     means that SMTP clients have to wait for a long time before they receive
  80     service.
  81
  82 C\bCo\bon\bnf\bfi\big\bgu\bur\bri\bin\bng\bg t\bth\bhe\be P\bPo\bos\bst\btf\bfi\bix\bx S\bSM\bMT\bTP\bP p\bpa\bas\bss\bs-\b-t\bth\bhr\bro\bou\bug\bgh\bh p\bpr\bro\box\bxy\by f\bfe\bea\bat\btu\bur\bre\be
  83
  84 In the following example, the before-filter Postfix SMTP server gives mail to a
  85 content filter that listens on localhost port 10025. The after-filter Postfix
  86 SMTP server receives mail from the content filter via localhost port 10026.
  87 From then on mail is processed as usual.
  88
  89 The content filter itself is not described here. You can use any filter that is
  90 SMTP enabled. For non-SMTP capable content filtering software, Bennett Todd's
  91 SMTP proxy implements a nice PERL/SMTP content filtering framework. See: http:/
  92 /bent.latency.net/smtpprox/.
  93
  94                                                Postfix
  95                   Postfix      filter on     SMTP server    Postfix    Postfix
  96     Internet -> SMTP server -> localhost  ->     on      -> cleanup -> incoming
  97                 on port 25     port 10025     localhost     server      queue
  98                                              port 10026
  99
 100 This is configured by editing the master.cf file:
 101
 102     /etc/postfix/master.cf:
 103         # =============================================================
 104         # service type  private unpriv  chroot  wakeup  maxproc command
 105         #               (yes)   (yes)   (yes)   (never) (100)
 106         # =============================================================
 107         #
 108         # Before-filter SMTP server. Receive mail from the network and
 109         # pass it to the content filter on localhost port 10025.
 110         #
 111         smtp      inet  n       -       n       -       20      smtpd
 112             -o smtpd_proxy_filter=127.0.0.1:10025
 113             -o smtpd_client_connection_count_limit=10
 114         #
 115         # After-filter SMTP server. Receive mail from the content filter
 116         # on localhost port 10026.
 117         #
 118         127.0.0.1:10026 inet n  -       n       -        -      smtpd
 119             -o smtpd_authorized_xforward_hosts=127.0.0.0/8
 120             -o smtpd_client_restrictions=
 121             -o smtpd_helo_restrictions=
 122             -o smtpd_sender_restrictions=
 123             -o smtpd_recipient_restrictions=permit_mynetworks,reject
 124             -o smtpd_data_restrictions=
 125             -o mynetworks=127.0.0.0/8
 126             -o receive_override_options=no_unknown_recipient_checks
 127
 128 Note: do not specify spaces around the "=" or "," characters.
 129
 130 The before-filter SMTP server entry is a modified version of the default
 131 Postfix SMTP server entry that is normally configured at the top of the
 132 master.cf file:
 133
 134   * The number of SMTP sessions is reduced from the default 100 to only 20.
 135     This prevents a burst of mail from running your system into the ground with
 136     too many content filter processes.
 137
 138   * The "-o smtpd_client_connection_count_limit=10" prevents one SMTP client
 139     from using up all 20 SMTP server processes. This limit is not necessary if
 140     you receive all mail from a trusted relay host.
 141
 142     Note: this setting is available in Postfix version 2.2 and later. Earlier
 143     Postfix versions will ignore it.
 144
 145   * The "-o smtpd_proxy_filter=127.0.0.1:10025" tells the before filter SMTP
 146     server that it should give incoming mail to the content filter that listens
 147     on localhost TCP port 10025.
 148
 149   * Postfix 2.3 supports both TCP and UNIX-domain filters. The above filter
 150     could be specified as "inet:127.0.0.1:10025". To specify a UNIX-domain
 151     filter, specify "unix:pathname". A relative pathname is interpreted
 152     relative to the Postfix queue directory.
 153
 154 The after-filter SMTP server is a new master.cf entry:
 155
 156   * The "127.0.0.1:10026" makes the after-filter SMTP server listen on the
 157     localhost address only, without exposing it to the network. NEVER expose
 158     the after-filter SMTP server to the Internet :-)
 159
 160   * The "-o smtpd_authorized_xforward_hosts=127.0.0.0/8" allows the after-
 161     filter SMTP server to receive remote SMTP client information from the
 162     before filter SMTP server, so that the after-filter Postfix daemons log the
 163     remote SMTP client information instead of logging localhost[127.0.0.1].
 164
 165   * The other after-filter SMTP server settings avoid duplication of work that
 166     is already done in the "before filter" SMTP server.
 167
 168 By default, the filter has 100 seconds to do its work. If it takes longer then
 169 Postfix gives up and reports an error to the remote SMTP client. You can
 170 increase this time limit (see configuration parameter section below) but doing
 171 so is pointless because you can't control when the remote SMTP client times
 172 out.
 173
 174 C\bCo\bon\bnf\bfi\big\bgu\bur\bra\bat\bti\bio\bon\bn p\bpa\bar\bra\bam\bme\bet\bte\ber\brs\bs
 175
 176 Parameters that control proxying:
 177
 178   * smtpd_proxy_filter (syntax: host:port): The host and TCP port of the
 179     before-queue content filter. When no host or host: is specified here,
 180     localhost is assumed.
 181
 182   * smtpd_proxy_timeout (default: 100s): Timeout for connecting to the before-
 183     queue content filter and for sending and receiving commands and data. All
 184     proxy errors are logged to the maillog file. For privacy reasons, all the
 185     remote SMTP client sees is "451 Error: queue file write error". It would
 186     not be right to disclose internal details to strangers.
 187
 188   * smtpd_proxy_ehlo (default: $myhostname): The hostname to use when sending
 189     an EHLO command to the before-queue content filter.
 190
 191 H\bHo\bow\bw P\bPo\bos\bst\btf\bfi\bix\bx t\bta\bal\blk\bks\bs t\bto\bo t\bth\bhe\be b\bbe\bef\bfo\bor\bre\be-\b-q\bqu\bue\beu\bue\be c\bco\bon\bnt\bte\ben\bnt\bt f\bfi\bil\blt\bte\ber\br
 192
 193 The before-filter Postfix SMTP server connects to the content filter, delivers
 194 one message, and disconnects. While sending mail into the content filter,
 195 Postfix speaks ESMTP but uses no command pipelining. Postfix generates its own
 196 EHLO, XFORWARD (for logging the remote client IP address instead of localhost
 197 [127.0.0.1]), DATA and QUIT commands, and forwards unmodified copies of all the
 198 MAIL FROM and RCPT TO commands that the before-filter Postfix SMTP server
 199 didn't reject itself. Postfix sends no other SMTP commands.
 200
 201 The content filter should accept the same MAIL FROM and RCPT TO command syntax
 202 as the before-filter Postfix SMTP server, and should forward the commands
 203 without modification to the after-filter SMTP server. If the content filter or
 204 after-filter SMTP server does not support all the ESMTP features that the
 205 before-filter Postfix SMTP server supports, then the missing features must be
 206 turned off in the before-filter Postfix SMTP server with the
 207 smtpd_discard_ehlo_keywords parameter.
 208
 209 When the filter rejects content, it should send a negative SMTP response back
 210 to the before-filter Postfix SMTP server, and it should abort the connection
 211 with the after-filter Postfix SMTP server without completing the SMTP
 212 conversation with the after-filter Postfix SMTP server.
 213