postfix-master/pipe.8.html

   1 <!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN"
   2         "http://www.w3.org/TR/html4/loose.dtd">
   3 <html> <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
   5 <title> Postfix manual - pipe(8) </title>
   6 </head> <body> <pre>
   7 PIPE(8)                                                                PIPE(8)
   8
   9 <b>NAME</b>
  10        pipe - Postfix delivery to external command
  11
  12 <b>SYNOPSIS</b>
  13        <b>pipe</b> [generic Postfix daemon options] command_attributes...
  14
  15 <b>DESCRIPTION</b>
  16        The  <a href="pipe.8.html"><b>pipe</b>(8)</a>  daemon  processes  requests from the Postfix
  17        queue manager to deliver messages  to  external  commands.
  18        This  program expects to be run from the <a href="master.8.html"><b>master</b>(8)</a> process
  19        manager.
  20
  21        Message  attributes  such  as  sender  address,  recipient
  22        address  and  next-hop  host name can be specified as com-
  23        mand-line macros that are  expanded  before  the  external
  24        command is executed.
  25
  26        The  <a href="pipe.8.html"><b>pipe</b>(8)</a>  daemon updates queue files and marks recipi-
  27        ents as finished, or it informs  the  queue  manager  that
  28        delivery  should  be tried again at a later time. Delivery
  29        status reports are sent  to  the  <a href="bounce.8.html"><b>bounce</b>(8)</a>,  <a href="defer.8.html"><b>defer</b>(8)</a>  or
  30        <a href="trace.8.html"><b>trace</b>(8)</a> daemon as appropriate.
  31
  32 <b>SINGLE-RECIPIENT DELIVERY</b>
  33        Some  destinations  cannot  handle more than one recipient
  34        per delivery request. Examples are pagers or fax machines.
  35        In  addition, multi-recipient delivery is undesirable when
  36        prepending  a  <b>Delivered-to:</b>  or  <b>X-Original-To:</b>   message
  37        header.
  38
  39        To  prevent  Postfix  from sending multiple recipients per
  40        delivery request, specify
  41
  42            <b><a href="postconf.5.html#transport_destination_recipient_limit"><i>transport</i>_destination_recipient_limit</a> = 1</b>
  43
  44        in the Postfix <a href="postconf.5.html"><b>main.cf</b></a> file, where <i>transport</i> is  the  name
  45        in the first column of the Postfix <a href="master.5.html"><b>master.cf</b></a> entry for the
  46        pipe-based delivery transport.
  47
  48 <b>COMMAND ATTRIBUTE SYNTAX</b>
  49        The external command attributes are given in the <a href="master.5.html"><b>master.cf</b></a>
  50        file at the end of a service definition.  The syntax is as
  51        follows:
  52
  53        <b>chroot=</b><i>pathname</i> (optional)
  54               Change  the  process  root  directory  and  working
  55               directory  to  the  named  directory.  This happens
  56               before switching to the privileges  specified  with
  57               the   <b>user</b>  attribute,  and  before  executing  the
  58               optional <b>directory=</b><i>pathname</i> directive. Delivery  is
  59               deferred in case of failure.
  60
  61               This feature is available as of Postfix 2.3.
  62
  63        <b>directory=</b><i>pathname</i> (optional)
  64               Change  to the named directory before executing the
  65               external command.  The directory must be accessible
  66               for the user specified with the <b>user</b> attribute (see
  67               below).    The   default   working   directory   is
  68               <b>$<a href="postconf.5.html#queue_directory">queue_directory</a></b>.   Delivery is deferred in case of
  69               failure.
  70
  71               This feature is available as of Postfix 2.2.
  72
  73        <b>eol=</b><i>string</i> (optional, default: <b>\n</b>)
  74               The output record delimiter.  Typically  one  would
  75               use  either <b>\r\n</b> or <b>\n</b>. The usual C-style backslash
  76               escape sequences are recognized: <b>\a \b \f \n \r  \t</b>
  77               <b>\v \</b><i>ddd</i> (up to three octal digits) and <b>\\</b>.
  78
  79        <b>flags=BDFORXhqu.</b>&gt; (optional)
  80               Optional  message  processing  flags. By default, a
  81               message is copied unchanged.
  82
  83               <b>B</b>      Append a blank line at the end of each  mes-
  84                      sage.  This  is  required  by some mail user
  85                      agents that recognize  "<b>From</b>  "  lines  only
  86                      when preceded by a blank line.
  87
  88               <b>D</b>      Prepend  a "<b>Delivered-To:</b> <i>recipient</i>" message
  89                      header with the envelope recipient  address.
  90                      Note: for this to work, the <i>transport</i><b>_desti-</b>
  91                      <b>nation_recipient_limit</b> must be 1  (see  SIN-
  92                      GLE-RECIPIENT DELIVERY above for details).
  93
  94                      The  <b>D</b>  flag  also  enforces  loop detection
  95                      (Postfix  2.5  and  later):  if  a   message
  96                      already contains a <b>Delivered-To:</b> header with
  97                      the same recipient address, then the message
  98                      is  returned  as  undeliverable. The address
  99                      comparison is case insensitive.
 100
 101                      This feature is available as of Postfix 2.0.
 102
 103               <b>F</b>      Prepend  a "<b>From</b> <i>sender time</i><b>_</b><i>stamp</i>" envelope
 104                      header to  the  message  content.   This  is
 105                      expected by, for example, <b>UUCP</b> software.
 106
 107               <b>O</b>      Prepend  an  "<b>X-Original-To:</b> <i>recipient</i>" mes-
 108                      sage header with the  recipient  address  as
 109                      given  to  Postfix.  Note: for this to work,
 110                      the    <b><a href="postconf.5.html#transport_destination_recipient_limit"><i>transport</i>_destination_recipient_limit</a></b>
 111                      must  be  1  (see  SINGLE-RECIPIENT DELIVERY
 112                      above for details).
 113
 114                      This feature is available as of Postfix 2.0.
 115
 116               <b>R</b>      Prepend  a  <b>Return-Path:</b> message header with
 117                      the envelope sender address.
 118
 119               <b>X</b>      Indicate that the external command  performs
 120                      final  delivery.  This flag affects the sta-
 121                      tus reported in "success" DSN (delivery sta-
 122                      tus  notification)  messages, and changes it
 123                      from "relayed" into "delivered".
 124
 125                      This feature is available as of Postfix 2.5.
 126
 127               <b>h</b>      Fold  the  command-line  <b>$original_recipient</b>
 128                      and <b>$recipient</b> address domain part (text  to
 129                      the  right of the right-most <b>@</b> character) to
 130                      lower case;  fold  the  entire  command-line
 131                      <b>$domain</b> and <b>$nexthop</b> host or domain informa-
 132                      tion to lower case.  This is recommended for
 133                      delivery via <b>UUCP</b>.
 134
 135               <b>q</b>      Quote  white space and other special charac-
 136                      ters in the  command-line  <b>$sender</b>,  <b>$origi-</b>
 137                      <b>nal_recipient</b>  and <b>$recipient</b> address local-
 138                      parts (text to the left of the right-most  <b>@</b>
 139                      character),  according to an 8-bit transpar-
 140                      ent version of <a href="http://tools.ietf.org/html/rfc822">RFC 822</a>.  This is recommended
 141                      for delivery via <b>UUCP</b> or <b>BSMTP</b>.
 142
 143                      The  result  is  compatible with the address
 144                      parsing of command-line  recipients  by  the
 145                      Postfix <a href="sendmail.1.html"><b>sendmail</b>(1)</a> mail submission command.
 146
 147                      The <b>q</b> flag affects  only  entire  addresses,
 148                      not the partial address information from the
 149                      <b>$user</b>, <b>$extension</b> or  <b>$mailbox</b>  command-line
 150                      macros.
 151
 152               <b>u</b>      Fold  the  command-line  <b>$original_recipient</b>
 153                      and <b>$recipient</b> address  localpart  (text  to
 154                      the  left  of the right-most <b>@</b> character) to
 155                      lower case.  This is recommended for  deliv-
 156                      ery via <b>UUCP</b>.
 157
 158               <b>.</b>      Prepend "<b>.</b>" to lines starting with "<b>.</b>". This
 159                      is needed by, for example, <b>BSMTP</b> software.
 160
 161               &gt;      Prepend "&gt;" to lines starting with "<b>From</b>  ".
 162                      This is expected by, for example, <b>UUCP</b> soft-
 163                      ware.
 164
 165        <b>null_sender</b>=<i>replacement</i> (default: MAILER-DAEMON)
 166               Replace the null sender address (typically used for
 167               delivery  status  notifications) with the specified
 168               text when expanding the <b>$sender</b> command-line macro,
 169               and when generating a From_ or Return-Path: message
 170               header.
 171
 172               If the null sender replacement text is a  non-empty
 173               string  then  it  is  affected  by  the  <b>q</b> flag for
 174               address quoting in command-line arguments.
 175
 176               The null sender replacement text may be empty; this
 177               form  is  recommended for content filters that feed
 178               mail back into Postfix. The empty sender address is
 179               not  affected  by the <b>q</b> flag for address quoting in
 180               command-line arguments.
 181
 182               Caution: a null sender address is easily mis-parsed
 183               by  naive  software.  For example, when the <a href="pipe.8.html"><b>pipe</b>(8)</a>
 184               daemon executes a command such as:
 185
 186                   <i>Wrong</i>: command -f$sender -- $recipient
 187
 188               the command will mis-parse the -f option value when
 189               the  sender  address is a null string.  For correct
 190               parsing, specify <b>$sender</b> as an argument by itself:
 191
 192                   <i>Right</i>: command -f $sender -- $recipient
 193
 194               This feature is available as of Postfix 2.3.
 195
 196        <b>size</b>=<i>size</i><b>_</b><i>limit</i> (optional)
 197               Don't deliver messages that exceed this size  limit
 198               (in bytes); return them to the sender instead.
 199
 200        <b>user</b>=<i>username</i> (required)
 201
 202        <b>user</b>=<i>username</i>:<i>groupname</i>
 203               Execute  the  external command with the user ID and
 204               group ID of the specified <i>username</i>.   The  software
 205               refuses  to  execute commands with root privileges,
 206               or with the privileges of the mail system owner. If
 207               <i>groupname</i>  is specified, the corresponding group ID
 208               is used instead of the group ID of <i>username</i>.
 209
 210        <b>argv</b>=<i>command</i>... (required)
 211               The command to be executed. This must be  specified
 212               as the last command attribute.  The command is exe-
 213               cuted  directly,  i.e.  without  interpretation  of
 214               shell  meta  characters  by  a shell command inter-
 215               preter.
 216
 217               In  the  command  argument  vector,  the  following
 218               macros are recognized and replaced with correspond-
 219               ing information  from  the  Postfix  queue  manager
 220               delivery request.
 221
 222               In  addition  to  the form ${<i>name</i>}, the forms $<i>name</i>
 223               and $(<i>name</i>) are also recognized.  Specify <b>$$</b>  where
 224               a single <b>$</b> is wanted.
 225
 226               <b>${client_address</b>}
 227                      This macro expands to the remote client net-
 228                      work address.
 229
 230                      This feature is available as of Postfix 2.2.
 231
 232               <b>${client_helo</b>}
 233                      This macro expands to the remote client HELO
 234                      command parameter.
 235
 236                      This feature is available as of Postfix 2.2.
 237
 238               <b>${client_hostname</b>}
 239                      This  macro  expands  to  the  remote client
 240                      hostname.
 241
 242                      This feature is available as of Postfix 2.2.
 243
 244               <b>${client_port</b>}
 245                      This  macro expands to the remote client TCP
 246                      port number.
 247
 248                      This feature is available as of Postfix 2.5.
 249
 250               <b>${client_protocol</b>}
 251                      This macro expands to the remote client pro-
 252                      tocol.
 253
 254                      This feature is available as of Postfix 2.2.
 255
 256               <b>${domain</b>}
 257                      This  macro expands to the domain portion of
 258                      the recipient address.  For example, with an
 259                      address   <i>user+foo@domain</i>   the   domain  is
 260                      <i>domain</i>.
 261
 262                      This information is modified by the  <b>h</b>  flag
 263                      for case folding.
 264
 265                      This feature is available as of Postfix 2.5.
 266
 267               <b>${extension</b>}
 268                      This macro expands to the extension part  of
 269                      a  recipient  address.  For example, with an
 270                      address  <i>user+foo@domain</i>  the  extension  is
 271                      <i>foo</i>.
 272
 273                      A   command-line   argument   that  contains
 274                      <b>${extension</b>} expands into as  many  command-
 275                      line arguments as there are recipients.
 276
 277                      This  information  is modified by the <b>u</b> flag
 278                      for case folding.
 279
 280               <b>${mailbox</b>}
 281                      This macro expands  to  the  complete  local
 282                      part  of  a recipient address.  For example,
 283                      with an address <i>user+foo@domain</i> the  mailbox
 284                      is <i>user+foo</i>.
 285
 286                      A   command-line   argument   that  contains
 287                      <b>${mailbox</b>} expands to as  many  command-line
 288                      arguments as there are recipients.
 289
 290                      This  information  is modified by the <b>u</b> flag
 291                      for case folding.
 292
 293               <b>${nexthop</b>}
 294                      This macro expands to the next-hop hostname.
 295
 296                      This  information  is modified by the <b>h</b> flag
 297                      for case folding.
 298
 299               <b>${original_recipient</b>}
 300                      This macro expands to the complete recipient
 301                      address  before  any  address  rewriting  or
 302                      aliasing.
 303
 304                      A  command-line   argument   that   contains
 305                      <b>${original_recipient</b>}  expands  to  as  many
 306                      command-line arguments as there are  recipi-
 307                      ents.
 308
 309                      This  information  is  modified  by  the <b>hqu</b>
 310                      flags for quoting and case folding.
 311
 312                      This feature is available as of Postfix 2.5.
 313
 314               <b>${recipient</b>}
 315                      This macro expands to the complete recipient
 316                      address.
 317
 318                      A  command-line   argument   that   contains
 319                      <b>${recipient</b>} expands to as many command-line
 320                      arguments as there are recipients.
 321
 322                      This information  is  modified  by  the  <b>hqu</b>
 323                      flags for quoting and case folding.
 324
 325               <b>${sasl_method</b>}
 326                      This  macro  expands to the name of the SASL
 327                      authentication mechanism in the AUTH command
 328                      when  the  Postfix  SMTP server received the
 329                      message.
 330
 331                      This feature is available as of Postfix 2.2.
 332
 333               <b>${sasl_sender</b>}
 334                      This  macro  expands to the SASL sender name
 335                      (i.e. the  original  submitter  as  per  <a href="http://tools.ietf.org/html/rfc4954">RFC</a>
 336                      <a href="http://tools.ietf.org/html/rfc4954">4954</a>)  in  the  MAIL  FROM  command when the
 337                      Postfix SMTP server received the message.
 338
 339                      This feature is available as of Postfix 2.2.
 340
 341               <b>${sasl_username</b>}
 342                      This  macro expands to the SASL user name in
 343                      the  AUTH  command  when  the  Postfix  SMTP
 344                      server received the message.
 345
 346                      This feature is available as of Postfix 2.2.
 347
 348               <b>${sender</b>}
 349                      This macro expands to  the  envelope  sender
 350                      address. By default, the null sender address
 351                      expands  to  MAILER-DAEMON;  this   can   be
 352                      changed  with  the <b>null_sender</b> attribute, as
 353                      described above.
 354
 355                      This information is modified by the  <b>q</b>  flag
 356                      for quoting.
 357
 358               <b>${size</b>}
 359                      This  macro expands to Postfix's idea of the
 360                      message size, which is an  approximation  of
 361                      the size of the message as delivered.
 362
 363               <b>${user</b>}
 364                      This macro expands to the username part of a
 365                      recipient address.   For  example,  with  an
 366                      address <i>user+foo@domain</i> the username part is
 367                      <i>user</i>.
 368
 369                      A  command-line   argument   that   contains
 370                      <b>${user</b>}  expands  into  as many command-line
 371                      arguments as there are recipients.
 372
 373                      This information is modified by the  <b>u</b>  flag
 374                      for case folding.
 375
 376 <b>STANDARDS</b>
 377        <a href="http://tools.ietf.org/html/rfc3463">RFC 3463</a> (Enhanced status codes)
 378
 379 <b>DIAGNOSTICS</b>
 380        Command  exit status codes are expected to follow the con-
 381        ventions defined in &lt;<b>sysexits.h</b>&gt;.   Exit  status  0  means
 382        normal successful completion.
 383
 384        In the case of a non-zero exit status, a limited amount of
 385        command output is reported in an delivery status notifica-
 386        tion.   When  the  output  begins  with  a  4.X.X or 5.X.X
 387        enhanced status code, the  status  code  takes  precedence
 388        over  the  non-zero  exit  status (Postfix version 2.3 and
 389        later).
 390
 391        Problems and transactions are logged to <b>syslogd</b>(8).   Cor-
 392        rupted  message files are marked so that the queue manager
 393        can move them to the <b>corrupt</b> queue for further inspection.
 394
 395 <b>SECURITY</b>
 396        This  program  needs  a  dual personality 1) to access the
 397        private Postfix queue and IPC mechanisms, and 2)  to  exe-
 398        cute external commands as the specified user. It is there-
 399        fore security sensitive.
 400
 401 <b>CONFIGURATION PARAMETERS</b>
 402        Changes to <a href="postconf.5.html"><b>main.cf</b></a> are picked up automatically as  <a href="pipe.8.html"><b>pipe</b>(8)</a>
 403        processes  run  for only a limited amount of time. Use the
 404        command "<b>postfix reload</b>" to speed up a change.
 405
 406        The text below provides  only  a  parameter  summary.  See
 407        <a href="postconf.5.html"><b>postconf</b>(5)</a> for more details including examples.
 408
 409 <b>RESOURCE AND RATE CONTROLS</b>
 410        In  the text below, <i>transport</i> is the first field in a <b>mas-</b>
 411        <b>ter.cf</b> entry.
 412
 413        <b><a href="postconf.5.html#transport_destination_concurrency_limit"><i>transport</i>_destination_concurrency_limit</a> ($<a href="postconf.5.html#default_destination_concurrency_limit">default_destina</a>-</b>
 414        <b><a href="postconf.5.html#default_destination_concurrency_limit">tion_concurrency_limit</a>)</b>
 415               Limit the number of parallel deliveries to the same
 416               destination,  for delivery via the named <i>transport</i>.
 417               The limit is enforced by the Postfix queue manager.
 418
 419        <b><a href="postconf.5.html#transport_destination_recipient_limit"><i>transport</i>_destination_recipient_limit</a>   ($<a href="postconf.5.html#default_destination_recipient_limit">default_destina</a>-</b>
 420        <b><a href="postconf.5.html#default_destination_recipient_limit">tion_recipient_limit</a>)</b>
 421               Limit  the  number of recipients per message deliv-
 422               ery, for delivery via  the  named  <i>transport</i>.   The
 423               limit is enforced by the Postfix queue manager.
 424
 425        <b><a href="postconf.5.html#transport_time_limit"><i>transport</i>_time_limit</a> ($<a href="postconf.5.html#command_time_limit">command_time_limit</a>)</b>
 426               Limit  the  time  for delivery to external command,
 427               for delivery via the named <i>transport</i>.  The limit is
 428               enforced by the pipe delivery agent.
 429
 430               Postfix  2.4 and later support a suffix that speci-
 431               fies the time unit: s  (seconds),  m  (minutes),  h
 432               (hours), d (days), w (weeks). The default time unit
 433               is seconds.
 434
 435 <b>MISCELLANEOUS CONTROLS</b>
 436        <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
 437               The default location of  the  Postfix  <a href="postconf.5.html">main.cf</a>  and
 438               <a href="master.5.html">master.cf</a> configuration files.
 439
 440        <b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b>
 441               How  much time a Postfix daemon process may take to
 442               handle a request  before  it  is  terminated  by  a
 443               built-in watchdog timer.
 444
 445        <b><a href="postconf.5.html#delay_logging_resolution_limit">delay_logging_resolution_limit</a> (2)</b>
 446               The  maximal  number  of  digits  after the decimal
 447               point when logging sub-second delay values.
 448
 449        <b><a href="postconf.5.html#export_environment">export_environment</a> (see 'postconf -d' output)</b>
 450               The list of environment variables  that  a  Postfix
 451               process will export to non-Postfix processes.
 452
 453        <b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b>
 454               The time limit for sending or receiving information
 455               over an internal communication channel.
 456
 457        <b><a href="postconf.5.html#mail_owner">mail_owner</a> (postfix)</b>
 458               The UNIX system account that owns the Postfix queue
 459               and most Postfix daemon processes.
 460
 461        <b><a href="postconf.5.html#max_idle">max_idle</a> (100s)</b>
 462               The  maximum  amount  of  time that an idle Postfix
 463               daemon process waits  for  an  incoming  connection
 464               before terminating voluntarily.
 465
 466        <b><a href="postconf.5.html#max_use">max_use</a> (100)</b>
 467               The  maximal  number of incoming connections that a
 468               Postfix daemon process will service  before  termi-
 469               nating voluntarily.
 470
 471        <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b>
 472               The  process  ID  of  a  Postfix  command or daemon
 473               process.
 474
 475        <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b>
 476               The process name of a  Postfix  command  or  daemon
 477               process.
 478
 479        <b><a href="postconf.5.html#queue_directory">queue_directory</a> (see 'postconf -d' output)</b>
 480               The  location of the Postfix top-level queue direc-
 481               tory.
 482
 483        <b><a href="postconf.5.html#recipient_delimiter">recipient_delimiter</a> (empty)</b>
 484               The separator between user names and address exten-
 485               sions (user+foo).
 486
 487        <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
 488               The syslog facility of Postfix logging.
 489
 490        <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
 491               The  mail  system  name  that  is  prepended to the
 492               process name in syslog  records,  so  that  "smtpd"
 493               becomes, for example, "postfix/smtpd".
 494
 495 <b>SEE ALSO</b>
 496        <a href="qmgr.8.html">qmgr(8)</a>, queue manager
 497        <a href="bounce.8.html">bounce(8)</a>, delivery status reports
 498        <a href="postconf.5.html">postconf(5)</a>, configuration parameters
 499        <a href="master.5.html">master(5)</a>, generic daemon options
 500        <a href="master.8.html">master(8)</a>, process manager
 501        syslogd(8), system logging
 502
 503 <b>LICENSE</b>
 504        The  Secure  Mailer  license must be distributed with this
 505        software.
 506
 507 <b>AUTHOR(S)</b>
 508        Wietse Venema
 509        IBM T.J. Watson Research
 510        P.O. Box 704
 511        Yorktown Heights, NY 10598, USA
 512
 513                                                                        PIPE(8)
 514 </pre> </body> </html>