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 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 <<b>sysexits.h</b>>. 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> 514