util/transport-filter.pl is gone.

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

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index 015d7140ec518af6acc36eb90a2a93aacec3b8c8..547bc44cc513bca1cdfec7752e4e05d4065c9236 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -1,4 +1,4 @@
-. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.34 2008/02/04 17:03:35 fanf2 Exp $
+. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.42 2008/04/16 10:16:13 fanf2 Exp $

 .
 . /////////////////////////////////////////////////////////////////////////////
 . This is the primary source of the Exim Manual. It is an xfpt document that is
 .
 . /////////////////////////////////////////////////////////////////////////////
 . This is the primary source of the Exim Manual. It is an xfpt document that is


@@ -431,8 +431,6 @@ directory are:
 .row &_exim.8_&              "a man page of Exim's command line options"
 .row &_experimental.txt_&    "documentation of experimental features"
 .row &_filter.txt_&          "specification of the filter language"
 .row &_exim.8_&              "a man page of Exim's command line options"
 .row &_experimental.txt_&    "documentation of experimental features"
 .row &_filter.txt_&          "specification of the filter language"

-.row &_pcrepattern.txt_&     "specification of PCRE regular expressions"
-.row &_pcretest.txt_&        "specification of the PCRE testing program"

 .row &_Exim3.upgrade_&       "upgrade notes from release 2 to release 3"
 .row &_Exim4.upgrade_&       "upgrade notes from release 3 to release 4"
 .endtable
 .row &_Exim3.upgrade_&       "upgrade notes from release 2 to release 3"
 .row &_Exim4.upgrade_&       "upgrade notes from release 3 to release 4"
 .endtable


@@ -732,10 +730,9 @@ A number of pieces of external code are included in the Exim distribution.
 .ilist
 Regular expressions are supported in the main Exim program and in the
 Exim monitor using the freely-distributable PCRE library, copyright
 .ilist
 Regular expressions are supported in the main Exim program and in the
 Exim monitor using the freely-distributable PCRE library, copyright

-© University of Cambridge. The source to a cut down version of PCRE
-used to be distributed in the directory &_src/pcre_&. However, this is
-no longer the case and you will need to use a system PCRE library or
-obtain and install the full version of the library from
+© University of Cambridge. The source to PCRE is no longer shipped with
+Exim, so you will need to use the version of PCRE shipped with your system,
+or obtain and install the full version of the library from

 &url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre).
 .next
 .cindex "cdb" "acknowledgment"
 &url(ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre).
 .next
 .cindex "cdb" "acknowledgment"


@@ -2226,9 +2223,8 @@ but this usage is deprecated.
 
 .cindex "installing Exim" "what is not installed"
 Running &'make install'& does not copy the Exim 4 conversion script
 
 .cindex "installing Exim" "what is not installed"
 Running &'make install'& does not copy the Exim 4 conversion script

-&'convert4r4'&, or the &'pcretest'& test program. You will probably run the
-first of these only once (if you are upgrading from Exim 3), and the second
-isn't really part of Exim. None of the documentation files in the &_doc_&
+&'convert4r4'&. You will probably run this only once if you are
+upgrading from Exim 3. None of the documentation files in the &_doc_&

 directory are copied, except for the info files when you have set
 INFO_DIRECTORY, as described in section &<<SECTinsinfdoc>>& below.
 
 directory are copied, except for the info files when you have set
 INFO_DIRECTORY, as described in section &<<SECTinsinfdoc>>& below.
 


@@ -5908,13 +5904,11 @@ Jeffrey Friedl's &'Mastering Regular Expressions'&, which is published by
 O'Reilly (see &url(http://www.oreilly.com/catalog/regex2/)).
 
 The documentation for the syntax and semantics of the regular expressions that
 O'Reilly (see &url(http://www.oreilly.com/catalog/regex2/)).
 
 The documentation for the syntax and semantics of the regular expressions that

-are supported by PCRE is included in plain text in the file
-&_doc/pcrepattern.txt_& in the Exim distribution, and also in the HTML
-tarbundle of Exim documentation. It describes in detail the features of the
-regular expressions that PCRE supports, so no further description is included
-here. The PCRE functions are called from Exim using the default option settings
-(that is, with no PCRE options set), except that the PCRE_CASELESS option is
-set when the matching is required to be case-insensitive.
+are supported by PCRE is included in the PCRE distribution, and no further
+description is included here. The PCRE functions are called from Exim using
+the default option settings (that is, with no PCRE options set), except that
+the PCRE_CASELESS option is set when the matching is required to be
+case-insensitive.

 
 In most cases, when a regular expression is required in an Exim configuration,
 it has to start with a circumflex, in order to distinguish it from plain text
 
 In most cases, when a regular expression is required in an Exim configuration,
 it has to start with a circumflex, in order to distinguish it from plain text


