PPoossttffiixx bbeeffoorree--qquueeuuee MMiilltteerr ssuuppppoorrtt

-------------------------------------------------------------------------------

IInnttrroodduuccttiioonn

Postfix version 2.3 introduces support for the Sendmail version 8 Milter (mail
filter) protocol. This protocol is used by applications that run outside the
MTA to inspect SMTP events (CONNECT, DISCONNECT), SMTP commands (HELO, MAIL
FROM, etc.) as well as mail content. All this happens before mail is queued.

The reason for adding Milter support to Postfix is that there exists a large
collection of applications, not only to block unwanted mail, but also to verify
authenticity (examples: SenderID+SPF and Domain keys) or to digitally sign mail
(example: Domain keys). Having yet another Postfix-specific version of all that
software is a poor use of human and system resources.

Postfix 2.3 implements all the requests of Sendmail version 8 Milter protocols
up to version 4, except one: message body replacement. See, however, the
workarounds and limitations sections at the end of this document.

This document provides information on the following topics:

  * How Milter applications plug into Postfix
  * Building Milter applications
  * Running Milter applications
  * Configuring Postfix
  * Workarounds
  * Limitations

HHooww MMiilltteerr aapppplliiccaattiioonnss pplluugg iinnttoo PPoossttffiixx

The Postfix Milter implementation uses two different lists of mail filters: one
list of filters that are used for SMTP mail only, and one list of filters that
are used for non-SMTP mail. The two lists have different capabilities, which is
unfortunate. Avoiding this would require major restructuring of Postfix.

  * The SMTP-only filters handle mail that arrives via the Postfix smtpd(8)
    server. They are typically used to filter unwanted mail and to sign mail
    from authorized SMTP clients. You specify SMTP-only Milter applications
    with the smtpd_milters parameter as described in a later section. Mail that
    arrives via the Postfix smtpd(8) server is not filtered by the non-SMTP
    filters that are described next.

  * The non-SMTP filters handle mail that arrives via the Postfix sendmail(1)
    command-line or via the Postfix qmqpd(8) server. They are typically used to
    digitally sign mail only. Although non-SMTP filters can be used to filter
    unwanted mail, they have limitations compared to the SMTP-only filters. You
    specify non-SMTP Milter applications with the non_smtpd_milters parameter
    as described in a later section.

For those who are familiar with the Postfix architecture, the figure below
shows how Milter applications plug into Postfix. Names followed by a number are
Postfix commands or server programs, while unnumbered names inside shaded areas
represent Postfix queues. To avoid clutter, the path for local submission is
simplified (the OVERVIEW document has a more complete description).

               SMTP-only      non-SMTP
                 filters       filters

                     ^ |
                     | v
                                   ^ |
                                   | |
    Network ->   smtpd(8)          | |
                                   | v

                           \

    Network ->   qmqpd(8)  -> cleanup(8) -> incoming

                           /

                pickup(8)

                      :

    Local   -> sendmail(1)

BBuuiillddiinngg MMiilltteerr aapppplliiccaattiioonnss

Milter applications have been written in C, JAVA and Perl, but this document
deals with C applications only. For these, you need an object library that
implements the Sendmail 8 Milter protocol. Postfix currently does not provide
such a library, but Sendmail does.

On some Linux and *BSD distributions, the Sendmail libmilter library is
installed by default. With this, applications such as dk-milter and sid-milter
build out of the box without requiring any tinkering:

    $ ggzzccaatt ddkk--mmiilltteerr--xx..yy..zz..ttaarr..ggzz || ttaarr xxff --
    $ ccdd ddkk--mmiilltteerr--xx..yy..zz
    $ mmaakkee
    [...lots of output omitted...]

