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