Doc: Minor clarifications about the environment

[users/jgh/exim.git] / doc / doc-docbook / spec.xfpt

diff --git a/doc/doc-docbook/spec.xfpt b/doc/doc-docbook/spec.xfpt
index fdb318b89888610d7203797e68e6a0a107ace6ec..606358407fac0bef048693d65d18b923636e4a4e 100644 (file)
--- a/doc/doc-docbook/spec.xfpt
+++ b/doc/doc-docbook/spec.xfpt
@@ -4017,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.
 .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%&"
 
 .vitem &%-O%&&~<&'data'&>
 .oindex "&%-O%&"


@@ -5622,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.
 
 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
 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


@@ -5640,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.
 
 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"
 
 
 .section "ACL configuration" "SECID54"


@@ -9115,7 +9154,7 @@ configuration, you must add &%-export-dynamic%& to EXTRALIBS.
 
 .vitem "&*${env{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}}*&"
 .cindex "expansion" "extracting value from environment"
 
 .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.
 The key is first expanded separately, and leading and trailing white space
 removed.
 This is then searched for as a name in the environment.


@@ -9135,6 +9174,9 @@ search failure.
 If {<&'string1'&>} is omitted the search result is substituted on
 search success.
 
 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'&>&*}}*&"
 
 .vitem "&*${extract{*&<&'key'&>&*}{*&<&'string1'&>&*}{*&<&'string2'&>&*}&&&
        {*&<&'string3'&>&*}}*&"


@@ -11659,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
 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$&"
 
 .vitem &$host$&
 .vindex "&$host$&"


@@ -11735,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.
 
 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$&"
 
 .vitem &$inode$&
 .vindex "&$inode$&"


@@ -13954,10 +14003,10 @@ received. See chapter &<<CHAPACL>>& for further details.
 
 .new
 .option add_environment main "string list" empty
 
 .new
 .option add_environment main "string list" empty

-.cindex "environment" "inherited"
+.cindex "environment" "set values"

 This option allows to set individual environment variables that the
 This option allows to set individual environment variables that the

-currently linked libraries and programs in child processes use. The
-default list is empty,
+currently linked libraries and programs in child processes use.
+See &<<SECTpipeenv>>& for the environment of &(pipe)& transports.

 .wen
 
 .option admin_groups main "string list&!!" unset
 .wen
 
 .option admin_groups main "string list&!!" unset


@@ -15049,7 +15098,7 @@ See &%ignore_fromline_hosts%& above.
 
 .new
 .option keep_environment main "string list" unset
 
 .new
 .option keep_environment main "string list" unset

-.cindex "environment" "inherited"
+.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
 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


@@ -15066,9 +15115,15 @@ 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$.
 
 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 startupif you do not mention
-&%keep_environment%& or &%add_environment%& in your runtime configuration
-file.
+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 &<<SECTpipeenv>>& for
+details.

 .wen
 
 
 .wen
 
 


@@ -16788,6 +16843,7 @@ messages that are released by &%ignore_bounce_errors_after%&).
 
 .option timezone main string unset
 .cindex "timezone, setting"
 
 .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
 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


@@ -20434,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"
 .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
 .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


@@ -22853,11 +22909,12 @@ with &%use_shell%&, and the whole mechanism is inherently less secure.
 
 .section "Environment variables" "SECTpipeenv"
 .cindex "&(pipe)& transport" "environment for command"
 
 .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
 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
 .display
 &`DOMAIN            `&   the domain of the address
 &`HOME              `&   the home directory, if set


@@ -22952,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"
 
 .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 &<<SECTpipeenv>>& for the default list). Its value is
 a string which is expanded, and then interpreted as a colon-separated list of
 This option is used to add additional variables to the environment in which the
 command runs (see section &<<SECTpipeenv>>& for the default list). Its value is
 a string which is expanded, and then interpreted as a colon-separated list of


@@ -26578,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.
 . 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.
 
 . However, for the future we really need support for checking a
 . user cert in LDAP - which probably wants a base-64 DER.
 


@@ -38382,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.
 
 (space-separated by default) where the initial element
 is an IP address and any subsequent elements are options.
 

-Options are a string <name>=<value>. 
+Options are a string <name>=<value>.

 The list of options is in the following table:
 .display
 &'auth   '& authentication method
 The list of options is in the following table:
 .display
 &'auth   '& authentication method