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