X-Git-Url: https://git.exim.org/users/jgh/exim.git/blobdiff_plain/9214d2e4dfd9d4f29e9cb7a0eea8a0758ed1b34a..1639c98f27941500daba8e74f5efb331a35f69e2:/doc/doc-docbook/spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 0e44b119b..c4e9ce284 100644
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -3966,7 +3966,7 @@ user.
 .vitem &%-MG%&&~<&'queue&~name'&>&~<&'message&~id'&>&~<&'message&~id'&>&~...
 .oindex "&%-MG%&"
 .cindex queue named
-.cindex "named queues"
+.cindex "named queues" "moving messages"
 .cindex "queue" "moving messages"
 This option requests that each listed message be moved from its current
 queue to the given named queue.
@@ -4185,6 +4185,7 @@ forces queueing.
 .vitem &%-odqs%&
 .oindex "&%-odqs%&"
 .cindex "SMTP" "delaying delivery"
+.cindex "first pass routing"
 This option is a hybrid between &%-odb%&/&%-odi%& and &%-odq%&.
 However, like &%-odb%& and &%-odi%&, this option has no effect if
 &%queue_only_override%& is false and one of the queueing options in the
@@ -4503,6 +4504,7 @@ appear in the correct order. Each flag is described in a separate item below.
 .cindex "queue" "double scanning"
 .cindex "queue" "routing"
 .cindex "routing" "whole queue before delivery"
+.cindex "first pass routing"
 An option starting with &%-qq%& requests a two-stage queue run. In the first
 stage, the queue is scanned as if the &%queue_smtp_domains%& option matched
 every domain. Addresses are routed, local deliveries happen, but no remote
@@ -4553,7 +4555,7 @@ for later delivery.
 .vitem &%-q[q][i][f[f]][l][G<name>[/<time>]]]%&
 .oindex "&%-qG%&"
 .cindex queue named
-.cindex "named queues"
+.cindex "named queues"	"deliver from"
 .cindex "queue" "delivering specific messages"
 If the &'G'& flag and a name is present, the queue runner operates on the
 queue with the given name rather than the default queue.
@@ -8300,6 +8302,19 @@ domainlist  dom2 = !a.b : *.b
 where &'x.y'& does not match. It's best to avoid negation altogether in
 referenced lists if you can.
 
+.new
+.cindex "hiding named list values"
+.cindex "named lists" "hiding value of"
+Some named list definitions may contain sensitive data, for example, passwords for
+accessing databases. To stop non-admin users from using the &%-bP%& command
+line option to read these values, you can precede the definition with the
+word &"hide"&. For example:
+.code
+hide domainlist filter_for_domains = ldap;PASS=secret ldap::/// ...
+.endd
+.wen
+
+
 Named lists may have a performance advantage. When Exim is routing an
 address or checking an incoming message, it caches the result of tests on named
 lists. So, if you have a setting such as
@@ -9719,7 +9734,7 @@ letters appear. For example:
        "&*$bheader_*&<&'header&~name'&>&*:*&&~or&~&&&
         &*$bh_*&<&'header&~name'&>&*:*&" &&&
        "&*$lheader_*&<&'header&~name'&>&*:*&&~or&~&&&
-        &*$lh_*&<&'header&~name'&>&*:*&"
+        &*$lh_*&<&'header&~name'&>&*:*&" &&&
        "&*$rheader_*&<&'header&~name'&>&*:*&&~or&~&&&
         &*$rh_*&<&'header&~name'&>&*:*&"
 .cindex "expansion" "header insertion"
@@ -12831,7 +12846,7 @@ or if not set, the value of &$qualify_domain$&.
 
 .vitem &$queue_name$&
 .vindex &$queue_name$&
-.cindex "named queues"
+.cindex "named queues" variable
 .cindex queues named
 The name of the spool queue in use; empty for the default queue.
 
@@ -16746,13 +16761,14 @@ run. If you do not want queue runs to occur, omit the &%-q%&&'xx'& setting on
 the daemon's command line.
 
 .cindex queues named
-.cindex "named queues"
+.cindex "named queues" "resource limit"
 To set limits for different named queues use
 an expansion depending on the &$queue_name$& variable.
 
 .option queue_smtp_domains main "domain list&!!" unset
 .cindex "queueing incoming messages"
 .cindex "message" "queueing remote deliveries"
+.cindex "first pass routing"
 When this option is set, a delivery process is started whenever a message is
 received, routing is performed, and local deliveries take place.
 However, if any SMTP deliveries are required for domains that match
@@ -20579,6 +20595,10 @@ yield empty addresses, for example, items containing only RFC 2822 address
 comments.
 
 .new
+.cindex "tainted data" "in filenames"
+.cindex redirect "tainted data"
+Tainted data may not be used for a filename.
+
 &*Warning*&: It is unwise to use &$local_part$& or &$domain$&
 directly for redirection,
 as they are provided by a potential attacker.
@@ -20812,6 +20832,11 @@ It must be given as
 .code
 list1:   :include:/opt/lists/list1
 .endd
+.new
+.cindex "tainted data" "in filenames"
+.cindex redirect "tainted data"
+Tainted data may not be used for a filename.
+.wen
 .next
 .cindex "address redirection" "to black hole"
 .cindex "delivery" "discard"
