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