X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/7d0ab55cbe2498a27fc54a779d82b5240e440517..08dfc92a7bdd17647ef79e47e85a121a57f55274:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 41c977589..b521a7e7e 100644 --- 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.32 2008/01/29 17:14:47 fanf2 Exp $ +. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.44 2008/06/04 19:15:47 fanf2 Exp $ . . ///////////////////////////////////////////////////////////////////////////// . This is the primary source of the Exim Manual. It is an xfpt document that is @@ -367,11 +367,14 @@ contributors. .section "Exim documentation" "SECID1" +. Keep this example change bar when updating the documentation! +.new .cindex "documentation" This edition of the Exim specification applies to version &version; of Exim. Substantive changes from the &previousversion; edition are marked in some renditions of the document; this paragraph is so marked if the rendition is capable of showing a change indicator. +.wen This document is very much a reference manual; it is not a tutorial. The reader is expected to have some familiarity with the SMTP mail transfer protocol and @@ -428,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 &_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 @@ -729,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 -© 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" @@ -1652,7 +1652,7 @@ architecture and operating system for itself, but the defaults can be overridden if necessary. -.section "PCRE library" "SECTdb" +.section "PCRE library" "SECTpcre" .cindex "PCRE library" Exim no longer has an embedded PCRE library as the vast majority of modern systems include PCRE as a system library, although you may need @@ -2223,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 -&'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 &<>& below. @@ -5905,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 -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 @@ -5950,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$&. - - - - - - . //////////////////////////////////////////////////////////////////////////// . //////////////////////////////////////////////////////////////////////////// @@ -10760,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*& -conditions (see section &<>&), and &*filter*&, &*man*&, and +conditions (see section &<>&), and &*filter*&, &*map*&, and &*reduce*& items (see section &<>&). In other circumstances, it is empty. @@ -19002,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 -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 @@ -23568,17 +23522,20 @@ login: 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 -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. @@ -24098,11 +24055,11 @@ sections &<>& and &<>&. .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 -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 @@ -25512,7 +25469,8 @@ ACL fragment writes no logging information when access is denied: &` log_reject_target =`& .endd This modifier can be used in SMTP and non-SMTP ACLs. It applies to both -permanent and temporary rejections. +permanent and temporary rejections. Its effect lasts for the rest of the +current ACL. .vitem &*logwrite*&&~=&~<&'text'&> @@ -26358,7 +26316,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 -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 : \ @@ -26935,7 +26895,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 -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 @@ -27593,19 +27553,8 @@ the third string (in this case &"1"&), whether or not the cryptographic and timeout checks succeed. The &$prvscheck_result$& variable contains the result of the checks (empty for failure, &"1"& for success). -There are two more issues you must consider when implementing prvs-signing. -Firstly, you need to ensure that prvs-signed addresses are not blocked by your -ACLs. A prvs-signed address contains a slash character, but the default Exim -configuration contains this statement in the RCPT ACL: -.code -deny message = Restricted characters in address - domains = +local_domains - local_parts = ^[.] : ^.*[@%!/|] -.endd -This is a conservative rule that blocks local parts that contain slashes. You -should remove the slash in the last line. - -Secondly, you have to ensure that the routers accept prvs-signed addresses and +There is one more issue you must consider when implementing prvs-signing: +you have to ensure that the routers accept prvs-signed addresses and deliver them correctly. The easiest way to handle this is to use a &(redirect)& router to remove the signature with a configuration along these lines: .code