File: spec_14.html

package info (click to toggle)
exim-html 3.20-1
links: PTS
area: main
in suites: etch, etch-m68k, sarge, woody
size: 2,868 kB
ctags: 4,188
sloc: makefile: 40; sh: 19
file content (503 lines) | stat: -rw-r--r-- 15,485 bytes
<HTML>
<HEAD>
<!-- This HTML file has been created by texi2html 1.52
     from spec on 25 November 2000 -->

<TITLE>Exim Specification - 14. Generic options for transports</TITLE>
</HEAD>
<body bgcolor="#FFFFFF" text="#00005A" link="#FF6600" alink="#FF9933" vlink="#990000">
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_13.html">previous</A>, <A HREF="spec_15.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
<P><HR><P>


<H1><A NAME="SEC402" HREF="spec_toc.html#TOC402">14. Generic options for transports</A></H1>

<P>
<A NAME="IDX1036"></A>
<A NAME="IDX1037"></A>
The generic options for transports are as follows:

</P>

<P>

<P>
<A NAME="IDX1038"></A>


<H3><A NAME="SEC403" HREF="spec_toc.html#TOC403">body_only (transport)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
<A NAME="IDX1039"></A>
<A NAME="IDX1040"></A>
<A NAME="IDX1041"></A>
If this option is set, the message's headers are not transported. It is
mutually exclusive with <EM>headers_only</EM>. If it is used with the <EM>appendfile</EM> or
<EM>pipe</EM> transports, the settings of <EM>prefix</EM> and <EM>suffix</EM> should be checked,
since this option does not automatically suppress them.

</P>
<P>
<A NAME="IDX1042"></A>


<H3><A NAME="SEC404" HREF="spec_toc.html#TOC404">debug_print (transport)</A></H3>

<P>
Type: string<BR>
Default: unset

</P>
<P>
<A NAME="IDX1043"></A>
If this option is set and debugging is enabled (see -<EM>d</EM>, -<EM>v</EM>, and
<EM>debug_level</EM>), the string is expanded and included in the debugging
output when the transport is run. This is to help with checking out the values
of variables and so on when debugging driver configurations. For example, if a
<EM>headers_add</EM> option is not working properly, <EM>debug_print</EM> could be used to
output the variables it references. A newline is added to the text if it does
not end with one.

</P>
<P>
<A NAME="IDX1044"></A>


<H3><A NAME="SEC405" HREF="spec_toc.html#TOC405">delivery_date_add (transport)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
If this option is true, a <EM>Delivery-date:</EM> header
<A NAME="IDX1045"></A>
is added to the message. This gives the actual time the delivery was made. As
this is not a standard header, Exim has a configuration option
(<EM>delivery_date_remove</EM>) which requests its removal from incoming messages,
so that delivered messages can safely be resent to other recipients.

</P>
<P>
<A NAME="IDX1046"></A>


<H3><A NAME="SEC406" HREF="spec_toc.html#TOC406">driver (transport)</A></H3>

<P>
Type: string<BR>
Default: unset

</P>
<P>
This specifies which of the available transport drivers is to be used. For
example:

<PRE>
driver = smtp
</PRE>

<P>
There is no default, and this option must be set for every transport.

</P>
<P>
<A NAME="IDX1047"></A>


<H3><A NAME="SEC407" HREF="spec_toc.html#TOC407">envelope_to_add (transport)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
If this option is true, an <EM>Envelope-to:</EM> header
<A NAME="IDX1048"></A>
is added to the message. This gives the original address(es) in the incoming
envelope that caused this delivery to happen. More than one address may be
present if <EM>batch</EM> or <EM>bsmtp</EM> is set on transports that support them, or if
more than one original address was aliased or forwarded to the same final
address. As this is not a standard header, Exim has a configuration option
(<EM>envelope_to_remove</EM>) which requests its removal from incoming messages, so
that delivered messages can safely be resent to other recipients.

</P>
<P>
<A NAME="IDX1049"></A>


<H3><A NAME="SEC408" HREF="spec_toc.html#TOC408">headers_add (transport)</A></H3>

<P>
Type: string<BR>
Default: unset