@@ -27544,6 +27569,19 @@ This option is exapanded before use, and should result in
 the account name to be used.
 .wen
 
+.new
+.option client_spassword gsasl string&!! unset
+If a SCRAM mechanism is being used and this option is set
+it is used in preference to &%client_password%&.
+The value after expansion should be
+a 40 (for SHA-1) or 64 (for SHA-256) character string
+with the PBKDF2-prepared password, hex-encoded.
+Note that this value will depend on the salt and iteration-count
+supplied by the server.
+.wen
+
+
+
 .option server_channelbinding gsasl boolean false
 Do not set this true and rely on the properties
 without consulting a cryptographic engineer.
@@ -27620,7 +27658,8 @@ Some mechanisms will use this data.
 .option server_scram_iter gsasl string&!! 4096
 This option provides data for the SCRAM family of mechanisms.
 .new
-The &$auth1$&, &$auth2$& and &$auth3$& variables are available for expansion.
+The &$auth1$&, &$auth2$& and &$auth3$& variables are available
+when this option is expanded.
 
 The result of expansion should be a decimal number,
 and represents both a lower-bound on the security, and
@@ -27628,19 +27667,50 @@ a compute cost factor imposed on the client
 (if it does not cache results, or the server changes
 either the iteration count or the salt).
 A minimum value of 4096 is required by the standards
-for all current CRAM mechanism variants.
+for all current SCRAM mechanism variants.
 .wen
 
-
 .option server_scram_salt gsasl string&!! unset
 This option provides data for the SCRAM family of mechanisms.
 .new
-The &$auth1$&, &$auth2$& and &$auth3$& variables are available for expansion.
+The &$auth1$&, &$auth2$& and &$auth3$& variables are available
+when this option is expanded.
+The value should be a base64-encoded string,
+of random data typically 4-to-16 bytes long.
 If unset or empty after expansion the library will provides a value for the
 protocol conversation.
 .wen
 
 
+.new
+.option server_key gsasl string&!! unset
+.option server_skey gsasl string&!! unset
+These options can be used for the SCRAM family of mechanisms
+to provide stored information related to a password,
+the storage of which is preferable to plaintext.
+
+&%server_key%& is the value defined in the SCRAM standards as ServerKey;
+&%server_skey%& is StoredKey.
+
+They are only available for version 1.9.0 (or later) of the gsasl library.
+When this is so, the macros
+_OPT_AUTHENTICATOR_GSASL_SERVER_KEY
+and _HAVE_AUTH_GSASL_SCRAM_S_KEY
+will be defined.
+
+The &$authN$& variables are available when these options are expanded.
+
+If set, the results of expansion should for each
+should be a 28 (for SHA-1) or 44 (for SHA-256) character string
+of base64-coded data, and will be used in preference to the
+&%server_password%& option.
+If unset or not of the right length, &%server_password%& will be used.
+
+The libgsasl library release includes a utility &'gsasl'& which can be used
+to generate these values.
+.wen
+
+
 .option server_service gsasl string &`smtp`&
 This is the SASL service that the server claims to implement.
 Some mechanisms will use this data.
@@ -30650,16 +30720,32 @@ response to an EHLO command. Therefore, it should normally appear in an ACL
 controlled by &%acl_smtp_connect%& or &%acl_smtp_helo%&. See also
 &%pipelining_advertise_hosts%&.
 
-.vitem &*control&~=&~queue_only*&
+.new
+.vitem &*control&~=&~queue/*&<&'options'&>* &&&
+       &*control&~=&~queue_only*&
+.oindex "&%queue%&"
 .oindex "&%queue_only%&"
 .cindex "queueing incoming messages"
+.cindex queueing "forcing in ACL"
+.cindex "first pass routing"
 This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, in
 other words, only when a message is being received. If the message is accepted,
 it is placed on Exim's queue and left there for delivery by a subsequent queue
-runner. No immediate delivery process is started. In other words, it has the
-effect as the &%queue_only%& global option. However, the control applies only
-to the current message, not to any subsequent ones that may be received in the
-same SMTP connection.
+runner.
+If used with no options set,
+no immediate delivery process is started. In other words, it has the
+effect as the &%queue_only%& global option or &'-odq'& command-line option.
+
+If the &'first_pass_route'& option is given then
+the behaviour is like the command-line &'-oqds'& option;
+a delivery process is started which stops short of making
+any SMTP delivery.  The benefit is that the hints database will be updated for
+the message being waiting for a specific host, and a later queue run will be
+able to send all such messages on a single connection.
+
+The control only applies to the current message, not to any subsequent ones that
+ may be received in the same SMTP connection.
+.wen
 
 .vitem &*control&~=&~submission/*&<&'options'&>
 .cindex "message" "submission"
@@ -36792,6 +36878,7 @@ delivered immediately.
 .cindex "SMTP" "passed connection"
 .cindex "SMTP" "multiple deliveries"
 .cindex "multiple SMTP deliveries"
+.cindex "first pass routing"
 Mail waiting to be sent from an intermittently connected host will probably
 not have been routed, because without a connection DNS lookups are not
 possible. This means that if a normal queue run is done at connection time,