Adding upstream version 4.92.upstream/4.92upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 1730 insertions, 0 deletions

diff --git a/doc/Exim4.upgrade b/doc/Exim4.upgrade
new file mode 100644
index 0000000..528d94d
--- /dev/null
+++ b/doc/Exim4.upgrade
@@ -0,0 +1,1730 @@
+Upgrading Exim from Release 3.33 to 4.xx
+----------------------------------------
+
+Exim 4.00 represents the largest upheaval in Exim's history. There are a lot of
+changes to the way some parts of Exim work, and a lot of incompatible changes
+to the run time configuration file.
+
+This document is in two parts. The first part contains instructions and
+suggestions for how you might go about performing the upgrade. The second part
+is a brief list of all the changes that have taken place. For full details of
+all the new features, please consult the current version of the reference
+manual.
+
+
+HOW TO UPGRADE YOUR EXIM
+------------------------
+
+When you compile Exim 4, a Perl script called convert4r4 is built in the build
+directory. It is not installed by the install script, because it is likely that
+you will run it only once.
+
+This script is provided to assist in updating Exim configuration files. It
+reads an Exim 3 configuration file on the standard input, and writes a modified
+file on the standard output. It also writes comments about what it has done to
+the standard error file. It assumes that the input is a valid Exim 3
+configuration file. A typical call to the conversion script might be
+
+  ./convert4r4  </etc/exim/configure  >/etc/exim/configure.new
+
+The output file MUST be checked and tested before trying to use it on a live
+system. The conversion script is just an aid which does a lot of the "grunt
+work". It does not guarantee to produce an Exim 4 configuration that behaves
+exactly the same as the Exim 3 configuration it reads.
+
+Each option change in the new file is preceded by an identifying comment. In
+fact, the conversion script tends to make quite a mess of your configuration,
+and you should expect to go through it afterwards and tidy it up by hand.
+
+Unless you are running a very straightforward configuration, the automatic
+conversion is likely to generate a non-optimal configuration. You should not
+only check it thoroughly, but also run as many tests as you can, to ensure that
+it is working as you expect. In particular, you should test address routing,
+using -bt and -bv, and the policy controls, using -bh. If possible, you should
+also do some live tests (i.e. send and receive some messages) before putting
+Exim 4 into service.
+
+If you have a very complicated configuration, it is possible that convert4r4
+will break it in some situations, which is why thorough testing is strongly
+recommended.
+
+                   *********************************
+                   ***** You Have Been Warned ******
+                   *********************************
+
+
+HOW TO MOVE FROM AN EXIM 3 RELEASE TO AN EXIM 4 RELEASE
+-------------------------------------------------------
+
+One way of upgrading to Exim 4 from a version 3 release is as follows:
+
+1. Suppose your run time configuration file is called /usr/exim/configure, and
+   you want to continue with this name after upgrading. The first thing to do
+   is to make another copy of this file called, say, /usr/exim/configure.r3.
+
+2. Rebuild your existing Exim to use the copy of the run time configuration
+   file instead of the standard file. Install this version of Exim and HUP your
+   daemon. You can check on the name of the configuration file by running
+
+     exim -bP configure_file
+
+   Ensure that everything is running smoothly. You now have something you can
+   fall back to. IMPORTANT: when you do this re-install, you should also
+   re-install the utilities because four of them (exicyclog, eximon, exinext,
+   and exiwhat) also refer to the configuration file.
+
+3. Build the new release, configured to use the standard configuration file.
+
+4. Use the convert4r4 utility to upgrade your configuration file for the new
+   release. After running the conversion utility, check the file by hand, and
+   tidy it up.
+
+5. Test, test, test! And test some more!
+
+6. You can run complete tests, including actual deliveries, from an uninstalled
+   binary, but you have to tell it where it is, so that any re-executions can
+   be done. You can do this by temporarily inserting a setting such as
+
+   exim_path = /source/exim/exim-4.00/build-SunOS5-5.8-sparc/exim
+
+   into the run time configuration. If you want to, you can also insert
+   settings for spool_directory and log_file_path to divert those away from
+   their normal places. Remember to remove these temporary settings when you
+   eventually install the binary for real.
+
+7. The new installation script installs the new release as exim-4.00-1, and
+   set a symbolic link called "exim" to point to it. The old version of Exim
+   will be renamed to something like exim-3.33-1.
+
+8. You can now easily change between the new and old releases simply by moving
+   the symbolic link and HUPping your daemon. The format of message files on
+   Exim's spool has _not_ changed, so there should be no problem in changing
+   between releases while there are messages on the queue.
+
+9. HOWEVER: If you do change back and forth between releases, you must also
+   change the utilities exicyclog, eximon, exinext, and exiwhat if you are
+   going to use them. Installing Exim 4 will have left the old versions with a
+   .O suffix. It might be helpful to rename these so that you don't lose them.
+
+
+WHAT HAS NOT CHANGED IN EXIM 4.00
+---------------------------------
+
+The basic overall philosophy, design, and process structure has not changed.
+The format of spool files is the same. The transports have had only minor
+modifications. The command line options remain the same, with a couple of
+additions.
+
+The general run time configuration approach has not changed, but the actual
+details of the configuration file are different.
+
+The Exim monitor has not changed, and there have been only very minor changes
+to other Exim utilities.
+
+
+WHAT HAS CHANGED IN EXIM 4.00
+-----------------------------
+
+The rest of this document lists the very many changes that have taken place.
+I'm going to give only brief details here, because this part of the document is
+intended as a way of alerting you to areas of difference. The reference manual
+describes how the new features work in detail.
+
+
+Named domain, host, address, and local part lists
+-------------------------------------------------
+
+A new feature makes it possible to give names to lists of domains, hosts,
+addresses, and local parts. The syntax used is
+
+  domainlist    <name> = <a domain list>
+  hostlist      <name> = <a host list>
+  addresslist   <name> = <an address list>
+  localpartlist <name> = <a list of local parts>
+
+For example:
+
+  domainlist  local_domains = *.my.domain
+  addresslist bad_senders = cdb;/etc/badsenders
+
+These lists are referenced in options by giving the name preceded by a + sign.
+For example, in a router you might have
+
+  domains = +local_domains
+
+At first sight, these lists might seem to be the same as macros, but they are
+not. Macros are just textual substitutions. If you write
+
+  ALIST = host1 : host2
+  auth_advertise_hosts = !ALIST
+
+it probably won't do what you want, because that is exactly the same as
+
+  auth_advertise_hosts = !host1 : host2
+
+Notice that the second host name is not negated. However, if you use a host
+list, and write
+
+  hostlist alist = host1 : host2
+  auth_advertise_hosts = ! +alist
+
+the negation applies to the whole list, and so that is equivalent to
+
+  auth_advertise_hosts = !host1 : !host2
+
+These named lists also have a performance advantage. When Exim is routing an
+address or checking an incoming message, it caches the result of tests on the
+lists. So, if you have a setting such as
+
+  domains = +local_domains
+
+on several of your routers, the actual test is done only for the first one.
+However, this caching works only if there are no expansions within the list
+itself or any sublists that it references. In other words, caching happens only
+if the list is known to be the same each time it is referenced.
+
+By default, there may be up to 16 named lists of each type. This limit can be
+extended by changing a compile-time variable.
+
+The use of domain and host lists is recommended for concepts such as local
+domains, relay domains, and relay hosts. The default configuration is set up
+like this.
+
+
+Processing of domain, host, local part, and address lists
+---------------------------------------------------------
+
+The handling of these lists is now more uniform. Every list is expanded as a
+single string before it is used. (In Exim 3, some options were expanded and
+some weren't, and query-style lookup items were then re-expanded.)
+
+If an expansion is forced to fail, Exim behaves as if the item has not been
+found in the list.
+
+The confusing $key variable has been abolished. When processing a domain list,
+$domain contains the relevant domain and can be used in generating database
+queries. Other appropriate variables are set when processing other kinds of
+list; $sender_host and $sender_host_address for checking incoming hosts and
+$host and $host_address for checking outgoing hosts.
+
+Note that this means that any \ and $ characters in regular expressions must be
+escaped if they appear in one of these lists. The new expansion feature to turn
+off expansion (\N ... \N) which is described below can be helpful here.
+
+IMPORTANT: The details of the processing of address lists has been revised. In
+particular, the handling of the case of an item that is a single-key lookup has
+changed. It no longer looks up the domain on its own before looking up the
+complete address. You need to supply an explicit "*@" before the lookup if you
+want just the domain to be looked up. Please check the manual for full details.
+
+If an item in a host list is the empty string, it matches only when no host is
+defined. If used when checking an incoming message, it matches only when the
+message is arriving by SMTP on the standard input from a local process (using
+-bs). This provides a way of distinguishing between SMTP mail from local
+processes and from remote hosts.
+
+The +allow_unknown and +warn_unknown settings for host lists have been replaced
+by a single item, +include_unknown. By default, failure to find a host name
+when needed causes Exim to behave as if the host does not match the list, but
+if +include_unknown is set, the opposite behaviour happens. Whenever
++include_unknown is invoked, the incident is logged.
+
+
+Merge of Directors and Routers
+------------------------------
+
+There are no longer any directors in Exim 4. There are just routers. All
+addresses are passed to a single list of routers which typically makes use of
+the "domains" option to choose which way to handle specific groups of domains.
+
+A consequence of this is that the code no longer contains any concept of "local
+domains". However, a typical configuration will probably define a named domain
+list (see above) called local_domains, and use it to control routing something
+like this:
+
+  route_remote:
+    driver = dnslookup
+    domains = ! +local_domains
+    transport = remote_smtp
+    no_more
+
+  system_aliases:
+    ....
+
+The first router does DNS routing for all domains that are not in the named
+list of local domains, and no_more ensures that it is the last router for those
+domains. All other domains fall through to the system_aliases and subsequent
+routers. For a complete configuration example, look at the default
+configuration file in src/configure.default.
+
+
+Router Actions
+--------------
+
+The concept of how the routers work is as follows:
+
+A number of pre-conditions are tested (details below). If any of them fails,
+control is passed to the next router. We say "the router is skipped". Otherwise
+the router is run, and can yield one of several different results:
+
+. accept: The router accepts the address, and either queues it for a transport,
+or generates one or more "child" addresses. Processing the original address
+ceases, unless "unseen" is set on the router, in which case the address is
+passed to the next router. Processing of any child addresses starts with the
+first router by default, or at the router defined by redirect_router if it is
+set. This may be any router in the list.
+
+. decline: The router declines to accept the address because it does not
+recognize it at all. The address is passed to the next router, unless no_more
+is set, in which case the address fails.
+
+. pass: The router recognizes the address, but cannot handle it itself. It
+requests that the address be passed to another router. This overrides no_more.
+By default the address is passed to the next router, but this can be changed by
+setting pass_router. However, in this case (unlike redirect_router) the named
+router must be below the current router (to avoid loops).
+
+. fail: The router determines that the address should fail, and queues it for
+the generation of a bounce message. There is no further processing of the
+original address, unless "unseen" is set.
+
+. defer: The router cannot handle the address at the present time. (For
+example, a database may be offline.) No further processing of the address
+happens in this delivery attempt. It is tried again next time.
+
+. error: There is some error in the router (for example, a syntax error in
+its configuration). The action is as for defer.
+
+
+Router pre-conditions
+---------------------
+
+In Exim 3 there are some strange interactions between the generic options that
+test things before running a director or router and the no_more test that
+happens afterwards.
+
+In Exim 4 it is all more straightforward. If any of the pre-condition tests
+fail, the router is skipped and control passes to the next router. The no_more
+option has an effect only if the router is actually run - that is, if all the
+pre-condition tests succeed. The order in which these tests are run is:
+
+  verify status, expn status, domains, local_parts, check_local_user
+
+If all those match, the debug_print string is output when debugging. Exim then
+goes on to test
+
+  senders, require_files, condition
+
+Note that require_files comes near the end of the list, so you cannot use it to
+check for the existence of a file in which to lookup up a domain, local part,
+or sender. However, as these options are all expanded, you can use the "exists"
+expansion condition to make such tests. The require_files option is intended
+for checking files that the router may be going to use internally, or which are
+needed by a specific transport (e.g. .procmailrc).
+
+In Exim 4, local part prefixes and suffixes are recognized and removed before
+any of the other pre-condition tests are done (in Exim 3 they were removed
+afterwards). Note that this means that the local_parts option now tests the
+local part without its prefix or suffix.
+
+If you want to use local parts that include any affixes in a pre-condition
+test, you can do so by using a "condition" option that uses the variables
+$local_part, $local_part_prefix, and $local_part_suffix as necessary.
+
+
+A New Set of Routers
+--------------------
+
+The two sets of routers and directors of Exim 3 have been replaced by a single
+set of routers for Exim 4. These are as follows:
+
+. accept        Always accepts an address. It has no private options.
+
+. dnslookup     Routes by DNS lookup (descended from lookuphost).
+
+. ipliteral     Routes IP literal addresses (unchanged).
+
+. iplookup      Special-purpose lookup router (unchanged).
+
+. manualroute   Routes domains from explicit data (descended from domainlist).
+
+. queryprogram  Routes addresses by running a program (detail changed).
+
+. redirect      Redirects addresses; handles all the functions previously
+                supported by aliasfile, forwardfile, and smartuser without
+                a transport.
+
+
+Saving duplication of effort while routing
+------------------------------------------
+
+Early versions of Exim used to copy the routing of one address for all other
+addresses in the same domain, thereby possibly saving some repeated DNS
+lookups. This feature was removed for release 2.12, after the possibility of
+varying the router actions according to the local part (the local_parts option)
+was added. (In fact, the use of $local_part could have broken it earlier.)
+
+For Exim 4, I have added an option called same_domain_copy_routing to the
+dnslookup and manualroute routers. When one of these routers routes an address
+to a remote transport and this option is set, any other addresses in the
+message that have the same domain are automatically given the same routing, but
+only if the router does not set headers_add or headers_remove, and does not
+`widen' the domain during the routing.
+
+
+Generic Router Options
+----------------------
+
+. The global locally_caseless option is replaced by a generic router option
+  called caseful_local_part. By default, routers handle local parts caselessly.
+
+. check_local_user is now a generic option that is needed to check for a local
+  account. Typically used on redirect (for user's forward files) and on accept
+  (for local deliveries).
+
+. The setting self=local has been removed (since there's no concept of local
+  domains in the code). The same kind of effect can be achieved by using
+  self=reroute or self=pass.
+
+. expn is now a generic router option.
+
+. local_part_prefix and local_part_suffix are now generic router options,
+  replacing prefix and suffix on directors.
+
+. Exim 3 has two logging styles for delivery, depending on whether the domain
+  is a local domain or not. For local domains, the address is given just as the
+  local part - this makes these deliveries easier to spot in the log. In Exim 4
+  there's no concept of local domains, so this functionality cannot be
+  automatic. Instead, there's a generic router option called log_as_local which
+  requests "local-style" logging. This option defaults on for the "accept"
+  router, and off for all the others.
+
+. There's an option called retry_use_local_part which is the default for any
+  router that has check_local_user set, and it applies to routing delays. (The
+  same option for transports applies to transport delays.)
+
+. transport_home_directory and transport_current_directory are new generic
+  options on all routers. They set up default values for home_directory and
+  current_directory on the transport to which they route an address. Any
+  settings in the transport override.
+
+. If transport_home_directory is not set, but check_local_user is set, the
+  user's home directory is used as a default value.
+
+. The special fudge that exists in Exim 3 for handling home_directory settings
+  in forwardfile directors is not needed in Exim 4. It has therefore been
+  removed.
+
+. The new_director option in Exim 3 allows the direction of redirected
+  addresses to start at a given director, instead of the first one. In Exim 4,
+  this option is now called redirect_router. The option is used when a redirect
+  router succeeds, and when a queryprogram router returns a "redirect"
+  response.
+
+. There is a new option called pass_router, which specifies the router to go to
+  when a router "passes" on an address. The named router must follow the
+  current router (to avoid routing loops). Note: if a router declines, control
+  always passes to the next router, unless no_more is set.
+
+. There is a new router option called address_data. This is set to a string
+  which is expanded just before the router is run, that is, after all the
+  pre-tests have succeeded. If the expansion is forced to fail, the router
+  declines. Other expansion failures cause delivery of the address to be
+  deferred.
+
+  When the expansion succeeds, the value is retained with the address, and can
+  be accessed using the variable $address_data. Even if the router declines or
+  passes, the value remains with the address, though it can be changed by
+  another address_data setting on a subsequent router. If a router generates
+  child addresses, the value of $address_data propagates to them.
+
+  The idea of address_data is that you can use it to look up a lot of data for
+  the address once, then then pick out parts of the data later. For example,
+  you could use an LDAP lookup to return a string of the form
+
+    uid=1234 gid=5678 mailbox=/mail/xyz forward=/home/xyz/.forward
+
+  In the transport you could then pick out the mailbox by a setting such as
+
+    file = ${extract{mailbox}{$address_data}}
+
+  This makes the configuration file less messy, and also reduces the number of
+  lookups. (Exim does cache the most recent lookup, but there may be several
+  addresses with different lookups.)
+
+. When a transport is run for several addresses simultaneously, the values of
+  $address_data, $local_part_data, and $domain_data are taken from the first
+  address that the transport handles. However, the order in which multiple
+  addresses are processed is not defined. You therefore need to be careful if
+  you want to use these variables with multiple addresses. The smtp transport
+  is the only one which by default handles multiple addresses.
+
+. When an address is routed by a router with the "unseen" option set, a "clone"
+  address is created, and it starts being routed at the next router. (This is
+  what people expect. In Exim 3 it starts at the top - in simple cases that has
+  the same effect because of the anti-looping rule, but if aliases are involved
+  it sometimes doesn't do what you want.)
+
+. The way that require_files works has been changed. Each item in the list is
+  now separately expanded as the test proceeds. The use of leading ! and +
+  characters is unchanged. However, user and group checking is done differently.
+  Previously, seteuid() was used, but seteuid() is no longer used in Exim (see
+  "Security" below). Instead, Exim now scans along the components of the file
+  path and checks the access for the given uid and gid. It expects "x" access
+  on directories and "r" on the final file. This means that file access control
+  lists (on those operating systems that have them) are ignored.
+
+
+Other Consequences of the Director/Router Merge
+-----------------------------------------------
+
+. The -odqr option is abolished, as there is no inbuilt concept of remote
+  domains.
+
+. The -odqs option is equivalent to queue_smtp_domains = *.
+
+. queue_remote_domains is renamed queue_domains, and applies to any domain.
+
+. The -ql option now suppresses remote delivery; routing always happens.
+
+. The "remote" facility of queue_only_file has been removed.
+
+. The match_directory option for forwardfile and localuser has been entirely
+  abolished. Its function can be achieved using the "condition" option in
+  conjunction with check_local_user.
+
+. When an address is being verified, if it is redirected to a single new
+  address, verification continues with that address. If it is redirected to
+  more than one address, verification ceases with a success result. (In Exim 3,
+  this applied only to aliasing, not to forwarding.)
+
+
+The dnslookup router
+--------------------
+
+This router replaces the lookuphost router of Exim 3. It is much the same,
+except that the "gethostbyname" option has been removed. It now does only DNS
+routing - hence the change of name. Routing using gethostbyname() can be done
+by the manualroute router.
+
+
+The manualroute router
+----------------------
+
+This is the new name for the domainlist router, supposedly to make its function
+clearer and to avoid confusion with the "domainlist" that is used to set up
+named domain lists. Several things have been removed and reorganized.
+
+. The old search mechanism (route_file, route_query, route_queries,
+  search_type) have been removed. Instead there is a new option called
+  route_data, which is an expanded string. It should expand to a single routing
+  entry. If the expansion ends up empty (or is forced to fail), the router
+  declines. The route_list option still exists, for convenient listing of a few
+  inline routes.
+
+. There is no longer any MX processing function in this router. The keywords
+  bydns_mx and bydns_a have been removed, leaving just
+
+    bydns  => find IP addresses from address records in the DNS
+    byname => find IP addresses by calling gethostbyname()
+
+  The default lookup type is "byname", and this can be omitted from a route
+  data line. If an IP address is given, both "byname" and "bydns" are ignored
+  (so typically you omit this field).
+
+. The qualify_single and search_parents options have also been removed.
+
+. A transport is always required to be set, unless verify_only is set.
+
+. The host_find_failed option can be set to "decline", to cause the router to
+  decline if it can't find an IP address for a listed host.
+
+. If manualroute routes to a local transport, there is no need to specify
+  byname or bydns in the routing data. Any supplied host list is passed as a
+  string in $host, but $host_address is unset.
+
+
+The queryprogram router
+-----------------------
+
+This router has been re-designed:
+
+. You must now specify a user and group for the program to be run using
+  command_user and (if necessary) command_group. It no longer defaults to
+  "nobody". These options are expanded.
+
+. The command is now split up and each argument expanded separately, as happens
+  for the pipe transport. The command name is also expanded.
+
+. The return value "forcefail" has been renamed "fail", and it causes delivery
+  to fail. (The original usage of "fail" meaning "decline" has finally been
+  removed.)
+
+. The $route_option variable, which queryprogram used to be able to set has
+  been abolished. A facility to set the new $address_data variable replaces it.
+
+. The string returned from queryprogram must now be one of:
+
+  DECLINE
+  FAIL text
+  DEFER text
+  PASS
+  FREEZE text
+  REDIRECT text
+  ACCEPT TRANSPORT=transport HOSTS=host list LOOKUP=byname|bydns DATA=text
+
+The text returned for "redirect" is a list of new addresses. The text for FAIL
+is returned in the SMTP dialogue when the router is run as part of address
+verification. It is also logged. The text for DEFER and FREEZE is just logged.
+
+The data items in the "accept" return can be given in any order, and all are
+optional. If no transport is included in the "accept" return, the router's
+default transport is used. The host list and lookup type are needed only if the
+transport is an smtp transport that does not itself have a host list. The
+default lookup type is "byname". If the "data" field is set, its value is
+placed in the $address_data variable.
+
+
+The redirect router
+-------------------
+
+This router replaces forwardfile, appendfile, and the use of smartuser without
+a transport. It has two mutually exclusive options for specifying the data that
+it uses. If "file" is set, the data is taken from a file. Otherwise "data" must
+be set, and the data is the expanded value of that option.
+
+The data may be an alias list, possibly including special entries such as
+:fail:, or it may be a list of filtering instructions.
+
+If "file" is set, but the file does not exist or is empty, or its contents have
+no effect (entirely comments, or a filter that does nothing), the router
+declines. This also happens if the expansion of "file" is forced to fail. Any
+other expansion failure causes the router to defer.
+
+Ownership of the file is checked if check_local_user is set or if owners is
+set, unless check_owner is explicitly set false.
+
+Likewise, the group is checked if owngroups is set, or if check_local_user is
+set and a modemask not containing 020 is set, unless check_group is explicitly
+set false.
+
+If "data" is set, a forced expansion causes the router to decline. This also
+happens if "data" is an empty string or a string that causes nothing to be
+generated and no action to be taken.
+
+Because "data" is now used for traditional /etc/aliases lookups, an empty alias
+no longer gives an error. It behaves in the same way as :unknown: (which is
+still recognized, but ignored).
+
+. If no_repeat_use is set, the router is skipped if _any_ ancestor of the
+  current address was routed by this router. This pre-test happens before any
+  of the others. (Contrast the default loop avoidance logic, which skips a
+  router if an ancestor with the same local part was routed by the router.)
+
+. If include_directory is set, :include: files are constrained to this
+  directory.
+
+. When an address is redirected to a file or a pipe, $address_file or
+  $address_pipe (as appropriate) is set when expanding the value of
+  file_transport or directory_transport.
+
+. There are new options forbid_filter_readfile and forbid_filter_run to lock
+  out the use of the new ${readfile and ${run expansion items in filters.
+
+. If one_time is set, forbid_pipe, forbid_file, and forbid_filter_reply are
+  forced to be true, and headers_add and headers_remove are forbidden.
+
+
+Generic transport options
+-------------------------
+
+. All remote deliveries are now done in subprocesses running with specified
+  UIDs and GIDs. (Formerly, only remote parallel deliveries were done in
+  subprocesses.) As a result, user and group are now generic options that can
+  be used on all transports. The default for both local and remote transports
+  is to run as the Exim user and group. For remote transports, this should not
+  normally be changed, but if it is, the user or group should be able to access
+  the hints databases, though failure to open a hints database is always
+  ignored.
+
+  If it turns out that a transport user is in the never_users list, Exim now
+  defers delivery and writes to the panic log. (Previously it just ran the
+  delivery as "nobody".) Because subprocesses (usually running as "exim")
+  are now always used for remote deliveries, you should *not* include "exim" in
+  the never_users list.
+
+. initgroups is now also a generic transport option.
+
+. home_directory and current_directory are generic options on all transports,
+  though some transports (e.g. smtp) make no use of them. If they are unset,
+  values supplied by the router are used.
+
+. The message_size_limit option is now expanded, which makes it possible to
+  have different limits for different hosts, for example.
+
+
+Multiple (batch) deliveries in the appendfile, lmtp, and pipe transports
+------------------------------------------------------------------------
+
+The options controlling batch deliveries, including BSMTP, were a mess, and
+have been reworked.
+
+. The batch option has been removed from all three transports, and the bsmtp
+  and bsmtp_helo options have been removed from appendfile and pipe.
+
+. The batch_max option defaults to 1 in all three transports.
+
+. A new option called use_bsmtp has been added to appendfile and pipe. When
+  set, the message is delivered in BSMTP format. If you want to have a HELO
+  line at the start of the message, you can configure this by making use of the
+  message_prefix option. You must include the terminating newline.
+
+. A new option called batch_id has been added to all three transports.
+
+Batching is now achieved by setting batch_max to a value greater than 1. This
+is recommended for lmtp. When multiple addresses are routed to the same
+transport that has a batch_max value greater than one, the addresses are
+delivered in a batch, subject to certain conditions:
+
+. If any of the transport's options contain a reference to "$local_part", no
+  batching is possible.
+
+. If any of the transport's options contain a reference to "$domain", only
+  addresses with the same domain are batched.
+
+. If batch_id is set, it is expanded for each address, and only those addresses
+  with the same expanded value are batched.
+
+. Batched addresses must also have the same errors address (where to send
+  delivery errors), the same header additions and removals, the same user and
+  group for the transport, and if a host list is present, the first host must
+  be the same.
+
+
+The appendfile transport
+------------------------
+
+. The prefix and suffix options have been renamed message_prefix and
+  message_suffix to avoid confusion with address affixes. The default values,
+  which are suitable for mbox deliveries, now apply only if "file" is set and
+  use_bsmtp is not set. Otherwise, the default values for these options are
+  unset. They can, of course, always be overridden.
+
+. If "directory" is set (which means that "file" is not set), the check_string
+  and escape_string options now default unset.
+
+. The require_lockfile options has been abolished. If use_lockfile is set, a
+  lock file is always required.
+
+. The quota_filecount option is now expanded.
+
+. The create_file option now also applies when delivering into an individual
+  file in a given directory, as well as when appending to a single file. In the
+  case of maildir delivery, the restriction applies to the top directory of the
+  maildir folder.
+
+. There's a new option called directory_file which is expanded to form the
+  final leaf name of files when "directory" is set, but neither maildir nor
+  mailstore is set. The default is "q${base62:$tod_epoch}-$inode", which
+  reproduces the old fixed value. The variable $inode is available only when
+  expanding this new option.
+
+
+The pipe transport
+------------------
+
+. The prefix and suffix options have been renamed message_prefix and
+  message_suffix to avoid confusion with address affixes. The default values
+  that are suitable for vacation deliveries now apply only if use_bsmtp is not
+  set. Otherwise the default values for these options are unset. They can, of
+  course, always be overridden.
+
+
+The smtp transport
+------------------
+
+. The badly-named batch_max option is now called connection_max_messages.
+
+. If hosts_randomize is set, it now affects host lists that come from a router
+  as well as the contents of the "hosts" option, but only if the hosts were not
+  obtained from MX records. Typically, such lists come from the manualroute
+  router. This change means that the router can provide the same host list for
+  multiple addresses - causing them all to be sent to the transport at once.
+  Randomizing is then done each time the transport is called. (If you set
+  hosts_randomize on the router, the randomizing happens for each address.)
+
+. The way that smtp operates when there are multiple addresses to be sent to
+  the same host is now different. Previously, the transport was called many
+  times, with a maximum of max_rcpt addresses per call. Each call made a new
+  connection to the host. When remote_max_parallel = 1, all the addresses are
+  now passed to the transport at once. It makes a single TCP/IP call, but may
+  send multiple copies of the message, each with no more than max_rcpt
+  recipients.
+
+  When remote_max_parallel is greater than 1, a heuristic is used. The number
+  of addresses passed to a single call of the transport is limited to
+
+    (the total number of recipients) / (the value of remote_max_parallel)
+
+  so, for example, if there are 100 recipients and remote_max_parallel is 2, no
+  more than 50 are passed in one call, even if max_rcpt is 100. (The idea is
+  that the other 50 will be passed to another call running in parallel.)
+
+  There is an option of the smtp transport called connection_max_messages
+  which limits the number of messages, or copies of a message, that Exim sends
+  down a single TCP/IP connection. This applies both to this mechanism for
+  multiple copies of a single message, and the re-use of a TCP/IP connection
+  for sending other messages destined for the same host, after a delivery
+  delay. The default value is 500.
+
+. The "interface" option is now expanded. If the result is a forced failure or
+  an empty string, it is ignored. Otherwise, the result must be a list of IP
+  addresses. The first one of the correct type (IPv4 or IPv6) for the outgoing
+  connection is used. If there isn't one of the correct type, the option is
+  ignored.
+
+. At the start of running the transport, the value of $host is taken from the
+  first host in a multi-host list. However, just before the transport connects
+  to a host, the value is changed to refer to that particular host. (This
+  applies to $host_address as well.) This means that options such as helo_data
+  and the tls_options can be made host-specific.
+
+. The tls_verify_ciphers option has been renamed tls_require_ciphers, in order
+  to leave the word "verify" as something that refers to the verification of
+  certificates.
+
+. The resolution of hosts and fallback_hosts used to look up MX records. This
+  was some kind of ancient silliness that I recently noticed. These are
+  definitely hosts, not mail domains. Exim 4 just looks up address records.
+  As a consequence of this, the mx_domains option of the smtp transport is
+  removed.
+
+. The authenticate_hosts option has been renamed as hosts_try_auth. A new
+  option called hosts_require_auth has been added; if authentication fails for
+  one of these hosts, Exim does _not_ try to send unauthenticated. It defers
+  instead. The deferral error is detectable in the retry rules, so this can be
+  turned into a hard failure if required.
+
+
+The System Filter
+-----------------
+
+. The system filter options that were called message_filter_xxx have all been
+  renamed as system_filter_xxx.
+
+. The value of system_filter is expanded.
+
+. message_filter_directory_transport and message_filter_file_transport are now
+  both expanded before use. If the filter set up any file or pipe deliveries,
+  $address_file and $address_pipe are set as appropriate while doing the
+  expansions.
+
+. message_filter_directory2_transport has been removed. The effect of using
+  different directory-style transports can be achieved by specifying a suitable
+  expansion string to system_filter_directory_transport.
+
+. When a system filter added recipients to a message, Exim 3 added an
+  X-Envelope-To: header, listing the real recipients (up to 100). This has been
+  abolished because you can do this kind of thing using "headers_add" nowadays.
+
+. The "fail" command has been extended to allow for two different messages, one
+  for Exim's log and the other to be returned to the sender. The syntax is
+
+    fail "<<log message>>user message"
+
+  That is, if the first two characters of the message are "<<" the following
+  text, up to ">>", is written to the log, and the remainder is returned to the
+  user. If there is no log message, the user message is logged. The motivation
+  for this feature was to reduce the amount of text logged, while being able to
+  send quite long (maybe even multi-line) messages back to the sender.
+
+
+Changes to Lookups
+------------------
+
+. Oracle support is available. It works like the mysql and pgsql support,
+  except that there is no "database name" involved, and the "host name" field
+  is used for what is called "service name" in Oracle. This often looks like a
+  host name. Also, semicolons are not used at the end of an SQL query for
+  Oracle.
+
+. There's a new single-key lookup type called dsearch. It searches a directory
+  for a file whose name matches the key. The result of a successful search is
+  the key. One possible use of this could be for recognizing virtual domains.
+  If each domain is represented by a file whose name is the domain name, you
+  needn't make a separate list of the domains. You could test for them in an
+  ACL (see below), for example, by a line like this
+
+     accept domains = dsearch;/etc/virtual/domains
+
+. The format of LDAP output has been changed for cases where multiple
+  attributes are requested. The data for each attribute is now always quoted.
+  Within the quotes, the quote character, backslash, and newline are escaped
+  with backslashes and commas are used to separate multiple values for the
+  attribute. Thus, the string in quotes takes the same form as the output when
+  a single attribute is requested. If multiple entries are found, their data is
+  still separated by a newline.
+
+. There's a new expansion condition called ldapauth which exists so that the
+  LDAP authentication mechanism can be used for user authentication. It is
+  described under "string expansion" below.
+
+. Exim now supports ldaps:// URLs as well as ldap:// URLs. The former do LDAP
+  over TLS (i.e. encrypted) connections.
+
+. There is now support for the "whoson" mechanism for doing "POP-before-SMTP"
+  authentication. This is provided by new query-style lookup type called
+  "whoson", with queries that consist of IP addresses. For example, in an ACL
+  you can write
+
+    require condition = ${lookup whoson {$sender_host_address}{yes}{no}}
+
+
+Special items in domain and host lists
+--------------------------------------
+
+. In a domain list, the special item @ matches the primary host name, and the
+  special item @[] matches any local interface address enclosed in square
+  brackets (as in domain literal email addresses). The special item @mx_any
+  matches any domain that has an MX record pointing to the local host. The
+  special items @mx_primary and @mx_secondary are similar, except that the
+  first matches only when the primary MX is to the local host, and the second
+  only when the primary MX is not the local host, but a secondary MX is.
+
+. In a host list, the special item @ matches the primary host name, and the
+  special item @[] matches any local interface address (not in brackets).
+
+
+Access Control Lists (ACLs)
+---------------------------
+
+All the policy control options for incoming messages have been replaced by
+Access Control Lists (ACLs). These give more flexibility to the sysadmin, and
+allow the order of testing to be specified. For example, using an ACL, it is
+possible to specify "accept if authenticated, even if from an RBL host, but
+otherwise deny if from an RBL host", which is not possible in Exim 3.
+
+ACLs are defined in a new part of the configuration file, and given names.
+Which ones to run are controlled by a new set of options that are placed in the
+main part of the configuration.
+
+  acl_smtp_auth   specifies the ACL to run when AUTH is received
+  acl_smtp_data   specifies the ACL to run after a message has been received
+  acl_smtp_etrn   specifies the ACL to run when ETRN is received
+  acl_smtp_expn   specifies the ACL to run when EXPN is received
+  acl_smtp_rcpt   specifies the ACL to run when RCPT is received
+  acl_smtp_vrfy   specifies the ACL to run when VRFY is received
+
+The default actions vary. If acl_smtp_auth is not defined, AUTH is always
+accepted (and an attempt is made to authenticate the session). If acl_smtp_data
+is not defined, no checks are done after a message has been received, and it is
+always accepted at that point.
+
+However, if any of the others are not defined, the relevant SMTP command is
+rejected. In particular, this means that acl_smtp_rcpt must be defined in order
+to receive any messages over an SMTP connection. The default configuration file
+contains a suitable default for this.
+
+ACLs can be provided in line, or in files, or looked up from databases. One ACL
+can call another in a subroutine-like manner. String expansion is used, and
+which ACL to run can be varied according to sender host or any other criterion
+that a string expansion can test.
+
+This is not the place to give a full specification of ACLs, but here is a
+typical example for checking RCPT commands, taken from the default
+configuration. The tests are performed in order.
+
+acl_check_rcpt:
+  # Accept if source is local SMTP (i.e. not over TCP/IP - undefined host)
+  accept  hosts = :
+
+  # Deny if the local part contains @ or % or /
+  deny    local_parts   = ^.*[@%/]
+
+  # Accept mail to postmaster in any local domain, regardless of the source,
+  # and without verifying the sender.
+  accept  domains       = +local_domains
+          local_parts   = postmaster
+
+  # Deny unless the sender address can be verified.
+  require verify        = sender
+
+  # Accept if the address is in a local domain, but only if the recipient can
+  # be verified. Otherwise deny. The "endpass" line is the border between
+  # passing on to the next ACL statement (if tests above it fail) or denying
+  # access (if tests below it fail).
+  accept  domains       = +local_domains
+          endpass
+          message       = unknown user
+          verify        = recipient
+
+  # We get here only for non-local domains. Accept if the message arrived over
+  # an authenticated connection, from any host. These messages are usually from
+  # MUAs, so recipient verification is omitted.
+  accept  authenticated = *
+
+  # Reaching the end of the ACL causes a "deny", but we might as well give
+  # an explicit message.
+  deny    message       = relay not permitted
+
+The following options have been abolished as a consequence of the introduction
+of ACLs:
+
+auth_hosts, auth_over_tls_hosts, headers_checks_fail, headers_check_syntax,
+headers_sender_verify, headers_sender_verify_errmsg, host_accept_relay,
+host_auth_accept_relay, host_reject_recipients, prohibition_message,
+rbl_domains, rbl_hosts, rbl_log_headers, rbl_log_rcpt_count,
+rbl_reject_recipients, rbl_warn_header, receiver_try_verify, receiver_verify,
+receiver_verify_addresses, receiver_verify_hosts, receiver_verify_senders,
+recipients_reject_except, recipients_reject_except_senders, relay_domains,
+relay_domains_include_local_mx, relay_match_host_or_sender,
+sender_address_relay, sender_address_relay_hosts, sender_reject,
+sender_reject_recipients, sender_try_verify, sender_verify,
+sender_verify_batch, sender_verify_hosts, sender_verify_fixup,
+sender_verify_hosts_callback, sender_verify_callback_domains,
+sender_verify_callback_timeout, sender_verify_max_retry_rate,
+sender_verify_reject, smtp_etrn_hosts, smtp_expn_hosts. smtp_verify, tls_hosts.
+
+The variable $prohibition_reason has been abolished.
+
+The host_reject option has been retained, but with its name changed to
+host_reject_connection, to emphasize that it causes a rejection at connection
+time. I've left it available just in case it is needed - but its use is not
+recommended in normal circumstances.
+
+
+Other Incoming SMTP Session Controls
+------------------------------------
+
+. The option smtp_accept_max_per_connection (default 1000) limits the number of
+  messages accepted over a single SMTP connection. This is a safety catch in
+  case some sender goes mad (incidents of this kind have been seen). After the
+  limit is reached, a 421 response is given to MAIL commands.
+
+. Some sites find it helpful to be able to limit the rate at which certain
+  hosts can send them messages, and the rate at which an individual message can
+  specify recipients. There are now options for controlling these two different
+  rates.
+
+  Rate limiting applies only to those hosts that match smtp_ratelimit_hosts,
+  whose value is a host list. When a host matches, one or both of the options
+  smtp_ratelimit_mail and smtp_ratelimit_rcpt may be set. They apply to the
+  rate of acceptance of MAIL and RCPT commands in a single SMTP session,
+  respectively.
+
+  The value of each option is a set of four comma-separated values:
+
+    1. A threshold, before which there is no rate limiting.
+    2. An initial time delay. Unlike other times in Exim, fractions are allowed
+       here.
+    3. A factor by which to increase the delay each time.
+    4. A maximum value for the delay.
+
+  For example, these settings have been used successfully at the site which
+  first suggested this feature, for controlling mail from their customers:
+
+    smtp_ratelimit_mail = 2, 0.5s, 1.05, 4m
+    smtp_ratelimit_rcpt = 4, 0.25s, 1.015, 4m
+
+. The default value for smtp_connect_backlog has been increased to 20.
+
+. The SMTP protocol specification requires the client to wait for a response
+  from the server at certain points in the dialogue. (Without PIPELINING these
+  are after every command; with PIPELINING they are fewer, but still exist.)
+  Some spamming sites send out a complete set of SMTP commands without waiting
+  for any response. Exim 4 protects against this by rejecting messages if the
+  client has sent further input when it should not have. The error response
+  "554 SMTP synchronization error" is sent, and the connection is dropped.
+
+  This check is controlled by smtp_enforce_sync, which is true by default.
+
+. helo_strict_syntax has been abolished. The default is now to enforce strict
+  domain syntax for HELO/EHLO arguments. You can use helo_accept_junk_hosts if
+  you want to avoid this.
+
+. There's a new option called helo_lookup_domains. If the domain given in a
+  HELO or EHLO command matches this list, a reverse lookup is done in order to
+  establish the host's true name. The default setting is
+
+    helo_lookup_domains = @ : @[]
+
+  That is, a lookup is forced if the client host gives the server's name or
+  [one of its IP addresses] in HELO or EHLO. (In Exim 3 this happened
+  automatically and was not configurable.)
+
+. The value of the global message_size_limit option is now expanded. For
+  locally submitted messages this happens at the start of message reception.
+  For messages from remote hosts, the expansion is done just after the host
+  connects, so that the value can depend on the host.
+
+
+Handling of Resent- Fields
+--------------------------
+
+RFC 2822 makes it clear that Resent- fields are purely informational. Exim used
+to make use of Resent-Reply-To: which does not actually exist, and it also used
+to use the last set of resent- fields for all the address fields it recognized.
+
+In Exim 4, resent- headers are dealt with as follows:
+
+. A Resent-From: header that just contains the login id as the address is
+  automatically rewritten in the same way as From: is (using qualify domain,
+  and user name from the passwd data).
+
+. If there's a rewrite rule for a header, it is also applied to resent- headers
+  of the same type. For example, a rule that rewrites From: headers also
+  rewrites Resent-From: headers.
+
+. For local messages, if Sender: is being removed on input, Resent-Sender: is
+  also removed.
+
+. If there are any resent- headers but no Resent-Date: or Resent-From: they are
+  added.
+
+. The logic for adding Sender: is now duplicated for Resent-Sender.
+
+. If there's no Resent-Message-Id: one is created, and it is the
+  Resent-Message-Id: which is included in the log line.
+
+
+Authentication
+--------------
+
+. The auth_hosts option has been abolished; this functionality is now
+  controlled by ACLs.
+
+. The auth_always_advertise option has been abolished because it depended on
+  auth_hosts and host_auth_accept_relay, both of which are no more. In its
+  place there is a new option called auth_advertise_hosts, whose default value
+  is *, meaning "advertise AUTH to all".
+
+. The value of server_setid is now used when logging failed authentication
+  attempts.
+
+. The -oMaa option allows trusted users to set the value of
+  $sender_host_authenticated (the authenticator name). This is normally used in
+  conjunction with -oMa.
+
+
+Encryption
+----------
+
+. Because tls_hosts is no more, tls_advertise_hosts is now the only means of
+  controlling the advertisement of STARTTLS (previously, tls_hosts overrode).
+
+. The global option tls_verify_ciphers has been abolished. There are now
+  facilities for checking which cipher is in use in ACLs.
+
+. There's a new option called tls_try_verify_hosts. Like tls_verify_hosts, this
+  causes the server to request a certificate from a client, and it verifies the
+  certificate that it receives. However, unlike tls_verify_hosts, Exim
+  continues with the SMTP connection (encrypted) if a client certificate is not
+  received, or if the certificate does not verify. This state can be detected
+  in an ACL, which makes it possible to implement policies such as "accept for
+  relay only if a verified certificate has been received but accept for local
+  delivery if encrypted, even without a verified certificate".
+
+  A match in tls_verify_hosts overrides tls_try_verify_hosts.
+
+
+The Daemon
+----------
+
+. local_interfaces can now specify a port number with each address, thus
+  allowing a single Exim daemon to listen on multiple ports. The format of each
+  address is either [aaaa]:ppp or aaaa.ppp where aaaa is an IP address and ppp
+  is a port number. For example:
+
+    local_interfaces = 192.168.3.4.25 : 192.168.3.4.26
+
+  If an address is listed without a port, the setting of daemon_smtp_port, or
+  the value of the -oX option, is the default.
+
+. The -oX option can now override local_interfaces. That is, it can supply IP
+  addresses as well as just a port. It is interpreted in this way if its value
+  contains any of the characters . : or []. For example:
+
+  exim -bd -oX 10.9.8.7:10.11.12.13.2525
+
+  The format of the string is identical to the format recognized by the
+  local_interfaces option.
+
+. The way the daemon wrote PID files was overly complicated and messy. It no
+  longer tries to be clever. A PID file is written if, and only if, -bd is used
+  and -oX is _not_ used. In other words, only if the daemon is started with its
+  standard options. There is only one PID file. If pid_file_path is unset, it
+  is exim-daemon.pid in Exim's spool directory. Otherwise the value of
+  pid_file_path is used. For backwards compatibility, "%s" in this value is
+  replaced by an empty string.
+
+
+Logging
+-------
+
+The log_level option and all the various independent logging control options
+have been abolished. In their place there is a single option called
+log_selector. It takes a string argument composed of names preceded by + or -
+characters. These turn on or off the logging of different things. For example:
+
+  log_selector = +arguments -retry_defer
+
+The optional logging items (defaults marked *) are:
+
+  address_rewrite             address rewriting
+  all_parents                 all parents in => lines
+  arguments                   exim arguments
+ *connection_reject           connection rejections
+ *delay_delivery              immediate delivery delayed (message queued)
+  delivery_size               add S=nnn to delivery lines
+ *dnslist_defer               defers of DNS list (aka RBL) lookups
+  incoming_interface          incoming interface on <= lines
+  incoming_port               incoming port on <= lines
+ *lost_incoming_connection    as it says (includes timeouts)
+ *queue_run                   start and end queue runs
+  received_sender             sender on <= lines
+  received_recipients         recipients on <= lines
+ *retry_defer                 "retry time not reached"
+  sender_on_delivery          add sender to => lines
+ *size_reject                 rejection because too big
+ *skip_delivery               "message is frozen"
+  smtp_confirmation           SMTP confirmation on <= lines
+  smtp_connection             SMTP connections
+  smtp_protocol_error         SMTP protocol errors
+  smtp_syntax_error           SMTP syntax errors
+  subject                     contents of Subject: on <= lines
+ *tls_cipher                  TLS cipher on <= lines
+  tls_peerdn                  TLS peer DN on <= lines
+
+  all                         all of the above
+
+"retry time not reached" is always omitted from individual message logs after
+the first delivery attempt.
+
+The log line "error message sent to" has been abolished, because the R= item on
+the incoming message line gives the relationship between the original message
+and the bounce.
+
+The logging options that have been abolished are: log_all_parents,
+log_arguments, log_incoming_port, log_interface, log_ip_options,
+log_level, log_queue_run_level, log_received_sender, log_received_recipients,
+log_rewrites, log_sender_on_delivery, log_smtp_confirmation,
+log_smtp_connections, log_smtp_syntax_errors, log_subject, tls_log_cipher,
+tls_log_peerdn.
+
+
+Debugging
+---------
+
+The debug_level option has been removed. The -dm option has been removed. The
+-df option has also be removed, along with its related build-time option
+STDERR_FILE. (To debug inetd usage, an auxiliary script should be used.)
+
+The -d option has been reworked. It no longer takes a debug level number
+argument, but instead takes a list of debugging names, each preceded by + or -
+to turn on or off individual sets of debugging messages.
+
+. The -v option now shows just the SMTP dialog and any log lines.
+
+. -d with no argument gives a lot of standard debugging data. This is in effect
+  the equivalent of the old -d9, the thing you ask people to set for an initial
+  debugging test.
+
+. -d+x      adds debugging option x to the default set
+  -d-x      removes debugging option x from the default set
+  -d-all+x  leaves only debugging option x
+
+The available debugging names are:
+
+  acl            ACL interpretation
+  auth           authenticators
+  deliver        general delivery logic
+  dns            DNS lookups (see also resolver)
+  dnsbl          DNS black list (aka RBL) code
+  exec           arguments for execv() calls
+  filter         filter handling
+  hints_lookup   hints data lookups
+  host_lookup    all types of name->IP address handling
+  ident          ident lookup
+  interface      lists of local interfaces
+  lists          matching things in lists
+  load           system load checks
+  lookup         general lookup code and all lookups
+  memory         memory handling (replaces the old -dm)
+  process_info   setting info for the process log
+  queue_run      queue runs
+  receive        general message reception logic
+  resolver       turn on the DNS resolver's debugging output; goes to stdout
+  retry          retry handling
+  rewrite        rewriting
+  route          address routing
+  tls            TLS logic
+  transport      transports
+  uid            changes of uid/gid and looking up uid/gid
+  verify         address verification logic
+
+  all            all of the above, and also -v
+
+The default (-d with no argument) includes all of the above, plus -v, with the
+exception of filter, interface, load, memory, and resolver. Some debugging
+output always happens unconditionally whenever any debugging is selected. This
+includes some initial output and every log line.
+
+-d without any value was previously allowed for non-admin users because it used
+to be synonymous with -v. In Exim 4, non-admin users may use -v, but not -d.
+
+If the debug_print option is set in any driver, it produces output whenever any
+debugging is selected, or if -v is used.
+
+
+Local Scan Function
+-------------------
+
+For customized message scanning, you can now supply a C function that is linked
+into the Exim binary. The function is called local_scan(), and it is called
+when Exim has received a message, but has not yet sent a final
+acknowledgement to the sender. This applies to all messages, whether local or
+remote, SMTP or not.
+
+From within your function you can inspect the message, change the recipients,
+add or remove headers, and tell Exim whether to accept or reject the message.
+
+The manual contains the specification of the API for this function.
+
+
+String Expansion
+----------------
+
+. The lookup feature that allowed for subkeys using the syntax
+
+    ${lookup {key:subkey} type {data...
+
+  has been abolished (a) because the effect can be achieved using ${extract,
+  and (b) because in non-lsearch lookups, a colon can be a valid character in a
+  key.
+
+. When a string key is used in a ${extract expansion item, it is now handled
+  case-insensitively.
+
+. A new expansion variable called $tod_epoch gives the time as a single decimal
+  number representing the number of seconds from the start of the Unix epoch.
+
+. There's a new expansion operator that can turn numbers into base 62, for
+  example, ${base62:$tod_epoch}.
+
+. ${extract{number} now recognizes a negative number as a request to count
+  fields from the right.
+
+. There's a new expansion feature for reading files:
+
+    ${readfile{/some/file}{eolstring}}
+
+  The contents of the file replace the item. If {eolstring} is present (it's
+  optional) any newlines in the file are replaced by that string.
+
+. There's a new expansion feature for running commands:
+
+    ${run{command args}{yes}{no}}
+
+  Like all the other conditional items, the {yes} and {no} strings are
+  optional. Omitting both is equivalent to {$value}. The standard output of the
+  command is put into $value if the command succeeds (returns a zero code). The
+  value of the code itself is put into $runrc, and this remains set afterwards,
+  so in a filter file you can do things like
+
+    if "${run{x y z}{}}$runrc" is 1 then ...
+    elsif $runrc is 2 then ...
+
+  As in other command executions from Exim, a shell is not used by default.
+  If you want a shell, you must explicitly code it.
+
+. The redirect router has options for forbidding ${readfile and ${run in
+  filters.
+
+. A feature is provided to suppress expansion of part of a string. Any
+  characters between two occurrences of \N are copied to the output string
+  verbatim. This is particularly useful for protecting regular expressions from
+  unwanted expansion effects. For example:
+
+    queue_smtp_domains = ! \N^ten-\d+\.testing\.com$\N
+
+  Without \N the \ and $ characters in the regex would have to be escaped.
+
+. Radius authentication is supported in a similar way to PAM. You must set
+  RADIUS_CONFIG_FILE in Local/Makefile to specify the location of the Radius
+  client configuration file. Then you can use expansions such as
+
+    server_condition = ${if radius{arguments}{yes}{no}}
+
+. User authentication can now also be done by attempting to bind to an LDAP
+  server. The syntax is again similar to PAM and Radius.
+
+    server_condition = ${if ldapauth{ldap query}{yes}{no}}
+
+  A user and password are required to be supplied with the query. No actual
+  data is looked up; Exim just does a bind to the LDAP server and sets the
+  condition according to the result. Here's an example of an SMTP
+  authenticator:
+
+    login:
+      driver = plaintext
+      public_name = LOGIN
+      server_prompts = "Username:: : Password::"
+      server_condition = ${if ldapauth \
+        {user="uid=${quote_ldap:$1},ou=people,o=example.org" pass="$2" \
+        ldap://ldap.example.org/}{yes}{no}}
+      server_set_id = uid=$1,ou=people,o=example.org
+
+
+
+Security
+--------
+
+Exim 3 could be run in a variety of ways as far as security was concerned. This
+has all been simplified in Exim 4. The security-conscious might like to know
+that it no longer makes any use of the seteuid() function.
+
+. A UID and GID are required to be specified when Exim is compiled. They can be
+  now specified by name as well as by number, so the relevant options are now
+  called EXIM_USER and EXIM_GROUP. If you really feel you have to run Exim as
+  root, you can specify root here, but it is not recommended.
+
+. The "security" option has been abolished. Exim always releases its root
+  privilege when it can. In a conventional configuration, that means when it is
+  receiving a message, when it is delivering a message, when it is running a
+  queryprogram router, and when it is obeying users' filter files (and system
+  filters if it has been given a user for that purpose).
+
+. One important change is that Exim 4 runs as root while routing addresses for
+  delivery. Exim 3 used seteuid() to give up privilege temporarily while
+  routing. Apart from the unliked use of seteuid(), this sometimes gave rise to
+  permissions problems on configuration files.
+
+. However, Exim still runs as the Exim user while receiving messages, and
+  therefore while using the routing logic for verifying at SMTP time.
+
+. There is a new option called deliver_drop_privilege. If this is set, Exim
+  gives up its privilege right at the start of a delivery process, and runs the
+  entire delivery as the Exim user. This is the same action that used to be
+  requested by setting security=unprivileged.
+
+
+Hints Databases
+---------------
+
+. A single "misc" hints database is now used for ETRN and host serialization.
+  There have been appropriate consequential changes to the utilities for
+  managing the hints.
+
+. The exim_tidydb -f option has been abolished. A full tidy is now always done
+  (it hasn't proved to be very expensive).
+
+
+The run time Configuration File
+------------------------------
+
+. The format of the configuration file has changed. Instead of using "end" to
+  terminate sections, it now uses "begin <name>" to start sections. This means
+  that the sections, apart from the first, may appear in any order.
+
+. You can now include other files inside Exim run time configuration files, by
+  using this syntax:
+
+  .include <file name>
+
+. Quotes round the file name are optional. Includes may be nested to any depth,
+  but remember that Exim reads its configuration file often. The processing of
+  .include happens early, at a physical line level, so, like comment lines, it
+  can be used in the middle of an options setting, for example:
+
+  hosts_lookup = a.b.c \
+                 .include /some/file
+
+  Include processing happens _before_ macro processing. Its effect is simply to
+  process the lines of the file as if they occurred inline where the .include
+  appears.
+
+. A macro at the start of a configuration line can now turn the line into an
+  empty line or a comment line. This applies to _logical_ input lines, that is,
+  after any concatenations have been done.
+
+
+Format of spool files
+---------------------
+
+. -local_scan is used in spool files to record the value of $local_scan_data,
+  the string returned from the locally-provided local_scan() function.
+
+
+Renamed Options
+---------------
+
+Some options have been renamed, to make their function clearer, or for
+consistency.
+
+. receiver_unqualified_hosts has been renamed as recipient_unqualified_hosts.
+  I'm going to use "recipient" everywhere in future.
+
+. helo_verify has become helo_verify_hosts.
+
+. remote_sort has become remote_sort_domains.
+
+. In the appendfile and pipe transports, "prefix" and "suffix" have become
+  "message_prefix" and "message_suffix". In the generic router options,
+  "prefix" and "suffix" have become "local_part_prefix" and "local_part_suffix".
+
+
+Miscellaneous
+-------------
+
+. ETRN serialization now uses a double fork, so that an Exim process (detached
+  from the original input process) can wait for the command to finish. This
+  means that it works whatever command ETRN causes to run. (Previously it
+  worked only if ETRN ran "exim -Rxxx".)
+
+. For incoming messages, the server's port number is preserved, and is
+  available in $interface_port. The privileged option -oMi can be used to
+  set this value.
+
+. The -Mmd option (to mark addresses delivered) now operates in a
+  case-sensitive manner.
+
+. Checks for duplicate deliveries are now case-sensitive in the local part.
+
+. The number of situations where Exim panics has been reduced. For example,
+  expansion failures for the "domains" or "local_parts" options in a router now
+  cause deferral instead of a panic.
+
+. EXPN no longer attempts to distinguish local and remote addresses (but you
+  can cause it to be rejected for certain arguments in the ACL).
+
+. accept_timeout has been renamed as receive_timeout, to match
+  smtp_receive_timeout.
+
+. The ability to check an ident value as part of an item in a host list has
+  been removed.
+
+. The reject log shows a message's headers only if the rejection happens after
+  the SMTP DATA command (because they aren't available for earlier checks). The
+  sender, and up to five recipients are listed in Envelope-from: and
+  Envelope-to: header lines. After the headers, a line of separator characters
+  is output. Separators are no longer used for other reject log entries.
+
+. Because header checks are now done as part of ACLs, they now apply only to
+  SMTP input.
+
+. The port number on SMTP connections is now logged in the format [aaaa]:ppp
+  where aaaa is an IP address and ppp is a port, instead of in the format
+  [aaaa.ppp] because the former format causes some software to complain about
+  bad IP addresses.
+
+. The -oMa and -oMi options can now use the [aaaa]:ppp notation to set a port
+  number, but they still also recognize the aaaa.ppp notation.
+
+. The build-time option HAVE_AUTH is abolished. Exim automatically includes
+  authentication code if any authenticators are configured.
+
+. The nobody_user and nobody_group options have been abolished.
+
+. The $message_precedence variable has been abolished. The value is now
+  available as $h_precedence:.
+
+. There's a new utility script called exim_checkaccess which packages up a call
+  to Exim with the -bh option, for access control checking. The syntax is
+
+    exim_checkaccess <IP address> <email address> [exim options]
+
+  It runs "exim -bh <IP address>", does the SMTP dialogue, tests the result and
+  outputs either "accepted" or "Rejected" and the SMTP response to the RCPT TO
+  command. The sender is <> by default, but can be changed by the use of the
+  -f option.
+
+. The default state of Exim is now to forbid domain literals. For this reason,
+  the option that changes this has been renamed as allow_domain_literals.
+
+. The dns_check_names boolean option has been abolished. Checking is now turned
+  off by unsetting dns_check_names_pattern.
+
+. The errors_address and freeze_tell_mailmaster options have been abolished. In
+  their place there is a new option called freeze_tell, which can be set to a
+  list of addresses. A message is sent to these addresses whenever a message is
+  frozen - with the exception of failed bounce messages (this is not changed).
+
+. The message_size_limit_count_recipients option has been abolished on the
+  grounds that it was a failed experiment.
+
+. The very-special-purpose X rewrite flag has been abolished. The facility it
+  provided can now be done using the features of ACLs.
+
+. The timestamps_utc option has been abolished. The facility is now provided by
+  setting timezone = utc.
+
+. The value of remote_max_parallel now defaults to 2.
+
+. ignore_errmsg_errors has been abolished. The effect can be achieved by
+  setting ignore_bounce_errors_after = 0s. This option has been renamed from
+  ignore_errmsg_errors_after to make its function clearer. The default value
+  for ignore_bounce_errors_after is now 10w (10 weeks - i.e. likely to be
+  longer than any other timeouts, thereby disabling the facility).
+
+. The default for message_size_limit is now 50M as a guard against DoS attacks.
+
+. The -qi option does only initial (first time) deliveries. This can be helpful
+  if you are injecting message onto the queue using -odq and want a queue
+  runner just to process new messages. You can also use -qqi if you want.
+
+. Rewriting and retry patterns are now anything that can be single address list
+  items. They are processed by the same code, and are therefore expanded before
+  the matching takes place. Regular expressions must be suitably quoted. These
+  patterns may now be enclosed in double quotes so that white space may be
+  included. Normal quote processing applies.
+
+. Some scripts were built in the util directory, which was a mistake, because
+  they might be different for different platforms. Everything that is built is
+  now built in the build directory. The util directory just contains a couple
+  of scripts that are not modified at build time.
+
+. The installation script now installs the Exim binary as exim-v.vv-bb (where
+  v.vv is the version number and bb is the build number), and points a symbolic
+  link called "exim" to this binary. It does this in an atomic way so that
+  there is no time when "exim" is non-existent. The script is clever enough to
+  cope with an existing non-symbolic-link binary, converting it to the new
+  scheme automatically (and atomically).
+
+. When installing utilities, Exim now uses cp instead of mv to add .O to the
+  old ones, in order to preserve the permissions.
+
+. If the installation script is installing the default configuration, and
+  /etc/aliases does not exist, the script installs a default version. This does
+  not actually contain any aliases, but it does contain comments about ones
+  that should be created. A warning is output to the user.
+
+. A delay warning message is not sent if all the addresses in a message get a
+  "retry time not reached" error. Exim waits until a delivery is actually
+  attempted, so as to be able to give a more informative message.
+
+. The existence of the three options deliver_load_max, queue_only_load, and
+  deliver_queue_load_max was confusing, because their function overlapped. The
+  first of them has been abolished. We are left with
+
+    queue_only_load         no immediate delivery if load is high when
+                            message arrives
+    deliver_queue_load_max  no queued delivery if load is too high
+
+. The ability to edit message bodies (-Meb and the Eximon menu item) has been
+  removed, on the grounds that it is bad practice to do this.
+
+. Eximstats is now Steve Campbell's patched version, which displays sizes in K
+  and M and G, and can optionally generate HTML.
+
+. If bounce_sender_authentication is set to an email address, this address is
+  used in an AUTH option of the MAIL command when sending bounce messages, if
+  authentication is being used. For example, if you set
+
+    bounce_sender_authentication = mailer-daemon@your.domain
+
+  a bounce message will be sent over an authenticated connection using
+
+    MAIL FROM:<> AUTH=mailer-daemon@your.domain
+
+. untrusted_set_sender has changed from a boolean to an address pattern. It
+  permits untrusted users to set sender addresses that match the pattern. Like
+  all address patterns, it is expanded. The identity of the user is in
+  $sender_ident, so you can, for example, restrict users to setting senders
+  that start with their login ids by setting
+
+    untrusted_set_sender = ^$sender_ident-
+
+  The effect of the previous boolean can be achieved by setting the value to *.
+  This option applies to all forms of local input.
+
+. The always_bcc option has been abolished. If an incoming message has no To:
+  or Cc: headers, Exim now always adds an empty Bcc: line. This makes the
+  message valid for RFC 822 (sic). In time, this can be removed, because RFC
+  2822 does not require there to be a recipient header.
+
+. ACTION_OUTPUT=no is now the default in the Exim monitor.
+
+. dns_ipv4_lookup has changed from a boolean into a domain list, and it now
+  applies only to those domains. Setting this option does not stop Exim from
+  making IPv6 calls: if an MX lookup returns AAAA records, Exim will use them.
+  What it does is to stop Exim looking for AAAA records explicitly.
+
+. The -G option is ignored (another Sendmail thing).
+
+. If no_bounce_return_message is set, the original message is not included in
+  bounce messages. If you want to include additional information in the bounce
+  message itself, you can use the existing errmsg_file and errmsg_text
+  facilities.
+
+. -bdf runs the daemon in the foreground (i.e. not detached from the terminal),
+  even when no debugging is requested.
+
+. Options for changing Exim's behaviour on receiving IPv4 options have been
+  abolished. Exim now always refuses calls that set these options, and logs the
+  incident. The abolished options are kill_ip_options, log_ip_options, and
+  refuse_ip_options.
+
+. The pattern for each errors_copy entry is now matched as an item in an
+  address list.
+
+. A number of options and variables that used the word "errmsg" have been
+  changed to use "bounce" instead, because it seems that "bounce message" is
+  now a reasonably well-understood term. I used it in the book and am now using
+  it in the manual; it's a lot less cumbersome than "delivery error
+  notification message". The changes are:
+
+  $errmsg_recipient          => $bounce_recipient
+  errmsg_file                => bounce_message_file
+  errmsg_text                => bounce_message_text
+  ignore_errmsg_errors_after => ignore_bounce_errors_after
+
+  For consistency, warnmsg_file has been changed to warn_message_file. However,
+  the two variables $warnmsg_delay and $warnmsg_recipients are unchanged.
+
+  The hide_child_in_errmsg option has not changed, because it applies to both
+  bounce and delay warning messages.
+
+. smtp_accept_max_per_host is now an expanded string, so it can be varied on
+  a per-host basis. However, because this test happens in the daemon before it
+  forks, the expansion should be kept as simple as possible (e.g. just inline
+  tests of $sender_host_address).
+
+. The retry rules can now recognize the error "auth_failed", which happens when
+  authentication is required, but cannot be done.
+
+. There's a new option called local_sender_retain which can be set if
+  no_local_from_check is set. It causes Sender: headers to be retained in
+  locally-submitted messages.
+
+. The -dropcr command line option now turns CRLF into LF, and leaves isolated
+  CRs alone. Previously it simply dropped _all_ CR characters. There is now
+  also a drop_cr main option which, if turned on, assumes -dropcr for all
+  non-SMTP input.
+
+
+Removal of Obsolete Things
+--------------------------
+
+. The obsolete values "fail_soft" and "fail_hard" for the "self" option have
+  been removed.
+
+. The obsolete "log" command has been removed from the filter language.
+
+. "service" was an obsolete synonym for "port" when specifying IP port numbers.
+  It has been removed.
+
+. The obsolete option collapse_source_routes has been removed. It has done
+  nothing since release 3.10.
+
+. The obsolete from_hack option in appendfile and pipe transports has been
+  removed.
+
+. The obsolete ipv4_address_lookup has been abolished (dns_ipv4_lookup has been
+  a synonym for some time, but it's changed - see above).
+
+. The obsolete generic transport options add_headers and remove_headers have
+  been abolished. The new names, headers_add and headers_remove, have been
+  available for some time.
+
+Philip Hazel
+February 2002