-. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.30 2008/01/28 18:30:29 fanf2 Exp $
+. $Cambridge: exim/doc/doc-docbook/spec.xfpt,v 1.43 2008/05/14 09:16:38 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
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
.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.
.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
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"
.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 : \
send in each time interval. It also specifies the number of messages permitted
in a fast burst. By increasing both &'m'& and &'p'& but keeping &'m/p'&
constant, you can allow a client to send more messages in a burst without
-changing its overall sending rate limit. Conversely, if &'m'& and &'p'& are
+changing its long-term sending rate limit. Conversely, if &'m'& and &'p'& are
both small, messages must be sent at an even rate.
There is a script in &_util/ratelimit.pl_& which extracts sending rates from
instructions when it is run with no arguments.
The key is used to look up the data for calculating the client's average
-sending rate. This data is stored in a database maintained by Exim in its spool
-directory, alongside the retry and other hints databases. The default key is
-&$sender_host_address$&, which applies the limit to each client host IP address.
+sending rate. This data is stored in Exim's spool directory, alongside the
+retry and other hints databases. The default key is &$sender_host_address$&,
+which means Exim computes the sending rate of each client host IP address.
By changing the key you can change how Exim identifies clients for the purpose
of ratelimiting. For example, to limit the sending rate of each authenticated
user, independent of the computer they are sending from, set the key to
&$authenticated_id$&. You must ensure that the lookup key is meaningful; for
example, &$authenticated_id$& is only meaningful if the client has
-authenticated, and you can check with the &%authenticated%& ACL condition.
+authenticated (which you can check with the &%authenticated%& ACL condition).
-If you want to limit the rate at which a recipient receives messages, you can
-use the key &`$local_part@$domain`& with the &%per_rcpt%& option (see below) in
-a RCPT ACL.
+The lookup key does not have to identify clients: If you want to limit the
+rate at which a recipient receives messages, you can use the key
+&`$local_part@$domain`& with the &%per_rcpt%& option (see below) in a RCPT
+ACL.
-Internally, Exim includes the smoothing constant &'p'& and the options in the
+Internally, Exim appends the smoothing constant &'p'& and the options onto the
lookup key because they alter the meaning of the stored data. This is not true
for the limit &'m'&, so you can alter the configured maximum rate and Exim will
still remember clients' past behaviour, but if you alter the other ratelimit
The &%per_byte%& option limits the sender's email bandwidth. Note that it is
best to use this option in the DATA ACL; if it is used in an earlier ACL it
-relies on the SIZE parameter on the MAIL command, 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.
+relies on the SIZE parameter specified by the client in its MAIL command,
+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
&%acl_smtp_rcpt%& ACL, the number of recipients is incremented by one.
In the case of a locally submitted message in the &%acl_not_smtp%& ACL,
-the number of recipients incremented is equal to &%$recipients_count%&
+the number of recipients is incremented by the &%$recipients_count%&
for the entire message. Note that in either case the rate limiting
engine will see a message with many recipients as a large high-speed
burst.
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
rest of the ACL. The default mode is leaky, which avoids a sender's
over-aggressive retry rate preventing it from getting any email through.
-The &%strict%& option means that the client's recorded rate is always updated.
-The effect of this is that Exim measures the client's average rate of attempts
-to send email, which can be much higher than the maximum &new("it is actually
-allowed. If the client is over the limit it may be subjected to
-counter-measures in the ACL until it slows down below the maximum rate.") The
-smoothing period determines the time it takes for a high sending rate to decay
-exponentially to 37% of its peak value, which means that 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:
+The &%strict%& option means that the client's recorded rate is always
+updated. The effect of this is that Exim measures the client's average rate
+of attempts to send email, which can be much higher than the maximum it is
+actually allowed. If the client is over the limit it may be subjected to
+counter-measures by the ACL until it slows down below the maximum rate. If
+the client stops attempting to send email for the time specified in the &'p'&
+parameter then its computed rate will decay exponentially to 37% of its peak
+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
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
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 / users / heiko / exim.git / blobdiff