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=utf-8"> 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="https://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 NOTE: DO NOT put quotes around the command, $sender, or $recipi- 173 ent. 174 175 This feature is available as of Postfix 2.3. 176 177 <b>size</b>=<i>size</i><b>_</b><i>limit</i> (optional) 178 Don't deliver messages that exceed this size limit (in bytes); 179 return them to the sender instead. 180 181 <b>user</b>=<i>username</i> (required) 182 183 <b>user</b>=<i>username</i>:<i>groupname</i> 184 Execute the external command with the user ID and group ID of 185 the specified <i>username</i>. The software refuses to execute com- 186 mands with root privileges, or with the privileges of the mail 187 system owner. If <i>groupname</i> is specified, the corresponding group 188 ID is used instead of the group ID of <i>username</i>. 189 190 <b>argv</b>=<i>command</i>... (required) 191 The command to be executed. This must be specified as the last 192 command attribute. The command is executed directly, i.e. with- 193 out interpretation of shell meta characters by a shell command 194 interpreter. 195 196 Specify "{" and "}" around command arguments that contain white- 197 space (Postfix 3.0 and later). Whitespace after the opening "{" 198 and before the closing "}" is ignored. 199 200 In the command argument vector, the following macros are recog- 201 nized and replaced with corresponding information from the Post- 202 fix queue manager delivery request. 203 204 In addition to the form ${<i>name</i>}, the forms $<i>name</i> and the depre- 205 cated form $(<i>name</i>) are also recognized. Specify <b>$$</b> where a sin- 206 gle <b>$</b> is wanted. 207 208 <b>${client_address}</b> 209 This macro expands to the remote client network address. 210 211 This feature is available as of Postfix 2.2. 212 213 <b>${client_helo}</b> 214 This macro expands to the remote client HELO command 215 parameter. 216 217 This feature is available as of Postfix 2.2. 218 219 <b>${client_hostname}</b> 220 This macro expands to the remote client hostname. 221 222 This feature is available as of Postfix 2.2. 223 224 <b>${client_port}</b> 225 This macro expands to the remote client TCP port number. 226 227 This feature is available as of Postfix 2.5. 228 229 <b>${client_protocol}</b> 230 This macro expands to the remote client protocol. 231 232 This feature is available as of Postfix 2.2. 233 234 <b>${domain}</b> 235 This macro expands to the domain portion of the recipient 236 address. For example, with an address <i>user+foo@domain</i> 237 the domain is <i>domain</i>. 238 239 This information is modified by the <b>h</b> flag for case fold- 240 ing. 241 242 This feature is available as of Postfix 2.5. 243 244 <b>${extension}</b> 245 This macro expands to the extension part of a recipient 246 address. For example, with an address <i>user+foo@domain</i> 247 the extension is <i>foo</i>. 248 249 A command-line argument that contains <b>${extension}</b> 250 expands into as many command-line arguments as there are 251 recipients. 252 253 This information is modified by the <b>u</b> flag for case fold- 254 ing. 255 256 <b>${mailbox}</b> 257 This macro expands to the complete local part of a recip- 258 ient address. For example, with an address 259 <i>user+foo@domain</i> the mailbox is <i>user+foo</i>. 260 261 A command-line argument that contains <b>${mailbox}</b> expands 262 to as many command-line arguments as there are recipi- 263 ents. 264 265 This information is modified by the <b>u</b> flag for case fold- 266 ing. 267 268 <b>${nexthop}</b> 269 This macro expands to the next-hop hostname. 270 271 This information is modified by the <b>h</b> flag for case fold- 272 ing. 273 274 <b>${original_recipient}</b> 275 This macro expands to the complete recipient address 276 before any address rewriting or aliasing. 277 278 A command-line argument that contains <b>${original_recipi-</b> 279 <b>ent}</b> expands to as many command-line arguments as there 280 are recipients. 281 282 This information is modified by the <b>hqu</b> flags for quoting 283 and case folding. 284 285 This feature is available as of Postfix 2.5. 286 287 <b>${queue_id}</b> 288 This macro expands to the queue id. 289 290 This feature is available as of Postfix 2.11. 291 292 <b>${recipient}</b> 293 This macro expands to the complete recipient address. 294 295 A command-line argument that contains <b>${recipient}</b> 296 expands to as many command-line arguments as there are 297 recipients. 298 299 This information is modified by the <b>hqu</b> flags for quoting 300 and case folding. 301 302 <b>${sasl_method}</b> 303 This macro expands to the name of the SASL authentication 304 mechanism in the AUTH command when the Postfix SMTP 305 server received the message. 306 307 This feature is available as of Postfix 2.2. 308 309 <b>${sasl_sender}</b> 310 This macro expands to the SASL sender name (i.e. the 311 original submitter as per <a href="https://tools.ietf.org/html/rfc4954">RFC 4954</a>) in the MAIL FROM com- 312 mand when the Postfix SMTP server received the message. 313 314 This feature is available as of Postfix 2.2. 315 316 <b>${sasl_username}</b> 317 This macro expands to the SASL user name in the AUTH com- 318 mand when the Postfix SMTP server received the message. 319 320 This feature is available as of Postfix 2.2. 321 322 <b>${sender}</b> 323 This macro expands to the envelope sender address. By 324 default, the null sender address expands to MAILER-DAE- 325 MON; this can be changed with the <b>null_sender</b> attribute, 326 as described above. 327 328 This information is modified by the <b>q</b> flag for quoting. 329 330 <b>${size}</b> 331 This macro expands to Postfix's idea of the message size, 332 which is an approximation of the size of the message as 333 delivered. 334 335 <b>${user}</b> 336 This macro expands to the username part of a recipient 337 address. For example, with an address <i>user+foo@domain</i> 338 the username part is <i>user</i>. 339 340 A command-line argument that contains <b>${user}</b> expands 341 into as many command-line arguments as there are recipi- 342 ents. 343 344 This information is modified by the <b>u</b> flag for case fold- 345 ing. 346 347<b>STANDARDS</b> 348 <a href="https://tools.ietf.org/html/rfc3463">RFC 3463</a> (Enhanced status codes) 349 350<b>DIAGNOSTICS</b> 351 Command exit status codes are expected to follow the conventions 352 defined in <<b>sysexits.h</b>>. Exit status 0 means normal successful comple- 353 tion. 354 355 In the case of a non-zero exit status, a limited amount of command out- 356 put is logged, and reported in a delivery status notification. When 357 the output begins with a 4.X.X or 5.X.X enhanced status code, the sta- 358 tus code takes precedence over the non-zero exit status (Postfix ver- 359 sion 2.3 and later). 360 361 After successful delivery (zero exit status) a limited amount of com- 362 mand output is logged, and reported in "success" delivery status noti- 363 fications (Postfix 3.0 and later). This command output is not examined 364 for the presence of an enhanced status code. 365 366 Problems and transactions are logged to <b>syslogd</b>(8) or <a href="postlogd.8.html"><b>postlogd</b>(8)</a>. 367 Corrupted message files are marked so that the queue manager can move 368 them to the <b>corrupt</b> queue for further inspection. 369 370<b>SECURITY</b> 371 This program needs a dual personality 1) to access the private Postfix 372 queue and IPC mechanisms, and 2) to execute external commands as the 373 specified user. It is therefore security sensitive. 374 375<b>CONFIGURATION PARAMETERS</b> 376 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 377 for only a limited amount of time. Use the command "<b>postfix reload</b>" to 378 speed up a change. 379 380 The text below provides only a parameter summary. See <a href="postconf.5.html"><b>postconf</b>(5)</a> for 381 more details including examples. 382 383<b>RESOURCE AND RATE CONTROLS</b> 384 In the text below, <i>transport</i> is the first field in a <a href="master.5.html"><b>master.cf</b></a> entry. 385 386 <b><a href="postconf.5.html#transport_time_limit">transport_time_limit</a> ($<a href="postconf.5.html#command_time_limit">command_time_limit</a>)</b> 387 A transport-specific override for the <a href="postconf.5.html#command_time_limit">command_time_limit</a> parame- 388 ter value, where <i>transport</i> is the <a href="master.5.html">master.cf</a> name of the message 389 delivery transport. 390 391 Implemented in the <a href="qmgr.8.html">qmgr(8)</a> daemon: 392 393 <b><a href="postconf.5.html#transport_destination_concurrency_limit">transport_destination_concurrency_limit</a> ($<a href="postconf.5.html#default_destination_concurrency_limit">default_destination_concur</a>-</b> 394 <b><a href="postconf.5.html#default_destination_concurrency_limit">rency_limit</a>)</b> 395 A transport-specific override for the <a href="postconf.5.html#default_destination_concurrency_limit">default_destination_con</a>- 396 <a href="postconf.5.html#default_destination_concurrency_limit">currency_limit</a> parameter value, where <i>transport</i> is the <a href="master.5.html">master.cf</a> 397 name of the message delivery transport. 398 399 <b><a href="postconf.5.html#transport_destination_recipient_limit">transport_destination_recipient_limit</a> ($<a href="postconf.5.html#default_destination_recipient_limit">default_destination_recipi</a>-</b> 400 <b><a href="postconf.5.html#default_destination_recipient_limit">ent_limit</a>)</b> 401 A transport-specific override for the <a href="postconf.5.html#default_destination_recipient_limit">default_destination_recip</a>- 402 <a href="postconf.5.html#default_destination_recipient_limit">ient_limit</a> parameter value, where <i>transport</i> is the <a href="master.5.html">master.cf</a> 403 name of the message delivery transport. 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 an email address local- 449 part, user name, or a .forward file name from its extension. 450 451 <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b> 452 The syslog facility of Postfix logging. 453 454 <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b> 455 A prefix that is prepended to the process name in syslog 456 records, so that, for example, "smtpd" becomes "prefix/smtpd". 457 458 Available in Postfix version 3.0 and later: 459 460 <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> 461 Optional filter for the <a href="pipe.8.html"><b>pipe</b>(8)</a> delivery agent to change the 462 delivery status code or explanatory text of successful or unsuc- 463 cessful deliveries. 464 465 Available in Postfix version 3.3 and later: 466 467 <b><a href="postconf.5.html#enable_original_recipient">enable_original_recipient</a> (yes)</b> 468 Enable support for the original recipient address after an 469 address is rewritten to a different address (for example with 470 aliasing or with canonical mapping). 471 472 <b><a href="postconf.5.html#service_name">service_name</a> (read-only)</b> 473 The <a href="master.5.html">master.cf</a> service name of a Postfix daemon process. 474 475 Available in Postfix 3.5 and later: 476 477 <b><a href="postconf.5.html#info_log_address_format">info_log_address_format</a> (external)</b> 478 The email address form that will be used in non-debug logging 479 (info, warning, etc.). 480 481<b>SEE ALSO</b> 482 <a href="qmgr.8.html">qmgr(8)</a>, queue manager 483 <a href="bounce.8.html">bounce(8)</a>, delivery status reports 484 <a href="postconf.5.html">postconf(5)</a>, configuration parameters 485 <a href="master.5.html">master(5)</a>, generic daemon options 486 <a href="master.8.html">master(8)</a>, process manager 487 <a href="postlogd.8.html">postlogd(8)</a>, Postfix logging 488 syslogd(8), system logging 489 490<b>LICENSE</b> 491 The Secure Mailer license must be distributed with this software. 492 493<b>AUTHOR(S)</b> 494 Wietse Venema 495 IBM T.J. Watson Research 496 P.O. Box 704 497 Yorktown Heights, NY 10598, USA 498 499 Wietse Venema 500 Google, Inc. 501 111 8th Avenue 502 New York, NY 10011, USA 503 504 PIPE(8) 505</pre> </body> </html> 506