external/ibm-public/postfix/dist/html/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 rights of the
 204               specified <i>username</i>.  The software refuses  to  exe-
 205               cute  commands  with  root  privileges, or with the
 206               privileges of the mail system owner.  If  <i>groupname</i>
 207               is  specified,  the  corresponding group ID is used
 208               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        Postfix  version  2.3  and  later  support  <a href="http://tools.ietf.org/html/rfc3463">RFC 3463</a>-style
 385        enhanced status codes.  If a  command  terminates  with  a
 386        non-zero  exit  status, and the command output begins with
 387        an enhanced status code, this status code takes precedence
 388        over the non-zero exit status.
 389
 390        Problems  and transactions are logged to <b>syslogd</b>(8).  Cor-
 391        rupted message files are marked so that the queue  manager
 392        can move them to the <b>corrupt</b> queue for further inspection.
 393
 394 <b>SECURITY</b>
 395        This program needs a dual personality  1)  to  access  the
 396        private  Postfix  queue and IPC mechanisms, and 2) to exe-
 397        cute external commands as the specified user. It is there-
 398        fore security sensitive.
 399
 400 <b>CONFIGURATION PARAMETERS</b>
 401        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>
 402        processes run for only a limited amount of time.  Use  the
 403        command "<b>postfix reload</b>" to speed up a change.
 404
 405        The  text  below  provides  only  a parameter summary. See
 406        <a href="postconf.5.html"><b>postconf</b>(5)</a> for more details including examples.
 407
 408 <b>RESOURCE AND RATE CONTROLS</b>
 409        In the text below, <i>transport</i> is the first field in a  <b>mas-</b>
 410        <b>ter.cf</b> entry.
 411
 412        <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>
 413        <b><a href="postconf.5.html#default_destination_concurrency_limit">tion_concurrency_limit</a>)</b>
 414               Limit the number of parallel deliveries to the same
 415               destination, for delivery via the named  <i>transport</i>.
 416               The limit is enforced by the Postfix queue manager.
 417
 418        <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>
 419        <b><a href="postconf.5.html#default_destination_recipient_limit">tion_recipient_limit</a>)</b>
 420               Limit the number of recipients per  message  deliv-
 421               ery,  for  delivery  via  the named <i>transport</i>.  The
 422               limit is enforced by the Postfix queue manager.
 423
 424        <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>
 425               Limit the time for delivery  to  external  command,
 426               for delivery via the named <i>transport</i>.  The limit is
 427               enforced by the pipe delivery agent.
 428
 429               Postfix 2.4 and later support a suffix that  speci-
 430               fies  the  time  unit:  s (seconds), m (minutes), h
 431               (hours), d (days), w (weeks). The default time unit
 432               is seconds.
 433
 434 <b>MISCELLANEOUS CONTROLS</b>
 435        <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b>
 436               The  default  location  of  the Postfix <a href="postconf.5.html">main.cf</a> and
 437               <a href="master.5.html">master.cf</a> configuration files.
 438
 439        <b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b>
 440               How much time a Postfix daemon process may take  to
 441               handle  a  request  before  it  is  terminated by a
 442               built-in watchdog timer.
 443
 444        <b><a href="postconf.5.html#delay_logging_resolution_limit">delay_logging_resolution_limit</a> (2)</b>
 445               The maximal number  of  digits  after  the  decimal
 446               point when logging sub-second delay values.
 447
 448        <b><a href="postconf.5.html#export_environment">export_environment</a> (see 'postconf -d' output)</b>
 449               The  list  of  environment variables that a Postfix
 450               process will export to non-Postfix processes.
 451
 452        <b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b>
 453               The time limit for sending or receiving information
 454               over an internal communication channel.
 455
 456        <b><a href="postconf.5.html#mail_owner">mail_owner</a> (postfix)</b>
 457               The UNIX system account that owns the Postfix queue
 458               and most Postfix daemon processes.
 459
 460        <b><a href="postconf.5.html#max_idle">max_idle</a> (100s)</b>
 461               The maximum amount of time  that  an  idle  Postfix
 462               daemon  process  waits  for  an incoming connection
 463               before terminating voluntarily.
 464
 465        <b><a href="postconf.5.html#max_use">max_use</a> (100)</b>
 466               The maximal number of incoming connections  that  a
 467               Postfix  daemon  process will service before termi-
 468               nating voluntarily.
 469
 470        <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b>
 471               The process ID  of  a  Postfix  command  or  daemon
 472               process.
 473
 474        <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b>
 475               The  process  name  of  a Postfix command or daemon
 476               process.
 477
 478        <b><a href="postconf.5.html#queue_directory">queue_directory</a> (see 'postconf -d' output)</b>
 479               The location of the Postfix top-level queue  direc-
 480               tory.
 481
 482        <b><a href="postconf.5.html#recipient_delimiter">recipient_delimiter</a> (empty)</b>
 483               The separator between user names and address exten-
 484               sions (user+foo).
 485
 486        <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b>
 487               The syslog facility of Postfix logging.
 488
 489        <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b>
 490               The mail system  name  that  is  prepended  to  the
 491               process  name  in  syslog  records, so that "smtpd"
 492               becomes, for example, "postfix/smtpd".
 493
 494 <b>SEE ALSO</b>
 495        <a href="qmgr.8.html">qmgr(8)</a>, queue manager
 496        <a href="bounce.8.html">bounce(8)</a>, delivery status reports
 497        <a href="postconf.5.html">postconf(5)</a>, configuration parameters
 498        <a href="master.5.html">master(5)</a>, generic daemon options
 499        <a href="master.8.html">master(8)</a>, process manager
 500        syslogd(8), system logging
 501
 502 <b>LICENSE</b>
 503        The Secure Mailer license must be  distributed  with  this
 504        software.
 505
 506 <b>AUTHOR(S)</b>
 507        Wietse Venema
 508        IBM T.J. Watson Research
 509        P.O. Box 704
 510        Yorktown Heights, NY 10598, USA
 511
 512                                                                        PIPE(8)
 513 </pre> </body> </html>