X-Git-Url: https://git.exim.org/users/jgh/exim.git/blobdiff_plain/c6ac190c6870d8f49b66c2cbb434b6529150723a..ff86345ee2c0b8c21e8008ca611932c726238a6b:/doc/doc-docbook/spec.xfpt?ds=sidebyside diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 2b47f0512..6162739d8 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.31 2008/01/29 17:08:54 fanf2 Exp $ +. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.39 2008/03/26 15:37:37 fanf2 Exp $ . . ///////////////////////////////////////////////////////////////////////////// . This is the primary source of the Exim Manual. It is an xfpt document that is @@ -367,6 +367,7 @@ 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. @@ -430,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 @@ -456,12 +455,12 @@ Squared, formerly Planet Online Ltd, whose support I gratefully acknowledge. .cindex "FAQ" As well as Exim distribution tar files, the Exim web site contains a number of differently formatted versions of the documentation. A recent addition to the -online information is the Exim wiki &new("(&url(http://wiki.exim.org))"), +online information is the Exim wiki (&url(http://wiki.exim.org)), which contains what used to be a separate FAQ, as well as various other examples, tips, and know-how that have been contributed by Exim users. .cindex Bugzilla -An Exim Bugzilla exists at &new("&url(http://bugs.exim.org)"). You can use +An Exim Bugzilla exists at &url(http://bugs.exim.org). You can use this to report bugs, and also to add items to the wish list. Please search first to check that you are not duplicating a previous entry. @@ -500,8 +499,8 @@ information will be posted at &url(http://www-tus.csx.cam.ac.uk/courses/exim/). .section "Bug reports" "SECID5" .cindex "bug reports" .cindex "reporting bugs" -Reports of obvious bugs &new("can be emailed to &'bugs@exim.org'& or reported -via the Bugzilla (&url(http://bugs.exim.org)).") However, if you are unsure +Reports of obvious bugs can be emailed to &'bugs@exim.org'& or reported +via the Bugzilla (&url(http://bugs.exim.org)). However, if you are unsure whether some behaviour is a bug or not, the best thing to do is to post a message to the &'exim-dev'& mailing list and have it discussed. @@ -731,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" @@ -1654,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 @@ -2225,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. @@ -5907,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 @@ -5952,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$&. - - - - - - . //////////////////////////////////////////////////////////////////////////// . //////////////////////////////////////////////////////////////////////////// @@ -7156,9 +7110,9 @@ If any MySQL, PostgreSQL, Oracle, or InterBase lookups are used, the &%mysql_servers%&, &%pgsql_servers%&, &%oracle_servers%&, or &%ibase_servers%& option (as appropriate) must be set to a colon-separated list of server information. -&new("(For MySQL and PostgreSQL only, the global option need not be set if all +(For MySQL and PostgreSQL only, the global option need not be set if all queries contain their own server information &-- see section -&<>&.)") Each item in the list is a slash-separated list of four +&<>&.) Each item in the list is a slash-separated list of four items: host name, database name, user name, and password. In the case of Oracle, the host name field is used for the &"service name"&, and the database name field is not used and should be empty. For example: @@ -10762,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. @@ -11641,9 +11595,9 @@ details of the &(smtp)& transport. When a message is received from a remote host over an encrypted SMTP connection, and Exim is configured to request a certificate from the client, the value of the Distinguished Name of the certificate is made available in the -&$tls_peerdn$& during subsequent processing. &new("Like &$tls_cipher$&, the +&$tls_peerdn$& during subsequent processing. Like &$tls_cipher$&, the value is retained during message delivery, except during outbound SMTP -deliveries.") +deliveries. .vitem &$tod_bsdinbox$& .vindex "&$tod_bsdinbox$&" @@ -12186,7 +12140,7 @@ listed in more than one group. .row &%disable_ipv6%& "do no IPv6 processing" .row &%keep_malformed%& "for broken files &-- should not happen" .row &%localhost_number%& "for unique message ids in clusters" -.row &new(&%message_body_newlines%&) "retain newlines in &$message_body$&" +.row &%message_body_newlines%& "retain newlines in &$message_body$&" .row &%message_body_visible%& "how much to show in &$message_body$&" .row &%mua_wrapper%& "run in &""MUA wrapper""& mode" .row &%print_topbitchars%& "top-bit characters are printing" @@ -12253,13 +12207,13 @@ listed in more than one group. .section "Data lookups" "SECID101" .table2 -.row &new(&%ibase_servers%&) "InterBase servers" +.row &%ibase_servers%& "InterBase servers" .row &%ldap_default_servers%& "used if no server in query" .row &%ldap_version%& "set protocol version" .row &%lookup_open_max%& "lookup files held open" -.row &new(&%mysql_servers%&) "default MySQL servers" -.row &new(&%oracle_servers%&) "Oracle servers" -.row &new(&%pgsql_servers%&) "default PostgreSQL servers" +.row &%mysql_servers%& "default MySQL servers" +.row &%oracle_servers%& "Oracle servers" +.row &%pgsql_servers%& "default PostgreSQL servers" .row &%sqlite_lock_timeout%& "as it says" .endtable @@ -12302,7 +12256,7 @@ listed in more than one group. .row &%check_spool_space%& "before accepting a message" .row &%deliver_queue_load_max%& "no queue deliveries if load high" .row &%queue_only_load%& "queue incoming if load high" -.row &new(&%queue_only_load_latch%&) "don't re-evaluate load for each message" +.row &%queue_only_load_latch%& "don't re-evaluate load for each message" .row &%queue_run_max%& "maximum simultaneous queue runners" .row &%remote_max_parallel%& "parallel SMTP delivery per message" .row &%smtp_accept_max%& "simultaneous incoming connections" @@ -12537,7 +12491,7 @@ See also the &'Policy controls'& section above. .row &%queue_only%& "no immediate delivery at all" .row &%queue_only_file%& "no immediate delivery if file exists" .row &%queue_only_load%& "no immediate delivery if load is high" -.row &new(&%queue_only_load_latch%&) "don't re-evaluate load for each message" +.row &%queue_only_load_latch%& "don't re-evaluate load for each message" .row &%queue_only_override%& "allow command line to override" .row &%queue_run_in_order%& "order of arrival" .row &%queue_run_max%& "of simultaneous queue runners" @@ -13118,7 +13072,7 @@ dns_check_names_pattern = \ (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9/-]*[^\W_])?)+$ .endd which permits only letters, digits, slashes, and hyphens in components, but -they must start and end with a letter or digit. &new(Slashes) are not, in fact, +they must start and end with a letter or digit. Slashes are not, in fact, permitted in host names, but they are found in certain NS records (which can be accessed in Exim by using a &%dnsdb%& lookup). If you set &%allow_utf8_domains%&, you must modify this pattern, or set the option to an @@ -20651,8 +20605,8 @@ delivers the message to it using the LMTP protocol. .option timeout lmtp time 5m The transport is aborted if the created process or Unix domain socket does not -respond to LMTP commands or message input within this timeout. &new("Delivery -is deferred, and will be tried again later.") Here is an example of a typical +respond to LMTP commands or message input within this timeout. Delivery +is deferred, and will be tried again later. Here is an example of a typical LMTP transport: .code lmtp: @@ -21655,8 +21609,8 @@ unauthenticated. See also &%hosts_require_auth%&, and chapter .vindex "&$host$&" .vindex "&$host_address$&" This option specifies which interface to bind to when making an outgoing SMTP -call. &new("The value is an IP address, not an interface name such as -&`eth0`&.") Do not confuse this with the interface address that was used when a +call. The value is an IP address, not an interface name such as +&`eth0`&. Do not confuse this with the interface address that was used when a message was received, which is in &$received_ip_address$&, formerly known as &$interface_address$&. The name was changed to minimize confusion with the outgoing interface address. There is no variable that contains an outgoing @@ -22282,11 +22236,9 @@ rewriting rule is skipped unless the relevant addresses are being processed. &`s`& rewrite the &'Sender:'& header &`t`& rewrite the &'To:'& header .endd -.new "All headers" means all of the headers listed above that can be selected individually, plus their &'Resent-'& versions. It does not include other headers such as &'Subject:'& etc. -.wen You should be particularly careful about rewriting &'Sender:'& headers, and restrict this to special known cases in your own domains. @@ -23572,17 +23524,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. @@ -24351,8 +24306,8 @@ incoming message (by default &-- you can, of course, change this), and it is also included in the log line that records a message's arrival, keyed by &"X="&, unless the &%tls_cipher%& log selector is turned off. The &%encrypted%& condition can be used to test for specific cipher suites in ACLs. -&new("(For outgoing SMTP deliveries, &$tls_cipher$& is reset &-- see section -&<>&.)") +(For outgoing SMTP deliveries, &$tls_cipher$& is reset &-- see section +&<>&.) Once TLS has been established, the ACLs that run for subsequent SMTP commands can check the name of the cipher suite and vary their actions accordingly. The @@ -24672,7 +24627,7 @@ options in the main part of the configuration. These options are: .irow &%acl_smtp_mail%& "ACL for MAIL" .irow &%acl_smtp_mailauth%& "ACL for the AUTH parameter of MAIL" .irow &%acl_smtp_mime%& "ACL for content-scanning MIME parts" -.irow &new(&%acl_smtp_notquit%&) "ACL for non-QUIT terminations" +.irow &%acl_smtp_notquit%& "ACL for non-QUIT terminations" .irow &%acl_smtp_predata%& "ACL at start of DATA command" .irow &%acl_smtp_quit%& "ACL for QUIT" .irow &%acl_smtp_rcpt%& "ACL for RCPT" @@ -26362,7 +26317,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 : \ @@ -26904,7 +26861,6 @@ which may be inaccurate or completely missing. You can follow the limit &'m'& in the configuration with K, M, or G to specify limits in kilobytes, megabytes, or gigabytes, respectively. -.new The &%per_rcpt%& option causes Exim to limit the rate at which recipients are accepted. To be effective, it would need to be used in either the &%acl_smtp_rcpt%& or the &%acl_not_smtp%& ACL. In the @@ -26920,7 +26876,6 @@ condition is processed. This can be used to limit the SMTP command rate. This command is essentially an alias of &%per_rcpt%& to make it clear that the effect is to limit the rate at which individual commands, rather than recipients, are accepted. -.wen .section "Ratelimit options for handling fast clients" "ratophanfas" If a client's average rate is greater than the maximum, the rate limiting @@ -26941,7 +26896,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 @@ -28177,7 +28132,7 @@ cases. These ACLs are called (possibly many times) just before the &%acl_smtp_data%& ACL in the case of an SMTP message, or just before the &%acl_not_smtp%& ACL in the case of a non-SMTP message. However, a MIME ACL is called only if the -message contains a &new(&'Content-Type:'&) header line. When a call to a MIME +message contains a &'Content-Type:'& header line. When a call to a MIME ACL does not yield &"accept"&, ACL processing is aborted and the appropriate result code is sent to the client. In the case of an SMTP message, the &%acl_smtp_data%& ACL is not called when this happens.