On other platforms you have two options:

  * Install the Sendmail libmilter object library and include files. On Linux
    systems, libmilter may be provided by the sendmail-devel package. After
    installing libmilter, build the Milter applications as described in the
    preceding paragraph.

  * Don't install the Sendmail libmilter library, but build the library from
    Sendmail source code instead:

        $ ggzzccaatt sseennddmmaaiill--xx..yy..zz..ttaarr..ggzz || ttaarr xxff --
        $ ccdd sseennddmmaaiill--xx..yy..zz//lliibbmmiilltteerr
        $ mmaakkee
        [...lots of output omitted...]

    After building your own libmilter library, follow the installation
    instructions in the Milter application source distribution to specify the
    location of the libmilter include files and object library. Typically,
    these settings are configured in a file named sid-filter/Makefile.m4 or
    similar:

        APPENDDEF(`confINCDIRS', `-I/some/where/sendmail-x.y.z/include')
        APPENDDEF(`confLIBDIRS', `-L/some/where/sendmail-x.y.z/obj.systemtype/
        libmilter')

    Then build the Milter application.

RRuunnnniinngg MMiilltteerr aapppplliiccaattiioonnss

To run a Milter application, see the documentation of the filter for options. A
typical command looks like this:

    # //ssoommee//wwhheerree//ddkk--ffiilltteerr --uu uusseerriidd --pp iinneett::ppoorrttnnuummbbeerr@@llooccaallhhoosstt ......ootthheerr
    ooppttiioonnss......

Please specify a userid value that isn't used for other applications (not
"postfix", not "www", etc.).

CCoonnffiigguurriinngg PPoossttffiixx

Like Sendmail, Postfix has a lot of configuration options that control how it
talks to Milter applications. With the initial Postfix Milter protocol
implementation, many options are global, that is, they apply to all Milter
applications. Future Postfix versions may support per-Milter timeouts, per-
Milter error handling, etc.

Information in this section:

  * SMTP-Only Milter applications
  * Non-SMTP Milter applications
  * Milter error handling
  * Milter protocol version
  * Milter protocol timeouts
  * Sendmail macro emulation

SSMMTTPP--OOnnllyy MMiilltteerr aapppplliiccaattiioonnss

The SMTP-only Milter applications handle mail that arrives via the Postfix
smtpd(8) server. They are typically used to filter unwanted mail, and to sign
mail from authorized SMTP clients. Mail that arrives via the Postfix smtpd(8)
server is not filtered by the non-SMTP filters that are described in the next
section.

NOTE: Do not use the header_checks(5) IGNORE action to remove Postfix's own
Received: message header. This causes problems with mail signing filters.
Instead, keep Postfix's own Received: message header and use the header_checks
(5) REPLACE action to sanitize information.

You specify SMTP-only Milter applications (there can be more than one) with the
smtpd_milters parameter. Each Milter application is identified by the name of
its listening socket; other Milter configuration options will be discussed in
later sections. Milter applications are applied in the order as specified, and
the first Milter application that rejects a command will override the responses
from other Milter applications.

    /etc/postfix/main.cf:
        # Milters for mail that arrives via the smtpd(8) server.
        # See below for socket address syntax.
        smtpd_milters = inet:localhost:portnumber ...other filters...

The general syntax for listening sockets is as follows:

    uunniixx::pathname
        Connect to the local UNIX-domain server that is bound to the specified
        pathname. If the smtpd(8) or cleanup(8) process runs chrooted, an
        absolute pathname is interpreted relative to the Postfix queue
        directory.

    iinneett::host::port
        Connect to the specified TCP port on the specified local or remote
        host. The host and port can be specified in numeric or symbolic form.

        NOTE: Postfix syntax differs from Milter syntax which has the form
        iinneett::port@@host.

NNoonn--SSMMTTPP MMiilltteerr aapppplliiccaattiioonnss

The non-SMTP Milter applications handle mail that arrives via the Postfix
sendmail(1) command-line or via the Postfix qmqpd(8) server. They are typically
used to digitally sign mail. Although non-SMTP filters can be used to filter
unwanted mail, there are limitations as discussed later in this section. Mail
that arrives via the Postfix smtpd(8) server is not filtered by the non-SMTP
filters.

NOTE: Do not use the header_checks(5) IGNORE action to remove Postfix's own
Received: message header. This causes problems with mail signing filters.
Instead, keep Postfix's own Received: message header and use the header_checks
(5) REPLACE action to sanitize information.

You specify non-SMTP Milter applications with the non_smtpd_milters parameter.
This parameter uses the same syntax as the smtpd_milters parameter in the
previous section. As with the SMTP-only filters, you can specify more than one
Milter application; they are applied in the order as specified, and the first
Milter application that rejects a command will override the responses from the
other applications.

    /etc/postfix/main.cf:
        # Milters for non-SMTP mail.
        # See below for socket address syntax.
        non_smtpd_milters = inet:localhost:portnumber ...other filters...

There's one small complication when using Milter applications for non-SMTP
mail: there is no SMTP session. To keep Milter applications happy, the Postfix
cleanup(8) server actually has to simulate the SMTP client CONNECT and
DISCONNECT events, and the SMTP client EHLO, MAIL FROM, RCPT TO and DATA
commands.

  * When new mail arrives via the sendmail(1) command line, the Postfix cleanup
    (8) server pretends that the mail arrives with ESMTP from "localhost" with
    IP address "127.0.0.1". The result is very similar to what happens with
    command line submissions in Sendmail version 8.12 and later, although
    Sendmail uses a different mechanism to achieve this result.

  * When new mail arrives via the qmqpd(8) server, the Postfix cleanup(8)
    server pretends that the mail arrives with ESMTP, and uses the QMQPD client
    hostname and IP address.

  * When old mail is re-injected into the queue with "postsuper -r", the
    Postfix cleanup(8) server uses the same client information that was used
    when the mail arrived as new mail.

This generally works as expected, with only one exception: non-SMTP filters
must not REJECT or TEMPFAIL simulated RCPT TO commands. When a
non_smtpd_milters application REJECTs or TEMPFAILs a recipient, Postfix will
report a configuration error, and mail will stay in the queue.

None of this is a problem for mail filters that digitally sign mail.

MMiilltteerr eerrrroorr hhaannddlliinngg

The milter_default_action parameter specifies how Postfix handles Milter
application errors. The default action is to respond with a temporary error
status, so that the client will try again later. Specify "accept" if you want
to receive mail as if the filter does not exist, and "reject" to reject mail
with a permanent status.

        # What to do in case of errors? Specify accept, reject, or tempfail.
        milter_default_action = tempfail

MMiilltteerr pprroottooccooll vveerrssiioonn

As Postfix is not built with the Sendmail libmilter library, you may need to
configure the Milter protocol version that Postfix should use. The default
version is 2.

    milter_protocol = 2

If the Postfix milter_protocol setting specifies a too low version, the
libmilter library will log an error message like this:

    application name: st_optionneg[xxxxx]: 0xyy does not fulfill action
    requirements 0xzz

The remedy is to increase the Postfix milter_protocol version number. See,
however, the limitations section below for features that aren't supported by
Postfix.

If the Postfix milter_protocol setting specifies a too high version, the
libmilter library simply hangs up without logging a warning, and you see a
Postfix warning message like one of the following:

    postfix/smtpd[21045]: warning: milter inet:host:port: can't read packet
    header: Unknown error : 0
    postfix/cleanup[15190]: warning: milter inet:host:port: can't read packet
    header: Success

The remedy is to lower the Postfix milter_protocol version number.

MMiilltteerr pprroottooccooll ttiimmeeoouuttss

Postfix uses different time limits at different Milter protocol stages. The
table shows wich timeouts are used and when (EOH = end of headers; EOM = end of
message).

     _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
    |PPaarraammeetteerr             |TTiimmee lliimmiitt|PPrroottooccooll ssttaaggee                 |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |milter_connect_timeout|30s       |CONNECT                        |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |milter_command_timeout|30s       |HELO, MAIL, RCPT, DATA, UNKNOWN|
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |milter_content_timeout|300s      |HEADER, EOH, BODY, EOM         |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |

Beware: 30s is not a lot for applications that do a lot of DNS lookups.
However, if you increase the above timeouts too much, remote SMTP clients may
hang up and mail may be delivered multiple times. This is an inherent problem
with before-queue filtering.

SSeennddmmaaiill mmaaccrroo eemmuullaattiioonn

Postfix emulates a limited number of Sendmail macros, as shown in the table.
Different macros are available at different SMTP protocol stages (EOM = end-of-
message); their availability is not always the same as in Sendmail. See the
workarounds section below for solutions.

     _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
    |NNaammee                |AAvvaaiillaabbiilliittyy             |DDeessccrriippttiioonn               |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |i                   |DATA, EOM                |Queue ID                  |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |j                   |Always                   |value of myhostname       |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |_                   |Always                   |The validated client name |
    |                    |                         |and address               |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |{auth_authen}       |MAIL, DATA, EOM          |SASL login name           |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |{auth_author}       |MAIL, DATA, EOM          |SASL sender               |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |{auth_type}         |MAIL, DATA, EOM          |SASL login method         |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |{client_addr}       |Always                   |Client IP address         |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |{client_connections}|CONNECT                  |Connection concurrency for|
    |                    |                         |this client               |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |                    |                         |Client hostname, "unknown"|
    |{client_name}       |Always                   |when lookup or            |
    |                    |                         |verification fails        |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |                    |                         |Client name from reverse  |
    |{client_ptr}        |CONNECT, HELO, MAIL, DATA|lookup, "unknown" when    |
    |                    |                         |lookup fails              |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |{cert_issuer}       |HELO, MAIL, DATA, EOM    |TLS client certificate    |
    |                    |                         |issuer                    |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |{cert_subject}      |HELO, MAIL, DATA, EOM    |TLS client certificate    |
    |                    |                         |subject                   |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |{cipher_bits}       |HELO, MAIL, DATA, EOM    |TLS session key size      |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |{cipher}            |HELO, MAIL, DATA, EOM    |TLS cipher                |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |{daemon_name}       |Always                   |value of                  |
    |                    |                         |milter_macro_daemon_name  |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |{mail_addr}         |MAIL                     |Sender address            |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |{rcpt_addr}         |RCPT                     |Recipient address         |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |{tls_version}       |HELO, MAIL, DATA, EOM    |TLS protocol version      |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |v                   |Always                   |value of milter_macro_v   |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |

Postfix sends specific sets of macros at different SMTP protocol stages. The
sets are configured with the parameters as described in the table (EOM = end of
message).

     _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
    |PPaarraammeetteerr nnaammee               |PPrroottooccooll vveerrssiioonn|PPrroottooccooll ssttaaggee |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |milter_connect_macros        |2 or higher     |CONNECT        |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |milter_helo_macros           |2 or higher     |HELO/EHLO      |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |milter_mail_macros           |2 or higher     |MAIL FROM      |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |milter_rcpt_macros           |2 or higher     |RCPT TO        |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |milter_data_macros           |4 or higher     |DATA           |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |milter_end_of_data_macros    |2 or higher     |EOM            |
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
    |milter_unknown_command_macros|3 or higher     |unknown command|
    |_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |

WWoorrkkaarroouunnddss

Content filters may break domain key etc. signatures. If you use an SMTP-based
content filter, then you should add a line to master.cf with "-
o disable_mime_output_conversion=yes" (note: no spaces around the "="), as
described in the advanced content filter example.

Sendmail Milter applications were originally developed for the Sendmail version
8 MTA, which has a different architecture than Postfix. The result is that some
Milter applications make assumptions that aren't true in a Postfix environment.

  * Some Milter applications use the "{if_addr}" macro to recognize local mail;
    this macro does not exist in Postfix. Workaround: use the "{client_addr}"
    macro instead.

  * Some Milter applications log a warning that looks like this:

        sid-filter[36540]: WARNING: sendmail symbol 'i' not available

    And they may insert a message header with "unknown-msgid" like this:

        X-SenderID: Sendmail Sender-ID Filter vx.y.z host.example.com <unknown-
        msgid>

    This happens because some Milter applications expect that the queue ID is
    known before the MTA accepts the MAIL FROM (sender) command. Postfix, on
    the other hand, does not choose a queue file name until after it accepts
    the first valid RCPT TO (recipient) command. Postfix queue file names must
    be unique across multiple directories, so the name can't be chosen before
    the file is created. If multiple messages were to use the same queue ID
    simultaneously, mail would be lost.

    To work around the ugly message header from Milter applications, we add a
    little code to the Milter source to look up the queue ID after Postfix
    receives the end of the message.

      o Edit the filter source file (typically named dk-filter/dk-filter.c or
        similar).

      o Look up the mlfi_eom() function and add code near the top shown as bboolldd
        text below:

        dfc = cc->cctx_msg;
        assert(dfc != NULL);

        //** DDeetteerrmmiinnee tthhee jjoobb IIDD ffoorr llooggggiinngg.. **//
        iiff ((ddffcc-->>mmccttxx__jjoobbiidd ==== 00 |||| ssttrrccmmpp((ddffcc-->>mmccttxx__jjoobbiidd,, JJOOBBIIDDUUNNKKNNOOWWNN)) ==== 00))
        {{
                cchhaarr **jjoobbiidd == ssmmffii__ggeettssyymmvvaall((ccttxx,, ""ii""));;
                iiff ((jjoobbiidd !!== 00))
                        ddffcc-->>mmccttxx__jjoobbiidd == jjoobbiidd;;
        }}

        /* get hostname; used in the X header and in new MIME boundaries */

    NOTES:

      o Different mail filters use slightly different names for variables. If
        the above code does not compile, look for the code at the start of the
        mlfi_eoh() routine.

      o This fixes only the ugly message header, but not the WARNING message.
        Fortunately, dk-filter logs that message only once.

    With some Milter applications we can fix both the WARNING and the "unknown-
    msgid" by postponing the call of mlfi_eoh() (or whatever routine logs the
    WARNING) until the end of the message.

      o Edit the filter source file (typically named sid-filter/sid-filter.c or
        similar).

      o Look up the smfilter table and replace mlfi_eoh (or whatever routine
        logs the WARNING) by NULL.

      o Look up the mlfi_eom() function and add code near the top that calls
        mlfi_eoh() as shown by the bboolldd text below:

                assert(ctx != NULL);
        #endif /* !DEBUG */

                rreett == mmllffii__eeoohh((ccttxx));;
                iiff ((rreett !!== SSMMFFIISS__CCOONNTTIINNUUEE))
                        rreettuurrnn rreett;;

    This works with sid-milter-0.2.10. Other Milter applications will dump core
    when you do this.

