Docs: indexing

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index d62ceafd73c5047de20d559ed24fa03cf719c115..ab76e873bdb3566e47942d61c1cf5b600a0f4974 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -161,6 +161,13 @@
 .macro index
 .echo "** Don't use .index; use .cindex or .oindex or .vindex"
 .endmacro
+
+
+. use this for a concept-index entry for a header line
+.macro chindex
+.cindex "&'$1'& header line"
+.cindex "header lines" $1
+.endmacro
 . ////////////////////////////////////////////////////////////////////////////
 
 
@@ -193,6 +200,8 @@
 . This chunk of literal XML implements index entries of the form "x, see y" and
 . "x, see also y". However, the DocBook DTD doesn't allow <indexterm> entries
 . at the top level, so we have to put the .chapter directive first.
+
+. These do not turn up in the HTML output, unfortunately.  The PDF does get them.
 . /////////////////////////////////////////////////////////////////////////////
 
 .chapter "Introduction" "CHID1"
@@ -318,6 +327,10 @@
   <primary>zero, binary</primary>
   <see><emphasis>binary zero</emphasis></see>
 </indexterm>
+<indexterm role="concept">
+  <primary>headers</primary>
+  <see><emphasis>header lines</emphasis></see>
+</indexterm>
 
 .literal off
 
@@ -2683,10 +2696,8 @@ Exim through the local interface (see the &%-bm%& and &%-f%& options below).
 See the &%untrusted_set_sender%& option for a way of permitting non-trusted
 users to set envelope senders.
 
-.cindex "&'From:'& header line"
-.cindex "&'Sender:'& header line"
-.cindex "header lines" "From:"
-.cindex "header lines" "Sender:"
+.chindex From:
+.chindex Sender:
 For a trusted user, there is never any check on the contents of the &'From:'&
 header line, and a &'Sender:'& line is never added. Furthermore, any existing
 &'Sender:'& line in incoming local (non-TCP/IP) messages is not removed.
@@ -3885,7 +3896,9 @@ id, and the remaining ones must be email addresses. However, if the message is
 active (in the middle of a delivery attempt), it is not altered. This option
 can be used only by an admin user.
 
-.vitem "&%-MC%&&~<&'transport'&>&~<&'hostname'&>&~<&'sequence&~number'&>&&&
+.vitem "&%-MC%&&~<&'transport'&>&~<&'hostname'&>&&&
+       &~<&'host&~IP'&>&&&
+       &~<&'sequence&~number'&>&&&
         &~<&'message&~id'&>"
 .oindex "&%-MC%&"
 .cindex "SMTP" "passed connection"
@@ -4782,9 +4795,9 @@ recognized when Exim is run normally. It allows for the setting up of explicit
 .vitem &%-t%&
 .oindex "&%-t%&"
 .cindex "recipient" "extracting from header lines"
-.cindex "&'Bcc:'& header line"
-.cindex "&'Cc:'& header line"
-.cindex "&'To:'& header line"
+.chindex Bcc:
+.chindex Cc:
+.chindex To:
 When Exim is receiving a locally-generated, non-SMTP message on its standard
 input, the &%-t%& option causes the recipients of the message to be obtained
 from the &'To:'&, &'Cc:'&, and &'Bcc:'& header lines in the message instead of
@@ -9716,7 +9729,7 @@ If the ACL returns defer the result is a forced-fail.  Otherwise the expansion f
 
 .vitem "&*${authresults{*&<&'authserv-id'&>&*}}*&"
 .cindex authentication "results header"
-.cindex headers "authentication-results:"
+.chindex Authentication-Results:
 .cindex authentication "expansion item"
 This item returns a string suitable for insertion as an
 &'Authentication-Results:'&
@@ -13703,7 +13716,11 @@ filter file to set values that can be tested in users' filter files. For
 example, a system filter could set a value indicating how likely it is that a
 message is junk mail.
 
-.vitem &$spam_$&&'xxx'&
+.vitem &$spam_score$& &&&
+       &$spam_score_int$& &&&
+       &$spam_bar$& &&&
+       &$spam_report$& &&&
+       &$spam_action$&
 A number of variables whose names start with &$spam$& are available when Exim
 is compiled with the content-scanning extension. For details, see section
 &<<SECTscanspamass>>&.
@@ -16977,7 +16994,7 @@ not count as protocol errors (see &%smtp_max_synprot_errors%&).
 .option pipelining_connect_advertise_hosts main "host list&!!" *
 .cindex "pipelining" "early connection"
 .cindex "pipelining" PIPE_CONNECT
