X-Git-Url: https://git.exim.org/exim.git/blobdiff_plain/9f35c169ea5438eaa6331a6d51974de1c4f4fdb0..exim-4_87:/doc/doc-docbook/spec.xfpt diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt index 18d67fe20..0d5577f06 100644 --- a/doc/doc-docbook/spec.xfpt +++ b/doc/doc-docbook/spec.xfpt @@ -52,7 +52,7 @@ .set I "    " .macro copyyear -2015 +2016 .endmacro . ///////////////////////////////////////////////////////////////////////////// @@ -2788,7 +2788,7 @@ continuations. As in Exim's run time configuration, white space at the start of continuation lines is ignored. Each argument or data line is passed through the string expansion mechanism, and the result is output. Variable values from the configuration file (for example, &$qualify_domain$&) are available, but no -message-specific values (such as &$sender_domain$&) are set, because no message +message-specific values (such as &$message_exim_id$&) are set, because no message is being processed (but see &%-bem%& and &%-Mset%&). &*Note*&: If you use this mechanism to test lookups, and you change the data @@ -3151,6 +3151,11 @@ using one of the words &%router_list%&, &%transport_list%&, or settings can be obtained by using &%routers%&, &%transports%&, or &%authenticators%&. +.cindex "environment" +If &%environment%& is given as an argument, the set of environment +variables is output, line by line. Using the &%-n%& flag suppresses the value of the +variables. + .cindex "options" "macro &-- extracting" If invoked by an admin user, then &%macro%&, &%macro_list%& and &%macros%& are available, similarly to the drivers. Because macros are sometimes used @@ -4012,7 +4017,8 @@ for that message. .oindex "&%-n%&" This option is interpreted by Sendmail to mean &"no aliasing"&. For normal modes of operation, it is ignored by Exim. -When combined with &%-bP%& it suppresses the name of an option from being output. +When combined with &%-bP%& it makes the output more terse (suppresses +option names, environment values and config pretty printing). .vitem &%-O%&&~<&'data'&> .oindex "&%-O%&" @@ -5617,7 +5623,7 @@ It provides a list of domains for which the &"percent hack"& is to operate. This is an almost obsolete form of explicit email routing. If you do not know anything about it, you can safely ignore this topic. -The last two settings in the main part of the default configuration are +The next two settings in the main part of the default configuration are concerned with messages that have been &"frozen"& on Exim's queue. When a message is frozen, Exim no longer continues to try to deliver it. Freezing occurs when a bounce message encounters a permanent failure because the sender @@ -5635,6 +5641,44 @@ message (whether a bounce message or not) is to be timed out (and discarded) after a week. In this configuration, the first setting ensures that no failing bounce message ever lasts a week. +Exim queues it's messages in a spool directory. If you expect to have +large queues, you may consider using this option. It splits the spool +directory into subdirectories to avoid file system degradation from +many files in a single directory, resulting in better performance. +Manual manipulation of queued messages becomes more complex (though fortunately +not often needed). +.code +# split_spool_directory = true +.endd + +In an ideal world everybody follows the standards. For non-ASCII +messages RFC 2047 is a standard, allowing a maximum line length of 76 +characters. Exim adheres that standard and won't process messages which +violate this standard. (Even ${rfc2047:...} expansions will fail.) +In particular, the Exim maintainers have had multiple reports of +problems from Russian administrators of issues until they disable this +check, because of some popular, yet buggy, mail composition software. +.code +# check_rfc2047_length = false +.endd + +If you need to be strictly RFC compliant you may wish to disable the +8BITMIME advertisement. Use this, if you exchange mails with systems +that are not 8-bit clean. +.code +# accept_8bitmime = false +.endd + +Libraries you use may depend on specific environment settings. This +imposes a security risk (e.g. PATH). There are two lists: +&%keep_environment%& for the variables to import as they are, and +&%add_environment%& for variables we want to set to a fixed value. +Note that TZ is handled separately, by the $%timezone%$ runtime +option and by the TIMEZONE_DEFAULT buildtime option. +.code +# keep_environment = ^LDAP +# add_environment = PATH=/usr/bin::/bin +.endd .section "ACL configuration" "SECID54" @@ -7739,7 +7783,7 @@ domain, host, address and local part lists. -.section "Expansion of lists" "SECID75" +.section "Expansion of lists" "SECTlistexpand" .cindex "expansion" "of lists" Each list is expanded as a single string before it is used. The result of expansion must be a list, possibly containing empty items, which is split up @@ -9110,7 +9154,7 @@ configuration, you must add &%-export-dynamic%& to EXTRALIBS. .vitem "&*${env{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*&" .cindex "expansion" "extracting value from environment" -.cindex "environment" "value from" +.cindex "environment" "values from" The key is first expanded separately, and leading and trailing white space removed. This is then searched for as a name in the environment. @@ -9130,6 +9174,9 @@ search failure. If {<&'string1'&>} is omitted the search result is substituted on search success. +The environment is adjusted by the &%keep_environment%& and +&%add_environment%& main section options. + .vitem "&*${extract{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}&&& {*&<&'string3'&>&*}}*&" @@ -9677,7 +9724,8 @@ ${readsocket{inet:[::1]:1234}{request string}} Only a single host name may be given, but if looking it up yields more than one IP address, they are each tried in turn until a connection is made. For both kinds of socket, Exim makes a connection, writes the request string -(unless it is an empty string) and reads from the socket until an end-of-file +unless it is an empty string; and no terminating NUL is ever sent) +and reads from the socket until an end-of-file is read. A timeout of 5 seconds is applied. Additional, optional arguments extend what can be done. Firstly, you can vary the timeout. For example: .code @@ -11653,7 +11701,8 @@ explicitly set a home directory for use by a transport; this can be overridden by a setting on the transport itself. When running a filter test via the &%-bf%& option, &$home$& is set to the value -of the environment variable HOME. +of the environment variable HOME, which is subject to the +&%keep_environment%& and &%add_environment%& main config options. .vitem &$host$& .vindex "&$host$&" @@ -11729,6 +11778,12 @@ See &$host_lookup_deferred$&. This variable is set to the remote host's TCP port whenever &$host$& is set for an outbound connection. +.vitem &$initial_cwd$& +.vindex "&$initial_cwd$& +This variable contains the full path name of the initial working +directory of the current Exim process. This may differ from the current +working directory, as Exim changes this to "/" during early startup, and +to &$spool_directory$& later. .vitem &$inode$& .vindex "&$inode$&" @@ -13946,6 +14001,14 @@ received. See chapter &<>& for further details. This option defines the ACL that is run when an SMTP VRFY command is received. See chapter &<>& for further details. +.new +.option add_environment main "string list" empty +.cindex "environment" "set values" +This option allows to set individual environment variables that the +currently linked libraries and programs in child processes use. +See &<>& for the environment of &(pipe)& transports. +.wen + .option admin_groups main "string list&!!" unset .cindex "admin user" This option is expanded just once, at the start of Exim's processing. If the @@ -14107,7 +14170,7 @@ If the message being returned has lines longer than this value it is treated as if the &%bounce_return_size_limit%& (below) restriction was exceeded. The option also applies to bounces returned when an error is detected -during reception of a messsage. +during reception of a message. In this case lines from the original are truncated. The option does not apply to messages generated by an &(autoreply)& transport. @@ -15033,6 +15096,36 @@ process rather than a remote host, and is using &%-bs%& to inject the messages, .option ignore_fromline_local main boolean false See &%ignore_fromline_hosts%& above. +.new +.option keep_environment main "string list" unset +.cindex "environment" "values from" +This option contains a string list of environment variables to keep. +You have to trust these variables or you have to be sure that +these variables do not impose any security risk. Keep in mind that +during the startup phase Exim is running with an effective UID 0 in most +installations. As the default value is an empty list, the default +environment for using libraries, running embedded Perl code, or running +external binaries is empty, and does not not even contain PATH or HOME. + +Actually the list is interpreted as a list of patterns +(&<>&), except that it is not expanded first. + +WARNING: Macro substitution is still done first, so having a macro +FOO and having FOO_HOME in your &%keep_environment%& option may have +unexpected results. You may work around this using a regular expression +that does not match the macro name: ^[F]OO_HOME$. + +Current versions of Exim issue a warning during startup if you do not mention +&%keep_environment%& in your runtime configuration file and if your +current environment is not empty. Future versions may not issue that warning +anymore. + +See the &%add_environment%& main config option for a way to set +environment variables to a fixed value. The environment for &(pipe)& +transports is handled separately, see section &<>& for +details. +.wen + .option keep_malformed main time 4d This option specifies the length of time to keep messages whose spool files @@ -16071,6 +16164,12 @@ it qualifies them only if the message came from a host that matches &%sender_unqualified_hosts%&, or if the message was submitted locally (not using TCP/IP), and the &%-bnq%& option was not set. +.option set_environment main "string list" empty +.cindex "environment" +This option allows to set individual environment variables that the +currently linked libraries and programs in child processes use. The +default list is empty, + .option slow_lookup_log main integer 0 .cindex "logging" "slow lookups" @@ -16744,6 +16843,7 @@ messages that are released by &%ignore_bounce_errors_after%&). .option timezone main string unset .cindex "timezone, setting" +.cindex "environment" "values from" The value of &%timezone%& is used to set the environment variable TZ while running Exim (if it is different on entry). This ensures that all timestamps created by Exim are in the required timezone. If you want all your timestamps @@ -16887,7 +16987,7 @@ this option selects a EC curve for use by Exim. Curve names of the form &'prime256v1'& are accepted. For even more-recent library versions, names of the form &'P-512'& are also accepted, plus the special value &'auto'& -which tell the library to choose. +which tells the library to choose. If the option is set to an empty string, no EC curves will be enabled. @@ -20390,7 +20490,7 @@ See &%skip_syntax_errors%& above. .chapter "Environment for running local transports" "CHAPenvironment" &&& "Environment for local transports" .scindex IIDenvlotra1 "local transports" "environment for" -.scindex IIDenvlotra2 "environment for local transports" +.scindex IIDenvlotra2 "environment" "local transports" .scindex IIDenvlotra3 "transport" "local; environment for" Local transports handle deliveries to files and pipes. (The &(autoreply)& transport can be thought of as similar to a pipe.) Exim always runs transports @@ -22809,11 +22909,12 @@ with &%use_shell%&, and the whole mechanism is inherently less secure. .section "Environment variables" "SECTpipeenv" .cindex "&(pipe)& transport" "environment for command" -.cindex "environment for pipe transport" +.cindex "environment" "&(pipe)& transport" The environment variables listed below are set up when the command is invoked. This list is a compromise for maximum compatibility with other MTAs. Note that the &%environment%& option can be used to add additional variables to this -environment. +environment. The environment for the &(pipe)& transport is not subject +to the &%add_environment%& and &%keep_environment%& main config options. .display &`DOMAIN `& the domain of the address &`HOME `& the home directory, if set @@ -22908,7 +23009,7 @@ Exim, and each argument is separately expanded, as described in section .option environment pipe string&!! unset .cindex "&(pipe)& transport" "environment for command" -.cindex "environment for &(pipe)& transport" +.cindex "environment" "&(pipe)& transport" This option is used to add additional variables to the environment in which the command runs (see section &<>& for the default list). Its value is a string which is expanded, and then interpreted as a colon-separated list of @@ -23417,6 +23518,15 @@ the message. As a result, the overall timeout for a message depends on the size of the message. Its value must not be zero. See also &%final_timeout%&. +.option dkim_domain smtp string&!! unset +.option dkim_selector smtp string&!! unset +.option dkim_private_key smtp string&!! unset +.option dkim_canon smtp string&!! unset +.option dkim_strict smtp string&!! unset +.option dkim_sign_headers smtp string&!! unset +DKIM signing options. For details see &<>&. + + .option delay_after_cutoff smtp boolean true This option controls what happens when all remote IP addresses for a given domain have been inaccessible for so long that they have passed their retry @@ -24059,7 +24169,7 @@ and certificate verification fails the TLS connection is closed. .option tls_verify_hosts smtp "host list&!!" unset .cindex "TLS" "server certificate verification" .cindex "certificate" "verification of server" -This option gives a list of hosts for which. on encrypted connections, +This option gives a list of hosts for which, on encrypted connections, certificate verification must succeed. The &%tls_verify_certificates%& option must also be set. If both this option and &%tls_try_verify_hosts%& are unset @@ -26525,7 +26635,7 @@ whereas a plaintext SMTP AUTH done inside TLS is not. . to require one of a set of specific certs that define a given account . (the verification is still required, but mostly irrelevant). . This would help for per-device use. -. +. . However, for the future we really need support for checking a . user cert in LDAP - which probably wants a base-64 DER. @@ -27450,9 +27560,6 @@ a realistic ACL for checking RCPT commands. This is discussed in chapter .section "Testing ACLs" "SECID188" The &%-bh%& command line option provides a way of testing your ACL configuration locally by running a fake SMTP session with which you interact. -The host &'relay-test.mail-abuse.org'& provides a service for checking your -relaying configuration (see section &<>& for more details). - .section "Specifying when ACLs are used" "SECID189" @@ -28596,7 +28703,11 @@ and data is copied from one to the other. An attempt to set this option for any recipient but the first for a mail will be quietly ignored. -If a recipient-verify callout connection is subsequently +If a recipient-verify callout +.new +(with use_sender) +.wen +connection is subsequently requested in the same ACL it is held open and used for any subsequent recipients and the data, otherwise one is made after the initial RCPT ACL completes. @@ -28607,6 +28718,14 @@ Note also that headers cannot be modified by any of the post-data ACLs (DATA, MIME and DKIM). Headers may be modified by routers (subject to the above) and transports. +.new +All the usual ACLs are called; if one results in the message being +rejected, all effort spent in delivery (including the costs on +the ultimate destination) will be wasted. +Note that in the case of data-time ACLs this includes the entire +message body. +.wen + Cutthrough delivery is not supported via transport-filters or when DKIM signing of outgoing messages is done, because it sends data to the ultimate destination before the entire message has been received from the source. @@ -30895,14 +31014,6 @@ in chapter &<>&. You can check the relay characteristics of your configuration in the same way that you can test any ACL behaviour for an incoming SMTP connection, by using the &%-bh%& option to run a fake SMTP session with which you interact. - -For specifically testing for unwanted relaying, the host -&'relay-test.mail-abuse.org'& provides a useful service. If you telnet to this -host from the host on which Exim is running, using the normal telnet port, you -will see a normal telnet connection message and then quite a long delay. Be -patient. The remote host is making an SMTP connection back to your host, and -trying a number of common probes to test for open relay vulnerability. The -results of the tests will eventually appear on your terminal. .ecindex IIDacl @@ -35573,8 +35684,8 @@ the following table: &`QT `& on &`=>`& lines: time spent on queue so far &` `& on &"Completed"& lines: time spent on queue &`R `& on &`<=`& lines: reference for local bounce -&` `& on &`=>`& &`**`& and &`==`& lines: router name -&`S `& size of message +&` `& on &`=>`& &`>>`& &`**`& and &`==`& lines: router name +&`S `& size of message in bytes &`SNI `& server name indication from TLS client hello &`ST `& shadow transport name &`T `& on &`<=`& lines: message subject (topic) @@ -38005,7 +38116,7 @@ where you accept mail from relay sources (internal hosts or authenticated senders). -.section "Signing outgoing messages" "SECID513" +.section "Signing outgoing messages" "SECDKIMSIGN" .cindex "DKIM" "signing" Signing is implemented by setting private options on the SMTP transport. @@ -38328,7 +38439,7 @@ Each proxy specifier is a list (space-separated by default) where the initial element is an IP address and any subsequent elements are options. -Options are a string =. +Options are a string =. The list of options is in the following table: .display &'auth '& authentication method