-. $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.38 2008/02/26 11:46:33 fanf2 Exp $
.
. /////////////////////////////////////////////////////////////////////////////
. This is the primary source of the Exim Manual. It is an xfpt document that is
.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.
.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
.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.
.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.
.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"
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
.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.
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
-.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$&.
-
-
-
-
-
-
. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////
&%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
-&<<SECTspeserque>>&.)") Each item in the list is a slash-separated list of four
+&<<SECTspeserque>>&.) 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:
.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.
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$&"
.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"
.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
.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"
.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"
(?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
.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:
.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
&`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.
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.
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
-&<<SECID185>>&.)")
+(For outgoing SMTP deliveries, &$tls_cipher$& is reset &-- see section
+&<<SECID185>>&.)
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
.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"
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
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
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
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.
git://git.exim.org / exim.git / blobdiff