Routers: named variables

[users/jgh/exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index d2a5499e8ba680222c86068742865e02a59d4941..a073730c61e99427d4b613128c5244fe206c4c5c 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -2626,6 +2626,7 @@ supplementary group is one of those listed in the &%trusted_groups%&
 configuration option. Note that the Exim group is not automatically trusted.
 
 .cindex '&"From"& line'
+.cindex "envelope from"
 .cindex "envelope sender"
 Trusted users are always permitted to use the &%-f%& option or a leading
 &"From&~"& line to specify the envelope sender of a message that is passed to
@@ -2877,6 +2878,7 @@ separate document entitled &'Exim's interfaces to mail filtering'&.
 
 When testing a filter file,
 .cindex "&""From""& line"
+.cindex "envelope from"
 .cindex "envelope sender"
 .oindex "&%-f%&" "for filter testing"
 the envelope sender can be set by the &%-f%& option,
@@ -3717,6 +3719,7 @@ between &%-F%& and the <&'string'&> is optional.
 .cindex "sender" "address"
 .cindex "address" "sender"
 .cindex "trusted users"
+.cindex "envelope from"
 .cindex "envelope sender"
 .cindex "user" "trusted"
 This option sets the address of the envelope sender of a locally-generated
@@ -12756,6 +12759,16 @@ or if not set, the value of &$qualify_domain$&.
 .cindex queues named
 The name of the spool queue in use; empty for the default queue.
 
+.new
+.vitem &$r_...$&
+.vindex &$r_...$&
+.cindex router variables
+Values can be placed in these variables by the &%set%& option of a router.
+They can be given any name that starts with &$r_$&.
+The values persist for the address being handled through subsequent routers
+and the eventual transport.
+.wen
+
 .vitem &$rcpt_count$&
 .vindex "&$rcpt_count$&"
 When a message is being received by SMTP, this variable contains the number of
@@ -15893,6 +15906,7 @@ and no &'Sender:'& header is ever added. If, in addition, you want to retain
 &'Sender:'& header lines supplied by untrusted users, you must also set
 &%local_sender_retain%& to be true.
 
+.cindex "envelope from"
 .cindex "envelope sender"
 These options affect only the header lines in the message. The envelope sender
 is still forced to be the login id at the qualify domain unless
@@ -17923,6 +17937,7 @@ See &%unknown_login%&.
 .cindex "sender" "setting by untrusted user"
 .cindex "untrusted user setting sender"
 .cindex "user" "untrusted setting sender"
+.cindex "envelope from"
 .cindex "envelope sender"
 When an untrusted user submits a message to Exim using the standard input, Exim
 normally creates an envelope sender address from the user's login and the
@@ -18073,6 +18088,10 @@ file = ${extract{mailbox}{$address_data}}
 This makes the configuration file less messy, and also reduces the number of
 lookups (though Exim does cache lookups).
 
+.new
+See also the &%set%& option below.
+.wen
+
 .vindex "&$sender_address_data$&"
 .vindex "&$address_data$&"
 The &%address_data%& facility is also useful as a means of passing information
@@ -18325,6 +18344,7 @@ Not effective on redirect routers.
 
 
 .option errors_to routers string&!! unset
+.cindex "envelope from"
 .cindex "envelope sender"
 .cindex "router" "changing address for errors"
 If a router successfully handles an address, it may assign the address to a
@@ -18986,6 +19006,27 @@ SMTP VRFY command is enabled, it must be used after MAIL if the sender address
 matters.
 
 
+.new
+.option set routers string unset
+.cindex router variables
+This option may be used multiple times on a router.
+Each string given must be of the form $"name = value"$
+and the names used must start with the string &"r_"&.
+Strings are accumulated for each router which is run.
+When a router runs, the strings are evaluated in order,
+to create variables.
+The variable is set with the expansion of the value.
+The variables can be used by the router options
+(not including any preconditions)
+and by the transport.
+Later definitions of a given named variable will override former ones.
+Varible use is via the usual &$r_...$& syntax.
+
+This is similar to the &%address_data%& option, except that
+many independent variables can be used, with choice of naming.
+.wen
+
+
 .option translate_ip_address routers string&!! unset
 .cindex "IP address" "translating"
 .cindex "packet radio"
@@ -21771,6 +21812,7 @@ on a remote transport in the current implementation.
 
 .option return_path transports string&!! unset
 .cindex "envelope sender"
+.cindex "envelope from"
 .cindex "transport" "return path; changing"
 .cindex "return path" "changing in transport"
 If this option is set, the string is expanded at transport time and replaces
@@ -22817,6 +22859,7 @@ percentage.
 
 
 .option use_bsmtp appendfile boolean false
+.cindex "envelope from"
 .cindex "envelope sender"
 If this option is set true, &(appendfile)& writes messages in &"batch SMTP"&
 format, with the envelope sender and recipient(s) included as SMTP commands. If
@@ -25312,6 +25355,7 @@ When an address is being routed, either for delivery or for verification,
 rewriting is applied immediately to child addresses that are generated by
 redirection, unless &%no_rewrite%& is set on the router.
 
+.cindex "envelope from"
 .cindex "envelope sender" "rewriting at transport time"
 .cindex "rewriting" "at transport time"
 .cindex "header lines" "rewriting at transport time"
@@ -34415,6 +34459,7 @@ headers remove "Old-Subject"
 
 
 .section "Setting an errors address in a system filter" "SECID217"
+.cindex "envelope from"
 .cindex "envelope sender"
 In a system filter, if a &%deliver%& command is followed by
 .code
@@ -34648,6 +34693,7 @@ other words, such qualification is also controlled by
 .cindex "sender" "address"
 .oindex "&%uucp_from_pattern%&"
 .oindex "&%uucp_from_sender%&"
+.cindex "envelope from"
 .cindex "envelope sender"
 .cindex "Sendmail compatibility" "&""From""& line"
 Messages that have come from UUCP (and some other applications) often begin
@@ -36096,6 +36142,7 @@ the address, giving a suitable error message.
 .section "Variable Envelope Return Paths (VERP)" "SECTverp"
 .cindex "VERP"
 .cindex "Variable Envelope Return Paths"
+.cindex "envelope from"
 .cindex "envelope sender"
 Variable Envelope Return Paths &-- see &url(https://cr.yp.to/proto/verp.txt) &--
 are a way of helping mailing list administrators discover which subscription