-.cindex "ESMTP extensions" X_PIPE_CONNECT
+.cindex "ESMTP extensions" PIPE_CONNECT
 If Exim is built with the SUPPORT_PIPE_CONNECT build option
 this option controls which hosts the facility is advertised to
 and from which pipeline early-connection (before MAIL) SMTP
@@ -16986,7 +17003,9 @@ When used, the pipelining saves on roundtrip times.
 
 See also the &%hosts_pipe_connect%& smtp transport option.
 
-Currently the option name &"X_PIPE_CONNECT"& is used.
+.new
+The SMTP service extension keyword advertised is &"PIPE_CONNECT"&.
+.wen
 
 
 .option prdr_enable main boolean false
@@ -19724,6 +19743,10 @@ Values containing a list-separator should have them doubled.
 When a router runs, the strings are evaluated in order,
 to create variables which are added to the set associated with
 the address.
+.new
+This is done immediately after all the preconditions, before the
+evaluation of the &%address_data%& option.
+.wen
 The variable is set with the expansion of the value.
 The variables can be used by the router options
 (not including any preconditions)
@@ -22571,7 +22594,7 @@ This defaults to the incoming sender address, but can be changed by setting
 
 
 .option return_path_add transports boolean false
-.cindex "&'Return-path:'& header line"
+.chindex Return-path:
 If this option is true, a &'Return-path:'& header 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
@@ -27362,7 +27385,7 @@ conditions:
 .ilist
 The client host must match &%auth_advertise_hosts%& (default *).
 .next
-It the &%server_advertise_condition%& option is set, its expansion must not
+If the &%server_advertise_condition%& option is set, its expansion must not
 yield the empty string, &"0"&, &"no"&, or &"false"&.
 .endlist
 
@@ -27470,7 +27493,7 @@ encode '\0user@domain.com\0pas$$word'
 .endd
 gives an incorrect answer because of the unescaped &"@"& and &"$"& characters.
 
