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 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>> (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 > Prepend ">" 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 <<b>sysexits.h</b>>. 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> 515