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