-If you have the &%mimencode%& command installed, another way to do produce
+If you have the &%mimencode%& command installed, another way to produce
 base64-encoded strings is to run the command
 .code
 echo -e -n `\0user\0password' | mimencode
@@ -27812,7 +27835,14 @@ fixed_plain:
   client_send = ^username^mysecret
 .endd
 The lack of colons means that the entire text is sent with the AUTH
-command, with the circumflex characters converted to NULs. A similar example
+command, with the circumflex characters converted to NULs.
+.new
+Note that due to the ambiguity of parsing three consectutive circumflex characters
+there is no way to provide a password having a leading circumflex.
+.wen
+
+
+A similar example
 that uses the LOGIN mechanism is:
 .code
 fixed_login:
@@ -28169,6 +28199,10 @@ supplied by the server.
 .option server_channelbinding gsasl boolean false
 Do not set this true and rely on the properties
 without consulting a cryptographic engineer.
+. Unsure what that's about.  It might be the "Triple Handshake"
+. vulnerability; cf. https://www.mitls.org/pages/attacks/3SHAKE
+. If so, we're ok, requiring Extended Master Secret if TLS
+. Session Resumption was used.
 
 Some authentication mechanisms are able to use external context at both ends
 of the session to bind the authentication to that context, and fail the
@@ -36007,8 +36041,7 @@ incoming SMTP message from a source that is not permitted to send them.
 
 
 .section "Resent- header lines" "SECID220"
-.cindex "&%Resent-%& header lines"
-.cindex "header lines" "Resent-"
+.chindex Resent-
 RFC 2822 makes provision for sets of header lines starting with the string
 &`Resent-`& to be added to a message when it is resent by the original
 recipient to somebody else. These headers are &'Resent-Date:'&,
@@ -36064,8 +36097,7 @@ existing &'Bcc:'& is not removed.
 
 
 .section "The Date: header line" "SECID223"
-.cindex "&'Date:'& header line"
-.cindex "header lines" "Date:"
+.cindex Date:
 If a locally-generated or submission-mode message has no &'Date:'& header line,
 Exim adds one, using the current date and time, unless the
 &%suppress_local_fixups%& control has been specified.
@@ -36082,8 +36114,7 @@ messages.
 
 
 .section "The Envelope-to: header line" "SECID225"
-.cindex "&'Envelope-to:'& header line"
-.cindex "header lines" "Envelope-to:"
+.chindex Envelope-to:
 .oindex "&%envelope_to_remove%&"
 &'Envelope-to:'& header lines are not part of the standard RFC 2822 header set.
 Exim can be configured to add them to the final delivery of messages. (See the
@@ -36094,8 +36125,7 @@ messages.
 
 
 .section "The From: header line" "SECTthefrohea"
-.cindex "&'From:'& header line"
-.cindex "header lines" "From:"
+.chindex From:
 .cindex "Sendmail compatibility" "&""From""& line"
 .cindex "message" "submission"
 .cindex "submission mode"
@@ -36138,8 +36168,7 @@ name as described in section &<<SECTconstr>>&.
 
 
 .section "The Message-ID: header line" "SECID226"
-.cindex "&'Message-ID:'& header line"
-.cindex "header lines" "Message-ID:"
+.chindex Message-ID:
 .cindex "message" "submission"
 .oindex "&%message_id_header_text%&"
 If a locally-generated or submission-mode incoming message does not contain a
@@ -36154,8 +36183,7 @@ in this header line by setting the &%message_id_header_text%& and/or
 
 
 .section "The Received: header line" "SECID227"
-.cindex "&'Received:'& header line"
-.cindex "header lines" "Received:"
+.chindex Received:
 A &'Received:'& header line is added at the start of every message. The
 contents are defined by the &%received_header_text%& configuration option, and
 Exim automatically adds a semicolon and a timestamp to the configured string.
@@ -36171,8 +36199,7 @@ changed to the time of acceptance, which is (apart from a small delay while the
 
 
 .section "The References: header line" "SECID228"
-.cindex "&'References:'& header line"
-.cindex "header lines" "References:"
+.chindex References:
 Messages created by the &(autoreply)& transport include a &'References:'&
 header line. This is constructed according to the rules that are described in
 section 3.64 of RFC 2822 (which states that replies should contain such a
@@ -36186,8 +36213,7 @@ incoming message. If there are more than 12, the first one and then the final
 
 
 .section "The Return-path: header line" "SECID229"
-.cindex "&'Return-path:'& header line"
-.cindex "header lines" "Return-path:"
+.chindex Return-path:
 .oindex "&%return_path_remove%&"
 &'Return-path:'& header lines are defined as something an MTA may insert when
 it does the final delivery of messages. (See the generic &%return_path_add%&
@@ -36200,7 +36226,7 @@ default), Exim removes &'Return-path:'& header lines from incoming messages.
 .section "The Sender: header line" "SECTthesenhea"
 .cindex "&'Sender:'& header line"
 .cindex "message" "submission"
-.cindex "header lines" "Sender:"
+.chindex Sender:
 For a locally-originated message from an untrusted user, Exim may remove an
 existing &'Sender:'& header line, and it may add a new one. You can modify
 these actions by setting the &%local_sender_retain%& option true, the
@@ -38300,8 +38326,11 @@ parentheses afterwards.
 When more than one address is included in a single delivery (for example, two
 SMTP RCPT commands in one transaction) the second and subsequent addresses are
 flagged with &`->`& instead of &`=>`&. When two or more messages are delivered
-down a single SMTP connection, an asterisk follows the IP address in the log
-lines for the second and subsequent messages.
+down a single SMTP connection, an asterisk follows the
+.new
+remote IP address (and port if enabled)
+.wen
+in the log lines for the second and subsequent messages.
 When two or more messages are delivered down a single TLS connection, the
 DNS and some TLS-related information logged for the first message delivered
 will not be present in the log lines for the second and subsequent messages.
@@ -38668,6 +38697,7 @@ routing email addresses, but it does apply to &"byname"& lookups.
 client's ident port times out.
 .next
 .cindex "log" "incoming interface"
+.cindex "log" "outgoing interface"
 .cindex "log" "local interface"
 .cindex "log" "local address and port"
 .cindex "TCP/IP" "logging local address and port"
@@ -38676,7 +38706,10 @@ client's ident port times out.
 to the &"<="& line as an IP address in square brackets, tagged by I= and
 followed by a colon and the port number. The local interface and port are also
 added to other SMTP log lines, for example, &"SMTP connection from"&, to
-rejection lines, and (despite the name) to outgoing &"=>"& and &"->"& lines.
+rejection lines, and (despite the name) to outgoing
+.new
+&"=>"&, &"->"&, &"=="& and &"**"& lines.
+.wen
 The latter can be disabled by turning off the &%outgoing_interface%& option.
 .next
 .cindex log "incoming proxy address"