postfix-master/MILTER_README.html

   1 <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
   2         "http://www.w3.org/TR/html4/loose.dtd">
   3
   4 <html>
   5
   6 <head>
   7
   8 <title>Postfix before-queue Milter support </title>
   9
  10 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  11
  12 </head>
  13
  14 <body>
  15
  16 <h1><img src="postfix-logo.jpg" width="203" height="98" ALT="">Postfix before-queue Milter support </h1>
  17
  18 <hr>
  19
  20 <h2>Introduction</h2>
  21
  22 <p> Postfix implements support for the Sendmail version 8 Milter
  23 (mail filter) protocol. This protocol is used by applications that
  24 run outside the MTA to inspect SMTP events (CONNECT, DISCONNECT),
  25 SMTP commands (HELO, MAIL FROM, etc.) as well as mail content
  26 (headers and body).  All this happens before mail is queued.  </p>
  27
  28 <p> The reason for adding Milter support to Postfix is that there
  29 exists a large collection of applications, not only to block unwanted
  30 mail, but also to verify authenticity (examples: <a
  31 href="http://www.opendkim.org/">OpenDKIM</a>, <a
  32 href="http://sourceforge.net/projects/dkim-milter/">DomainKeys
  33 Identified Mail (DKIM)</a>, <a
  34 href="http://sourceforge.net/projects/sid-milter/">SenderID+SPF</a> and
  35 <a href="http://sourceforge.net/projects/dk-milter/">DomainKeys</a>)
  36 or to digitally sign mail (examples: <a
  37 href="http://www.opendkim.org/">OpenDKIM</a>, <a
  38 href="http://sourceforge.net/projects/dkim-milter/">DomainKeys
  39 Identified Mail (DKIM)</a>, <a
  40 href="http://sourceforge.net/projects/dk-milter/">DomainKeys</a>).
  41 Having yet another Postfix-specific version of all that software
  42 is a poor use of human and system resources. </p>
  43
  44 <p> The Milter protocol has evolved over time, and different Postfix
  45 versions implement different feature sets.  See the <a
  46 href="#workarounds">workarounds</a> and <a
  47 href="#limitations">limitations</a> sections at the end of this
  48 document for differences between Postfix and Sendmail implementations.
  49 </p>
  50
  51 <p> This document provides information on the following topics: </p>
  52
  53 <ul>
  54
  55 <li><a href="#plumbing">How Milter applications plug into Postfix </a>
  56
  57 <li><a href="#building">Building Milter applications</a>
  58
  59 <li><a href="#running">Running Milter applications</a>
  60
  61 <li><a href="#config">Configuring Postfix</a>
  62
  63 <li><a href="#workarounds">Workarounds</a>
  64
  65 <li><a href="#limitations">Limitations</a>
  66
  67 </ul>
  68
  69 <h2><a name="plumbing">How Milter applications plug into Postfix </a> </h2>
  70
  71 <p> The Postfix Milter implementation uses two different lists of
  72 mail filters: one list of filters for SMTP mail only,
  73 and one list of filters for non-SMTP mail. The two
  74 lists have different capabilities, which is unfortunate.  Avoiding
  75 this would require major restructuring of Postfix. </p>
  76
  77 <ul>
  78
  79 <li> <p> The SMTP-only filters handle mail that arrives via the
  80 Postfix <a href="smtpd.8.html">smtpd(8)</a> server. They are typically used to filter unwanted
  81 mail and to sign mail from authorized SMTP clients. You specify
  82 SMTP-only Milter applications with the <a href="postconf.5.html#smtpd_milters">smtpd_milters</a> parameter as
  83 described in a later section.  Mail that arrives via the Postfix
  84 <a href="smtpd.8.html">smtpd(8)</a> server is not filtered by the non-SMTP filters that are
  85 described next. </p>
  86
  87 <li> <p> The non-SMTP filters handle mail that arrives via the
  88 Postfix <a href="sendmail.1.html">sendmail(1)</a> command-line or via the Postfix <a href="qmqpd.8.html">qmqpd(8)</a> server.
  89 They are typically used to digitally sign mail only. Although
  90 non-SMTP filters can be used to filter unwanted mail, they have
  91 limitations compared to the SMTP-only filters. You specify non-SMTP
  92 Milter applications with the <a href="postconf.5.html#non_smtpd_milters">non_smtpd_milters</a> parameter as described
  93 in a later section.  </p>
  94
  95 </ul>
  96
  97 <p> For those who are familiar with the Postfix architecture, the
  98 figure below shows how Milter applications plug into Postfix.  Names
  99 followed by a number are Postfix commands or server programs, while
 100 unnumbered names inside shaded areas represent Postfix queues.  To
 101 avoid clutter, the path for local submission is simplified (the
 102 <a href="OVERVIEW.html">OVERVIEW</a> document has a more complete description of the Postfix
 103 architecture).  </p>
 104
 105 <blockquote>
 106
 107 <table>
 108
 109 <tr>
 110
 111 <td colspan="2"> </td>
 112
 113 <td align="center"> SMTP-only <br> filters </td>
 114
 115 <td> </td>
 116
 117 <td align="center"> non-SMTP <br> filters </td>
 118
 119 </tr>
 120
 121 <tr>
 122
 123 <td colspan="2"> </td>
 124
 125 <td align="center"> <table> <tr> <td align="center">
 126 ^<br> <tt> | </tt> </td> <td align="center"> <tt> |<br> v </tt>
 127 </td> </tr> </table> </td>
 128
 129 <td rowspan="2"> </td>
 130
 131 <td rowspan="3" align="center"> <table> <tr> <td align="center">
 132 ^<br> <tt> |<br> |<br> | </tt> </td> <td align="center"> <tt> |<br>
 133 |<br> |<br> v </tt> </td> </tr> </table> </td>
 134
 135 </tr>
 136
 137 <tr>
 138
 139 <td> Network </td> <td> <tt> -&gt; </tt> </td>
 140
 141 <td bgcolor="#f0f0ff" align="center" valign="middle"> <a href="smtpd.8.html">smtpd(8)</a>
 142 </td>
 143
 144 </tr>
 145
 146 <tr>
 147
 148 <td colspan="3"> </td> <td> <tt> \ </tt> </td>
 149
 150 </tr>
 151
 152 <tr>
 153
 154 <td> Network </td> <td> <tt> -&gt; </tt> </td>
 155
 156 <td bgcolor="#f0f0ff" align="center" valign="middle"> <a href="qmqpd.8.html">qmqpd(8)</a>
 157 </td>
 158
 159 <td> <tt> -&gt; </tt> </td>
 160
 161 <td bgcolor="#f0f0ff" align="center" valign="middle"> <a href="cleanup.8.html">cleanup(8)</a>
 162 </td>
 163
 164 <td> <tt> -&gt; </tt> </td>
 165
 166 <td bgcolor="#f0f0ff" align="center" valign="middle"> <a
 167 href="QSHAPE_README.html#incoming_queue"> incoming </a> </td>
 168
 169 </tr>
 170
 171 <tr>
 172
 173 <td colspan="3"> </td> <td> <tt> / </tt> </td>
 174
 175 </tr>
 176
 177 <tr>
 178
 179 <td colspan="2"> </td>
 180
 181 <td bgcolor="#f0f0ff" align="center" valign="middle"> <a href="pickup.8.html">pickup(8)</a>
 182 </td>
 183
 184 </tr>
 185
 186 <tr> <td colspan="2"> </td> <td align="center"> : </td> </tr>
 187
 188 <tr>
 189
 190 <td> Local </td> <td> <tt> -&gt; </tt> </td>
 191
 192 <td bgcolor="#f0f0ff" align="center" valign="middle"> <a href="sendmail.1.html">sendmail(1)</a>
 193 </td>
 194
 195 </tr>
 196
 197 </table>
 198
 199 </blockquote>
 200
 201 <h2><a name="building">Building Milter applications</a></h2>
 202
 203 <p> Milter applications have been written in C, JAVA and Perl, but
 204 this document deals with C applications only.   For these, you need
 205 an object library that implements the Sendmail 8 Milter protocol.
 206 Postfix currently does not provide such a library, but Sendmail
 207 does. </p>
 208
 209 <ul>
 210
 211 <li> <p> The first option is to use a pre-compiled library. Some
 212 systems install the Sendmail libmilter library by default.  With
 213 other systems, libmilter may be provided by a package (called
 214 "sendmail-devel" on some Linux systems).  </p>
 215
 216 <p> Once libmilter is installed, applications such as <a
 217 href="http://www.opendkim.org/">OpenDKIM</a>, <a
 218 href="http://sourceforge.net/projects/dkim-milter/">dkim-milter</a> and
 219 <a href="http://sourceforge.net/projects/sid-milter/">sid-milter</a>
 220 build out of the box without requiring any tinkering:</p>
 221
 222 <blockquote>
 223 <pre>
 224 $ <b>gzcat opendkim-<i>x.y.z</i>.tar.gz | tar xf -</b>
 225 $ <b>cd opendkim-<i>x.y.z</i></b>
 226 $ <b>./configure ...<i>options</i>...</b>
 227 $ <b>make</b>
 228 [...<i>lots of output omitted</i>...]
 229 $ <b>make install</b>
 230 </pre>
 231 </blockquote>
 232
 233 <blockquote>
 234 <pre>
 235 $ <b>gzcat dkim-milter-<i>x.y.z</i>.tar.gz | tar xf -</b>
 236 $ <b>cd dkim-milter-<i>x.y.z</i></b>
 237 $ <b>make</b>
 238 [...<i>lots of output omitted</i>...]
 239 </pre>
 240 </blockquote>
 241
 242 <li> <p> The other option is to build the libmilter library from
 243 Sendmail source code: </p>
 244
 245 <blockquote>
 246 <pre>
 247 $ <b>gzcat sendmail-<i>x.y.z</i>.tar.gz | tar xf -</b>
 248 $ <b>cd sendmail-<i>x.y.z</i>/libmilter</b>
 249 $ <b>make</b>
 250 [...<i>lots of output omitted</i>...]
 251 </pre>
 252 </blockquote>
 253
 254 <p> After building your own libmilter library, follow the installation
 255 instructions in the Milter application source distribution to specify
 256 the location of the libmilter include files and object library.
 257 Typically, these settings are configured in a file named
 258 <tt>sid-filter/Makefile.m4</tt> or similar:
 259
 260 <blockquote>
 261 <pre>
 262 APPENDDEF(`confINCDIRS', `-I/some/where/sendmail-x.y.z/include')
 263 APPENDDEF(`confLIBDIRS', `-L/some/where/sendmail-x.y.z/obj.<i>systemtype</i>/libmilter')
 264 </pre>
 265 </blockquote>
 266
 267 <p>Then build the Milter application. </p>
 268
 269 </ul>
 270
 271 <h2><a name="running">Running Milter applications</a></h2>
 272
 273 <p> To run a Milter application, see the documentation of the filter
 274 for options.  A typical command looks like this:</p>
 275
 276 <blockquote>
 277 <pre>
 278 # <b>/some/where/dkim-filter -u <i>userid</i> -p inet:<i>portnumber</i>@localhost ...<i>other options</i>...</b>
 279 </pre>
 280 </blockquote>
 281
 282 <p> Please specify a <i>userid</i> value that isn't used for other
 283 applications (not "postfix", not "www", etc.). </p>
 284
 285 <h2><a name="config">Configuring Postfix</a></h2>
 286
 287 <p> Like Sendmail, Postfix has a lot of configuration options that
 288 control how it talks to Milter applications. With the initial Postfix
 289 Milter protocol implementation, many options are global, that is,
 290 they apply to all Milter applications. Future Postfix versions may
 291 support per-Milter timeouts, per-Milter error handling, etc. </p>
 292
 293 <p> Information in this section: </p>
 294
 295 <ul>
 296
 297 <li><a href="#smtp-only-milters">SMTP-Only Milter applications </a>
 298
 299 <li><a href="#non-smtp-milters">Non-SMTP Milter applications </a>
 300
 301 <li><a href="#errors">Milter error handling </a>
 302
 303 <li><a href="#version">Milter protocol version</a>
 304
 305 <li><a href="#timeouts">Milter protocol timeouts</a>
 306
 307 <li><a href="#macros">Sendmail macro emulation</a>
 308
 309 </ul>
 310
 311 <h3><a name="smtp-only-milters">SMTP-Only Milter applications</a></h3>
 312
 313 <p>  The SMTP-only Milter applications handle mail that arrives via
 314 the Postfix <a href="smtpd.8.html">smtpd(8)</a> server. They are typically used to filter
 315 unwanted mail, and to sign mail from authorized SMTP clients.  Mail
 316 that arrives via the Postfix <a href="smtpd.8.html">smtpd(8)</a> server is not filtered by the
 317 non-SMTP filters that are described in the next section. </p>
 318
 319 <p> NOTE: Do not use the <a href="header_checks.5.html">header_checks(5)</a> IGNORE action to remove
 320 Postfix's own Received: message header. This causes problems with
 321 mail signing filters. Instead, keep Postfix's own Received: message
 322 header and use the <a href="header_checks.5.html">header_checks(5)</a> REPLACE action to sanitize
 323 information. </p>
 324
 325 <p> You specify SMTP-only Milter applications (there can be more
 326 than one) with the <a href="postconf.5.html#smtpd_milters">smtpd_milters</a> parameter.  Each Milter application
 327 is identified by the name of its listening socket; other Milter
 328 configuration options will be discussed in later sections.  Milter
 329 applications are applied in the order as specified, and the first
 330 Milter application that rejects a command will override the responses
 331 from other Milter applications.  </p>
 332
 333 <blockquote>
 334 <pre>
 335 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 336     # Milters for mail that arrives via the <a href="smtpd.8.html">smtpd(8)</a> server.
 337     # See below for socket address syntax.
 338     <a href="postconf.5.html#smtpd_milters">smtpd_milters</a> = inet:localhost:<i>portnumber</i> ...<i>other filters</i>...
 339 </pre>
 340 </blockquote>
 341
 342 <p> The general syntax for listening sockets is as follows: </p>
 343
 344 <blockquote>
 345
 346 <dl>
 347
 348 <dt> <b>unix:</b><i>pathname</i> </dt> <dd><p>Connect to the local
 349 UNIX-domain server that is bound to the specified pathname. If the
 350 <a href="smtpd.8.html">smtpd(8)</a> or <a href="cleanup.8.html">cleanup(8)</a> process runs chrooted, an absolute pathname
 351 is interpreted relative to the Postfix queue directory.</p> </dd>
 352
 353 <dt> <b> inet:</b><i>host</i><b>:</b><i>port</i> </dt> <dd> <p>
 354 Connect to the specified TCP port on the specified local or remote
 355 host.  The host and port can be specified in numeric or symbolic
 356 form.</p>
 357
 358 <p> NOTE: Postfix syntax differs from Milter syntax which has the
 359 form <b>inet:</b><i>port</i><b>@</b><i>host</i>. </p>  </dd>
 360
 361 </dl>
 362
 363 </blockquote>
 364
 365 <h3> <a name="non-smtp-milters">Non-SMTP Milter applications </a> </h3>
 366
 367 <p> The non-SMTP Milter applications handle mail that arrives via
 368 the Postfix <a href="sendmail.1.html">sendmail(1)</a> command-line or via the Postfix <a href="qmqpd.8.html">qmqpd(8)</a>
 369 server. They are typically used to digitally sign mail. Although
 370 non-SMTP filters can be used to filter unwanted mail, there are
 371 limitations as discussed later in this section.  Mail that arrives
 372 via the Postfix <a href="smtpd.8.html">smtpd(8)</a> server is not filtered by the non-SMTP
 373 filters.  </p>
 374
 375 <p> NOTE: Do not use the <a href="header_checks.5.html">header_checks(5)</a> IGNORE action to remove
 376 Postfix's own Received: message header. This causes problems with
 377 mail signing filters. Instead, keep Postfix's own Received: message
 378 header and use the <a href="header_checks.5.html">header_checks(5)</a> REPLACE action to sanitize
 379 information. </p>
 380
 381 <p> You specify non-SMTP Milter applications with the <a href="postconf.5.html#non_smtpd_milters">non_smtpd_milters</a>
 382 parameter. This parameter uses the same syntax as the <a href="postconf.5.html#smtpd_milters">smtpd_milters</a>
 383 parameter in the previous section. As with the SMTP-only filters,
 384 you can specify more than one Milter application; they are applied
 385 in the order as specified, and the first Milter application that
 386 rejects a command will override the responses from the other
 387 applications.  </p>
 388
 389 <blockquote>
 390 <pre>
 391 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 392     # Milters for non-SMTP mail.
 393     # See below for socket address syntax.
 394     <a href="postconf.5.html#non_smtpd_milters">non_smtpd_milters</a> = inet:localhost:<i>portnumber</i> ...<i>other filters</i>...
 395 </pre>
 396 </blockquote>
 397
 398 <p> There's one small complication when using Milter applications
 399 for non-SMTP mail: there is no SMTP session.  To keep Milter
 400 applications happy, the Postfix <a href="cleanup.8.html">cleanup(8)</a> server actually has to
 401 simulate the SMTP client CONNECT and DISCONNECT events, and the
 402 SMTP client EHLO, MAIL FROM, RCPT TO and DATA commands. </p>
 403
 404 <ul>
 405
 406 <li> <p> When new mail arrives via the <a href="sendmail.1.html">sendmail(1)</a> command line,
 407 the Postfix <a href="cleanup.8.html">cleanup(8)</a> server pretends that the mail arrives with
 408 ESMTP from "localhost" with IP address "127.0.0.1". The result is
 409 very similar to what happens with command line submissions in
 410 Sendmail version 8.12 and later, although Sendmail uses a different
 411 mechanism to achieve this result.  </p>
 412
 413 <li> <p> When new mail arrives via the <a href="qmqpd.8.html">qmqpd(8)</a> server, the Postfix
 414 <a href="cleanup.8.html">cleanup(8)</a> server pretends that the mail arrives with ESMTP, and
 415 uses the QMQPD client hostname and IP address. </p>
 416
 417 <li> <p> When old mail is re-injected into the queue with "postsuper
 418 -r", the Postfix <a href="cleanup.8.html">cleanup(8)</a> server uses the same client information
 419 that was used when the mail arrived as new mail. </p>
 420
 421 </ul>
 422
 423 <p> This generally works as expected, with only one exception:
 424 non-SMTP filters must not REJECT or TEMPFAIL simulated RCPT TO
 425 commands.  When a <a href="postconf.5.html#non_smtpd_milters">non_smtpd_milters</a> application REJECTs or TEMPFAILs
 426 a recipient, Postfix will report a configuration error, and mail
 427 will stay in the queue.  </p>
 428
 429 <p> None of this is a problem for mail filters that digitally sign
 430 mail. </p>
 431
 432 <h3><a name="errors">Milter error handling</a></h3>
 433
 434 <p> The <a href="postconf.5.html#milter_default_action">milter_default_action</a> parameter specifies how Postfix handles
 435 Milter application errors. The default action is to respond with a
 436 temporary error status, so that the client will try again later.
 437 Specify "accept" if you want to receive mail as if the filter does
 438 not exist, and "reject" to reject mail with a permanent status.
 439 The "quarantine" action is like "accept" but freezes the message
 440 in the "<a href="QSHAPE_README.html#hold_queue">hold" queue</a>, and is available with Postfix 2.6 or later.
 441 </p>
 442
 443 <blockquote>
 444 <pre>
 445 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 446     # What to do in case of errors? Specify accept, reject, tempfail,
 447     # or quarantine (Postfix 2.6 or later).
 448     <a href="postconf.5.html#milter_default_action">milter_default_action</a> = tempfail
 449 </pre>
 450 </blockquote>
 451
 452 <h3><a name="version">Milter protocol version</a></h3>
 453
 454 <p> As Postfix is not built with the Sendmail libmilter library,
 455 you may need to configure the Milter protocol version that Postfix
 456 should use.  The default version is 6 (before Postfix 2.6 the default
 457 version is 2). </p>
 458
 459 <blockquote>
 460 <pre>
 461 /etc/postfix/<a href="postconf.5.html">main.cf</a>:
 462     # Postfix &ge; 2.6
 463     <a href="postconf.5.html#milter_protocol">milter_protocol</a> = 6
 464     # 2.3 &le; Postfix &le; 2.5
 465     <a href="postconf.5.html#milter_protocol">milter_protocol</a> = 2
 466 </pre>
 467 </blockquote>
 468
 469 <p> If the Postfix <a href="postconf.5.html#milter_protocol">milter_protocol</a> setting specifies a too low
 470 version, the libmilter library will log an error message like this:
 471 </p>
 472
 473 <blockquote>
 474 <pre>
 475 <i>application name</i>: st_optionneg[<i>xxxxx</i>]: 0x<i>yy</i> does not fulfill action requirements 0x<i>zz</i>
 476 </pre>
 477 </blockquote>
 478
 479 <p> The remedy is to increase the Postfix <a href="postconf.5.html#milter_protocol">milter_protocol</a> version
 480 number.  See, however, the <a href="#limitations">limitations</a>
 481 section below for features that aren't supported by Postfix. </p>
 482
 483 <p> With Postfix 2.7 and earlier, if the Postfix <a href="postconf.5.html#milter_protocol">milter_protocol</a>
 484 setting specifies a too high
 485 version, the libmilter library simply hangs up without logging a
 486 warning, and you see a Postfix warning message like one of the
 487 following: </p>
 488
 489 <blockquote>
 490 <pre>
 491 warning: milter inet:<i>host</i>:<i>port</i>: can't read packet header: Unknown error : 0
 492 warning: milter inet:<i>host</i>:<i>port</i>: can't read packet header: Success
 493 warning: milter inet:<i>host</i>:<i>port</i>: can't read SMFIC_DATA reply packet header: No such file or directory
 494 </pre>
 495 </blockquote>
 496
 497 <p> The remedy is to lower the Postfix <a href="postconf.5.html#milter_protocol">milter_protocol</a> version
 498 number. Postfix 2.8 and later will automatically turn off protocol
 499 features that the application's libmilter library does not expect.
 500 </p>
 501
 502 <h3><a name="timeouts">Milter protocol timeouts</a></h3>
 503
 504 <p> Postfix uses different time limits at different Milter protocol
 505 stages. The table shows the timeout settings and the corresponding
 506 protocol stages
 507 (EOH = end of headers; EOM = end of message).  </p>
 508
 509 <blockquote>
 510
 511 <table border="1">
 512
 513 <tr> <th> Postfix parameter </th> <th> Time limit </th> <th> Milter
 514 protocol stage</th> </tr>
 515
 516 <tr> <td> <a href="postconf.5.html#milter_connect_timeout">milter_connect_timeout</a> </td> <td> 30s </td> <td> CONNECT
 517 </td> </tr>
 518
 519 <tr> <td> <a href="postconf.5.html#milter_command_timeout">milter_command_timeout</a> </td> <td> 30s </td> <td> HELO,
 520 MAIL, RCPT, DATA, UNKNOWN </td> </tr>
 521
 522 <tr> <td> <a href="postconf.5.html#milter_content_timeout">milter_content_timeout</a> </td> <td> 300s </td> <td> HEADER,
 523 EOH, BODY, EOM </td> </tr>
 524
 525 </table>
 526
 527 </blockquote>
 528
 529 <p> Beware: 30s may be too short for Milter applications that do
 530 lots of DNS lookups.  However, if you increase the above timeouts
 531 too much, remote SMTP clients may hang up and mail may be delivered
 532 multiple times. This is an inherent problem with before-queue
 533 filtering. </p>
 534
 535 <h3><a name="macros">Sendmail macro emulation</a></h3>
 536
 537 <p> Postfix emulates a limited number of Sendmail macros, as shown
 538 in the table. Some macro values depend on whether a recipient is
 539 rejected (rejected recipients are available on request by the Milter
 540 application). Different macros are available at different Milter
 541 protocol stages (EOH = end-of-header, EOM = end-of-message); their
 542 availability is not
 543 always the same as in Sendmail. See the <a
 544 href="#workarounds">workarounds</a> section below for solutions.
 545 </p>
 546
 547 <blockquote>
 548
 549 <table border="1">
 550
 551 <tr> <th> Sendmail macro </th> <th> Milter protocol stage </th>
 552 <th> Description </th> </tr>
 553
 554 <tr> <td> i </td> <td> DATA, EOH, EOM </td> <td> Queue ID, also
 555 Postfix queue file name </td> </tr>
 556
 557 <tr> <td> j </td> <td> Always </td> <td> Value of <a href="postconf.5.html#myhostname">myhostname</a> </td>
 558 </tr>
 559
 560 <tr> <td> _ </td> <td> Always </td> <td> The validated client name
 561 and address </td> </tr>
 562
 563 <tr> <td> {auth_authen} </td> <td> MAIL, DATA, EOH, EOM </td> <td> SASL
 564 login name </td> </tr>
 565
 566 <tr> <td> {auth_author} </td> <td> MAIL, DATA, EOH, EOM </td> <td> SASL
 567 sender </td> </tr>
 568
 569 <tr> <td> {auth_type} </td> <td> MAIL, DATA, EOH, EOM </td> <td> SASL
 570 login method </td> </tr>
 571
 572 <tr> <td> {client_addr} </td> <td> Always </td> <td> Client IP
 573 address </td> </tr>
 574
 575 <tr> <td> {client_connections} </td> <td> CONNECT </td> <td>
 576 Connection concurrency for this client </td> </tr>
 577
 578 <tr> <td> {client_name} </td> <td> Always </td> <td> Client hostname
 579 <br> When address &rarr; name lookup or name &rarr; address
 580 verification fails: "unknown" </td> </tr>
 581
 582 <tr> <td> {client_port} </td> <td> Always (Postfix &ge;2.5) </td>
 583 <td> Client TCP port </td> </tr>
 584
 585 <tr> <td> {client_ptr} </td> <td> CONNECT, HELO, MAIL, DATA </td>
 586 <td> Client name from address &rarr; name lookup <br> When address
 587 &rarr; name lookup fails: "unknown" </td> </tr>
 588
 589 <tr> <td> {cert_issuer} </td> <td> HELO, MAIL, DATA, EOH, EOM </td> <td>
 590 TLS client certificate issuer </td> </tr>
 591
 592 <tr> <td> {cert_subject} </td> <td> HELO, MAIL, DATA, EOH, EOM </td>
 593 <td> TLS client certificate subject </td> </tr>
 594
 595 <tr> <td> {cipher_bits} </td> <td> HELO, MAIL, DATA, EOH, EOM </td> <td>
 596 TLS session key size </td> </tr>
 597
 598 <tr> <td> {cipher} </td> <td> HELO, MAIL, DATA, EOH, EOM </td> <td> TLS
 599 cipher </td> </tr>
 600
 601 <tr> <td> {daemon_name} </td> <td> Always </td> <td> value of
 602 <a href="postconf.5.html#milter_macro_daemon_name">milter_macro_daemon_name</a> </td> </tr>
 603
 604 <tr> <td> {mail_addr} </td> <td> MAIL </td> <td> Sender address
 605 </td> </tr>
 606
 607 <tr> <td> {mail_host} </td> <td> MAIL (Postfix &ge; 2.6, only with
 608 <a href="postconf.5.html#smtpd_milters">smtpd_milters</a>) </td> <td> Sender next-hop destination </td> </tr>
 609
 610 <tr> <td> {mail_mailer} </td> <td> MAIL (Postfix &ge; 2.6, only with
 611 <a href="postconf.5.html#smtpd_milters">smtpd_milters</a>) </td> <td> Sender mail delivery transport </td> </tr>
 612
 613 <tr> <td> {rcpt_addr} </td> <td> RCPT </td> <td> Recipient address
 614 <br> With rejected recipient: descriptive text </td> </tr>
 615
 616 <tr> <td> {rcpt_host} </td> <td> RCPT (Postfix &ge; 2.6, only with
 617 <a href="postconf.5.html#smtpd_milters">smtpd_milters</a>) </td> <td> Recipient next-hop destination <br> With
 618 rejected recipient: enhanced status code </td> </tr>
 619
 620 <tr> <td> {rcpt_mailer} </td> <td> RCPT (Postfix &ge; 2.6, only with
 621 <a href="postconf.5.html#smtpd_milters">smtpd_milters</a>) </td> <td> Recipient mail delivery transport <br>
 622 With rejected recipient: "error" </td> </tr>
 623
 624 <tr> <td> {tls_version} </td> <td> HELO, MAIL, DATA, EOH, EOM </td>
 625 <td> TLS protocol version </td> </tr>
 626
 627 <tr> <td> v </td> <td> Always </td> <td> value of <a href="postconf.5.html#milter_macro_v">milter_macro_v</a>
 628 </td> </tr>
 629
 630 </table>
 631
 632 </blockquote>
 633
 634 <p> Postfix sends specific sets of macros at different Milter protocol
 635 stages.  The sets are configured with the parameters as described
 636 in the table (EOH = end of headers; EOM = end of message). The
 637 protocol version is a number that Postfix sends at the beginning
 638 of the Milter protocol handshake. </p>
 639
 640 <p> As of Sendmail 8.14.0, Milter applications can specify what
 641 macros they want to receive at different Milter protocol stages.
 642 An application-specified list takes precedence over a Postfix-specified
 643 list. </p>
 644
 645 <blockquote>
 646
 647 <table border="1">
 648
 649 <tr> <th> Postfix parameter </th> <th> Milter protocol version </th>
 650 <th> Milter protocol stage </th> </tr>
 651
 652 <tr> <td> <a href="postconf.5.html#milter_connect_macros">milter_connect_macros</a> </td> <td> 2 or higher </td> <td>
 653 CONNECT </td> </tr>
 654
 655 <tr> <td> <a href="postconf.5.html#milter_helo_macros">milter_helo_macros</a> </td> <td> 2 or higher </td> <td>
 656 HELO/EHLO </td> </tr>
 657
 658 <tr> <td> <a href="postconf.5.html#milter_mail_macros">milter_mail_macros</a> </td> <td> 2 or higher </td> <td> MAIL
 659 FROM </td> </tr>
 660
 661 <tr> <td> <a href="postconf.5.html#milter_rcpt_macros">milter_rcpt_macros</a> </td> <td> 2 or higher </td> <td> RCPT
 662 TO </td> </tr>
 663
 664 <tr> <td> <a href="postconf.5.html#milter_data_macros">milter_data_macros</a> </td> <td> 4 or higher </td> <td> DATA
 665 </td> </tr>
 666
 667 <tr> <td> <a href="postconf.5.html#milter_end_of_header_macros">milter_end_of_header_macros</a> </td> <td> 6 or higher </td>
 668 <td> EOH </td> </tr>
 669
 670 <tr> <td> <a href="postconf.5.html#milter_end_of_data_macros">milter_end_of_data_macros</a> </td> <td> 2 or higher </td>
 671 <td> EOM </td> </tr>
 672
 673 <tr> <td> <a href="postconf.5.html#milter_unknown_command_macros">milter_unknown_command_macros</a> </td> <td> 3 or higher </td>
 674 <td> unknown command </td> </tr>
 675
 676 </table>
 677
 678 </blockquote>
 679
 680 <h2><a name="workarounds">Workarounds</a></h2>
 681
 682 <ul>
 683
 684 <li> <p> To avoid breaking DKIM etc. signatures with an SMTP-based
 685 content filter, update the before-filter SMTP client in <a href="master.5.html">master.cf</a>,
 686 and add a line with "-o <a href="postconf.5.html#disable_mime_output_conversion">disable_mime_output_conversion</a>=yes" (note:
 687 no spaces around the "="). For details, see the <a
 688 href="FILTER_README.html#advanced_filter">advanced content filter</a>
 689 example. </p>
 690
 691 <pre>
 692 /etc/postfix/<a href="master.5.html">master.cf</a>:
 693     # =============================================================
 694     # service type  private unpriv  chroot  wakeup  maxproc command
 695     #               (yes)   (yes)   (yes)   (never) (100)
 696     # =============================================================
 697     scan      unix  -       -       n       -       10      smtp
 698         -o <a href="postconf.5.html#smtp_send_xforward_command">smtp_send_xforward_command</a>=yes
 699         -o <a href="postconf.5.html#disable_mime_output_conversion">disable_mime_output_conversion</a>=yes
 700         -o <a href="postconf.5.html#smtp_generic_maps">smtp_generic_maps</a>=
 701 </pre>
 702
 703 <li> <p> Some Milter applications use the "<tt>{if_addr}</tt>" macro
 704 to recognize local mail; this macro does not exist in Postfix.
 705 Workaround: use the "<tt>{client_addr}</tt>" macro instead. </p>
 706
 707 <li> <p> Some Milter applications log a warning that looks like
 708 this: </p>
 709
 710 <blockquote> <pre>
 711 sid-filter[36540]: WARNING: sendmail symbol 'i' not available
 712 </pre>
 713 </blockquote>
 714
 715 <p> And they may insert an ugly message header with "unknown-msgid"
 716 like this: </p>
 717
 718 <blockquote>
 719 <pre>
 720 X-SenderID: Sendmail Sender-ID Filter vx.y.z host.example.com &lt;unknown-msgid&gt;
 721 </pre>
 722 </blockquote>
 723
 724 <p> The problem is that Milter applications expect that the queue
 725 ID is known <i>before</i> the MTA accepts the MAIL FROM (sender)
 726 command.  Postfix does not choose a queue ID, which is used as the
 727 queue file name, until <i>after</i> it accepts the first valid RCPT
 728 TO (recipient) command. </p>
 729
 730 <p> If you experience the ugly header problem, see if a recent
 731 version of the Milter application fixes it. For example, current
 732 versions of dkim-filter and dk-filter already have code that looks
 733 up the Postfix queue ID at a later protocol stage, and sid-filter
 734 version 1.0.0 no longer includes the queue ID in the message header.
 735 </p>
 736
 737 <p> To fix the ugly message header, you will need to add code that
 738 looks up the Postfix queue ID at some later point in time. The
 739 example below adds the lookup after the end-of-message.  </p>
 740
 741 <ul>
 742
 743 <li> <p> Edit the filter source file (typically named
 744 <tt>xxx-filter/xxx-filter.c</tt> or similar). </p>
 745
 746 <li> <p> Look up the <tt>mlfi_eom()</tt> function and add code near
 747 the top shown as <b>bold</b> text below: </p>
 748
 749 </ul>
 750
 751 <blockquote>
 752 <pre>
 753 dfc = cc->cctx_msg;
 754 assert(dfc != NULL);
 755 <b>
 756 /* Determine the job ID for logging. */
 757 if (dfc->mctx_jobid == 0 || strcmp(dfc->mctx_jobid, JOBIDUNKNOWN) == 0) {
 758         char *jobid = smfi_getsymval(ctx, "i");
 759         if (jobid != 0)
 760                 dfc->mctx_jobid = jobid;
 761 }</b>
 762 </pre>
 763 </blockquote>
 764
 765 <p> NOTES: </p>
 766
 767 <ul>
 768
 769 <li> <p> Different mail filters use slightly different names for
 770 variables. If the above code does not compile, look elsewhere in
 771 the mail filter source file for code that looks up the "i" macro
 772 value, and copy that code.  </p>
 773
 774 <li> <p> This change fixes only the ugly message header, but not
 775 the WARNING message.  Fortunately, many Milters log that message
 776 only once. </p>
 777
 778 </ul>
 779
 780 </ul>
 781
 782 <h2><a name="limitations">Limitations</a></h2>
 783
 784 <p> This section lists limitations of the Postfix Milter implementation.
 785 Some limitations will be removed as the implementation is extended
 786 over time. Of course the usual limitations of before-queue filtering
 787 will always apply. See the <a href="CONTENT_INSPECTION_README.html">CONTENT_INSPECTION_README</a> document for
 788 a discussion. </p>
 789
 790 <ul>
 791
 792 <li> <p> The Milter protocol has evolved over time. Therefore,
 793 different Postfix versions implement different feature sets. </p>
 794
 795 <table border="1">
 796
 797 <tr> <th> Postfix </th> <th> Supported Milter requests </th>
 798 </tr>
 799
 800 <tr> <td align="center"> 2.6 </td> <td> All Milter requests of
 801 Sendmail 8.14.0 (see notes below).  </td> </tr>
 802
 803 <tr> <td align="center"> 2.5 </td> <td> All Milter requests of
 804 Sendmail 8.14.0, except: <br> SMFIP_RCPT_REJ (report rejected
 805 recipients to the mail filter), <br> SMFIR_CHGFROM (replace sender,
 806 with optional ESMTP parameters), <br> SMFIR_ADDRCPT_PAR (add
 807 recipient, with optional ESMTP parameters). </td> </tr>
 808
 809 <tr> <td align="center"> 2.4 </td> <td> All Milter requests of
 810 Sendmail 8.13.0.  </td> </tr>
 811
 812 <tr> <td align="center"> 2.3 </td> <td> All Milter requests of
 813 Sendmail 8.13.0, except: <br> SMFIR_REPLBODY (replace message body).
 814
 815 </table>
 816
 817 <li> <p> For Milter applications that are written in C, you need
 818 to use the Sendmail libmilter library. </p>
 819
 820 <li> <p> Postfix has TWO sets of mail filters: filters that are used
 821 for SMTP mail only (specified with the <a href="postconf.5.html#smtpd_milters">smtpd_milters</a> parameter),
 822 and filters for non-SMTP mail (specified with the <a href="postconf.5.html#non_smtpd_milters">non_smtpd_milters</a>
 823 parameter).  The non-SMTP filters are primarily for local submissions.
 824 </p>
 825
 826 <p> When mail is filtered by <a href="postconf.5.html#non_smtpd_milters">non_smtpd_milters</a>, the Postfix <a href="cleanup.8.html">cleanup(8)</a>
 827 server has to simulate SMTP client requests.  This works as expected,
 828 with only one exception: <a href="postconf.5.html#non_smtpd_milters">non_smtpd_milters</a> must not REJECT or
 829 TEMPFAIL simulated RCPT TO commands. When this rule is violated,
 830 Postfix will report a configuration error, and mail will stay in
 831 the queue.  </p>
 832
 833 <li> <p> Postfix currently does not apply content filters to mail
 834 that is forwarded or aliased internally, or to mail that is generated
 835 internally such as bounces or Postmaster notifications. This may
 836 be a problem when you want to apply a signing Milter to such mail.
 837 </p>
 838
 839 <li> <p> When you use the before-queue content filter for incoming
 840 SMTP mail (see <a href="SMTPD_PROXY_README.html">SMTPD_PROXY_README</a>), Milter applications have access
 841 only to the SMTP command information; they have no access to the
 842 message header or body, and cannot make modifications to the message
 843 or to the envelope. </p>
 844
 845 <li> <p> Postfix 2.6 ignores the optional ESMTP parameters in
 846 requests to replace the sender (SMFIR_CHGFROM) or to append a
 847 recipient (SMFIR_ADDRCPT_PAR). Postfix logs a warning message when
 848 a Milter application supplies such ESMTP parameters: </p>
 849
 850 <pre>
 851 warning: <i>queue-id</i>: cleanup_chg_from: ignoring ESMTP arguments "<i>whatever</i>"
 852 warning: <i>queue-id</i>: cleanup_add_rcpt: ignoring ESMTP arguments "<i>whatever</i>"
 853 </pre>
 854
 855 <li> <p> Postfix 2.3 does not implement requests to replace the
 856 message body. Milter applications log a warning message when they
 857 need this unsupported operation: </p>
 858
 859 <pre>
 860 st_optionneg[134563840]: 0x3d does not fulfill action requirements 0x1e
 861 </pre>
 862
 863 <p> The solution is to use Postfix version 2.4 or later. </p>
 864
 865 <li> <p> Most Milter configuration options are global. Future Postfix
 866 versions may support per-Milter timeouts, per-Milter error handling,
 867 etc. </p>
 868
 869 </ul>
 870
 871 </body>
 872
 873 </html>