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:
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:
- unix: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.
- inet: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 inet:port@host.
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.
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
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.
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).
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.
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.
| Name | Availability | Description |
| 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_name} | Always | Client hostname,
"unknown" when lookup or verification fails |
| {client_ptr} | CONNECT, HELO, MAIL, DATA |
Client name from reverse 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).
