+
. /////////////////////////////////////////////////////////////////////////////
. This is the primary source of the Exim Manual. It is an xfpt document that is
. converted into DocBook XML for subsequent conversion into printable and online
The following Exim mailing lists exist:
.table2 140pt
-.row &'exim-announce@exim.org'& "Moderated, low volume announcements list"
-.row &'exim-users@exim.org'& "General discussion list"
-.row &'exim-dev@exim.org'& "Discussion of bugs, enhancements, etc."
-.row &'exim-cvs@exim.org'& "Automated commit messages from the VCS"
+.row &'exim-announce@lists.exim.org'& "Moderated, low volume announcements list"
+.row &'exim-users@lists.exim.org'& "General discussion list"
+.row &'exim-users-de@lists.exim.org'& "General discussion list in German language"
+.row &'exim-dev@lists.exim.org'& "Discussion of bugs, enhancements, etc."
+.row &'exim-cvs@lists.exim.org'& "Automated commit messages from the VCS"
.endtable
You can subscribe to these lists, change your existing subscriptions, and view
.cindex "base36"
.cindex "Darwin"
.cindex "Cygwin"
+.cindex "exim_msgdate"
Every message handled by Exim is given a &'message id'& which is sixteen
characters long. It is divided into three parts, separated by hyphens, for
-example &`16VDhn-0001bo-D3`&. Each part is a sequence of letters and digits,
+example &`16VDhn-000000001bo-D342`&. Each part is a sequence of letters and digits,
normally encoding numbers in base 62. However, in the Darwin operating
system (Mac OS X) and when Exim is compiled to run under Cygwin, base 36
(avoiding the use of lower case letters) is used instead, because the message
contains the number of seconds since the start of the epoch (the normal Unix
way of representing the date and time of day).
.next
-After the first hyphen, the next six characters are the id of the process that
-received the message.
+After the first hyphen, the next
+.new
+eleven
+.wen
+characters are the id of the process that received the message.
.next
-There are two different possibilities for the final two characters:
+.new
+There are two different possibilities for the final four characters:
.olist
.oindex "&%localhost_number%&"
If &%localhost_number%& is not set, this value is the fractional part of the
-time of reception, normally in units of 1/2000 of a second, but for systems
+time of reception, normally in units of
+microseconds.
+but for systems
that must use base 36 instead of base 62 (because of case-insensitive file
-systems), the units are 1/1000 of a second.
+systems), the units are
+2 us.
.next
-If &%localhost_number%& is set, it is multiplied by 200 (100) and added to
-the fractional part of the time, which in this case is in units of 1/200
-(1/100) of a second.
+If &%localhost_number%& is set, it is multiplied by
+500000 (250000) and added to
+the fractional part of the time, which in this case is in units of 2 us (4 us).
.endlist
+.wen
.endlist
After a message has been received, Exim waits for the clock to tick at the
pid, it is guaranteed that the time will be different. In most cases, the clock
will already have ticked while the message was being received.
+The exim_msgdate utility (see section &<<SECTexim_msgdate>>&) can be
+used to display the date, and optionally the process id, of an Exim
+Message ID.
+
.section "Receiving mail" "SECID13"
.cindex "receiving mail"
referenced from the configuration (for example, alias files) are changed,
because these are reread each time they are used.
+.new
+Either a SIGTERM or a SIGINT signal should be used to cause the daemon
+to cleanly shut down.
+Subprocesses handling recceiving or delivering messages,
+or for scanning the queue,
+will not be affected by the termination of the daemon process.
+.wen
+
.cmdopt -bdf
This option has the same effect as &%-bd%& except that it never disconnects
from the controlling terminal, even when no debugging is specified.
&%queue_list_requires_admin%& is set false.
+.cmdopt -bpi
+.cindex queue "list of message IDs"
+This option operates like &%-bp%&, but only outputs message ids
+(one per line).
+
+
.cmdopt -bpr
This option operates like &%-bp%&, but the output is not sorted into
chronological order of message arrival. This can speed it up when there are
.cmdopt -bpra
This option is a combination of &%-bpr%& and &%-bpa%&.
+.cmdopt -bpri
+This option is a combination of &%-bpr%& and &%-bpi%&.
+
.cmdopt -bpru
This option is a combination of &%-bpr%& and &%-bpu%&.
given.
Normally the daemon creates this socket, unless a &%-oX%& and &*no*& &%-oP%&
option is also present.
-If this option is given then the socket will not be created. This could be
-required if the system is running multiple daemons.
+.new
+If this option is given then the socket will not be created. This is required
+if the system is running multiple daemons, in which case it should
+be used on all.
+The features supported by the socket will not be available in such cases.
The socket is currently used for
.ilist
fast ramp-up of queue runner processes
.next
+caching compiled regexes
+.next
obtaining a current queue size
.endlist
+.wen
.cmdopt -pd
.cindex "Perl" "starting the interpreter"
transports are run.
Performance will be best if the &%queue_run_in_order%& option is false.
-If that is so and the &%queue_fast_ramp%& option is true then
-in the first phase of the run,
+If that is so and
+the &%queue_fast_ramp%& option is true
+and a daemon-notifier socket is available
+then in the first phase of the run,
once a threshold number of messages are routed for a given host,
a delivery process is forked in parallel with the rest of the scan.
.cindex "hints database" "remembering routing"
The hints database that remembers which messages are waiting for specific hosts
-is updated, as if delivery to those hosts had been deferred. After this is
-complete, a second, normal queue scan happens, with routing and delivery taking
-place as normal. Messages that are routed to the same host should mostly be
+is updated, as if delivery to those hosts had been deferred.
+
+After the first queue scan complete,
+a second, normal queue scan is done, with routing and delivery taking
+place as normal.
+Messages that are routed to the same host should mostly be
delivered down a single SMTP
.cindex "SMTP" "passed connection"
.cindex "SMTP" "multiple deliveries"
.cindex "multiple SMTP deliveries"
connection because of the hints that were set up during the first queue scan.
-This option may be useful for hosts that are connected to the Internet
+
+.new
+Two-phase queue runs should be used on systems which, even intermittently,
+have a large queue (such as mailing-list operators).
+They may also be useful for hosts that are connected to the Internet
intermittently.
+.wen
.vitem &%-q[q]i...%&
.oindex "&%-qi%&"
Such a daemon listens for incoming SMTP calls, and also starts a queue runner
process every 30 minutes.
+.new
+.cindex "named queues" "queue runners"
+It is possible to set up runners for multiple named queues within one daemon,
+For example:
+.code
+exim -qGhipri/2m -q10m -qqGmailinglist/1h
+.endd
+.wen
+
When a daemon is started by &%-q%& with a time value, but without &%-bd%&, no
pid file is written unless one is explicitly requested by the &%-oP%& option.
The &'query-style'& type accepts a generalized database query. No particular
key value is assumed by Exim for query-style lookups. You can use whichever
Exim variables you need to construct the database query.
+
+For the string-expansion kind of lookups, the query is given in the first
+bracketed argument of the &${lookup ...}$& expansion.
+For the list-argument kind of lookup the quury is given by the remainder of the
+list item after the first semicolon.
+
.cindex "tainted data" "quoting for lookups"
If tainted data is used in the query then it should be quuted by
using the &*${quote_*&<&'lookup-type'&>&*:*&<&'string'&>&*}*& expansion operator
After expansion, <&'string'&> is interpreted as a list, colon-separated by
default, but the separator can be changed in the usual way (&<<SECTlistsepchange>>&).
For each item
-in this list, its value is place in &$item$&, and then the condition is
+in this list, its value is placed in &$item$&, and then the condition is
evaluated.
.new
Any modification of &$value$& by this evaluation is discarded.
sending the request. Values are &"yes"& (the default) or &"no"&
(preferred, eg. by some webservers).
+.next
+&*sni*&
+Controls the use of Server Name Identification on the connection.
+Any nonempty value will be the SNI sent; TLS will be forced.
+
.next
&*tls*&
Controls the use of TLS on the connection.
This item inserts &"raw"& header lines. It is described with the &%header%&
expansion item in section &<<SECTexpansionitems>>& above.
-.vitem "&*${run <&'options'&> {*&<&'command&~arg&~list'&>&*}{*&<&'string1'&>&*}&&&
+.vitem "&*${run<&'options'&> {*&<&'command&~arg&~list'&>&*}{*&<&'string1'&>&*}&&&
{*&<&'string2'&>&*}}*&"
.cindex "expansion" "running a command"
.cindex "&%run%& expansion item"
This item runs an external command, as a subprocess.
-One option is supported after the word &'run'&, comma-separated.
+One option is supported after the word &'run'&, comma-separated
+and without whitespace.
If the option &'preexpand'& is not used,
the command string is split into individual arguments by spaces
+.new
+.vitem &*${headerwrap_*&<&'cols'&>&*_*&<&'limit'&>&*:*&<&'string'&>&*}*&
+.cindex header "wrapping operator"
+.cindex expansion "header wrapping"
+This operator line-wraps its argument in a way useful for headers.
+The &'cols'& value gives the column number to wrap after,
+the &'limit'& gives a limit number of result characters to truncate at.
+Either just the &'limit'& and the preceding underbar, or both, can be omitted;
+the defaults are 80 and 998.
+Wrapping will be inserted at a space if possible before the
+column number is reached.
+Whitespace at a chosen wrap point is removed.
+A line-wrap consists of a newline followed by a tab,
+and the tab is counted as 8 columns.
+.wen
+
+
+
.vitem &*${hex2b64:*&<&'hexstring'&>&*}*&
.cindex "base64 encoding" "conversion from hex"
.cindex "expansion" "hex to base64"
.cindex "router" "name"
.cindex "name" "of router"
.vindex "&$router_name$&"
-During the running of a router this variable contains its name.
+During the running of a router, or a transport called,
+this variable contains the router name.
.vitem &$runrc$&
.cindex "return code" "from &%run%& expansion"
single connection is being processed. When a child process terminates, the
daemon decrements its copy of the variable.
+.vitem &$smtp_notquit_reason$&
+.vindex "&$smtp_notquit_reason$&"
+When the not-QUIT ACL is running, this variable is set to a string
+that indicates the reason for the termination of the SMTP connection.
+
.vitem "&$sn0$& &-- &$sn9$&"
These variables are copies of the values of the &$n0$& &-- &$n9$& accumulators
that were current at the end of the system filter file. This allows a system
.option freeze_tell main "string list, comma separated" unset
.cindex "freezing messages" "sending a message when freezing"
+.cindex "frozen messages" "sending a message when freezing"
On encountering certain errors, or when configured to do so in a system filter,
ACL, or special router, Exim freezes a message. This means that no further
delivery attempts take place until an administrator thaws the message, or the
.option tls_eccurve main string list&!! &`auto`&
.cindex TLS "EC cryptography"
This option selects EC curves for use by Exim when used with OpenSSL.
-It has no effect when Exim is used with GnuTLS.
+It has no effect when Exim is used with GnuTLS
+(the equivalent can be done using a priority string for the
+&%tls_require_ciphers%& option).
After expansion it must contain
.new
transport_filter = '/bin/cmd${if eq{$host}{a.b.c}{1}{2}}'
.endd
This runs the command &(/bin/cmd1)& if the host name is &'a.b.c'&, and
-&(/bin/cmd2)& otherwise. If double quotes had been used, they would have been
+&(/bin/cmd2)& otherwise.
+
+Option strings in general have any fully-surrounding double quote wrapping
+removed early in parsing (see &<<SECTstrings>>&).
+Then, for this option, quotes protect against whitespace being
+regarded as a separator while splitting into the command argument vector.
+Either double or single quotes can be used here;
+the former interprets backlash-quoted charachters
+and the latter does not.
+
+If double quotes had been used in this example, they would have been
stripped by Exim when it read the option's value. When the value is used, if
the single quotes were missing, the line would be split into two items,
&`/bin/cmd${if`& and &`eq{$host}{a.b.c}{1}{2}`&, and an error would occur when
while verifying the server certificate,
checks will be included on the host name
(note that this will generally be the result of a DNS MX lookup)
-versus Subject and Subject-Alternate-Name fields. Wildcard names are permitted
+versus the Subject-Alternate-Name (or, if none, Subject-Name) fields.
+Wildcard names are permitted,
limited to being the initial component of a 3-or-more component FQDN.
There is no equivalent checking on client certificates.
Note that Dovecot must be configured to use auth-client not auth-userdb.
If you are using Dovecot to authenticate POP/IMAP clients, it might be helpful
to use the same mechanisms for SMTP authentication. This is a server
-authenticator only. There is only one option:
+authenticator only. There is only one non-generic option:
.option server_socket dovecot string unset
dovecot_plain:
driver = dovecot
public_name = PLAIN
+ server_advertise_condition = ${if def:tls_in_cipher}
server_socket = /var/run/dovecot/auth-client
server_set_id = $auth1
server_socket = /var/run/dovecot/auth-client
server_set_id = $auth1
.endd
+
+.new
+&*Note*&: plaintext authentication methods such as PLAIN and LOGIN
+should not be advertised on cleartext SMTP connections.
+See the discussion in section &<<SECTplain_TLS>>&.
+.wen
+
If the SMTP connection is encrypted, or if &$sender_host_address$& is equal to
&$received_ip_address$& (that is, the connection is local), the &"secured"&
option is passed in the Dovecot authentication command. If, for a TLS
(see &<<CHAPTLS>>&).
If an authenticator of this type is configured it is
-run before any SMTP-level communication is done,
+run immediately after a TLS connection being negotiated
+(due to either STARTTLS or TLS-on-connect)
and can authenticate the connection.
-If it does, SMTP authentication is not offered.
+If it does, SMTP authentication is not subsequently offered.
A maximum of one authenticator of this type may be present.
.vitem &*control&~=&~fakedefer/*&<&'message'&>
.cindex "fake defer"
.cindex "defer, fake"
+.cindex fakedefer
This control works in exactly the same way as &%fakereject%& (described below)
except that it causes an SMTP 450 response after the message data instead of a
550 response. You must take care when using &%fakedefer%& because it causes the
.vitem &*control&~=&~fakereject/*&<&'message'&>
.cindex "fake rejection"
.cindex "rejection, fake"
+.cindex fakereject
This control is permitted only for the MAIL, RCPT, and DATA ACLs, in other
words, only when an SMTP message is being received. If Exim accepts the
message, instead the final 250 response, a 550 rejection message is sent.
DATA, MIME or DKIM ACLs for a message delivered by cutthrough routing.
More than one header can be removed at the same time by using a colon separated
-list of header names. The header matching is case insensitive. Wildcards are
-not permitted, nor is list expansion performed, so you cannot use hostlists to
+list of header specifiers.
+.new
+If a specifier does not start with a circumflex (^)
+then it is treated as a header name.
+The header name matching is case insensitive.
+If it does, then it is treated as a (front-anchored)
+regular expression applied to the whole header.
+
+&*Note*&: The colon terminating a header name will need to be doubled
+if used in an RE, and there can legitimately be whitepace before it.
+
+Example:
+.code
+remove_header = \N^(?i)Authentication-Results\s*::\s*example.org;\N
+.endd
+.wen
+
+List expansion is not performed, so you cannot use hostlists to
create a list of headers, however both connection and message variable expansion
are performed (&%$acl_c_*%& and &%$acl_m_*%&), illustrated in this example:
.code
warn message = Remove internal headers
remove_header = $acl_c_ihdrs
.endd
-Header names for removal are accumulated during the MAIL, RCPT, and predata ACLs.
+Header specifiers for removal are accumulated during the MAIL, RCPT, and predata ACLs.
Matching header lines are removed from the message before processing the DATA and MIME ACLs.
If multiple header lines match, all are removed.
There is no harm in attempting to remove the same header twice nor in removing
-a non-existent header. Further header lines to be removed may be accumulated
-during the DATA and MIME ACLs, after which they are removed from the message,
-if present. In the case of non-SMTP messages, headers to be removed are
-accumulated during the non-SMTP ACLs, and are removed from the message after
+a non-existent header. Further header specifiers for removal may be accumulated
+during the DATA and MIME ACLs, after which matching headers are removed
+if present. In the case of non-SMTP messages, remove speifiers are
+accumulated during the non-SMTP ACLs, and are acted on after
all the ACLs have run. If a message is rejected after DATA or by the non-SMTP
ACL, there really is no effect because there is no logging of what headers
would have been removed.
.section "Reducing or increasing what is logged" "SECTlogselector"
.cindex "log" "selectors"
By setting the &%log_selector%& global option, you can disable some of Exim's
-default logging, or you can request additional logging. The value of
+default logging to the main log, or you can request additional logging. The value of
&%log_selector%& is made up of names preceded by plus or minus characters. For
example:
.code
.irow &<<SECTtidydb>>& &'exim_tidydb'& "clean up a hints database"
.irow &<<SECTfixdb>>& &'exim_fixdb'& "patch a hints database"
.irow &<<SECTmailboxmaint>>& &'exim_lock'& "lock a mailbox file"
+.irow &<<SECTexim_msgdate>>& &'exim_msgdate'& "Message Ids for humans (exim_msgdate)"
.endtable
Another utility that might be of use to sites with many MTAs is Tom Kistner's
.endd
Note that if a command is supplied, it must be entirely contained within the
second argument &-- hence the quotes.
-.ecindex IIDutils
+.section "Message Ids for humans (exim_msgdate)" "SECTexim_msgdate"
+.cindex "exim_msgdate"
+The &'exim_msgdate'& utility is written by Andrew Aitchison and included in the Exim distribution.
+This Perl script converts an Exim Mesage ID back into a human readable form.
+For details of &'exim_msgdate'&'s options, run &'exim_msgdate'& with the &%--help%& option.
+
+Section &<<SECTmessiden>>& (Message identification) describes Exim Mesage IDs.
+.ecindex IIDutils
. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////
# one, plus the max_rcpt and return_path options
remote_forwarded_smtp:
driver = smtp
- # modify the envelope from, for mails that we forward
+ # single-recipient so that $original_domain is valid
max_rcpt = 1
+ # modify the envelope from, for mails that we forward
return_path = ${srs_encode {SRS_SECRET} {$return_path} {$original_domain}}
.endd
git://git.exim.org / exim.git / blobdiff