</P>
<P>
<A NAME="IDX1050"></A>
This option specifies a string of text which is expanded and added to the
header portion of a message as it is transported.
If the result of the expansion is an empty string, or if the expansion is
forced to fail, no action is taken. Other expansion failures are treated as
errors and cause the delivery to be deferred.
The expanded string should be in the form of one or more RFC 822 header lines,
separated by newlines (coded as `\n' inside a quoted string), for example:

<PRE>
headers_add = "X-added: this is a header added at $tod_log\n\
               X-added: this is another"
</PRE>

<P>
Exim does not check the syntax of these added headers. A newline is supplied at
the end if one is not present. The text is added at the end of any existing
headers. If you include a blank line within the string, you can subvert this
facility into adding text at the start of the message's body.

</P>
<P>
The name <EM>add_headers</EM> was formerly used for this option, and is retained as a
synonym for backward compatibility. Additional headers can also be specified by
directors and routers. See chapter 20 and section
49.13.

</P>
<P>
<A NAME="IDX1051"></A>


<H3><A NAME="SEC409" HREF="spec_toc.html#TOC409">headers_only (transport)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
<A NAME="IDX1052"></A>
<A NAME="IDX1053"></A>
<A NAME="IDX1054"></A>
If this option is set, the message's body is not transported. It is mutually
exclusive with <EM>body_only</EM>. If it is used with the <EM>appendfile</EM> or <EM>pipe</EM>
transports, the settings of <EM>prefix</EM> and <EM>suffix</EM> should be checked, since this
option does not automatically suppress them.

</P>
<P>
<A NAME="IDX1055"></A>


<H3><A NAME="SEC410" HREF="spec_toc.html#TOC410">headers_remove (transport)</A></H3>

<P>
Type: string<BR>
Default: unset

</P>
<P>
<A NAME="IDX1056"></A>
This option is expanded; the result must consist
of a colon-separated list of header names, not including the terminating colon,
for example:

<PRE>
headers_remove = return-receipt-to:acknowledge-to
</PRE>

<P>
Any existing headers matching those names are not included in any message that
transmitted by the transport. However, added headers may have these names.
Thus it is possible to replace a header by specifying it in <EM>remove_headers</EM>
and supplying the replacement in <EM>add_headers</EM>.

</P>
<P>
The name <EM>remove_headers</EM> was formerly used for this option, and is retained
as a synonym for backward compatibility. Headers to be removed can also be
specified by directors and routers. See chapter 20 and
section 49.13.

</P>
<P>
<font color=green>
<A NAME="IDX1057"></A>


<H3><A NAME="SEC411" HREF="spec_toc.html#TOC411">headers_rewrite (transport)</A></H3>

<P>
Type: string<BR>
Default: unset

</P>
<P>
<A NAME="IDX1058"></A>
<A NAME="IDX1059"></A>
This option allows addresses in header lines to be rewritten at transport time,
that is, as the message is being copied to its destination. The contents of the
option are a colon-separated list of rewriting rules. Each rule is in exactly
the same form as one of the general rewriting rules that are applied when a
message is received. These are described in chapter 34. For example,

<PRE>
headers_rewrite = a@b c@d f : \
                  x@y w@z
</PRE>

<P>
changes <EM>a@b</EM> into <EM>c@d</EM> in <EM>From:</EM> header lines, and <EM>x@y</EM> into <EM>w@z</EM> in
all address-bearing header lines. The rules are applied to the header lines
just before they are  written out at transport time, so they affect only those
copies of the message that pass through the transport. However, only the
message's original header lines, and any that were added by a system filter,
are rewritten. If a router, director, or transport adds header lines, these are
not affected. These rewriting rules are <EM>not</EM> applied to the envelope. You
can change the return path using <EM>return_path</EM>; you cannot change envelope
recipients at this time.
</font>

</P>
<P>
<A NAME="IDX1060"></A>


<H3><A NAME="SEC412" HREF="spec_toc.html#TOC412">message_size_limit (transport)</A></H3>

<P>
Type: integer<BR>
Default: 0

</P>
<P>
This option controls the size of messages passed through the transport. If its
value is greater than zero and the size of a message message exceeds the
limit, the address is failed. If there is any chance that the resulting bounce
message could be routed to the same transport, you should ensure that
<EM>return_size_limit</EM> is less than the transport's <EM>message_size_limit</EM>, as
otherwise the bounce message will fail to get delivered.

</P>
<P>
<A NAME="IDX1061"></A>


<H3><A NAME="SEC413" HREF="spec_toc.html#TOC413">return_path (transport)</A></H3>

<P>
Type: string, expanded<BR>
Default: unset

</P>
<P>
If this option is set, the string is expanded at transport time and replaces
the existing return path (envelope sender) value. The expansion can refer to
the existing value via $<EM>return_path</EM>. If the expansion is forced to fail, no
replacement occurs; if it fails for another reason, Exim panics. This option
can be used to support VERP (Variable Envelope Return Paths) -- see chapter
48.

</P>

<P>
<A NAME="IDX1062"></A>


<H3><A NAME="SEC414" HREF="spec_toc.html#TOC414">return_path_add (transport)</A></H3>

<P>
Type: boolean<BR>
Default: false

</P>
<P>
If this option is true, a <EM>Return-path:</EM> header
<A NAME="IDX1063"></A>
is added to the message. Although the return path is normally available in the
prefix line of BSD mailboxes, this is commonly not displayed by MUAs, and so
the user does not have easy access to it.

</P>
<P>
RFC 822 states that the <EM>Return-path:</EM> header is `added by the final transport
system that delivers the message to its recipient' (section 4.3.1), which
implies that this header should not be present in incoming messages. Exim has a
configuration option, <EM>return_path_remove</EM>, which requests removal of this
header from incoming messages, so that delivered messages can safely be resent
to other recipients.

</P>
<P>
<A NAME="IDX1064"></A>


<H3><A NAME="SEC415" HREF="spec_toc.html#TOC415">shadow_condition (transport)</A></H3>

<P>
Type: string, expanded<BR>
Default: unset

</P>
<P>
See <EM>shadow_transport</EM> below.

</P>
<P>
<A NAME="IDX1065"></A>


<H3><A NAME="SEC416" HREF="spec_toc.html#TOC416">shadow_transport (transport)</A></H3>

<P>
Type: string<BR>
Default: unset

</P>
<P>
<A NAME="IDX1066"></A>
<A NAME="IDX1067"></A>
This facility is somewhat experimental, and may change in future. A local
transport may set the <EM>shadow_transport</EM> option to the name of another,
previously-defined, local transport. Shadow remote transports are not
supported.

</P>
<P>
Whenever a delivery to the main transport succeeds, and either
<EM>shadow_condition</EM> is unset, or its expansion does not result in a forced
expansion failure or the empty string or one of the strings `0' or `no' or
`false', the message is also passed to the shadow transport,
<font color=green>
with the same delivery address or addresses.
</font>
However, the result of the shadow transport is discarded and does not affect
the subsequent processing of the message. Only a single level of shadowing is
provided; the <EM>shadow_transport</EM> option is ignored on any transport when it is
running as a shadow. Options concerned with output from pipes are also ignored.

</P>
<P>
The log line for the successful delivery has an item added on the end, of the
form

<PRE>
ST=&#60;<EM>shadow transport name</EM>&#62;
</PRE>

<P>
If the shadow transport did not succeed, the error message is put in
parentheses afterwards.

</P>
<P>
Shadow transports can be used for a number of different purposes, including
keeping more detailed log information than Exim normally provides, and
implementing automatic acknowledgement policies based on message headers that
some sites insist on.

</P>

<P>
<A NAME="IDX1068"></A>


<H3><A NAME="SEC417" HREF="spec_toc.html#TOC417">transport_filter (transport)</A></H3>

<P>
Type: string<BR>
Default: unset

</P>
<P>
<A NAME="IDX1069"></A>
<A NAME="IDX1070"></A>
This option sets up a filtering (in the Unix shell sense) process for messages
at transport time. It should not be confused with mail filtering as set up by
individual users or via a system filter.

</P>
<P>
When the message is about to be written out, the command specified by
<EM>transport_filter</EM> is started up in a separate process, and the entire
message, including the headers, is passed to it on its standard input (this in
fact is done from a third process, to avoid deadlock). This happens before any
SMTP-specific processing, such as turning `\n' into `\r\n' and escaping
lines beginning with a dot, and also before any processing implied by the
settings of <EM>check_string</EM> and <EM>escape_string</EM> in the <EM>appendfile</EM> or
<font color=green>
<EM>pipe</EM>
</font>
transports.

</P>
<P>
The filter's standard output is read and written to the message's destination.
The filter can perform any transformations it likes, but of course should take
care not to break RFC 822 syntax. A demonstration Perl script is provided in
<EM>util/transport-filter.pl</EM>; this makes a few arbitrary modifications just to
show the possibilities.
<font color=green>
Exim does not check the result, except to test for a final newline when SMTP is
in use. All messages transmitted over SMTP must end with a newline, so Exim
supplies one if it is missing.
</font>

</P>

<P>
<A NAME="IDX1071"></A>
A problem might arise if the filter increases the size of a message that is
being sent down an SMTP channel. If the receiving SMTP server has indicated
support for the SIZE parameter, Exim will have sent the size of the message
at the start of the SMTP session. If what is actually sent is substantially
more, the server might reject the message. This can be worked round by setting
the <EM>size_addition</EM> option on the <EM>smtp</EM> transport, either to allow for
additions to the message, or to disable the use of SIZE altogether.

</P>

<P>
The value of the option is the command string for starting up the filter, which
is run directly from Exim, not under a shell. The string is parsed by Exim in
the same way as a command string for the <EM>pipe</EM> transport: Exim breaks it up
into arguments and then expands each argument separately. The special argument
$<EM>pipe_addresses</EM> is replaced by a number of arguments, one for each address
that applies to this delivery. (This isn't an ideal name for this feature here,
but as it was already implemented for the <EM>pipe</EM> transport, it seemed sensible
not to change it.)

</P>
<P>
The expansion variables $<EM>host</EM> and $<EM>host_address</EM> are available when the
transport is a remote one. They are set only for the expansion of a transport
filter command, as that is the only thing that is expanded after a connection
has been set up. For example:

<PRE>
transport_filter = /some/directory/transport-filter.pl \
  $host $host_address $sender_address $pipe_addresses
</PRE>

<P>
The filter process is run under the same uid and gid as the normal delivery.
For remote deliveries this is the exim uid/gid if they are defined.

</P>
<P>
If a transport filter is set on an autoreply transport, the original message is
passed through the filter as it is being copied into the newly generated
message, which happens if the <EM>return_message</EM> option is set.

</P>

<P><HR><P>
Go to the <A HREF="spec_1.html">first</A>, <A HREF="spec_13.html">previous</A>, <A HREF="spec_15.html">next</A>, <A HREF="spec_59.html">last</A> section, <A HREF="spec_toc.html">table of contents</A>.
</BODY>
</HTML>