+
. /////////////////////////////////////////////////////////////////////////////
. 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
.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,
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.
&` _DRIVER_ROUTER_* `& router drivers
&` _DRIVER_TRANSPORT_* `& transport drivers
&` _DRIVER_AUTHENTICATOR_* `& authenticator drivers
+&` _EXP_COND_* `& expansion conditions
+&` _EXP_ITEM_* `& expansion items
+&` _EXP_OP_* `& expansion operators
+&` _EXP_VAR_* `& expansion variables
&` _LOG_* `& log_selector values
&` _OPT_MAIN_* `& main config options
&` _OPT_ROUTERS_* `& generic router options
on the number of entries returned, and no time limit on queries.
When a DN is quoted in the USER= setting for LDAP authentication, Exim
-removes any URL quoting that it may contain before passing it LDAP. Apparently
+removes any URL quoting that it may contain before passing it to the LDAP library.
+Apparently
some libraries do this for themselves, but some do not. Removing the URL
quoting has two advantages:
.code
add_header = :at_start:${authresults {$primary_hostname}}
.endd
-This is safe even if no authentication results are available.
+This is safe even if no authentication results are available
+.new
+and would generally be placed in the DATA ACL.
+.wen
.vitem "&*${certextract{*&<&'field'&>&*}{*&<&'certificate'&>&*}&&&
+.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"
SRS decode. See SECT &<<SECTSRS>>& for details.
-.vitem &*inlist&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*& &&&
- &*inlisti&~{*&<&'string1'&>&*}{*&<&'string2'&>&*}*&
+.vitem &*inlist&~{*&<&'subject'&>&*}{*&<&'list'&>&*}*& &&&
+ &*inlisti&~{*&<&'subject'&>&*}{*&<&'list'&>&*}*&
.cindex "string" "comparison"
.cindex "list" "iterative conditions"
Both strings are expanded; the second string is treated as a list of simple
.code
dns_again_means_nonexist = *.in-addr.arpa
.endd
-This option applies to all DNS lookups that Exim does. It also applies when the
+This option applies to all DNS lookups that Exim does,
+.new
+except for TLSA lookups (where knowing about such failures
+is security-relevant).
+.wen
+It also applies when the
&[gethostbyname()]& or &[getipnodebyname()]& functions give temporary errors,
since these are most likely to be caused by DNS lookup problems. The
&(dnslookup)& router has some options of its own for controlling what happens
.cindex "host" "rejecting connections from"
If this option is set, incoming SMTP calls from the hosts listed are rejected
as soon as the connection is made.
-This option is mostly obsolete, retained for backward compatibility because
+This option is obsolete, and retained only for backward compatibility, because
nowadays the ACL specified by &%acl_smtp_connect%& can also reject incoming
-connections immediately
+connections immediately.
+
.new
-(except for tls-on-connect connections).
+If the connection is on a TLS-on-connect port then the TCP connection is
+just dropped. Otherwise, an SMTP error is sent first.
.wen
The ability to give an immediate rejection (either by this option or using an
.cindex "banner for SMTP"
.cindex "welcome banner for SMTP"
.cindex "customizing" "SMTP banner"
-This string, which is expanded every time it is used, is output as the initial
+If a connect ACL does not supply a message,
+this string (which is expanded every time it is used) is output as the initial
positive response to an SMTP connection. The default setting is:
.code
smtp_banner = $smtp_active_hostname ESMTP Exim \
$version_number $tod_full
.endd
-Failure to expand the string causes a panic error. If you want to create a
+.new
+Failure to expand the string causes a panic error;
+a forced fail just closes the connection.
+.wen
+If you want to create a
multiline response to the initial SMTP connection, use &"\n"& in the string at
appropriate points, but not at the end. Note that the 220 code is not included
in this string. Exim adds it automatically (several times in the case of a
acceptable bound from 1024 to 2048.
-.option tls_eccurve main string&!! &`auto`&
+.option tls_eccurve main string list&!! &`auto`&
.cindex TLS "EC cryptography"
-This option selects a EC curve for use by Exim when used with OpenSSL.
-It has no effect when Exim is used with GnuTLS.
+This option selects EC curves for use by Exim when used with OpenSSL.
+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 a valid EC curve parameter, such as
-&`prime256v1`&, &`secp384r1`&, or &`P-512`&. Consult your OpenSSL manual
-for valid selections.
+After expansion it must contain
+.new
+one or (only for OpenSSL versiona 1.1.1 onwards) more
+.wen
+EC curve names, such as &`prime256v1`&, &`secp384r1`&, or &`P-521`&.
+Consult your OpenSSL manual for valid curve names.
For OpenSSL versions before (and not including) 1.0.2, the string
&`auto`& selects &`prime256v1`&. For more recent OpenSSL versions
&`auto`& tells the library to choose.
-If the option expands to an empty string, no EC curves will be enabled.
+.new
+If the option expands to an empty string, the effect is undefined.
+.wen
.option tls_ocsp_file main string&!! unset
resent to other recipients.
&*Note:*& If used on a transport handling multiple recipients
-(the smtp transport unless &%rcpt_max%& is 1, the appendfile, pipe or lmtp
+(the smtp transport unless &%max_rcpt%& is 1, the appendfile, pipe or lmtp
transport if &%batch_max%& is greater than 1)
then information about Bcc recipients will be leaked.
Doing so is generally not advised.
string &`IGNOREQUOTA`& is added to RCPT commands, provided that the LMTP server
has advertised support for IGNOREQUOTA in its response to the LHLO command.
-.option max_rcpt smtp integer 100
+.option max_rcpt smtp integer&!! 100
.cindex "RCPT" "maximum number of outgoing"
-This option limits the number of RCPT commands that are sent in a single
-SMTP message transaction. Each set of addresses is treated independently, and
+This option,
+.new
+after expansion,
+.wen
+limits the number of RCPT commands that are sent in a single
+SMTP message transaction.
+A value setting of zero disables the limit.
+
+.new
+If a constant is given,
+.wen
+each set of addresses is treated independently, and
so can cause parallel connections to the same host if &%remote_max_parallel%&
-permits this. A value setting of zero disables the limit.
+permits this.
.option message_linelength_limit smtp integer 998
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
the message override the banner message that is otherwise specified by the
&%smtp_banner%& option.
-For tls-on-connect connections, the ACL is run after the TLS connection
-is accepted (however, &%host_reject_connection%& is tested before).
+.new
+For tls-on-connect connections, the ACL is run before the TLS connection
+is accepted; if the ACL does not accept then the TCP connection is dropped without
+any TLS startup attempt and without any SMTP response being transmitted.
+.wen
.subsection "The EHLO/HELO ACL" SECID192
immediate writes to file are done as normal.
trigger=<&'reason'&> This option selects cause for the pretrigger buffer
- see above) to be copied to file. A reason of $*now*
+ see above) to be copied to file. A reason of &*now*&
take effect immediately; one of &*paniclog*& triggers
on a write to the panic log.
.endd
.irow &`etrn`& * "ETRN commands"
.irow &`host_lookup_failed`& * "as it says"
.irow &`ident_timeout`& "timeout for ident connection"
-.irow &`incoming_interface`& "local interface on <= and => lines"
+.irow &`incoming_interface`& "local interface & port on <= and => lines"
.irow &`incoming_port`& "remote port on <= lines"
.irow &`lost_incoming_connection`& * "as it says (includes timeouts)"
.irow &`millisec`& "millisecond timestamps and RT,QT,DT,D times"
.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