diff options
Diffstat (limited to 'html/pipe.8.html')
| -rw-r--r-- | html/pipe.8.html | 506 |
1 files changed, 506 insertions, 0 deletions
diff --git a/html/pipe.8.html b/html/pipe.8.html new file mode 100644 index 0000000..a0e4678 --- /dev/null +++ b/html/pipe.8.html @@ -0,0 +1,506 @@ +<!doctype html public "-//W3C//DTD HTML 4.01 Transitional//EN" + "http://www.w3.org/TR/html4/loose.dtd"> +<html> <head> +<meta http-equiv="Content-Type" content="text/html; charset=utf-8"> +<link rel='stylesheet' type='text/css' href='postfix-doc.css'> +<title> Postfix manual - pipe(8) </title> +</head> <body> <pre> +PIPE(8) PIPE(8) + +<b>NAME</b> + pipe - Postfix delivery to external command + +<b>SYNOPSIS</b> + <b>pipe</b> [generic Postfix daemon options] command_attributes... + +<b>DESCRIPTION</b> + The <a href="pipe.8.html"><b>pipe</b>(8)</a> daemon processes requests from the Postfix queue manager to + deliver messages to external commands. This program expects to be run + from the <a href="master.8.html"><b>master</b>(8)</a> process manager. + + Message attributes such as sender address, recipient address and + next-hop host name can be specified as command-line macros that are + expanded before the external command is executed. + + The <a href="pipe.8.html"><b>pipe</b>(8)</a> daemon updates queue files and marks recipients as fin- + ished, or it informs the queue manager that delivery should be tried + again at a later time. Delivery status reports are sent to the + <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. + +<b>SINGLE-RECIPIENT DELIVERY</b> + Some destinations cannot handle more than one recipient per delivery + request. Examples are pagers or fax machines. In addition, + multi-recipient delivery is undesirable when prepending a <b>Delivered-to:</b> + or <b>X-Original-To:</b> message header. + + To prevent Postfix from sending multiple recipients per delivery + request, specify + + <b><a href="postconf.5.html#transport_destination_recipient_limit"><i>transport</i>_destination_recipient_limit</a> = 1</b> + + in the Postfix <a href="postconf.5.html"><b>main.cf</b></a> file, where <i>transport</i> is the name in the first + column of the Postfix <a href="master.5.html"><b>master.cf</b></a> entry for the pipe-based delivery + transport. + +<b>COMMAND ATTRIBUTE SYNTAX</b> + The external command attributes are given in the <a href="master.5.html"><b>master.cf</b></a> file at the + end of a service definition. The syntax is as follows: + + <b>chroot=</b><i>pathname</i> (optional) + Change the process root directory and working directory to the + named directory. This happens before switching to the privileges + specified with the <b>user</b> attribute, and before executing the + optional <b>directory=</b><i>pathname</i> directive. Delivery is deferred in + case of failure. + + This feature is available as of Postfix 2.3. + + <b>directory=</b><i>pathname</i> (optional) + Change to the named directory before executing the external com- + mand. The directory must be accessible for the user specified + with the <b>user</b> attribute (see below). The default working direc- + tory is <b>$<a href="postconf.5.html#queue_directory">queue_directory</a></b>. Delivery is deferred in case of fail- + ure. + + This feature is available as of Postfix 2.2. + + <b>eol=</b><i>string</i> (optional, default: <b>\n</b>) + The output record delimiter. Typically one would use either <b>\r\n</b> + or <b>\n</b>. The usual C-style backslash escape sequences are recog- + nized: <b>\a \b \f \n \r \t \v \</b><i>ddd</i> (up to three octal digits) and + <b>\\</b>. + + <b>flags=BDFORXhqu.</b>> (optional) + Optional message processing flags. By default, a message is + copied unchanged. + + <b>B</b> Append a blank line at the end of each message. This is + required by some mail user agents that recognize "<b>From</b> " + lines only when preceded by a blank line. + + <b>D</b> Prepend a "<b>Delivered-To:</b> <i>recipient</i>" message header with + the envelope recipient address. Note: for this to work, + the <b><a href="postconf.5.html#transport_destination_recipient_limit"><i>transport</i>_destination_recipient_limit</a></b> must be 1 (see + SINGLE-RECIPIENT DELIVERY above for details). + + The <b>D</b> flag also enforces loop detection (Postfix 2.5 and + later): if a message already contains a <b>Delivered-To:</b> + header with the same recipient address, then the message + is returned as undeliverable. The address comparison is + case insensitive. + + This feature is available as of Postfix 2.0. + + <b>F</b> Prepend a "<b>From</b> <i>sender time</i><b>_</b><i>stamp</i>" envelope header to the + message content. This is expected by, for example, <b>UUCP</b> + software. + + <b>O</b> Prepend an "<b>X-Original-To:</b> <i>recipient</i>" message header with + the recipient address as given to Postfix. Note: for this + to work, the <b><a href="postconf.5.html#transport_destination_recipient_limit"><i>transport</i>_destination_recipient_limit</a></b> must + be 1 (see SINGLE-RECIPIENT DELIVERY above for details). + + This feature is available as of Postfix 2.0. + + <b>R</b> Prepend a <b>Return-Path:</b> message header with the envelope + sender address. + + <b>X</b> Indicate that the external command performs final deliv- + ery. This flag affects the status reported in "success" + DSN (delivery status notification) messages, and changes + it from "relayed" into "delivered". + + This feature is available as of Postfix 2.5. + + <b>h</b> Fold the command-line <b>$original_recipient</b> and <b>$recipient</b> + address domain part (text to the right of the right-most + <b>@</b> character) to lower case; fold the entire command-line + <b>$domain</b> and <b>$nexthop</b> host or domain information to lower + case. This is recommended for delivery via <b>UUCP</b>. + + <b>q</b> Quote white space and other special characters in the + command-line <b>$sender</b>, <b>$original_recipient</b> and <b>$recipient</b> + address localparts (text to the left of the right-most <b>@</b> + character), according to an 8-bit transparent version of + <a href="https://tools.ietf.org/html/rfc822">RFC 822</a>. This is recommended for delivery via <b>UUCP</b> or + <b>BSMTP</b>. + + The result is compatible with the address parsing of com- + mand-line recipients by the Postfix <a href="sendmail.1.html"><b>sendmail</b>(1)</a> mail sub- + mission command. + + The <b>q</b> flag affects only entire addresses, not the partial + address information from the <b>$user</b>, <b>$extension</b> or <b>$mail-</b> + <b>box</b> command-line macros. + + <b>u</b> Fold the command-line <b>$original_recipient</b> and <b>$recipient</b> + address localpart (text to the left of the right-most <b>@</b> + character) to lower case. This is recommended for deliv- + ery via <b>UUCP</b>. + + <b>.</b> Prepend "<b>.</b>" to lines starting with "<b>.</b>". This is needed + by, for example, <b>BSMTP</b> software. + + > Prepend ">" to lines starting with "<b>From</b> ". This is + expected by, for example, <b>UUCP</b> software. + + <b>null_sender</b>=<i>replacement</i> (default: MAILER-DAEMON) + Replace the null sender address (typically used for delivery + status notifications) with the specified text when expanding the + <b>$sender</b> command-line macro, and when generating a From_ or + Return-Path: message header. + + If the null sender replacement text is a non-empty string then + it is affected by the <b>q</b> flag for address quoting in command-line + arguments. + + The null sender replacement text may be empty; this form is rec- + ommended for content filters that feed mail back into Postfix. + The empty sender address is not affected by the <b>q</b> flag for + address quoting in command-line arguments. + + Caution: a null sender address is easily mis-parsed by naive + software. For example, when the <a href="pipe.8.html"><b>pipe</b>(8)</a> daemon executes a com- + mand such as: + + <i>Wrong</i>: command -f$sender -- $recipient + + the command will mis-parse the -f option value when the sender + address is a null string. For correct parsing, specify <b>$sender</b> + as an argument by itself: + + <i>Right</i>: command -f $sender -- $recipient + NOTE: DO NOT put quotes around the command, $sender, or $recipi- + ent. + + This feature is available as of Postfix 2.3. + + <b>size</b>=<i>size</i><b>_</b><i>limit</i> (optional) + Don't deliver messages that exceed this size limit (in bytes); + return them to the sender instead. + + <b>user</b>=<i>username</i> (required) + + <b>user</b>=<i>username</i>:<i>groupname</i> + Execute the external command with the user ID and group ID of + the specified <i>username</i>. The software refuses to execute com- + mands with root privileges, or with the privileges of the mail + system owner. If <i>groupname</i> is specified, the corresponding group + ID is used instead of the group ID of <i>username</i>. + + <b>argv</b>=<i>command</i>... (required) + The command to be executed. This must be specified as the last + command attribute. The command is executed directly, i.e. with- + out interpretation of shell meta characters by a shell command + interpreter. + + Specify "{" and "}" around command arguments that contain white- + space (Postfix 3.0 and later). Whitespace after the opening "{" + and before the closing "}" is ignored. + + In the command argument vector, the following macros are recog- + nized and replaced with corresponding information from the Post- + fix queue manager delivery request. + + In addition to the form ${<i>name</i>}, the forms $<i>name</i> and the depre- + cated form $(<i>name</i>) are also recognized. Specify <b>$$</b> where a sin- + gle <b>$</b> is wanted. + + <b>${client_address}</b> + This macro expands to the remote client network address. + + This feature is available as of Postfix 2.2. + + <b>${client_helo}</b> + This macro expands to the remote client HELO command + parameter. + + This feature is available as of Postfix 2.2. + + <b>${client_hostname}</b> + This macro expands to the remote client hostname. + + This feature is available as of Postfix 2.2. + + <b>${client_port}</b> + This macro expands to the remote client TCP port number. + + This feature is available as of Postfix 2.5. + + <b>${client_protocol}</b> + This macro expands to the remote client protocol. + + This feature is available as of Postfix 2.2. + + <b>${domain}</b> + This macro expands to the domain portion of the recipient + address. For example, with an address <i>user+foo@domain</i> + the domain is <i>domain</i>. + + This information is modified by the <b>h</b> flag for case fold- + ing. + + This feature is available as of Postfix 2.5. + + <b>${extension}</b> + This macro expands to the extension part of a recipient + address. For example, with an address <i>user+foo@domain</i> + the extension is <i>foo</i>. + + A command-line argument that contains <b>${extension}</b> + expands into as many command-line arguments as there are + recipients. + + This information is modified by the <b>u</b> flag for case fold- + ing. + + <b>${mailbox}</b> + This macro expands to the complete local part of a recip- + ient address. For example, with an address + <i>user+foo@domain</i> the mailbox is <i>user+foo</i>. + + A command-line argument that contains <b>${mailbox}</b> expands + to as many command-line arguments as there are recipi- + ents. + + This information is modified by the <b>u</b> flag for case fold- + ing. + + <b>${nexthop}</b> + This macro expands to the next-hop hostname. + + This information is modified by the <b>h</b> flag for case fold- + ing. + + <b>${original_recipient}</b> + This macro expands to the complete recipient address + before any address rewriting or aliasing. + + A command-line argument that contains <b>${original_recipi-</b> + <b>ent}</b> expands to as many command-line arguments as there + are recipients. + + This information is modified by the <b>hqu</b> flags for quoting + and case folding. + + This feature is available as of Postfix 2.5. + + <b>${queue_id}</b> + This macro expands to the queue id. + + This feature is available as of Postfix 2.11. + + <b>${recipient}</b> + This macro expands to the complete recipient address. + + A command-line argument that contains <b>${recipient}</b> + expands to as many command-line arguments as there are + recipients. + + This information is modified by the <b>hqu</b> flags for quoting + and case folding. + + <b>${sasl_method}</b> + This macro expands to the name of the SASL authentication + mechanism in the AUTH command when the Postfix SMTP + server received the message. + + This feature is available as of Postfix 2.2. + + <b>${sasl_sender}</b> + This macro expands to the SASL sender name (i.e. the + original submitter as per <a href="https://tools.ietf.org/html/rfc4954">RFC 4954</a>) in the MAIL FROM com- + mand when the Postfix SMTP server received the message. + + This feature is available as of Postfix 2.2. + + <b>${sasl_username}</b> + This macro expands to the SASL user name in the AUTH com- + mand when the Postfix SMTP server received the message. + + This feature is available as of Postfix 2.2. + + <b>${sender}</b> + This macro expands to the envelope sender address. By + default, the null sender address expands to MAILER-DAE- + MON; this can be changed with the <b>null_sender</b> attribute, + as described above. + + This information is modified by the <b>q</b> flag for quoting. + + <b>${size}</b> + This macro expands to Postfix's idea of the message size, + which is an approximation of the size of the message as + delivered. + + <b>${user}</b> + This macro expands to the username part of a recipient + address. For example, with an address <i>user+foo@domain</i> + the username part is <i>user</i>. + + A command-line argument that contains <b>${user}</b> expands + into as many command-line arguments as there are recipi- + ents. + + This information is modified by the <b>u</b> flag for case fold- + ing. + +<b>STANDARDS</b> + <a href="https://tools.ietf.org/html/rfc3463">RFC 3463</a> (Enhanced status codes) + +<b>DIAGNOSTICS</b> + Command exit status codes are expected to follow the conventions + defined in <<b>sysexits.h</b>>. Exit status 0 means normal successful comple- + tion. + + In the case of a non-zero exit status, a limited amount of command out- + put is logged, and reported in a delivery status notification. When + the output begins with a 4.X.X or 5.X.X enhanced status code, the sta- + tus code takes precedence over the non-zero exit status (Postfix ver- + sion 2.3 and later). + + After successful delivery (zero exit status) a limited amount of com- + mand output is logged, and reported in "success" delivery status noti- + fications (Postfix 3.0 and later). This command output is not examined + for the presence of an enhanced status code. + + Problems and transactions are logged to <b>syslogd</b>(8) or <a href="postlogd.8.html"><b>postlogd</b>(8)</a>. + Corrupted message files are marked so that the queue manager can move + them to the <b>corrupt</b> queue for further inspection. + +<b>SECURITY</b> + This program needs a dual personality 1) to access the private Postfix + queue and IPC mechanisms, and 2) to execute external commands as the + specified user. It is therefore security sensitive. + +<b>CONFIGURATION PARAMETERS</b> + 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 + for only a limited amount of time. Use the command "<b>postfix reload</b>" to + speed up a change. + + The text below provides only a parameter summary. See <a href="postconf.5.html"><b>postconf</b>(5)</a> for + more details including examples. + +<b>RESOURCE AND RATE CONTROLS</b> + In the text below, <i>transport</i> is the first field in a <a href="master.5.html"><b>master.cf</b></a> entry. + + <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> + A transport-specific override for the <a href="postconf.5.html#command_time_limit">command_time_limit</a> parame- + ter value, where <i>transport</i> is the <a href="master.5.html">master.cf</a> name of the message + delivery transport. + + Implemented in the <a href="qmgr.8.html">qmgr(8)</a> daemon: + + <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> + <b><a href="postconf.5.html#default_destination_concurrency_limit">rency_limit</a>)</b> + A transport-specific override for the <a href="postconf.5.html#default_destination_concurrency_limit">default_destination_con</a>- + <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> + name of the message delivery transport. + + <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> + <b><a href="postconf.5.html#default_destination_recipient_limit">ent_limit</a>)</b> + A transport-specific override for the <a href="postconf.5.html#default_destination_recipient_limit">default_destination_recip</a>- + <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> + name of the message delivery transport. + +<b>MISCELLANEOUS CONTROLS</b> + <b><a href="postconf.5.html#config_directory">config_directory</a> (see 'postconf -d' output)</b> + The default location of the Postfix <a href="postconf.5.html">main.cf</a> and <a href="master.5.html">master.cf</a> con- + figuration files. + + <b><a href="postconf.5.html#daemon_timeout">daemon_timeout</a> (18000s)</b> + How much time a Postfix daemon process may take to handle a + request before it is terminated by a built-in watchdog timer. + + <b><a href="postconf.5.html#delay_logging_resolution_limit">delay_logging_resolution_limit</a> (2)</b> + The maximal number of digits after the decimal point when log- + ging sub-second delay values. + + <b><a href="postconf.5.html#export_environment">export_environment</a> (see 'postconf -d' output)</b> + The list of environment variables that a Postfix process will + export to non-Postfix processes. + + <b><a href="postconf.5.html#ipc_timeout">ipc_timeout</a> (3600s)</b> + The time limit for sending or receiving information over an + internal communication channel. + + <b><a href="postconf.5.html#mail_owner">mail_owner</a> (postfix)</b> + The UNIX system account that owns the Postfix queue and most + Postfix daemon processes. + + <b><a href="postconf.5.html#max_idle">max_idle</a> (100s)</b> + The maximum amount of time that an idle Postfix daemon process + waits for an incoming connection before terminating voluntarily. + + <b><a href="postconf.5.html#max_use">max_use</a> (100)</b> + The maximal number of incoming connections that a Postfix daemon + process will service before terminating voluntarily. + + <b><a href="postconf.5.html#process_id">process_id</a> (read-only)</b> + The process ID of a Postfix command or daemon process. + + <b><a href="postconf.5.html#process_name">process_name</a> (read-only)</b> + The process name of a Postfix command or daemon process. + + <b><a href="postconf.5.html#queue_directory">queue_directory</a> (see 'postconf -d' output)</b> + The location of the Postfix top-level queue directory. + + <b><a href="postconf.5.html#recipient_delimiter">recipient_delimiter</a> (empty)</b> + The set of characters that can separate an email address local- + part, user name, or a .forward file name from its extension. + + <b><a href="postconf.5.html#syslog_facility">syslog_facility</a> (mail)</b> + The syslog facility of Postfix logging. + + <b><a href="postconf.5.html#syslog_name">syslog_name</a> (see 'postconf -d' output)</b> + A prefix that is prepended to the process name in syslog + records, so that, for example, "smtpd" becomes "prefix/smtpd". + + Available in Postfix version 3.0 and later: + + <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> + Optional filter for the <a href="pipe.8.html"><b>pipe</b>(8)</a> delivery agent to change the + delivery status code or explanatory text of successful or unsuc- + cessful deliveries. + + Available in Postfix version 3.3 and later: + + <b><a href="postconf.5.html#enable_original_recipient">enable_original_recipient</a> (yes)</b> + Enable support for the original recipient address after an + address is rewritten to a different address (for example with + aliasing or with canonical mapping). + + <b><a href="postconf.5.html#service_name">service_name</a> (read-only)</b> + The <a href="master.5.html">master.cf</a> service name of a Postfix daemon process. + + Available in Postfix 3.5 and later: + + <b><a href="postconf.5.html#info_log_address_format">info_log_address_format</a> (external)</b> + The email address form that will be used in non-debug logging + (info, warning, etc.). + +<b>SEE ALSO</b> + <a href="qmgr.8.html">qmgr(8)</a>, queue manager + <a href="bounce.8.html">bounce(8)</a>, delivery status reports + <a href="postconf.5.html">postconf(5)</a>, configuration parameters + <a href="master.5.html">master(5)</a>, generic daemon options + <a href="master.8.html">master(8)</a>, process manager + <a href="postlogd.8.html">postlogd(8)</a>, Postfix logging + syslogd(8), system logging + +<b>LICENSE</b> + The Secure Mailer license must be distributed with this software. + +<b>AUTHOR(S)</b> + Wietse Venema + IBM T.J. Watson Research + P.O. Box 704 + Yorktown Heights, NY 10598, USA + + Wietse Venema + Google, Inc. + 111 8th Avenue + New York, NY 10011, USA + + PIPE(8) +</pre> </body> </html> |