Fix build with DISABLE_EVENT (proper spelling)
[exim.git] / doc / doc-txt / Exim4.upgrade
1 Upgrading Exim from Release 3.33 to 4.xx
2 ----------------------------------------
3
4 Exim 4.00 represents the largest upheaval in Exim's history. There are a lot of
5 changes to the way some parts of Exim work, and a lot of incompatible changes
6 to the run time configuration file.
7
8 This document is in two parts. The first part contains instructions and
9 suggestions for how you might go about performing the upgrade. The second part
10 is a brief list of all the changes that have taken place. For full details of
11 all the new features, please consult the current version of the reference
12 manual.
13
14
15 HOW TO UPGRADE YOUR EXIM
16 ------------------------
17
18 When you compile Exim 4, a Perl script called convert4r4 is built in the build
19 directory. It is not installed by the install script, because it is likely that
20 you will run it only once.
21
22 This script is provided to assist in updating Exim configuration files. It
23 reads an Exim 3 configuration file on the standard input, and writes a modified
24 file on the standard output. It also writes comments about what it has done to
25 the standard error file. It assumes that the input is a valid Exim 3
26 configuration file. A typical call to the conversion script might be
27
28   ./convert4r4  </etc/exim/configure  >/etc/exim/configure.new
29
30 The output file MUST be checked and tested before trying to use it on a live
31 system. The conversion script is just an aid which does a lot of the "grunt
32 work". It does not guarantee to produce an Exim 4 configuration that behaves
33 exactly the same as the Exim 3 configuration it reads.
34
35 Each option change in the new file is preceded by an identifying comment. In
36 fact, the conversion script tends to make quite a mess of your configuration,
37 and you should expect to go through it afterwards and tidy it up by hand.
38
39 Unless you are running a very straightforward configuration, the automatic
40 conversion is likely to generate a non-optimal configuration. You should not
41 only check it thoroughly, but also run as many tests as you can, to ensure that
42 it is working as you expect. In particular, you should test address routing,
43 using -bt and -bv, and the policy controls, using -bh. If possible, you should
44 also do some live tests (i.e. send and receive some messages) before putting
45 Exim 4 into service.
46
47 If you have a very complicated configuration, it is possible that convert4r4
48 will break it in some situations, which is why thorough testing is strongly
49 recommended.
50
51                    *********************************
52                    ***** You Have Been Warned ******
53                    *********************************
54
55
56 HOW TO MOVE FROM AN EXIM 3 RELEASE TO AN EXIM 4 RELEASE
57 -------------------------------------------------------
58
59 One way of upgrading to Exim 4 from a version 3 release is as follows:
60
61 1. Suppose your run time configuration file is called /usr/exim/configure, and
62    you want to continue with this name after upgrading. The first thing to do
63    is to make another copy of this file called, say, /usr/exim/configure.r3.
64
65 2. Rebuild your existing Exim to use the copy of the run time configuration
66    file instead of the standard file. Install this version of Exim and HUP your
67    daemon. You can check on the name of the configuration file by running
68
69      exim -bP configure_file
70
71    Ensure that everything is running smoothly. You now have something you can
72    fall back to. IMPORTANT: when you do this re-install, you should also
73    re-install the utilities because four of them (exicyclog, eximon, exinext,
74    and exiwhat) also refer to the configuration file.
75
76 3. Build the new release, configured to use the standard configuration file.
77
78 4. Use the convert4r4 utility to upgrade your configuration file for the new
79    release. After running the conversion utility, check the file by hand, and
80    tidy it up.
81
82 5. Test, test, test! And test some more!
83
84 6. You can run complete tests, including actual deliveries, from an uninstalled
85    binary, but you have to tell it where it is, so that any re-executions can
86    be done. You can do this by temporarily inserting a setting such as
87
88    exim_path = /source/exim/exim-4.00/build-SunOS5-5.8-sparc/exim
89
90    into the run time configuration. If you want to, you can also insert
91    settings for spool_directory and log_file_path to divert those away from
92    their normal places. Remember to remove these temporary settings when you
93    eventually install the binary for real.
94
95 7. The new installation script installs the new release as exim-4.00-1, and
96    set a symbolic link called "exim" to point to it. The old version of Exim
97    will be renamed to something like exim-3.33-1.
98
99 8. You can now easily change between the new and old releases simply by moving
100    the symbolic link and HUPping your daemon. The format of message files on
101    Exim's spool has _not_ changed, so there should be no problem in changing
102    between releases while there are messages on the queue.
103
104 9. HOWEVER: If you do change back and forth between releases, you must also
105    change the utilities exicyclog, eximon, exinext, and exiwhat if you are
106    going to use them. Installing Exim 4 will have left the old versions with a
107    .O suffix. It might be helpful to rename these so that you don't lose them.
108
109
110 WHAT HAS NOT CHANGED IN EXIM 4.00
111 ---------------------------------
112
113 The basic overall philosophy, design, and process structure has not changed.
114 The format of spool files is the same. The transports have had only minor
115 modifications. The command line options remain the same, with a couple of
116 additions.
117
118 The general run time configuration approach has not changed, but the actual
119 details of the configuration file are different.
120
121 The Exim monitor has not changed, and there have been only very minor changes
122 to other Exim utilities.
123
124
125 WHAT HAS CHANGED IN EXIM 4.00
126 -----------------------------
127
128 The rest of this document lists the very many changes that have taken place.
129 I'm going to give only brief details here, because this part of the document is
130 intended as a way of alerting you to areas of difference. The reference manual
131 describes how the new features work in detail.
132
133
134 Named domain, host, address, and local part lists
135 -------------------------------------------------
136
137 A new feature makes it possible to give names to lists of domains, hosts,
138 addresses, and local parts. The syntax used is
139
140   domainlist    <name> = <a domain list>
141   hostlist      <name> = <a host list>
142   addresslist   <name> = <an address list>
143   localpartlist <name> = <a list of local parts>
144
145 For example:
146
147   domainlist  local_domains = *.my.domain
148   addresslist bad_senders = cdb;/etc/badsenders
149
150 These lists are referenced in options by giving the name preceded by a + sign.
151 For example, in a router you might have
152
153   domains = +local_domains
154
155 At first sight, these lists might seem to be the same as macros, but they are
156 not. Macros are just textual substitutions. If you write
157
158   ALIST = host1 : host2
159   auth_advertise_hosts = !ALIST
160
161 it probably won't do what you want, because that is exactly the same as
162
163   auth_advertise_hosts = !host1 : host2
164
165 Notice that the second host name is not negated. However, if you use a host
166 list, and write
167
168   hostlist alist = host1 : host2
169   auth_advertise_hosts = ! +alist
170
171 the negation applies to the whole list, and so that is equivalent to
172
173   auth_advertise_hosts = !host1 : !host2
174
175 These named lists also have a performance advantage. When Exim is routing an
176 address or checking an incoming message, it caches the result of tests on the
177 lists. So, if you have a setting such as
178
179   domains = +local_domains
180
181 on several of your routers, the actual test is done only for the first one.
182 However, this caching works only if there are no expansions within the list
183 itself or any sublists that it references. In other words, caching happens only
184 if the list is known to be the same each time it is referenced.
185
186 By default, there may be up to 16 named lists of each type. This limit can be
187 extended by changing a compile-time variable.
188
189 The use of domain and host lists is recommended for concepts such as local
190 domains, relay domains, and relay hosts. The default configuration is set up
191 like this.
192
193
194 Processing of domain, host, local part, and address lists
195 ---------------------------------------------------------
196
197 The handling of these lists is now more uniform. Every list is expanded as a
198 single string before it is used. (In Exim 3, some options were expanded and
199 some weren't, and query-style lookup items were then re-expanded.)
200
201 If an expansion is forced to fail, Exim behaves as if the item has not been
202 found in the list.
203
204 The confusing $key variable has been abolished. When processing a domain list,
205 $domain contains the relevant domain and can be used in generating database
206 queries. Other appropriate variables are set when processing other kinds of
207 list; $sender_host and $sender_host_address for checking incoming hosts and
208 $host and $host_address for checking outgoing hosts.
209
210 Note that this means that any \ and $ characters in regular expressions must be
211 escaped if they appear in one of these lists. The new expansion feature to turn
212 off expansion (\N ... \N) which is described below can be helpful here.
213
214 IMPORTANT: The details of the processing of address lists has been revised. In
215 particular, the handling of the case of an item that is a single-key lookup has
216 changed. It no longer looks up the domain on its own before looking up the
217 complete address. You need to supply an explicit "*@" before the lookup if you
218 want just the domain to be looked up. Please check the manual for full details.
219
220 If an item in a host list is the empty string, it matches only when no host is
221 defined. If used when checking an incoming message, it matches only when the
222 message is arriving by SMTP on the standard input from a local process (using
223 -bs). This provides a way of distinguishing between SMTP mail from local
224 processes and from remote hosts.
225
226 The +allow_unknown and +warn_unknown settings for host lists have been replaced
227 by a single item, +include_unknown. By default, failure to find a host name
228 when needed causes Exim to behave as if the host does not match the list, but
229 if +include_unknown is set, the opposite behaviour happens. Whenever
230 +include_unknown is invoked, the incident is logged.
231
232
233 Merge of Directors and Routers
234 ------------------------------
235
236 There are no longer any directors in Exim 4. There are just routers. All
237 addresses are passed to a single list of routers which typically makes use of
238 the "domains" option to choose which way to handle specific groups of domains.
239
240 A consequence of this is that the code no longer contains any concept of "local
241 domains". However, a typical configuration will probably define a named domain
242 list (see above) called local_domains, and use it to control routing something
243 like this:
244
245   route_remote:
246     driver = dnslookup
247     domains = ! +local_domains
248     transport = remote_smtp
249     no_more
250
251   system_aliases:
252     ....
253
254 The first router does DNS routing for all domains that are not in the named
255 list of local domains, and no_more ensures that it is the last router for those
256 domains. All other domains fall through to the system_aliases and subsequent
257 routers. For a complete configuration example, look at the default
258 configuration file in src/configure.default.
259
260
261 Router Actions
262 --------------
263
264 The concept of how the routers work is as follows:
265
266 A number of pre-conditions are tested (details below). If any of them fails,
267 control is passed to the next router. We say "the router is skipped". Otherwise
268 the router is run, and can yield one of several different results:
269
270 . accept: The router accepts the address, and either queues it for a transport,
271 or generates one or more "child" addresses. Processing the original address
272 ceases, unless "unseen" is set on the router, in which case the address is
273 passed to the next router. Processing of any child addresses starts with the
274 first router by default, or at the router defined by redirect_router if it is
275 set. This may be any router in the list.
276
277 . decline: The router declines to accept the address because it does not
278 recognize it at all. The address is passed to the next router, unless no_more
279 is set, in which case the address fails.
280
281 . pass: The router recognizes the address, but cannot handle it itself. It
282 requests that the address be passed to another router. This overrides no_more.
283 By default the address is passed to the next router, but this can be changed by
284 setting pass_router. However, in this case (unlike redirect_router) the named
285 router must be below the current router (to avoid loops).
286
287 . fail: The router determines that the address should fail, and queues it for
288 the generation of a bounce message. There is no further processing of the
289 original address, unless "unseen" is set.
290
291 . defer: The router cannot handle the address at the present time. (For
292 example, a database may be offline.) No further processing of the address
293 happens in this delivery attempt. It is tried again next time.
294
295 . error: There is some error in the router (for example, a syntax error in
296 its configuration). The action is as for defer.
297
298
299 Router pre-conditions
300 ---------------------
301
302 In Exim 3 there are some strange interactions between the generic options that
303 test things before running a director or router and the no_more test that
304 happens afterwards.
305
306 In Exim 4 it is all more straightforward. If any of the pre-condition tests
307 fail, the router is skipped and control passes to the next router. The no_more
308 option has an effect only if the router is actually run - that is, if all the
309 pre-condition tests succeed. The order in which these tests are run is:
310
311   verify status, expn status, domains, local_parts, check_local_user
312
313 If all those match, the debug_print string is output when debugging. Exim then
314 goes on to test
315
316   senders, require_files, condition
317
318 Note that require_files comes near the end of the list, so you cannot use it to
319 check for the existence of a file in which to lookup up a domain, local part,
320 or sender. However, as these options are all expanded, you can use the "exists"
321 expansion condition to make such tests. The require_files option is intended
322 for checking files that the router may be going to use internally, or which are
323 needed by a specific transport (e.g. .procmailrc).
324
325 In Exim 4, local part prefixes and suffixes are recognized and removed before
326 any of the other pre-condition tests are done (in Exim 3 they were removed
327 afterwards). Note that this means that the local_parts option now tests the
328 local part without its prefix or suffix.
329
330 If you want to use local parts that include any affixes in a pre-condition
331 test, you can do so by using a "condition" option that uses the variables
332 $local_part, $local_part_prefix, and $local_part_suffix as necessary.
333
334
335 A New Set of Routers
336 --------------------
337
338 The two sets of routers and directors of Exim 3 have been replaced by a single
339 set of routers for Exim 4. These are as follows:
340
341 . accept        Always accepts an address. It has no private options.
342
343 . dnslookup     Routes by DNS lookup (descended from lookuphost).
344
345 . ipliteral     Routes IP literal addresses (unchanged).
346
347 . iplookup      Special-purpose lookup router (unchanged).
348
349 . manualroute   Routes domains from explicit data (descended from domainlist).
350
351 . queryprogram  Routes addresses by running a program (detail changed).
352
353 . redirect      Redirects addresses; handles all the functions previously
354                 supported by aliasfile, forwardfile, and smartuser without
355                 a transport.
356
357
358 Saving duplication of effort while routing
359 ------------------------------------------
360
361 Early versions of Exim used to copy the routing of one address for all other
362 addresses in the same domain, thereby possibly saving some repeated DNS
363 lookups. This feature was removed for release 2.12, after the possibility of
364 varying the router actions according to the local part (the local_parts option)
365 was added. (In fact, the use of $local_part could have broken it earlier.)
366
367 For Exim 4, I have added an option called same_domain_copy_routing to the
368 dnslookup and manualroute routers. When one of these routers routes an address
369 to a remote transport and this option is set, any other addresses in the
370 message that have the same domain are automatically given the same routing, but
371 only if the router does not set headers_add or headers_remove, and does not
372 `widen' the domain during the routing.
373
374
375 Generic Router Options
376 ----------------------
377
378 . The global locally_caseless option is replaced by a generic router option
379   called caseful_local_part. By default, routers handle local parts caselessly.
380
381 . check_local_user is now a generic option that is needed to check for a local
382   account. Typically used on redirect (for user's forward files) and on accept
383   (for local deliveries).
384
385 . The setting self=local has been removed (since there's no concept of local
386   domains in the code). The same kind of effect can be achieved by using
387   self=reroute or self=pass.
388
389 . expn is now a generic router option.
390
391 . local_part_prefix and local_part_suffix are now generic router options,
392   replacing prefix and suffix on directors.
393
394 . Exim 3 has two logging styles for delivery, depending on whether the domain
395   is a local domain or not. For local domains, the address is given just as the
396   local part - this makes these deliveries easier to spot in the log. In Exim 4
397   there's no concept of local domains, so this functionality cannot be
398   automatic. Instead, there's a generic router option called log_as_local which
399   requests "local-style" logging. This option defaults on for the "accept"
400   router, and off for all the others.
401
402 . There's an option called retry_use_local_part which is the default for any
403   router that has check_local_user set, and it applies to routing delays. (The
404   same option for transports applies to transport delays.)
405
406 . transport_home_directory and transport_current_directory are new generic
407   options on all routers. They set up default values for home_directory and
408   current_directory on the transport to which they route an address. Any
409   settings in the transport override.
410
411 . If transport_home_directory is not set, but check_local_user is set, the
412   user's home directory is used as a default value.
413
414 . The special fudge that exists in Exim 3 for handling home_directory settings
415   in forwardfile directors is not needed in Exim 4. It has therefore been
416   removed.
417
418 . The new_director option in Exim 3 allows the direction of redirected
419   addresses to start at a given director, instead of the first one. In Exim 4,
420   this option is now called redirect_router. The option is used when a redirect
421   router succeeds, and when a queryprogram router returns a "redirect"
422   response.
423
424 . There is a new option called pass_router, which specifies the router to go to
425   when a router "passes" on an address. The named router must follow the
426   current router (to avoid routing loops). Note: if a router declines, control
427   always passes to the next router, unless no_more is set.
428
429 . There is a new router option called address_data. This is set to a string
430   which is expanded just before the router is run, that is, after all the
431   pre-tests have succeeded. If the expansion is forced to fail, the router
432   declines. Other expansion failures cause delivery of the address to be
433   deferred.
434
435   When the expansion succeeds, the value is retained with the address, and can
436   be accessed using the variable $address_data. Even if the router declines or
437   passes, the value remains with the address, though it can be changed by
438   another address_data setting on a subsequent router. If a router generates
439   child addresses, the value of $address_data propagates to them.
440
441   The idea of address_data is that you can use it to look up a lot of data for
442   the address once, then then pick out parts of the data later. For example,
443   you could use an LDAP lookup to return a string of the form
444
445     uid=1234 gid=5678 mailbox=/mail/xyz forward=/home/xyz/.forward
446
447   In the transport you could then pick out the mailbox by a setting such as
448
449     file = ${extract{mailbox}{$address_data}}
450
451   This makes the configuration file less messy, and also reduces the number of
452   lookups. (Exim does cache the most recent lookup, but there may be several
453   addresses with different lookups.)
454
455 . When a transport is run for several addresses simultaneously, the values of
456   $address_data, $local_part_data, and $domain_data are taken from the first
457   address that the transport handles. However, the order in which multiple
458   addresses are processed is not defined. You therefore need to be careful if
459   you want to use these variables with multiple addresses. The smtp transport
460   is the only one which by default handles multiple addresses.
461
462 . When an address is routed by a router with the "unseen" option set, a "clone"
463   address is created, and it starts being routed at the next router. (This is
464   what people expect. In Exim 3 it starts at the top - in simple cases that has
465   the same effect because of the anti-looping rule, but if aliases are involved
466   it sometimes doesn't do what you want.)
467
468 . The way that require_files works has been changed. Each item in the list is
469   now separately expanded as the test proceeds. The use of leading ! and +
470   characters is unchanged. However, user and group checking is done differently.
471   Previously, seteuid() was used, but seteuid() is no longer used (see
472   "Security" below) for checking the files required by this option. Instead,
473   Exim now scans along the components of the file path and checks the access
474   for the given uid and gid. It expects "x" access on directories and "r" on
475   the final file. This means that file access control lists (on those
476   operating systems that have them) are ignored.
477
478
479 Other Consequences of the Director/Router Merge
480 -----------------------------------------------
481
482 . The -odqr option is abolished, as there is no inbuilt concept of remote
483   domains.
484
485 . The -odqs option is equivalent to queue_smtp_domains = *.
486
487 . queue_remote_domains is renamed queue_domains, and applies to any domain.
488
489 . The -ql option now suppresses remote delivery; routing always happens.
490
491 . The "remote" facility of queue_only_file has been removed.
492
493 . The match_directory option for forwardfile and localuser has been entirely
494   abolished. Its function can be achieved using the "condition" option in
495   conjunction with check_local_user.
496
497 . When an address is being verified, if it is redirected to a single new
498   address, verification continues with that address. If it is redirected to
499   more than one address, verification ceases with a success result. (In Exim 3,
500   this applied only to aliasing, not to forwarding.)
501
502
503 The dnslookup router
504 --------------------
505
506 This router replaces the lookuphost router of Exim 3. It is much the same,
507 except that the "gethostbyname" option has been removed. It now does only DNS
508 routing - hence the change of name. Routing using gethostbyname() can be done
509 by the manualroute router.
510
511
512 The manualroute router
513 ----------------------
514
515 This is the new name for the domainlist router, supposedly to make its function
516 clearer and to avoid confusion with the "domainlist" that is used to set up
517 named domain lists. Several things have been removed and reorganized.
518
519 . The old search mechanism (route_file, route_query, route_queries,
520   search_type) have been removed. Instead there is a new option called
521   route_data, which is an expanded string. It should expand to a single routing
522   entry. If the expansion ends up empty (or is forced to fail), the router
523   declines. The route_list option still exists, for convenient listing of a few
524   inline routes.
525
526 . There is no longer any MX processing function in this router. The keywords
527   bydns_mx and bydns_a have been removed, leaving just
528
529     bydns  => find IP addresses from address records in the DNS
530     byname => find IP addresses by calling gethostbyname()
531
532   The default lookup type is "byname", and this can be omitted from a route
533   data line. If an IP address is given, both "byname" and "bydns" are ignored
534   (so typically you omit this field).
535
536 . The qualify_single and search_parents options have also been removed.
537
538 . A transport is always required to be set, unless verify_only is set.
539
540 . The host_find_failed option can be set to "decline", to cause the router to
541   decline if it can't find an IP address for a listed host.
542
543 . If manualroute routes to a local transport, there is no need to specify
544   byname or bydns in the routing data. Any supplied host list is passed as a
545   string in $host, but $host_address is unset.
546
547
548 The queryprogram router
549 -----------------------
550
551 This router has been re-designed:
552
553 . You must now specify a user and group for the program to be run using
554   command_user and (if necessary) command_group. It no longer defaults to
555   "nobody". These options are expanded.
556
557 . The command is now split up and each argument expanded separately, as happens
558   for the pipe transport. The command name is also expanded.
559
560 . The return value "forcefail" has been renamed "fail", and it causes delivery
561   to fail. (The original usage of "fail" meaning "decline" has finally been
562   removed.)
563
564 . The $route_option variable, which queryprogram used to be able to set has
565   been abolished. A facility to set the new $address_data variable replaces it.
566
567 . The string returned from queryprogram must now be one of:
568
569   DECLINE
570   FAIL text
571   DEFER text
572   PASS
573   FREEZE text
574   REDIRECT text
575   ACCEPT TRANSPORT=transport HOSTS=host list LOOKUP=byname|bydns DATA=text
576
577 The text returned for "redirect" is a list of new addresses. The text for FAIL
578 is returned in the SMTP dialogue when the router is run as part of address
579 verification. It is also logged. The text for DEFER and FREEZE is just logged.
580
581 The data items in the "accept" return can be given in any order, and all are
582 optional. If no transport is included in the "accept" return, the router's
583 default transport is used. The host list and lookup type are needed only if the
584 transport is an smtp transport that does not itself have a host list. The
585 default lookup type is "byname". If the "data" field is set, its value is
586 placed in the $address_data variable.
587
588
589 The redirect router
590 -------------------
591
592 This router replaces forwardfile, appendfile, and the use of smartuser without
593 a transport. It has two mutually exclusive options for specifying the data that
594 it uses. If "file" is set, the data is taken from a file. Otherwise "data" must
595 be set, and the data is the expanded value of that option.
596
597 The data may be an alias list, possibly including special entries such as
598 :fail:, or it may be a list of filtering instructions.
599
600 If "file" is set, but the file does not exist or is empty, or its contents have
601 no effect (entirely comments, or a filter that does nothing), the router
602 declines. This also happens if the expansion of "file" is forced to fail. Any
603 other expansion failure causes the router to defer.
604
605 Ownership of the file is checked if check_local_user is set or if owners is
606 set, unless check_owner is explicitly set false.
607
608 Likewise, the group is checked if owngroups is set, or if check_local_user is
609 set and a modemask not containing 020 is set, unless check_group is explicitly
610 set false.
611
612 If "data" is set, a forced expansion causes the router to decline. This also
613 happens if "data" is an empty string or a string that causes nothing to be
614 generated and no action to be taken.
615
616 Because "data" is now used for traditional /etc/aliases lookups, an empty alias
617 no longer gives an error. It behaves in the same way as :unknown: (which is
618 still recognized, but ignored).
619
620 . If no_repeat_use is set, the router is skipped if _any_ ancestor of the
621   current address was routed by this router. This pre-test happens before any
622   of the others. (Contrast the default loop avoidance logic, which skips a
623   router if an ancestor with the same local part was routed by the router.)
624
625 . If include_directory is set, :include: files are constrained to this
626   directory.
627
628 . When an address is redirected to a file or a pipe, $address_file or
629   $address_pipe (as appropriate) is set when expanding the value of
630   file_transport or directory_transport.
631
632 . There are new options forbid_filter_readfile and forbid_filter_run to lock
633   out the use of the new ${readfile and ${run expansion items in filters.
634
635 . If one_time is set, forbid_pipe, forbid_file, and forbid_filter_reply are
636   forced to be true, and headers_add and headers_remove are forbidden.
637
638
639 Generic transport options
640 -------------------------
641
642 . All remote deliveries are now done in subprocesses running with specified
643   UIDs and GIDs. (Formerly, only remote parallel deliveries were done in
644   subprocesses.) As a result, user and group are now generic options that can
645   be used on all transports. The default for both local and remote transports
646   is to run as the Exim user and group. For remote transports, this should not
647   normally be changed, but if it is, the user or group should be able to access
648   the hints databases, though failure to open a hints database is always
649   ignored.
650
651   If it turns out that a transport user is in the never_users list, Exim now
652   defers delivery and writes to the panic log. (Previously it just ran the
653   delivery as "nobody".) Because subprocesses (usually running as "exim")
654   are now always used for remote deliveries, you should *not* include "exim" in
655   the never_users list.
656
657 . initgroups is now also a generic transport option.
658
659 . home_directory and current_directory are generic options on all transports,
660   though some transports (e.g. smtp) make no use of them. If they are unset,
661   values supplied by the router are used.
662
663 . The message_size_limit option is now expanded, which makes it possible to
664   have different limits for different hosts, for example.
665
666
667 Multiple (batch) deliveries in the appendfile, lmtp, and pipe transports
668 ------------------------------------------------------------------------
669
670 The options controlling batch deliveries, including BSMTP, were a mess, and
671 have been reworked.
672
673 . The batch option has been removed from all three transports, and the bsmtp
674   and bsmtp_helo options have been removed from appendfile and pipe.
675
676 . The batch_max option defaults to 1 in all three transports.
677
678 . A new option called use_bsmtp has been added to appendfile and pipe. When
679   set, the message is delivered in BSMTP format. If you want to have a HELO
680   line at the start of the message, you can configure this by making use of the
681   message_prefix option. You must include the terminating newline.
682
683 . A new option called batch_id has been added to all three transports.
684
685 Batching is now achieved by setting batch_max to a value greater than 1. This
686 is recommended for lmtp. When multiple addresses are routed to the same
687 transport that has a batch_max value greater than one, the addresses are
688 delivered in a batch, subject to certain conditions:
689
690 . If any of the transport's options contain a reference to "$local_part", no
691   batching is possible.
692
693 . If any of the transport's options contain a reference to "$domain", only
694   addresses with the same domain are batched.
695
696 . If batch_id is set, it is expanded for each address, and only those addresses
697   with the same expanded value are batched.
698
699 . Batched addresses must also have the same errors address (where to send
700   delivery errors), the same header additions and removals, the same user and
701   group for the transport, and if a host list is present, the first host must
702   be the same.
703
704
705 The appendfile transport
706 ------------------------
707
708 . The prefix and suffix options have been renamed message_prefix and
709   message_suffix to avoid confusion with address affixes. The default values,
710   which are suitable for mbox deliveries, now apply only if "file" is set and
711   use_bsmtp is not set. Otherwise, the default values for these options are
712   unset. They can, of course, always be overridden.
713
714 . If "directory" is set (which means that "file" is not set), the check_string
715   and escape_string options now default unset.
716
717 . The require_lockfile options has been abolished. If use_lockfile is set, a
718   lock file is always required.
719
720 . The quota_filecount option is now expanded.
721
722 . The create_file option now also applies when delivering into an individual
723   file in a given directory, as well as when appending to a single file. In the
724   case of maildir delivery, the restriction applies to the top directory of the
725   maildir folder.
726
727 . There's a new option called directory_file which is expanded to form the
728   final leaf name of files when "directory" is set, but neither maildir nor
729   mailstore is set. The default is "q${base62:$tod_epoch}-$inode", which
730   reproduces the old fixed value. The variable $inode is available only when
731   expanding this new option.
732
733
734 The pipe transport
735 ------------------
736
737 . The prefix and suffix options have been renamed message_prefix and
738   message_suffix to avoid confusion with address affixes. The default values
739   that are suitable for vacation deliveries now apply only if use_bsmtp is not
740   set. Otherwise the default values for these options are unset. They can, of
741   course, always be overridden.
742
743
744 The smtp transport
745 ------------------
746
747 . The badly-named batch_max option is now called connection_max_messages.
748
749 . If hosts_randomize is set, it now affects host lists that come from a router
750   as well as the contents of the "hosts" option, but only if the hosts were not
751   obtained from MX records. Typically, such lists come from the manualroute
752   router. This change means that the router can provide the same host list for
753   multiple addresses - causing them all to be sent to the transport at once.
754   Randomizing is then done each time the transport is called. (If you set
755   hosts_randomize on the router, the randomizing happens for each address.)
756
757 . The way that smtp operates when there are multiple addresses to be sent to
758   the same host is now different. Previously, the transport was called many
759   times, with a maximum of max_rcpt addresses per call. Each call made a new
760   connection to the host. When remote_max_parallel = 1, all the addresses are
761   now passed to the transport at once. It makes a single TCP/IP call, but may
762   send multiple copies of the message, each with no more than max_rcpt
763   recipients.
764
765   When remote_max_parallel is greater than 1, a heuristic is used. The number
766   of addresses passed to a single call of the transport is limited to
767
768     (the total number of recipients) / (the value of remote_max_parallel)
769
770   so, for example, if there are 100 recipients and remote_max_parallel is 2, no
771   more than 50 are passed in one call, even if max_rcpt is 100. (The idea is
772   that the other 50 will be passed to another call running in parallel.)
773
774   There is an option of the smtp transport called connection_max_messages
775   which limits the number of messages, or copies of a message, that Exim sends
776   down a single TCP/IP connection. This applies both to this mechanism for
777   multiple copies of a single message, and the re-use of a TCP/IP connection
778   for sending other messages destined for the same host, after a delivery
779   delay. The default value is 500.
780
781 . The "interface" option is now expanded. If the result is a forced failure or
782   an empty string, it is ignored. Otherwise, the result must be a list of IP
783   addresses. The first one of the correct type (IPv4 or IPv6) for the outgoing
784   connection is used. If there isn't one of the correct type, the option is
785   ignored.
786
787 . At the start of running the transport, the value of $host is taken from the
788   first host in a multi-host list. However, just before the transport connects
789   to a host, the value is changed to refer to that particular host. (This
790   applies to $host_address as well.) This means that options such as helo_data
791   and the tls_options can be made host-specific.
792
793 . The tls_verify_ciphers option has been renamed tls_require_ciphers, in order
794   to leave the word "verify" as something that refers to the verification of
795   certificates.
796
797 . The resolution of hosts and fallback_hosts used to look up MX records. This
798   was some kind of ancient silliness that I recently noticed. These are
799   definitely hosts, not mail domains. Exim 4 just looks up address records.
800   As a consequence of this, the mx_domains option of the smtp transport is
801   removed.
802
803 . The authenticate_hosts option has been renamed as hosts_try_auth. A new
804   option called hosts_require_auth has been added; if authentication fails for
805   one of these hosts, Exim does _not_ try to send unauthenticated. It defers
806   instead. The deferral error is detectable in the retry rules, so this can be
807   turned into a hard failure if required.
808
809
810 The System Filter
811 -----------------
812
813 . The system filter options that were called message_filter_xxx have all been
814   renamed as system_filter_xxx.
815
816 . The value of system_filter is expanded.
817
818 . message_filter_directory_transport and message_filter_file_transport are now
819   both expanded before use. If the filter set up any file or pipe deliveries,
820   $address_file and $address_pipe are set as appropriate while doing the
821   expansions.
822
823 . message_filter_directory2_transport has been removed. The effect of using
824   different directory-style transports can be achieved by specifying a suitable
825   expansion string to system_filter_directory_transport.
826
827 . When a system filter added recipients to a message, Exim 3 added an
828   X-Envelope-To: header, listing the real recipients (up to 100). This has been
829   abolished because you can do this kind of thing using "headers_add" nowadays.
830
831 . The "fail" command has been extended to allow for two different messages, one
832   for Exim's log and the other to be returned to the sender. The syntax is
833
834     fail "<<log message>>user message"
835
836   That is, if the first two characters of the message are "<<" the following
837   text, up to ">>", is written to the log, and the remainder is returned to the
838   user. If there is no log message, the user message is logged. The motivation
839   for this feature was to reduce the amount of text logged, while being able to
840   send quite long (maybe even multi-line) messages back to the sender.
841
842
843 Changes to Lookups
844 ------------------
845
846 . Oracle support is available. It works like the mysql and pgsql support,
847   except that there is no "database name" involved, and the "host name" field
848   is used for what is called "service name" in Oracle. This often looks like a
849   host name. Also, semicolons are not used at the end of an SQL query for
850   Oracle.
851
852 . There's a new single-key lookup type called dsearch. It searches a directory
853   for a file whose name matches the key. The result of a successful search is
854   the key. One possible use of this could be for recognizing virtual domains.
855   If each domain is represented by a file whose name is the domain name, you
856   needn't make a separate list of the domains. You could test for them in an
857   ACL (see below), for example, by a line like this
858
859      accept domains = dsearch;/etc/virtual/domains
860
861 . The format of LDAP output has been changed for cases where multiple
862   attributes are requested. The data for each attribute is now always quoted.
863   Within the quotes, the quote character, backslash, and newline are escaped
864   with backslashes and commas are used to separate multiple values for the
865   attribute. Thus, the string in quotes takes the same form as the output when
866   a single attribute is requested. If multiple entries are found, their data is
867   still separated by a newline.
868
869 . There's a new expansion condition called ldapauth which exists so that the
870   LDAP authentication mechanism can be used for user authentication. It is
871   described under "string expansion" below.
872
873 . Exim now supports ldaps:// URLs as well as ldap:// URLs. The former do LDAP
874   over TLS (i.e. encrypted) connections.
875
876 . There is now support for the "whoson" mechanism for doing "POP-before-SMTP"
877   authentication. This is provided by new query-style lookup type called
878   "whoson", with queries that consist of IP addresses. For example, in an ACL
879   you can write
880
881     require condition = ${lookup whoson {$sender_host_address}{yes}{no}}
882
883
884 Special items in domain and host lists
885 --------------------------------------
886
887 . In a domain list, the special item @ matches the primary host name, and the
888   special item @[] matches any local interface address enclosed in square
889   brackets (as in domain literal email addresses). The special item @mx_any
890   matches any domain that has an MX record pointing to the local host. The
891   special items @mx_primary and @mx_secondary are similar, except that the
892   first matches only when the primary MX is to the local host, and the second
893   only when the primary MX is not the local host, but a secondary MX is.
894
895 . In a host list, the special item @ matches the primary host name, and the
896   special item @[] matches any local interface address (not in brackets).
897
898
899 Access Control Lists (ACLs)
900 ---------------------------
901
902 All the policy control options for incoming messages have been replaced by
903 Access Control Lists (ACLs). These give more flexibility to the sysadmin, and
904 allow the order of testing to be specified. For example, using an ACL, it is
905 possible to specify "accept if authenticated, even if from an RBL host, but
906 otherwise deny if from an RBL host", which is not possible in Exim 3.
907
908 ACLs are defined in a new part of the configuration file, and given names.
909 Which ones to run are controlled by a new set of options that are placed in the
910 main part of the configuration.
911
912   acl_smtp_auth   specifies the ACL to run when AUTH is received
913   acl_smtp_data   specifies the ACL to run after a message has been received
914   acl_smtp_etrn   specifies the ACL to run when ETRN is received
915   acl_smtp_expn   specifies the ACL to run when EXPN is received
916   acl_smtp_rcpt   specifies the ACL to run when RCPT is received
917   acl_smtp_vrfy   specifies the ACL to run when VRFY is received
918
919 The default actions vary. If acl_smtp_auth is not defined, AUTH is always
920 accepted (and an attempt is made to authenticate the session). If acl_smtp_data
921 is not defined, no checks are done after a message has been received, and it is
922 always accepted at that point.
923
924 However, if any of the others are not defined, the relevant SMTP command is
925 rejected. In particular, this means that acl_smtp_rcpt must be defined in order
926 to receive any messages over an SMTP connection. The default configuration file
927 contains a suitable default for this.
928
929 ACLs can be provided in line, or in files, or looked up from databases. One ACL
930 can call another in a subroutine-like manner. String expansion is used, and
931 which ACL to run can be varied according to sender host or any other criterion
932 that a string expansion can test.
933
934 This is not the place to give a full specification of ACLs, but here is a
935 typical example for checking RCPT commands, taken from the default
936 configuration. The tests are performed in order.
937
938 acl_check_rcpt:
939   # Accept if source is local SMTP (i.e. not over TCP/IP - undefined host)
940   accept  hosts = :
941
942   # Deny if the local part contains @ or % or /
943   deny    local_parts   = ^.*[@%/]
944
945   # Accept mail to postmaster in any local domain, regardless of the source,
946   # and without verifying the sender.
947   accept  domains       = +local_domains
948           local_parts   = postmaster
949
950   # Deny unless the sender address can be verified.
951   require verify        = sender
952
953   # Accept if the address is in a local domain, but only if the recipient can
954   # be verified. Otherwise deny. The "endpass" line is the border between
955   # passing on to the next ACL statement (if tests above it fail) or denying
956   # access (if tests below it fail).
957   accept  domains       = +local_domains
958           endpass
959           message       = unknown user
960           verify        = recipient
961
962   # We get here only for non-local domains. Accept if the message arrived over
963   # an authenticated connection, from any host. These messages are usually from
964   # MUAs, so recipient verification is omitted.
965   accept  authenticated = *
966
967   # Reaching the end of the ACL causes a "deny", but we might as well give
968   # an explicit message.
969   deny    message       = relay not permitted
970
971 The following options have been abolished as a consequence of the introduction
972 of ACLs:
973
974 auth_hosts, auth_over_tls_hosts, headers_checks_fail, headers_check_syntax,
975 headers_sender_verify, headers_sender_verify_errmsg, host_accept_relay,
976 host_auth_accept_relay, host_reject_recipients, prohibition_message,
977 rbl_domains, rbl_hosts, rbl_log_headers, rbl_log_rcpt_count,
978 rbl_reject_recipients, rbl_warn_header, receiver_try_verify, receiver_verify,
979 receiver_verify_addresses, receiver_verify_hosts, receiver_verify_senders,
980 recipients_reject_except, recipients_reject_except_senders, relay_domains,
981 relay_domains_include_local_mx, relay_match_host_or_sender,
982 sender_address_relay, sender_address_relay_hosts, sender_reject,
983 sender_reject_recipients, sender_try_verify, sender_verify,
984 sender_verify_batch, sender_verify_hosts, sender_verify_fixup,
985 sender_verify_hosts_callback, sender_verify_callback_domains,
986 sender_verify_callback_timeout, sender_verify_max_retry_rate,
987 sender_verify_reject, smtp_etrn_hosts, smtp_expn_hosts. smtp_verify, tls_hosts.
988
989 The variable $prohibition_reason has been abolished.
990
991 The host_reject option has been retained, but with its name changed to
992 host_reject_connection, to emphasize that it causes a rejection at connection
993 time. I've left it available just in case it is needed - but its use is not
994 recommended in normal circumstances.
995
996
997 Other Incoming SMTP Session Controls
998 ------------------------------------
999
1000 . The option smtp_accept_max_per_connection (default 1000) limits the number of
1001   messages accepted over a single SMTP connection. This is a safety catch in
1002   case some sender goes mad (incidents of this kind have been seen). After the
1003   limit is reached, a 421 response is given to MAIL commands.
1004
1005 . Some sites find it helpful to be able to limit the rate at which certain
1006   hosts can send them messages, and the rate at which an individual message can
1007   specify recipients. There are now options for controlling these two different
1008   rates.
1009
1010   Rate limiting applies only to those hosts that match smtp_ratelimit_hosts,
1011   whose value is a host list. When a host matches, one or both of the options
1012   smtp_ratelimit_mail and smtp_ratelimit_rcpt may be set. They apply to the
1013   rate of acceptance of MAIL and RCPT commands in a single SMTP session,
1014   respectively.
1015
1016   The value of each option is a set of four comma-separated values:
1017
1018     1. A threshold, before which there is no rate limiting.
1019     2. An initial time delay. Unlike other times in Exim, fractions are allowed
1020        here.
1021     3. A factor by which to increase the delay each time.
1022     4. A maximum value for the delay.
1023
1024   For example, these settings have been used successfully at the site which
1025   first suggested this feature, for controlling mail from their customers:
1026
1027     smtp_ratelimit_mail = 2, 0.5s, 1.05, 4m
1028     smtp_ratelimit_rcpt = 4, 0.25s, 1.015, 4m
1029
1030 . The default value for smtp_connect_backlog has been increased to 20.
1031
1032 . The SMTP protocol specification requires the client to wait for a response
1033   from the server at certain points in the dialogue. (Without PIPELINING these
1034   are after every command; with PIPELINING they are fewer, but still exist.)
1035   Some spamming sites send out a complete set of SMTP commands without waiting
1036   for any response. Exim 4 protects against this by rejecting messages if the
1037   client has sent further input when it should not have. The error response
1038   "554 SMTP synchronization error" is sent, and the connection is dropped.
1039
1040   This check is controlled by smtp_enforce_sync, which is true by default.
1041
1042 . helo_strict_syntax has been abolished. The default is now to enforce strict
1043   domain syntax for HELO/EHLO arguments. You can use helo_accept_junk_hosts if
1044   you want to avoid this.
1045
1046 . There's a new option called helo_lookup_domains. If the domain given in a
1047   HELO or EHLO command matches this list, a reverse lookup is done in order to
1048   establish the host's true name. The default setting is
1049
1050     helo_lookup_domains = @ : @[]
1051
1052   That is, a lookup is forced if the client host gives the server's name or
1053   [one of its IP addresses] in HELO or EHLO. (In Exim 3 this happened
1054   automatically and was not configurable.)
1055
1056 . The value of the global message_size_limit option is now expanded. For
1057   locally submitted messages this happens at the start of message reception.
1058   For messages from remote hosts, the expansion is done just after the host
1059   connects, so that the value can depend on the host.
1060
1061
1062 Handling of Resent- Fields
1063 --------------------------
1064
1065 RFC 2822 makes it clear that Resent- fields are purely informational. Exim used
1066 to make use of Resent-Reply-To: which does not actually exist, and it also used
1067 to use the last set of resent- fields for all the address fields it recognized.
1068
1069 In Exim 4, resent- headers are dealt with as follows:
1070
1071 . A Resent-From: header that just contains the login id as the address is
1072   automatically rewritten in the same way as From: is (using qualify domain,
1073   and user name from the passwd data).
1074
1075 . If there's a rewrite rule for a header, it is also applied to resent- headers
1076   of the same type. For example, a rule that rewrites From: headers also
1077   rewrites Resent-From: headers.
1078
1079 . For local messages, if Sender: is being removed on input, Resent-Sender: is
1080   also removed.
1081
1082 . If there are any resent- headers but no Resent-Date: or Resent-From: they are
1083   added.
1084
1085 . The logic for adding Sender: is now duplicated for Resent-Sender.
1086
1087 . If there's no Resent-Message-Id: one is created, and it is the
1088   Resent-Message-Id: which is included in the log line.
1089
1090
1091 Authentication
1092 --------------
1093
1094 . The auth_hosts option has been abolished; this functionality is now
1095   controlled by ACLs.
1096
1097 . The auth_always_advertise option has been abolished because it depended on
1098   auth_hosts and host_auth_accept_relay, both of which are no more. In its
1099   place there is a new option called auth_advertise_hosts, whose default value
1100   is *, meaning "advertise AUTH to all".
1101
1102 . The value of server_setid is now used when logging failed authentication
1103   attempts.
1104
1105 . The -oMaa option allows trusted users to set the value of
1106   $sender_host_authenticated (the authenticator name). This is normally used in
1107   conjunction with -oMa.
1108
1109
1110 Encryption
1111 ----------
1112
1113 . Because tls_hosts is no more, tls_advertise_hosts is now the only means of
1114   controlling the advertisement of STARTTLS (previously, tls_hosts overrode).
1115
1116 . The global option tls_verify_ciphers has been abolished. There are now
1117   facilities for checking which cipher is in use in ACLs.
1118
1119 . There's a new option called tls_try_verify_hosts. Like tls_verify_hosts, this
1120   causes the server to request a certificate from a client, and it verifies the
1121   certificate that it receives. However, unlike tls_verify_hosts, Exim
1122   continues with the SMTP connection (encrypted) if a client certificate is not
1123   received, or if the certificate does not verify. This state can be detected
1124   in an ACL, which makes it possible to implement policies such as "accept for
1125   relay only if a verified certificate has been received but accept for local
1126   delivery if encrypted, even without a verified certificate".
1127
1128   A match in tls_verify_hosts overrides tls_try_verify_hosts.
1129
1130
1131 The Daemon
1132 ----------
1133
1134 . local_interfaces can now specify a port number with each address, thus
1135   allowing a single Exim daemon to listen on multiple ports. The format of each
1136   address is either [aaaa]:ppp or aaaa.ppp where aaaa is an IP address and ppp
1137   is a port number. For example:
1138
1139     local_interfaces = 192.168.3.4.25 : 192.168.3.4.26
1140
1141   If an address is listed without a port, the setting of daemon_smtp_port, or
1142   the value of the -oX option, is the default.
1143
1144 . The -oX option can now override local_interfaces. That is, it can supply IP
1145   addresses as well as just a port. It is interpreted in this way if its value
1146   contains any of the characters . : or []. For example:
1147
1148   exim -bd -oX 10.9.8.7:10.11.12.13.2525
1149
1150   The format of the string is identical to the format recognized by the
1151   local_interfaces option.
1152
1153 . The way the daemon wrote PID files was overly complicated and messy. It no
1154   longer tries to be clever. A PID file is written if, and only if, -bd is used
1155   and -oX is _not_ used. In other words, only if the daemon is started with its
1156   standard options. There is only one PID file. If pid_file_path is unset, it
1157   is exim-daemon.pid in Exim's spool directory. Otherwise the value of
1158   pid_file_path is used. For backwards compatibility, "%s" in this value is
1159   replaced by an empty string.
1160
1161
1162 Logging
1163 -------
1164
1165 The log_level option and all the various independent logging control options
1166 have been abolished. In their place there is a single option called
1167 log_selector. It takes a string argument composed of names preceded by + or -
1168 characters. These turn on or off the logging of different things. For example:
1169
1170   log_selector = +arguments -retry_defer
1171
1172 The optional logging items (defaults marked *) are:
1173
1174   address_rewrite             address rewriting
1175   all_parents                 all parents in => lines
1176   arguments                   exim arguments
1177  *connection_reject           connection rejections
1178  *delay_delivery              immediate delivery delayed (message queued)
1179   delivery_size               add S=nnn to delivery lines
1180  *dnslist_defer               defers of DNS list (aka RBL) lookups
1181   incoming_interface          incoming interface on <= lines
1182   incoming_port               incoming port on <= lines
1183  *lost_incoming_connection    as it says (includes timeouts)
1184  *queue_run                   start and end queue runs
1185   received_sender             sender on <= lines
1186   received_recipients         recipients on <= lines
1187  *retry_defer                 "retry time not reached"
1188   sender_on_delivery          add sender to => lines
1189  *size_reject                 rejection because too big
1190  *skip_delivery               "message is frozen"
1191   smtp_confirmation           SMTP confirmation on <= lines
1192   smtp_connection             SMTP connections
1193   smtp_protocol_error         SMTP protocol errors
1194   smtp_syntax_error           SMTP syntax errors
1195   subject                     contents of Subject: on <= lines
1196  *tls_cipher                  TLS cipher on <= lines
1197   tls_peerdn                  TLS peer DN on <= lines
1198
1199   all                         all of the above
1200
1201 "retry time not reached" is always omitted from individual message logs after
1202 the first delivery attempt.
1203
1204 The log line "error message sent to" has been abolished, because the R= item on
1205 the incoming message line gives the relationship between the original message
1206 and the bounce.
1207
1208 The logging options that have been abolished are: log_all_parents,
1209 log_arguments, log_incoming_port, log_interface, log_ip_options,
1210 log_level, log_queue_run_level, log_received_sender, log_received_recipients,
1211 log_rewrites, log_sender_on_delivery, log_smtp_confirmation,
1212 log_smtp_connections, log_smtp_syntax_errors, log_subject, tls_log_cipher,
1213 tls_log_peerdn.
1214
1215
1216 Debugging
1217 ---------
1218
1219 The debug_level option has been removed. The -dm option has been removed. The
1220 -df option has also be removed, along with its related build-time option
1221 STDERR_FILE. (To debug inetd usage, an auxiliary script should be used.)
1222
1223 The -d option has been reworked. It no longer takes a debug level number
1224 argument, but instead takes a list of debugging names, each preceded by + or -
1225 to turn on or off individual sets of debugging messages.
1226
1227 . The -v option now shows just the SMTP dialog and any log lines.
1228
1229 . -d with no argument gives a lot of standard debugging data. This is in effect
1230   the equivalent of the old -d9, the thing you ask people to set for an initial
1231   debugging test.
1232
1233 . -d+x      adds debugging option x to the default set
1234   -d-x      removes debugging option x from the default set
1235   -d-all+x  leaves only debugging option x
1236
1237 The available debugging names are:
1238
1239   acl            ACL interpretation
1240   auth           authenticators
1241   deliver        general delivery logic
1242   dns            DNS lookups (see also resolver)
1243   dnsbl          DNS black list (aka RBL) code
1244   exec           arguments for execv() calls
1245   filter         filter handling
1246   hints_lookup   hints data lookups
1247   host_lookup    all types of name->IP address handling
1248   ident          ident lookup
1249   interface      lists of local interfaces
1250   lists          matching things in lists
1251   load           system load checks
1252   lookup         general lookup code and all lookups
1253   memory         memory handling (replaces the old -dm)
1254   process_info   setting info for the process log
1255   queue_run      queue runs
1256   receive        general message reception logic
1257   resolver       turn on the DNS resolver's debugging output; goes to stdout
1258   retry          retry handling
1259   rewrite        rewriting
1260   route          address routing
1261   tls            TLS logic
1262   transport      transports
1263   uid            changes of uid/gid and looking up uid/gid
1264   verify         address verification logic
1265
1266   all            all of the above, and also -v
1267
1268 The default (-d with no argument) includes all of the above, plus -v, with the
1269 exception of filter, interface, load, memory, and resolver. Some debugging
1270 output always happens unconditionally whenever any debugging is selected. This
1271 includes some initial output and every log line.
1272
1273 -d without any value was previously allowed for non-admin users because it used
1274 to be synonymous with -v. In Exim 4, non-admin users may use -v, but not -d.
1275
1276 If the debug_print option is set in any driver, it produces output whenever any
1277 debugging is selected, or if -v is used.
1278
1279
1280 Local Scan Function
1281 -------------------
1282
1283 For customized message scanning, you can now supply a C function that is linked
1284 into the Exim binary. The function is called local_scan(), and it is called
1285 when Exim has received a message, but has not yet sent a final
1286 acknowledgement to the sender. This applies to all messages, whether local or
1287 remote, SMTP or not.
1288
1289 From within your function you can inspect the message, change the recipients,
1290 add or remove headers, and tell Exim whether to accept or reject the message.
1291
1292 The manual contains the specification of the API for this function.
1293
1294
1295 String Expansion
1296 ----------------
1297
1298 . The lookup feature that allowed for subkeys using the syntax
1299
1300     ${lookup {key:subkey} type {data...
1301
1302   has been abolished (a) because the effect can be achieved using ${extract,
1303   and (b) because in non-lsearch lookups, a colon can be a valid character in a
1304   key.
1305
1306 . When a string key is used in a ${extract expansion item, it is now handled
1307   case-insensitively.
1308
1309 . A new expansion variable called $tod_epoch gives the time as a single decimal
1310   number representing the number of seconds from the start of the Unix epoch.
1311
1312 . There's a new expansion operator that can turn numbers into base 62, for
1313   example, ${base62:$tod_epoch}.
1314
1315 . ${extract{number} now recognizes a negative number as a request to count
1316   fields from the right.
1317
1318 . There's a new expansion feature for reading files:
1319
1320     ${readfile{/some/file}{eolstring}}
1321
1322   The contents of the file replace the item. If {eolstring} is present (it's
1323   optional) any newlines in the file are replaced by that string.
1324
1325 . There's a new expansion feature for running commands:
1326
1327     ${run{command args}{yes}{no}}
1328
1329   Like all the other conditional items, the {yes} and {no} strings are
1330   optional. Omitting both is equivalent to {$value}. The standard output of the
1331   command is put into $value if the command succeeds (returns a zero code). The
1332   value of the code itself is put into $runrc, and this remains set afterwards,
1333   so in a filter file you can do things like
1334
1335     if "${run{x y z}{}}$runrc" is 1 then ...
1336     elsif $runrc is 2 then ...
1337
1338   As in other command executions from Exim, a shell is not used by default.
1339   If you want a shell, you must explicitly code it.
1340
1341 . The redirect router has options for forbidding ${readfile and ${run in
1342   filters.
1343
1344 . A feature is provided to suppress expansion of part of a string. Any
1345   characters between two occurrences of \N are copied to the output string
1346   verbatim. This is particularly useful for protecting regular expressions from
1347   unwanted expansion effects. For example:
1348
1349     queue_smtp_domains = ! \N^ten-\d+\.testing\.com$\N
1350
1351   Without \N the \ and $ characters in the regex would have to be escaped.
1352
1353 . Radius authentication is supported in a similar way to PAM. You must set
1354   RADIUS_CONFIG_FILE in Local/Makefile to specify the location of the Radius
1355   client configuration file. Then you can use expansions such as
1356
1357     server_condition = ${if radius{arguments}{yes}{no}}
1358
1359 . User authentication can now also be done by attempting to bind to an LDAP
1360   server. The syntax is again similar to PAM and Radius.
1361
1362     server_condition = ${if ldapauth{ldap query}{yes}{no}}
1363
1364   A user and password are required to be supplied with the query. No actual
1365   data is looked up; Exim just does a bind to the LDAP server and sets the
1366   condition according to the result. Here's an example of an SMTP
1367   authenticator:
1368
1369     login:
1370       driver = plaintext
1371       public_name = LOGIN
1372       server_prompts = "Username:: : Password::"
1373       server_condition = ${if ldapauth \
1374         {user="uid=${quote_ldap:$1},ou=people,o=example.org" pass="$2" \
1375         ldap://ldap.example.org/}{yes}{no}}
1376       server_set_id = uid=$1,ou=people,o=example.org
1377
1378
1379
1380 Security
1381 --------
1382
1383 Exim 3 could be run in a variety of ways as far as security was concerned. This
1384 has all been simplified in Exim 4. Exim dropped the use of seteuid() in
1385 most places. But recent (2020-10/2021-04) vulnerabilities forced us to
1386 re-introduce seteuid() for opening the database files (hint files) as secure as
1387 possible. For future (>= 4.95) versions we work on a solution that
1388 does not need the seteuid call.
1389
1390 . A UID and GID are required to be specified when Exim is compiled. They can be
1391   now specified by name as well as by number, so the relevant options are now
1392   called EXIM_USER and EXIM_GROUP. If you really feel you have to run Exim as
1393   root, you can specify root here, but it is not recommended.
1394
1395 . The "security" option has been abolished. Exim always releases its root
1396   privilege when it can. In a conventional configuration, that means when it is
1397   receiving a message, when it is delivering a message, when it is running a
1398   queryprogram router, and when it is obeying users' filter files (and system
1399   filters if it has been given a user for that purpose).
1400
1401 . One important change is that Exim 4 runs as root while routing addresses for
1402   delivery. Exim 3 used seteuid() to give up privilege temporarily while
1403   routing. Apart from the unliked use of seteuid(), this sometimes gave rise to
1404   permissions problems on configuration files.
1405
1406 . However, Exim still runs as the Exim user while receiving messages, and
1407   therefore while using the routing logic for verifying at SMTP time.
1408
1409 . There is a new option called deliver_drop_privilege. If this is set, Exim
1410   gives up its privilege right at the start of a delivery process, and runs the
1411   entire delivery as the Exim user. This is the same action that used to be
1412   requested by setting security=unprivileged.
1413
1414
1415 Hints Databases
1416 ---------------
1417
1418 . A single "misc" hints database is now used for ETRN and host serialization.
1419   There have been appropriate consequential changes to the utilities for
1420   managing the hints.
1421
1422 . The exim_tidydb -f option has been abolished. A full tidy is now always done
1423   (it hasn't proved to be very expensive).
1424
1425
1426 The run time Configuration File
1427 ------------------------------
1428
1429 . The format of the configuration file has changed. Instead of using "end" to
1430   terminate sections, it now uses "begin <name>" to start sections. This means
1431   that the sections, apart from the first, may appear in any order.
1432
1433 . You can now include other files inside Exim run time configuration files, by
1434   using this syntax:
1435
1436   .include <file name>
1437
1438 . Quotes round the file name are optional. Includes may be nested to any depth,
1439   but remember that Exim reads its configuration file often. The processing of
1440   .include happens early, at a physical line level, so, like comment lines, it
1441   can be used in the middle of an options setting, for example:
1442
1443   hosts_lookup = a.b.c \
1444                  .include /some/file
1445
1446   Include processing happens _before_ macro processing. Its effect is simply to
1447   process the lines of the file as if they occurred inline where the .include
1448   appears.
1449
1450 . A macro at the start of a configuration line can now turn the line into an
1451   empty line or a comment line. This applies to _logical_ input lines, that is,
1452   after any concatenations have been done.
1453
1454
1455 Format of spool files
1456 ---------------------
1457
1458 . -local_scan is used in spool files to record the value of $local_scan_data,
1459   the string returned from the locally-provided local_scan() function.
1460
1461
1462 Renamed Options
1463 ---------------
1464
1465 Some options have been renamed, to make their function clearer, or for
1466 consistency.
1467
1468 . receiver_unqualified_hosts has been renamed as recipient_unqualified_hosts.
1469   I'm going to use "recipient" everywhere in future.
1470
1471 . helo_verify has become helo_verify_hosts.
1472
1473 . remote_sort has become remote_sort_domains.
1474
1475 . In the appendfile and pipe transports, "prefix" and "suffix" have become
1476   "message_prefix" and "message_suffix". In the generic router options,
1477   "prefix" and "suffix" have become "local_part_prefix" and "local_part_suffix".
1478
1479
1480 Miscellaneous
1481 -------------
1482
1483 . ETRN serialization now uses a double fork, so that an Exim process (detached
1484   from the original input process) can wait for the command to finish. This
1485   means that it works whatever command ETRN causes to run. (Previously it
1486   worked only if ETRN ran "exim -Rxxx".)
1487
1488 . For incoming messages, the server's port number is preserved, and is
1489   available in $interface_port. The privileged option -oMi can be used to
1490   set this value.
1491
1492 . The -Mmd option (to mark addresses delivered) now operates in a
1493   case-sensitive manner.
1494
1495 . Checks for duplicate deliveries are now case-sensitive in the local part.
1496
1497 . The number of situations where Exim panics has been reduced. For example,
1498   expansion failures for the "domains" or "local_parts" options in a router now
1499   cause deferral instead of a panic.
1500
1501 . EXPN no longer attempts to distinguish local and remote addresses (but you
1502   can cause it to be rejected for certain arguments in the ACL).
1503
1504 . accept_timeout has been renamed as receive_timeout, to match
1505   smtp_receive_timeout.
1506
1507 . The ability to check an ident value as part of an item in a host list has
1508   been removed.
1509
1510 . The reject log shows a message's headers only if the rejection happens after
1511   the SMTP DATA command (because they aren't available for earlier checks). The
1512   sender, and up to five recipients are listed in Envelope-from: and
1513   Envelope-to: header lines. After the headers, a line of separator characters
1514   is output. Separators are no longer used for other reject log entries.
1515
1516 . Because header checks are now done as part of ACLs, they now apply only to
1517   SMTP input.
1518
1519 . The port number on SMTP connections is now logged in the format [aaaa]:ppp
1520   where aaaa is an IP address and ppp is a port, instead of in the format
1521   [aaaa.ppp] because the former format causes some software to complain about
1522   bad IP addresses.
1523
1524 . The -oMa and -oMi options can now use the [aaaa]:ppp notation to set a port
1525   number, but they still also recognize the aaaa.ppp notation.
1526
1527 . The build-time option HAVE_AUTH is abolished. Exim automatically includes
1528   authentication code if any authenticators are configured.
1529
1530 . The nobody_user and nobody_group options have been abolished.
1531
1532 . The $message_precedence variable has been abolished. The value is now
1533   available as $h_precedence:.
1534
1535 . There's a new utility script called exim_checkaccess which packages up a call
1536   to Exim with the -bh option, for access control checking. The syntax is
1537
1538     exim_checkaccess <IP address> <email address> [exim options]
1539
1540   It runs "exim -bh <IP address>", does the SMTP dialogue, tests the result and
1541   outputs either "accepted" or "Rejected" and the SMTP response to the RCPT TO
1542   command. The sender is <> by default, but can be changed by the use of the
1543   -f option.
1544
1545 . The default state of Exim is now to forbid domain literals. For this reason,
1546   the option that changes this has been renamed as allow_domain_literals.
1547
1548 . The dns_check_names boolean option has been abolished. Checking is now turned
1549   off by unsetting dns_check_names_pattern.
1550
1551 . The errors_address and freeze_tell_mailmaster options have been abolished. In
1552   their place there is a new option called freeze_tell, which can be set to a
1553   list of addresses. A message is sent to these addresses whenever a message is
1554   frozen - with the exception of failed bounce messages (this is not changed).
1555
1556 . The message_size_limit_count_recipients option has been abolished on the
1557   grounds that it was a failed experiment.
1558
1559 . The very-special-purpose X rewrite flag has been abolished. The facility it
1560   provided can now be done using the features of ACLs.
1561
1562 . The timestamps_utc option has been abolished. The facility is now provided by
1563   setting timezone = utc.
1564
1565 . The value of remote_max_parallel now defaults to 2.
1566
1567 . ignore_errmsg_errors has been abolished. The effect can be achieved by
1568   setting ignore_bounce_errors_after = 0s. This option has been renamed from
1569   ignore_errmsg_errors_after to make its function clearer. The default value
1570   for ignore_bounce_errors_after is now 10w (10 weeks - i.e. likely to be
1571   longer than any other timeouts, thereby disabling the facility).
1572
1573 . The default for message_size_limit is now 50M as a guard against DoS attacks.
1574
1575 . The -qi option does only initial (first time) deliveries. This can be helpful
1576   if you are injecting message onto the queue using -odq and want a queue
1577   runner just to process new messages. You can also use -qqi if you want.
1578
1579 . Rewriting and retry patterns are now anything that can be single address list
1580   items. They are processed by the same code, and are therefore expanded before
1581   the matching takes place. Regular expressions must be suitably quoted. These
1582   patterns may now be enclosed in double quotes so that white space may be
1583   included. Normal quote processing applies.
1584
1585 . Some scripts were built in the util directory, which was a mistake, because
1586   they might be different for different platforms. Everything that is built is
1587   now built in the build directory. The util directory just contains a couple
1588   of scripts that are not modified at build time.
1589
1590 . The installation script now installs the Exim binary as exim-v.vv-bb (where
1591   v.vv is the version number and bb is the build number), and points a symbolic
1592   link called "exim" to this binary. It does this in an atomic way so that
1593   there is no time when "exim" is non-existent. The script is clever enough to
1594   cope with an existing non-symbolic-link binary, converting it to the new
1595   scheme automatically (and atomically).
1596
1597 . When installing utilities, Exim now uses cp instead of mv to add .O to the
1598   old ones, in order to preserve the permissions.
1599
1600 . If the installation script is installing the default configuration, and
1601   /etc/aliases does not exist, the script installs a default version. This does
1602   not actually contain any aliases, but it does contain comments about ones
1603   that should be created. A warning is output to the user.
1604
1605 . A delay warning message is not sent if all the addresses in a message get a
1606   "retry time not reached" error. Exim waits until a delivery is actually
1607   attempted, so as to be able to give a more informative message.
1608
1609 . The existence of the three options deliver_load_max, queue_only_load, and
1610   deliver_queue_load_max was confusing, because their function overlapped. The
1611   first of them has been abolished. We are left with
1612
1613     queue_only_load         no immediate delivery if load is high when
1614                             message arrives
1615     deliver_queue_load_max  no queued delivery if load is too high
1616
1617 . The ability to edit message bodies (-Meb and the Eximon menu item) has been
1618   removed, on the grounds that it is bad practice to do this.
1619
1620 . Eximstats is now Steve Campbell's patched version, which displays sizes in K
1621   and M and G, and can optionally generate HTML.
1622
1623 . If bounce_sender_authentication is set to an email address, this address is
1624   used in an AUTH option of the MAIL command when sending bounce messages, if
1625   authentication is being used. For example, if you set
1626
1627     bounce_sender_authentication = mailer-daemon@your.domain
1628
1629   a bounce message will be sent over an authenticated connection using
1630
1631     MAIL FROM:<> AUTH=mailer-daemon@your.domain
1632
1633 . untrusted_set_sender has changed from a boolean to an address pattern. It
1634   permits untrusted users to set sender addresses that match the pattern. Like
1635   all address patterns, it is expanded. The identity of the user is in
1636   $sender_ident, so you can, for example, restrict users to setting senders
1637   that start with their login ids by setting
1638
1639     untrusted_set_sender = ^$sender_ident-
1640
1641   The effect of the previous boolean can be achieved by setting the value to *.
1642   This option applies to all forms of local input.
1643
1644 . The always_bcc option has been abolished. If an incoming message has no To:
1645   or Cc: headers, Exim now always adds an empty Bcc: line. This makes the
1646   message valid for RFC 822 (sic). In time, this can be removed, because RFC
1647   2822 does not require there to be a recipient header.
1648
1649 . ACTION_OUTPUT=no is now the default in the Exim monitor.
1650
1651 . dns_ipv4_lookup has changed from a boolean into a domain list, and it now
1652   applies only to those domains. Setting this option does not stop Exim from
1653   making IPv6 calls: if an MX lookup returns AAAA records, Exim will use them.
1654   What it does is to stop Exim looking for AAAA records explicitly.
1655
1656 . The -G option is ignored (another Sendmail thing).
1657
1658 . If no_bounce_return_message is set, the original message is not included in
1659   bounce messages. If you want to include additional information in the bounce
1660   message itself, you can use the existing errmsg_file and errmsg_text
1661   facilities.
1662
1663 . -bdf runs the daemon in the foreground (i.e. not detached from the terminal),
1664   even when no debugging is requested.
1665
1666 . Options for changing Exim's behaviour on receiving IPv4 options have been
1667   abolished. Exim now always refuses calls that set these options, and logs the
1668   incident. The abolished options are kill_ip_options, log_ip_options, and
1669   refuse_ip_options.
1670
1671 . The pattern for each errors_copy entry is now matched as an item in an
1672   address list.
1673
1674 . A number of options and variables that used the word "errmsg" have been
1675   changed to use "bounce" instead, because it seems that "bounce message" is
1676   now a reasonably well-understood term. I used it in the book and am now using
1677   it in the manual; it's a lot less cumbersome than "delivery error
1678   notification message". The changes are:
1679
1680   $errmsg_recipient          => $bounce_recipient
1681   errmsg_file                => bounce_message_file
1682   errmsg_text                => bounce_message_text
1683   ignore_errmsg_errors_after => ignore_bounce_errors_after
1684
1685   For consistency, warnmsg_file has been changed to warn_message_file. However,
1686   the two variables $warnmsg_delay and $warnmsg_recipients are unchanged.
1687
1688   The hide_child_in_errmsg option has not changed, because it applies to both
1689   bounce and delay warning messages.
1690
1691 . smtp_accept_max_per_host is now an expanded string, so it can be varied on
1692   a per-host basis. However, because this test happens in the daemon before it
1693   forks, the expansion should be kept as simple as possible (e.g. just inline
1694   tests of $sender_host_address).
1695
1696 . The retry rules can now recognize the error "auth_failed", which happens when
1697   authentication is required, but cannot be done.
1698
1699 . There's a new option called local_sender_retain which can be set if
1700   no_local_from_check is set. It causes Sender: headers to be retained in
1701   locally-submitted messages.
1702
1703 . The -dropcr command line option now turns CRLF into LF, and leaves isolated
1704   CRs alone. Previously it simply dropped _all_ CR characters. There is now
1705   also a drop_cr main option which, if turned on, assumes -dropcr for all
1706   non-SMTP input.
1707
1708
1709 Removal of Obsolete Things
1710 --------------------------
1711
1712 . The obsolete values "fail_soft" and "fail_hard" for the "self" option have
1713   been removed.
1714
1715 . The obsolete "log" command has been removed from the filter language.
1716
1717 . "service" was an obsolete synonym for "port" when specifying IP port numbers.
1718   It has been removed.
1719
1720 . The obsolete option collapse_source_routes has been removed. It has done
1721   nothing since release 3.10.
1722
1723 . The obsolete from_hack option in appendfile and pipe transports has been
1724   removed.
1725
1726 . The obsolete ipv4_address_lookup has been abolished (dns_ipv4_lookup has been
1727   a synonym for some time, but it's changed - see above).
1728
1729 . The obsolete generic transport options add_headers and remove_headers have
1730   been abolished. The new names, headers_add and headers_remove, have been
1731   available for some time.
1732
1733 Philip Hazel
1734 February 2002