. Update the Copyright year (only) when changing content.
. /////////////////////////////////////////////////////////////////////////////
-.set previousversion "4.97"
+.set previousversion "4.98"
.include ./local_params
.set ACL "access control lists (ACLs)"
.set drivernamemax "64"
.macro copyyear
-2023
+2024
.endmacro
. /////////////////////////////////////////////////////////////////////////////
versions. However, the more recent releases seem to have standardized on the
Berkeley DB library.
+.new
+Ownership of the Berkeley DB library has moved to a major corporation;
+development seems to have stalled and documentation is not freely available.
+This is probably not tenable for the long term use by Exim.
+.wen
+
Different DBM libraries have different conventions for naming the files they
use. When a program opens a file called &_dbmfile_&, there are several
possibilities:
&url(https://sourceforge.net/projects/tdb/files/). It has its own interface, and also
operates on a single file.
.next
-.new
It is possible to use sqlite3 (&url(https://www.sqlite.org/index.html))
for the DBM library.
-.wen
.endlist
.cindex "USE_DB"
There is further detailed discussion about the various DBM libraries in the
file &_doc/dbm.discuss.txt_& in the Exim distribution.
+.new
+When moving from one DBM library to another,
+for the hints databases it suffices to just remove all the files in the
+directory named &"db/"& under the spool directory.
+This is because hints are only for optimisation and will be rebuilt
+during normal operations.
+Non-hints DBM databases (used by &"dbm"& lookups in the configuration)
+will need individual rebuilds for the new DBM library.
+This is not done automatically
+.wen
+
.section "Pre-building configuration" "SECID25"
The word &"set"& at the start of a line, followed by a single space,
is recognised specially as defining a value for a variable.
-.new
.cindex "tainted data" "expansion testing"
If the sequence &",t"& is inserted before the space,
the value is marked as tainted.
-.wen
The syntax is otherwise the same as the ACL modifier &"set ="&.
.cmdopt -bem <&'filename'&>
.cindex "dsearch lookup type"
The given file must be an absolute directory path; this is searched for an entry
whose name is the key by calling the &[lstat()]& function.
-.new
Unless the options (below) permit a path,
-.wen
the key may not contain any forward slash characters.
If &[lstat()]& succeeds then so does the lookup.
.cindex "tainted data" "dsearch result"
${lookup pgsql,servers=master/db/name/pw {UPDATE ...} }
.endd
-.new
A now-deprecated syntax places the servers specification before the query,
semicolon separated:
.code
including the server sepcification - which is not permissible.
If the older sytax is used, a warning message will be logged.
This syntax will be removed in a future release.
-.wen
&*Note*&: server specifications in list-style lookups are still problematic.
anything (for example, setting a field to the value it already has), the result
is zero because no rows are affected.
-.new
To get an encryted connection, use a Mysql option file with the required
parameters for the connection.
-.wen
.subsection "Special PostgreSQL features" SECID74
For information on internationalisation support see &<<SECTi18nMTA>>&.
-.new
.vitem &*${xtextd:*&<&'string'&>&*}*&
.cindex "text forcing in strings"
.cindex "string" "xtext decoding"
.cindex "xtext"
.cindex "&%xtextd%& expansion item"
This performs xtext decoding of the string (per RFC 3461 section 4).
-.wen
.option acl_smtp_etrn main string&!! unset
.cindex "ETRN" "ACL for"
+.cindex "ETRN" advertisement
This option defines the ACL that is run when an SMTP ETRN command is
-received. See chapter &<<CHAPACL>>& for further details.
+received.
+If no value is set then the ETRN facility is not advertised.
+See chapter &<<CHAPACL>>& for further details.
.option acl_smtp_expn main string&!! unset
.cindex "EXPN" "ACL for"
This option defines the ACL that is run when an SMTP VRFY command is
received. See chapter &<<CHAPACL>>& for further details.
-.new
.option acl_smtp_wellknown main string&!! unset
.cindex "WELLKNOWN, ACL for"
This option defines the ACL that is run when an SMTP WELLKNOWN command is
received. See section &<<SECTWELLKNOWNACL>>& for further details.
-.wen
.option add_environment main "string list" empty
.cindex "environment" "set values"
-.new
.option limits_advertise_hosts main "host list&!!" *
.cindex LIMITS "suppressing advertising"
.cindex "ESMTP extensions" LIMITS
the limit for RCPT commands set by the &%recipients_max%& option (if it is set)
and the limit for MAIL commands set by the &%smtp_accept_max_per_connection%&
option.
-.wen
.option local_from_check main boolean true
.cindex "&'Sender:'& header line" "disabling addition of"
Non-SMTP messages with too many recipients are failed, and no deliveries are
done.
-.new
For SMTP message the expansion is done after the connection is
accepted (but before any SMTP conversation) and may depend on
the IP addresses and port numbers of the connection.
&*Note*&: If an expansion is used for the option,
care should be taken that a resonable value results for
non-SMTP messages.
-.wen
.cindex "RCPT" "maximum number of incoming"
&*Note*&: The RFCs specify that an SMTP server should accept at least 100
See also &%bounce_message_file%&.
-.new
.option wellknown_advertise_hosts main boolean unset
.cindex WELLKNOWN advertisement
.cindex "ESMTP extensions" WELLKNOWN
This option enables the advertising of the SMTP WELLKNOWN extension.
See also the &%acl_smtp_wellknown%& ACL (&<<SECTWELLKNOWNACL>>&).
-.wen
.option write_rejectlog main boolean true
.cindex "reject log" "disabling"
and are rewritten according to the global rewriting rules.
+.option sieve_inbox redirect string&!! &"inbox"&
+.new
+The value of this option is passed to a Sieve filter to specify the
+name of the mailbox used for "keep" operations (explicit or implicit).
+.wen
+
.option sieve_subaddress redirect string&!! unset
The value of this option is passed to a Sieve filter to specify the
:subaddress part of an address.
.endd
In this situation, the expansion of &%file%& or &%directory%& in the transport
must transform the relative path into an appropriate absolute filename. In the
-case of Sieve filters, the name &'inbox'& must be handled. It is the name that
+case of Sieve filters, the name &'inbox'& must be handled. It is the
+.new
+default
+.wen
+name that
is used as a result of a &"keep"& action in the filter. This example shows one
way of handling this requirement:
.code
location, absolute paths are used without change, and other folders are in the
&_mail_& directory within the home directory.
+.new
+An alternative for the &"keep"& aspect is to use the &%sieve_inbox%& option
+on the redirect router that calls the Sieve filter,
+to explicitly set the filename used.
+.wen
+
&*Note 1*&: While processing an Exim filter, a relative path such as
&_folder23_& is turned into an absolute path if a home directory is known to
the router. In particular, this is the case if &%check_local_user%& is set. If
&*Note 2*&: An absolute path in &$address_file$& is not treated specially;
the &%file%& or &%directory%& option is still used if it is set.
+.new
+&*Note 3*&: Permitting a user to enable writes to an absolute path
+may be a security issue.
+.wen
For testing purposes, this value can be overridden by the &%-oB%& command line
option.
-.new
.cindex "ESMTP extensions" LIMITS
If the peer advertises a LIMITS extension with a MAILMAX value,
and either TLSS is in use or was not advertised,
that value also constrains the result of this option.
-.wen
.option dane_require_tls_ciphers smtp string&!! unset
During the expansion of this option the &$item$& variable will have the
server's EHLO response.
-.new
For TLS-on-connect connections we do not have an EHLO
response to use. Because of this the default value of this option is
set to a static string for those cases, meaning that resumption will
always be attempted if permitted by the &%tls_resumption_hosts%& option.
-.wen
The result of the option expansion is included in the key used to store and
retrieve the TLS session, for session resumption.
so can cause parallel connections to the same host if &%remote_max_parallel%&
permits this.
-.new
.cindex "ESMTP extensions" LIMITS
If the peer advertises a LIMITS extension with a RCPTMAX value,
and either TLSS is in use or was not advertised,
that value also constrains the result of this option
and no parallel connections will be caused on meeting the RCPTMAX limit.
-.wen
.option message_linelength_limit smtp integer 998
only messages having the domain used for the DANE TLSA lookup are
sent on the connection.
-.new
.cindex "ESMTP extensions" LIMITS
If the peer advertises a LIMITS extension with a RCPTDOMAINMAX value,
and either TLSS is in use or was not advertised,
this option is regarded as being false.
-.wen
.option port smtp string&!! "see below"
deliveries into closed message stores. Exim also has support for running LMTP
over a pipe to a local process &-- see chapter &<<CHAPLMTP>>&.
-.new
&*Note*&: When using LMTP it should be considered whether the default values
for some other features, such as DANE, are appropriate.
-.wen
If this option is set to &"smtps"&, the default value for the &%port%& option
changes to &"smtps"&, and the transport initiates TLS immediately after
If the ACL is not defined, processing completes as if
the feature was not requested by the client.
-.new
.subsection "The SMTP WELLKNOWN ACL" SECTWELLKNOWNACL
.cindex "WELLKNOWN" "ACL for"
.oindex "&%acl_smtp_wellknown%&"
giving a key for an item of "site-wide metadata".
The verb and key are separated by whitespace,
and the key is xtext-encoded (per RFC 3461 section 4).
-.wen
.subsection "The QUIT ACL" SECTQUITACL
For the others (&%acl_smtp_etrn%&, &%acl_smtp_expn%&, &%acl_smtp_rcpt%&,
&%acl_smtp_vrfy%&
-.new
and &%acl_smtp_wellknown%&),
-.wen
the action when the ACL
is not defined is &"deny"&. This means that &%acl_smtp_rcpt%& must be
defined in order to receive any messages over an SMTP connection.
to a-label form.
For details see section &<<SECTi18nMTA>>&.
-.new
.vitem &*control&~=&~wellknown*&
This control sets up a response data file for a WELLKNOWN SMTP command.
It may only be used in an ACL servicing that command.
For details see section &<<SECTWELLKNOWNACL>>&.
-.wen
.endlist vlist
filename, and the default path is then used.
.endlist
The &%decode%& condition normally succeeds. It is only false for syntax
-errors or unusual circumstances such as memory shortages. You can easily decode
-a file with its original, proposed filename using
-.code
-decode = $mime_filename
-.endd
-However, you should keep in mind that &$mime_filename$& might contain
-anything. If you place files outside of the default path, they are not
+errors or unusual circumstances such as memory shortages.
+The variable &$mime_filename$& will have the suggested name for the file.
+Note however that this might contain anything, and is very difficult
+to safely use as all or even part of the filename.
+If you place files outside of the default path, they are not
automatically unlinked.
For RFC822 attachments (these are messages attached to messages, with a
.cindex "SMTP" "batching over TCP/IP"
When a message is successfully delivered over a TCP/IP SMTP connection, Exim
looks in the hints database for the transport to see if there are any queued
-messages waiting for the host to which it is connected. If it finds one, it
-creates a new Exim process using the &%-MC%& option (which can only be used by
-a process running as root or the Exim user) and passes the TCP/IP socket to it
-so that it can deliver another message using the same socket. The new process
-does only those deliveries that are routed to the connected host, and may in
-turn pass the socket on to a third process, and so on.
+messages waiting for the host to which it is connected.
+If it finds one, it arranges to attempt that message on the same connection.
The &%connection_max_messages%& option of the &(smtp)& transport can be used to
limit the number of messages sent down a single TCP/IP connection.
.subsection "The ETRN command" SECTETRN
.cindex "ETRN" "processing"
.cindex "ESMTP extensions" ETRN
+Most modern installations never need to use this.
+It is used for managing messages queued for an intermittently-connecting
+destination (eg. one using a dialup connection).
+
+.oindex "&%acl_smtp_etrn%&"
+The command is only available if permitted by an ACL
+specfied by the main-section &%acl_smtp_etrn%& option.
+
RFC 1985 describes an ESMTP command called ETRN that is designed to
overcome the security problems of the TURN command (which has fallen into
disuse). When Exim receives an ETRN command on a TCP/IP connection, it runs
.cindex log "DKIM verification"
.cindex DKIM "verification logging"
&%dkim_verbose%&: A log entry is written for each attempted DKIM verification.
-.new
Also, on message delivery lines signing information (domain and selector)
is added, tagged with DKIM=.
-.wen
.next
.cindex "log" "dnslist defer"
.cindex "DNS list" "logging defer"
The &'misc'& database is used for
.ilist
-Serializing ETRN runs (when &%smtp_etrn_serialize%& is set)
-.next
Serializing delivery to a specific host (when &%serialize_hosts%& is set in an
&(smtp)& transport)
.next
in a transport)
.next
Recording EHLO-time facilities advertised by hosts
+.next
+Serializing ETRN runs (when &%smtp_etrn_serialize%& is set)
.endlist
-.section "exim_dumpdb" "SECTdumpdb"
+.subsection "exim_dumpdb" "SECTdumpdb"
.cindex "&'exim_dumpdb'&"
The entire contents of a database are written to the standard output by the
&'exim_dumpdb'& program,
-.section "exim_tidydb" "SECTtidydb"
+.subsection "exim_tidydb" "SECTtidydb"
.cindex "&'exim_tidydb'&"
The &'exim_tidydb'& utility program is used to tidy up the contents of a hints
database. If run with no options, it removes all records that are more than 30
-.section "exim_fixdb" "SECTfixdb"
+.subsection "exim_fixdb" "SECTfixdb"
.cindex "&'exim_fixdb'&"
The &'exim_fixdb'& program is a utility for interactively modifying databases.
Its main use is for testing Exim, but it might also be occasionally useful for
Signing outgoing messages: This function is implemented in the SMTP transport.
It can co-exist with all other Exim features
(including transport filters) except cutthrough delivery.
-.new
However, signing options may not depend on headers modified by
routers, the transport or a transport filter.
-.wen
.next
Verifying signatures in incoming messages: This is implemented by an additional
ACL (acl_smtp_dkim), which can be called several times per message, with
.option dkim_timestamps smtp integer&!! unset
This option controls the inclusion of timestamp information in the signature.
If not set, no such information will be included.
-.new
Otherwise, must be an unsigned number giving an offset in seconds from the
current time for the expiry tag (e.g. 1209600 for two weeks); both creation
(t=) and expiry (x=) tags will be included unless the offset is 0 (no expiry).
-.wen
RFC 6376 lists these tags as RECOMMENDED.
ACL condition that checks a colon-separated list of possible DKIM verification
results against the actual result of verification,
given by &$dkim_verify_status$& if that is non-empty or "none" if empty.
-.new
This condition may be used in DKIM, MIME, PRDR and DATA ACLs.
-.wen
A basic verification might be:
.code
for more information of what they mean.
The condition is true if the status
-.new
(or any of the list of status values)
-.wen
is any one of the supplied list.
.endlist
The name is placed in the variable &$event_name$& and the event action
expansion must check this, as it will be called for every possible event type.
-.new
The current list of events is:
-.wen
.itable all 0 0 4 25* left 10* center 15* center 50* left
.row auth:fail after both "per driver per authentication attempt"
.row dane:fail after transport "per connection"
For OpenSSL it will trigger for every chain element including those
loaded locally.
-.new
For dns:fail events from dnsdb lookups, a &"defer_never"& option does not
affect the reporting of DNS_AGAIN.
-.wen
. ////////////////////////////////////////////////////////////////////////////
. ////////////////////////////////////////////////////////////////////////////
git://git.exim.org / exim.git / blobdiff