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