| 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 |
| 805 | instead. The deferal error is detectable in the retry rules, so this can be |
| 806 | turned into a hard failure if required. |
| 807 | |
| 808 | |
| 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 |
| 1097 | auth_hosts and host_auth_accept_relay, both of which are no more. In its |
| 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, |
| 1209 | log_level, log_queue_run_level, log_received_sender, log_received_rceipients, |
| 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 | |
| 1326 | ${run{comand args}{yes}{no}} |
| 1327 | |
| 1328 | Like all the other conditional items, the {yes} and {no} strings are |
| 1329 | optional. Omitting both is equivalent to {$value}. The standard output of the |
| 1330 | command is put into $value if the command succeeds (returns a zero code). The |
| 1331 | value of the code itself is put into $runrc, and this remains set afterwards, |
| 1332 | so in a filter file you can do things like |
| 1333 | |
| 1334 | if "${run{x y z}{}}$runrc" is 1 then ... |
| 1335 | elsif $runrc is 2 then ... |
| 1336 | |
| 1337 | As in other command executions from Exim, a shell is not used by default. |
| 1338 | If you want a shell, you must explicitly code it. |
| 1339 | |
| 1340 | . The redirect router has options for forbidding ${readfile and ${run in |
| 1341 | filters. |
| 1342 | |
| 1343 | . A feature is provided to suppress expansion of part of a string. Any |
| 1344 | characters between two occurrences of \N are copied to the output string |
| 1345 | verbatim. This is particularly useful for protecting regular expressions from |
| 1346 | unwanted expansion effects. For example: |
| 1347 | |
| 1348 | queue_smtp_domains = ! \N^ten-\d+\.testing\.com$\N |
| 1349 | |
| 1350 | Without \N the \ and $ characters in the regex would have to be escaped. |
| 1351 | |
| 1352 | . Radius authentication is supported in a similar way to PAM. You must set |
| 1353 | RADIUS_CONFIG_FILE in Local/Makefile to specify the location of the Radius |
| 1354 | client configuration file. Then you can use expansions such as |
| 1355 | |
| 1356 | server_condition = ${if radius{arguments}{yes}{no}} |
| 1357 | |
| 1358 | . User authentication can now also be done by attempting to bind to an LDAP |
| 1359 | server. The syntax is again similar to PAM and Radius. |
| 1360 | |
| 1361 | server_condition = ${if ldapauth{ldap query}{yes}{no}} |
| 1362 | |
| 1363 | A user and password are required to be supplied with the query. No actual |
| 1364 | data is looked up; Exim just does a bind to the LDAP server and sets the |
| 1365 | condition according to the result. Here's an example of an SMTP |
| 1366 | authenticator: |
| 1367 | |
| 1368 | login: |
| 1369 | driver = plaintext |
| 1370 | public_name = LOGIN |
| 1371 | server_prompts = "Username:: : Password::" |
| 1372 | server_condition = ${if ldapauth \ |
| 1373 | {user="uid=${quote_ldap:$1},ou=people,o=example.org" pass="$2" \ |
| 1374 | ldap://ldap.example.org/}{yes}{no}} |
| 1375 | server_set_id = uid=$1,ou=people,o=example.org |
| 1376 | |
| 1377 | |
| 1378 | |
| 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 |