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 next- 21 hop host name can be specified as command-line macros that are expanded 22 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, multi- 32 recipient delivery is undesirable when prepending a <b>Delivered-to:</b> or <b>X-</b> 33 <b>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 In the command argument vector, the following macros are recog- 195 nized and replaced with corresponding information from the Post- 196 fix queue manager delivery request. 197 198 In addition to the form ${<i>name</i>}, the forms $<i>name</i> and $(<i>name</i>) are 199 also recognized. Specify <b>$$</b> where a single <b>$</b> is wanted. 200 201 <b>${client_address}</b> 202 This macro expands to the remote client network address. 203 204 This feature is available as of Postfix 2.2. 205 206 <b>${client_helo}</b> 207 This macro expands to the remote client HELO command 208 parameter. 209 210 This feature is available as of Postfix 2.2. 211 212 <b>${client_hostname}</b> 213 This macro expands to the remote client hostname. 214 215 This feature is available as of Postfix 2.2. 216 217 <b>${client_port}</b> 218 This macro expands to the remote client TCP port number. 219 220 This feature is available as of Postfix 2.5. 221 222 <b>${client_protocol}</b> 223 This macro expands to the remote client protocol. 224 225 This feature is available as of Postfix 2.2. 226 227 <b>${domain}</b> 228 This macro expands to the domain portion of the recipient 229 address. For example, with an address <i>user+foo@domain</i> 230 the domain is <i>domain</i>. 231 232 This information is modified by the <b>h</b> flag for case fold- 233 ing. 234 235 This feature is available as of Postfix 2.5. 236 237 <b>${extension}</b> 238 This macro expands to the extension part of a recipient 239 address. For example, with an address <i>user+foo@domain</i> 240 the extension is <i>foo</i>. 241 242 A command-line argument that contains <b>${extension}</b> 243 expands into as many command-line arguments as there are 244 recipients. 245 246 This information is modified by the <b>u</b> flag for case fold- 247 ing. 248 249 <b>${mailbox}</b> 250 This macro expands to the complete local part of a recip- 251 ient address. For example, with an address 252 <i>user+foo@domain</i> the mailbox is <i>user+foo</i>. 253 254 A command-line argument that contains <b>${mailbox}</b> expands 255 to as many command-line arguments as there are recipi- 256 ents. 257 258 This information is modified by the <b>u</b> flag for case fold- 259 ing. 260 261 <b>${nexthop}</b> 262 This macro expands to the next-hop hostname. 263 264 This information is modified by the <b>h</b> flag for case fold- 265 ing. 266 267 <b>${original_recipient}</b> 268 This macro expands to the complete recipient address 269 before any address rewriting or aliasing. 270 271 A command-line argument that contains <b>${original_recipi-</b> 272 <b>ent}</b> expands to as many command-line arguments as there 273 are recipients. 274 275 This information is modified by the <b>hqu</b> flags for quoting 276 and case folding. 277 278 This feature is available as of Postfix 2.5. 279 280 <b>${queue_id}</b> 281 This macro expands to the queue id. 282 283 This feature is available as of Postfix 2.11. 284 285 <b>${recipient}</b> 286 This macro expands to the complete recipient address. 287 288 A command-line argument that contains <b>${recipient}</b> 289 expands to as many command-line arguments as there are 290 recipients. 291 292 This information is modified by the <b>hqu</b> flags for quoting 293 and case folding. 294 295 <b>${sasl_method}</b> 296 This macro expands to the name of the SASL authentication 297 mechanism in the AUTH command when the Postfix SMTP 298 server received the message. 299 300 This feature is available as of Postfix 2.2. 301 302 <b>${sasl_sender}</b> 303 This macro expands to the SASL sender name (i.e. the 304 original submitter as per <a href="http://tools.ietf.org/html/rfc4954">RFC 4954</a>) in the MAIL FROM com- 305 mand when the Postfix SMTP server received the message. 306 307 This feature is available as of Postfix 2.2. 308 309 <b>${sasl_username}</b> 310 This macro expands to the SASL user name in the AUTH com- 311 mand when the Postfix SMTP server received the message. 312 313 This feature is available as of Postfix 2.2. 314 315 <b>${sender}</b> 316 This macro expands to the envelope sender address. By 317 default, the null sender address expands to MAILER-DAE- 318 MON; this can be changed with the <b>null_sender</b> attribute, 319 as described above. 320 321 This information is modified by the <b>q</b> flag for quoting. 322 323 <b>${size}</b> 324 This macro expands to Postfix's idea of the message size, 325 which is an approximation of the size of the message as 326 delivered. 327 328 <b>${user}</b> 329 This macro expands to the username part of a recipient 330 address. For example, with an address <i>user+foo@domain</i> 331 the username part is <i>user</i>. 332 333 A command-line argument that contains <b>${user}</b> expands 334 into as many command-line arguments as there are recipi- 335 ents. 336 337 This information is modified by the <b>u</b> flag for case fold- 338 ing. 339 340<b>STANDARDS</b> 341 <a href="http://tools.ietf.org/html/rfc3463">RFC 3463</a> (Enhanced status codes) 342 343<b>DIAGNOSTICS</b> 344 Command exit status codes are expected to follow the conventions 345 defined in <<b>sysexits.h</b>>. Exit status 0 means normal successful comple- 346 tion. 347 348 In the case of a non-zero exit status, a limited amount of command out- 349 put is reported in an delivery status notification. When the output 350 begins with a 4.X.X or 5.X.X enhanced status code, the status code 351 takes precedence over the non-zero exit status (Postfix version 2.3 and 352 later). 353 354 Problems and transactions are logged to <b>syslogd</b>(8). Corrupted message 355 files are marked so that the queue manager can move them to the <b>corrupt</b> 356 queue for further inspection. 357 358<b>SECURITY</b> 359 This program needs a dual personality 1) to access the private Postfix 360 queue and IPC mechanisms, and 2) to execute external commands as the 361 specified user. It is therefore security sensitive. 362 363<b>CONFIGURATION PARAMETERS</b> 364 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 365 for only a limited amount of time. Use the command "<b>postfix reload</b>" to 366 speed up a change. 367 368 The text below provides only a parameter summary. See <a href="postconf.5.html"><b>postconf</b>(5)</a> for 369 more details including examples. 370 371<b>RESOURCE AND RATE CONTROLS</b> 372 In the text below, <i>transport</i> is the first field in a <a href="master.5.html"><b>master.cf</b></a> entry. 373 374 <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> 375 <b><a href="postconf.5.html#default_destination_concurrency_limit">rency_limit</a>)</b> 376 Limit the number of parallel deliveries to the same destination, 377 for delivery via the named <i>transport</i>. The limit is enforced by 378 the Postfix queue manager. 379 380 <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> 381 <b><a href="postconf.5.html#default_destination_recipient_limit">ent_limit</a>)</b> 382 Limit the number of recipients per message delivery, for deliv- 383 ery via the named <i>transport</i>. The limit is enforced by the Post- 384 fix queue manager. 385 386 <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> 387 Limit the time for delivery to external command, for delivery 388 via the named <i>transport</i>. The limit is enforced by the pipe 389 delivery agent. 390 391 Postfix 2.4 and later support a suffix that specifies the time 392 unit: s (seconds), m (minutes), h (hours), d (days), w (weeks). 393 The default time unit is seconds. 394 395<b>MISCELLANEOUS CONTROLS</b> 396 <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b> 397 The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con- 398 figuration files. 399 400 <b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b> 401 How much time a Postfix daemon process may take to handle a 402 request before it is terminated by a built-in watchdog timer. 403 404 <b><a href="postconf.5.html#delay_logging_resolution_limit">delay_logging_resolution_limit</a> (2)</b> 405 The maximal number of digits after the decimal point when log- 406 ging sub-second delay values. 407 408 <b><a href="postconf.5.html#export_environment">export_environment</a> (see 'postconf -d' output)</b> 409 The list of environment variables that a Postfix process will 410 export to non-Postfix processes. 411 412 <b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b> 413 The time limit for sending or receiving information over an 414 internal communication channel. 415 416 <b><a href="postconf.5.html#mail_owner">mail_owner</a> (postfix)</b> 417 The UNIX system account that owns the Postfix queue and most 418 Postfix daemon processes. 419 420 <b><a href="postconf.5.html#max_idle">max_idle</a> (100s)</b> 421 The maximum amount of time that an idle Postfix daemon process 422 waits for an incoming connection before terminating voluntarily. 423 424 <b><a href="postconf.5.html#max_use">max_use</a> (100)</b> 425 The maximal number of incoming connections that a Postfix daemon 426 process will service before terminating voluntarily. 427 428 <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b> 429 The process ID of a Postfix command or daemon process. 430 431 <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b> 432 The process name of a Postfix command or daemon process. 433 434 <b><a href="postconf.5.html#queue_directory">queue_directory</a> (see 'postconf -d' output)</b> 435 The location of the Postfix top-level queue directory. 436 437 <b><a href="postconf.5.html#recipient_delimiter">recipient_delimiter</a> (empty)</b> 438 The set of characters that can separate a user name from its 439 extension (example: user+foo), or a .forward file name from its 440 extension (example: .forward+foo). 441 442 <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b> 443 The syslog facility of Postfix logging. 444 445 <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b> 446 The mail system name that is prepended to the process name in 447 syslog records, so that "smtpd" becomes, for example, "post- 448 fix/smtpd". 449 450<b>SEE ALSO</b> 451 <a href="qmgr.8.html">qmgr(8)</a>, queue manager 452 <a href="bounce.8.html">bounce(8)</a>, delivery status reports 453 <a href="postconf.5.html">postconf(5)</a>, configuration parameters 454 <a href="master.5.html">master(5)</a>, generic daemon options 455 <a href="master.8.html">master(8)</a>, process manager 456 syslogd(8), system logging 457 458<b>LICENSE</b> 459 The Secure Mailer license must be distributed with this software. 460 461<b>AUTHOR(S)</b> 462 Wietse Venema 463 IBM T.J. Watson Research 464 P.O. Box 704 465 Yorktown Heights, NY 10598, USA 466 467 PIPE(8) 468</pre> </body> </html> 469