@@ -5953,47 +5947,6 @@ $ is needed because string expansion also interprets dollar characters.
 
 
 
 
 
 

-.section "Testing regular expressions" "SECID59"
-.cindex "testing" "regular expressions"
-.cindex "regular expressions" "testing"
-.cindex "&'pcretest'&"
-A program called &'pcretest'& forms part of the PCRE distribution and is built
-with PCRE during the process of building Exim. It is primarily intended for
-testing PCRE itself, but it can also be used for experimenting with regular
-expressions. After building Exim, the binary can be found in the build
-directory (it is not installed anywhere automatically). There is documentation
-of various options in &_doc/pcretest.txt_&, but for simple testing, none are
-needed. This is the output of a sample run of &'pcretest'&:
-.display
-&`  re> `&&*&`/^([@]+)@.+\.(ac|edu)\.(?!kr)[a-z]{2}$/`&*&
-&`data> `&&*&`x@y.ac.uk`&*&
-&` 0: x@y.ac.uk`&
-&` 1: x`&
-&` 2: ac`&
-&`data> `&&*&`x@y.ac.kr`&*&
-&`No match`&
-&`data> `&&*&`x@y.edu.com`&*&
-&`No match`&
-&`data> `&&*&`x@y.edu.co`&*&
-&` 0: x@y.edu.co`&
-&` 1: x`&
-&` 2: edu`&
-.endd
-Input typed by the user is shown in bold face. After the &"re>"& prompt, a
-regular expression enclosed in delimiters is expected. If this compiles without
-error, &"data>"& prompts are given for strings against which the expression is
-matched. An empty data line causes a new regular expression to be read. If the
-match is successful, the captured substring values (that is, what would be in
-the variables &$0$&, &$1$&, &$2$&, etc.) are shown. The above example tests for
-an email address whose domain ends with either &"ac"& or &"edu"& followed by a
-two-character top-level domain that is not &"kr"&. The local part is captured
-in &$1$& and the &"ac"& or &"edu"& in &$2$&.
-
-
-
-
-
-

 . ////////////////////////////////////////////////////////////////////////////
 . ////////////////////////////////////////////////////////////////////////////
 
 . ////////////////////////////////////////////////////////////////////////////
 . ////////////////////////////////////////////////////////////////////////////
 


@@ -10763,7 +10716,7 @@ This is an obsolete name for &$received_port$&.
 .vitem &$item$&
 .vindex "&$item$&"
 This variable is used during the expansion of &*forall*& and &*forany*&
 .vitem &$item$&
 .vindex "&$item$&"
 This variable is used during the expansion of &*forall*& and &*forany*&

-conditions (see section &<<SECTexpcond>>&), and &*filter*&, &*man*&, and
+conditions (see section &<<SECTexpcond>>&), and &*filter*&, &*map*&, and

 &*reduce*& items (see section &<<SECTexpcond>>&). In other circumstances, it is
 empty.
 
 &*reduce*& items (see section &<<SECTexpcond>>&). In other circumstances, it is
 empty.
 


@@ -19005,11 +18958,9 @@ filter itself, and the original process that reads the result and delivers it
 are all run in parallel, like a shell pipeline.
 
 The filter can perform any transformations it likes, but of course should take
 are all run in parallel, like a shell pipeline.
 
 The filter can perform any transformations it likes, but of course should take

-care not to break RFC 2822 syntax. A demonstration Perl script is provided in
-&_util/transport-filter.pl_&; this makes a few arbitrary modifications just to
-show the possibilities. 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.
+care not to break RFC 2822 syntax. 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.

 
 .cindex "content scanning" "per user"
 A transport filter can be used to provide content-scanning on a per-user basis
 
 .cindex "content scanning" "per user"
 A transport filter can be used to provide content-scanning on a per-user basis


@@ -23571,17 +23522,20 @@ login:
   driver = plaintext
   public_name = LOGIN
   server_prompts = Username:: : Password::
   driver = plaintext
   public_name = LOGIN
   server_prompts = Username:: : Password::