LLiimmiittaattiioonnss

This section lists limitations of the Postfix Milter implementation. Some
limitations will be removed as the implementation is extended over time. Of
course the usual limitations of before-queue filtering will always apply. See
the CONTENT_INSPECTION_README document for a discussion.

  * Postfix currently supports only applications that speak the Sendmail 8
    Milter protocol versions 2..4. Support for other protocol types or protocol
    versions may be added later.

  * For applications that are written in C, you need to use the Sendmail
    libmilter library. A Postfix replacement may be provided in the future.

  * There are TWO sets of mail filters: filters that are used for SMTP mail
    only (specified with the smtpd_milters parameter), and filters for non-SMTP
    mail (specified with the non_smtpd_milters parameter). The non-SMTP filters
    are primarily for local submissions.

  * When mail is filtered by non-SMTP filters, the Postfix cleanup(8) server
    has to simulate the SMTP client CONNECT and DISCONNECT events, and the SMTP
    client EHLO, MAIL FROM, RCPT TO and DATA commands. This works as expected,
    with only one exception: non-SMTP filters must not REJECT or TEMPFAIL
    simulated RCPT TO commands. When a non-SMTP filter REJECTs or TEMPFAILs a
    recipient, Postfix will report a configuration error, and mail will stay in
    the queue.

  * Postfix currently does not apply content filters to mail that is forwarded
    or aliased internally, or to mail that is generated internally such as
    bounces or Postmaster notifications. This may be a problem when you want to
    apply a signing Milter to such mail.

  * When you use the before-queue content filter for incoming SMTP mail (see
    SMTPD_PROXY_README), Milter applications have access only to the SMTP
    command information; they have no access to the message header or body, and
    cannot make modifications to the message or to the envelope.

  * Postfix 2.3 does not support Milter requests to replace the message body.
    Milter applications that request this unsupported operation will log a
    warning like this:

        application name: st_optionneg[134563840]: 0x3d does not fulfill action
        requirements 0x1e

    The solution is (to wait for) a Postfix version that supports the missing
    functionality.

  * Most Milter configuration options are global. Future Postfix versions may
    support per-Milter timeouts, per-Milter error handling, etc.