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