-  server_condition = ${if ldapauth \
-    {user="cn=${quote_ldap_dn:$auth1},ou=people,o=example.org" \
-    pass=${quote:$auth2} \
-    ldap://ldap.example.org/}}
+  server_condition = ${if and{{
+    !eq{}{$auth1} }{ \
+    ldapauth{user="cn=${quote_ldap_dn:$auth1},ou=people,o=example.org" \
+             pass=${quote:$auth2} \
+             ldap://ldap.example.org/} }} }

   server_set_id = uid=$auth1,ou=people,o=example.org
 .endd
   server_set_id = uid=$auth1,ou=people,o=example.org
 .endd

-Note the use of the &%quote_ldap_dn%& operator to correctly quote the DN for
-authentication. However, the basic &%quote%& operator, rather than any of the
-LDAP quoting operators, is the correct one to use for the password, because
-quoting is needed only to make the password conform to the Exim syntax. At the
-LDAP level, the password is an uninterpreted string.
+We have to check that the username is not empty before using it, because LDAP
+does not permit empty DN components. We must also use the &%quote_ldap_dn%&
+operator to correctly quote the DN for authentication. However, the basic
+&%quote%& operator, rather than any of the LDAP quoting operators, is the
+correct one to use for the password, because quoting is needed only to make
+the password conform to the Exim syntax. At the LDAP level, the password is an
+uninterpreted string.

 
 
 
 
 
 


@@ -24101,11 +24055,11 @@ sections &<<SECTreqciphssl>>& and &<<SECTreqciphgnu>>&.
 
 
 .section "GnuTLS parameter computation" "SECID181"
 
 
 .section "GnuTLS parameter computation" "SECID181"

-GnuTLS uses RSA and D-H parameters that may take a substantial amount of time
+GnuTLS uses D-H parameters that may take a substantial amount of time

 to compute. It is unreasonable to re-compute them for every TLS session.
 Therefore, Exim keeps this data in a file in its spool directory, called
 &_gnutls-params_&. The file is owned by the Exim user and is readable only by
 to compute. It is unreasonable to re-compute them for every TLS session.
 Therefore, Exim keeps this data in a file in its spool directory, called
 &_gnutls-params_&. The file is owned by the Exim user and is readable only by

-its owner. Every Exim process that start up GnuTLS reads the RSA and D-H
+its owner. Every Exim process that start up GnuTLS reads the D-H

 parameters from this file. If the file does not exist, the first Exim process
 that needs it computes the data and writes it to a temporary file which is
 renamed once it is complete. It does not matter if several Exim processes do
 parameters from this file. If the file does not exist, the first Exim process
 that needs it computes the data and writes it to a temporary file which is
 renamed once it is complete. It does not matter if several Exim processes do


@@ -26361,7 +26315,9 @@ verified as a sender.
 .cindex "&ACL;" "testing a DNS list"
 In its simplest form, the &%dnslists%& condition tests whether the calling host
 is on at least one of a number of DNS lists by looking up the inverted IP
 .cindex "&ACL;" "testing a DNS list"
 In its simplest form, the &%dnslists%& condition tests whether the calling host
 is on at least one of a number of DNS lists by looking up the inverted IP

-address in one or more DNS domains. For example, if the calling host's IP
+address in one or more DNS domains. (Note that DNS list domains are not mail
+domains, so the &`+`& syntax for named lists doesn't work - it is used for
+special options instead.) For example, if the calling host's IP

 address is 192.168.62.43, and the ACL statement is
 .code
 deny dnslists = blackholes.mail-abuse.org : \
 address is 192.168.62.43, and the ACL statement is
 .code
 deny dnslists = blackholes.mail-abuse.org : \


@@ -26938,7 +26894,7 @@ value. You can work out the time (the number of smoothing periods) that a
 client is subjected to counter-measures after an over-limit burst with this
 formula:
 .code
 client is subjected to counter-measures after an over-limit burst with this
 formula:
 .code

-ln(peakrate/maxrate)
+        ln(peakrate/maxrate)

 .endd
 The &%leaky%& (default) option means that the client's recorded rate is not
 updated if it is above the limit. The effect of this is that Exim measures the
 .endd
 The &%leaky%& (default) option means that the client's recorded rate is not
 updated if it is above the limit. The effect of this is that Exim measures the