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