Commit | Line | Data |
---|---|---|
495ae4b0 PH |
1 | Upgrading Exim from Release 3.33 to 4.xx |
2 | ---------------------------------------- | |
3 | ||
4 | Exim 4.00 represents the largest upheaval in Exim's history. There are a lot of | |
5 | changes to the way some parts of Exim work, and a lot of incompatible changes | |
6 | to the run time configuration file. | |
7 | ||
8 | This document is in two parts. The first part contains instructions and | |
9 | suggestions for how you might go about performing the upgrade. The second part | |
10 | is a brief list of all the changes that have taken place. For full details of | |
11 | all the new features, please consult the current version of the reference | |
12 | manual. | |
13 | ||
14 | ||
15 | HOW TO UPGRADE YOUR EXIM | |
16 | ------------------------ | |
17 | ||
18 | When you compile Exim 4, a Perl script called convert4r4 is built in the build | |
19 | directory. It is not installed by the install script, because it is likely that | |
20 | you will run it only once. | |
21 | ||
22 | This script is provided to assist in updating Exim configuration files. It | |
23 | reads an Exim 3 configuration file on the standard input, and writes a modified | |
24 | file on the standard output. It also writes comments about what it has done to | |
25 | the standard error file. It assumes that the input is a valid Exim 3 | |
26 | configuration file. A typical call to the conversion script might be | |
27 | ||
28 | ./convert4r4 </etc/exim/configure >/etc/exim/configure.new | |
29 | ||
30 | The output file MUST be checked and tested before trying to use it on a live | |
31 | system. The conversion script is just an aid which does a lot of the "grunt | |
32 | work". It does not guarantee to produce an Exim 4 configuration that behaves | |
33 | exactly the same as the Exim 3 configuration it reads. | |
34 | ||
35 | Each option change in the new file is preceded by an identifying comment. In | |
36 | fact, the conversion script tends to make quite a mess of your configuration, | |
37 | and you should expect to go through it afterwards and tidy it up by hand. | |
38 | ||
39 | Unless you are running a very straightforward configuration, the automatic | |
40 | conversion is likely to generate a non-optimal configuration. You should not | |
41 | only check it thoroughly, but also run as many tests as you can, to ensure that | |
42 | it is working as you expect. In particular, you should test address routing, | |
43 | using -bt and -bv, and the policy controls, using -bh. If possible, you should | |
44 | also do some live tests (i.e. send and receive some messages) before putting | |
45 | Exim 4 into service. | |
46 | ||
47 | If you have a very complicated configuration, it is possible that convert4r4 | |
48 | will break it in some situations, which is why thorough testing is strongly | |
49 | recommended. | |
50 | ||
51 | ********************************* | |
52 | ***** You Have Been Warned ****** | |
53 | ********************************* | |
54 | ||
55 | ||
56 | HOW TO MOVE FROM AN EXIM 3 RELEASE TO AN EXIM 4 RELEASE | |
57 | ------------------------------------------------------- | |
58 | ||
59 | One way of upgrading to Exim 4 from a version 3 release is as follows: | |
60 | ||
61 | 1. Suppose your run time configuration file is called /usr/exim/configure, and | |
62 | you want to continue with this name after upgrading. The first thing to do | |
63 | is to make another copy of this file called, say, /usr/exim/configure.r3. | |
64 | ||
65 | 2. Rebuild your existing Exim to use the copy of the run time configuration | |
66 | file instead of the standard file. Install this version of Exim and HUP your | |
67 | daemon. You can check on the name of the configuration file by running | |
68 | ||
69 | exim -bP configure_file | |
70 | ||
71 | Ensure that everything is running smoothly. You now have something you can | |
72 | fall back to. IMPORTANT: when you do this re-install, you should also | |
73 | re-install the utilities because four of them (exicyclog, eximon, exinext, | |
74 | and exiwhat) also refer to the configuration file. | |
75 | ||
76 | 3. Build the new release, configured to use the standard configuration file. | |
77 | ||
78 | 4. Use the convert4r4 utility to upgrade your configuration file for the new | |
79 | release. After running the conversion utility, check the file by hand, and | |
80 | tidy it up. | |
81 | ||
82 | 5. Test, test, test! And test some more! | |
83 | ||
84 | 6. You can run complete tests, including actual deliveries, from an uninstalled | |
85 | binary, but you have to tell it where it is, so that any re-executions can | |
86 | be done. You can do this by temporarily inserting a setting such as | |
87 | ||
88 | exim_path = /source/exim/exim-4.00/build-SunOS5-5.8-sparc/exim | |
89 | ||
90 | into the run time configuration. If you want to, you can also insert | |
91 | settings for spool_directory and log_file_path to divert those away from | |
92 | their normal places. Remember to remove these temporary settings when you | |
93 | eventually install the binary for real. | |
94 | ||
95 | 7. The new installation script installs the new release as exim-4.00-1, and | |
96 | set a symbolic link called "exim" to point to it. The old version of Exim | |
97 | will be renamed to something like exim-3.33-1. | |
98 | ||
99 | 8. You can now easily change between the new and old releases simply by moving | |
100 | the symbolic link and HUPping your daemon. The format of message files on | |
101 | Exim's spool has _not_ changed, so there should be no problem in changing | |
102 | between releases while there are messages on the queue. | |
103 | ||
104 | 9. HOWEVER: If you do change back and forth between releases, you must also | |
105 | change the utilities exicyclog, eximon, exinext, and exiwhat if you are | |
106 | going to use them. Installing Exim 4 will have left the old versions with a | |
107 | .O suffix. It might be helpful to rename these so that you don't lose them. | |
108 | ||
109 | ||
110 | WHAT HAS NOT CHANGED IN EXIM 4.00 | |
111 | --------------------------------- | |
112 | ||
113 | The basic overall philosophy, design, and process structure has not changed. | |
114 | The format of spool files is the same. The transports have had only minor | |
115 | modifications. The command line options remain the same, with a couple of | |
116 | additions. | |
117 | ||
118 | The general run time configuration approach has not changed, but the actual | |
119 | details of the configuration file are different. | |
120 | ||
121 | The Exim monitor has not changed, and there have been only very minor changes | |
122 | to other Exim utilities. | |
123 | ||
124 | ||
125 | WHAT HAS CHANGED IN EXIM 4.00 | |
126 | ----------------------------- | |
127 | ||
128 | The rest of this document lists the very many changes that have taken place. | |
129 | I'm going to give only brief details here, because this part of the document is | |
130 | intended as a way of alerting you to areas of difference. The reference manual | |
131 | describes how the new features work in detail. | |
132 | ||
133 | ||
134 | Named domain, host, address, and local part lists | |
135 | ------------------------------------------------- | |
136 | ||
137 | A new feature makes it possible to give names to lists of domains, hosts, | |
138 | addresses, and local parts. The syntax used is | |
139 | ||
140 | domainlist <name> = <a domain list> | |
141 | hostlist <name> = <a host list> | |
142 | addresslist <name> = <an address list> | |
143 | localpartlist <name> = <a list of local parts> | |
144 | ||
145 | For example: | |
146 | ||
147 | domainlist local_domains = *.my.domain | |
148 | addresslist bad_senders = cdb;/etc/badsenders | |
149 | ||
150 | These lists are referenced in options by giving the name preceded by a + sign. | |
151 | For example, in a router you might have | |
152 | ||
153 | domains = +local_domains | |
154 | ||
155 | At first sight, these lists might seem to be the same as macros, but they are | |
156 | not. Macros are just textual substitutions. If you write | |
157 | ||
158 | ALIST = host1 : host2 | |
159 | auth_advertise_hosts = !ALIST | |
160 | ||
161 | it probably won't do what you want, because that is exactly the same as | |
162 | ||
163 | auth_advertise_hosts = !host1 : host2 | |
164 | ||
165 | Notice that the second host name is not negated. However, if you use a host | |
166 | list, and write | |
167 | ||
168 | hostlist alist = host1 : host2 | |
169 | auth_advertise_hosts = ! +alist | |
170 | ||
171 | the negation applies to the whole list, and so that is equivalent to | |
172 | ||
173 | auth_advertise_hosts = !host1 : !host2 | |
174 | ||
175 | These named lists also have a performance advantage. When Exim is routing an | |
176 | address or checking an incoming message, it caches the result of tests on the | |
177 | lists. So, if you have a setting such as | |
178 | ||
179 | domains = +local_domains | |
180 | ||
181 | on several of your routers, the actual test is done only for the first one. | |
182 | However, this caching works only if there are no expansions within the list | |
183 | itself or any sublists that it references. In other words, caching happens only | |
184 | if the list is known to be the same each time it is referenced. | |
185 | ||
186 | By default, there may be up to 16 named lists of each type. This limit can be | |
187 | extended by changing a compile-time variable. | |
188 | ||
189 | The use of domain and host lists is recommended for concepts such as local | |
190 | domains, relay domains, and relay hosts. The default configuration is set up | |
191 | like this. | |
192 | ||
193 | ||
194 | Processing of domain, host, local part, and address lists | |
195 | --------------------------------------------------------- | |
196 | ||
197 | The handling of these lists is now more uniform. Every list is expanded as a | |
198 | single string before it is used. (In Exim 3, some options were expanded and | |
199 | some weren't, and query-style lookup items were then re-expanded.) | |
200 | ||
201 | If an expansion is forced to fail, Exim behaves as if the item has not been | |
202 | found in the list. | |
203 | ||
204 | The confusing $key variable has been abolished. When processing a domain list, | |
205 | $domain contains the relevant domain and can be used in generating database | |
206 | queries. Other appropriate variables are set when processing other kinds of | |
207 | list; $sender_host and $sender_host_address for checking incoming hosts and | |
208 | $host and $host_address for checking outgoing hosts. | |
209 | ||
210 | Note that this means that any \ and $ characters in regular expressions must be | |
211 | escaped if they appear in one of these lists. The new expansion feature to turn | |
212 | off expansion (\N ... \N) which is described below can be helpful here. | |
213 | ||
214 | IMPORTANT: The details of the processing of address lists has been revised. In | |
215 | particular, the handling of the case of an item that is a single-key lookup has | |
216 | changed. It no longer looks up the domain on its own before looking up the | |
217 | complete address. You need to supply an explicit "*@" before the lookup if you | |
218 | want just the domain to be looked up. Please check the manual for full details. | |
219 | ||
220 | If an item in a host list is the empty string, it matches only when no host is | |
221 | defined. If used when checking an incoming message, it matches only when the | |
222 | message is arriving by SMTP on the standard input from a local process (using | |
223 | -bs). This provides a way of distinguishing between SMTP mail from local | |
224 | processes and from remote hosts. | |
225 | ||
226 | The +allow_unknown and +warn_unknown settings for host lists have been replaced | |
227 | by a single item, +include_unknown. By default, failure to find a host name | |
228 | when needed causes Exim to behave as if the host does not match the list, but | |
229 | if +include_unknown is set, the opposite behaviour happens. Whenever | |
230 | +include_unknown is invoked, the incident is logged. | |
231 | ||
232 | ||
233 | Merge of Directors and Routers | |
234 | ------------------------------ | |
235 | ||
236 | There are no longer any directors in Exim 4. There are just routers. All | |
237 | addresses are passed to a single list of routers which typically makes use of | |
238 | the "domains" option to choose which way to handle specific groups of domains. | |
239 | ||
240 | A consequence of this is that the code no longer contains any concept of "local | |
241 | domains". However, a typical configuration will probably define a named domain | |
242 | list (see above) called local_domains, and use it to control routing something | |
243 | like this: | |
244 | ||
245 | route_remote: | |
246 | driver = dnslookup | |
247 | domains = ! +local_domains | |
248 | transport = remote_smtp | |
249 | no_more | |
250 | ||
251 | system_aliases: | |
252 | .... | |
253 | ||
254 | The first router does DNS routing for all domains that are not in the named | |
255 | list of local domains, and no_more ensures that it is the last router for those | |
256 | domains. All other domains fall through to the system_aliases and subsequent | |
257 | routers. For a complete configuration example, look at the default | |
258 | configuration file in src/configure.default. | |
259 | ||
260 | ||
261 | Router Actions | |
262 | -------------- | |
263 | ||
264 | The concept of how the routers work is as follows: | |
265 | ||
266 | A number of pre-conditions are tested (details below). If any of them fails, | |
267 | control is passed to the next router. We say "the router is skipped". Otherwise | |
268 | the router is run, and can yield one of several different results: | |
269 | ||
270 | . accept: The router accepts the address, and either queues it for a transport, | |
271 | or generates one or more "child" addresses. Processing the original address | |
272 | ceases, unless "unseen" is set on the router, in which case the address is | |
273 | passed to the next router. Processing of any child addresses starts with the | |
274 | first router by default, or at the router defined by redirect_router if it is | |
275 | set. This may be any router in the list. | |
276 | ||
277 | . decline: The router declines to accept the address because it does not | |
278 | recognize it at all. The address is passed to the next router, unless no_more | |
279 | is set, in which case the address fails. | |
280 | ||
281 | . pass: The router recognizes the address, but cannot handle it itself. It | |
282 | requests that the address be passed to another router. This overrides no_more. | |
283 | By default the address is passed to the next router, but this can be changed by | |
284 | setting pass_router. However, in this case (unlike redirect_router) the named | |
285 | router must be below the current router (to avoid loops). | |
286 | ||
287 | . fail: The router determines that the address should fail, and queues it for | |
288 | the generation of a bounce message. There is no further processing of the | |
289 | original address, unless "unseen" is set. | |
290 | ||
291 | . defer: The router cannot handle the address at the present time. (For | |
292 | example, a database may be offline.) No further processing of the address | |
293 | happens in this delivery attempt. It is tried again next time. | |
294 | ||
295 | . error: There is some error in the router (for example, a syntax error in | |
296 | its configuration). The action is as for defer. | |
297 | ||
298 | ||
299 | Router pre-conditions | |
300 | --------------------- | |
301 | ||
302 | In Exim 3 there are some strange interactions between the generic options that | |
303 | test things before running a director or router and the no_more test that | |
304 | happens afterwards. | |
305 | ||
306 | In Exim 4 it is all more straightforward. If any of the pre-condition tests | |
307 | fail, the router is skipped and control passes to the next router. The no_more | |
308 | option has an effect only if the router is actually run - that is, if all the | |
309 | pre-condition tests succeed. The order in which these tests are run is: | |
310 | ||
311 | verify status, expn status, domains, local_parts, check_local_user | |
312 | ||
313 | If all those match, the debug_print string is output when debugging. Exim then | |
314 | goes on to test | |
315 | ||
316 | senders, require_files, condition | |
317 | ||
318 | Note that require_files comes near the end of the list, so you cannot use it to | |
319 | check for the existence of a file in which to lookup up a domain, local part, | |
320 | or sender. However, as these options are all expanded, you can use the "exists" | |
321 | expansion condition to make such tests. The require_files option is intended | |
322 | for checking files that the router may be going to use internally, or which are | |
323 | needed by a specific transport (e.g. .procmailrc). | |
324 | ||
325 | In Exim 4, local part prefixes and suffixes are recognized and removed before | |
326 | any of the other pre-condition tests are done (in Exim 3 they were removed | |
327 | afterwards). Note that this means that the local_parts option now tests the | |
328 | local part without its prefix or suffix. | |
329 | ||
330 | If you want to use local parts that include any affixes in a pre-condition | |
331 | test, you can do so by using a "condition" option that uses the variables | |
332 | $local_part, $local_part_prefix, and $local_part_suffix as necessary. | |
333 | ||
334 | ||
335 | A New Set of Routers | |
336 | -------------------- | |
337 | ||
338 | The two sets of routers and directors of Exim 3 have been replaced by a single | |
339 | set of routers for Exim 4. These are as follows: | |
340 | ||
341 | . accept Always accepts an address. It has no private options. | |
342 | ||
343 | . dnslookup Routes by DNS lookup (descended from lookuphost). | |
344 | ||
345 | . ipliteral Routes IP literal addresses (unchanged). | |
346 | ||
347 | . iplookup Special-purpose lookup router (unchanged). | |
348 | ||
349 | . manualroute Routes domains from explicit data (descended from domainlist). | |
350 | ||
351 | . queryprogram Routes addresses by running a program (detail changed). | |
352 | ||
353 | . redirect Redirects addresses; handles all the functions previously | |
354 | supported by aliasfile, forwardfile, and smartuser without | |
355 | a transport. | |
356 | ||
357 | ||
358 | Saving duplication of effort while routing | |
359 | ------------------------------------------ | |
360 | ||
361 | Early versions of Exim used to copy the routing of one address for all other | |
362 | addresses in the same domain, thereby possibly saving some repeated DNS | |
363 | lookups. This feature was removed for release 2.12, after the possibility of | |
364 | varying the router actions according to the local part (the local_parts option) | |
365 | was added. (In fact, the use of $local_part could have broken it earlier.) | |
366 | ||
367 | For Exim 4, I have added an option called same_domain_copy_routing to the | |
368 | dnslookup and manualroute routers. When one of these routers routes an address | |
369 | to a remote transport and this option is set, any other addresses in the | |
370 | message that have the same domain are automatically given the same routing, but | |
371 | only if the router does not set headers_add or headers_remove, and does not | |
372 | `widen' the domain during the routing. | |
373 | ||
374 | ||
375 | Generic Router Options | |
376 | ---------------------- | |
377 | ||
378 | . The global locally_caseless option is replaced by a generic router option | |
379 | called caseful_local_part. By default, routers handle local parts caselessly. | |
380 | ||
381 | . check_local_user is now a generic option that is needed to check for a local | |
382 | account. Typically used on redirect (for user's forward files) and on accept | |
383 | (for local deliveries). | |
384 | ||
385 | . The setting self=local has been removed (since there's no concept of local | |
386 | domains in the code). The same kind of effect can be achieved by using | |
387 | self=reroute or self=pass. | |
388 | ||
389 | . expn is now a generic router option. | |
390 | ||
391 | . local_part_prefix and local_part_suffix are now generic router options, | |
392 | replacing prefix and suffix on directors. | |
393 | ||
394 | . Exim 3 has two logging styles for delivery, depending on whether the domain | |
395 | is a local domain or not. For local domains, the address is given just as the | |
396 | local part - this makes these deliveries easier to spot in the log. In Exim 4 | |
397 | there's no concept of local domains, so this functionality cannot be | |
398 | automatic. Instead, there's a generic router option called log_as_local which | |
399 | requests "local-style" logging. This option defaults on for the "accept" | |
400 | router, and off for all the others. | |
401 | ||
402 | . There's an option called retry_use_local_part which is the default for any | |
403 | router that has check_local_user set, and it applies to routing delays. (The | |
404 | same option for transports applies to transport delays.) | |
405 | ||
406 | . transport_home_directory and transport_current_directory are new generic | |
407 | options on all routers. They set up default values for home_directory and | |
408 | current_directory on the transport to which they route an address. Any | |
409 | settings in the transport override. | |
410 | ||
411 | . If transport_home_directory is not set, but check_local_user is set, the | |
412 | user's home directory is used as a default value. | |
413 | ||
414 | . The special fudge that exists in Exim 3 for handling home_directory settings | |
415 | in forwardfile directors is not needed in Exim 4. It has therefore been | |
416 | removed. | |
417 | ||
418 | . The new_director option in Exim 3 allows the direction of redirected | |
419 | addresses to start at a given director, instead of the first one. In Exim 4, | |
420 | this option is now called redirect_router. The option is used when a redirect | |
421 | router succeeds, and when a queryprogram router returns a "redirect" | |
422 | response. | |
423 | ||
424 | . There is a new option called pass_router, which specifies the router to go to | |
425 | when a router "passes" on an address. The named router must follow the | |
426 | current router (to avoid routing loops). Note: if a router declines, control | |
427 | always passes to the next router, unless no_more is set. | |
428 | ||
429 | . There is a new router option called address_data. This is set to a string | |
430 | which is expanded just before the router is run, that is, after all the | |
431 | pre-tests have succeeded. If the expansion is forced to fail, the router | |
432 | declines. Other expansion failures cause delivery of the address to be | |
433 | deferred. | |
434 | ||
435 | When the expansion succeeds, the value is retained with the address, and can | |
436 | be accessed using the variable $address_data. Even if the router declines or | |
437 | passes, the value remains with the address, though it can be changed by | |
438 | another address_data setting on a subsequent router. If a router generates | |
439 | child addresses, the value of $address_data propagates to them. | |
440 | ||
441 | The idea of address_data is that you can use it to look up a lot of data for | |
442 | the address once, then then pick out parts of the data later. For example, | |
443 | you could use an LDAP lookup to return a string of the form | |
444 | ||
445 | uid=1234 gid=5678 mailbox=/mail/xyz forward=/home/xyz/.forward | |
446 | ||
447 | In the transport you could then pick out the mailbox by a setting such as | |
448 | ||
449 | file = ${extract{mailbox}{$address_data}} | |
450 | ||
451 | This makes the configuration file less messy, and also reduces the number of | |
452 | lookups. (Exim does cache the most recent lookup, but there may be several | |
453 | addresses with different lookups.) | |
454 | ||
455 | . When a transport is run for several addresses simultaneously, the values of | |
456 | $address_data, $local_part_data, and $domain_data are taken from the first | |
457 | address that the transport handles. However, the order in which multiple | |
458 | addresses are processed is not defined. You therefore need to be careful if | |
459 | you want to use these variables with multiple addresses. The smtp transport | |
460 | is the only one which by default handles multiple addresses. | |
461 | ||
462 | . When an address is routed by a router with the "unseen" option set, a "clone" | |
463 | address is created, and it starts being routed at the next router. (This is | |
464 | what people expect. In Exim 3 it starts at the top - in simple cases that has | |
465 | the same effect because of the anti-looping rule, but if aliases are involved | |
466 | it sometimes doesn't do what you want.) | |
467 | ||
468 | . The way that require_files works has been changed. Each item in the list is | |
469 | now separately expanded as the test proceeds. The use of leading ! and + | |
470 | characters is unchanged. However, user and group checking is done differently. | |
471 | Previously, seteuid() was used, but seteuid() is no longer used 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 | ||
478 | Other 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 | ||
502 | The dnslookup router | |
503 | -------------------- | |
504 | ||
505 | This router replaces the lookuphost router of Exim 3. It is much the same, | |
506 | except that the "gethostbyname" option has been removed. It now does only DNS | |
507 | routing - hence the change of name. Routing using gethostbyname() can be done | |
508 | by the manualroute router. | |
509 | ||
510 | ||
511 | The manualroute router | |
512 | ---------------------- | |
513 | ||
514 | This is the new name for the domainlist router, supposedly to make its function | |
515 | clearer and to avoid confusion with the "domainlist" that is used to set up | |
516 | named 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 | ||
547 | The queryprogram router | |
548 | ----------------------- | |
549 | ||
550 | This 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 | ||
576 | The text returned for "redirect" is a list of new addresses. The text for FAIL | |
577 | is returned in the SMTP dialogue when the router is run as part of address | |
578 | verification. It is also logged. The text for DEFER and FREEZE is just logged. | |
579 | ||
580 | The data items in the "accept" return can be given in any order, and all are | |
581 | optional. If no transport is included in the "accept" return, the router's | |
582 | default transport is used. The host list and lookup type are needed only if the | |
583 | transport is an smtp transport that does not itself have a host list. The | |
584 | default lookup type is "byname". If the "data" field is set, its value is | |
585 | placed in the $address_data variable. | |
586 | ||
587 | ||
588 | The redirect router | |
589 | ------------------- | |
590 | ||
591 | This router replaces forwardfile, appendfile, and the use of smartuser without | |
592 | a transport. It has two mutually exclusive options for specifying the data that | |
593 | it uses. If "file" is set, the data is taken from a file. Otherwise "data" must | |
594 | be set, and the data is the expanded value of that option. | |
595 | ||
596 | The data may be an alias list, possibly including special entries such as | |
597 | :fail:, or it may be a list of filtering instructions. | |
598 | ||
599 | If "file" is set, but the file does not exist or is empty, or its contents have | |
600 | no effect (entirely comments, or a filter that does nothing), the router | |
601 | declines. This also happens if the expansion of "file" is forced to fail. Any | |
602 | other expansion failure causes the router to defer. | |
603 | ||
604 | Ownership of the file is checked if check_local_user is set or if owners is | |
605 | set, unless check_owner is explicitly set false. | |
606 | ||
607 | Likewise, the group is checked if owngroups is set, or if check_local_user is | |
608 | set and a modemask not containing 020 is set, unless check_group is explicitly | |
609 | set false. | |
610 | ||
611 | If "data" is set, a forced expansion causes the router to decline. This also | |
612 | happens if "data" is an empty string or a string that causes nothing to be | |
613 | generated and no action to be taken. | |
614 | ||
615 | Because "data" is now used for traditional /etc/aliases lookups, an empty alias | |
616 | no longer gives an error. It behaves in the same way as :unknown: (which is | |
617 | still 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 | ||
638 | Generic 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 | ||
666 | Multiple (batch) deliveries in the appendfile, lmtp, and pipe transports | |
667 | ------------------------------------------------------------------------ | |
668 | ||
669 | The options controlling batch deliveries, including BSMTP, were a mess, and | |
670 | have 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 | ||
684 | Batching is now achieved by setting batch_max to a value greater than 1. This | |
685 | is recommended for lmtp. When multiple addresses are routed to the same | |
686 | transport that has a batch_max value greater than one, the addresses are | |
687 | delivered 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 | ||
704 | The 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 | ||
733 | The 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 | ||
743 | The 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 | |
4c04137d | 805 | instead. The deferral error is detectable in the retry rules, so this can be |
495ae4b0 PH |
806 | turned into a hard failure if required. |
807 | ||
808 | ||
809 | The 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 | ||
842 | Changes 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 | ||
883 | Special 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 | ||
898 | Access Control Lists (ACLs) | |
899 | --------------------------- | |
900 | ||
901 | All the policy control options for incoming messages have been replaced by | |
902 | Access Control Lists (ACLs). These give more flexibility to the sysadmin, and | |
903 | allow the order of testing to be specified. For example, using an ACL, it is | |
904 | possible to specify "accept if authenticated, even if from an RBL host, but | |
905 | otherwise deny if from an RBL host", which is not possible in Exim 3. | |
906 | ||
907 | ACLs are defined in a new part of the configuration file, and given names. | |
908 | Which ones to run are controlled by a new set of options that are placed in the | |
909 | main 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 | ||
918 | The default actions vary. If acl_smtp_auth is not defined, AUTH is always | |
919 | accepted (and an attempt is made to authenticate the session). If acl_smtp_data | |
920 | is not defined, no checks are done after a message has been received, and it is | |
921 | always accepted at that point. | |
922 | ||
923 | However, if any of the others are not defined, the relevant SMTP command is | |
924 | rejected. In particular, this means that acl_smtp_rcpt must be defined in order | |
925 | to receive any messages over an SMTP connection. The default configuration file | |
926 | contains a suitable default for this. | |
927 | ||
928 | ACLs can be provided in line, or in files, or looked up from databases. One ACL | |
929 | can call another in a subroutine-like manner. String expansion is used, and | |
930 | which ACL to run can be varied according to sender host or any other criterion | |
931 | that a string expansion can test. | |
932 | ||
933 | This is not the place to give a full specification of ACLs, but here is a | |
934 | typical example for checking RCPT commands, taken from the default | |
935 | configuration. The tests are performed in order. | |
936 | ||
937 | acl_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 | ||
970 | The following options have been abolished as a consequence of the introduction | |
971 | of ACLs: | |
972 | ||
973 | auth_hosts, auth_over_tls_hosts, headers_checks_fail, headers_check_syntax, | |
974 | headers_sender_verify, headers_sender_verify_errmsg, host_accept_relay, | |
975 | host_auth_accept_relay, host_reject_recipients, prohibition_message, | |
976 | rbl_domains, rbl_hosts, rbl_log_headers, rbl_log_rcpt_count, | |
977 | rbl_reject_recipients, rbl_warn_header, receiver_try_verify, receiver_verify, | |
978 | receiver_verify_addresses, receiver_verify_hosts, receiver_verify_senders, | |
979 | recipients_reject_except, recipients_reject_except_senders, relay_domains, | |
980 | relay_domains_include_local_mx, relay_match_host_or_sender, | |
981 | sender_address_relay, sender_address_relay_hosts, sender_reject, | |
982 | sender_reject_recipients, sender_try_verify, sender_verify, | |
983 | sender_verify_batch, sender_verify_hosts, sender_verify_fixup, | |
984 | sender_verify_hosts_callback, sender_verify_callback_domains, | |
985 | sender_verify_callback_timeout, sender_verify_max_retry_rate, | |
986 | sender_verify_reject, smtp_etrn_hosts, smtp_expn_hosts. smtp_verify, tls_hosts. | |
987 | ||
988 | The variable $prohibition_reason has been abolished. | |
989 | ||
990 | The host_reject option has been retained, but with its name changed to | |
991 | host_reject_connection, to emphasize that it causes a rejection at connection | |
992 | time. I've left it available just in case it is needed - but its use is not | |
993 | recommended in normal circumstances. | |
994 | ||
995 | ||
996 | Other 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 | ||
1061 | Handling of Resent- Fields | |
1062 | -------------------------- | |
1063 | ||
1064 | RFC 2822 makes it clear that Resent- fields are purely informational. Exim used | |
1065 | to make use of Resent-Reply-To: which does not actually exist, and it also used | |
1066 | to use the last set of resent- fields for all the address fields it recognized. | |
1067 | ||
1068 | In 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 | ||
1090 | Authentication | |
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 | ||
1109 | Encryption | |
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 | ||
1130 | The 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 | ||
1161 | Logging | |
1162 | ------- | |
1163 | ||
1164 | The log_level option and all the various independent logging control options | |
1165 | have been abolished. In their place there is a single option called | |
1166 | log_selector. It takes a string argument composed of names preceded by + or - | |
1167 | characters. These turn on or off the logging of different things. For example: | |
1168 | ||
1169 | log_selector = +arguments -retry_defer | |
1170 | ||
1171 | The 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 | |
1201 | the first delivery attempt. | |
1202 | ||
1203 | The log line "error message sent to" has been abolished, because the R= item on | |
1204 | the incoming message line gives the relationship between the original message | |
1205 | and the bounce. | |
1206 | ||
1207 | The logging options that have been abolished are: log_all_parents, | |
1208 | log_arguments, log_incoming_port, log_interface, log_ip_options, | |
4c04137d | 1209 | log_level, log_queue_run_level, log_received_sender, log_received_recipients, |
495ae4b0 PH |
1210 | log_rewrites, log_sender_on_delivery, log_smtp_confirmation, |
1211 | log_smtp_connections, log_smtp_syntax_errors, log_subject, tls_log_cipher, | |
1212 | tls_log_peerdn. | |
1213 | ||
1214 | ||
1215 | Debugging | |
1216 | --------- | |
1217 | ||
1218 | The 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 | |
1220 | STDERR_FILE. (To debug inetd usage, an auxiliary script should be used.) | |
1221 | ||
1222 | The -d option has been reworked. It no longer takes a debug level number | |
1223 | argument, but instead takes a list of debugging names, each preceded by + or - | |
1224 | to 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 | ||
1236 | The 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 | ||
1267 | The default (-d with no argument) includes all of the above, plus -v, with the | |
1268 | exception of filter, interface, load, memory, and resolver. Some debugging | |
1269 | output always happens unconditionally whenever any debugging is selected. This | |
1270 | includes some initial output and every log line. | |
1271 | ||
1272 | -d without any value was previously allowed for non-admin users because it used | |
1273 | to be synonymous with -v. In Exim 4, non-admin users may use -v, but not -d. | |
1274 | ||
1275 | If the debug_print option is set in any driver, it produces output whenever any | |
1276 | debugging is selected, or if -v is used. | |
1277 | ||
1278 | ||
1279 | Local Scan Function | |
1280 | ------------------- | |
1281 | ||
1282 | For customized message scanning, you can now supply a C function that is linked | |
1283 | into the Exim binary. The function is called local_scan(), and it is called | |
1284 | when Exim has received a message, but has not yet sent a final | |
1285 | acknowledgement to the sender. This applies to all messages, whether local or | |
1286 | remote, SMTP or not. | |
1287 | ||
1288 | From within your function you can inspect the message, change the recipients, | |
1289 | add or remove headers, and tell Exim whether to accept or reject the message. | |
1290 | ||
1291 | The manual contains the specification of the API for this function. | |
1292 | ||
1293 | ||
1294 | String 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 | ||
4c04137d | 1326 | ${run{command args}{yes}{no}} |
495ae4b0 PH |
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 | ||
1379 | Security | |
1380 | -------- | |
1381 | ||
1382 | Exim 3 could be run in a variety of ways as far as security was concerned. This | |
1383 | has all been simplified in Exim 4. The security-conscious might like to know | |
1384 | that 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 | ||
1411 | Hints 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 | ||
1422 | The 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 | ||
1451 | Format 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 | ||
1458 | Renamed Options | |
1459 | --------------- | |
1460 | ||
1461 | Some options have been renamed, to make their function clearer, or for | |
1462 | consistency. | |
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 | ||
1476 | Miscellaneous | |
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 | ||
1705 | Removal 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 | ||
1729 | Philip Hazel | |
1730 | February 2002 |