| 1 | Specification of the Exim Mail Transfer Agent |
| 2 | |
| 3 | Exim Maintainers |
| 4 | |
| 5 | Copyright (c) 2017 University of Cambridge |
| 6 | |
| 7 | Revision 4.89 07 Mar 2017 EM |
| 8 | |
| 9 | ------------------------------------------------------------------------------- |
| 10 | |
| 11 | TABLE OF CONTENTS |
| 12 | |
| 13 | 1. Introduction |
| 14 | |
| 15 | 1.1. Exim documentation |
| 16 | 1.2. FTP and web sites |
| 17 | 1.3. Mailing lists |
| 18 | 1.4. Exim training |
| 19 | 1.5. Bug reports |
| 20 | 1.6. Where to find the Exim distribution |
| 21 | 1.7. Limitations |
| 22 | 1.8. Run time configuration |
| 23 | 1.9. Calling interface |
| 24 | 1.10. Terminology |
| 25 | |
| 26 | 2. Incorporated code |
| 27 | 3. How Exim receives and delivers mail |
| 28 | |
| 29 | 3.1. Overall philosophy |
| 30 | 3.2. Policy control |
| 31 | 3.3. User filters |
| 32 | 3.4. Message identification |
| 33 | 3.5. Receiving mail |
| 34 | 3.6. Handling an incoming message |
| 35 | 3.7. Life of a message |
| 36 | 3.8. Processing an address for delivery |
| 37 | 3.9. Processing an address for verification |
| 38 | 3.10. Running an individual router |
| 39 | 3.11. Duplicate addresses |
| 40 | 3.12. Router preconditions |
| 41 | 3.13. Delivery in detail |
| 42 | 3.14. Retry mechanism |
| 43 | 3.15. Temporary delivery failure |
| 44 | 3.16. Permanent delivery failure |
| 45 | 3.17. Failures to deliver bounce messages |
| 46 | |
| 47 | 4. Building and installing Exim |
| 48 | |
| 49 | 4.1. Unpacking |
| 50 | 4.2. Multiple machine architectures and operating systems |
| 51 | 4.3. PCRE library |
| 52 | 4.4. DBM libraries |
| 53 | 4.5. Pre-building configuration |
| 54 | 4.6. Support for iconv() |
| 55 | 4.7. Including TLS/SSL encryption support |
| 56 | 4.8. Use of tcpwrappers |
| 57 | 4.9. Including support for IPv6 |
| 58 | 4.10. Dynamically loaded lookup module support |
| 59 | 4.11. The building process |
| 60 | 4.12. Output from "make" |
| 61 | 4.13. Overriding build-time options for Exim |
| 62 | 4.14. OS-specific header files |
| 63 | 4.15. Overriding build-time options for the monitor |
| 64 | 4.16. Installing Exim binaries and scripts |
| 65 | 4.17. Installing info documentation |
| 66 | 4.18. Setting up the spool directory |
| 67 | 4.19. Testing |
| 68 | 4.20. Replacing another MTA with Exim |
| 69 | 4.21. Upgrading Exim |
| 70 | 4.22. Stopping the Exim daemon on Solaris |
| 71 | |
| 72 | 5. The Exim command line |
| 73 | |
| 74 | 5.1. Setting options by program name |
| 75 | 5.2. Trusted and admin users |
| 76 | 5.3. Command line options |
| 77 | |
| 78 | 6. The Exim run time configuration file |
| 79 | |
| 80 | 6.1. Using a different configuration file |
| 81 | 6.2. Configuration file format |
| 82 | 6.3. File inclusions in the configuration file |
| 83 | 6.4. Macros in the configuration file |
| 84 | 6.5. Macro substitution |
| 85 | 6.6. Redefining macros |
| 86 | 6.7. Overriding macro values |
| 87 | 6.8. Example of macro usage |
| 88 | 6.9. Builtin macros |
| 89 | 6.10. Conditional skips in the configuration file |
| 90 | 6.11. Common option syntax |
| 91 | 6.12. Boolean options |
| 92 | 6.13. Integer values |
| 93 | 6.14. Octal integer values |
| 94 | 6.15. Fixed point numbers |
| 95 | 6.16. Time intervals |
| 96 | 6.17. String values |
| 97 | 6.18. Expanded strings |
| 98 | 6.19. User and group names |
| 99 | 6.20. List construction |
| 100 | 6.21. Changing list separators |
| 101 | 6.22. Empty items in lists |
| 102 | 6.23. Format of driver configurations |
| 103 | |
| 104 | 7. The default configuration file |
| 105 | |
| 106 | 7.1. Main configuration settings |
| 107 | 7.2. ACL configuration |
| 108 | 7.3. Router configuration |
| 109 | 7.4. Transport configuration |
| 110 | 7.5. Default retry rule |
| 111 | 7.6. Rewriting configuration |
| 112 | 7.7. Authenticators configuration |
| 113 | |
| 114 | 8. Regular expressions |
| 115 | 9. File and database lookups |
| 116 | |
| 117 | 9.1. Examples of different lookup syntax |
| 118 | 9.2. Lookup types |
| 119 | 9.3. Single-key lookup types |
| 120 | 9.4. Query-style lookup types |
| 121 | 9.5. Temporary errors in lookups |
| 122 | 9.6. Default values in single-key lookups |
| 123 | 9.7. Partial matching in single-key lookups |
| 124 | 9.8. Lookup caching |
| 125 | 9.9. Quoting lookup data |
| 126 | 9.10. More about dnsdb |
| 127 | 9.11. Dnsdb lookup modifiers |
| 128 | 9.12. Pseudo dnsdb record types |
| 129 | 9.13. Multiple dnsdb lookups |
| 130 | 9.14. More about LDAP |
| 131 | 9.15. Format of LDAP queries |
| 132 | 9.16. LDAP quoting |
| 133 | 9.17. LDAP connections |
| 134 | 9.18. LDAP authentication and control information |
| 135 | 9.19. Format of data returned by LDAP |
| 136 | 9.20. More about NIS+ |
| 137 | 9.21. SQL lookups |
| 138 | 9.22. More about MySQL, PostgreSQL, Oracle, InterBase, and Redis |
| 139 | 9.23. Specifying the server in the query |
| 140 | 9.24. Special MySQL features |
| 141 | 9.25. Special PostgreSQL features |
| 142 | 9.26. More about SQLite |
| 143 | 9.27. More about Redis |
| 144 | |
| 145 | 10. Domain, host, address, and local part lists |
| 146 | |
| 147 | 10.1. Expansion of lists |
| 148 | 10.2. Negated items in lists |
| 149 | 10.3. File names in lists |
| 150 | 10.4. An lsearch file is not an out-of-line list |
| 151 | 10.5. Named lists |
| 152 | 10.6. Named lists compared with macros |
| 153 | 10.7. Named list caching |
| 154 | 10.8. Domain lists |
| 155 | 10.9. Host lists |
| 156 | 10.10. Special host list patterns |
| 157 | 10.11. Host list patterns that match by IP address |
| 158 | 10.12. Host list patterns for single-key lookups by host address |
| 159 | 10.13. Host list patterns that match by host name |
| 160 | 10.14. Behaviour when an IP address or name cannot be found |
| 161 | 10.15. Mixing wildcarded host names and addresses in host lists |
| 162 | 10.16. Temporary DNS errors when looking up host information |
| 163 | 10.17. Host list patterns for single-key lookups by host name |
| 164 | 10.18. Host list patterns for query-style lookups |
| 165 | 10.19. Address lists |
| 166 | 10.20. Case of letters in address lists |
| 167 | 10.21. Local part lists |
| 168 | |
| 169 | 11. String expansions |
| 170 | |
| 171 | 11.1. Literal text in expanded strings |
| 172 | 11.2. Character escape sequences in expanded strings |
| 173 | 11.3. Testing string expansions |
| 174 | 11.4. Forced expansion failure |
| 175 | 11.5. Expansion items |
| 176 | 11.6. Expansion operators |
| 177 | 11.7. Expansion conditions |
| 178 | 11.8. Combining expansion conditions |
| 179 | 11.9. Expansion variables |
| 180 | |
| 181 | 12. Embedded Perl |
| 182 | |
| 183 | 12.1. Setting up so Perl can be used |
| 184 | 12.2. Calling Perl subroutines |
| 185 | 12.3. Calling Exim functions from Perl |
| 186 | 12.4. Use of standard output and error by Perl |
| 187 | |
| 188 | 13. Starting the daemon and the use of network interfaces |
| 189 | |
| 190 | 13.1. Starting a listening daemon |
| 191 | 13.2. Special IP listening addresses |
| 192 | 13.3. Overriding local_interfaces and daemon_smtp_ports |
| 193 | 13.4. Support for the obsolete SSMTP (or SMTPS) protocol |
| 194 | 13.5. IPv6 address scopes |
| 195 | 13.6. Disabling IPv6 |
| 196 | 13.7. Examples of starting a listening daemon |
| 197 | 13.8. Recognizing the local host |
| 198 | 13.9. Delivering to a remote host |
| 199 | |
| 200 | 14. Main configuration |
| 201 | |
| 202 | 14.1. Miscellaneous |
| 203 | 14.2. Exim parameters |
| 204 | 14.3. Privilege controls |
| 205 | 14.4. Logging |
| 206 | 14.5. Frozen messages |
| 207 | 14.6. Data lookups |
| 208 | 14.7. Message ids |
| 209 | 14.8. Embedded Perl Startup |
| 210 | 14.9. Daemon |
| 211 | 14.10. Resource control |
| 212 | 14.11. Policy controls |
| 213 | 14.12. Callout cache |
| 214 | 14.13. TLS |
| 215 | 14.14. Local user handling |
| 216 | 14.15. All incoming messages (SMTP and non-SMTP) |
| 217 | 14.16. Non-SMTP incoming messages |
| 218 | 14.17. Incoming SMTP messages |
| 219 | 14.18. SMTP extensions |
| 220 | 14.19. Processing messages |
| 221 | 14.20. System filter |
| 222 | 14.21. Routing and delivery |
| 223 | 14.22. Bounce and warning messages |
| 224 | 14.23. Alphabetical list of main options |
| 225 | |
| 226 | 15. Generic options for routers |
| 227 | 16. The accept router |
| 228 | 17. The dnslookup router |
| 229 | |
| 230 | 17.1. Problems with DNS lookups |
| 231 | 17.2. Declining addresses by dnslookup |
| 232 | 17.3. Private options for dnslookup |
| 233 | 17.4. Effect of qualify_single and search_parents |
| 234 | |
| 235 | 18. The ipliteral router |
| 236 | 19. The iplookup router |
| 237 | 20. The manualroute router |
| 238 | |
| 239 | 20.1. Private options for manualroute |
| 240 | 20.2. Routing rules in route_list |
| 241 | 20.3. Routing rules in route_data |
| 242 | 20.4. Format of the list of hosts |
| 243 | 20.5. Format of one host item |
| 244 | 20.6. How the list of hosts is used |
| 245 | 20.7. How the options are used |
| 246 | 20.8. Manualroute examples |
| 247 | |
| 248 | 21. The queryprogram router |
| 249 | 22. The redirect router |
| 250 | |
| 251 | 22.1. Redirection data |
| 252 | 22.2. Forward files and address verification |
| 253 | 22.3. Interpreting redirection data |
| 254 | 22.4. Items in a non-filter redirection list |
| 255 | 22.5. Redirecting to a local mailbox |
| 256 | 22.6. Special items in redirection lists |
| 257 | 22.7. Duplicate addresses |
| 258 | 22.8. Repeated redirection expansion |
| 259 | 22.9. Errors in redirection lists |
| 260 | 22.10. Private options for the redirect router |
| 261 | |
| 262 | 23. Environment for running local transports |
| 263 | |
| 264 | 23.1. Concurrent deliveries |
| 265 | 23.2. Uids and gids |
| 266 | 23.3. Current and home directories |
| 267 | 23.4. Expansion variables derived from the address |
| 268 | |
| 269 | 24. Generic options for transports |
| 270 | 25. Address batching in local transports |
| 271 | 26. The appendfile transport |
| 272 | |
| 273 | 26.1. The file and directory options |
| 274 | 26.2. Private options for appendfile |
| 275 | 26.3. Operational details for appending |
| 276 | 26.4. Operational details for delivery to a new file |
| 277 | 26.5. Maildir delivery |
| 278 | 26.6. Using tags to record message sizes |
| 279 | 26.7. Using a maildirsize file |
| 280 | 26.8. Mailstore delivery |
| 281 | 26.9. Non-special new file delivery |
| 282 | |
| 283 | 27. The autoreply transport |
| 284 | |
| 285 | 27.1. Private options for autoreply |
| 286 | |
| 287 | 28. The lmtp transport |
| 288 | 29. The pipe transport |
| 289 | |
| 290 | 29.1. Concurrent delivery |
| 291 | 29.2. Returned status and data |
| 292 | 29.3. How the command is run |
| 293 | 29.4. Environment variables |
| 294 | 29.5. Private options for pipe |
| 295 | 29.6. Using an external local delivery agent |
| 296 | |
| 297 | 30. The smtp transport |
| 298 | |
| 299 | 30.1. Multiple messages on a single connection |
| 300 | 30.2. Use of the $host and $host_address variables |
| 301 | 30.3. Use of $tls_cipher and $tls_peerdn |
| 302 | 30.4. Private options for smtp |
| 303 | 30.5. How the limits for the number of hosts to try are used |
| 304 | |
| 305 | 31. Address rewriting |
| 306 | |
| 307 | 31.1. Explicitly configured address rewriting |
| 308 | 31.2. When does rewriting happen? |
| 309 | 31.3. Testing the rewriting rules that apply on input |
| 310 | 31.4. Rewriting rules |
| 311 | 31.5. Rewriting patterns |
| 312 | 31.6. Rewriting replacements |
| 313 | 31.7. Rewriting flags |
| 314 | 31.8. Flags specifying which headers and envelope addresses to rewrite |
| 315 | 31.9. The SMTP-time rewriting flag |
| 316 | 31.10. Flags controlling the rewriting process |
| 317 | 31.11. Rewriting examples |
| 318 | |
| 319 | 32. Retry configuration |
| 320 | |
| 321 | 32.1. Changing retry rules |
| 322 | 32.2. Format of retry rules |
| 323 | 32.3. Choosing which retry rule to use for address errors |
| 324 | 32.4. Choosing which retry rule to use for host and message errors |
| 325 | 32.5. Retry rules for specific errors |
| 326 | 32.6. Retry rules for specified senders |
| 327 | 32.7. Retry parameters |
| 328 | 32.8. Retry rule examples |
| 329 | 32.9. Timeout of retry data |
| 330 | 32.10. Long-term failures |
| 331 | 32.11. Deliveries that work intermittently |
| 332 | |
| 333 | 33. SMTP authentication |
| 334 | |
| 335 | 33.1. Generic options for authenticators |
| 336 | 33.2. The AUTH parameter on MAIL commands |
| 337 | 33.3. Authentication on an Exim server |
| 338 | 33.4. Testing server authentication |
| 339 | 33.5. Authentication by an Exim client |
| 340 | |
| 341 | 34. The plaintext authenticator |
| 342 | |
| 343 | 34.1. Plaintext options |
| 344 | 34.2. Using plaintext in a server |
| 345 | 34.3. The PLAIN authentication mechanism |
| 346 | 34.4. The LOGIN authentication mechanism |
| 347 | 34.5. Support for different kinds of authentication |
| 348 | 34.6. Using plaintext in a client |
| 349 | |
| 350 | 35. The cram_md5 authenticator |
| 351 | |
| 352 | 35.1. Using cram_md5 as a server |
| 353 | 35.2. Using cram_md5 as a client |
| 354 | |
| 355 | 36. The cyrus_sasl authenticator |
| 356 | |
| 357 | 36.1. Using cyrus_sasl as a server |
| 358 | |
| 359 | 37. The dovecot authenticator |
| 360 | 38. The gsasl authenticator |
| 361 | |
| 362 | 38.1. gsasl auth variables |
| 363 | |
| 364 | 39. The heimdal_gssapi authenticator |
| 365 | |
| 366 | 39.1. heimdal_gssapi auth variables |
| 367 | |
| 368 | 40. The spa authenticator |
| 369 | |
| 370 | 40.1. Using spa as a server |
| 371 | 40.2. Using spa as a client |
| 372 | |
| 373 | 41. The tls authenticator |
| 374 | 42. Encrypted SMTP connections using TLS/SSL |
| 375 | |
| 376 | 42.1. Support for the legacy "ssmtp" (aka "smtps") protocol |
| 377 | 42.2. OpenSSL vs GnuTLS |
| 378 | 42.3. GnuTLS parameter computation |
| 379 | 42.4. Requiring specific ciphers in OpenSSL |
| 380 | 42.5. Requiring specific ciphers or other parameters in GnuTLS |
| 381 | 42.6. Configuring an Exim server to use TLS |
| 382 | 42.7. Requesting and verifying client certificates |
| 383 | 42.8. Revoked certificates |
| 384 | 42.9. Configuring an Exim client to use TLS |
| 385 | 42.10. Use of TLS Server Name Indication |
| 386 | 42.11. Multiple messages on the same encrypted TCP/IP connection |
| 387 | 42.12. Certificates and all that |
| 388 | 42.13. Certificate chains |
| 389 | 42.14. Self-signed certificates |
| 390 | |
| 391 | 43. Access control lists |
| 392 | |
| 393 | 43.1. Testing ACLs |
| 394 | 43.2. Specifying when ACLs are used |
| 395 | 43.3. The non-SMTP ACLs |
| 396 | 43.4. The SMTP connect ACL |
| 397 | 43.5. The EHLO/HELO ACL |
| 398 | 43.6. The DATA ACLs |
| 399 | 43.7. The SMTP DKIM ACL |
| 400 | 43.8. The SMTP MIME ACL |
| 401 | 43.9. The SMTP PRDR ACL |
| 402 | 43.10. The QUIT ACL |
| 403 | 43.11. The not-QUIT ACL |
| 404 | 43.12. Finding an ACL to use |
| 405 | 43.13. ACL return codes |
| 406 | 43.14. Unset ACL options |
| 407 | 43.15. Data for message ACLs |
| 408 | 43.16. Data for non-message ACLs |
| 409 | 43.17. Format of an ACL |
| 410 | 43.18. ACL verbs |
| 411 | 43.19. ACL variables |
| 412 | 43.20. Condition and modifier processing |
| 413 | 43.21. ACL modifiers |
| 414 | 43.22. Use of the control modifier |
| 415 | 43.23. Summary of message fixup control |
| 416 | 43.24. Adding header lines in ACLs |
| 417 | 43.25. Removing header lines in ACLs |
| 418 | 43.26. ACL conditions |
| 419 | 43.27. Using DNS lists |
| 420 | 43.28. Specifying the IP address for a DNS list lookup |
| 421 | 43.29. DNS lists keyed on domain names |
| 422 | 43.30. Multiple explicit keys for a DNS list |
| 423 | 43.31. Data returned by DNS lists |
| 424 | 43.32. Variables set from DNS lists |
| 425 | 43.33. Additional matching conditions for DNS lists |
| 426 | 43.34. Negated DNS matching conditions |
| 427 | 43.35. Handling multiple DNS records from a DNS list |
| 428 | 43.36. Detailed information from merged DNS lists |
| 429 | 43.37. DNS lists and IPv6 |
| 430 | 43.38. Rate limiting incoming messages |
| 431 | 43.39. Ratelimit options for what is being measured |
| 432 | 43.40. Ratelimit update modes |
| 433 | 43.41. Ratelimit options for handling fast clients |
| 434 | 43.42. Limiting the rate of different events |
| 435 | 43.43. Using rate limiting |
| 436 | 43.44. Address verification |
| 437 | 43.45. Callout verification |
| 438 | 43.46. Additional parameters for callouts |
| 439 | 43.47. Callout caching |
| 440 | 43.48. Sender address verification reporting |
| 441 | 43.49. Redirection while verifying |
| 442 | 43.50. Client SMTP authorization (CSA) |
| 443 | 43.51. Bounce address tag validation |
| 444 | 43.52. Using an ACL to control relaying |
| 445 | 43.53. Checking a relay configuration |
| 446 | |
| 447 | 44. Content scanning at ACL time |
| 448 | |
| 449 | 44.1. Scanning for viruses |
| 450 | 44.2. Scanning with SpamAssassin and Rspamd |
| 451 | 44.3. Calling SpamAssassin from an Exim ACL |
| 452 | 44.4. Scanning MIME parts |
| 453 | 44.5. Scanning with regular expressions |
| 454 | |
| 455 | 45. Adding a local scan function to Exim |
| 456 | |
| 457 | 45.1. Building Exim to use a local scan function |
| 458 | 45.2. API for local_scan() |
| 459 | 45.3. Configuration options for local_scan() |
| 460 | 45.4. Available Exim variables |
| 461 | 45.5. Structure of header lines |
| 462 | 45.6. Structure of recipient items |
| 463 | 45.7. Available Exim functions |
| 464 | 45.8. More about Exim's memory handling |
| 465 | |
| 466 | 46. System-wide message filtering |
| 467 | |
| 468 | 46.1. Specifying a system filter |
| 469 | 46.2. Testing a system filter |
| 470 | 46.3. Contents of a system filter |
| 471 | 46.4. Additional variable for system filters |
| 472 | 46.5. Defer, freeze, and fail commands for system filters |
| 473 | 46.6. Adding and removing headers in a system filter |
| 474 | 46.7. Setting an errors address in a system filter |
| 475 | 46.8. Per-address filtering |
| 476 | |
| 477 | 47. Message processing |
| 478 | |
| 479 | 47.1. Submission mode for non-local messages |
| 480 | 47.2. Line endings |
| 481 | 47.3. Unqualified addresses |
| 482 | 47.4. The UUCP From line |
| 483 | 47.5. Resent- header lines |
| 484 | 47.6. The Auto-Submitted: header line |
| 485 | 47.7. The Bcc: header line |
| 486 | 47.8. The Date: header line |
| 487 | 47.9. The Delivery-date: header line |
| 488 | 47.10. The Envelope-to: header line |
| 489 | 47.11. The From: header line |
| 490 | 47.12. The Message-ID: header line |
| 491 | 47.13. The Received: header line |
| 492 | 47.14. The References: header line |
| 493 | 47.15. The Return-path: header line |
| 494 | 47.16. The Sender: header line |
| 495 | 47.17. Adding and removing header lines in routers and transports |
| 496 | 47.18. Constructed addresses |
| 497 | 47.19. Case of local parts |
| 498 | 47.20. Dots in local parts |
| 499 | 47.21. Rewriting addresses |
| 500 | |
| 501 | 48. SMTP processing |
| 502 | |
| 503 | 48.1. Outgoing SMTP and LMTP over TCP/IP |
| 504 | 48.2. Errors in outgoing SMTP |
| 505 | 48.3. Incoming SMTP messages over TCP/IP |
| 506 | 48.4. Unrecognized SMTP commands |
| 507 | 48.5. Syntax and protocol errors in SMTP commands |
| 508 | 48.6. Use of non-mail SMTP commands |
| 509 | 48.7. The VRFY and EXPN commands |
| 510 | 48.8. The ETRN command |
| 511 | 48.9. Incoming local SMTP |
| 512 | 48.10. Outgoing batched SMTP |
| 513 | 48.11. Incoming batched SMTP |
| 514 | |
| 515 | 49. Customizing bounce and warning messages |
| 516 | |
| 517 | 49.1. Customizing bounce messages |
| 518 | 49.2. Customizing warning messages |
| 519 | |
| 520 | 50. Some common configuration settings |
| 521 | |
| 522 | 50.1. Sending mail to a smart host |
| 523 | 50.2. Using Exim to handle mailing lists |
| 524 | 50.3. Syntax errors in mailing lists |
| 525 | 50.4. Re-expansion of mailing lists |
| 526 | 50.5. Closed mailing lists |
| 527 | 50.6. Variable Envelope Return Paths (VERP) |
| 528 | 50.7. Virtual domains |
| 529 | 50.8. Multiple user mailboxes |
| 530 | 50.9. Simplified vacation processing |
| 531 | 50.10. Taking copies of mail |
| 532 | 50.11. Intermittently connected hosts |
| 533 | 50.12. Exim on the upstream server host |
| 534 | 50.13. Exim on the intermittently connected client host |
| 535 | |
| 536 | 51. Using Exim as a non-queueing client |
| 537 | 52. Log files |
| 538 | |
| 539 | 52.1. Where the logs are written |
| 540 | 52.2. Logging to local files that are periodically "cycled" |
| 541 | 52.3. Datestamped log files |
| 542 | 52.4. Logging to syslog |
| 543 | 52.5. Log line flags |
| 544 | 52.6. Logging message reception |
| 545 | 52.7. Logging deliveries |
| 546 | 52.8. Discarded deliveries |
| 547 | 52.9. Deferred deliveries |
| 548 | 52.10. Delivery failures |
| 549 | 52.11. Fake deliveries |
| 550 | 52.12. Completion |
| 551 | 52.13. Summary of Fields in Log Lines |
| 552 | 52.14. Other log entries |
| 553 | 52.15. Reducing or increasing what is logged |
| 554 | 52.16. Message log |
| 555 | |
| 556 | 53. Exim utilities |
| 557 | |
| 558 | 53.1. Finding out what Exim processes are doing (exiwhat) |
| 559 | 53.2. Selective queue listing (exiqgrep) |
| 560 | 53.3. Summarizing the queue (exiqsumm) |
| 561 | 53.4. Extracting specific information from the log (exigrep) |
| 562 | 53.5. Selecting messages by various criteria (exipick) |
| 563 | 53.6. Cycling log files (exicyclog) |
| 564 | 53.7. Mail statistics (eximstats) |
| 565 | 53.8. Checking access policy (exim_checkaccess) |
| 566 | 53.9. Making DBM files (exim_dbmbuild) |
| 567 | 53.10. Finding individual retry times (exinext) |
| 568 | 53.11. Hints database maintenance |
| 569 | 53.12. exim_dumpdb |
| 570 | 53.13. exim_tidydb |
| 571 | 53.14. exim_fixdb |
| 572 | 53.15. Mailbox maintenance (exim_lock) |
| 573 | |
| 574 | 54. The Exim monitor |
| 575 | |
| 576 | 54.1. Running the monitor |
| 577 | 54.2. The stripcharts |
| 578 | 54.3. Main action buttons |
| 579 | 54.4. The log display |
| 580 | 54.5. The queue display |
| 581 | 54.6. The queue menu |
| 582 | |
| 583 | 55. Security considerations |
| 584 | |
| 585 | 55.1. Building a more "hardened" Exim |
| 586 | 55.2. Root privilege |
| 587 | 55.3. Running Exim without privilege |
| 588 | 55.4. Delivering to local files |
| 589 | 55.5. Running local commands |
| 590 | 55.6. Trust in configuration data |
| 591 | 55.7. IPv4 source routing |
| 592 | 55.8. The VRFY, EXPN, and ETRN commands in SMTP |
| 593 | 55.9. Privileged users |
| 594 | 55.10. Spool files |
| 595 | 55.11. Use of argv[0] |
| 596 | 55.12. Use of %f formatting |
| 597 | 55.13. Embedded Exim path |
| 598 | 55.14. Dynamic module directory |
| 599 | 55.15. Use of sprintf() |
| 600 | 55.16. Use of debug_printf() and log_write() |
| 601 | 55.17. Use of strcat() and strcpy() |
| 602 | |
| 603 | 56. Format of spool files |
| 604 | |
| 605 | 56.1. Format of the -H file |
| 606 | |
| 607 | 57. Support for DKIM (DomainKeys Identified Mail) |
| 608 | |
| 609 | 57.1. Signing outgoing messages |
| 610 | 57.2. Verifying DKIM signatures in incoming mail |
| 611 | |
| 612 | 58. Proxies |
| 613 | |
| 614 | 58.1. Inbound proxies |
| 615 | 58.2. Outbound proxies |
| 616 | 58.3. Logging |
| 617 | |
| 618 | 59. Internationalisation |
| 619 | |
| 620 | 59.1. MTA operations |
| 621 | 59.2. MDA operations |
| 622 | |
| 623 | 60. Events |
| 624 | 61. Adding new drivers or lookup types |
| 625 | |
| 626 | |
| 627 | |
| 628 | =============================================================================== |
| 629 | 1. INTRODUCTION |
| 630 | |
| 631 | Exim is a mail transfer agent (MTA) for hosts that are running Unix or |
| 632 | Unix-like operating systems. It was designed on the assumption that it would be |
| 633 | run on hosts that are permanently connected to the Internet. However, it can be |
| 634 | used on intermittently connected hosts with suitable configuration adjustments. |
| 635 | |
| 636 | Configuration files currently exist for the following operating systems: AIX, |
| 637 | BSD/OS (aka BSDI), Darwin (Mac OS X), DGUX, Dragonfly, FreeBSD, GNU/Hurd, GNU/ |
| 638 | Linux, HI-OSF (Hitachi), HI-UX, HP-UX, IRIX, MIPS RISCOS, NetBSD, OpenBSD, |
| 639 | OpenUNIX, QNX, SCO, SCO SVR4.2 (aka UNIX-SV), Solaris (aka SunOS5), SunOS4, |
| 640 | Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1), Ultrix, and Unixware. |
| 641 | Some of these operating systems are no longer current and cannot easily be |
| 642 | tested, so the configuration files may no longer work in practice. |
| 643 | |
| 644 | There are also configuration files for compiling Exim in the Cygwin environment |
| 645 | that can be installed on systems running Windows. However, this document does |
| 646 | not contain any information about running Exim in the Cygwin environment. |
| 647 | |
| 648 | The terms and conditions for the use and distribution of Exim are contained in |
| 649 | the file NOTICE. Exim is distributed under the terms of the GNU General Public |
| 650 | Licence, a copy of which may be found in the file LICENCE. |
| 651 | |
| 652 | The use, supply or promotion of Exim for the purpose of sending bulk, |
| 653 | unsolicited electronic mail is incompatible with the basic aims of the program, |
| 654 | which revolve around the free provision of a service that enhances the quality |
| 655 | of personal communications. The author of Exim regards indiscriminate |
| 656 | mass-mailing as an antisocial, irresponsible abuse of the Internet. |
| 657 | |
| 658 | Exim owes a great deal to Smail 3 and its author, Ron Karr. Without the |
| 659 | experience of running and working on the Smail 3 code, I could never have |
| 660 | contemplated starting to write a new MTA. Many of the ideas and user interfaces |
| 661 | were originally taken from Smail 3, though the actual code of Exim is entirely |
| 662 | new, and has developed far beyond the initial concept. |
| 663 | |
| 664 | Many people, both in Cambridge and around the world, have contributed to the |
| 665 | development and the testing of Exim, and to porting it to various operating |
| 666 | systems. I am grateful to them all. The distribution now contains a file called |
| 667 | ACKNOWLEDGMENTS, in which I have started recording the names of contributors. |
| 668 | |
| 669 | |
| 670 | 1.1 Exim documentation |
| 671 | ---------------------- |
| 672 | |
| 673 | This edition of the Exim specification applies to version 4.89 of Exim. |
| 674 | Substantive changes from the 4.88 edition are marked in some renditions of the |
| 675 | document; this paragraph is so marked if the rendition is capable of showing a |
| 676 | change indicator. |
| 677 | |
| 678 | This document is very much a reference manual; it is not a tutorial. The reader |
| 679 | is expected to have some familiarity with the SMTP mail transfer protocol and |
| 680 | with general Unix system administration. Although there are some discussions |
| 681 | and examples in places, the information is mostly organized in a way that makes |
| 682 | it easy to look up, rather than in a natural order for sequential reading. |
| 683 | Furthermore, the manual aims to cover every aspect of Exim in detail, including |
| 684 | a number of rarely-used, special-purpose features that are unlikely to be of |
| 685 | very wide interest. |
| 686 | |
| 687 | An "easier" discussion of Exim which provides more in-depth explanatory, |
| 688 | introductory, and tutorial material can be found in a book entitled The Exim |
| 689 | SMTP Mail Server (second edition, 2007), published by UIT Cambridge (http:// |
| 690 | www.uit.co.uk/exim-book/). |
| 691 | |
| 692 | This book also contains a chapter that gives a general introduction to SMTP and |
| 693 | Internet mail. Inevitably, however, the book is unlikely to be fully up-to-date |
| 694 | with the latest release of Exim. (Note that the earlier book about Exim, |
| 695 | published by O'Reilly, covers Exim 3, and many things have changed in Exim 4.) |
| 696 | |
| 697 | If you are using a Debian distribution of Exim, you will find information about |
| 698 | Debian-specific features in the file /usr/share/doc/exim4-base/README.Debian. |
| 699 | The command man update-exim.conf is another source of Debian-specific |
| 700 | information. |
| 701 | |
| 702 | As the program develops, there may be features in newer versions that have not |
| 703 | yet made it into this document, which is updated only when the most significant |
| 704 | digit of the fractional part of the version number changes. Specifications of |
| 705 | new features that are not yet in this manual are placed in the file doc/ |
| 706 | NewStuff in the Exim distribution. |
| 707 | |
| 708 | Some features may be classified as "experimental". These may change |
| 709 | incompatibly while they are developing, or even be withdrawn. For this reason, |
| 710 | they are not documented in this manual. Information about experimental features |
| 711 | can be found in the file doc/experimental.txt. |
| 712 | |
| 713 | All changes to the program (whether new features, bug fixes, or other kinds of |
| 714 | change) are noted briefly in the file called doc/ChangeLog. |
| 715 | |
| 716 | This specification itself is available as an ASCII file in doc/spec.txt so that |
| 717 | it can easily be searched with a text editor. Other files in the doc directory |
| 718 | are: |
| 719 | |
| 720 | OptionLists.txt list of all options in alphabetical order |
| 721 | dbm.discuss.txt discussion about DBM libraries |
| 722 | exim.8 a man page of Exim's command line options |
| 723 | experimental.txt documentation of experimental features |
| 724 | filter.txt specification of the filter language |
| 725 | Exim3.upgrade upgrade notes from release 2 to release 3 |
| 726 | Exim4.upgrade upgrade notes from release 3 to release 4 |
| 727 | openssl.txt installing a current OpenSSL release |
| 728 | |
| 729 | The main specification and the specification of the filtering language are also |
| 730 | available in other formats (HTML, PostScript, PDF, and Texinfo). Section 1.6 |
| 731 | below tells you how to get hold of these. |
| 732 | |
| 733 | |
| 734 | 1.2 FTP and web sites |
| 735 | --------------------- |
| 736 | |
| 737 | The primary site for Exim source distributions is currently the University of |
| 738 | Cambridge's FTP site, whose contents are described in Where to find the Exim |
| 739 | distribution below. In addition, there is a web site and an FTP site at |
| 740 | exim.org. These are now also hosted at the University of Cambridge. The |
| 741 | exim.org site was previously hosted for a number of years by Energis Squared, |
| 742 | formerly Planet Online Ltd, whose support I gratefully acknowledge. |
| 743 | |
| 744 | As well as Exim distribution tar files, the Exim web site contains a number of |
| 745 | differently formatted versions of the documentation. A recent addition to the |
| 746 | online information is the Exim wiki (http://wiki.exim.org), which contains what |
| 747 | used to be a separate FAQ, as well as various other examples, tips, and |
| 748 | know-how that have been contributed by Exim users. |
| 749 | |
| 750 | An Exim Bugzilla exists at http://bugs.exim.org. You can use this to report |
| 751 | bugs, and also to add items to the wish list. Please search first to check that |
| 752 | you are not duplicating a previous entry. |
| 753 | |
| 754 | |
| 755 | 1.3 Mailing lists |
| 756 | ----------------- |
| 757 | |
| 758 | The following Exim mailing lists exist: |
| 759 | |
| 760 | exim-announce@exim.org Moderated, low volume announcements list |
| 761 | exim-users@exim.org General discussion list |
| 762 | exim-dev@exim.org Discussion of bugs, enhancements, etc. |
| 763 | exim-cvs@exim.org Automated commit messages from the VCS |
| 764 | |
| 765 | You can subscribe to these lists, change your existing subscriptions, and view |
| 766 | or search the archives via the mailing lists link on the Exim home page. If you |
| 767 | are using a Debian distribution of Exim, you may wish to subscribe to the |
| 768 | Debian-specific mailing list pkg-exim4-users@lists.alioth.debian.org via this |
| 769 | web page: |
| 770 | |
| 771 | http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users |
| 772 | |
| 773 | Please ask Debian-specific questions on this list and not on the general Exim |
| 774 | lists. |
| 775 | |
| 776 | |
| 777 | 1.4 Exim training |
| 778 | ----------------- |
| 779 | |
| 780 | Training courses in Cambridge (UK) used to be run annually by the author of |
| 781 | Exim, before he retired. At the time of writing, there are no plans to run |
| 782 | further Exim courses in Cambridge. However, if that changes, relevant |
| 783 | information will be posted at http://www-tus.csx.cam.ac.uk/courses/exim/. |
| 784 | |
| 785 | |
| 786 | 1.5 Bug reports |
| 787 | --------------- |
| 788 | |
| 789 | Reports of obvious bugs can be emailed to bugs@exim.org or reported via the |
| 790 | Bugzilla (http://bugs.exim.org). However, if you are unsure whether some |
| 791 | behaviour is a bug or not, the best thing to do is to post a message to the |
| 792 | exim-dev mailing list and have it discussed. |
| 793 | |
| 794 | |
| 795 | 1.6 Where to find the Exim distribution |
| 796 | --------------------------------------- |
| 797 | |
| 798 | The master ftp site for the Exim distribution is |
| 799 | |
| 800 | ftp://ftp.csx.cam.ac.uk/pub/software/email/exim |
| 801 | |
| 802 | This is mirrored by |
| 803 | |
| 804 | ftp://ftp.exim.org/pub/exim |
| 805 | |
| 806 | The file references that follow are relative to the exim directories at these |
| 807 | sites. There are now quite a number of independent mirror sites around the |
| 808 | world. Those that I know about are listed in the file called Mirrors. |
| 809 | |
| 810 | Within the exim directory there are subdirectories called exim3 (for previous |
| 811 | Exim 3 distributions), exim4 (for the latest Exim 4 distributions), and Testing |
| 812 | for testing versions. In the exim4 subdirectory, the current release can always |
| 813 | be found in files called |
| 814 | |
| 815 | exim-n.nn.tar.gz |
| 816 | exim-n.nn.tar.bz2 |
| 817 | |
| 818 | where n.nn is the highest such version number in the directory. The two files |
| 819 | contain identical data; the only difference is the type of compression. The |
| 820 | .bz2 file is usually a lot smaller than the .gz file. |
| 821 | |
| 822 | The distributions will be PGP signed by an individual key of the Release |
| 823 | Coordinator. This key will have a uid containing an email address in the |
| 824 | exim.org domain and will have signatures from other people, including other |
| 825 | Exim maintainers. We expect that the key will be in the "strong set" of PGP |
| 826 | keys. There should be a trust path to that key from Nigel Metheringham's PGP |
| 827 | key, a version of which can be found in the release directory in the file |
| 828 | nigel-pubkey.asc. All keys used will be available in public keyserver pools, |
| 829 | such as pool.sks-keyservers.net. |
| 830 | |
| 831 | At time of last update, releases were being made by Phil Pennock and signed |
| 832 | with key 0x403043153903637F, although that key is expected to be replaced in |
| 833 | 2013. A trust path from Nigel's key to Phil's can be observed at https:// |
| 834 | www.security.spodhuis.org/exim-trustpath. |
| 835 | |
| 836 | Releases have also been authorized to be performed by Todd Lyons who signs with |
| 837 | key 0xC4F4F94804D29EBA. A direct trust path exists between previous RE Phil |
| 838 | Pennock and Todd Lyons through a common associate. |
| 839 | |
| 840 | The signatures for the tar bundles are in: |
| 841 | |
| 842 | exim-n.nn.tar.gz.asc |
| 843 | exim-n.nn.tar.bz2.asc |
| 844 | |
| 845 | For each released version, the log of changes is made separately available in a |
| 846 | separate file in the directory ChangeLogs so that it is possible to find out |
| 847 | what has changed without having to download the entire distribution. |
| 848 | |
| 849 | The main distribution contains ASCII versions of this specification and other |
| 850 | documentation; other formats of the documents are available in separate files |
| 851 | inside the exim4 directory of the FTP site: |
| 852 | |
| 853 | exim-html-n.nn.tar.gz |
| 854 | exim-pdf-n.nn.tar.gz |
| 855 | exim-postscript-n.nn.tar.gz |
| 856 | exim-texinfo-n.nn.tar.gz |
| 857 | |
| 858 | These tar files contain only the doc directory, not the complete distribution, |
| 859 | and are also available in .bz2 as well as .gz forms. |
| 860 | |
| 861 | |
| 862 | 1.7 Limitations |
| 863 | --------------- |
| 864 | |
| 865 | * Exim is designed for use as an Internet MTA, and therefore handles |
| 866 | addresses in RFC 2822 domain format only. It cannot handle UUCP "bang |
| 867 | paths", though simple two-component bang paths can be converted by a |
| 868 | straightforward rewriting configuration. This restriction does not prevent |
| 869 | Exim from being interfaced to UUCP as a transport mechanism, provided that |
| 870 | domain addresses are used. |
| 871 | |
| 872 | * Exim insists that every address it handles has a domain attached. For |
| 873 | incoming local messages, domainless addresses are automatically qualified |
| 874 | with a configured domain value. Configuration options specify from which |
| 875 | remote systems unqualified addresses are acceptable. These are then |
| 876 | qualified on arrival. |
| 877 | |
| 878 | * The only external transport mechanisms that are currently implemented are |
| 879 | SMTP and LMTP over a TCP/IP network (including support for IPv6). However, |
| 880 | a pipe transport is available, and there are facilities for writing |
| 881 | messages to files and pipes, optionally in batched SMTP format; these |
| 882 | facilities can be used to send messages to other transport mechanisms such |
| 883 | as UUCP, provided they can handle domain-style addresses. Batched SMTP |
| 884 | input is also catered for. |
| 885 | |
| 886 | * Exim is not designed for storing mail for dial-in hosts. When the volumes |
| 887 | of such mail are large, it is better to get the messages "delivered" into |
| 888 | files (that is, off Exim's queue) and subsequently passed on to the dial-in |
| 889 | hosts by other means. |
| 890 | |
| 891 | * Although Exim does have basic facilities for scanning incoming messages, |
| 892 | these are not comprehensive enough to do full virus or spam scanning. Such |
| 893 | operations are best carried out using additional specialized software |
| 894 | packages. If you compile Exim with the content-scanning extension, |
| 895 | straightforward interfaces to a number of common scanners are provided. |
| 896 | |
| 897 | |
| 898 | 1.8 Run time configuration |
| 899 | -------------------------- |
| 900 | |
| 901 | Exim's run time configuration is held in a single text file that is divided |
| 902 | into a number of sections. The entries in this file consist of keywords and |
| 903 | values, in the style of Smail 3 configuration files. A default configuration |
| 904 | file which is suitable for simple online installations is provided in the |
| 905 | distribution, and is described in chapter 7 below. |
| 906 | |
| 907 | |
| 908 | 1.9 Calling interface |
| 909 | --------------------- |
| 910 | |
| 911 | Like many MTAs, Exim has adopted the Sendmail command line interface so that it |
| 912 | can be a straight replacement for /usr/lib/sendmail or /usr/sbin/sendmail when |
| 913 | sending mail, but you do not need to know anything about Sendmail in order to |
| 914 | run Exim. For actions other than sending messages, Sendmail-compatible options |
| 915 | also exist, but those that produce output (for example, -bp, which lists the |
| 916 | messages on the queue) do so in Exim's own format. There are also some |
| 917 | additional options that are compatible with Smail 3, and some further options |
| 918 | that are new to Exim. Chapter 5 documents all Exim's command line options. This |
| 919 | information is automatically made into the man page that forms part of the Exim |
| 920 | distribution. |
| 921 | |
| 922 | Control of messages on the queue can be done via certain privileged command |
| 923 | line options. There is also an optional monitor program called eximon, which |
| 924 | displays current information in an X window, and which contains a menu |
| 925 | interface to Exim's command line administration options. |
| 926 | |
| 927 | |
| 928 | 1.10 Terminology |
| 929 | ---------------- |
| 930 | |
| 931 | The body of a message is the actual data that the sender wants to transmit. It |
| 932 | is the last part of a message, and is separated from the header (see below) by |
| 933 | a blank line. |
| 934 | |
| 935 | When a message cannot be delivered, it is normally returned to the sender in a |
| 936 | delivery failure message or a "non-delivery report" (NDR). The term bounce is |
| 937 | commonly used for this action, and the error reports are often called bounce |
| 938 | messages. This is a convenient shorthand for "delivery failure error report". |
| 939 | Such messages have an empty sender address in the message's envelope (see |
| 940 | below) to ensure that they cannot themselves give rise to further bounce |
| 941 | messages. |
| 942 | |
| 943 | The term default appears frequently in this manual. It is used to qualify a |
| 944 | value which is used in the absence of any setting in the configuration. It may |
| 945 | also qualify an action which is taken unless a configuration setting specifies |
| 946 | otherwise. |
| 947 | |
| 948 | The term defer is used when the delivery of a message to a specific destination |
| 949 | cannot immediately take place for some reason (a remote host may be down, or a |
| 950 | user's local mailbox may be full). Such deliveries are deferred until a later |
| 951 | time. |
| 952 | |
| 953 | The word domain is sometimes used to mean all but the first component of a |
| 954 | host's name. It is not used in that sense here, where it normally refers to the |
| 955 | part of an email address following the @ sign. |
| 956 | |
| 957 | A message in transit has an associated envelope, as well as a header and a |
| 958 | body. The envelope contains a sender address (to which bounce messages should |
| 959 | be delivered), and any number of recipient addresses. References to the sender |
| 960 | or the recipients of a message usually mean the addresses in the envelope. An |
| 961 | MTA uses these addresses for delivery, and for returning bounce messages, not |
| 962 | the addresses that appear in the header lines. |
| 963 | |
| 964 | The header of a message is the first part of a message's text, consisting of a |
| 965 | number of lines, each of which has a name such as From:, To:, Subject:, etc. |
| 966 | Long header lines can be split over several text lines by indenting the |
| 967 | continuations. The header is separated from the body by a blank line. |
| 968 | |
| 969 | The term local part, which is taken from RFC 2822, is used to refer to that |
| 970 | part of an email address that precedes the @ sign. The part that follows the @ |
| 971 | sign is called the domain or mail domain. |
| 972 | |
| 973 | The terms local delivery and remote delivery are used to distinguish delivery |
| 974 | to a file or a pipe on the local host from delivery by SMTP over TCP/IP to |
| 975 | another host. As far as Exim is concerned, all hosts other than the host it is |
| 976 | running on are remote. |
| 977 | |
| 978 | Return path is another name that is used for the sender address in a message's |
| 979 | envelope. |
| 980 | |
| 981 | The term queue is used to refer to the set of messages awaiting delivery, |
| 982 | because this term is in widespread use in the context of MTAs. However, in |
| 983 | Exim's case the reality is more like a pool than a queue, because there is |
| 984 | normally no ordering of waiting messages. |
| 985 | |
| 986 | The term queue runner is used to describe a process that scans the queue and |
| 987 | attempts to deliver those messages whose retry times have come. This term is |
| 988 | used by other MTAs, and also relates to the command runq, but in Exim the |
| 989 | waiting messages are normally processed in an unpredictable order. |
| 990 | |
| 991 | The term spool directory is used for a directory in which Exim keeps the |
| 992 | messages on its queue - that is, those that it is in the process of delivering. |
| 993 | This should not be confused with the directory in which local mailboxes are |
| 994 | stored, which is called a "spool directory" by some people. In the Exim |
| 995 | documentation, "spool" is always used in the first sense. |
| 996 | |
| 997 | |
| 998 | |
| 999 | =============================================================================== |
| 1000 | 2. INCORPORATED CODE |
| 1001 | |
| 1002 | A number of pieces of external code are included in the Exim distribution. |
| 1003 | |
| 1004 | * Regular expressions are supported in the main Exim program and in the Exim |
| 1005 | monitor using the freely-distributable PCRE library, copyright (c) |
| 1006 | University of Cambridge. The source to PCRE is no longer shipped with Exim, |
| 1007 | so you will need to use the version of PCRE shipped with your system, or |
| 1008 | obtain and install the full version of the library from ftp:// |
| 1009 | ftp.csx.cam.ac.uk/pub/software/programming/pcre. |
| 1010 | |
| 1011 | * Support for the cdb (Constant DataBase) lookup method is provided by code |
| 1012 | contributed by Nigel Metheringham of (at the time he contributed it) Planet |
| 1013 | Online Ltd. The implementation is completely contained within the code of |
| 1014 | Exim. It does not link against an external cdb library. The code contains |
| 1015 | the following statements: |
| 1016 | |
| 1017 | Copyright (c) 1998 Nigel Metheringham, Planet Online Ltd |
| 1018 | |
| 1019 | This program is free software; you can redistribute it and/or modify it |
| 1020 | under the terms of the GNU General Public License as published by the |
| 1021 | Free Software Foundation; either version 2 of the License, or (at your |
| 1022 | option) any later version. This code implements Dan Bernstein's |
| 1023 | Constant DataBase (cdb) spec. Information, the spec and sample code for |
| 1024 | cdb can be obtained from http://www.pobox.com/~djb/cdb.html. This |
| 1025 | implementation borrows some code from Dan Bernstein's implementation |
| 1026 | (which has no license restrictions applied to it). |
| 1027 | |
| 1028 | * Client support for Microsoft's Secure Password Authentication is provided |
| 1029 | by code contributed by Marc Prud'hommeaux. Server support was contributed |
| 1030 | by Tom Kistner. This includes code taken from the Samba project, which is |
| 1031 | released under the Gnu GPL. |
| 1032 | |
| 1033 | * Support for calling the Cyrus pwcheck and saslauthd daemons is provided by |
| 1034 | code taken from the Cyrus-SASL library and adapted by Alexander S. |
| 1035 | Sabourenkov. The permission notice appears below, in accordance with the |
| 1036 | conditions expressed therein. |
| 1037 | |
| 1038 | Copyright (c) 2001 Carnegie Mellon University. All rights reserved. |
| 1039 | |
| 1040 | Redistribution and use in source and binary forms, with or without |
| 1041 | modification, are permitted provided that the following conditions are |
| 1042 | met: |
| 1043 | |
| 1044 | 1. Redistributions of source code must retain the above copyright |
| 1045 | notice, this list of conditions and the following disclaimer. |
| 1046 | |
| 1047 | 2. Redistributions in binary form must reproduce the above copyright |
| 1048 | notice, this list of conditions and the following disclaimer in the |
| 1049 | documentation and/or other materials provided with the |
| 1050 | distribution. |
| 1051 | |
| 1052 | 3. The name "Carnegie Mellon University" must not be used to endorse |
| 1053 | or promote products derived from this software without prior |
| 1054 | written permission. For permission or any other legal details, |
| 1055 | please contact |
| 1056 | |
| 1057 | Office of Technology Transfer |
| 1058 | Carnegie Mellon University |
| 1059 | 5000 Forbes Avenue |
| 1060 | Pittsburgh, PA 15213-3890 |
| 1061 | (412) 268-4387, fax: (412) 268-7395 |
| 1062 | tech-transfer@andrew.cmu.edu |
| 1063 | |
| 1064 | 4. Redistributions of any form whatsoever must retain the following |
| 1065 | acknowledgment: |
| 1066 | |
| 1067 | "This product includes software developed by Computing Services at |
| 1068 | Carnegie Mellon University (http://www.cmu.edu/computing/." |
| 1069 | |
| 1070 | CARNEGIE MELLON UNIVERSITY DISCLAIMS ALL WARRANTIES WITH REGARD TO |
| 1071 | THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY |
| 1072 | AND FITNESS, IN NO EVENT SHALL CARNEGIE MELLON UNIVERSITY BE LIABLE |
| 1073 | FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES |
| 1074 | WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN |
| 1075 | AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING |
| 1076 | OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS |
| 1077 | SOFTWARE. |
| 1078 | |
| 1079 | * The Exim Monitor program, which is an X-Window application, includes |
| 1080 | modified versions of the Athena StripChart and TextPop widgets. This code |
| 1081 | is copyright by DEC and MIT, and their permission notice appears below, in |
| 1082 | accordance with the conditions expressed therein. |
| 1083 | |
| 1084 | Copyright 1987, 1988 by Digital Equipment Corporation, Maynard, |
| 1085 | Massachusetts, and the Massachusetts Institute of Technology, |
| 1086 | Cambridge, Massachusetts. |
| 1087 | |
| 1088 | All Rights Reserved |
| 1089 | |
| 1090 | Permission to use, copy, modify, and distribute this software and its |
| 1091 | documentation for any purpose and without fee is hereby granted, |
| 1092 | provided that the above copyright notice appear in all copies and that |
| 1093 | both that copyright notice and this permission notice appear in |
| 1094 | supporting documentation, and that the names of Digital or MIT not be |
| 1095 | used in advertising or publicity pertaining to distribution of the |
| 1096 | software without specific, written prior permission. |
| 1097 | |
| 1098 | DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, |
| 1099 | INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO |
| 1100 | EVENT SHALL DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR |
| 1101 | CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF |
| 1102 | USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR |
| 1103 | OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR |
| 1104 | PERFORMANCE OF THIS SOFTWARE. |
| 1105 | |
| 1106 | * The DMARC implementation uses the OpenDMARC library which is Copyrighted by |
| 1107 | The Trusted Domain Project. Portions of Exim source which use OpenDMARC |
| 1108 | derived code are indicated in the respective source files. The full |
| 1109 | OpenDMARC license is provided in the LICENSE.opendmarc file contained in |
| 1110 | the distributed source code. |
| 1111 | |
| 1112 | * Many people have contributed code fragments, some large, some small, that |
| 1113 | were not covered by any specific licence requirements. It is assumed that |
| 1114 | the contributors are happy to see their code incorporated into Exim under |
| 1115 | the GPL. |
| 1116 | |
| 1117 | |
| 1118 | |
| 1119 | =============================================================================== |
| 1120 | 3. HOW EXIM RECEIVES AND DELIVERS MAIL |
| 1121 | |
| 1122 | |
| 1123 | 3.1 Overall philosophy |
| 1124 | ---------------------- |
| 1125 | |
| 1126 | Exim is designed to work efficiently on systems that are permanently connected |
| 1127 | to the Internet and are handling a general mix of mail. In such circumstances, |
| 1128 | most messages can be delivered immediately. Consequently, Exim does not |
| 1129 | maintain independent queues of messages for specific domains or hosts, though |
| 1130 | it does try to send several messages in a single SMTP connection after a host |
| 1131 | has been down, and it also maintains per-host retry information. |
| 1132 | |
| 1133 | |
| 1134 | 3.2 Policy control |
| 1135 | ------------------ |
| 1136 | |
| 1137 | Policy controls are now an important feature of MTAs that are connected to the |
| 1138 | Internet. Perhaps their most important job is to stop MTAs being abused as |
| 1139 | "open relays" by misguided individuals who send out vast amounts of unsolicited |
| 1140 | junk, and want to disguise its source. Exim provides flexible facilities for |
| 1141 | specifying policy controls on incoming mail: |
| 1142 | |
| 1143 | * Exim 4 (unlike previous versions of Exim) implements policy controls on |
| 1144 | incoming mail by means of Access Control Lists (ACLs). Each list is a |
| 1145 | series of statements that may either grant or deny access. ACLs can be used |
| 1146 | at several places in the SMTP dialogue while receiving a message from a |
| 1147 | remote host. However, the most common places are after each RCPT command, |
| 1148 | and at the very end of the message. The sysadmin can specify conditions for |
| 1149 | accepting or rejecting individual recipients or the entire message, |
| 1150 | respectively, at these two points (see chapter 43). Denial of access |
| 1151 | results in an SMTP error code. |
| 1152 | |
| 1153 | * An ACL is also available for locally generated, non-SMTP messages. In this |
| 1154 | case, the only available actions are to accept or deny the entire message. |
| 1155 | |
| 1156 | * When Exim is compiled with the content-scanning extension, facilities are |
| 1157 | provided in the ACL mechanism for passing the message to external virus and |
| 1158 | /or spam scanning software. The result of such a scan is passed back to the |
| 1159 | ACL, which can then use it to decide what to do with the message. |
| 1160 | |
| 1161 | * When a message has been received, either from a remote host or from the |
| 1162 | local host, but before the final acknowledgment has been sent, a locally |
| 1163 | supplied C function called local_scan() can be run to inspect the message |
| 1164 | and decide whether to accept it or not (see chapter 45). If the message is |
| 1165 | accepted, the list of recipients can be modified by the function. |
| 1166 | |
| 1167 | * Using the local_scan() mechanism is another way of calling external scanner |
| 1168 | software. The SA-Exim add-on package works this way. It does not require |
| 1169 | Exim to be compiled with the content-scanning extension. |
| 1170 | |
| 1171 | * After a message has been accepted, a further checking mechanism is |
| 1172 | available in the form of the system filter (see chapter 46). This runs at |
| 1173 | the start of every delivery process. |
| 1174 | |
| 1175 | |
| 1176 | 3.3 User filters |
| 1177 | ---------------- |
| 1178 | |
| 1179 | In a conventional Exim configuration, users are able to run private filters by |
| 1180 | setting up appropriate .forward files in their home directories. See chapter 22 |
| 1181 | (about the redirect router) for the configuration needed to support this, and |
| 1182 | the separate document entitled Exim's interfaces to mail filtering for user |
| 1183 | details. Two different kinds of filtering are available: |
| 1184 | |
| 1185 | * Sieve filters are written in the standard filtering language that is |
| 1186 | defined by RFC 3028. |
| 1187 | |
| 1188 | * Exim filters are written in a syntax that is unique to Exim, but which is |
| 1189 | more powerful than Sieve, which it pre-dates. |
| 1190 | |
| 1191 | User filters are run as part of the routing process, described below. |
| 1192 | |
| 1193 | |
| 1194 | 3.4 Message identification |
| 1195 | -------------------------- |
| 1196 | |
| 1197 | Every message handled by Exim is given a message id which is sixteen characters |
| 1198 | long. It is divided into three parts, separated by hyphens, for example |
| 1199 | "16VDhn-0001bo-D3". Each part is a sequence of letters and digits, normally |
| 1200 | encoding numbers in base 62. However, in the Darwin operating system (Mac OS X) |
| 1201 | and when Exim is compiled to run under Cygwin, base 36 (avoiding the use of |
| 1202 | lower case letters) is used instead, because the message id is used to |
| 1203 | construct file names, and the names of files in those systems are not always |
| 1204 | case-sensitive. |
| 1205 | |
| 1206 | The detail of the contents of the message id have changed as Exim has evolved. |
| 1207 | Earlier versions relied on the operating system not re-using a process id (pid) |
| 1208 | within one second. On modern operating systems, this assumption can no longer |
| 1209 | be made, so the algorithm had to be changed. To retain backward compatibility, |
| 1210 | the format of the message id was retained, which is why the following rules are |
| 1211 | somewhat eccentric: |
| 1212 | |
| 1213 | * The first six characters of the message id are the time at which the |
| 1214 | message started to be received, to a granularity of one second. That is, |
| 1215 | this field contains the number of seconds since the start of the epoch (the |
| 1216 | normal Unix way of representing the date and time of day). |
| 1217 | |
| 1218 | * After the first hyphen, the next six characters are the id of the process |
| 1219 | that received the message. |
| 1220 | |
| 1221 | * There are two different possibilities for the final two characters: |
| 1222 | |
| 1223 | 1. If localhost_number is not set, this value is the fractional part of |
| 1224 | the time of reception, normally in units of 1/2000 of a second, but for |
| 1225 | systems that must use base 36 instead of base 62 (because of |
| 1226 | case-insensitive file systems), the units are 1/1000 of a second. |
| 1227 | |
| 1228 | 2. If localhost_number is set, it is multiplied by 200 (100) and added to |
| 1229 | the fractional part of the time, which in this case is in units of 1/ |
| 1230 | 200 (1/100) of a second. |
| 1231 | |
| 1232 | After a message has been received, Exim waits for the clock to tick at the |
| 1233 | appropriate resolution before proceeding, so that if another message is |
| 1234 | received by the same process, or by another process with the same (re-used) |
| 1235 | pid, it is guaranteed that the time will be different. In most cases, the clock |
| 1236 | will already have ticked while the message was being received. |
| 1237 | |
| 1238 | |
| 1239 | 3.5 Receiving mail |
| 1240 | ------------------ |
| 1241 | |
| 1242 | The only way Exim can receive mail from another host is using SMTP over TCP/IP, |
| 1243 | in which case the sender and recipient addresses are transferred using SMTP |
| 1244 | commands. However, from a locally running process (such as a user's MUA), there |
| 1245 | are several possibilities: |
| 1246 | |
| 1247 | * If the process runs Exim with the -bm option, the message is read |
| 1248 | non-interactively (usually via a pipe), with the recipients taken from the |
| 1249 | command line, or from the body of the message if -t is also used. |
| 1250 | |
| 1251 | * If the process runs Exim with the -bS option, the message is also read |
| 1252 | non-interactively, but in this case the recipients are listed at the start |
| 1253 | of the message in a series of SMTP RCPT commands, terminated by a DATA |
| 1254 | command. This is so-called "batch SMTP" format, but it isn't really SMTP. |
| 1255 | The SMTP commands are just another way of passing envelope addresses in a |
| 1256 | non-interactive submission. |
| 1257 | |
| 1258 | * If the process runs Exim with the -bs option, the message is read |
| 1259 | interactively, using the SMTP protocol. A two-way pipe is normally used for |
| 1260 | passing data between the local process and the Exim process. This is "real" |
| 1261 | SMTP and is handled in the same way as SMTP over TCP/IP. For example, the |
| 1262 | ACLs for SMTP commands are used for this form of submission. |
| 1263 | |
| 1264 | * A local process may also make a TCP/IP call to the host's loopback address |
| 1265 | (127.0.0.1) or any other of its IP addresses. When receiving messages, Exim |
| 1266 | does not treat the loopback address specially. It treats all such |
| 1267 | connections in the same way as connections from other hosts. |
| 1268 | |
| 1269 | In the three cases that do not involve TCP/IP, the sender address is |
| 1270 | constructed from the login name of the user that called Exim and a default |
| 1271 | qualification domain (which can be set by the qualify_domain configuration |
| 1272 | option). For local or batch SMTP, a sender address that is passed using the |
| 1273 | SMTP MAIL command is ignored. However, the system administrator may allow |
| 1274 | certain users ("trusted users") to specify a different sender address |
| 1275 | unconditionally, or all users to specify certain forms of different sender |
| 1276 | address. The -f option or the SMTP MAIL command is used to specify these |
| 1277 | different addresses. See section 5.2 for details of trusted users, and the |
| 1278 | untrusted_set_sender option for a way of allowing untrusted users to change |
| 1279 | sender addresses. |
| 1280 | |
| 1281 | Messages received by either of the non-interactive mechanisms are subject to |
| 1282 | checking by the non-SMTP ACL, if one is defined. Messages received using SMTP |
| 1283 | (either over TCP/IP, or interacting with a local process) can be checked by a |
| 1284 | number of ACLs that operate at different times during the SMTP session. Either |
| 1285 | individual recipients, or the entire message, can be rejected if local policy |
| 1286 | requirements are not met. The local_scan() function (see chapter 45) is run for |
| 1287 | all incoming messages. |
| 1288 | |
| 1289 | Exim can be configured not to start a delivery process when a message is |
| 1290 | received; this can be unconditional, or depend on the number of incoming SMTP |
| 1291 | connections or the system load. In these situations, new messages wait on the |
| 1292 | queue until a queue runner process picks them up. However, in standard |
| 1293 | configurations under normal conditions, delivery is started as soon as a |
| 1294 | message is received. |
| 1295 | |
| 1296 | |
| 1297 | 3.6 Handling an incoming message |
| 1298 | -------------------------------- |
| 1299 | |
| 1300 | When Exim accepts a message, it writes two files in its spool directory. The |
| 1301 | first contains the envelope information, the current status of the message, and |
| 1302 | the header lines, and the second contains the body of the message. The names of |
| 1303 | the two spool files consist of the message id, followed by "-H" for the file |
| 1304 | containing the envelope and header, and "-D" for the data file. |
| 1305 | |
| 1306 | By default all these message files are held in a single directory called input |
| 1307 | inside the general Exim spool directory. Some operating systems do not perform |
| 1308 | very well if the number of files in a directory gets large; to improve |
| 1309 | performance in such cases, the split_spool_directory option can be used. This |
| 1310 | causes Exim to split up the input files into 62 sub-directories whose names are |
| 1311 | single letters or digits. When this is done, the queue is processed one |
| 1312 | sub-directory at a time instead of all at once, which can improve overall |
| 1313 | performance even when there are not enough files in each directory to affect |
| 1314 | file system performance. |
| 1315 | |
| 1316 | The envelope information consists of the address of the message's sender and |
| 1317 | the addresses of the recipients. This information is entirely separate from any |
| 1318 | addresses contained in the header lines. The status of the message includes a |
| 1319 | list of recipients who have already received the message. The format of the |
| 1320 | first spool file is described in chapter 56. |
| 1321 | |
| 1322 | Address rewriting that is specified in the rewrite section of the configuration |
| 1323 | (see chapter 31) is done once and for all on incoming addresses, both in the |
| 1324 | header lines and the envelope, at the time the message is accepted. If during |
| 1325 | the course of delivery additional addresses are generated (for example, via |
| 1326 | aliasing), these new addresses are rewritten as soon as they are generated. At |
| 1327 | the time a message is actually delivered (transported) further rewriting can |
| 1328 | take place; because this is a transport option, it can be different for |
| 1329 | different forms of delivery. It is also possible to specify the addition or |
| 1330 | removal of certain header lines at the time the message is delivered (see |
| 1331 | chapters 15 and 24). |
| 1332 | |
| 1333 | |
| 1334 | 3.7 Life of a message |
| 1335 | --------------------- |
| 1336 | |
| 1337 | A message remains in the spool directory until it is completely delivered to |
| 1338 | its recipients or to an error address, or until it is deleted by an |
| 1339 | administrator or by the user who originally created it. In cases when delivery |
| 1340 | cannot proceed - for example, when a message can neither be delivered to its |
| 1341 | recipients nor returned to its sender, the message is marked "frozen" on the |
| 1342 | spool, and no more deliveries are attempted. |
| 1343 | |
| 1344 | An administrator can "thaw" such messages when the problem has been corrected, |
| 1345 | and can also freeze individual messages by hand if necessary. In addition, an |
| 1346 | administrator can force a delivery error, causing a bounce message to be sent. |
| 1347 | |
| 1348 | There are options called ignore_bounce_errors_after and timeout_frozen_after, |
| 1349 | which discard frozen messages after a certain time. The first applies only to |
| 1350 | frozen bounces, the second to any frozen messages. |
| 1351 | |
| 1352 | While Exim is working on a message, it writes information about each delivery |
| 1353 | attempt to its main log file. This includes successful, unsuccessful, and |
| 1354 | delayed deliveries for each recipient (see chapter 52). The log lines are also |
| 1355 | written to a separate message log file for each message. These logs are solely |
| 1356 | for the benefit of the administrator, and are normally deleted along with the |
| 1357 | spool files when processing of a message is complete. The use of individual |
| 1358 | message logs can be disabled by setting no_message_logs; this might give an |
| 1359 | improvement in performance on very busy systems. |
| 1360 | |
| 1361 | All the information Exim itself needs to set up a delivery is kept in the first |
| 1362 | spool file, along with the header lines. When a successful delivery occurs, the |
| 1363 | address is immediately written at the end of a journal file, whose name is the |
| 1364 | message id followed by "-J". At the end of a delivery run, if there are some |
| 1365 | addresses left to be tried again later, the first spool file (the "-H" file) is |
| 1366 | updated to indicate which these are, and the journal file is then deleted. |
| 1367 | Updating the spool file is done by writing a new file and renaming it, to |
| 1368 | minimize the possibility of data loss. |
| 1369 | |
| 1370 | Should the system or the program crash after a successful delivery but before |
| 1371 | the spool file has been updated, the journal is left lying around. The next |
| 1372 | time Exim attempts to deliver the message, it reads the journal file and |
| 1373 | updates the spool file before proceeding. This minimizes the chances of double |
| 1374 | deliveries caused by crashes. |
| 1375 | |
| 1376 | |
| 1377 | 3.8 Processing an address for delivery |
| 1378 | -------------------------------------- |
| 1379 | |
| 1380 | The main delivery processing elements of Exim are called routers and transports |
| 1381 | , and collectively these are known as drivers. Code for a number of them is |
| 1382 | provided in the source distribution, and compile-time options specify which |
| 1383 | ones are included in the binary. Run time options specify which ones are |
| 1384 | actually used for delivering messages. |
| 1385 | |
| 1386 | Each driver that is specified in the run time configuration is an instance of |
| 1387 | that particular driver type. Multiple instances are allowed; for example, you |
| 1388 | can set up several different smtp transports, each with different option values |
| 1389 | that might specify different ports or different timeouts. Each instance has its |
| 1390 | own identifying name. In what follows we will normally use the instance name |
| 1391 | when discussing one particular instance (that is, one specific configuration of |
| 1392 | the driver), and the generic driver name when discussing the driver's features |
| 1393 | in general. |
| 1394 | |
| 1395 | A router is a driver that operates on an address, either determining how its |
| 1396 | delivery should happen, by assigning it to a specific transport, or converting |
| 1397 | the address into one or more new addresses (for example, via an alias file). A |
| 1398 | router may also explicitly choose to fail an address, causing it to be bounced. |
| 1399 | |
| 1400 | A transport is a driver that transmits a copy of the message from Exim's spool |
| 1401 | to some destination. There are two kinds of transport: for a local transport, |
| 1402 | the destination is a file or a pipe on the local host, whereas for a remote |
| 1403 | transport the destination is some other host. A message is passed to a specific |
| 1404 | transport as a result of successful routing. If a message has several |
| 1405 | recipients, it may be passed to a number of different transports. |
| 1406 | |
| 1407 | An address is processed by passing it to each configured router instance in |
| 1408 | turn, subject to certain preconditions, until a router accepts the address or |
| 1409 | specifies that it should be bounced. We will describe this process in more |
| 1410 | detail shortly. First, as a simple example, we consider how each recipient |
| 1411 | address in a message is processed in a small configuration of three routers. |
| 1412 | |
| 1413 | To make this a more concrete example, it is described in terms of some actual |
| 1414 | routers, but remember, this is only an example. You can configure Exim's |
| 1415 | routers in many different ways, and there may be any number of routers in a |
| 1416 | configuration. |
| 1417 | |
| 1418 | The first router that is specified in a configuration is often one that handles |
| 1419 | addresses in domains that are not recognized specially by the local host. These |
| 1420 | are typically addresses for arbitrary domains on the Internet. A precondition |
| 1421 | is set up which looks for the special domains known to the host (for example, |
| 1422 | its own domain name), and the router is run for addresses that do not match. |
| 1423 | Typically, this is a router that looks up domains in the DNS in order to find |
| 1424 | the hosts to which this address routes. If it succeeds, the address is assigned |
| 1425 | to a suitable SMTP transport; if it does not succeed, the router is configured |
| 1426 | to fail the address. |
| 1427 | |
| 1428 | The second router is reached only when the domain is recognized as one that |
| 1429 | "belongs" to the local host. This router does redirection - also known as |
| 1430 | aliasing and forwarding. When it generates one or more new addresses from the |
| 1431 | original, each of them is routed independently from the start. Otherwise, the |
| 1432 | router may cause an address to fail, or it may simply decline to handle the |
| 1433 | address, in which case the address is passed to the next router. |
| 1434 | |
| 1435 | The final router in many configurations is one that checks to see if the |
| 1436 | address belongs to a local mailbox. The precondition may involve a check to see |
| 1437 | if the local part is the name of a login account, or it may look up the local |
| 1438 | part in a file or a database. If its preconditions are not met, or if the |
| 1439 | router declines, we have reached the end of the routers. When this happens, the |
| 1440 | address is bounced. |
| 1441 | |
| 1442 | |
| 1443 | 3.9 Processing an address for verification |
| 1444 | ------------------------------------------ |
| 1445 | |
| 1446 | As well as being used to decide how to deliver to an address, Exim's routers |
| 1447 | are also used for address verification. Verification can be requested as one of |
| 1448 | the checks to be performed in an ACL for incoming messages, on both sender and |
| 1449 | recipient addresses, and it can be tested using the -bv and -bvs command line |
| 1450 | options. |
| 1451 | |
| 1452 | When an address is being verified, the routers are run in "verify mode". This |
| 1453 | does not affect the way the routers work, but it is a state that can be |
| 1454 | detected. By this means, a router can be skipped or made to behave differently |
| 1455 | when verifying. A common example is a configuration in which the first router |
| 1456 | sends all messages to a message-scanning program, unless they have been |
| 1457 | previously scanned. Thus, the first router accepts all addresses without any |
| 1458 | checking, making it useless for verifying. Normally, the no_verify option would |
| 1459 | be set for such a router, causing it to be skipped in verify mode. |
| 1460 | |
| 1461 | |
| 1462 | 3.10 Running an individual router |
| 1463 | --------------------------------- |
| 1464 | |
| 1465 | As explained in the example above, a number of preconditions are checked before |
| 1466 | running a router. If any are not met, the router is skipped, and the address is |
| 1467 | passed to the next router. When all the preconditions on a router are met, the |
| 1468 | router is run. What happens next depends on the outcome, which is one of the |
| 1469 | following: |
| 1470 | |
| 1471 | * accept: The router accepts the address, and either assigns it to a |
| 1472 | transport, or generates one or more "child" addresses. Processing the |
| 1473 | original address ceases, unless the unseen option is set on the router. |
| 1474 | This option can be used to set up multiple deliveries with different |
| 1475 | routing (for example, for keeping archive copies of messages). When unseen |
| 1476 | is set, the address is passed to the next router. Normally, however, an |
| 1477 | accept return marks the end of routing. |
| 1478 | |
| 1479 | Any child addresses generated by the router are processed independently, |
| 1480 | starting with the first router by default. It is possible to change this by |
| 1481 | setting the redirect_router option to specify which router to start at for |
| 1482 | child addresses. Unlike pass_router (see below) the router specified by |
| 1483 | redirect_router may be anywhere in the router configuration. |
| 1484 | |
| 1485 | * pass: The router recognizes the address, but cannot handle it itself. It |
| 1486 | requests that the address be passed to another router. By default the |
| 1487 | address is passed to the next router, but this can be changed by setting |
| 1488 | the pass_router option. However, (unlike redirect_router) the named router |
| 1489 | must be below the current router (to avoid loops). |
| 1490 | |
| 1491 | * decline: The router declines to accept the address because it does not |
| 1492 | recognize it at all. By default, the address is passed to the next router, |
| 1493 | but this can be prevented by setting the no_more option. When no_more is |
| 1494 | set, all the remaining routers are skipped. In effect, no_more converts |
| 1495 | decline into fail. |
| 1496 | |
| 1497 | * fail: The router determines that the address should fail, and queues it for |
| 1498 | the generation of a bounce message. There is no further processing of the |
| 1499 | original address unless unseen is set on the router. |
| 1500 | |
| 1501 | * defer: The router cannot handle the address at the present time. (A |
| 1502 | database may be offline, or a DNS lookup may have timed out.) No further |
| 1503 | processing of the address happens in this delivery attempt. It is tried |
| 1504 | again next time the message is considered for delivery. |
| 1505 | |
| 1506 | * error: There is some error in the router (for example, a syntax error in |
| 1507 | its configuration). The action is as for defer. |
| 1508 | |
| 1509 | If an address reaches the end of the routers without having been accepted by |
| 1510 | any of them, it is bounced as unrouteable. The default error message in this |
| 1511 | situation is "unrouteable address", but you can set your own message by making |
| 1512 | use of the cannot_route_message option. This can be set for any router; the |
| 1513 | value from the last router that "saw" the address is used. |
| 1514 | |
| 1515 | Sometimes while routing you want to fail a delivery when some conditions are |
| 1516 | met but others are not, instead of passing the address on for further routing. |
| 1517 | You can do this by having a second router that explicitly fails the delivery |
| 1518 | when the relevant conditions are met. The redirect router has a "fail" facility |
| 1519 | for this purpose. |
| 1520 | |
| 1521 | |
| 1522 | 3.11 Duplicate addresses |
| 1523 | ------------------------ |
| 1524 | |
| 1525 | Once routing is complete, Exim scans the addresses that are assigned to local |
| 1526 | and remote transports, and discards any duplicates that it finds. During this |
| 1527 | check, local parts are treated as case-sensitive. This happens only when |
| 1528 | actually delivering a message; when testing routers with -bt, all the routed |
| 1529 | addresses are shown. |
| 1530 | |
| 1531 | |
| 1532 | 3.12 Router preconditions |
| 1533 | ------------------------- |
| 1534 | |
| 1535 | The preconditions that are tested for each router are listed below, in the |
| 1536 | order in which they are tested. The individual configuration options are |
| 1537 | described in more detail in chapter 15. |
| 1538 | |
| 1539 | * The local_part_prefix and local_part_suffix options can specify that the |
| 1540 | local parts handled by the router may or must have certain prefixes and/or |
| 1541 | suffixes. If a mandatory affix (prefix or suffix) is not present, the |
| 1542 | router is skipped. These conditions are tested first. When an affix is |
| 1543 | present, it is removed from the local part before further processing, |
| 1544 | including the evaluation of any other conditions. |
| 1545 | |
| 1546 | * Routers can be designated for use only when not verifying an address, that |
| 1547 | is, only when routing it for delivery (or testing its delivery routing). If |
| 1548 | the verify option is set false, the router is skipped when Exim is |
| 1549 | verifying an address. Setting the verify option actually sets two options, |
| 1550 | verify_sender and verify_recipient, which independently control the use of |
| 1551 | the router for sender and recipient verification. You can set these options |
| 1552 | directly if you want a router to be used for only one type of verification. |
| 1553 | Note that cutthrough delivery is classed as a recipient verification for |
| 1554 | this purpose. |
| 1555 | |
| 1556 | * If the address_test option is set false, the router is skipped when Exim is |
| 1557 | run with the -bt option to test an address routing. This can be helpful |
| 1558 | when the first router sends all new messages to a scanner of some sort; it |
| 1559 | makes it possible to use -bt to test subsequent delivery routing without |
| 1560 | having to simulate the effect of the scanner. |
| 1561 | |
| 1562 | * Routers can be designated for use only when verifying an address, as |
| 1563 | opposed to routing it for delivery. The verify_only option controls this. |
| 1564 | Again, cutthrough delivery counts as a verification. |
| 1565 | |
| 1566 | * Individual routers can be explicitly skipped when running the routers to |
| 1567 | check an address given in the SMTP EXPN command (see the expn option). |
| 1568 | |
| 1569 | * If the domains option is set, the domain of the address must be in the set |
| 1570 | of domains that it defines. |
| 1571 | |
| 1572 | * If the local_parts option is set, the local part of the address must be in |
| 1573 | the set of local parts that it defines. If local_part_prefix or |
| 1574 | local_part_suffix is in use, the prefix or suffix is removed from the local |
| 1575 | part before this check. If you want to do precondition tests on local parts |
| 1576 | that include affixes, you can do so by using a condition option (see below) |
| 1577 | that uses the variables $local_part, $local_part_prefix, and |
| 1578 | $local_part_suffix as necessary. |
| 1579 | |
| 1580 | * If the check_local_user option is set, the local part must be the name of |
| 1581 | an account on the local host. If this check succeeds, the uid and gid of |
| 1582 | the local user are placed in $local_user_uid and $local_user_gid and the |
| 1583 | user's home directory is placed in $home; these values can be used in the |
| 1584 | remaining preconditions. |
| 1585 | |
| 1586 | * If the router_home_directory option is set, it is expanded at this point, |
| 1587 | because it overrides the value of $home. If this expansion were left till |
| 1588 | later, the value of $home as set by check_local_user would be used in |
| 1589 | subsequent tests. Having two different values of $home in the same router |
| 1590 | could lead to confusion. |
| 1591 | |
| 1592 | * If the senders option is set, the envelope sender address must be in the |
| 1593 | set of addresses that it defines. |
| 1594 | |
| 1595 | * If the require_files option is set, the existence or non-existence of |
| 1596 | specified files is tested. |
| 1597 | |
| 1598 | * If the condition option is set, it is evaluated and tested. This option |
| 1599 | uses an expanded string to allow you to set up your own custom |
| 1600 | preconditions. Expanded strings are described in chapter 11. |
| 1601 | |
| 1602 | Note that require_files comes near the end of the list, so you cannot use it to |
| 1603 | check for the existence of a file in which to lookup up a domain, local part, |
| 1604 | or sender. However, as these options are all expanded, you can use the exists |
| 1605 | expansion condition to make such tests within each condition. The require_files |
| 1606 | option is intended for checking files that the router may be going to use |
| 1607 | internally, or which are needed by a specific transport (for example, |
| 1608 | .procmailrc). |
| 1609 | |
| 1610 | |
| 1611 | 3.13 Delivery in detail |
| 1612 | ----------------------- |
| 1613 | |
| 1614 | When a message is to be delivered, the sequence of events is as follows: |
| 1615 | |
| 1616 | * If a system-wide filter file is specified, the message is passed to it. The |
| 1617 | filter may add recipients to the message, replace the recipients, discard |
| 1618 | the message, cause a new message to be generated, or cause the message |
| 1619 | delivery to fail. The format of the system filter file is the same as for |
| 1620 | Exim user filter files, described in the separate document entitled Exim's |
| 1621 | interfaces to mail filtering. (Note: Sieve cannot be used for system filter |
| 1622 | files.) |
| 1623 | |
| 1624 | Some additional features are available in system filters - see chapter 46 |
| 1625 | for details. Note that a message is passed to the system filter only once |
| 1626 | per delivery attempt, however many recipients it has. However, if there are |
| 1627 | several delivery attempts because one or more addresses could not be |
| 1628 | immediately delivered, the system filter is run each time. The filter |
| 1629 | condition first_delivery can be used to detect the first run of the system |
| 1630 | filter. |
| 1631 | |
| 1632 | * Each recipient address is offered to each configured router in turn, |
| 1633 | subject to its preconditions, until one is able to handle it. If no router |
| 1634 | can handle the address, that is, if they all decline, the address is |
| 1635 | failed. Because routers can be targeted at particular domains, several |
| 1636 | locally handled domains can be processed entirely independently of each |
| 1637 | other. |
| 1638 | |
| 1639 | * A router that accepts an address may assign it to a local or a remote |
| 1640 | transport. However, the transport is not run at this time. Instead, the |
| 1641 | address is placed on a list for the particular transport, which will be run |
| 1642 | later. Alternatively, the router may generate one or more new addresses |
| 1643 | (typically from alias, forward, or filter files). New addresses are fed |
| 1644 | back into this process from the top, but in order to avoid loops, a router |
| 1645 | ignores any address which has an identically-named ancestor that was |
| 1646 | processed by itself. |
| 1647 | |
| 1648 | * When all the routing has been done, addresses that have been successfully |
| 1649 | handled are passed to their assigned transports. When local transports are |
| 1650 | doing real local deliveries, they handle only one address at a time, but if |
| 1651 | a local transport is being used as a pseudo-remote transport (for example, |
| 1652 | to collect batched SMTP messages for transmission by some other means) |
| 1653 | multiple addresses can be handled. Remote transports can always handle more |
| 1654 | than one address at a time, but can be configured not to do so, or to |
| 1655 | restrict multiple addresses to the same domain. |
| 1656 | |
| 1657 | * Each local delivery to a file or a pipe runs in a separate process under a |
| 1658 | non-privileged uid, and these deliveries are run one at a time. Remote |
| 1659 | deliveries also run in separate processes, normally under a uid that is |
| 1660 | private to Exim ("the Exim user"), but in this case, several remote |
| 1661 | deliveries can be run in parallel. The maximum number of simultaneous |
| 1662 | remote deliveries for any one message is set by the remote_max_parallel |
| 1663 | option. The order in which deliveries are done is not defined, except that |
| 1664 | all local deliveries happen before any remote deliveries. |
| 1665 | |
| 1666 | * When it encounters a local delivery during a queue run, Exim checks its |
| 1667 | retry database to see if there has been a previous temporary delivery |
| 1668 | failure for the address before running the local transport. If there was a |
| 1669 | previous failure, Exim does not attempt a new delivery until the retry time |
| 1670 | for the address is reached. However, this happens only for delivery |
| 1671 | attempts that are part of a queue run. Local deliveries are always |
| 1672 | attempted when delivery immediately follows message reception, even if |
| 1673 | retry times are set for them. This makes for better behaviour if one |
| 1674 | particular message is causing problems (for example, causing quota |
| 1675 | overflow, or provoking an error in a filter file). |
| 1676 | |
| 1677 | * Remote transports do their own retry handling, since an address may be |
| 1678 | deliverable to one of a number of hosts, each of which may have a different |
| 1679 | retry time. If there have been previous temporary failures and no host has |
| 1680 | reached its retry time, no delivery is attempted, whether in a queue run or |
| 1681 | not. See chapter 32 for details of retry strategies. |
| 1682 | |
| 1683 | * If there were any permanent errors, a bounce message is returned to an |
| 1684 | appropriate address (the sender in the common case), with details of the |
| 1685 | error for each failing address. Exim can be configured to send copies of |
| 1686 | bounce messages to other addresses. |
| 1687 | |
| 1688 | * If one or more addresses suffered a temporary failure, the message is left |
| 1689 | on the queue, to be tried again later. Delivery of these addresses is said |
| 1690 | to be deferred. |
| 1691 | |
| 1692 | * When all the recipient addresses have either been delivered or bounced, |
| 1693 | handling of the message is complete. The spool files and message log are |
| 1694 | deleted, though the message log can optionally be preserved if required. |
| 1695 | |
| 1696 | |
| 1697 | 3.14 Retry mechanism |
| 1698 | -------------------- |
| 1699 | |
| 1700 | Exim's mechanism for retrying messages that fail to get delivered at the first |
| 1701 | attempt is the queue runner process. You must either run an Exim daemon that |
| 1702 | uses the -q option with a time interval to start queue runners at regular |
| 1703 | intervals, or use some other means (such as cron) to start them. If you do not |
| 1704 | arrange for queue runners to be run, messages that fail temporarily at the |
| 1705 | first attempt will remain on your queue for ever. A queue runner process works |
| 1706 | its way through the queue, one message at a time, trying each delivery that has |
| 1707 | passed its retry time. You can run several queue runners at once. |
| 1708 | |
| 1709 | Exim uses a set of configured rules to determine when next to retry the failing |
| 1710 | address (see chapter 32). These rules also specify when Exim should give up |
| 1711 | trying to deliver to the address, at which point it generates a bounce message. |
| 1712 | If no retry rules are set for a particular host, address, and error |
| 1713 | combination, no retries are attempted, and temporary errors are treated as |
| 1714 | permanent. |
| 1715 | |
| 1716 | |
| 1717 | 3.15 Temporary delivery failure |
| 1718 | ------------------------------- |
| 1719 | |
| 1720 | There are many reasons why a message may not be immediately deliverable to a |
| 1721 | particular address. Failure to connect to a remote machine (because it, or the |
| 1722 | connection to it, is down) is one of the most common. Temporary failures may be |
| 1723 | detected during routing as well as during the transport stage of delivery. |
| 1724 | Local deliveries may be delayed if NFS files are unavailable, or if a mailbox |
| 1725 | is on a file system where the user is over quota. Exim can be configured to |
| 1726 | impose its own quotas on local mailboxes; where system quotas are set they will |
| 1727 | also apply. |
| 1728 | |
| 1729 | If a host is unreachable for a period of time, a number of messages may be |
| 1730 | waiting for it by the time it recovers, and sending them in a single SMTP |
| 1731 | connection is clearly beneficial. Whenever a delivery to a remote host is |
| 1732 | deferred, Exim makes a note in its hints database, and whenever a successful |
| 1733 | SMTP delivery has happened, it looks to see if any other messages are waiting |
| 1734 | for the same host. If any are found, they are sent over the same SMTP |
| 1735 | connection, subject to a configuration limit as to the maximum number in any |
| 1736 | one connection. |
| 1737 | |
| 1738 | |
| 1739 | 3.16 Permanent delivery failure |
| 1740 | ------------------------------- |
| 1741 | |
| 1742 | When a message cannot be delivered to some or all of its intended recipients, a |
| 1743 | bounce message is generated. Temporary delivery failures turn into permanent |
| 1744 | errors when their timeout expires. All the addresses that fail in a given |
| 1745 | delivery attempt are listed in a single message. If the original message has |
| 1746 | many recipients, it is possible for some addresses to fail in one delivery |
| 1747 | attempt and others to fail subsequently, giving rise to more than one bounce |
| 1748 | message. The wording of bounce messages can be customized by the administrator. |
| 1749 | See chapter 49 for details. |
| 1750 | |
| 1751 | Bounce messages contain an X-Failed-Recipients: header line that lists the |
| 1752 | failed addresses, for the benefit of programs that try to analyse such messages |
| 1753 | automatically. |
| 1754 | |
| 1755 | A bounce message is normally sent to the sender of the original message, as |
| 1756 | obtained from the message's envelope. For incoming SMTP messages, this is the |
| 1757 | address given in the MAIL command. However, when an address is expanded via a |
| 1758 | forward or alias file, an alternative address can be specified for delivery |
| 1759 | failures of the generated addresses. For a mailing list expansion (see section |
| 1760 | 50.2) it is common to direct bounce messages to the manager of the list. |
| 1761 | |
| 1762 | |
| 1763 | 3.17 Failures to deliver bounce messages |
| 1764 | ---------------------------------------- |
| 1765 | |
| 1766 | If a bounce message (either locally generated or received from a remote host) |
| 1767 | itself suffers a permanent delivery failure, the message is left on the queue, |
| 1768 | but it is frozen, awaiting the attention of an administrator. There are options |
| 1769 | that can be used to make Exim discard such failed messages, or to keep them for |
| 1770 | only a short time (see timeout_frozen_after and ignore_bounce_errors_after). |
| 1771 | |
| 1772 | |
| 1773 | |
| 1774 | =============================================================================== |
| 1775 | 4. BUILDING AND INSTALLING EXIM |
| 1776 | |
| 1777 | |
| 1778 | 4.1 Unpacking |
| 1779 | ------------- |
| 1780 | |
| 1781 | Exim is distributed as a gzipped or bzipped tar file which, when unpacked, |
| 1782 | creates a directory with the name of the current release (for example, |
| 1783 | exim-4.89) into which the following files are placed: |
| 1784 | |
| 1785 | ACKNOWLEDGMENTS contains some acknowledgments |
| 1786 | CHANGES contains a reference to where changes are documented |
| 1787 | LICENCE the GNU General Public Licence |
| 1788 | Makefile top-level make file |
| 1789 | NOTICE conditions for the use of Exim |
| 1790 | README list of files, directories and simple build instructions |
| 1791 | |
| 1792 | Other files whose names begin with README may also be present. The following |
| 1793 | subdirectories are created: |
| 1794 | |
| 1795 | Local an empty directory for local configuration files |
| 1796 | OS OS-specific files |
| 1797 | doc documentation files |
| 1798 | exim_monitor source files for the Exim monitor |
| 1799 | scripts scripts used in the build process |
| 1800 | src remaining source files |
| 1801 | util independent utilities |
| 1802 | |
| 1803 | The main utility programs are contained in the src directory, and are built |
| 1804 | with the Exim binary. The util directory contains a few optional scripts that |
| 1805 | may be useful to some sites. |
| 1806 | |
| 1807 | |
| 1808 | 4.2 Multiple machine architectures and operating systems |
| 1809 | -------------------------------------------------------- |
| 1810 | |
| 1811 | The building process for Exim is arranged to make it easy to build binaries for |
| 1812 | a number of different architectures and operating systems from the same set of |
| 1813 | source files. Compilation does not take place in the src directory. Instead, a |
| 1814 | build directory is created for each architecture and operating system. Symbolic |
| 1815 | links to the sources are installed in this directory, which is where the actual |
| 1816 | building takes place. In most cases, Exim can discover the machine architecture |
| 1817 | and operating system for itself, but the defaults can be overridden if |
| 1818 | necessary. |
| 1819 | |
| 1820 | |
| 1821 | 4.3 PCRE library |
| 1822 | ---------------- |
| 1823 | |
| 1824 | Exim no longer has an embedded PCRE library as the vast majority of modern |
| 1825 | systems include PCRE as a system library, although you may need to install the |
| 1826 | PCRE or PCRE development package for your operating system. If your system has |
| 1827 | a normal PCRE installation the Exim build process will need no further |
| 1828 | configuration. If the library or the headers are in an unusual location you |
| 1829 | will need to either set the PCRE_LIBS and INCLUDE directives appropriately, or |
| 1830 | set PCRE_CONFIG=yes to use the installed pcre-config command. If your operating |
| 1831 | system has no PCRE support then you will need to obtain and build the current |
| 1832 | PCRE from ftp://ftp.csx.cam.ac.uk/pub/software/programming/pcre/. More |
| 1833 | information on PCRE is available at http://www.pcre.org/. |
| 1834 | |
| 1835 | |
| 1836 | 4.4 DBM libraries |
| 1837 | ----------------- |
| 1838 | |
| 1839 | Even if you do not use any DBM files in your configuration, Exim still needs a |
| 1840 | DBM library in order to operate, because it uses indexed files for its hints |
| 1841 | databases. Unfortunately, there are a number of DBM libraries in existence, and |
| 1842 | different operating systems often have different ones installed. |
| 1843 | |
| 1844 | If you are using Solaris, IRIX, one of the modern BSD systems, or a modern |
| 1845 | Linux distribution, the DBM configuration should happen automatically, and you |
| 1846 | may be able to ignore this section. Otherwise, you may have to learn more than |
| 1847 | you would like about DBM libraries from what follows. |
| 1848 | |
| 1849 | Licensed versions of Unix normally contain a library of DBM functions operating |
| 1850 | via the ndbm interface, and this is what Exim expects by default. Free versions |
| 1851 | of Unix seem to vary in what they contain as standard. In particular, some |
| 1852 | early versions of Linux have no default DBM library, and different distributors |
| 1853 | have chosen to bundle different libraries with their packaged versions. |
| 1854 | However, the more recent releases seem to have standardized on the Berkeley DB |
| 1855 | library. |
| 1856 | |
| 1857 | Different DBM libraries have different conventions for naming the files they |
| 1858 | use. When a program opens a file called dbmfile, there are several |
| 1859 | possibilities: |
| 1860 | |
| 1861 | 1. A traditional ndbm implementation, such as that supplied as part of |
| 1862 | Solaris, operates on two files called dbmfile.dir and dbmfile.pag. |
| 1863 | |
| 1864 | 2. The GNU library, gdbm, operates on a single file. If used via its ndbm |
| 1865 | compatibility interface it makes two different hard links to it with names |
| 1866 | dbmfile.dir and dbmfile.pag, but if used via its native interface, the file |
| 1867 | name is used unmodified. |
| 1868 | |
| 1869 | 3. The Berkeley DB package, if called via its ndbm compatibility interface, |
| 1870 | operates on a single file called dbmfile.db, but otherwise looks to the |
| 1871 | programmer exactly the same as the traditional ndbm implementation. |
| 1872 | |
| 1873 | 4. If the Berkeley package is used in its native mode, it operates on a single |
| 1874 | file called dbmfile; the programmer's interface is somewhat different to |
| 1875 | the traditional ndbm interface. |
| 1876 | |
| 1877 | 5. To complicate things further, there are several very different versions of |
| 1878 | the Berkeley DB package. Version 1.85 was stable for a very long time, |
| 1879 | releases 2.x and 3.x were current for a while, but the latest versions are |
| 1880 | now numbered 4.x. Maintenance of some of the earlier releases has ceased. |
| 1881 | All versions of Berkeley DB can be obtained from http://www.sleepycat.com/. |
| 1882 | |
| 1883 | 6. Yet another DBM library, called tdb, is available from http:// |
| 1884 | download.sourceforge.net/tdb. It has its own interface, and also operates |
| 1885 | on a single file. |
| 1886 | |
| 1887 | Exim and its utilities can be compiled to use any of these interfaces. In order |
| 1888 | to use any version of the Berkeley DB package in native mode, you must set |
| 1889 | USE_DB in an appropriate configuration file (typically Local/Makefile). For |
| 1890 | example: |
| 1891 | |
| 1892 | USE_DB=yes |
| 1893 | |
| 1894 | Similarly, for gdbm you set USE_GDBM, and for tdb you set USE_TDB. An error is |
| 1895 | diagnosed if you set more than one of these. |
| 1896 | |
| 1897 | At the lowest level, the build-time configuration sets none of these options, |
| 1898 | thereby assuming an interface of type (1). However, some operating system |
| 1899 | configuration files (for example, those for the BSD operating systems and |
| 1900 | Linux) assume type (4) by setting USE_DB as their default, and the |
| 1901 | configuration files for Cygwin set USE_GDBM. Anything you set in Local/Makefile |
| 1902 | , however, overrides these system defaults. |
| 1903 | |
| 1904 | As well as setting USE_DB, USE_GDBM, or USE_TDB, it may also be necessary to |
| 1905 | set DBMLIB, to cause inclusion of the appropriate library, as in one of these |
| 1906 | lines: |
| 1907 | |
| 1908 | DBMLIB = -ldb |
| 1909 | DBMLIB = -ltdb |
| 1910 | |
| 1911 | Settings like that will work if the DBM library is installed in the standard |
| 1912 | place. Sometimes it is not, and the library's header file may also not be in |
| 1913 | the default path. You may need to set INCLUDE to specify where the header file |
| 1914 | is, and to specify the path to the library more fully in DBMLIB, as in this |
| 1915 | example: |
| 1916 | |
| 1917 | INCLUDE=-I/usr/local/include/db-4.1 |
| 1918 | DBMLIB=/usr/local/lib/db-4.1/libdb.a |
| 1919 | |
| 1920 | There is further detailed discussion about the various DBM libraries in the |
| 1921 | file doc/dbm.discuss.txt in the Exim distribution. |
| 1922 | |
| 1923 | |
| 1924 | 4.5 Pre-building configuration |
| 1925 | ------------------------------ |
| 1926 | |
| 1927 | Before building Exim, a local configuration file that specifies options |
| 1928 | independent of any operating system has to be created with the name Local/ |
| 1929 | Makefile. A template for this file is supplied as the file src/EDITME, and it |
| 1930 | contains full descriptions of all the option settings therein. These |
| 1931 | descriptions are therefore not repeated here. If you are building Exim for the |
| 1932 | first time, the simplest thing to do is to copy src/EDITME to Local/Makefile, |
| 1933 | then read it and edit it appropriately. |
| 1934 | |
| 1935 | There are three settings that you must supply, because Exim will not build |
| 1936 | without them. They are the location of the run time configuration file |
| 1937 | (CONFIGURE_FILE), the directory in which Exim binaries will be installed |
| 1938 | (BIN_DIRECTORY), and the identity of the Exim user (EXIM_USER and maybe |
| 1939 | EXIM_GROUP as well). The value of CONFIGURE_FILE can in fact be a |
| 1940 | colon-separated list of file names; Exim uses the first of them that exists. |
| 1941 | |
| 1942 | There are a few other parameters that can be specified either at build time or |
| 1943 | at run time, to enable the same binary to be used on a number of different |
| 1944 | machines. However, if the locations of Exim's spool directory and log file |
| 1945 | directory (if not within the spool directory) are fixed, it is recommended that |
| 1946 | you specify them in Local/Makefile instead of at run time, so that errors |
| 1947 | detected early in Exim's execution (such as a malformed configuration file) can |
| 1948 | be logged. |
| 1949 | |
| 1950 | Exim's interfaces for calling virus and spam scanning software directly from |
| 1951 | access control lists are not compiled by default. If you want to include these |
| 1952 | facilities, you need to set |
| 1953 | |
| 1954 | WITH_CONTENT_SCAN=yes |
| 1955 | |
| 1956 | in your Local/Makefile. For details of the facilities themselves, see chapter |
| 1957 | 44. |
| 1958 | |
| 1959 | If you are going to build the Exim monitor, a similar configuration process is |
| 1960 | required. The file exim_monitor/EDITME must be edited appropriately for your |
| 1961 | installation and saved under the name Local/eximon.conf. If you are happy with |
| 1962 | the default settings described in exim_monitor/EDITME, Local/eximon.conf can be |
| 1963 | empty, but it must exist. |
| 1964 | |
| 1965 | This is all the configuration that is needed in straightforward cases for known |
| 1966 | operating systems. However, the building process is set up so that it is easy |
| 1967 | to override options that are set by default or by operating-system-specific |
| 1968 | configuration files, for example to change the name of the C compiler, which |
| 1969 | defaults to gcc. See section 4.13 below for details of how to do this. |
| 1970 | |
| 1971 | |
| 1972 | 4.6 Support for iconv() |
| 1973 | ----------------------- |
| 1974 | |
| 1975 | The contents of header lines in messages may be encoded according to the rules |
| 1976 | described RFC 2047. This makes it possible to transmit characters that are not |
| 1977 | in the ASCII character set, and to label them as being in a particular |
| 1978 | character set. When Exim is inspecting header lines by means of the $h_ |
| 1979 | mechanism, it decodes them, and translates them into a specified character set |
| 1980 | (default is set at build time). The translation is possible only if the |
| 1981 | operating system supports the iconv() function. |
| 1982 | |
| 1983 | However, some of the operating systems that supply iconv() do not support very |
| 1984 | many conversions. The GNU libiconv library (available from http://www.gnu.org/ |
| 1985 | software/libiconv/) can be installed on such systems to remedy this deficiency, |
| 1986 | as well as on systems that do not supply iconv() at all. After installing |
| 1987 | libiconv, you should add |
| 1988 | |
| 1989 | HAVE_ICONV=yes |
| 1990 | |
| 1991 | to your Local/Makefile and rebuild Exim. |
| 1992 | |
| 1993 | |
| 1994 | 4.7 Including TLS/SSL encryption support |
| 1995 | ---------------------------------------- |
| 1996 | |
| 1997 | Exim can be built to support encrypted SMTP connections, using the STARTTLS |
| 1998 | command as per RFC 2487. It can also support legacy clients that expect to |
| 1999 | start a TLS session immediately on connection to a non-standard port (see the |
| 2000 | tls_on_connect_ports runtime option and the -tls-on-connect command line |
| 2001 | option). |
| 2002 | |
| 2003 | If you want to build Exim with TLS support, you must first install either the |
| 2004 | OpenSSL or GnuTLS library. There is no cryptographic code in Exim itself for |
| 2005 | implementing SSL. |
| 2006 | |
| 2007 | If OpenSSL is installed, you should set |
| 2008 | |
| 2009 | SUPPORT_TLS=yes |
| 2010 | TLS_LIBS=-lssl -lcrypto |
| 2011 | |
| 2012 | in Local/Makefile. You may also need to specify the locations of the OpenSSL |
| 2013 | library and include files. For example: |
| 2014 | |
| 2015 | SUPPORT_TLS=yes |
| 2016 | TLS_LIBS=-L/usr/local/openssl/lib -lssl -lcrypto |
| 2017 | TLS_INCLUDE=-I/usr/local/openssl/include/ |
| 2018 | |
| 2019 | If you have pkg-config available, then instead you can just use: |
| 2020 | |
| 2021 | SUPPORT_TLS=yes |
| 2022 | USE_OPENSSL_PC=openssl |
| 2023 | |
| 2024 | If GnuTLS is installed, you should set |
| 2025 | |
| 2026 | SUPPORT_TLS=yes |
| 2027 | USE_GNUTLS=yes |
| 2028 | TLS_LIBS=-lgnutls -ltasn1 -lgcrypt |
| 2029 | |
| 2030 | in Local/Makefile, and again you may need to specify the locations of the |
| 2031 | library and include files. For example: |
| 2032 | |
| 2033 | SUPPORT_TLS=yes |
| 2034 | USE_GNUTLS=yes |
| 2035 | TLS_LIBS=-L/usr/gnu/lib -lgnutls -ltasn1 -lgcrypt |
| 2036 | TLS_INCLUDE=-I/usr/gnu/include |
| 2037 | |
| 2038 | If you have pkg-config available, then instead you can just use: |
| 2039 | |
| 2040 | SUPPORT_TLS=yes |
| 2041 | USE_GNUTLS=yes |
| 2042 | USE_GNUTLS_PC=gnutls |
| 2043 | |
| 2044 | You do not need to set TLS_INCLUDE if the relevant directory is already |
| 2045 | specified in INCLUDE. Details of how to configure Exim to make use of TLS are |
| 2046 | given in chapter 42. |
| 2047 | |
| 2048 | |
| 2049 | 4.8 Use of tcpwrappers |
| 2050 | ---------------------- |
| 2051 | |
| 2052 | Exim can be linked with the tcpwrappers library in order to check incoming SMTP |
| 2053 | calls using the tcpwrappers control files. This may be a convenient alternative |
| 2054 | to Exim's own checking facilities for installations that are already making use |
| 2055 | of tcpwrappers for other purposes. To do this, you should set USE_TCP_WRAPPERS |
| 2056 | in Local/Makefile, arrange for the file tcpd.h to be available at compile time, |
| 2057 | and also ensure that the library libwrap.a is available at link time, typically |
| 2058 | by including -lwrap in EXTRALIBS_EXIM. For example, if tcpwrappers is installed |
| 2059 | in /usr/local, you might have |
| 2060 | |
| 2061 | USE_TCP_WRAPPERS=yes |
| 2062 | CFLAGS=-O -I/usr/local/include |
| 2063 | EXTRALIBS_EXIM=-L/usr/local/lib -lwrap |
| 2064 | |
| 2065 | in Local/Makefile. The daemon name to use in the tcpwrappers control files is |
| 2066 | "exim". For example, the line |
| 2067 | |
| 2068 | exim : LOCAL 192.168.1. .friendly.domain.example |
| 2069 | |
| 2070 | in your /etc/hosts.allow file allows connections from the local host, from the |
| 2071 | subnet 192.168.1.0/24, and from all hosts in friendly.domain.example. All other |
| 2072 | connections are denied. The daemon name used by tcpwrappers can be changed at |
| 2073 | build time by setting TCP_WRAPPERS_DAEMON_NAME in Local/Makefile, or by setting |
| 2074 | tcp_wrappers_daemon_name in the configure file. Consult the tcpwrappers |
| 2075 | documentation for further details. |
| 2076 | |
| 2077 | |
| 2078 | 4.9 Including support for IPv6 |
| 2079 | ------------------------------ |
| 2080 | |
| 2081 | Exim contains code for use on systems that have IPv6 support. Setting |
| 2082 | "HAVE_IPV6=YES" in Local/Makefile causes the IPv6 code to be included; it may |
| 2083 | also be necessary to set IPV6_INCLUDE and IPV6_LIBS on systems where the IPv6 |
| 2084 | support is not fully integrated into the normal include and library files. |
| 2085 | |
| 2086 | Two different types of DNS record for handling IPv6 addresses have been |
| 2087 | defined. AAAA records (analogous to A records for IPv4) are in use, and are |
| 2088 | currently seen as the mainstream. Another record type called A6 was proposed as |
| 2089 | better than AAAA because it had more flexibility. However, it was felt to be |
| 2090 | over-complex, and its status was reduced to "experimental". Exim used to have a |
| 2091 | compile option for including A6 record support but this has now been withdrawn. |
| 2092 | |
| 2093 | |
| 2094 | 4.10 Dynamically loaded lookup module support |
| 2095 | --------------------------------------------- |
| 2096 | |
| 2097 | On some platforms, Exim supports not compiling all lookup types directly into |
| 2098 | the main binary, instead putting some into external modules which can be loaded |
| 2099 | on demand. This permits packagers to build Exim with support for lookups with |
| 2100 | extensive library dependencies without requiring all users to install all of |
| 2101 | those dependencies. Most, but not all, lookup types can be built this way. |
| 2102 | |
| 2103 | Set "LOOKUP_MODULE_DIR" to the directory into which the modules will be |
| 2104 | installed; Exim will only load modules from that directory, as a security |
| 2105 | measure. You will need to set "CFLAGS_DYNAMIC" if not already defined for your |
| 2106 | OS; see OS/Makefile-Linux for an example. Some other requirements for adjusting |
| 2107 | "EXTRALIBS" may also be necessary, see src/EDITME for details. |
| 2108 | |
| 2109 | Then, for each module to be loaded dynamically, define the relevant "LOOKUP_"< |
| 2110 | lookup_type> flags to have the value "2" instead of "yes". For example, this |
| 2111 | will build in lsearch but load sqlite and mysql support on demand: |
| 2112 | |
| 2113 | LOOKUP_LSEARCH=yes |
| 2114 | LOOKUP_SQLITE=2 |
| 2115 | LOOKUP_MYSQL=2 |
| 2116 | |
| 2117 | |
| 2118 | 4.11 The building process |
| 2119 | ------------------------- |
| 2120 | |
| 2121 | Once Local/Makefile (and Local/eximon.conf, if required) have been created, run |
| 2122 | make at the top level. It determines the architecture and operating system |
| 2123 | types, and creates a build directory if one does not exist. For example, on a |
| 2124 | Sun system running Solaris 8, the directory build-SunOS5-5.8-sparc is created. |
| 2125 | Symbolic links to relevant source files are installed in the build directory. |
| 2126 | |
| 2127 | If this is the first time make has been run, it calls a script that builds a |
| 2128 | make file inside the build directory, using the configuration files from the |
| 2129 | Local directory. The new make file is then passed to another instance of make. |
| 2130 | This does the real work, building a number of utility scripts, and then |
| 2131 | compiling and linking the binaries for the Exim monitor (if configured), a |
| 2132 | number of utility programs, and finally Exim itself. The command "make |
| 2133 | makefile" can be used to force a rebuild of the make file in the build |
| 2134 | directory, should this ever be necessary. |
| 2135 | |
| 2136 | If you have problems building Exim, check for any comments there may be in the |
| 2137 | README file concerning your operating system, and also take a look at the FAQ, |
| 2138 | where some common problems are covered. |
| 2139 | |
| 2140 | |
| 2141 | 4.12 Output from "make" |
| 2142 | ----------------------- |
| 2143 | |
| 2144 | The output produced by the make process for compile lines is often very |
| 2145 | unreadable, because these lines can be very long. For this reason, the normal |
| 2146 | output is suppressed by default, and instead output similar to that which |
| 2147 | appears when compiling the 2.6 Linux kernel is generated: just a short line for |
| 2148 | each module that is being compiled or linked. However, it is still possible to |
| 2149 | get the full output, by calling make like this: |
| 2150 | |
| 2151 | FULLECHO='' make -e |
| 2152 | |
| 2153 | The value of FULLECHO defaults to "@", the flag character that suppresses |
| 2154 | command reflection in make. When you ask for the full output, it is given in |
| 2155 | addition to the short output. |
| 2156 | |
| 2157 | |
| 2158 | 4.13 Overriding build-time options for Exim |
| 2159 | ------------------------------------------- |
| 2160 | |
| 2161 | The main make file that is created at the beginning of the building process |
| 2162 | consists of the concatenation of a number of files which set configuration |
| 2163 | values, followed by a fixed set of make instructions. If a value is set more |
| 2164 | than once, the last setting overrides any previous ones. This provides a |
| 2165 | convenient way of overriding defaults. The files that are concatenated are, in |
| 2166 | order: |
| 2167 | |
| 2168 | OS/Makefile-Default |
| 2169 | OS/Makefile-<ostype> |
| 2170 | Local/Makefile |
| 2171 | Local/Makefile-<ostype> |
| 2172 | Local/Makefile-<archtype> |
| 2173 | Local/Makefile-<ostype>-<archtype> |
| 2174 | OS/Makefile-Base |
| 2175 | |
| 2176 | where <ostype> is the operating system type and <archtype> is the architecture |
| 2177 | type. Local/Makefile is required to exist, and the building process fails if it |
| 2178 | is absent. The other three Local files are optional, and are often not needed. |
| 2179 | |
| 2180 | The values used for <ostype> and <archtype> are obtained from scripts called |
| 2181 | scripts/os-type and scripts/arch-type respectively. If either of the |
| 2182 | environment variables EXIM_OSTYPE or EXIM_ARCHTYPE is set, their values are |
| 2183 | used, thereby providing a means of forcing particular settings. Otherwise, the |
| 2184 | scripts try to get values from the uname command. If this fails, the shell |
| 2185 | variables OSTYPE and ARCHTYPE are inspected. A number of ad hoc transformations |
| 2186 | are then applied, to produce the standard names that Exim expects. You can run |
| 2187 | these scripts directly from the shell in order to find out what values are |
| 2188 | being used on your system. |
| 2189 | |
| 2190 | OS/Makefile-Default contains comments about the variables that are set therein. |
| 2191 | Some (but not all) are mentioned below. If there is something that needs |
| 2192 | changing, review the contents of this file and the contents of the make file |
| 2193 | for your operating system (OS/Makefile-<ostype>) to see what the default values |
| 2194 | are. |
| 2195 | |
| 2196 | If you need to change any of the values that are set in OS/Makefile-Default or |
| 2197 | in OS/Makefile-<ostype>, or to add any new definitions, you do not need to |
| 2198 | change the original files. Instead, you should make the changes by putting the |
| 2199 | new values in an appropriate Local file. For example, when building Exim in |
| 2200 | many releases of the Tru64-Unix (formerly Digital UNIX, formerly DEC-OSF1) |
| 2201 | operating system, it is necessary to specify that the C compiler is called cc |
| 2202 | rather than gcc. Also, the compiler must be called with the option -std1, to |
| 2203 | make it recognize some of the features of Standard C that Exim uses. (Most |
| 2204 | other compilers recognize Standard C by default.) To do this, you should create |
| 2205 | a file called Local/Makefile-OSF1 containing the lines |
| 2206 | |
| 2207 | CC=cc |
| 2208 | CFLAGS=-std1 |
| 2209 | |
| 2210 | If you are compiling for just one operating system, it may be easier to put |
| 2211 | these lines directly into Local/Makefile. |
| 2212 | |
| 2213 | Keeping all your local configuration settings separate from the distributed |
| 2214 | files makes it easy to transfer them to new versions of Exim simply by copying |
| 2215 | the contents of the Local directory. |
| 2216 | |
| 2217 | Exim contains support for doing LDAP, NIS, NIS+, and other kinds of file |
| 2218 | lookup, but not all systems have these components installed, so the default is |
| 2219 | not to include the relevant code in the binary. All the different kinds of file |
| 2220 | and database lookup that Exim supports are implemented as separate code modules |
| 2221 | which are included only if the relevant compile-time options are set. In the |
| 2222 | case of LDAP, NIS, and NIS+, the settings for Local/Makefile are: |
| 2223 | |
| 2224 | LOOKUP_LDAP=yes |
| 2225 | LOOKUP_NIS=yes |
| 2226 | LOOKUP_NISPLUS=yes |
| 2227 | |
| 2228 | and similar settings apply to the other lookup types. They are all listed in |
| 2229 | src/EDITME. In many cases the relevant include files and interface libraries |
| 2230 | need to be installed before compiling Exim. However, there are some optional |
| 2231 | lookup types (such as cdb) for which the code is entirely contained within |
| 2232 | Exim, and no external include files or libraries are required. When a lookup |
| 2233 | type is not included in the binary, attempts to configure Exim to use it cause |
| 2234 | run time configuration errors. |
| 2235 | |
| 2236 | Many systems now use a tool called pkg-config to encapsulate information about |
| 2237 | how to compile against a library; Exim has some initial support for being able |
| 2238 | to use pkg-config for lookups and authenticators. For any given makefile |
| 2239 | variable which starts "LOOKUP_" or "AUTH_", you can add a new variable with the |
| 2240 | "_PC" suffix in the name and assign as the value the name of the package to be |
| 2241 | queried. The results of querying via the pkg-config command will be added to |
| 2242 | the appropriate Makefile variables with "+=" directives, so your version of |
| 2243 | make will need to support that syntax. For instance: |
| 2244 | |
| 2245 | LOOKUP_SQLITE=yes |
| 2246 | LOOKUP_SQLITE_PC=sqlite3 |
| 2247 | AUTH_GSASL=yes |
| 2248 | AUTH_GSASL_PC=libgsasl |
| 2249 | AUTH_HEIMDAL_GSSAPI=yes |
| 2250 | AUTH_HEIMDAL_GSSAPI_PC=heimdal-gssapi |
| 2251 | |
| 2252 | Exim can be linked with an embedded Perl interpreter, allowing Perl subroutines |
| 2253 | to be called during string expansion. To enable this facility, |
| 2254 | |
| 2255 | EXIM_PERL=perl.o |
| 2256 | |
| 2257 | must be defined in Local/Makefile. Details of this facility are given in |
| 2258 | chapter 12. |
| 2259 | |
| 2260 | The location of the X11 libraries is something that varies a lot between |
| 2261 | operating systems, and there may be different versions of X11 to cope with. |
| 2262 | Exim itself makes no use of X11, but if you are compiling the Exim monitor, the |
| 2263 | X11 libraries must be available. The following three variables are set in OS/ |
| 2264 | Makefile-Default: |
| 2265 | |
| 2266 | X11=/usr/X11R6 |
| 2267 | XINCLUDE=-I$(X11)/include |
| 2268 | XLFLAGS=-L$(X11)/lib |
| 2269 | |
| 2270 | These are overridden in some of the operating-system configuration files. For |
| 2271 | example, in OS/Makefile-SunOS5 there is |
| 2272 | |
| 2273 | X11=/usr/openwin |
| 2274 | XINCLUDE=-I$(X11)/include |
| 2275 | XLFLAGS=-L$(X11)/lib -R$(X11)/lib |
| 2276 | |
| 2277 | If you need to override the default setting for your operating system, place a |
| 2278 | definition of all three of these variables into your Local/Makefile-<ostype> |
| 2279 | file. |
| 2280 | |
| 2281 | If you need to add any extra libraries to the link steps, these can be put in a |
| 2282 | variable called EXTRALIBS, which appears in all the link commands, but by |
| 2283 | default is not defined. In contrast, EXTRALIBS_EXIM is used only on the command |
| 2284 | for linking the main Exim binary, and not for any associated utilities. |
| 2285 | |
| 2286 | There is also DBMLIB, which appears in the link commands for binaries that use |
| 2287 | DBM functions (see also section 4.4). Finally, there is EXTRALIBS_EXIMON, which |
| 2288 | appears only in the link step for the Exim monitor binary, and which can be |
| 2289 | used, for example, to include additional X11 libraries. |
| 2290 | |
| 2291 | The make file copes with rebuilding Exim correctly if any of the configuration |
| 2292 | files are edited. However, if an optional configuration file is deleted, it is |
| 2293 | necessary to touch the associated non-optional file (that is, Local/Makefile or |
| 2294 | Local/eximon.conf) before rebuilding. |
| 2295 | |
| 2296 | |
| 2297 | 4.14 OS-specific header files |
| 2298 | ----------------------------- |
| 2299 | |
| 2300 | The OS directory contains a number of files with names of the form os.h- |
| 2301 | <ostype>. These are system-specific C header files that should not normally |
| 2302 | need to be changed. There is a list of macro settings that are recognized in |
| 2303 | the file OS/os.configuring, which should be consulted if you are porting Exim |
| 2304 | to a new operating system. |
| 2305 | |
| 2306 | |
| 2307 | 4.15 Overriding build-time options for the monitor |
| 2308 | -------------------------------------------------- |
| 2309 | |
| 2310 | A similar process is used for overriding things when building the Exim monitor, |
| 2311 | where the files that are involved are |
| 2312 | |
| 2313 | OS/eximon.conf-Default |
| 2314 | OS/eximon.conf-<ostype> |
| 2315 | Local/eximon.conf |
| 2316 | Local/eximon.conf-<ostype> |
| 2317 | Local/eximon.conf-<archtype> |
| 2318 | Local/eximon.conf-<ostype>-<archtype> |
| 2319 | |
| 2320 | As with Exim itself, the final three files need not exist, and in this case the |
| 2321 | OS/eximon.conf-<ostype> file is also optional. The default values in OS/ |
| 2322 | eximon.conf-Default can be overridden dynamically by setting environment |
| 2323 | variables of the same name, preceded by EXIMON_. For example, setting |
| 2324 | EXIMON_LOG_DEPTH in the environment overrides the value of LOG_DEPTH at run |
| 2325 | time. |
| 2326 | |
| 2327 | |
| 2328 | 4.16 Installing Exim binaries and scripts |
| 2329 | ----------------------------------------- |
| 2330 | |
| 2331 | The command "make install" runs the exim_install script with no arguments. The |
| 2332 | script copies binaries and utility scripts into the directory whose name is |
| 2333 | specified by the BIN_DIRECTORY setting in Local/Makefile. The install script |
| 2334 | copies files only if they are newer than the files they are going to replace. |
| 2335 | The Exim binary is required to be owned by root and have the setuid bit set, |
| 2336 | for normal configurations. Therefore, you must run "make install" as root so |
| 2337 | that it can set up the Exim binary in this way. However, in some special |
| 2338 | situations (for example, if a host is doing no local deliveries) it may be |
| 2339 | possible to run Exim without making the binary setuid root (see chapter 55 for |
| 2340 | details). |
| 2341 | |
| 2342 | Exim's run time configuration file is named by the CONFIGURE_FILE setting in |
| 2343 | Local/Makefile. If this names a single file, and the file does not exist, the |
| 2344 | default configuration file src/configure.default is copied there by the |
| 2345 | installation script. If a run time configuration file already exists, it is |
| 2346 | left alone. If CONFIGURE_FILE is a colon-separated list, naming several |
| 2347 | alternative files, no default is installed. |
| 2348 | |
| 2349 | One change is made to the default configuration file when it is installed: the |
| 2350 | default configuration contains a router that references a system aliases file. |
| 2351 | The path to this file is set to the value specified by SYSTEM_ALIASES_FILE in |
| 2352 | Local/Makefile (/etc/aliases by default). If the system aliases file does not |
| 2353 | exist, the installation script creates it, and outputs a comment to the user. |
| 2354 | |
| 2355 | The created file contains no aliases, but it does contain comments about the |
| 2356 | aliases a site should normally have. Mail aliases have traditionally been kept |
| 2357 | in /etc/aliases. However, some operating systems are now using /etc/mail/ |
| 2358 | aliases. You should check if yours is one of these, and change Exim's |
| 2359 | configuration if necessary. |
| 2360 | |
| 2361 | The default configuration uses the local host's name as the only local domain, |
| 2362 | and is set up to do local deliveries into the shared directory /var/mail, |
| 2363 | running as the local user. System aliases and .forward files in users' home |
| 2364 | directories are supported, but no NIS or NIS+ support is configured. Domains |
| 2365 | other than the name of the local host are routed using the DNS, with delivery |
| 2366 | over SMTP. |
| 2367 | |
| 2368 | It is possible to install Exim for special purposes (such as building a binary |
| 2369 | distribution) in a private part of the file system. You can do this by a |
| 2370 | command such as |
| 2371 | |
| 2372 | make DESTDIR=/some/directory/ install |
| 2373 | |
| 2374 | This has the effect of pre-pending the specified directory to all the file |
| 2375 | paths, except the name of the system aliases file that appears in the default |
| 2376 | configuration. (If a default alias file is created, its name is modified.) For |
| 2377 | backwards compatibility, ROOT is used if DESTDIR is not set, but this usage is |
| 2378 | deprecated. |
| 2379 | |
| 2380 | Running make install does not copy the Exim 4 conversion script convert4r4. You |
| 2381 | will probably run this only once if you are upgrading from Exim 3. None of the |
| 2382 | documentation files in the doc directory are copied, except for the info files |
| 2383 | when you have set INFO_DIRECTORY, as described in section 4.17 below. |
| 2384 | |
| 2385 | For the utility programs, old versions are renamed by adding the suffix .O to |
| 2386 | their names. The Exim binary itself, however, is handled differently. It is |
| 2387 | installed under a name that includes the version number and the compile number, |
| 2388 | for example exim-4.89-1. The script then arranges for a symbolic link called |
| 2389 | exim to point to the binary. If you are updating a previous version of Exim, |
| 2390 | the script takes care to ensure that the name exim is never absent from the |
| 2391 | directory (as seen by other processes). |
| 2392 | |
| 2393 | If you want to see what the make install will do before running it for real, |
| 2394 | you can pass the -n option to the installation script by this command: |
| 2395 | |
| 2396 | make INSTALL_ARG=-n install |
| 2397 | |
| 2398 | The contents of the variable INSTALL_ARG are passed to the installation script. |
| 2399 | You do not need to be root to run this test. Alternatively, you can run the |
| 2400 | installation script directly, but this must be from within the build directory. |
| 2401 | For example, from the top-level Exim directory you could use this command: |
| 2402 | |
| 2403 | (cd build-SunOS5-5.5.1-sparc; ../scripts/exim_install -n) |
| 2404 | |
| 2405 | There are two other options that can be supplied to the installation script. |
| 2406 | |
| 2407 | * -no_chown bypasses the call to change the owner of the installed binary to |
| 2408 | root, and the call to make it a setuid binary. |
| 2409 | |
| 2410 | * -no_symlink bypasses the setting up of the symbolic link exim to the |
| 2411 | installed binary. |
| 2412 | |
| 2413 | INSTALL_ARG can be used to pass these options to the script. For example: |
| 2414 | |
| 2415 | make INSTALL_ARG=-no_symlink install |
| 2416 | |
| 2417 | The installation script can also be given arguments specifying which files are |
| 2418 | to be copied. For example, to install just the Exim binary, and nothing else, |
| 2419 | without creating the symbolic link, you could use: |
| 2420 | |
| 2421 | make INSTALL_ARG='-no_symlink exim' install |
| 2422 | |
| 2423 | |
| 2424 | 4.17 Installing info documentation |
| 2425 | ---------------------------------- |
| 2426 | |
| 2427 | Not all systems use the GNU info system for documentation, and for this reason, |
| 2428 | the Texinfo source of Exim's documentation is not included in the main |
| 2429 | distribution. Instead it is available separately from the ftp site (see section |
| 2430 | 1.6). |
| 2431 | |
| 2432 | If you have defined INFO_DIRECTORY in Local/Makefile and the Texinfo source of |
| 2433 | the documentation is found in the source tree, running "make install" |
| 2434 | automatically builds the info files and installs them. |
| 2435 | |
| 2436 | |
| 2437 | 4.18 Setting up the spool directory |
| 2438 | ----------------------------------- |
| 2439 | |
| 2440 | When it starts up, Exim tries to create its spool directory if it does not |
| 2441 | exist. The Exim uid and gid are used for the owner and group of the spool |
| 2442 | directory. Sub-directories are automatically created in the spool directory as |
| 2443 | necessary. |
| 2444 | |
| 2445 | |
| 2446 | 4.19 Testing |
| 2447 | ------------ |
| 2448 | |
| 2449 | Having installed Exim, you can check that the run time configuration file is |
| 2450 | syntactically valid by running the following command, which assumes that the |
| 2451 | Exim binary directory is within your PATH environment variable: |
| 2452 | |
| 2453 | exim -bV |
| 2454 | |
| 2455 | If there are any errors in the configuration file, Exim outputs error messages. |
| 2456 | Otherwise it outputs the version number and build date, the DBM library that is |
| 2457 | being used, and information about which drivers and other optional code modules |
| 2458 | are included in the binary. Some simple routing tests can be done by using the |
| 2459 | address testing option. For example, |
| 2460 | |
| 2461 | exim -bt <local username> |
| 2462 | |
| 2463 | should verify that it recognizes a local mailbox, and |
| 2464 | |
| 2465 | exim -bt <remote address> |
| 2466 | |
| 2467 | a remote one. Then try getting it to deliver mail, both locally and remotely. |
| 2468 | This can be done by passing messages directly to Exim, without going through a |
| 2469 | user agent. For example: |
| 2470 | |
| 2471 | exim -v postmaster@your.domain.example |
| 2472 | From: user@your.domain.example |
| 2473 | To: postmaster@your.domain.example |
| 2474 | Subject: Testing Exim |
| 2475 | |
| 2476 | This is a test message. |
| 2477 | ^D |
| 2478 | |
| 2479 | The -v option causes Exim to output some verification of what it is doing. In |
| 2480 | this case you should see copies of three log lines, one for the message's |
| 2481 | arrival, one for its delivery, and one containing "Completed". |
| 2482 | |
| 2483 | If you encounter problems, look at Exim's log files (mainlog and paniclog) to |
| 2484 | see if there is any relevant information there. Another source of information |
| 2485 | is running Exim with debugging turned on, by specifying the -d option. If a |
| 2486 | message is stuck on Exim's spool, you can force a delivery with debugging |
| 2487 | turned on by a command of the form |
| 2488 | |
| 2489 | exim -d -M <exim-message-id> |
| 2490 | |
| 2491 | You must be root or an "admin user" in order to do this. The -d option produces |
| 2492 | rather a lot of output, but you can cut this down to specific areas. For |
| 2493 | example, if you use -d-all+route only the debugging information relevant to |
| 2494 | routing is included. (See the -d option in chapter 5 for more details.) |
| 2495 | |
| 2496 | One specific problem that has shown up on some sites is the inability to do |
| 2497 | local deliveries into a shared mailbox directory, because it does not have the |
| 2498 | "sticky bit" set on it. By default, Exim tries to create a lock file before |
| 2499 | writing to a mailbox file, and if it cannot create the lock file, the delivery |
| 2500 | is deferred. You can get round this either by setting the "sticky bit" on the |
| 2501 | directory, or by setting a specific group for local deliveries and allowing |
| 2502 | that group to create files in the directory (see the comments above the |
| 2503 | local_delivery transport in the default configuration file). Another approach |
| 2504 | is to configure Exim not to use lock files, but just to rely on fcntl() locking |
| 2505 | instead. However, you should do this only if all user agents also use fcntl() |
| 2506 | locking. For further discussion of locking issues, see chapter 26. |
| 2507 | |
| 2508 | One thing that cannot be tested on a system that is already running an MTA is |
| 2509 | the receipt of incoming SMTP mail on the standard SMTP port. However, the -oX |
| 2510 | option can be used to run an Exim daemon that listens on some other port, or |
| 2511 | inetd can be used to do this. The -bh option and the exim_checkaccess utility |
| 2512 | can be used to check out policy controls on incoming SMTP mail. |
| 2513 | |
| 2514 | Testing a new version on a system that is already running Exim can most easily |
| 2515 | be done by building a binary with a different CONFIGURE_FILE setting. From |
| 2516 | within the run time configuration, all other file and directory names that Exim |
| 2517 | uses can be altered, in order to keep it entirely clear of the production |
| 2518 | version. |
| 2519 | |
| 2520 | |
| 2521 | 4.20 Replacing another MTA with Exim |
| 2522 | ------------------------------------ |
| 2523 | |
| 2524 | Building and installing Exim for the first time does not of itself put it in |
| 2525 | general use. The name by which the system's MTA is called by mail user agents |
| 2526 | is either /usr/sbin/sendmail, or /usr/lib/sendmail (depending on the operating |
| 2527 | system), and it is necessary to make this name point to the exim binary in |
| 2528 | order to get the user agents to pass messages to Exim. This is normally done by |
| 2529 | renaming any existing file and making /usr/sbin/sendmail or /usr/lib/sendmail a |
| 2530 | symbolic link to the exim binary. It is a good idea to remove any setuid |
| 2531 | privilege and executable status from the old MTA. It is then necessary to stop |
| 2532 | and restart the mailer daemon, if one is running. |
| 2533 | |
| 2534 | Some operating systems have introduced alternative ways of switching MTAs. For |
| 2535 | example, if you are running FreeBSD, you need to edit the file /etc/mail/ |
| 2536 | mailer.conf instead of setting up a symbolic link as just described. A typical |
| 2537 | example of the contents of this file for running Exim is as follows: |
| 2538 | |
| 2539 | sendmail /usr/exim/bin/exim |
| 2540 | send-mail /usr/exim/bin/exim |
| 2541 | mailq /usr/exim/bin/exim -bp |
| 2542 | newaliases /usr/bin/true |
| 2543 | |
| 2544 | Once you have set up the symbolic link, or edited /etc/mail/mailer.conf, your |
| 2545 | Exim installation is "live". Check it by sending a message from your favourite |
| 2546 | user agent. |
| 2547 | |
| 2548 | You should consider what to tell your users about the change of MTA. Exim may |
| 2549 | have different capabilities to what was previously running, and there are |
| 2550 | various operational differences such as the text of messages produced by |
| 2551 | command line options and in bounce messages. If you allow your users to make |
| 2552 | use of Exim's filtering capabilities, you should make the document entitled |
| 2553 | Exim's interface to mail filtering available to them. |
| 2554 | |
| 2555 | |
| 2556 | 4.21 Upgrading Exim |
| 2557 | ------------------- |
| 2558 | |
| 2559 | If you are already running Exim on your host, building and installing a new |
| 2560 | version automatically makes it available to MUAs, or any other programs that |
| 2561 | call the MTA directly. However, if you are running an Exim daemon, you do need |
| 2562 | to send it a HUP signal, to make it re-execute itself, and thereby pick up the |
| 2563 | new binary. You do not need to stop processing mail in order to install a new |
| 2564 | version of Exim. The install script does not modify an existing runtime |
| 2565 | configuration file. |
| 2566 | |
| 2567 | |
| 2568 | 4.22 Stopping the Exim daemon on Solaris |
| 2569 | ---------------------------------------- |
| 2570 | |
| 2571 | The standard command for stopping the mailer daemon on Solaris is |
| 2572 | |
| 2573 | /etc/init.d/sendmail stop |
| 2574 | |
| 2575 | If /usr/lib/sendmail has been turned into a symbolic link, this script fails to |
| 2576 | stop Exim because it uses the command ps -e and greps the output for the text |
| 2577 | "sendmail"; this is not present because the actual program name (that is, |
| 2578 | "exim") is given by the ps command with these options. A solution is to replace |
| 2579 | the line that finds the process id with something like |
| 2580 | |
| 2581 | pid=`cat /var/spool/exim/exim-daemon.pid` |
| 2582 | |
| 2583 | to obtain the daemon's pid directly from the file that Exim saves it in. |
| 2584 | |
| 2585 | Note, however, that stopping the daemon does not "stop Exim". Messages can |
| 2586 | still be received from local processes, and if automatic delivery is configured |
| 2587 | (the normal case), deliveries will still occur. |
| 2588 | |
| 2589 | |
| 2590 | |
| 2591 | =============================================================================== |
| 2592 | 5. THE EXIM COMMAND LINE |
| 2593 | |
| 2594 | Exim's command line takes the standard Unix form of a sequence of options, each |
| 2595 | starting with a hyphen character, followed by a number of arguments. The |
| 2596 | options are compatible with the main options of Sendmail, and there are also |
| 2597 | some additional options, some of which are compatible with Smail 3. Certain |
| 2598 | combinations of options do not make sense, and provoke an error if used. The |
| 2599 | form of the arguments depends on which options are set. |
| 2600 | |
| 2601 | |
| 2602 | 5.1 Setting options by program name |
| 2603 | ----------------------------------- |
| 2604 | |
| 2605 | If Exim is called under the name mailq, it behaves as if the option -bp were |
| 2606 | present before any other options. The -bp option requests a listing of the |
| 2607 | contents of the mail queue on the standard output. This feature is for |
| 2608 | compatibility with some systems that contain a command of that name in one of |
| 2609 | the standard libraries, symbolically linked to /usr/sbin/sendmail or /usr/lib/ |
| 2610 | sendmail. |
| 2611 | |
| 2612 | If Exim is called under the name rsmtp it behaves as if the option -bS were |
| 2613 | present before any other options, for compatibility with Smail. The -bS option |
| 2614 | is used for reading in a number of messages in batched SMTP format. |
| 2615 | |
| 2616 | If Exim is called under the name rmail it behaves as if the -i and -oee options |
| 2617 | were present before any other options, for compatibility with Smail. The name |
| 2618 | rmail is used as an interface by some UUCP systems. |
| 2619 | |
| 2620 | If Exim is called under the name runq it behaves as if the option -q were |
| 2621 | present before any other options, for compatibility with Smail. The -q option |
| 2622 | causes a single queue runner process to be started. |
| 2623 | |
| 2624 | If Exim is called under the name newaliases it behaves as if the option -bi |
| 2625 | were present before any other options, for compatibility with Sendmail. This |
| 2626 | option is used for rebuilding Sendmail's alias file. Exim does not have the |
| 2627 | concept of a single alias file, but can be configured to run a given command if |
| 2628 | called with the -bi option. |
| 2629 | |
| 2630 | |
| 2631 | 5.2 Trusted and admin users |
| 2632 | --------------------------- |
| 2633 | |
| 2634 | Some Exim options are available only to trusted users and others are available |
| 2635 | only to admin users. In the description below, the phrases "Exim user" and |
| 2636 | "Exim group" mean the user and group defined by EXIM_USER and EXIM_GROUP in |
| 2637 | Local/Makefile or set by the exim_user and exim_group options. These do not |
| 2638 | necessarily have to use the name "exim". |
| 2639 | |
| 2640 | * The trusted users are root, the Exim user, any user listed in the |
| 2641 | trusted_users configuration option, and any user whose current group or any |
| 2642 | supplementary group is one of those listed in the trusted_groups |
| 2643 | configuration option. Note that the Exim group is not automatically |
| 2644 | trusted. |
| 2645 | |
| 2646 | Trusted users are always permitted to use the -f option or a leading |
| 2647 | "From " line to specify the envelope sender of a message that is passed to |
| 2648 | Exim through the local interface (see the -bm and -f options below). See |
| 2649 | the untrusted_set_sender option for a way of permitting non-trusted users |
| 2650 | to set envelope senders. |
| 2651 | |
| 2652 | For a trusted user, there is never any check on the contents of the From: |
| 2653 | header line, and a Sender: line is never added. Furthermore, any existing |
| 2654 | Sender: line in incoming local (non-TCP/IP) messages is not removed. |
| 2655 | |
| 2656 | Trusted users may also specify a host name, host address, interface |
| 2657 | address, protocol name, ident value, and authentication data when |
| 2658 | submitting a message locally. Thus, they are able to insert messages into |
| 2659 | Exim's queue locally that have the characteristics of messages received |
| 2660 | from a remote host. Untrusted users may in some circumstances use -f, but |
| 2661 | can never set the other values that are available to trusted users. |
| 2662 | |
| 2663 | * The admin users are root, the Exim user, and any user that is a member of |
| 2664 | the Exim group or of any group listed in the admin_groups configuration |
| 2665 | option. The current group does not have to be one of these groups. |
| 2666 | |
| 2667 | Admin users are permitted to list the queue, and to carry out certain |
| 2668 | operations on messages, for example, to force delivery failures. It is also |
| 2669 | necessary to be an admin user in order to see the full information provided |
| 2670 | by the Exim monitor, and full debugging output. |
| 2671 | |
| 2672 | By default, the use of the -M, -q, -R, and -S options to cause Exim to |
| 2673 | attempt delivery of messages on its queue is restricted to admin users. |
| 2674 | However, this restriction can be relaxed by setting the prod_requires_admin |
| 2675 | option false (that is, specifying no_prod_requires_admin). |
| 2676 | |
| 2677 | Similarly, the use of the -bp option to list all the messages in the queue |
| 2678 | is restricted to admin users unless queue_list_requires_admin is set false. |
| 2679 | |
| 2680 | Warning: If you configure your system so that admin users are able to edit |
| 2681 | Exim's configuration file, you are giving those users an easy way of getting |
| 2682 | root. There is further discussion of this issue at the start of chapter 6. |
| 2683 | |
| 2684 | |
| 2685 | 5.3 Command line options |
| 2686 | ------------------------ |
| 2687 | |
| 2688 | Exim's command line options are described in alphabetical order below. If none |
| 2689 | of the options that specifies a specific action (such as starting the daemon or |
| 2690 | a queue runner, or testing an address, or receiving a message in a specific |
| 2691 | format, or listing the queue) are present, and there is at least one argument |
| 2692 | on the command line, -bm (accept a local message on the standard input, with |
| 2693 | the arguments specifying the recipients) is assumed. Otherwise, Exim outputs a |
| 2694 | brief message about itself and exits. |
| 2695 | |
| 2696 | -- |
| 2697 | |
| 2698 | This is a pseudo-option whose only purpose is to terminate the options and |
| 2699 | therefore to cause subsequent command line items to be treated as arguments |
| 2700 | rather than options, even if they begin with hyphens. |
| 2701 | |
| 2702 | --help |
| 2703 | |
| 2704 | This option causes Exim to output a few sentences stating what it is. The |
| 2705 | same output is generated if the Exim binary is called with no options and |
| 2706 | no arguments. |
| 2707 | |
| 2708 | --version |
| 2709 | |
| 2710 | This option is an alias for -bV and causes version information to be |
| 2711 | displayed. |
| 2712 | |
| 2713 | -Ac, -Am |
| 2714 | |
| 2715 | These options are used by Sendmail for selecting configuration files and |
| 2716 | are ignored by Exim. |
| 2717 | |
| 2718 | -B<type> |
| 2719 | |
| 2720 | This is a Sendmail option for selecting 7 or 8 bit processing. Exim is |
| 2721 | 8-bit clean; it ignores this option. |
| 2722 | |
| 2723 | -bd |
| 2724 | |
| 2725 | This option runs Exim as a daemon, awaiting incoming SMTP connections. |
| 2726 | Usually the -bd option is combined with the -q<time> option, to specify |
| 2727 | that the daemon should also initiate periodic queue runs. |
| 2728 | |
| 2729 | The -bd option can be used only by an admin user. If either of the -d |
| 2730 | (debugging) or -v (verifying) options are set, the daemon does not |
| 2731 | disconnect from the controlling terminal. When running this way, it can be |
| 2732 | stopped by pressing ctrl-C. |
| 2733 | |
| 2734 | By default, Exim listens for incoming connections to the standard SMTP port |
| 2735 | on all the host's running interfaces. However, it is possible to listen on |
| 2736 | other ports, on multiple ports, and only on specific interfaces. Chapter 13 |
| 2737 | contains a description of the options that control this. |
| 2738 | |
| 2739 | When a listening daemon is started without the use of -oX (that is, without |
| 2740 | overriding the normal configuration), it writes its process id to a file |
| 2741 | called exim-daemon.pid in Exim's spool directory. This location can be |
| 2742 | overridden by setting PID_FILE_PATH in Local/Makefile. The file is written |
| 2743 | while Exim is still running as root. |
| 2744 | |
| 2745 | When -oX is used on the command line to start a listening daemon, the |
| 2746 | process id is not written to the normal pid file path. However, -oP can be |
| 2747 | used to specify a path on the command line if a pid file is required. |
| 2748 | |
| 2749 | The SIGHUP signal can be used to cause the daemon to re-execute itself. |
| 2750 | This should be done whenever Exim's configuration file, or any file that is |
| 2751 | incorporated into it by means of the .include facility, is changed, and |
| 2752 | also whenever a new version of Exim is installed. It is not necessary to do |
| 2753 | this when other files that are referenced from the configuration (for |
| 2754 | example, alias files) are changed, because these are reread each time they |
| 2755 | are used. |
| 2756 | |
| 2757 | -bdf |
| 2758 | |
| 2759 | This option has the same effect as -bd except that it never disconnects |
| 2760 | from the controlling terminal, even when no debugging is specified. |
| 2761 | |
| 2762 | -be |
| 2763 | |
| 2764 | Run Exim in expansion testing mode. Exim discards its root privilege, to |
| 2765 | prevent ordinary users from using this mode to read otherwise inaccessible |
| 2766 | files. If no arguments are given, Exim runs interactively, prompting for |
| 2767 | lines of data. Otherwise, it processes each argument in turn. |
| 2768 | |
| 2769 | If Exim was built with USE_READLINE=yes in Local/Makefile, it tries to load |
| 2770 | the libreadline library dynamically whenever the -be option is used without |
| 2771 | command line arguments. If successful, it uses the readline() function, |
| 2772 | which provides extensive line-editing facilities, for reading the test |
| 2773 | data. A line history is supported. |
| 2774 | |
| 2775 | Long expansion expressions can be split over several lines by using |
| 2776 | backslash continuations. As in Exim's run time configuration, white space |
| 2777 | at the start of continuation lines is ignored. Each argument or data line |
| 2778 | is passed through the string expansion mechanism, and the result is output. |
| 2779 | Variable values from the configuration file (for example, $qualify_domain) |
| 2780 | are available, but no message-specific values (such as $message_exim_id) |
| 2781 | are set, because no message is being processed (but see -bem and -Mset). |
| 2782 | |
| 2783 | Note: If you use this mechanism to test lookups, and you change the data |
| 2784 | files or databases you are using, you must exit and restart Exim before |
| 2785 | trying the same lookup again. Otherwise, because each Exim process caches |
| 2786 | the results of lookups, you will just get the same result as before. |
| 2787 | |
| 2788 | -bem <filename> |
| 2789 | |
| 2790 | This option operates like -be except that it must be followed by the name |
| 2791 | of a file. For example: |
| 2792 | |
| 2793 | exim -bem /tmp/testmessage |
| 2794 | |
| 2795 | The file is read as a message (as if receiving a locally-submitted non-SMTP |
| 2796 | message) before any of the test expansions are done. Thus, message-specific |
| 2797 | variables such as $message_size and $header_from: are available. However, |
| 2798 | no Received: header is added to the message. If the -t option is set, |
| 2799 | recipients are read from the headers in the normal way, and are shown in |
| 2800 | the $recipients variable. Note that recipients cannot be given on the |
| 2801 | command line, because further arguments are taken as strings to expand |
| 2802 | (just like -be). |
| 2803 | |
| 2804 | -bF <filename> |
| 2805 | |
| 2806 | This option is the same as -bf except that it assumes that the filter being |
| 2807 | tested is a system filter. The additional commands that are available only |
| 2808 | in system filters are recognized. |
| 2809 | |
| 2810 | -bf <filename> |
| 2811 | |
| 2812 | This option runs Exim in user filter testing mode; the file is the filter |
| 2813 | file to be tested, and a test message must be supplied on the standard |
| 2814 | input. If there are no message-dependent tests in the filter, an empty file |
| 2815 | can be supplied. |
| 2816 | |
| 2817 | If you want to test a system filter file, use -bF instead of -bf. You can |
| 2818 | use both -bF and -bf on the same command, in order to test a system filter |
| 2819 | and a user filter in the same run. For example: |
| 2820 | |
| 2821 | exim -bF /system/filter -bf /user/filter </test/message |
| 2822 | |
| 2823 | This is helpful when the system filter adds header lines or sets filter |
| 2824 | variables that are used by the user filter. |
| 2825 | |
| 2826 | If the test filter file does not begin with one of the special lines |
| 2827 | |
| 2828 | # Exim filter |
| 2829 | # Sieve filter |
| 2830 | |
| 2831 | it is taken to be a normal .forward file, and is tested for validity under |
| 2832 | that interpretation. See sections 22.4 to 22.6 for a description of the |
| 2833 | possible contents of non-filter redirection lists. |
| 2834 | |
| 2835 | The result of an Exim command that uses -bf, provided no errors are |
| 2836 | detected, is a list of the actions that Exim would try to take if presented |
| 2837 | with the message for real. More details of filter testing are given in the |
| 2838 | separate document entitled Exim's interfaces to mail filtering. |
| 2839 | |
| 2840 | When testing a filter file, the envelope sender can be set by the -f |
| 2841 | option, or by a "From " line at the start of the test message. Various |
| 2842 | parameters that would normally be taken from the envelope recipient address |
| 2843 | of the message can be set by means of additional command line options (see |
| 2844 | the next four options). |
| 2845 | |
| 2846 | -bfd <domain> |
| 2847 | |
| 2848 | This sets the domain of the recipient address when a filter file is being |
| 2849 | tested by means of the -bf option. The default is the value of |
| 2850 | $qualify_domain. |
| 2851 | |
| 2852 | -bfl <local part> |
| 2853 | |
| 2854 | This sets the local part of the recipient address when a filter file is |
| 2855 | being tested by means of the -bf option. The default is the username of the |
| 2856 | process that calls Exim. A local part should be specified with any prefix |
| 2857 | or suffix stripped, because that is how it appears to the filter when a |
| 2858 | message is actually being delivered. |
| 2859 | |
| 2860 | -bfp <prefix> |
| 2861 | |
| 2862 | This sets the prefix of the local part of the recipient address when a |
| 2863 | filter file is being tested by means of the -bf option. The default is an |
| 2864 | empty prefix. |
| 2865 | |
| 2866 | -bfs <suffix> |
| 2867 | |
| 2868 | This sets the suffix of the local part of the recipient address when a |
| 2869 | filter file is being tested by means of the -bf option. The default is an |
| 2870 | empty suffix. |
| 2871 | |
| 2872 | -bh <IP address> |
| 2873 | |
| 2874 | This option runs a fake SMTP session as if from the given IP address, using |
| 2875 | the standard input and output. The IP address may include a port number at |
| 2876 | the end, after a full stop. For example: |
| 2877 | |
| 2878 | exim -bh 10.9.8.7.1234 |
| 2879 | exim -bh fe80::a00:20ff:fe86:a061.5678 |
| 2880 | |
| 2881 | When an IPv6 address is given, it is converted into canonical form. In the |
| 2882 | case of the second example above, the value of $sender_host_address after |
| 2883 | conversion to the canonical form is |
| 2884 | "fe80:0000:0000:0a00:20ff:fe86:a061.5678". |
| 2885 | |
| 2886 | Comments as to what is going on are written to the standard error file. |
| 2887 | These include lines beginning with "LOG" for anything that would have been |
| 2888 | logged. This facility is provided for testing configuration options for |
| 2889 | incoming messages, to make sure they implement the required policy. For |
| 2890 | example, you can test your relay controls using -bh. |
| 2891 | |
| 2892 | Warning 1: You can test features of the configuration that rely on ident |
| 2893 | (RFC 1413) information by using the -oMt option. However, Exim cannot |
| 2894 | actually perform an ident callout when testing using -bh because there is |
| 2895 | no incoming SMTP connection. |
| 2896 | |
| 2897 | Warning 2: Address verification callouts (see section 43.45) are also |
| 2898 | skipped when testing using -bh. If you want these callouts to occur, use |
| 2899 | -bhc instead. |
| 2900 | |
| 2901 | Messages supplied during the testing session are discarded, and nothing is |
| 2902 | written to any of the real log files. There may be pauses when DNS (and |
| 2903 | other) lookups are taking place, and of course these may time out. The -oMi |
| 2904 | option can be used to specify a specific IP interface and port if this is |
| 2905 | important, and -oMaa and -oMai can be used to set parameters as if the SMTP |
| 2906 | session were authenticated. |
| 2907 | |
| 2908 | The exim_checkaccess utility is a "packaged" version of -bh whose output |
| 2909 | just states whether a given recipient address from a given host is |
| 2910 | acceptable or not. See section 53.8. |
| 2911 | |
| 2912 | Features such as authentication and encryption, where the client input is |
| 2913 | not plain text, cannot easily be tested with -bh. Instead, you should use a |
| 2914 | specialized SMTP test program such as swaks. |
| 2915 | |
| 2916 | -bhc <IP address> |
| 2917 | |
| 2918 | This option operates in the same way as -bh, except that address |
| 2919 | verification callouts are performed if required. This includes consulting |
| 2920 | and updating the callout cache database. |
| 2921 | |
| 2922 | -bi |
| 2923 | |
| 2924 | Sendmail interprets the -bi option as a request to rebuild its alias file. |
| 2925 | Exim does not have the concept of a single alias file, and so it cannot |
| 2926 | mimic this behaviour. However, calls to /usr/lib/sendmail with the -bi |
| 2927 | option tend to appear in various scripts such as NIS make files, so the |
| 2928 | option must be recognized. |
| 2929 | |
| 2930 | If -bi is encountered, the command specified by the bi_command |
| 2931 | configuration option is run, under the uid and gid of the caller of Exim. |
| 2932 | If the -oA option is used, its value is passed to the command as an |
| 2933 | argument. The command set by bi_command may not contain arguments. The |
| 2934 | command can use the exim_dbmbuild utility, or some other means, to rebuild |
| 2935 | alias files if this is required. If the bi_command option is not set, |
| 2936 | calling Exim with -bi is a no-op. |
| 2937 | |
| 2938 | -bI:help |
| 2939 | |
| 2940 | We shall provide various options starting "-bI:" for querying Exim for |
| 2941 | information. The output of many of these will be intended for machine |
| 2942 | consumption. This one is not. The -bI:help option asks Exim for a synopsis |
| 2943 | of supported options beginning "-bI:". Use of any of these options shall |
| 2944 | cause Exim to exit after producing the requested output. |
| 2945 | |
| 2946 | -bI:dscp |
| 2947 | |
| 2948 | This option causes Exim to emit an alphabetically sorted list of all |
| 2949 | recognised DSCP names. |
| 2950 | |
| 2951 | -bI:sieve |
| 2952 | |
| 2953 | This option causes Exim to emit an alphabetically sorted list of all |
| 2954 | supported Sieve protocol extensions on stdout, one per line. This is |
| 2955 | anticipated to be useful for ManageSieve (RFC 5804) implementations, in |
| 2956 | providing that protocol's "SIEVE" capability response line. As the precise |
| 2957 | list may depend upon compile-time build options, which this option will |
| 2958 | adapt to, this is the only way to guarantee a correct response. |
| 2959 | |
| 2960 | -bm |
| 2961 | |
| 2962 | This option runs an Exim receiving process that accepts an incoming, |
| 2963 | locally-generated message on the standard input. The recipients are given |
| 2964 | as the command arguments (except when -t is also present - see below). Each |
| 2965 | argument can be a comma-separated list of RFC 2822 addresses. This is the |
| 2966 | default option for selecting the overall action of an Exim call; it is |
| 2967 | assumed if no other conflicting option is present. |
| 2968 | |
| 2969 | If any addresses in the message are unqualified (have no domain), they are |
| 2970 | qualified by the values of the qualify_domain or qualify_recipient options, |
| 2971 | as appropriate. The -bnq option (see below) provides a way of suppressing |
| 2972 | this for special cases. |
| 2973 | |
| 2974 | Policy checks on the contents of local messages can be enforced by means of |
| 2975 | the non-SMTP ACL. See chapter 43 for details. |
| 2976 | |
| 2977 | The return code is zero if the message is successfully accepted. Otherwise, |
| 2978 | the action is controlled by the -oex option setting - see below. |
| 2979 | |
| 2980 | The format of the message must be as defined in RFC 2822, except that, for |
| 2981 | compatibility with Sendmail and Smail, a line in one of the forms |
| 2982 | |
| 2983 | From sender Fri Jan 5 12:55 GMT 1997 |
| 2984 | From sender Fri, 5 Jan 97 12:55:01 |
| 2985 | |
| 2986 | (with the weekday optional, and possibly with additional text after the |
| 2987 | date) is permitted to appear at the start of the message. There appears to |
| 2988 | be no authoritative specification of the format of this line. Exim |
| 2989 | recognizes it by matching against the regular expression defined by the |
| 2990 | uucp_from_pattern option, which can be changed if necessary. |
| 2991 | |
| 2992 | The specified sender is treated as if it were given as the argument to the |
| 2993 | -f option, but if a -f option is also present, its argument is used in |
| 2994 | preference to the address taken from the message. The caller of Exim must |
| 2995 | be a trusted user for the sender of a message to be set in this way. |
| 2996 | |
| 2997 | -bmalware <filename> |
| 2998 | |
| 2999 | This debugging option causes Exim to scan the given file or directory |
| 3000 | (depending on the used scanner interface), using the malware scanning |
| 3001 | framework. The option of av_scanner influences this option, so if |
| 3002 | av_scanner's value is dependent upon an expansion then the expansion should |
| 3003 | have defaults which apply to this invocation. ACLs are not invoked, so if |
| 3004 | av_scanner references an ACL variable then that variable will never be |
| 3005 | populated and -bmalware will fail. |
| 3006 | |
| 3007 | Exim will have changed working directory before resolving the filename, so |
| 3008 | using fully qualified pathnames is advisable. Exim will be running as the |
| 3009 | Exim user when it tries to open the file, rather than as the invoking user. |
| 3010 | This option requires admin privileges. |
| 3011 | |
| 3012 | The -bmalware option will not be extended to be more generally useful, |
| 3013 | there are better tools for file-scanning. This option exists to help |
| 3014 | administrators verify their Exim and AV scanner configuration. |
| 3015 | |
| 3016 | -bnq |
| 3017 | |
| 3018 | By default, Exim automatically qualifies unqualified addresses (those |
| 3019 | without domains) that appear in messages that are submitted locally (that |
| 3020 | is, not over TCP/IP). This qualification applies both to addresses in |
| 3021 | envelopes, and addresses in header lines. Sender addresses are qualified |
| 3022 | using qualify_domain, and recipient addresses using qualify_recipient |
| 3023 | (which defaults to the value of qualify_domain). |
| 3024 | |
| 3025 | Sometimes, qualification is not wanted. For example, if -bS (batch SMTP) is |
| 3026 | being used to re-submit messages that originally came from remote hosts |
| 3027 | after content scanning, you probably do not want to qualify unqualified |
| 3028 | addresses in header lines. (Such lines will be present only if you have not |
| 3029 | enabled a header syntax check in the appropriate ACL.) |
| 3030 | |
| 3031 | The -bnq option suppresses all qualification of unqualified addresses in |
| 3032 | messages that originate on the local host. When this is used, unqualified |
| 3033 | addresses in the envelope provoke errors (causing message rejection) and |
| 3034 | unqualified addresses in header lines are left alone. |
| 3035 | |
| 3036 | -bP |
| 3037 | |
| 3038 | If this option is given with no arguments, it causes the values of all |
| 3039 | Exim's main configuration options to be written to the standard output. The |
| 3040 | values of one or more specific options can be requested by giving their |
| 3041 | names as arguments, for example: |
| 3042 | |
| 3043 | exim -bP qualify_domain hold_domains |
| 3044 | |
| 3045 | However, any option setting that is preceded by the word "hide" in the |
| 3046 | configuration file is not shown in full, except to an admin user. For other |
| 3047 | users, the output is as in this example: |
| 3048 | |
| 3049 | mysql_servers = <value not displayable> |
| 3050 | |
| 3051 | If config is given as an argument, the config is output, as it was parsed, |
| 3052 | any include file resolved, any comment removed. |
| 3053 | |
| 3054 | If config_file is given as an argument, the name of the run time |
| 3055 | configuration file is output. (configure_file works too, for backward |
| 3056 | compatibility.) If a list of configuration files was supplied, the value |
| 3057 | that is output here is the name of the file that was actually used. |
| 3058 | |
| 3059 | If the -n flag is given, then for most modes of -bP operation the name will |
| 3060 | not be output. |
| 3061 | |
| 3062 | If log_file_path or pid_file_path are given, the names of the directories |
| 3063 | where log files and daemon pid files are written are output, respectively. |
| 3064 | If these values are unset, log files are written in a sub-directory of the |
| 3065 | spool directory called log, and the pid file is written directly into the |
| 3066 | spool directory. |
| 3067 | |
| 3068 | If -bP is followed by a name preceded by "+", for example, |
| 3069 | |
| 3070 | exim -bP +local_domains |
| 3071 | |
| 3072 | it searches for a matching named list of any type (domain, host, address, |
| 3073 | or local part) and outputs what it finds. |
| 3074 | |
| 3075 | If one of the words router, transport, or authenticator is given, followed |
| 3076 | by the name of an appropriate driver instance, the option settings for that |
| 3077 | driver are output. For example: |
| 3078 | |
| 3079 | exim -bP transport local_delivery |
| 3080 | |
| 3081 | The generic driver options are output first, followed by the driver's |
| 3082 | private options. A list of the names of drivers of a particular type can be |
| 3083 | obtained by using one of the words router_list, transport_list, or |
| 3084 | authenticator_list, and a complete list of all drivers with their option |
| 3085 | settings can be obtained by using routers, transports, or authenticators. |
| 3086 | |
| 3087 | If environment is given as an argument, the set of environment variables is |
| 3088 | output, line by line. Using the -n flag suppresses the value of the |
| 3089 | variables. |
| 3090 | |
| 3091 | If invoked by an admin user, then macro, macro_list and macros are |
| 3092 | available, similarly to the drivers. Because macros are sometimes used for |
| 3093 | storing passwords, this option is restricted. The output format is one item |
| 3094 | per line. |
| 3095 | |
| 3096 | -bp |
| 3097 | |
| 3098 | This option requests a listing of the contents of the mail queue on the |
| 3099 | standard output. If the -bp option is followed by a list of message ids, |
| 3100 | just those messages are listed. By default, this option can be used only by |
| 3101 | an admin user. However, the queue_list_requires_admin option can be set |
| 3102 | false to allow any user to see the queue. |
| 3103 | |
| 3104 | Each message on the queue is displayed as in the following example: |
| 3105 | |
| 3106 | 25m 2.9K 0t5C6f-0000c8-00 <alice@wonderland.fict.example> |
| 3107 | red.king@looking-glass.fict.example |
| 3108 | <other addresses> |
| 3109 | |
| 3110 | The first line contains the length of time the message has been on the |
| 3111 | queue (in this case 25 minutes), the size of the message (2.9K), the unique |
| 3112 | local identifier for the message, and the message sender, as contained in |
| 3113 | the envelope. For bounce messages, the sender address is empty, and appears |
| 3114 | as "<>". If the message was submitted locally by an untrusted user who |
| 3115 | overrode the default sender address, the user's login name is shown in |
| 3116 | parentheses before the sender address. |
| 3117 | |
| 3118 | If the message is frozen (attempts to deliver it are suspended) then the |
| 3119 | text "*** frozen ***" is displayed at the end of this line. |
| 3120 | |
| 3121 | The recipients of the message (taken from the envelope, not the headers) |
| 3122 | are displayed on subsequent lines. Those addresses to which the message has |
| 3123 | already been delivered are marked with the letter D. If an original address |
| 3124 | gets expanded into several addresses via an alias or forward file, the |
| 3125 | original is displayed with a D only when deliveries for all of its child |
| 3126 | addresses are complete. |
| 3127 | |
| 3128 | -bpa |
| 3129 | |
| 3130 | This option operates like -bp, but in addition it shows delivered addresses |
| 3131 | that were generated from the original top level address(es) in each message |
| 3132 | by alias or forwarding operations. These addresses are flagged with "+D" |
| 3133 | instead of just "D". |
| 3134 | |
| 3135 | -bpc |
| 3136 | |
| 3137 | This option counts the number of messages on the queue, and writes the |
| 3138 | total to the standard output. It is restricted to admin users, unless |
| 3139 | queue_list_requires_admin is set false. |
| 3140 | |
| 3141 | -bpr |
| 3142 | |
| 3143 | This option operates like -bp, but the output is not sorted into |
| 3144 | chronological order of message arrival. This can speed it up when there are |
| 3145 | lots of messages on the queue, and is particularly useful if the output is |
| 3146 | going to be post-processed in a way that doesn't need the sorting. |
| 3147 | |
| 3148 | -bpra |
| 3149 | |
| 3150 | This option is a combination of -bpr and -bpa. |
| 3151 | |
| 3152 | -bpru |
| 3153 | |
| 3154 | This option is a combination of -bpr and -bpu. |
| 3155 | |
| 3156 | -bpu |
| 3157 | |
| 3158 | This option operates like -bp but shows only undelivered top-level |
| 3159 | addresses for each message displayed. Addresses generated by aliasing or |
| 3160 | forwarding are not shown, unless the message was deferred after processing |
| 3161 | by a router with the one_time option set. |
| 3162 | |
| 3163 | -brt |
| 3164 | |
| 3165 | This option is for testing retry rules, and it must be followed by up to |
| 3166 | three arguments. It causes Exim to look for a retry rule that matches the |
| 3167 | values and to write it to the standard output. For example: |
| 3168 | |
| 3169 | exim -brt bach.comp.mus.example |
| 3170 | Retry rule: *.comp.mus.example F,2h,15m; F,4d,30m; |
| 3171 | |
| 3172 | See chapter 32 for a description of Exim's retry rules. The first argument, |
| 3173 | which is required, can be a complete address in the form local_part@domain, |
| 3174 | or it can be just a domain name. If the second argument contains a dot, it |
| 3175 | is interpreted as an optional second domain name; if no retry rule is found |
| 3176 | for the first argument, the second is tried. This ties in with Exim's |
| 3177 | behaviour when looking for retry rules for remote hosts - if no rule is |
| 3178 | found that matches the host, one that matches the mail domain is sought. |
| 3179 | Finally, an argument that is the name of a specific delivery error, as used |
| 3180 | in setting up retry rules, can be given. For example: |
| 3181 | |
| 3182 | exim -brt haydn.comp.mus.example quota_3d |
| 3183 | Retry rule: *@haydn.comp.mus.example quota_3d F,1h,15m |
| 3184 | |
| 3185 | -brw |
| 3186 | |
| 3187 | This option is for testing address rewriting rules, and it must be followed |
| 3188 | by a single argument, consisting of either a local part without a domain, |
| 3189 | or a complete address with a fully qualified domain. Exim outputs how this |
| 3190 | address would be rewritten for each possible place it might appear. See |
| 3191 | chapter 31 for further details. |
| 3192 | |
| 3193 | -bS |
| 3194 | |
| 3195 | This option is used for batched SMTP input, which is an alternative |
| 3196 | interface for non-interactive local message submission. A number of |
| 3197 | messages can be submitted in a single run. However, despite its name, this |
| 3198 | is not really SMTP input. Exim reads each message's envelope from SMTP |
| 3199 | commands on the standard input, but generates no responses. If the caller |
| 3200 | is trusted, or untrusted_set_sender is set, the senders in the SMTP MAIL |
| 3201 | commands are believed; otherwise the sender is always the caller of Exim. |
| 3202 | |
| 3203 | The message itself is read from the standard input, in SMTP format (leading |
| 3204 | dots doubled), terminated by a line containing just a single dot. An error |
| 3205 | is provoked if the terminating dot is missing. A further message may then |
| 3206 | follow. |
| 3207 | |
| 3208 | As for other local message submissions, the contents of incoming batch SMTP |
| 3209 | messages can be checked using the non-SMTP ACL (see chapter 43). |
| 3210 | Unqualified addresses are automatically qualified using qualify_domain and |
| 3211 | qualify_recipient, as appropriate, unless the -bnq option is used. |
| 3212 | |
| 3213 | Some other SMTP commands are recognized in the input. HELO and EHLO act as |
| 3214 | RSET; VRFY, EXPN, ETRN, and HELP act as NOOP; QUIT quits, ignoring the rest |
| 3215 | of the standard input. |
| 3216 | |
| 3217 | If any error is encountered, reports are written to the standard output and |
| 3218 | error streams, and Exim gives up immediately. The return code is 0 if no |
| 3219 | error was detected; it is 1 if one or more messages were accepted before |
| 3220 | the error was detected; otherwise it is 2. |
| 3221 | |
| 3222 | More details of input using batched SMTP are given in section 48.11. |
| 3223 | |
| 3224 | -bs |
| 3225 | |
| 3226 | This option causes Exim to accept one or more messages by reading SMTP |
| 3227 | commands on the standard input, and producing SMTP replies on the standard |
| 3228 | output. SMTP policy controls, as defined in ACLs (see chapter 43) are |
| 3229 | applied. Some user agents use this interface as a way of passing |
| 3230 | locally-generated messages to the MTA. |
| 3231 | |
| 3232 | In this usage, if the caller of Exim is trusted, or untrusted_set_sender is |
| 3233 | set, the senders of messages are taken from the SMTP MAIL commands. |
| 3234 | Otherwise the content of these commands is ignored and the sender is set up |
| 3235 | as the calling user. Unqualified addresses are automatically qualified |
| 3236 | using qualify_domain and qualify_recipient, as appropriate, unless the -bnq |
| 3237 | option is used. |
| 3238 | |
| 3239 | The -bs option is also used to run Exim from inetd, as an alternative to |
| 3240 | using a listening daemon. Exim can distinguish the two cases by checking |
| 3241 | whether the standard input is a TCP/IP socket. When Exim is called from |
| 3242 | inetd, the source of the mail is assumed to be remote, and the comments |
| 3243 | above concerning senders and qualification do not apply. In this situation, |
| 3244 | Exim behaves in exactly the same way as it does when receiving a message |
| 3245 | via the listening daemon. |
| 3246 | |
| 3247 | -bt |
| 3248 | |
| 3249 | This option runs Exim in address testing mode, in which each argument is |
| 3250 | taken as a recipient address to be tested for deliverability. The results |
| 3251 | are written to the standard output. If a test fails, and the caller is not |
| 3252 | an admin user, no details of the failure are output, because these might |
| 3253 | contain sensitive information such as usernames and passwords for database |
| 3254 | lookups. |
| 3255 | |
| 3256 | If no arguments are given, Exim runs in an interactive manner, prompting |
| 3257 | with a right angle bracket for addresses to be tested. |
| 3258 | |
| 3259 | Unlike the -be test option, you cannot arrange for Exim to use the readline |
| 3260 | () function, because it is running as root and there are security issues. |
| 3261 | |
| 3262 | Each address is handled as if it were the recipient address of a message |
| 3263 | (compare the -bv option). It is passed to the routers and the result is |
| 3264 | written to the standard output. However, any router that has |
| 3265 | no_address_test set is bypassed. This can make -bt easier to use for |
| 3266 | genuine routing tests if your first router passes everything to a scanner |
| 3267 | program. |
| 3268 | |
| 3269 | The return code is 2 if any address failed outright; it is 1 if no address |
| 3270 | failed outright but at least one could not be resolved for some reason. |
| 3271 | Return code 0 is given only when all addresses succeed. |
| 3272 | |
| 3273 | Note: When actually delivering a message, Exim removes duplicate recipient |
| 3274 | addresses after routing is complete, so that only one delivery takes place. |
| 3275 | This does not happen when testing with -bt; the full results of routing are |
| 3276 | always shown. |
| 3277 | |
| 3278 | Warning: -bt can only do relatively simple testing. If any of the routers |
| 3279 | in the configuration makes any tests on the sender address of a message, |
| 3280 | you can use the -f option to set an appropriate sender when running -bt |
| 3281 | tests. Without it, the sender is assumed to be the calling user at the |
| 3282 | default qualifying domain. However, if you have set up (for example) |
| 3283 | routers whose behaviour depends on the contents of an incoming message, you |
| 3284 | cannot test those conditions using -bt. The -N option provides a possible |
| 3285 | way of doing such tests. |
| 3286 | |
| 3287 | -bV |
| 3288 | |
| 3289 | This option causes Exim to write the current version number, compilation |
| 3290 | number, and compilation date of the exim binary to the standard output. It |
| 3291 | also lists the DBM library that is being used, the optional modules (such |
| 3292 | as specific lookup types), the drivers that are included in the binary, and |
| 3293 | the name of the run time configuration file that is in use. |
| 3294 | |
| 3295 | As part of its operation, -bV causes Exim to read and syntax check its |
| 3296 | configuration file. However, this is a static check only. It cannot check |
| 3297 | values that are to be expanded. For example, although a misspelt ACL verb |
| 3298 | is detected, an error in the verb's arguments is not. You cannot rely on |
| 3299 | -bV alone to discover (for example) all the typos in the configuration; |
| 3300 | some realistic testing is needed. The -bh and -N options provide more |
| 3301 | dynamic testing facilities. |
| 3302 | |
| 3303 | -bv |
| 3304 | |
| 3305 | This option runs Exim in address verification mode, in which each argument |
| 3306 | is taken as a recipient address to be verified by the routers. (This does |
| 3307 | not involve any verification callouts). During normal operation, |
| 3308 | verification happens mostly as a consequence processing a verify condition |
| 3309 | in an ACL (see chapter 43). If you want to test an entire ACL, possibly |
| 3310 | including callouts, see the -bh and -bhc options. |
| 3311 | |
| 3312 | If verification fails, and the caller is not an admin user, no details of |
| 3313 | the failure are output, because these might contain sensitive information |
| 3314 | such as usernames and passwords for database lookups. |
| 3315 | |
| 3316 | If no arguments are given, Exim runs in an interactive manner, prompting |
| 3317 | with a right angle bracket for addresses to be verified. |
| 3318 | |
| 3319 | Unlike the -be test option, you cannot arrange for Exim to use the readline |
| 3320 | () function, because it is running as exim and there are security issues. |
| 3321 | |
| 3322 | Verification differs from address testing (the -bt option) in that routers |
| 3323 | that have no_verify set are skipped, and if the address is accepted by a |
| 3324 | router that has fail_verify set, verification fails. The address is |
| 3325 | verified as a recipient if -bv is used; to test verification for a sender |
| 3326 | address, -bvs should be used. |
| 3327 | |
| 3328 | If the -v option is not set, the output consists of a single line for each |
| 3329 | address, stating whether it was verified or not, and giving a reason in the |
| 3330 | latter case. Without -v, generating more than one address by redirection |
| 3331 | causes verification to end successfully, without considering the generated |
| 3332 | addresses. However, if just one address is generated, processing continues, |
| 3333 | and the generated address must verify successfully for the overall |
| 3334 | verification to succeed. |
| 3335 | |
| 3336 | When -v is set, more details are given of how the address has been handled, |
| 3337 | and in the case of address redirection, all the generated addresses are |
| 3338 | also considered. Verification may succeed for some and fail for others. |
| 3339 | |
| 3340 | The return code is 2 if any address failed outright; it is 1 if no address |
| 3341 | failed outright but at least one could not be resolved for some reason. |
| 3342 | Return code 0 is given only when all addresses succeed. |
| 3343 | |
| 3344 | If any of the routers in the configuration makes any tests on the sender |
| 3345 | address of a message, you should use the -f option to set an appropriate |
| 3346 | sender when running -bv tests. Without it, the sender is assumed to be the |
| 3347 | calling user at the default qualifying domain. |
| 3348 | |
| 3349 | -bvs |
| 3350 | |
| 3351 | This option acts like -bv, but verifies the address as a sender rather than |
| 3352 | a recipient address. This affects any rewriting and qualification that |
| 3353 | might happen. |
| 3354 | |
| 3355 | -bw |
| 3356 | |
| 3357 | This option runs Exim as a daemon, awaiting incoming SMTP connections, |
| 3358 | similarly to the -bd option. All port specifications on the command-line |
| 3359 | and in the configuration file are ignored. Queue-running may not be |
| 3360 | specified. |
| 3361 | |
| 3362 | In this mode, Exim expects to be passed a socket as fd 0 (stdin) which is |
| 3363 | listening for connections. This permits the system to start up and have |
| 3364 | inetd (or equivalent) listen on the SMTP ports, starting an Exim daemon for |
| 3365 | each port only when the first connection is received. |
| 3366 | |
| 3367 | If the option is given as -bw<time> then the time is a timeout, after which |
| 3368 | the daemon will exit, which should cause inetd to listen once more. |
| 3369 | |
| 3370 | -C <filelist> |
| 3371 | |
| 3372 | This option causes Exim to find the run time configuration file from the |
| 3373 | given list instead of from the list specified by the CONFIGURE_FILE |
| 3374 | compile-time setting. Usually, the list will consist of just a single file |
| 3375 | name, but it can be a colon-separated list of names. In this case, the |
| 3376 | first file that exists is used. Failure to open an existing file stops Exim |
| 3377 | from proceeding any further along the list, and an error is generated. |
| 3378 | |
| 3379 | When this option is used by a caller other than root, and the list is |
| 3380 | different from the compiled-in list, Exim gives up its root privilege |
| 3381 | immediately, and runs with the real and effective uid and gid set to those |
| 3382 | of the caller. However, if a TRUSTED_CONFIG_LIST file is defined in Local/ |
| 3383 | Makefile, that file contains a list of full pathnames, one per line, for |
| 3384 | configuration files which are trusted. Root privilege is retained for any |
| 3385 | configuration file so listed, as long as the caller is the Exim user (or |
| 3386 | the user specified in the CONFIGURE_OWNER option, if any), and as long as |
| 3387 | the configuration file is not writeable by inappropriate users or groups. |
| 3388 | |
| 3389 | Leaving TRUSTED_CONFIG_LIST unset precludes the possibility of testing a |
| 3390 | configuration using -C right through message reception and delivery, even |
| 3391 | if the caller is root. The reception works, but by that time, Exim is |
| 3392 | running as the Exim user, so when it re-executes to regain privilege for |
| 3393 | the delivery, the use of -C causes privilege to be lost. However, root can |
| 3394 | test reception and delivery using two separate commands (one to put a |
| 3395 | message on the queue, using -odq, and another to do the delivery, using -M |
| 3396 | ). |
| 3397 | |
| 3398 | If ALT_CONFIG_PREFIX is defined in Local/Makefile, it specifies a prefix |
| 3399 | string with which any file named in a -C command line option must start. In |
| 3400 | addition, the file name must not contain the sequence "/../". However, if |
| 3401 | the value of the -C option is identical to the value of CONFIGURE_FILE in |
| 3402 | Local/Makefile, Exim ignores -C and proceeds as usual. There is no default |
| 3403 | setting for ALT_CONFIG_PREFIX; when it is unset, any file name can be used |
| 3404 | with -C. |
| 3405 | |
| 3406 | ALT_CONFIG_PREFIX can be used to confine alternative configuration files to |
| 3407 | a directory to which only root has access. This prevents someone who has |
| 3408 | broken into the Exim account from running a privileged Exim with an |
| 3409 | arbitrary configuration file. |
| 3410 | |
| 3411 | The -C facility is useful for ensuring that configuration files are |
| 3412 | syntactically correct, but cannot be used for test deliveries, unless the |
| 3413 | caller is privileged, or unless it is an exotic configuration that does not |
| 3414 | require privilege. No check is made on the owner or group of the files |
| 3415 | specified by this option. |
| 3416 | |
| 3417 | -D<macro>=<value> |
| 3418 | |
| 3419 | This option can be used to override macro definitions in the configuration |
| 3420 | file (see section 6.4). However, like -C, if it is used by an unprivileged |
| 3421 | caller, it causes Exim to give up its root privilege. If DISABLE_D_OPTION |
| 3422 | is defined in Local/Makefile, the use of -D is completely disabled, and its |
| 3423 | use causes an immediate error exit. |
| 3424 | |
| 3425 | If WHITELIST_D_MACROS is defined in Local/Makefile then it should be a |
| 3426 | colon-separated list of macros which are considered safe and, if -D only |
| 3427 | supplies macros from this list, and the values are acceptable, then Exim |
| 3428 | will not give up root privilege if the caller is root, the Exim run-time |
| 3429 | user, or the CONFIGURE_OWNER, if set. This is a transition mechanism and is |
| 3430 | expected to be removed in the future. Acceptable values for the macros |
| 3431 | satisfy the regexp: "^[A-Za-z0-9_/.-]*$" |
| 3432 | |
| 3433 | The entire option (including equals sign if present) must all be within one |
| 3434 | command line item. -D can be used to set the value of a macro to the empty |
| 3435 | string, in which case the equals sign is optional. These two commands are |
| 3436 | synonymous: |
| 3437 | |
| 3438 | exim -DABC ... |
| 3439 | exim -DABC= ... |
| 3440 | |
| 3441 | To include spaces in a macro definition item, quotes must be used. If you |
| 3442 | use quotes, spaces are permitted around the macro name and the equals sign. |
| 3443 | For example: |
| 3444 | |
| 3445 | exim '-D ABC = something' ... |
| 3446 | |
| 3447 | -D may be repeated up to 10 times on a command line. Only macro names up to |
| 3448 | 22 letters long can be set. |
| 3449 | |
| 3450 | -d<debug options> |
| 3451 | |
| 3452 | This option causes debugging information to be written to the standard |
| 3453 | error stream. It is restricted to admin users because debugging output may |
| 3454 | show database queries that contain password information. Also, the details |
| 3455 | of users' filter files should be protected. If a non-admin user uses -d, |
| 3456 | Exim writes an error message to the standard error stream and exits with a |
| 3457 | non-zero return code. |
| 3458 | |
| 3459 | When -d is used, -v is assumed. If -d is given on its own, a lot of |
| 3460 | standard debugging data is output. This can be reduced, or increased to |
| 3461 | include some more rarely needed information, by directly following -d with |
| 3462 | a string made up of names preceded by plus or minus characters. These add |
| 3463 | or remove sets of debugging data, respectively. For example, -d+filter adds |
| 3464 | filter debugging, whereas -d-all+filter selects only filter debugging. Note |
| 3465 | that no spaces are allowed in the debug setting. The available debugging |
| 3466 | categories are: |
| 3467 | |
| 3468 | acl ACL interpretation |
| 3469 | auth authenticators |
| 3470 | deliver general delivery logic |
| 3471 | dns DNS lookups (see also resolver) |
| 3472 | dnsbl DNS black list (aka RBL) code |
| 3473 | exec arguments for execv() calls |
| 3474 | expand detailed debugging for string expansions |
| 3475 | filter filter handling |
| 3476 | hints_lookup hints data lookups |
| 3477 | host_lookup all types of name-to-IP address handling |
| 3478 | ident ident lookup |
| 3479 | interface lists of local interfaces |
| 3480 | lists matching things in lists |
| 3481 | load system load checks |
| 3482 | local_scan can be used by local_scan() (see chapter 45) |
| 3483 | lookup general lookup code and all lookups |
| 3484 | memory memory handling |
| 3485 | pid add pid to debug output lines |
| 3486 | process_info setting info for the process log |
| 3487 | queue_run queue runs |
| 3488 | receive general message reception logic |
| 3489 | resolver turn on the DNS resolver's debugging output |
| 3490 | retry retry handling |
| 3491 | rewrite address rewriting |
| 3492 | route address routing |
| 3493 | timestamp add timestamp to debug output lines |
| 3494 | tls TLS logic |
| 3495 | transport transports |
| 3496 | uid changes of uid/gid and looking up uid/gid |
| 3497 | verify address verification logic |
| 3498 | all almost all of the above (see below), and also -v |
| 3499 | |
| 3500 | The "all" option excludes "memory" when used as "+all", but includes it for |
| 3501 | "-all". The reason for this is that "+all" is something that people tend to |
| 3502 | use when generating debug output for Exim maintainers. If "+memory" is |
| 3503 | included, an awful lot of output that is very rarely of interest is |
| 3504 | generated, so it now has to be explicitly requested. However, "-all" does |
| 3505 | turn everything off. |
| 3506 | |
| 3507 | The "resolver" option produces output only if the DNS resolver was compiled |
| 3508 | with DEBUG enabled. This is not the case in some operating systems. Also, |
| 3509 | unfortunately, debugging output from the DNS resolver is written to stdout |
| 3510 | rather than stderr. |
| 3511 | |
| 3512 | The default (-d with no argument) omits "expand", "filter", "interface", |
| 3513 | "load", "memory", "pid", "resolver", and "timestamp". However, the "pid" |
| 3514 | selector is forced when debugging is turned on for a daemon, which then |
| 3515 | passes it on to any re-executed Exims. Exim also automatically adds the pid |
| 3516 | to debug lines when several remote deliveries are run in parallel. |
| 3517 | |
| 3518 | The "timestamp" selector causes the current time to be inserted at the |
| 3519 | start of all debug output lines. This can be useful when trying to track |
| 3520 | down delays in processing. |
| 3521 | |
| 3522 | If the debug_print option is set in any driver, it produces output whenever |
| 3523 | any debugging is selected, or if -v is used. |
| 3524 | |
| 3525 | -dd<debug options> |
| 3526 | |
| 3527 | This option behaves exactly like -d except when used on a command that |
| 3528 | starts a daemon process. In that case, debugging is turned off for the |
| 3529 | subprocesses that the daemon creates. Thus, it is useful for monitoring the |
| 3530 | behaviour of the daemon without creating as much output as full debugging |
| 3531 | does. |
| 3532 | |
| 3533 | -dropcr |
| 3534 | |
| 3535 | This is an obsolete option that is now a no-op. It used to affect the way |
| 3536 | Exim handled CR and LF characters in incoming messages. What happens now is |
| 3537 | described in section 47.2. |
| 3538 | |
| 3539 | -E |
| 3540 | |
| 3541 | This option specifies that an incoming message is a locally-generated |
| 3542 | delivery failure report. It is used internally by Exim when handling |
| 3543 | delivery failures and is not intended for external use. Its only effect is |
| 3544 | to stop Exim generating certain messages to the postmaster, as otherwise |
| 3545 | message cascades could occur in some situations. As part of the same |
| 3546 | option, a message id may follow the characters -E. If it does, the log |
| 3547 | entry for the receipt of the new message contains the id, following "R=", |
| 3548 | as a cross-reference. |
| 3549 | |
| 3550 | -ex |
| 3551 | |
| 3552 | There are a number of Sendmail options starting with -oe which seem to be |
| 3553 | called by various programs without the leading o in the option. For |
| 3554 | example, the vacation program uses -eq. Exim treats all options of the form |
| 3555 | -ex as synonymous with the corresponding -oex options. |
| 3556 | |
| 3557 | -F <string> |
| 3558 | |
| 3559 | This option sets the sender's full name for use when a locally-generated |
| 3560 | message is being accepted. In the absence of this option, the user's gecos |
| 3561 | entry from the password data is used. As users are generally permitted to |
| 3562 | alter their gecos entries, no security considerations are involved. White |
| 3563 | space between -F and the <string> is optional. |
| 3564 | |
| 3565 | -f <address> |
| 3566 | |
| 3567 | This option sets the address of the envelope sender of a locally-generated |
| 3568 | message (also known as the return path). The option can normally be used |
| 3569 | only by a trusted user, but untrusted_set_sender can be set to allow |
| 3570 | untrusted users to use it. |
| 3571 | |
| 3572 | Processes running as root or the Exim user are always trusted. Other |
| 3573 | trusted users are defined by the trusted_users or trusted_groups options. |
| 3574 | In the absence of -f, or if the caller is not trusted, the sender of a |
| 3575 | local message is set to the caller's login name at the default qualify |
| 3576 | domain. |
| 3577 | |
| 3578 | There is one exception to the restriction on the use of -f: an empty sender |
| 3579 | can be specified by any user, trusted or not, to create a message that can |
| 3580 | never provoke a bounce. An empty sender can be specified either as an empty |
| 3581 | string, or as a pair of angle brackets with nothing between them, as in |
| 3582 | these examples of shell commands: |
| 3583 | |
| 3584 | exim -f '<>' user@domain |
| 3585 | exim -f "" user@domain |
| 3586 | |
| 3587 | In addition, the use of -f is not restricted when testing a filter file |
| 3588 | with -bf or when testing or verifying addresses using the -bt or -bv |
| 3589 | options. |
| 3590 | |
| 3591 | Allowing untrusted users to change the sender address does not of itself |
| 3592 | make it possible to send anonymous mail. Exim still checks that the From: |
| 3593 | header refers to the local user, and if it does not, it adds a Sender: |
| 3594 | header, though this can be overridden by setting no_local_from_check. |
| 3595 | |
| 3596 | White space between -f and the <address> is optional (that is, they can be |
| 3597 | given as two arguments or one combined argument). The sender of a |
| 3598 | locally-generated message can also be set (when permitted) by an initial |
| 3599 | "From " line in the message - see the description of -bm above - but if -f |
| 3600 | is also present, it overrides "From ". |
| 3601 | |
| 3602 | -G |
| 3603 | |
| 3604 | This option is equivalent to an ACL applying: |
| 3605 | |
| 3606 | control = suppress_local_fixups |
| 3607 | |
| 3608 | for every message received. Note that Sendmail will complain about such bad |
| 3609 | formatting, where Exim silently just does not fix it up. This may change in |
| 3610 | future. |
| 3611 | |
| 3612 | As this affects audit information, the caller must be a trusted user to use |
| 3613 | this option. |
| 3614 | |
| 3615 | -h <number> |
| 3616 | |
| 3617 | This option is accepted for compatibility with Sendmail, but has no effect. |
| 3618 | (In Sendmail it overrides the "hop count" obtained by counting Received: |
| 3619 | headers.) |
| 3620 | |
| 3621 | -i |
| 3622 | |
| 3623 | This option, which has the same effect as -oi, specifies that a dot on a |
| 3624 | line by itself should not terminate an incoming, non-SMTP message. I can |
| 3625 | find no documentation for this option in Solaris 2.4 Sendmail, but the |
| 3626 | mailx command in Solaris 2.4 uses it. See also -ti. |
| 3627 | |
| 3628 | -L <tag> |
| 3629 | |
| 3630 | This option is equivalent to setting syslog_processname in the config file |
| 3631 | and setting log_file_path to "syslog". Its use is restricted to |
| 3632 | administrators. The configuration file has to be read and parsed, to |
| 3633 | determine access rights, before this is set and takes effect, so early |
| 3634 | configuration file errors will not honour this flag. |
| 3635 | |
| 3636 | The tag should not be longer than 32 characters. |
| 3637 | |
| 3638 | -M <message id> <message id> ... |
| 3639 | |
| 3640 | This option requests Exim to run a delivery attempt on each message in |
| 3641 | turn. If any of the messages are frozen, they are automatically thawed |
| 3642 | before the delivery attempt. The settings of queue_domains, |
| 3643 | queue_smtp_domains, and hold_domains are ignored. |
| 3644 | |
| 3645 | Retry hints for any of the addresses are overridden - Exim tries to deliver |
| 3646 | even if the normal retry time has not yet been reached. This option |
| 3647 | requires the caller to be an admin user. However, there is an option called |
| 3648 | prod_requires_admin which can be set false to relax this restriction (and |
| 3649 | also the same requirement for the -q, -R, and -S options). |
| 3650 | |
| 3651 | The deliveries happen synchronously, that is, the original Exim process |
| 3652 | does not terminate until all the delivery attempts have finished. No output |
| 3653 | is produced unless there is a serious error. If you want to see what is |
| 3654 | happening, use the -v option as well, or inspect Exim's main log. |
| 3655 | |
| 3656 | -Mar <message id> <address> <address> ... |
| 3657 | |
| 3658 | This option requests Exim to add the addresses to the list of recipients of |
| 3659 | the message ("ar" for "add recipients"). The first argument must be a |
| 3660 | message id, and the remaining ones must be email addresses. However, if the |
| 3661 | message is active (in the middle of a delivery attempt), it is not altered. |
| 3662 | This option can be used only by an admin user. |
| 3663 | |
| 3664 | -MC <transport> <hostname> <sequence number> <message id> |
| 3665 | |
| 3666 | This option is not intended for use by external callers. It is used |
| 3667 | internally by Exim to invoke another instance of itself to deliver a |
| 3668 | waiting message using an existing SMTP connection, which is passed as the |
| 3669 | standard input. Details are given in chapter 48. This must be the final |
| 3670 | option, and the caller must be root or the Exim user in order to use it. |
| 3671 | |
| 3672 | -MCA |
| 3673 | |
| 3674 | This option is not intended for use by external callers. It is used |
| 3675 | internally by Exim in conjunction with the -MC option. It signifies that |
| 3676 | the connection to the remote host has been authenticated. |
| 3677 | |
| 3678 | -MCD |
| 3679 | |
| 3680 | This option is not intended for use by external callers. It is used |
| 3681 | internally by Exim in conjunction with the -MC option. It signifies that |
| 3682 | the remote host supports the ESMTP DSN extension. |
| 3683 | |
| 3684 | -MCG |
| 3685 | |
| 3686 | This option is not intended for use by external callers. It is used |
| 3687 | internally by Exim in conjunction with the -MC option. It signifies that an |
| 3688 | alternate queue is used, named by the following option. |
| 3689 | |
| 3690 | -MCP |
| 3691 | |
| 3692 | This option is not intended for use by external callers. It is used |
| 3693 | internally by Exim in conjunction with the -MC option. It signifies that |
| 3694 | the server to which Exim is connected supports pipelining. |
| 3695 | |
| 3696 | -MCQ <process id> <pipe fd> |
| 3697 | |
| 3698 | This option is not intended for use by external callers. It is used |
| 3699 | internally by Exim in conjunction with the -MC option when the original |
| 3700 | delivery was started by a queue runner. It passes on the process id of the |
| 3701 | queue runner, together with the file descriptor number of an open pipe. |
| 3702 | Closure of the pipe signals the final completion of the sequence of |
| 3703 | processes that are passing messages through the same SMTP connection. |
| 3704 | |
| 3705 | -MCS |
| 3706 | |
| 3707 | This option is not intended for use by external callers. It is used |
| 3708 | internally by Exim in conjunction with the -MC option, and passes on the |
| 3709 | fact that the SMTP SIZE option should be used on messages delivered down |
| 3710 | the existing connection. |
| 3711 | |
| 3712 | -MCT |
| 3713 | |
| 3714 | This option is not intended for use by external callers. It is used |
| 3715 | internally by Exim in conjunction with the -MC option, and passes on the |
| 3716 | fact that the host to which Exim is connected supports TLS encryption. |
| 3717 | |
| 3718 | -Mc <message id> <message id> ... |
| 3719 | |
| 3720 | This option requests Exim to run a delivery attempt on each message in |
| 3721 | turn, but unlike the -M option, it does check for retry hints, and respects |
| 3722 | any that are found. This option is not very useful to external callers. It |
| 3723 | is provided mainly for internal use by Exim when it needs to re-invoke |
| 3724 | itself in order to regain root privilege for a delivery (see chapter 55). |
| 3725 | However, -Mc can be useful when testing, in order to run a delivery that |
| 3726 | respects retry times and other options such as hold_domains that are |
| 3727 | overridden when -M is used. Such a delivery does not count as a queue run. |
| 3728 | If you want to run a specific delivery as if in a queue run, you should use |
| 3729 | -q with a message id argument. A distinction between queue run deliveries |
| 3730 | and other deliveries is made in one or two places. |
| 3731 | |
| 3732 | -Mes <message id> <address> |
| 3733 | |
| 3734 | This option requests Exim to change the sender address in the message to |
| 3735 | the given address, which must be a fully qualified address or "<>" ("es" |
| 3736 | for "edit sender"). There must be exactly two arguments. The first argument |
| 3737 | must be a message id, and the second one an email address. However, if the |
| 3738 | message is active (in the middle of a delivery attempt), its status is not |
| 3739 | altered. This option can be used only by an admin user. |
| 3740 | |
| 3741 | -Mf <message id> <message id> ... |
| 3742 | |
| 3743 | This option requests Exim to mark each listed message as "frozen". This |
| 3744 | prevents any delivery attempts taking place until the message is "thawed", |
| 3745 | either manually or as a result of the auto_thaw configuration option. |
| 3746 | However, if any of the messages are active (in the middle of a delivery |
| 3747 | attempt), their status is not altered. This option can be used only by an |
| 3748 | admin user. |
| 3749 | |
| 3750 | -Mg <message id> <message id> ... |
| 3751 | |
| 3752 | This option requests Exim to give up trying to deliver the listed messages, |
| 3753 | including any that are frozen. However, if any of the messages are active, |
| 3754 | their status is not altered. For non-bounce messages, a delivery error |
| 3755 | message is sent to the sender, containing the text "cancelled by |
| 3756 | administrator". Bounce messages are just discarded. This option can be used |
| 3757 | only by an admin user. |
| 3758 | |
| 3759 | -Mmad <message id> <message id> ... |
| 3760 | |
| 3761 | This option requests Exim to mark all the recipient addresses in the |
| 3762 | messages as already delivered ("mad" for "mark all delivered"). However, if |
| 3763 | any message is active (in the middle of a delivery attempt), its status is |
| 3764 | not altered. This option can be used only by an admin user. |
| 3765 | |
| 3766 | -Mmd <message id> <address> <address> ... |
| 3767 | |
| 3768 | This option requests Exim to mark the given addresses as already delivered |
| 3769 | ("md" for "mark delivered"). The first argument must be a message id, and |
| 3770 | the remaining ones must be email addresses. These are matched to recipient |
| 3771 | addresses in the message in a case-sensitive manner. If the message is |
| 3772 | active (in the middle of a delivery attempt), its status is not altered. |
| 3773 | This option can be used only by an admin user. |
| 3774 | |
| 3775 | -Mrm <message id> <message id> ... |
| 3776 | |
| 3777 | This option requests Exim to remove the given messages from the queue. No |
| 3778 | bounce messages are sent; each message is simply forgotten. However, if any |
| 3779 | of the messages are active, their status is not altered. This option can be |
| 3780 | used only by an admin user or by the user who originally caused the message |
| 3781 | to be placed on the queue. |
| 3782 | |
| 3783 | -Mset <message id> |
| 3784 | |
| 3785 | This option is useful only in conjunction with -be (that is, when testing |
| 3786 | string expansions). Exim loads the given message from its spool before |
| 3787 | doing the test expansions, thus setting message-specific variables such as |
| 3788 | $message_size and the header variables. The $recipients variable is made |
| 3789 | available. This feature is provided to make it easier to test expansions |
| 3790 | that make use of these variables. However, this option can be used only by |
| 3791 | an admin user. See also -bem. |
| 3792 | |
| 3793 | -Mt <message id> <message id> ... |
| 3794 | |
| 3795 | This option requests Exim to "thaw" any of the listed messages that are |
| 3796 | "frozen", so that delivery attempts can resume. However, if any of the |
| 3797 | messages are active, their status is not altered. This option can be used |
| 3798 | only by an admin user. |
| 3799 | |
| 3800 | -Mvb <message id> |
| 3801 | |
| 3802 | This option causes the contents of the message body (-D) spool file to be |
| 3803 | written to the standard output. This option can be used only by an admin |
| 3804 | user. |
| 3805 | |
| 3806 | -Mvc <message id> |
| 3807 | |
| 3808 | This option causes a copy of the complete message (header lines plus body) |
| 3809 | to be written to the standard output in RFC 2822 format. This option can be |
| 3810 | used only by an admin user. |
| 3811 | |
| 3812 | -Mvh <message id> |
| 3813 | |
| 3814 | This option causes the contents of the message headers (-H) spool file to |
| 3815 | be written to the standard output. This option can be used only by an admin |
| 3816 | user. |
| 3817 | |
| 3818 | -Mvl <message id> |
| 3819 | |
| 3820 | This option causes the contents of the message log spool file to be written |
| 3821 | to the standard output. This option can be used only by an admin user. |
| 3822 | |
| 3823 | -m |
| 3824 | |
| 3825 | This is apparently a synonym for -om that is accepted by Sendmail, so Exim |
| 3826 | treats it that way too. |
| 3827 | |
| 3828 | -N |
| 3829 | |
| 3830 | This is a debugging option that inhibits delivery of a message at the |
| 3831 | transport level. It implies -v. Exim goes through many of the motions of |
| 3832 | delivery - it just doesn't actually transport the message, but instead |
| 3833 | behaves as if it had successfully done so. However, it does not make any |
| 3834 | updates to the retry database, and the log entries for deliveries are |
| 3835 | flagged with "*>" rather than "=>". |
| 3836 | |
| 3837 | Because -N discards any message to which it applies, only root or the Exim |
| 3838 | user are allowed to use it with -bd, -q, -R or -M. In other words, an |
| 3839 | ordinary user can use it only when supplying an incoming message to which |
| 3840 | it will apply. Although transportation never fails when -N is set, an |
| 3841 | address may be deferred because of a configuration problem on a transport, |
| 3842 | or a routing problem. Once -N has been used for a delivery attempt, it |
| 3843 | sticks to the message, and applies to any subsequent delivery attempts that |
| 3844 | may happen for that message. |
| 3845 | |
| 3846 | -n |
| 3847 | |
| 3848 | This option is interpreted by Sendmail to mean "no aliasing". For normal |
| 3849 | modes of operation, it is ignored by Exim. When combined with -bP it makes |
| 3850 | the output more terse (suppresses option names, environment values and |
| 3851 | config pretty printing). |
| 3852 | |
| 3853 | -O <data> |
| 3854 | |
| 3855 | This option is interpreted by Sendmail to mean "set option". It is ignored |
| 3856 | by Exim. |
| 3857 | |
| 3858 | -oA <file name> |
| 3859 | |
| 3860 | This option is used by Sendmail in conjunction with -bi to specify an |
| 3861 | alternative alias file name. Exim handles -bi differently; see the |
| 3862 | description above. |
| 3863 | |
| 3864 | -oB <n> |
| 3865 | |
| 3866 | This is a debugging option which limits the maximum number of messages that |
| 3867 | can be delivered down one SMTP connection, overriding the value set in any |
| 3868 | smtp transport. If <n> is omitted, the limit is set to 1. |
| 3869 | |
| 3870 | -odb |
| 3871 | |
| 3872 | This option applies to all modes in which Exim accepts incoming messages, |
| 3873 | including the listening daemon. It requests "background" delivery of such |
| 3874 | messages, which means that the accepting process automatically starts a |
| 3875 | delivery process for each message received, but does not wait for the |
| 3876 | delivery processes to finish. |
| 3877 | |
| 3878 | When all the messages have been received, the reception process exits, |
| 3879 | leaving the delivery processes to finish in their own time. The standard |
| 3880 | output and error streams are closed at the start of each delivery process. |
| 3881 | This is the default action if none of the -od options are present. |
| 3882 | |
| 3883 | If one of the queueing options in the configuration file (queue_only or |
| 3884 | queue_only_file, for example) is in effect, -odb overrides it if |
| 3885 | queue_only_override is set true, which is the default setting. If |
| 3886 | queue_only_override is set false, -odb has no effect. |
| 3887 | |
| 3888 | -odf |
| 3889 | |
| 3890 | This option requests "foreground" (synchronous) delivery when Exim has |
| 3891 | accepted a locally-generated message. (For the daemon it is exactly the |
| 3892 | same as -odb.) A delivery process is automatically started to deliver the |
| 3893 | message, and Exim waits for it to complete before proceeding. |
| 3894 | |
| 3895 | The original Exim reception process does not finish until the delivery |
| 3896 | process for the final message has ended. The standard error stream is left |
| 3897 | open during deliveries. |
| 3898 | |
| 3899 | However, like -odb, this option has no effect if queue_only_override is |
| 3900 | false and one of the queueing options in the configuration file is in |
| 3901 | effect. |
| 3902 | |
| 3903 | If there is a temporary delivery error during foreground delivery, the |
| 3904 | message is left on the queue for later delivery, and the original reception |
| 3905 | process exits. See chapter 51 for a way of setting up a restricted |
| 3906 | configuration that never queues messages. |
| 3907 | |
| 3908 | -odi |
| 3909 | |
| 3910 | This option is synonymous with -odf. It is provided for compatibility with |
| 3911 | Sendmail. |
| 3912 | |
| 3913 | -odq |
| 3914 | |
| 3915 | This option applies to all modes in which Exim accepts incoming messages, |
| 3916 | including the listening daemon. It specifies that the accepting process |
| 3917 | should not automatically start a delivery process for each message |
| 3918 | received. Messages are placed on the queue, and remain there until a |
| 3919 | subsequent queue runner process encounters them. There are several |
| 3920 | configuration options (such as queue_only) that can be used to queue |
| 3921 | incoming messages under certain conditions. This option overrides all of |
| 3922 | them and also -odqs. It always forces queueing. |
| 3923 | |
| 3924 | -odqs |
| 3925 | |
| 3926 | This option is a hybrid between -odb/-odi and -odq. However, like -odb and |
| 3927 | -odi, this option has no effect if queue_only_override is false and one of |
| 3928 | the queueing options in the configuration file is in effect. |
| 3929 | |
| 3930 | When -odqs does operate, a delivery process is started for each incoming |
| 3931 | message, in the background by default, but in the foreground if -odi is |
| 3932 | also present. The recipient addresses are routed, and local deliveries are |
| 3933 | done in the normal way. However, if any SMTP deliveries are required, they |
| 3934 | are not done at this time, so the message remains on the queue until a |
| 3935 | subsequent queue runner process encounters it. Because routing was done, |
| 3936 | Exim knows which messages are waiting for which hosts, and so a number of |
| 3937 | messages for the same host can be sent in a single SMTP connection. The |
| 3938 | queue_smtp_domains configuration option has the same effect for specific |
| 3939 | domains. See also the -qq option. |
| 3940 | |
| 3941 | -oee |
| 3942 | |
| 3943 | If an error is detected while a non-SMTP message is being received (for |
| 3944 | example, a malformed address), the error is reported to the sender in a |
| 3945 | mail message. |
| 3946 | |
| 3947 | Provided this error message is successfully sent, the Exim receiving |
| 3948 | process exits with a return code of zero. If not, the return code is 2 if |
| 3949 | the problem is that the original message has no recipients, or 1 for any |
| 3950 | other error. This is the default -oex option if Exim is called as rmail. |
| 3951 | |
| 3952 | -oem |
| 3953 | |
| 3954 | This is the same as -oee, except that Exim always exits with a non-zero |
| 3955 | return code, whether or not the error message was successfully sent. This |
| 3956 | is the default -oex option, unless Exim is called as rmail. |
| 3957 | |
| 3958 | -oep |
| 3959 | |
| 3960 | If an error is detected while a non-SMTP message is being received, the |
| 3961 | error is reported by writing a message to the standard error file (stderr). |
| 3962 | The return code is 1 for all errors. |
| 3963 | |
| 3964 | -oeq |
| 3965 | |
| 3966 | This option is supported for compatibility with Sendmail, but has the same |
| 3967 | effect as -oep. |
| 3968 | |
| 3969 | -oew |
| 3970 | |
| 3971 | This option is supported for compatibility with Sendmail, but has the same |
| 3972 | effect as -oem. |
| 3973 | |
| 3974 | -oi |
| 3975 | |
| 3976 | This option, which has the same effect as -i, specifies that a dot on a |
| 3977 | line by itself should not terminate an incoming, non-SMTP message. |
| 3978 | Otherwise, a single dot does terminate, though Exim does no special |
| 3979 | processing for other lines that start with a dot. This option is set by |
| 3980 | default if Exim is called as rmail. See also -ti. |
| 3981 | |
| 3982 | -oitrue |
| 3983 | |
| 3984 | This option is treated as synonymous with -oi. |
| 3985 | |
| 3986 | -oMa <host address> |
| 3987 | |
| 3988 | A number of options starting with -oM can be used to set values associated |
| 3989 | with remote hosts on locally-submitted messages (that is, messages not |
| 3990 | received over TCP/IP). These options can be used by any caller in |
| 3991 | conjunction with the -bh, -be, -bf, -bF, -bt, or -bv testing options. In |
| 3992 | other circumstances, they are ignored unless the caller is trusted. |
| 3993 | |
| 3994 | The -oMa option sets the sender host address. This may include a port |
| 3995 | number at the end, after a full stop (period). For example: |
| 3996 | |
| 3997 | exim -bs -oMa 10.9.8.7.1234 |
| 3998 | |
| 3999 | An alternative syntax is to enclose the IP address in square brackets, |
| 4000 | followed by a colon and the port number: |
| 4001 | |
| 4002 | exim -bs -oMa [10.9.8.7]:1234 |
| 4003 | |
| 4004 | The IP address is placed in the $sender_host_address variable, and the |
| 4005 | port, if present, in $sender_host_port. If both -oMa and -bh are present on |
| 4006 | the command line, the sender host IP address is taken from whichever one is |
| 4007 | last. |
| 4008 | |
| 4009 | -oMaa <name> |
| 4010 | |
| 4011 | See -oMa above for general remarks about the -oM options. The -oMaa option |
| 4012 | sets the value of $sender_host_authenticated (the authenticator name). See |
| 4013 | chapter 33 for a discussion of SMTP authentication. This option can be used |
| 4014 | with -bh and -bs to set up an authenticated SMTP session without actually |
| 4015 | using the SMTP AUTH command. |
| 4016 | |
| 4017 | -oMai <string> |
| 4018 | |
| 4019 | See -oMa above for general remarks about the -oM options. The -oMai option |
| 4020 | sets the value of $authenticated_id (the id that was authenticated). This |
| 4021 | overrides the default value (the caller's login id, except with -bh, where |
| 4022 | there is no default) for messages from local sources. See chapter 33 for a |
| 4023 | discussion of authenticated ids. |
| 4024 | |
| 4025 | -oMas <address> |
| 4026 | |
| 4027 | See -oMa above for general remarks about the -oM options. The -oMas option |
| 4028 | sets the authenticated sender value in $authenticated_sender. It overrides |
| 4029 | the sender address that is created from the caller's login id for messages |
| 4030 | from local sources, except when -bh is used, when there is no default. For |
| 4031 | both -bh and -bs, an authenticated sender that is specified on a MAIL |
| 4032 | command overrides this value. See chapter 33 for a discussion of |
| 4033 | authenticated senders. |
| 4034 | |
| 4035 | -oMi <interface address> |
| 4036 | |
| 4037 | See -oMa above for general remarks about the -oM options. The -oMi option |
| 4038 | sets the IP interface address value. A port number may be included, using |
| 4039 | the same syntax as for -oMa. The interface address is placed in |
| 4040 | $received_ip_address and the port number, if present, in $received_port. |
| 4041 | |
| 4042 | -oMm <message reference> |
| 4043 | |
| 4044 | See -oMa above for general remarks about the -oM options. The -oMm option |
| 4045 | sets the message reference, e.g. message-id, and is logged during delivery. |
| 4046 | This is useful when some kind of audit trail is required to tie messages |
| 4047 | together. The format of the message reference is checked and will abort if |
| 4048 | the format is invalid. The option will only be accepted if exim is running |
| 4049 | in trusted mode, not as any regular user. |
| 4050 | |
| 4051 | The best example of a message reference is when Exim sends a bounce |
| 4052 | message. The message reference is the message-id of the original message |
| 4053 | for which Exim is sending the bounce. |
| 4054 | |
| 4055 | -oMr <protocol name> |
| 4056 | |
| 4057 | See -oMa above for general remarks about the -oM options. The -oMr option |
| 4058 | sets the received protocol value that is stored in $received_protocol. |
| 4059 | However, it does not apply (and is ignored) when -bh or -bs is used. For |
| 4060 | -bh, the protocol is forced to one of the standard SMTP protocol names (see |
| 4061 | the description of $received_protocol in section 11.9). For -bs, the |
| 4062 | protocol is always "local-" followed by one of those same names. For -bS |
| 4063 | (batched SMTP) however, the protocol can be set by -oMr. |
| 4064 | |
| 4065 | -oMs <host name> |
| 4066 | |
| 4067 | See -oMa above for general remarks about the -oM options. The -oMs option |
| 4068 | sets the sender host name in $sender_host_name. When this option is |
| 4069 | present, Exim does not attempt to look up a host name from an IP address; |
| 4070 | it uses the name it is given. |
| 4071 | |
| 4072 | -oMt <ident string> |
| 4073 | |
| 4074 | See -oMa above for general remarks about the -oM options. The -oMt option |
| 4075 | sets the sender ident value in $sender_ident. The default setting for local |
| 4076 | callers is the login id of the calling process, except when -bh is used, |
| 4077 | when there is no default. |
| 4078 | |
| 4079 | -om |
| 4080 | |
| 4081 | In Sendmail, this option means "me too", indicating that the sender of a |
| 4082 | message should receive a copy of the message if the sender appears in an |
| 4083 | alias expansion. Exim always does this, so the option does nothing. |
| 4084 | |
| 4085 | -oo |
| 4086 | |
| 4087 | This option is ignored. In Sendmail it specifies "old style headers", |
| 4088 | whatever that means. |
| 4089 | |
| 4090 | -oP <path> |
| 4091 | |
| 4092 | This option is useful only in conjunction with -bd or -q with a time value. |
| 4093 | The option specifies the file to which the process id of the daemon is |
| 4094 | written. When -oX is used with -bd, or when -q with a time is used without |
| 4095 | -bd, this is the only way of causing Exim to write a pid file, because in |
| 4096 | those cases, the normal pid file is not used. |
| 4097 | |
| 4098 | -or <time> |
| 4099 | |
| 4100 | This option sets a timeout value for incoming non-SMTP messages. If it is |
| 4101 | not set, Exim will wait forever for the standard input. The value can also |
| 4102 | be set by the receive_timeout option. The format used for specifying times |
| 4103 | is described in section 6.16. |
| 4104 | |
| 4105 | -os <time> |
| 4106 | |
| 4107 | This option sets a timeout value for incoming SMTP messages. The timeout |
| 4108 | applies to each SMTP command and block of data. The value can also be set |
| 4109 | by the smtp_receive_timeout option; it defaults to 5 minutes. The format |
| 4110 | used for specifying times is described in section 6.16. |
| 4111 | |
| 4112 | -ov |
| 4113 | |
| 4114 | This option has exactly the same effect as -v. |
| 4115 | |
| 4116 | -oX <number or string> |
| 4117 | |
| 4118 | This option is relevant only when the -bd (start listening daemon) option |
| 4119 | is also given. It controls which ports and interfaces the daemon uses. |
| 4120 | Details of the syntax, and how it interacts with configuration file |
| 4121 | options, are given in chapter 13. When -oX is used to start a daemon, no |
| 4122 | pid file is written unless -oP is also present to specify a pid file name. |
| 4123 | |
| 4124 | -pd |
| 4125 | |
| 4126 | This option applies when an embedded Perl interpreter is linked with Exim |
| 4127 | (see chapter 12). It overrides the setting of the perl_at_start option, |
| 4128 | forcing the starting of the interpreter to be delayed until it is needed. |
| 4129 | |
| 4130 | -ps |
| 4131 | |
| 4132 | This option applies when an embedded Perl interpreter is linked with Exim |
| 4133 | (see chapter 12). It overrides the setting of the perl_at_start option, |
| 4134 | forcing the starting of the interpreter to occur as soon as Exim is |
| 4135 | started. |
| 4136 | |
| 4137 | -p<rval>:<sval> |
| 4138 | |
| 4139 | For compatibility with Sendmail, this option is equivalent to |
| 4140 | |
| 4141 | -oMr <rval> -oMs <sval> |
| 4142 | |
| 4143 | It sets the incoming protocol and host name (for trusted callers). The host |
| 4144 | name and its colon can be omitted when only the protocol is to be set. Note |
| 4145 | the Exim already has two private options, -pd and -ps, that refer to |
| 4146 | embedded Perl. It is therefore impossible to set a protocol value of "d" or |
| 4147 | "s" using this option (but that does not seem a real limitation). |
| 4148 | |
| 4149 | -q |
| 4150 | |
| 4151 | This option is normally restricted to admin users. However, there is a |
| 4152 | configuration option called prod_requires_admin which can be set false to |
| 4153 | relax this restriction (and also the same requirement for the -M, -R, and |
| 4154 | -S options). |
| 4155 | |
| 4156 | If other commandline options do not specify an action, the -q option starts |
| 4157 | one queue runner process. This scans the queue of waiting messages, and |
| 4158 | runs a delivery process for each one in turn. It waits for each delivery |
| 4159 | process to finish before starting the next one. A delivery process may not |
| 4160 | actually do any deliveries if the retry times for the addresses have not |
| 4161 | been reached. Use -qf (see below) if you want to override this. |
| 4162 | |
| 4163 | If the delivery process spawns other processes to deliver other messages |
| 4164 | down passed SMTP connections, the queue runner waits for these to finish |
| 4165 | before proceeding. |
| 4166 | |
| 4167 | When all the queued messages have been considered, the original queue |
| 4168 | runner process terminates. In other words, a single pass is made over the |
| 4169 | waiting mail, one message at a time. Use -q with a time (see below) if you |
| 4170 | want this to be repeated periodically. |
| 4171 | |
| 4172 | Exim processes the waiting messages in an unpredictable order. It isn't |
| 4173 | very random, but it is likely to be different each time, which is all that |
| 4174 | matters. If one particular message screws up a remote MTA, other messages |
| 4175 | to the same MTA have a chance of getting through if they get tried first. |
| 4176 | |
| 4177 | It is possible to cause the messages to be processed in lexical message id |
| 4178 | order, which is essentially the order in which they arrived, by setting the |
| 4179 | queue_run_in_order option, but this is not recommended for normal use. |
| 4180 | |
| 4181 | -q<qflags> |
| 4182 | |
| 4183 | The -q option may be followed by one or more flag letters that change its |
| 4184 | behaviour. They are all optional, but if more than one is present, they |
| 4185 | must appear in the correct order. Each flag is described in a separate item |
| 4186 | below. |
| 4187 | |
| 4188 | -qq... |
| 4189 | |
| 4190 | An option starting with -qq requests a two-stage queue run. In the first |
| 4191 | stage, the queue is scanned as if the queue_smtp_domains option matched |
| 4192 | every domain. Addresses are routed, local deliveries happen, but no remote |
| 4193 | transports are run. |
| 4194 | |
| 4195 | The hints database that remembers which messages are waiting for specific |
| 4196 | hosts is updated, as if delivery to those hosts had been deferred. After |
| 4197 | this is complete, a second, normal queue scan happens, with routing and |
| 4198 | delivery taking place as normal. Messages that are routed to the same host |
| 4199 | should mostly be delivered down a single SMTP connection because of the |
| 4200 | hints that were set up during the first queue scan. This option may be |
| 4201 | useful for hosts that are connected to the Internet intermittently. |
| 4202 | |
| 4203 | -q[q]i... |
| 4204 | |
| 4205 | If the i flag is present, the queue runner runs delivery processes only for |
| 4206 | those messages that haven't previously been tried. (i stands for "initial |
| 4207 | delivery".) This can be helpful if you are putting messages on the queue |
| 4208 | using -odq and want a queue runner just to process the new messages. |
| 4209 | |
| 4210 | -q[q][i]f... |
| 4211 | |
| 4212 | If one f flag is present, a delivery attempt is forced for each non-frozen |
| 4213 | message, whereas without f only those non-frozen addresses that have passed |
| 4214 | their retry times are tried. |
| 4215 | |
| 4216 | -q[q][i]ff... |
| 4217 | |
| 4218 | If ff is present, a delivery attempt is forced for every message, whether |
| 4219 | frozen or not. |
| 4220 | |
| 4221 | -q[q][i][f[f]]l |
| 4222 | |
| 4223 | The l (the letter "ell") flag specifies that only local deliveries are to |
| 4224 | be done. If a message requires any remote deliveries, it remains on the |
| 4225 | queue for later delivery. |
| 4226 | |
| 4227 | -q[q][i][f[f]][l][G<name>[/<time>]]] |
| 4228 | |
| 4229 | If the G flag and a name is present, the queue runner operates on the queue |
| 4230 | with the given name rather than the default queue. The name should not |
| 4231 | contain a / character. For a periodic queue run (see below) append to the |
| 4232 | name a slash and a time value. |
| 4233 | |
| 4234 | If other commandline options specify an action, a -qG<name> option will |
| 4235 | specify a queue to operate on. For example: |
| 4236 | |
| 4237 | exim -bp -qGquarantine |
| 4238 | mailq -qGquarantine |
| 4239 | exim -qGoffpeak -Rf @special.domain.example |
| 4240 | |
| 4241 | -q<qflags> <start id> <end id> |
| 4242 | |
| 4243 | When scanning the queue, Exim can be made to skip over messages whose ids |
| 4244 | are lexically less than a given value by following the -q option with a |
| 4245 | starting message id. For example: |
| 4246 | |
| 4247 | exim -q 0t5C6f-0000c8-00 |
| 4248 | |
| 4249 | Messages that arrived earlier than "0t5C6f-0000c8-00" are not inspected. If |
| 4250 | a second message id is given, messages whose ids are lexically greater than |
| 4251 | it are also skipped. If the same id is given twice, for example, |
| 4252 | |
| 4253 | exim -q 0t5C6f-0000c8-00 0t5C6f-0000c8-00 |
| 4254 | |
| 4255 | just one delivery process is started, for that message. This differs from |
| 4256 | -M in that retry data is respected, and it also differs from -Mc in that it |
| 4257 | counts as a delivery from a queue run. Note that the selection mechanism |
| 4258 | does not affect the order in which the messages are scanned. There are also |
| 4259 | other ways of selecting specific sets of messages for delivery in a queue |
| 4260 | run - see -R and -S. |
| 4261 | |
| 4262 | -q<qflags><time> |
| 4263 | |
| 4264 | When a time value is present, the -q option causes Exim to run as a daemon, |
| 4265 | starting a queue runner process at intervals specified by the given time |
| 4266 | value (whose format is described in section 6.16). This form of the -q |
| 4267 | option is commonly combined with the -bd option, in which case a single |
| 4268 | daemon process handles both functions. A common way of starting up a |
| 4269 | combined daemon at system boot time is to use a command such as |
| 4270 | |
| 4271 | /usr/exim/bin/exim -bd -q30m |
| 4272 | |
| 4273 | Such a daemon listens for incoming SMTP calls, and also starts a queue |
| 4274 | runner process every 30 minutes. |
| 4275 | |
| 4276 | When a daemon is started by -q with a time value, but without -bd, no pid |
| 4277 | file is written unless one is explicitly requested by the -oP option. |
| 4278 | |
| 4279 | -qR<rsflags> <string> |
| 4280 | |
| 4281 | This option is synonymous with -R. It is provided for Sendmail |
| 4282 | compatibility. |
| 4283 | |
| 4284 | -qS<rsflags> <string> |
| 4285 | |
| 4286 | This option is synonymous with -S. |
| 4287 | |
| 4288 | -R<rsflags> <string> |
| 4289 | |
| 4290 | The <rsflags> may be empty, in which case the white space before the string |
| 4291 | is optional, unless the string is f, ff, r, rf, or rff, which are the |
| 4292 | possible values for <rsflags>. White space is required if <rsflags> is not |
| 4293 | empty. |
| 4294 | |
| 4295 | This option is similar to -q with no time value, that is, it causes Exim to |
| 4296 | perform a single queue run, except that, when scanning the messages on the |
| 4297 | queue, Exim processes only those that have at least one undelivered |
| 4298 | recipient address containing the given string, which is checked in a |
| 4299 | case-independent way. If the <rsflags> start with r, <string> is |
| 4300 | interpreted as a regular expression; otherwise it is a literal string. |
| 4301 | |
| 4302 | If you want to do periodic queue runs for messages with specific |
| 4303 | recipients, you can combine -R with -q and a time value. For example: |
| 4304 | |
| 4305 | exim -q25m -R @special.domain.example |
| 4306 | |
| 4307 | This example does a queue run for messages with recipients in the given |
| 4308 | domain every 25 minutes. Any additional flags that are specified with -q |
| 4309 | are applied to each queue run. |
| 4310 | |
| 4311 | Once a message is selected for delivery by this mechanism, all its |
| 4312 | addresses are processed. For the first selected message, Exim overrides any |
| 4313 | retry information and forces a delivery attempt for each undelivered |
| 4314 | address. This means that if delivery of any address in the first message is |
| 4315 | successful, any existing retry information is deleted, and so delivery |
| 4316 | attempts for that address in subsequently selected messages (which are |
| 4317 | processed without forcing) will run. However, if delivery of any address |
| 4318 | does not succeed, the retry information is updated, and in subsequently |
| 4319 | selected messages, the failing address will be skipped. |
| 4320 | |
| 4321 | If the <rsflags> contain f or ff, the delivery forcing applies to all |
| 4322 | selected messages, not just the first; frozen messages are included when ff |
| 4323 | is present. |
| 4324 | |
| 4325 | The -R option makes it straightforward to initiate delivery of all messages |
| 4326 | to a given domain after a host has been down for some time. When the SMTP |
| 4327 | command ETRN is accepted by its ACL (see chapter 43), its default effect is |
| 4328 | to run Exim with the -R option, but it can be configured to run an |
| 4329 | arbitrary command instead. |
| 4330 | |
| 4331 | -r |
| 4332 | |
| 4333 | This is a documented (for Sendmail) obsolete alternative name for -f. |
| 4334 | |
| 4335 | -S<rsflags> <string> |
| 4336 | |
| 4337 | This option acts like -R except that it checks the string against each |
| 4338 | message's sender instead of against the recipients. If -R is also set, both |
| 4339 | conditions must be met for a message to be selected. If either of the |
| 4340 | options has f or ff in its flags, the associated action is taken. |
| 4341 | |
| 4342 | -Tqt <times> |
| 4343 | |
| 4344 | This is an option that is exclusively for use by the Exim testing suite. It |
| 4345 | is not recognized when Exim is run normally. It allows for the setting up |
| 4346 | of explicit "queue times" so that various warning/retry features can be |
| 4347 | tested. |
| 4348 | |
| 4349 | -t |
| 4350 | |
| 4351 | When Exim is receiving a locally-generated, non-SMTP message on its |
| 4352 | standard input, the -t option causes the recipients of the message to be |
| 4353 | obtained from the To:, Cc:, and Bcc: header lines in the message instead of |
| 4354 | from the command arguments. The addresses are extracted before any |
| 4355 | rewriting takes place and the Bcc: header line, if present, is then |
| 4356 | removed. |
| 4357 | |
| 4358 | If the command has any arguments, they specify addresses to which the |
| 4359 | message is not to be delivered. That is, the argument addresses are removed |
| 4360 | from the recipients list obtained from the headers. This is compatible with |
| 4361 | Smail 3 and in accordance with the documented behaviour of several versions |
| 4362 | of Sendmail, as described in man pages on a number of operating systems |
| 4363 | (e.g. Solaris 8, IRIX 6.5, HP-UX 11). However, some versions of Sendmail |
| 4364 | add argument addresses to those obtained from the headers, and the O'Reilly |
| 4365 | Sendmail book documents it that way. Exim can be made to add argument |
| 4366 | addresses instead of subtracting them by setting the option |
| 4367 | extract_addresses_remove_arguments false. |
| 4368 | |
| 4369 | If there are any Resent- header lines in the message, Exim extracts |
| 4370 | recipients from all Resent-To:, Resent-Cc:, and Resent-Bcc: header lines |
| 4371 | instead of from To:, Cc:, and Bcc:. This is for compatibility with Sendmail |
| 4372 | and other MTAs. (Prior to release 4.20, Exim gave an error if -t was used |
| 4373 | in conjunction with Resent- header lines.) |
| 4374 | |
| 4375 | RFC 2822 talks about different sets of Resent- header lines (for when a |
| 4376 | message is resent several times). The RFC also specifies that they should |
| 4377 | be added at the front of the message, and separated by Received: lines. It |
| 4378 | is not at all clear how -t should operate in the present of multiple sets, |
| 4379 | nor indeed exactly what constitutes a "set". In practice, it seems that |
| 4380 | MUAs do not follow the RFC. The Resent- lines are often added at the end of |
| 4381 | the header, and if a message is resent more than once, it is common for the |
| 4382 | original set of Resent- headers to be renamed as X-Resent- when a new set |
| 4383 | is added. This removes any possible ambiguity. |
| 4384 | |
| 4385 | -ti |
| 4386 | |
| 4387 | This option is exactly equivalent to -t -i. It is provided for |
| 4388 | compatibility with Sendmail. |
| 4389 | |
| 4390 | -tls-on-connect |
| 4391 | |
| 4392 | This option is available when Exim is compiled with TLS support. It forces |
| 4393 | all incoming SMTP connections to behave as if the incoming port is listed |
| 4394 | in the tls_on_connect_ports option. See section 13.4 and chapter 42 for |
| 4395 | further details. |
| 4396 | |
| 4397 | -U |
| 4398 | |
| 4399 | Sendmail uses this option for "initial message submission", and its |
| 4400 | documentation states that in future releases, it may complain about |
| 4401 | syntactically invalid messages rather than fixing them when this flag is |
| 4402 | not set. Exim ignores this option. |
| 4403 | |
| 4404 | -v |
| 4405 | |
| 4406 | This option causes Exim to write information to the standard error stream, |
| 4407 | describing what it is doing. In particular, it shows the log lines for |
| 4408 | receiving and delivering a message, and if an SMTP connection is made, the |
| 4409 | SMTP dialogue is shown. Some of the log lines shown may not actually be |
| 4410 | written to the log if the setting of log_selector discards them. Any |
| 4411 | relevant selectors are shown with each log line. If none are shown, the |
| 4412 | logging is unconditional. |
| 4413 | |
| 4414 | -x |
| 4415 | |
| 4416 | AIX uses -x for a private purpose ("mail from a local mail program has |
| 4417 | National Language Support extended characters in the body of the mail |
| 4418 | item"). It sets -x when calling the MTA from its mail command. Exim ignores |
| 4419 | this option. |
| 4420 | |
| 4421 | -X <logfile> |
| 4422 | |
| 4423 | This option is interpreted by Sendmail to cause debug information to be |
| 4424 | sent to the named file. It is ignored by Exim. |
| 4425 | |
| 4426 | -z <log-line> |
| 4427 | |
| 4428 | This option writes its argument to Exim's logfile. Use is restricted to |
| 4429 | administrators; the intent is for operational notes. Quotes should be used |
| 4430 | to maintain a multi-word item as a single argument, under most shells. |
| 4431 | |
| 4432 | |
| 4433 | |
| 4434 | =============================================================================== |
| 4435 | 6. THE EXIM RUN TIME CONFIGURATION FILE |
| 4436 | |
| 4437 | Exim uses a single run time configuration file that is read whenever an Exim |
| 4438 | binary is executed. Note that in normal operation, this happens frequently, |
| 4439 | because Exim is designed to operate in a distributed manner, without central |
| 4440 | control. |
| 4441 | |
| 4442 | If a syntax error is detected while reading the configuration file, Exim writes |
| 4443 | a message on the standard error, and exits with a non-zero return code. The |
| 4444 | message is also written to the panic log. Note: Only simple syntax errors can |
| 4445 | be detected at this time. The values of any expanded options are not checked |
| 4446 | until the expansion happens, even when the expansion does not actually alter |
| 4447 | the string. |
| 4448 | |
| 4449 | The name of the configuration file is compiled into the binary for security |
| 4450 | reasons, and is specified by the CONFIGURE_FILE compilation option. In most |
| 4451 | configurations, this specifies a single file. However, it is permitted to give |
| 4452 | a colon-separated list of file names, in which case Exim uses the first |
| 4453 | existing file in the list. |
| 4454 | |
| 4455 | The run time configuration file must be owned by root or by the user that is |
| 4456 | specified at compile time by the CONFIGURE_OWNER option (if set). The |
| 4457 | configuration file must not be world-writeable, or group-writeable unless its |
| 4458 | group is the root group or the one specified at compile time by the |
| 4459 | CONFIGURE_GROUP option. |
| 4460 | |
| 4461 | Warning: In a conventional configuration, where the Exim binary is setuid to |
| 4462 | root, anybody who is able to edit the run time configuration file has an easy |
| 4463 | way to run commands as root. If you specify a user or group in the |
| 4464 | CONFIGURE_OWNER or CONFIGURE_GROUP options, then that user and/or any users who |
| 4465 | are members of that group will trivially be able to obtain root privileges. |
| 4466 | |
| 4467 | Up to Exim version 4.72, the run time configuration file was also permitted to |
| 4468 | be writeable by the Exim user and/or group. That has been changed in Exim 4.73 |
| 4469 | since it offered a simple privilege escalation for any attacker who managed to |
| 4470 | compromise the Exim user account. |
| 4471 | |
| 4472 | A default configuration file, which will work correctly in simple situations, |
| 4473 | is provided in the file src/configure.default. If CONFIGURE_FILE defines just |
| 4474 | one file name, the installation process copies the default configuration to a |
| 4475 | new file of that name if it did not previously exist. If CONFIGURE_FILE is a |
| 4476 | list, no default is automatically installed. Chapter 7 is a "walk-through" |
| 4477 | discussion of the default configuration. |
| 4478 | |
| 4479 | |
| 4480 | 6.1 Using a different configuration file |
| 4481 | ---------------------------------------- |
| 4482 | |
| 4483 | A one-off alternate configuration can be specified by the -C command line |
| 4484 | option, which may specify a single file or a list of files. However, when -C is |
| 4485 | used, Exim gives up its root privilege, unless called by root (or unless the |
| 4486 | argument for -C is identical to the built-in value from CONFIGURE_FILE), or is |
| 4487 | listed in the TRUSTED_CONFIG_LIST file and the caller is the Exim user or the |
| 4488 | user specified in the CONFIGURE_OWNER setting. -C is useful mainly for checking |
| 4489 | the syntax of configuration files before installing them. No owner or group |
| 4490 | checks are done on a configuration file specified by -C, if root privilege has |
| 4491 | been dropped. |
| 4492 | |
| 4493 | Even the Exim user is not trusted to specify an arbitrary configuration file |
| 4494 | with the -C option to be used with root privileges, unless that file is listed |
| 4495 | in the TRUSTED_CONFIG_LIST file. This locks out the possibility of testing a |
| 4496 | configuration using -C right through message reception and delivery, even if |
| 4497 | the caller is root. The reception works, but by that time, Exim is running as |
| 4498 | the Exim user, so when it re-execs to regain privilege for the delivery, the |
| 4499 | use of -C causes privilege to be lost. However, root can test reception and |
| 4500 | delivery using two separate commands (one to put a message on the queue, using |
| 4501 | -odq, and another to do the delivery, using -M). |
| 4502 | |
| 4503 | If ALT_CONFIG_PREFIX is defined in Local/Makefile, it specifies a prefix string |
| 4504 | with which any file named in a -C command line option must start. In addition, |
| 4505 | the file name must not contain the sequence "/../". There is no default setting |
| 4506 | for ALT_CONFIG_PREFIX; when it is unset, any file name can be used with -C. |
| 4507 | |
| 4508 | One-off changes to a configuration can be specified by the -D command line |
| 4509 | option, which defines and overrides values for macros used inside the |
| 4510 | configuration file. However, like -C, the use of this option by a |
| 4511 | non-privileged user causes Exim to discard its root privilege. If |
| 4512 | DISABLE_D_OPTION is defined in Local/Makefile, the use of -D is completely |
| 4513 | disabled, and its use causes an immediate error exit. |
| 4514 | |
| 4515 | The WHITELIST_D_MACROS option in Local/Makefile permits the binary builder to |
| 4516 | declare certain macro names trusted, such that root privilege will not |
| 4517 | necessarily be discarded. WHITELIST_D_MACROS defines a colon-separated list of |
| 4518 | macros which are considered safe and, if -D only supplies macros from this |
| 4519 | list, and the values are acceptable, then Exim will not give up root privilege |
| 4520 | if the caller is root, the Exim run-time user, or the CONFIGURE_OWNER, if set. |
| 4521 | This is a transition mechanism and is expected to be removed in the future. |
| 4522 | Acceptable values for the macros satisfy the regexp: "^[A-Za-z0-9_/.-]*$" |
| 4523 | |
| 4524 | Some sites may wish to use the same Exim binary on different machines that |
| 4525 | share a file system, but to use different configuration files on each machine. |
| 4526 | If CONFIGURE_FILE_USE_NODE is defined in Local/Makefile, Exim first looks for a |
| 4527 | file whose name is the configuration file name followed by a dot and the |
| 4528 | machine's node name, as obtained from the uname() function. If this file does |
| 4529 | not exist, the standard name is tried. This processing occurs for each file |
| 4530 | name in the list given by CONFIGURE_FILE or -C. |
| 4531 | |
| 4532 | In some esoteric situations different versions of Exim may be run under |
| 4533 | different effective uids and the CONFIGURE_FILE_USE_EUID is defined to help |
| 4534 | with this. See the comments in src/EDITME for details. |
| 4535 | |
| 4536 | |
| 4537 | 6.2 Configuration file format |
| 4538 | ----------------------------- |
| 4539 | |
| 4540 | Exim's configuration file is divided into a number of different parts. General |
| 4541 | option settings must always appear at the start of the file. The other parts |
| 4542 | are all optional, and may appear in any order. Each part other than the first |
| 4543 | is introduced by the word "begin" followed by at least one literal space, and |
| 4544 | the name of the part. The optional parts are: |
| 4545 | |
| 4546 | * ACL: Access control lists for controlling incoming SMTP mail (see chapter |
| 4547 | 43). |
| 4548 | |
| 4549 | * authenticators: Configuration settings for the authenticator drivers. These |
| 4550 | are concerned with the SMTP AUTH command (see chapter 33). |
| 4551 | |
| 4552 | * routers: Configuration settings for the router drivers. Routers process |
| 4553 | addresses and determine how the message is to be delivered (see chapters 15 |
| 4554 | -22). |
| 4555 | |
| 4556 | * transports: Configuration settings for the transport drivers. Transports |
| 4557 | define mechanisms for copying messages to destinations (see chapters 24-30 |
| 4558 | ). |
| 4559 | |
| 4560 | * retry: Retry rules, for use when a message cannot be delivered immediately. |
| 4561 | If there is no retry section, or if it is empty (that is, no retry rules |
| 4562 | are defined), Exim will not retry deliveries. In this situation, temporary |
| 4563 | errors are treated the same as permanent errors. Retry rules are discussed |
| 4564 | in chapter 32. |
| 4565 | |
| 4566 | * rewrite: Global address rewriting rules, for use when a message arrives and |
| 4567 | when new addresses are generated during delivery. Rewriting is discussed in |
| 4568 | chapter 31. |
| 4569 | |
| 4570 | * local_scan: Private options for the local_scan() function. If you want to |
| 4571 | use this feature, you must set |
| 4572 | |
| 4573 | LOCAL_SCAN_HAS_OPTIONS=yes |
| 4574 | |
| 4575 | in Local/Makefile before building Exim. Details of the local_scan() |
| 4576 | facility are given in chapter 45. |
| 4577 | |
| 4578 | Leading and trailing white space in configuration lines is always ignored. |
| 4579 | |
| 4580 | Blank lines in the file, and lines starting with a # character (ignoring |
| 4581 | leading white space) are treated as comments and are ignored. Note: A # |
| 4582 | character other than at the beginning of a line is not treated specially, and |
| 4583 | does not introduce a comment. |
| 4584 | |
| 4585 | Any non-comment line can be continued by ending it with a backslash. Note that |
| 4586 | the general rule for white space means that trailing white space after the |
| 4587 | backslash and leading white space at the start of continuation lines is |
| 4588 | ignored. Comment lines beginning with # (but not empty lines) may appear in the |
| 4589 | middle of a sequence of continuation lines. |
| 4590 | |
| 4591 | A convenient way to create a configuration file is to start from the default, |
| 4592 | which is supplied in src/configure.default, and add, delete, or change settings |
| 4593 | as required. |
| 4594 | |
| 4595 | The ACLs, retry rules, and rewriting rules have their own syntax which is |
| 4596 | described in chapters 43, 32, and 31, respectively. The other parts of the |
| 4597 | configuration file have some syntactic items in common, and these are described |
| 4598 | below, from section 6.11 onwards. Before that, the inclusion, macro, and |
| 4599 | conditional facilities are described. |
| 4600 | |
| 4601 | |
| 4602 | 6.3 File inclusions in the configuration file |
| 4603 | --------------------------------------------- |
| 4604 | |
| 4605 | You can include other files inside Exim's run time configuration file by using |
| 4606 | this syntax: |
| 4607 | |
| 4608 | .include <file name> |
| 4609 | .include_if_exists <file name> |
| 4610 | |
| 4611 | on a line by itself. Double quotes round the file name are optional. If you use |
| 4612 | the first form, a configuration error occurs if the file does not exist; the |
| 4613 | second form does nothing for non-existent files. |
| 4614 | |
| 4615 | The first form allows a relative name. It is resolved relative to the directory |
| 4616 | of the including file. For the second form an absolute file name is required. |
| 4617 | |
| 4618 | Includes may be nested to any depth, but remember that Exim reads its |
| 4619 | configuration file often, so it is a good idea to keep them to a minimum. If |
| 4620 | you change the contents of an included file, you must HUP the daemon, because |
| 4621 | an included file is read only when the configuration itself is read. |
| 4622 | |
| 4623 | The processing of inclusions happens early, at a physical line level, so, like |
| 4624 | comment lines, an inclusion can be used in the middle of an option setting, for |
| 4625 | example: |
| 4626 | |
| 4627 | hosts_lookup = a.b.c \ |
| 4628 | .include /some/file |
| 4629 | |
| 4630 | Include processing happens after macro processing (see below). Its effect is to |
| 4631 | process the lines of the included file as if they occurred inline where the |
| 4632 | inclusion appears. |
| 4633 | |
| 4634 | |
| 4635 | 6.4 Macros in the configuration file |
| 4636 | ------------------------------------ |
| 4637 | |
| 4638 | If a line in the main part of the configuration (that is, before the first |
| 4639 | "begin" line) begins with an upper case letter, it is taken as a macro |
| 4640 | definition, and must be of the form |
| 4641 | |
| 4642 | <name> = <rest of line> |
| 4643 | |
| 4644 | The name must consist of letters, digits, and underscores, and need not all be |
| 4645 | in upper case, though that is recommended. The rest of the line, including any |
| 4646 | continuations, is the replacement text, and has leading and trailing white |
| 4647 | space removed. Quotes are not removed. The replacement text can never end with |
| 4648 | a backslash character, but this doesn't seem to be a serious limitation. |
| 4649 | |
| 4650 | Macros may also be defined between router, transport, authenticator, or ACL |
| 4651 | definitions. They may not, however, be defined within an individual driver or |
| 4652 | ACL, or in the local_scan, retry, or rewrite sections of the configuration. |
| 4653 | |
| 4654 | |
| 4655 | 6.5 Macro substitution |
| 4656 | ---------------------- |
| 4657 | |
| 4658 | Once a macro is defined, all subsequent lines in the file (and any included |
| 4659 | files) are scanned for the macro name; if there are several macros, the line is |
| 4660 | scanned for each in turn, in the order in which the macros are defined. The |
| 4661 | replacement text is not re-scanned for the current macro, though it is scanned |
| 4662 | for subsequently defined macros. For this reason, a macro name may not contain |
| 4663 | the name of a previously defined macro as a substring. You could, for example, |
| 4664 | define |
| 4665 | |
| 4666 | ABCD_XYZ = <something> |
| 4667 | ABCD = <something else> |
| 4668 | |
| 4669 | but putting the definitions in the opposite order would provoke a configuration |
| 4670 | error. Macro expansion is applied to individual physical lines from the file, |
| 4671 | before checking for line continuation or file inclusion (see above). If a line |
| 4672 | consists solely of a macro name, and the expansion of the macro is empty, the |
| 4673 | line is ignored. A macro at the start of a line may turn the line into a |
| 4674 | comment line or a ".include" line. |
| 4675 | |
| 4676 | |
| 4677 | 6.6 Redefining macros |
| 4678 | --------------------- |
| 4679 | |
| 4680 | Once defined, the value of a macro can be redefined later in the configuration |
| 4681 | (or in an included file). Redefinition is specified by using == instead of =. |
| 4682 | For example: |
| 4683 | |
| 4684 | MAC = initial value |
| 4685 | ... |
| 4686 | MAC == updated value |
| 4687 | |
| 4688 | Redefinition does not alter the order in which the macros are applied to the |
| 4689 | subsequent lines of the configuration file. It is still the same order in which |
| 4690 | the macros were originally defined. All that changes is the macro's value. |
| 4691 | Redefinition makes it possible to accumulate values. For example: |
| 4692 | |
| 4693 | MAC = initial value |
| 4694 | ... |
| 4695 | MAC == MAC and something added |
| 4696 | |
| 4697 | This can be helpful in situations where the configuration file is built from a |
| 4698 | number of other files. |
| 4699 | |
| 4700 | |
| 4701 | 6.7 Overriding macro values |
| 4702 | --------------------------- |
| 4703 | |
| 4704 | The values set for macros in the configuration file can be overridden by the -D |
| 4705 | command line option, but Exim gives up its root privilege when -D is used, |
| 4706 | unless called by root or the Exim user. A definition on the command line using |
| 4707 | the -D option causes all definitions and redefinitions within the file to be |
| 4708 | ignored. |
| 4709 | |
| 4710 | |
| 4711 | 6.8 Example of macro usage |
| 4712 | -------------------------- |
| 4713 | |
| 4714 | As an example of macro usage, consider a configuration where aliases are looked |
| 4715 | up in a MySQL database. It helps to keep the file less cluttered if long |
| 4716 | strings such as SQL statements are defined separately as macros, for example: |
| 4717 | |
| 4718 | ALIAS_QUERY = select mailbox from user where \ |
| 4719 | login='${quote_mysql:$local_part}'; |
| 4720 | |
| 4721 | This can then be used in a redirect router setting like this: |
| 4722 | |
| 4723 | data = ${lookup mysql{ALIAS_QUERY}} |
| 4724 | |
| 4725 | In earlier versions of Exim macros were sometimes used for domain, host, or |
| 4726 | address lists. In Exim 4 these are handled better by named lists - see section |
| 4727 | 10.5. |
| 4728 | |
| 4729 | |
| 4730 | 6.9 Builtin macros |
| 4731 | ------------------ |
| 4732 | |
| 4733 | Exim defines some macros depending on facilities available, which may differ |
| 4734 | due to build-time definitions and from one release to another. All of these |
| 4735 | macros start with an underscore. They can be used to conditionally include |
| 4736 | parts of a configuration (see below). |
| 4737 | |
| 4738 | The following classes of macros are defined: |
| 4739 | |
| 4740 | _HAVE_* build-time defines |
| 4741 | _DRIVER_ROUTER_* router drivers |
| 4742 | _DRIVER_TRANSPORT_* transport drivers |
| 4743 | _DRIVER_AUTHENTICATOR_* authenticator drivers |
| 4744 | _OPT_MAIN_* main config options |
| 4745 | _OPT_ROUTERS_* generic router options |
| 4746 | _OPT_TRANSPORTS_* generic transport options |
| 4747 | _OPT_AUTHENTICATORS_* generic authenticator options |
| 4748 | _OPT_ROUTER_*_* private router options |
| 4749 | _OPT_TRANSPORT_*_* private transport options |
| 4750 | _OPT_AUTHENTICATOR_*_* private authenticator options |
| 4751 | |
| 4752 | Use an "exim -bP macros" command to get the list of macros. |
| 4753 | |
| 4754 | |
| 4755 | 6.10 Conditional skips in the configuration file |
| 4756 | ------------------------------------------------ |
| 4757 | |
| 4758 | You can use the directives ".ifdef", ".ifndef", ".elifdef", ".elifndef", |
| 4759 | ".else", and ".endif" to dynamically include or exclude portions of the |
| 4760 | configuration file. The processing happens whenever the file is read (that is, |
| 4761 | when an Exim binary starts to run). |
| 4762 | |
| 4763 | The implementation is very simple. Instances of the first four directives must |
| 4764 | be followed by text that includes the names of one or macros. The condition |
| 4765 | that is tested is whether or not any macro substitution has taken place in the |
| 4766 | line. Thus: |
| 4767 | |
| 4768 | .ifdef AAA |
| 4769 | message_size_limit = 50M |
| 4770 | .else |
| 4771 | message_size_limit = 100M |
| 4772 | .endif |
| 4773 | |
| 4774 | sets a message size limit of 50M if the macro "AAA" is defined (or "A" or |
| 4775 | "AA"), and 100M otherwise. If there is more than one macro named on the line, |
| 4776 | the condition is true if any of them are defined. That is, it is an "or" |
| 4777 | condition. To obtain an "and" condition, you need to use nested ".ifdef"s. |
| 4778 | |
| 4779 | Although you can use a macro expansion to generate one of these directives, it |
| 4780 | is not very useful, because the condition "there was a macro substitution in |
| 4781 | this line" will always be true. |
| 4782 | |
| 4783 | Text following ".else" and ".endif" is ignored, and can be used as comment to |
| 4784 | clarify complicated nestings. |
| 4785 | |
| 4786 | |
| 4787 | 6.11 Common option syntax |
| 4788 | ------------------------- |
| 4789 | |
| 4790 | For the main set of options, driver options, and local_scan() options, each |
| 4791 | setting is on a line by itself, and starts with a name consisting of lower-case |
| 4792 | letters and underscores. Many options require a data value, and in these cases |
| 4793 | the name must be followed by an equals sign (with optional white space) and |
| 4794 | then the value. For example: |
| 4795 | |
| 4796 | qualify_domain = mydomain.example.com |
| 4797 | |
| 4798 | Some option settings may contain sensitive data, for example, passwords for |
| 4799 | accessing databases. To stop non-admin users from using the -bP command line |
| 4800 | option to read these values, you can precede the option settings with the word |
| 4801 | "hide". For example: |
| 4802 | |
| 4803 | hide mysql_servers = localhost/users/admin/secret-password |
| 4804 | |
| 4805 | For non-admin users, such options are displayed like this: |
| 4806 | |
| 4807 | mysql_servers = <value not displayable> |
| 4808 | |
| 4809 | If "hide" is used on a driver option, it hides the value of that option on all |
| 4810 | instances of the same driver. |
| 4811 | |
| 4812 | The following sections describe the syntax used for the different data types |
| 4813 | that are found in option settings. |
| 4814 | |
| 4815 | |
| 4816 | 6.12 Boolean options |
| 4817 | -------------------- |
| 4818 | |
| 4819 | Options whose type is given as boolean are on/off switches. There are two |
| 4820 | different ways of specifying such options: with and without a data value. If |
| 4821 | the option name is specified on its own without data, the switch is turned on; |
| 4822 | if it is preceded by "no_" or "not_" the switch is turned off. However, boolean |
| 4823 | options may be followed by an equals sign and one of the words "true", "false", |
| 4824 | "yes", or "no", as an alternative syntax. For example, the following two |
| 4825 | settings have exactly the same effect: |
| 4826 | |
| 4827 | queue_only |
| 4828 | queue_only = true |
| 4829 | |
| 4830 | The following two lines also have the same (opposite) effect: |
| 4831 | |
| 4832 | no_queue_only |
| 4833 | queue_only = false |
| 4834 | |
| 4835 | You can use whichever syntax you prefer. |
| 4836 | |
| 4837 | |
| 4838 | 6.13 Integer values |
| 4839 | ------------------- |
| 4840 | |
| 4841 | If an option's type is given as "integer", the value can be given in decimal, |
| 4842 | hexadecimal, or octal. If it starts with a digit greater than zero, a decimal |
| 4843 | number is assumed. Otherwise, it is treated as an octal number unless it starts |
| 4844 | with the characters "0x", in which case the remainder is interpreted as a |
| 4845 | hexadecimal number. |
| 4846 | |
| 4847 | If an integer value is followed by the letter K, it is multiplied by 1024; if |
| 4848 | it is followed by the letter M, it is multiplied by 1024x1024; if by the letter |
| 4849 | G, 1024x1024x1024. When the values of integer option settings are output, |
| 4850 | values which are an exact multiple of 1024 or 1024x1024 are sometimes, but not |
| 4851 | always, printed using the letters K and M. The printing style is independent of |
| 4852 | the actual input format that was used. |
| 4853 | |
| 4854 | |
| 4855 | 6.14 Octal integer values |
| 4856 | ------------------------- |
| 4857 | |
| 4858 | If an option's type is given as "octal integer", its value is always |
| 4859 | interpreted as an octal number, whether or not it starts with the digit zero. |
| 4860 | Such options are always output in octal. |
| 4861 | |
| 4862 | |
| 4863 | 6.15 Fixed point numbers |
| 4864 | ------------------------ |
| 4865 | |
| 4866 | If an option's type is given as "fixed-point", its value must be a decimal |
| 4867 | integer, optionally followed by a decimal point and up to three further digits. |
| 4868 | |
| 4869 | |
| 4870 | 6.16 Time intervals |
| 4871 | ------------------- |
| 4872 | |
| 4873 | A time interval is specified as a sequence of numbers, each followed by one of |
| 4874 | the following letters, with no intervening white space: |
| 4875 | |
| 4876 | s seconds |
| 4877 | m minutes |
| 4878 | h hours |
| 4879 | d days |
| 4880 | w weeks |
| 4881 | |
| 4882 | For example, "3h50m" specifies 3 hours and 50 minutes. The values of time |
| 4883 | intervals are output in the same format. Exim does not restrict the values; it |
| 4884 | is perfectly acceptable, for example, to specify "90m" instead of "1h30m". |
| 4885 | |
| 4886 | |
| 4887 | 6.17 String values |
| 4888 | ------------------ |
| 4889 | |
| 4890 | If an option's type is specified as "string", the value can be specified with |
| 4891 | or without double-quotes. If it does not start with a double-quote, the value |
| 4892 | consists of the remainder of the line plus any continuation lines, starting at |
| 4893 | the first character after any leading white space, with trailing white space |
| 4894 | removed, and with no interpretation of the characters in the string. Because |
| 4895 | Exim removes comment lines (those beginning with #) at an early stage, they can |
| 4896 | appear in the middle of a multi-line string. The following two settings are |
| 4897 | therefore equivalent: |
| 4898 | |
| 4899 | trusted_users = uucp:mail |
| 4900 | trusted_users = uucp:\ |
| 4901 | # This comment line is ignored |
| 4902 | mail |
| 4903 | |
| 4904 | If a string does start with a double-quote, it must end with a closing |
| 4905 | double-quote, and any backslash characters other than those used for line |
| 4906 | continuation are interpreted as escape characters, as follows: |
| 4907 | |
| 4908 | "\\" single backslash |
| 4909 | "\n" newline |
| 4910 | "\r" carriage return |
| 4911 | "\t" tab |
| 4912 | "\"<octal digits> up to 3 octal digits specify one character |
| 4913 | "\x"<hex digits> up to 2 hexadecimal digits specify one character |
| 4914 | |
| 4915 | If a backslash is followed by some other character, including a double-quote |
| 4916 | character, that character replaces the pair. |
| 4917 | |
| 4918 | Quoting is necessary only if you want to make use of the backslash escapes to |
| 4919 | insert special characters, or if you need to specify a value with leading or |
| 4920 | trailing spaces. These cases are rare, so quoting is almost never needed in |
| 4921 | current versions of Exim. In versions of Exim before 3.14, quoting was required |
| 4922 | in order to continue lines, so you may come across older configuration files |
| 4923 | and examples that apparently quote unnecessarily. |
| 4924 | |
| 4925 | |
| 4926 | 6.18 Expanded strings |
| 4927 | --------------------- |
| 4928 | |
| 4929 | Some strings in the configuration file are subjected to string expansion, by |
| 4930 | which means various parts of the string may be changed according to the |
| 4931 | circumstances (see chapter 11). The input syntax for such strings is as just |
| 4932 | described; in particular, the handling of backslashes in quoted strings is done |
| 4933 | as part of the input process, before expansion takes place. However, backslash |
| 4934 | is also an escape character for the expander, so any backslashes that are |
| 4935 | required for that reason must be doubled if they are within a quoted |
| 4936 | configuration string. |
| 4937 | |
| 4938 | |
| 4939 | 6.19 User and group names |
| 4940 | ------------------------- |
| 4941 | |
| 4942 | User and group names are specified as strings, using the syntax described |
| 4943 | above, but the strings are interpreted specially. A user or group name must |
| 4944 | either consist entirely of digits, or be a name that can be looked up using the |
| 4945 | getpwnam() or getgrnam() function, as appropriate. |
| 4946 | |
| 4947 | |
| 4948 | 6.20 List construction |
| 4949 | ---------------------- |
| 4950 | |
| 4951 | The data for some configuration options is a list of items, with colon as the |
| 4952 | default separator. Many of these options are shown with type "string list" in |
| 4953 | the descriptions later in this document. Others are listed as "domain list", |
| 4954 | "host list", "address list", or "local part list". Syntactically, they are all |
| 4955 | the same; however, those other than "string list" are subject to particular |
| 4956 | kinds of interpretation, as described in chapter 10. |
| 4957 | |
| 4958 | In all these cases, the entire list is treated as a single string as far as the |
| 4959 | input syntax is concerned. The trusted_users setting in section 6.17 above is |
| 4960 | an example. If a colon is actually needed in an item in a list, it must be |
| 4961 | entered as two colons. Leading and trailing white space on each item in a list |
| 4962 | is ignored. This makes it possible to include items that start with a colon, |
| 4963 | and in particular, certain forms of IPv6 address. For example, the list |
| 4964 | |
| 4965 | local_interfaces = 127.0.0.1 : ::::1 |
| 4966 | |
| 4967 | contains two IP addresses, the IPv4 address 127.0.0.1 and the IPv6 address ::1. |
| 4968 | |
| 4969 | Note: Although leading and trailing white space is ignored in individual list |
| 4970 | items, it is not ignored when parsing the list. The space after the first colon |
| 4971 | in the example above is necessary. If it were not there, the list would be |
| 4972 | interpreted as the two items 127.0.0.1:: and 1. |
| 4973 | |
| 4974 | |
| 4975 | 6.21 Changing list separators |
| 4976 | ----------------------------- |
| 4977 | |
| 4978 | Doubling colons in IPv6 addresses is an unwelcome chore, so a mechanism was |
| 4979 | introduced to allow the separator character to be changed. If a list begins |
| 4980 | with a left angle bracket, followed by any punctuation character, that |
| 4981 | character is used instead of colon as the list separator. For example, the list |
| 4982 | above can be rewritten to use a semicolon separator like this: |
| 4983 | |
| 4984 | local_interfaces = <; 127.0.0.1 ; ::1 |
| 4985 | |
| 4986 | This facility applies to all lists, with the exception of the list in |
| 4987 | log_file_path. It is recommended that the use of non-colon separators be |
| 4988 | confined to circumstances where they really are needed. |
| 4989 | |
| 4990 | It is also possible to use newline and other control characters (those with |
| 4991 | code values less than 32, plus DEL) as separators in lists. Such separators |
| 4992 | must be provided literally at the time the list is processed. For options that |
| 4993 | are string-expanded, you can write the separator using a normal escape |
| 4994 | sequence. This will be processed by the expander before the string is |
| 4995 | interpreted as a list. For example, if a newline-separated list of domains is |
| 4996 | generated by a lookup, you can process it directly by a line such as this: |
| 4997 | |
| 4998 | domains = <\n ${lookup mysql{.....}} |
| 4999 | |
| 5000 | This avoids having to change the list separator in such data. You are unlikely |
| 5001 | to want to use a control character as a separator in an option that is not |
| 5002 | expanded, because the value is literal text. However, it can be done by giving |
| 5003 | the value in quotes. For example: |
| 5004 | |
| 5005 | local_interfaces = "<\n 127.0.0.1 \n ::1" |
| 5006 | |
| 5007 | Unlike printing character separators, which can be included in list items by |
| 5008 | doubling, it is not possible to include a control character as data when it is |
| 5009 | set as the separator. Two such characters in succession are interpreted as |
| 5010 | enclosing an empty list item. |
| 5011 | |
| 5012 | |
| 5013 | 6.22 Empty items in lists |
| 5014 | ------------------------- |
| 5015 | |
| 5016 | An empty item at the end of a list is always ignored. In other words, trailing |
| 5017 | separator characters are ignored. Thus, the list in |
| 5018 | |
| 5019 | senders = user@domain : |
| 5020 | |
| 5021 | contains only a single item. If you want to include an empty string as one item |
| 5022 | in a list, it must not be the last item. For example, this list contains three |
| 5023 | items, the second of which is empty: |
| 5024 | |
| 5025 | senders = user1@domain : : user2@domain |
| 5026 | |
| 5027 | Note: There must be white space between the two colons, as otherwise they are |
| 5028 | interpreted as representing a single colon data character (and the list would |
| 5029 | then contain just one item). If you want to specify a list that contains just |
| 5030 | one, empty item, you can do it as in this example: |
| 5031 | |
| 5032 | senders = : |
| 5033 | |
| 5034 | In this case, the first item is empty, and the second is discarded because it |
| 5035 | is at the end of the list. |
| 5036 | |
| 5037 | |
| 5038 | 6.23 Format of driver configurations |
| 5039 | ------------------------------------ |
| 5040 | |
| 5041 | There are separate parts in the configuration for defining routers, transports, |
| 5042 | and authenticators. In each part, you are defining a number of driver |
| 5043 | instances, each with its own set of options. Each driver instance is defined by |
| 5044 | a sequence of lines like this: |
| 5045 | |
| 5046 | <instance name>: |
| 5047 | <option> |
| 5048 | ... |
| 5049 | <option> |
| 5050 | |
| 5051 | In the following example, the instance name is localuser, and it is followed by |
| 5052 | three options settings: |
| 5053 | |
| 5054 | localuser: |
| 5055 | driver = accept |
| 5056 | check_local_user |
| 5057 | transport = local_delivery |
| 5058 | |
| 5059 | For each driver instance, you specify which Exim code module it uses - by the |
| 5060 | setting of the driver option - and (optionally) some configuration settings. |
| 5061 | For example, in the case of transports, if you want a transport to deliver with |
| 5062 | SMTP you would use the smtp driver; if you want to deliver to a local file you |
| 5063 | would use the appendfile driver. Each of the drivers is described in detail in |
| 5064 | its own separate chapter later in this manual. |
| 5065 | |
| 5066 | You can have several routers, transports, or authenticators that are based on |
| 5067 | the same underlying driver (each must have a different instance name). |
| 5068 | |
| 5069 | The order in which routers are defined is important, because addresses are |
| 5070 | passed to individual routers one by one, in order. The order in which |
| 5071 | transports are defined does not matter at all. The order in which |
| 5072 | authenticators are defined is used only when Exim, as a client, is searching |
| 5073 | them to find one that matches an authentication mechanism offered by the |
| 5074 | server. |
| 5075 | |
| 5076 | Within a driver instance definition, there are two kinds of option: generic and |
| 5077 | private. The generic options are those that apply to all drivers of the same |
| 5078 | type (that is, all routers, all transports or all authenticators). The driver |
| 5079 | option is a generic option that must appear in every definition. The private |
| 5080 | options are special for each driver, and none need appear, because they all |
| 5081 | have default values. |
| 5082 | |
| 5083 | The options may appear in any order, except that the driver option must precede |
| 5084 | any private options, since these depend on the particular driver. For this |
| 5085 | reason, it is recommended that driver always be the first option. |
| 5086 | |
| 5087 | Driver instance names, which are used for reference in log entries and |
| 5088 | elsewhere, can be any sequence of letters, digits, and underscores (starting |
| 5089 | with a letter) and must be unique among drivers of the same type. A router and |
| 5090 | a transport (for example) can each have the same name, but no two router |
| 5091 | instances can have the same name. The name of a driver instance should not be |
| 5092 | confused with the name of the underlying driver module. For example, the |
| 5093 | configuration lines: |
| 5094 | |
| 5095 | remote_smtp: |
| 5096 | driver = smtp |
| 5097 | |
| 5098 | create an instance of the smtp transport driver whose name is remote_smtp. The |
| 5099 | same driver code can be used more than once, with different instance names and |
| 5100 | different option settings each time. A second instance of the smtp transport, |
| 5101 | with different options, might be defined thus: |
| 5102 | |
| 5103 | special_smtp: |
| 5104 | driver = smtp |
| 5105 | port = 1234 |
| 5106 | command_timeout = 10s |
| 5107 | |
| 5108 | The names remote_smtp and special_smtp would be used to reference these |
| 5109 | transport instances from routers, and these names would appear in log lines. |
| 5110 | |
| 5111 | Comment lines may be present in the middle of driver specifications. The full |
| 5112 | list of option settings for any particular driver instance, including all the |
| 5113 | defaulted values, can be extracted by making use of the -bP command line |
| 5114 | option. |
| 5115 | |
| 5116 | |
| 5117 | |
| 5118 | =============================================================================== |
| 5119 | 7. THE DEFAULT CONFIGURATION FILE |
| 5120 | |
| 5121 | The default configuration file supplied with Exim as src/configure.default is |
| 5122 | sufficient for a host with simple mail requirements. As an introduction to the |
| 5123 | way Exim is configured, this chapter "walks through" the default configuration, |
| 5124 | giving brief explanations of the settings. Detailed descriptions of the options |
| 5125 | are given in subsequent chapters. The default configuration file itself |
| 5126 | contains extensive comments about ways you might want to modify the initial |
| 5127 | settings. However, note that there are many options that are not mentioned at |
| 5128 | all in the default configuration. |
| 5129 | |
| 5130 | |
| 5131 | 7.1 Main configuration settings |
| 5132 | ------------------------------- |
| 5133 | |
| 5134 | The main (global) configuration option settings must always come first in the |
| 5135 | file. The first thing you'll see in the file, after some initial comments, is |
| 5136 | the line |
| 5137 | |
| 5138 | # primary_hostname = |
| 5139 | |
| 5140 | This is a commented-out setting of the primary_hostname option. Exim needs to |
| 5141 | know the official, fully qualified name of your host, and this is where you can |
| 5142 | specify it. However, in most cases you do not need to set this option. When it |
| 5143 | is unset, Exim uses the uname() system function to obtain the host name. |
| 5144 | |
| 5145 | The first three non-comment configuration lines are as follows: |
| 5146 | |
| 5147 | domainlist local_domains = @ |
| 5148 | domainlist relay_to_domains = |
| 5149 | hostlist relay_from_hosts = 127.0.0.1 |
| 5150 | |
| 5151 | These are not, in fact, option settings. They are definitions of two named |
| 5152 | domain lists and one named host list. Exim allows you to give names to lists of |
| 5153 | domains, hosts, and email addresses, in order to make it easier to manage the |
| 5154 | configuration file (see section 10.5). |
| 5155 | |
| 5156 | The first line defines a domain list called local_domains; this is used later |
| 5157 | in the configuration to identify domains that are to be delivered on the local |
| 5158 | host. |
| 5159 | |
| 5160 | There is just one item in this list, the string "@". This is a special form of |
| 5161 | entry which means "the name of the local host". Thus, if the local host is |
| 5162 | called a.host.example, mail to any.user@a.host.example is expected to be |
| 5163 | delivered locally. Because the local host's name is referenced indirectly, the |
| 5164 | same configuration file can be used on different hosts. |
| 5165 | |
| 5166 | The second line defines a domain list called relay_to_domains, but the list |
| 5167 | itself is empty. Later in the configuration we will come to the part that |
| 5168 | controls mail relaying through the local host; it allows relaying to any |
| 5169 | domains in this list. By default, therefore, no relaying on the basis of a mail |
| 5170 | domain is permitted. |
| 5171 | |
| 5172 | The third line defines a host list called relay_from_hosts. This list is used |
| 5173 | later in the configuration to permit relaying from any host or IP address that |
| 5174 | matches the list. The default contains just the IP address of the IPv4 loopback |
| 5175 | interface, which means that processes on the local host are able to submit mail |
| 5176 | for relaying by sending it over TCP/IP to that interface. No other hosts are |
| 5177 | permitted to submit messages for relaying. |
| 5178 | |
| 5179 | Just to be sure there's no misunderstanding: at this point in the configuration |
| 5180 | we aren't actually setting up any controls. We are just defining some domains |
| 5181 | and hosts that will be used in the controls that are specified later. |
| 5182 | |
| 5183 | The next two configuration lines are genuine option settings: |
| 5184 | |
| 5185 | acl_smtp_rcpt = acl_check_rcpt |
| 5186 | acl_smtp_data = acl_check_data |
| 5187 | |
| 5188 | These options specify Access Control Lists (ACLs) that are to be used during an |
| 5189 | incoming SMTP session for every recipient of a message (every RCPT command), |
| 5190 | and after the contents of the message have been received, respectively. The |
| 5191 | names of the lists are acl_check_rcpt and acl_check_data, and we will come to |
| 5192 | their definitions below, in the ACL section of the configuration. The RCPT ACL |
| 5193 | controls which recipients are accepted for an incoming message - if a |
| 5194 | configuration does not provide an ACL to check recipients, no SMTP mail can be |
| 5195 | accepted. The DATA ACL allows the contents of a message to be checked. |
| 5196 | |
| 5197 | Two commented-out option settings are next: |
| 5198 | |
| 5199 | # av_scanner = clamd:/tmp/clamd |
| 5200 | # spamd_address = 127.0.0.1 783 |
| 5201 | |
| 5202 | These are example settings that can be used when Exim is compiled with the |
| 5203 | content-scanning extension. The first specifies the interface to the virus |
| 5204 | scanner, and the second specifies the interface to SpamAssassin. Further |
| 5205 | details are given in chapter 44. |
| 5206 | |
| 5207 | Three more commented-out option settings follow: |
| 5208 | |
| 5209 | # tls_advertise_hosts = * |
| 5210 | # tls_certificate = /etc/ssl/exim.crt |
| 5211 | # tls_privatekey = /etc/ssl/exim.pem |
| 5212 | |
| 5213 | These are example settings that can be used when Exim is compiled with support |
| 5214 | for TLS (aka SSL) as described in section 4.7. The first one specifies the list |
| 5215 | of clients that are allowed to use TLS when connecting to this server; in this |
| 5216 | case the wildcard means all clients. The other options specify where Exim |
| 5217 | should find its TLS certificate and private key, which together prove the |
| 5218 | server's identity to any clients that connect. More details are given in |
| 5219 | chapter 42. |
| 5220 | |
| 5221 | Another two commented-out option settings follow: |
| 5222 | |
| 5223 | # daemon_smtp_ports = 25 : 465 : 587 |
| 5224 | # tls_on_connect_ports = 465 |
| 5225 | |
| 5226 | These options provide better support for roaming users who wish to use this |
| 5227 | server for message submission. They are not much use unless you have turned on |
| 5228 | TLS (as described in the previous paragraph) and authentication (about which |
| 5229 | more in section 7.7). The usual SMTP port 25 is often blocked on end-user |
| 5230 | networks, so RFC 4409 specifies that message submission should use port 587 |
| 5231 | instead. However some software (notably Microsoft Outlook) cannot be configured |
| 5232 | to use port 587 correctly, so these settings also enable the non-standard |
| 5233 | "smtps" (aka "ssmtp") port 465 (see section 13.4). |
| 5234 | |
| 5235 | Two more commented-out options settings follow: |
| 5236 | |
| 5237 | # qualify_domain = |
| 5238 | # qualify_recipient = |
| 5239 | |
| 5240 | The first of these specifies a domain that Exim uses when it constructs a |
| 5241 | complete email address from a local login name. This is often needed when Exim |
| 5242 | receives a message from a local process. If you do not set qualify_domain, the |
| 5243 | value of primary_hostname is used. If you set both of these options, you can |
| 5244 | have different qualification domains for sender and recipient addresses. If you |
| 5245 | set only the first one, its value is used in both cases. |
| 5246 | |
| 5247 | The following line must be uncommented if you want Exim to recognize addresses |
| 5248 | of the form user@[10.11.12.13] that is, with a "domain literal" (an IP address |
| 5249 | within square brackets) instead of a named domain. |
| 5250 | |
| 5251 | # allow_domain_literals |
| 5252 | |
| 5253 | The RFCs still require this form, but many people think that in the modern |
| 5254 | Internet it makes little sense to permit mail to be sent to specific hosts by |
| 5255 | quoting their IP addresses. This ancient format has been used by people who try |
| 5256 | to abuse hosts by using them for unwanted relaying. However, some people |
| 5257 | believe there are circumstances (for example, messages addressed to postmaster) |
| 5258 | where domain literals are still useful. |
| 5259 | |
| 5260 | The next configuration line is a kind of trigger guard: |
| 5261 | |
| 5262 | never_users = root |
| 5263 | |
| 5264 | It specifies that no delivery must ever be run as the root user. The normal |
| 5265 | convention is to set up root as an alias for the system administrator. This |
| 5266 | setting is a guard against slips in the configuration. The list of users |
| 5267 | specified by never_users is not, however, the complete list; the build-time |
| 5268 | configuration in Local/Makefile has an option called FIXED_NEVER_USERS |
| 5269 | specifying a list that cannot be overridden. The contents of never_users are |
| 5270 | added to this list. By default FIXED_NEVER_USERS also specifies root. |
| 5271 | |
| 5272 | When a remote host connects to Exim in order to send mail, the only information |
| 5273 | Exim has about the host's identity is its IP address. The next configuration |
| 5274 | line, |
| 5275 | |
| 5276 | host_lookup = * |
| 5277 | |
| 5278 | specifies that Exim should do a reverse DNS lookup on all incoming connections, |
| 5279 | in order to get a host name. This improves the quality of the logging |
| 5280 | information, but if you feel it is too expensive, you can remove it entirely, |
| 5281 | or restrict the lookup to hosts on "nearby" networks. Note that it is not |
| 5282 | always possible to find a host name from an IP address, because not all DNS |
| 5283 | reverse zones are maintained, and sometimes DNS servers are unreachable. |
| 5284 | |
| 5285 | The next two lines are concerned with ident callbacks, as defined by RFC 1413 |
| 5286 | (hence their names): |
| 5287 | |
| 5288 | rfc1413_hosts = * |
| 5289 | rfc1413_query_timeout = 0s |
| 5290 | |
| 5291 | These settings cause Exim to avoid ident callbacks for all incoming SMTP calls. |
| 5292 | Few hosts offer RFC1413 service these days; calls have to be terminated by a |
| 5293 | timeout and this needlessly delays the startup of an incoming SMTP connection. |
| 5294 | If you have hosts for which you trust RFC1413 and need this information, you |
| 5295 | can change this. |
| 5296 | |
| 5297 | This line enables an efficiency SMTP option. It is negotiated by clients and |
| 5298 | not expected to cause problems but can be disabled if needed. |
| 5299 | |
| 5300 | prdr_enable = true |
| 5301 | |
| 5302 | When Exim receives messages over SMTP connections, it expects all addresses to |
| 5303 | be fully qualified with a domain, as required by the SMTP definition. However, |
| 5304 | if you are running a server to which simple clients submit messages, you may |
| 5305 | find that they send unqualified addresses. The two commented-out options: |
| 5306 | |
| 5307 | # sender_unqualified_hosts = |
| 5308 | # recipient_unqualified_hosts = |
| 5309 | |
| 5310 | show how you can specify hosts that are permitted to send unqualified sender |
| 5311 | and recipient addresses, respectively. |
| 5312 | |
| 5313 | The log_selector option is used to increase the detail of logging over the |
| 5314 | default: |
| 5315 | |
| 5316 | log_selector = +smtp_protocol_error +smtp_syntax_error \ |
| 5317 | +tls_certificate_verified |
| 5318 | |
| 5319 | The percent_hack_domains option is also commented out: |
| 5320 | |
| 5321 | # percent_hack_domains = |
| 5322 | |
| 5323 | It provides a list of domains for which the "percent hack" is to operate. This |
| 5324 | is an almost obsolete form of explicit email routing. If you do not know |
| 5325 | anything about it, you can safely ignore this topic. |
| 5326 | |
| 5327 | The next two settings in the main part of the default configuration are |
| 5328 | concerned with messages that have been "frozen" on Exim's queue. When a message |
| 5329 | is frozen, Exim no longer continues to try to deliver it. Freezing occurs when |
| 5330 | a bounce message encounters a permanent failure because the sender address of |
| 5331 | the original message that caused the bounce is invalid, so the bounce cannot be |
| 5332 | delivered. This is probably the most common case, but there are also other |
| 5333 | conditions that cause freezing, and frozen messages are not always bounce |
| 5334 | messages. |
| 5335 | |
| 5336 | ignore_bounce_errors_after = 2d |
| 5337 | timeout_frozen_after = 7d |
| 5338 | |
| 5339 | The first of these options specifies that failing bounce messages are to be |
| 5340 | discarded after 2 days on the queue. The second specifies that any frozen |
| 5341 | message (whether a bounce message or not) is to be timed out (and discarded) |
| 5342 | after a week. In this configuration, the first setting ensures that no failing |
| 5343 | bounce message ever lasts a week. |
| 5344 | |
| 5345 | Exim queues it's messages in a spool directory. If you expect to have large |
| 5346 | queues, you may consider using this option. It splits the spool directory into |
| 5347 | subdirectories to avoid file system degradation from many files in a single |
| 5348 | directory, resulting in better performance. Manual manipulation of queued |
| 5349 | messages becomes more complex (though fortunately not often needed). |
| 5350 | |
| 5351 | # split_spool_directory = true |
| 5352 | |
| 5353 | In an ideal world everybody follows the standards. For non-ASCII messages RFC |
| 5354 | 2047 is a standard, allowing a maximum line length of 76 characters. Exim |
| 5355 | adheres that standard and won't process messages which violate this standard. |
| 5356 | (Even ${rfc2047:...} expansions will fail.) In particular, the Exim maintainers |
| 5357 | have had multiple reports of problems from Russian administrators of issues |
| 5358 | until they disable this check, because of some popular, yet buggy, mail |
| 5359 | composition software. |
| 5360 | |
| 5361 | # check_rfc2047_length = false |
| 5362 | |
| 5363 | If you need to be strictly RFC compliant you may wish to disable the 8BITMIME |
| 5364 | advertisement. Use this, if you exchange mails with systems that are not 8-bit |
| 5365 | clean. |
| 5366 | |
| 5367 | # accept_8bitmime = false |
| 5368 | |
| 5369 | Libraries you use may depend on specific environment settings. This imposes a |
| 5370 | security risk (e.g. PATH). There are two lists: keep_environment for the |
| 5371 | variables to import as they are, and add_environment for variables we want to |
| 5372 | set to a fixed value. Note that TZ is handled separately, by the $%timezone%$ |
| 5373 | runtime option and by the TIMEZONE_DEFAULT buildtime option. |
| 5374 | |
| 5375 | # keep_environment = ^LDAP |
| 5376 | # add_environment = PATH=/usr/bin::/bin |
| 5377 | |
| 5378 | |
| 5379 | 7.2 ACL configuration |
| 5380 | --------------------- |
| 5381 | |
| 5382 | In the default configuration, the ACL section follows the main configuration. |
| 5383 | It starts with the line |
| 5384 | |
| 5385 | begin acl |
| 5386 | |
| 5387 | and it contains the definitions of two ACLs, called acl_check_rcpt and |
| 5388 | acl_check_data, that were referenced in the settings of acl_smtp_rcpt and |
| 5389 | acl_smtp_data above. |
| 5390 | |
| 5391 | The first ACL is used for every RCPT command in an incoming SMTP message. Each |
| 5392 | RCPT command specifies one of the message's recipients. The ACL statements are |
| 5393 | considered in order, until the recipient address is either accepted or |
| 5394 | rejected. The RCPT command is then accepted or rejected, according to the |
| 5395 | result of the ACL processing. |
| 5396 | |
| 5397 | acl_check_rcpt: |
| 5398 | |
| 5399 | This line, consisting of a name terminated by a colon, marks the start of the |
| 5400 | ACL, and names it. |
| 5401 | |
| 5402 | accept hosts = : |
| 5403 | |
| 5404 | This ACL statement accepts the recipient if the sending host matches the list. |
| 5405 | But what does that strange list mean? It doesn't actually contain any host |
| 5406 | names or IP addresses. The presence of the colon puts an empty item in the |
| 5407 | list; Exim matches this only if the incoming message did not come from a remote |
| 5408 | host, because in that case, the remote hostname is empty. The colon is |
| 5409 | important. Without it, the list itself is empty, and can never match anything. |
| 5410 | |
| 5411 | What this statement is doing is to accept unconditionally all recipients in |
| 5412 | messages that are submitted by SMTP from local processes using the standard |
| 5413 | input and output (that is, not using TCP/IP). A number of MUAs operate in this |
| 5414 | manner. |
| 5415 | |
| 5416 | deny message = Restricted characters in address |
| 5417 | domains = +local_domains |
| 5418 | local_parts = ^[.] : ^.*[@%!/|] |
| 5419 | |
| 5420 | deny message = Restricted characters in address |
| 5421 | domains = !+local_domains |
| 5422 | local_parts = ^[./|] : ^.*[@%!] : ^.*/\\.\\./ |
| 5423 | |
| 5424 | These statements are concerned with local parts that contain any of the |
| 5425 | characters "@", "%", "!", "/", "|", or dots in unusual places. Although these |
| 5426 | characters are entirely legal in local parts (in the case of "@" and leading |
| 5427 | dots, only if correctly quoted), they do not commonly occur in Internet mail |
| 5428 | addresses. |
| 5429 | |
| 5430 | The first three have in the past been associated with explicitly routed |
| 5431 | addresses (percent is still sometimes used - see the percent_hack_domains |
| 5432 | option). Addresses containing these characters are regularly tried by spammers |
| 5433 | in an attempt to bypass relaying restrictions, and also by open relay testing |
| 5434 | programs. Unless you really need them it is safest to reject these characters |
| 5435 | at this early stage. This configuration is heavy-handed in rejecting these |
| 5436 | characters for all messages it accepts from remote hosts. This is a deliberate |
| 5437 | policy of being as safe as possible. |
| 5438 | |
| 5439 | The first rule above is stricter, and is applied to messages that are addressed |
| 5440 | to one of the local domains handled by this host. This is implemented by the |
| 5441 | first condition, which restricts it to domains that are listed in the |
| 5442 | local_domains domain list. The "+" character is used to indicate a reference to |
| 5443 | a named list. In this configuration, there is just one domain in local_domains, |
| 5444 | but in general there may be many. |
| 5445 | |
| 5446 | The second condition on the first statement uses two regular expressions to |
| 5447 | block local parts that begin with a dot or contain "@", "%", "!", "/", or "|". |
| 5448 | If you have local accounts that include these characters, you will have to |
| 5449 | modify this rule. |
| 5450 | |
| 5451 | Empty components (two dots in a row) are not valid in RFC 2822, but Exim allows |
| 5452 | them because they have been encountered in practice. (Consider the common |
| 5453 | convention of local parts constructed as " |
| 5454 | first-initial.second-initial.family-name" when applied to someone like the |
| 5455 | author of Exim, who has no second initial.) However, a local part starting with |
| 5456 | a dot or containing "/../" can cause trouble if it is used as part of a file |
| 5457 | name (for example, for a mailing list). This is also true for local parts that |
| 5458 | contain slashes. A pipe symbol can also be troublesome if the local part is |
| 5459 | incorporated unthinkingly into a shell command line. |
| 5460 | |
| 5461 | The second rule above applies to all other domains, and is less strict. This |
| 5462 | allows your own users to send outgoing messages to sites that use slashes and |
| 5463 | vertical bars in their local parts. It blocks local parts that begin with a |
| 5464 | dot, slash, or vertical bar, but allows these characters within the local part. |
| 5465 | However, the sequence "/../" is barred. The use of "@", "%", and "!" is |
| 5466 | blocked, as before. The motivation here is to prevent your users (or your |
| 5467 | users' viruses) from mounting certain kinds of attack on remote sites. |
| 5468 | |
| 5469 | accept local_parts = postmaster |
| 5470 | domains = +local_domains |
| 5471 | |
| 5472 | This statement, which has two conditions, accepts an incoming address if the |
| 5473 | local part is postmaster and the domain is one of those listed in the |
| 5474 | local_domains domain list. The "+" character is used to indicate a reference to |
| 5475 | a named list. In this configuration, there is just one domain in local_domains, |
| 5476 | but in general there may be many. |
| 5477 | |
| 5478 | The presence of this statement means that mail to postmaster is never blocked |
| 5479 | by any of the subsequent tests. This can be helpful while sorting out problems |
| 5480 | in cases where the subsequent tests are incorrectly denying access. |
| 5481 | |
| 5482 | require verify = sender |
| 5483 | |
| 5484 | This statement requires the sender address to be verified before any subsequent |
| 5485 | ACL statement can be used. If verification fails, the incoming recipient |
| 5486 | address is refused. Verification consists of trying to route the address, to |
| 5487 | see if a bounce message could be delivered to it. In the case of remote |
| 5488 | addresses, basic verification checks only the domain, but callouts can be used |
| 5489 | for more verification if required. Section 43.44 discusses the details of |
| 5490 | address verification. |
| 5491 | |
| 5492 | accept hosts = +relay_from_hosts |
| 5493 | control = submission |
| 5494 | |
| 5495 | This statement accepts the address if the message is coming from one of the |
| 5496 | hosts that are defined as being allowed to relay through this host. Recipient |
| 5497 | verification is omitted here, because in many cases the clients are dumb MUAs |
| 5498 | that do not cope well with SMTP error responses. For the same reason, the |
| 5499 | second line specifies "submission mode" for messages that are accepted. This is |
| 5500 | described in detail in section 47.1; it causes Exim to fix messages that are |
| 5501 | deficient in some way, for example, because they lack a Date: header line. If |
| 5502 | you are actually relaying out from MTAs, you should probably add recipient |
| 5503 | verification here, and disable submission mode. |
| 5504 | |
| 5505 | accept authenticated = * |
| 5506 | control = submission |
| 5507 | |
| 5508 | This statement accepts the address if the client host has authenticated itself. |
| 5509 | Submission mode is again specified, on the grounds that such messages are most |
| 5510 | likely to come from MUAs. The default configuration does not define any |
| 5511 | authenticators, though it does include some nearly complete commented-out |
| 5512 | examples described in 7.7. This means that no client can in fact authenticate |
| 5513 | until you complete the authenticator definitions. |
| 5514 | |
| 5515 | require message = relay not permitted |
| 5516 | domains = +local_domains : +relay_to_domains |
| 5517 | |
| 5518 | This statement rejects the address if its domain is neither a local domain nor |
| 5519 | one of the domains for which this host is a relay. |
| 5520 | |
| 5521 | require verify = recipient |
| 5522 | |
| 5523 | This statement requires the recipient address to be verified; if verification |
| 5524 | fails, the address is rejected. |
| 5525 | |
| 5526 | # deny message = rejected because $sender_host_address \ |
| 5527 | # is in a black list at $dnslist_domain\n\ |
| 5528 | # $dnslist_text |
| 5529 | # dnslists = black.list.example |
| 5530 | # |
| 5531 | # warn dnslists = black.list.example |
| 5532 | # add_header = X-Warning: $sender_host_address is in \ |
| 5533 | # a black list at $dnslist_domain |
| 5534 | # log_message = found in $dnslist_domain |
| 5535 | |
| 5536 | These commented-out lines are examples of how you could configure Exim to check |
| 5537 | sending hosts against a DNS black list. The first statement rejects messages |
| 5538 | from blacklisted hosts, whereas the second just inserts a warning header line. |
| 5539 | |
| 5540 | # require verify = csa |
| 5541 | |
| 5542 | This commented-out line is an example of how you could turn on client SMTP |
| 5543 | authorization (CSA) checking. Such checks do DNS lookups for special SRV |
| 5544 | records. |
| 5545 | |
| 5546 | accept |
| 5547 | |
| 5548 | The final statement in the first ACL unconditionally accepts any recipient |
| 5549 | address that has successfully passed all the previous tests. |
| 5550 | |
| 5551 | acl_check_data: |
| 5552 | |
| 5553 | This line marks the start of the second ACL, and names it. Most of the contents |
| 5554 | of this ACL are commented out: |
| 5555 | |
| 5556 | # deny malware = * |
| 5557 | # message = This message contains a virus \ |
| 5558 | # ($malware_name). |
| 5559 | |
| 5560 | These lines are examples of how to arrange for messages to be scanned for |
| 5561 | viruses when Exim has been compiled with the content-scanning extension, and a |
| 5562 | suitable virus scanner is installed. If the message is found to contain a |
| 5563 | virus, it is rejected with the given custom error message. |
| 5564 | |
| 5565 | # warn spam = nobody |
| 5566 | # message = X-Spam_score: $spam_score\n\ |
| 5567 | # X-Spam_score_int: $spam_score_int\n\ |
| 5568 | # X-Spam_bar: $spam_bar\n\ |
| 5569 | # X-Spam_report: $spam_report |
| 5570 | |
| 5571 | These lines are an example of how to arrange for messages to be scanned by |
| 5572 | SpamAssassin when Exim has been compiled with the content-scanning extension, |
| 5573 | and SpamAssassin has been installed. The SpamAssassin check is run with |
| 5574 | "nobody" as its user parameter, and the results are added to the message as a |
| 5575 | series of extra header line. In this case, the message is not rejected, |
| 5576 | whatever the spam score. |
| 5577 | |
| 5578 | accept |
| 5579 | |
| 5580 | This final line in the DATA ACL accepts the message unconditionally. |
| 5581 | |
| 5582 | |
| 5583 | 7.3 Router configuration |
| 5584 | ------------------------ |
| 5585 | |
| 5586 | The router configuration comes next in the default configuration, introduced by |
| 5587 | the line |
| 5588 | |
| 5589 | begin routers |
| 5590 | |
| 5591 | Routers are the modules in Exim that make decisions about where to send |
| 5592 | messages. An address is passed to each router in turn, until it is either |
| 5593 | accepted, or failed. This means that the order in which you define the routers |
| 5594 | matters. Each router is fully described in its own chapter later in this |
| 5595 | manual. Here we give only brief overviews. |
| 5596 | |
| 5597 | # domain_literal: |
| 5598 | # driver = ipliteral |
| 5599 | # domains = !+local_domains |
| 5600 | # transport = remote_smtp |
| 5601 | |
| 5602 | This router is commented out because the majority of sites do not want to |
| 5603 | support domain literal addresses (those of the form user@[10.9.8.7]). If you |
| 5604 | uncomment this router, you also need to uncomment the setting of |
| 5605 | allow_domain_literals in the main part of the configuration. |
| 5606 | |
| 5607 | dnslookup: |
| 5608 | driver = dnslookup |
| 5609 | domains = ! +local_domains |
| 5610 | transport = remote_smtp |
| 5611 | ignore_target_hosts = 0.0.0.0 : 127.0.0.0/8 |
| 5612 | no_more |
| 5613 | |
| 5614 | The first uncommented router handles addresses that do not involve any local |
| 5615 | domains. This is specified by the line |
| 5616 | |
| 5617 | domains = ! +local_domains |
| 5618 | |
| 5619 | The domains option lists the domains to which this router applies, but the |
| 5620 | exclamation mark is a negation sign, so the router is used only for domains |
| 5621 | that are not in the domain list called local_domains (which was defined at the |
| 5622 | start of the configuration). The plus sign before local_domains indicates that |
| 5623 | it is referring to a named list. Addresses in other domains are passed on to |
| 5624 | the following routers. |
| 5625 | |
| 5626 | The name of the router driver is dnslookup, and is specified by the driver |
| 5627 | option. Do not be confused by the fact that the name of this router instance is |
| 5628 | the same as the name of the driver. The instance name is arbitrary, but the |
| 5629 | name set in the driver option must be one of the driver modules that is in the |
| 5630 | Exim binary. |
| 5631 | |
| 5632 | The dnslookup router routes addresses by looking up their domains in the DNS in |
| 5633 | order to obtain a list of hosts to which the address is routed. If the router |
| 5634 | succeeds, the address is queued for the remote_smtp transport, as specified by |
| 5635 | the transport option. If the router does not find the domain in the DNS, no |
| 5636 | further routers are tried because of the no_more setting, so the address fails |
| 5637 | and is bounced. |
| 5638 | |
| 5639 | The ignore_target_hosts option specifies a list of IP addresses that are to be |
| 5640 | entirely ignored. This option is present because a number of cases have been |
| 5641 | encountered where MX records in the DNS point to host names whose IP addresses |
| 5642 | are 0.0.0.0 or are in the 127 subnet (typically 127.0.0.1). Completely ignoring |
| 5643 | these IP addresses causes Exim to fail to route the email address, so it |
| 5644 | bounces. Otherwise, Exim would log a routing problem, and continue to try to |
| 5645 | deliver the message periodically until the address timed out. |
| 5646 | |
| 5647 | system_aliases: |
| 5648 | driver = redirect |
| 5649 | allow_fail |
| 5650 | allow_defer |
| 5651 | data = ${lookup{$local_part}lsearch{/etc/aliases}} |
| 5652 | # user = exim |
| 5653 | file_transport = address_file |
| 5654 | pipe_transport = address_pipe |
| 5655 | |
| 5656 | Control reaches this and subsequent routers only for addresses in the local |
| 5657 | domains. This router checks to see whether the local part is defined as an |
| 5658 | alias in the /etc/aliases file, and if so, redirects it according to the data |
| 5659 | that it looks up from that file. If no data is found for the local part, the |
| 5660 | value of the data option is empty, causing the address to be passed to the next |
| 5661 | router. |
| 5662 | |
| 5663 | /etc/aliases is a conventional name for the system aliases file that is often |
| 5664 | used. That is why it is referenced by from the default configuration file. |
| 5665 | However, you can change this by setting SYSTEM_ALIASES_FILE in Local/Makefile |
| 5666 | before building Exim. |
| 5667 | |
| 5668 | userforward: |
| 5669 | driver = redirect |
| 5670 | check_local_user |
| 5671 | # local_part_suffix = +* : -* |
| 5672 | # local_part_suffix_optional |
| 5673 | file = $home/.forward |
| 5674 | # allow_filter |
| 5675 | no_verify |
| 5676 | no_expn |
| 5677 | check_ancestor |
| 5678 | file_transport = address_file |
| 5679 | pipe_transport = address_pipe |
| 5680 | reply_transport = address_reply |
| 5681 | |
| 5682 | This is the most complicated router in the default configuration. It is another |
| 5683 | redirection router, but this time it is looking for forwarding data set up by |
| 5684 | individual users. The check_local_user setting specifies a check that the local |
| 5685 | part of the address is the login name of a local user. If it is not, the router |
| 5686 | is skipped. The two commented options that follow check_local_user, namely: |
| 5687 | |
| 5688 | # local_part_suffix = +* : -* |
| 5689 | # local_part_suffix_optional |
| 5690 | |
| 5691 | show how you can specify the recognition of local part suffixes. If the first |
| 5692 | is uncommented, a suffix beginning with either a plus or a minus sign, followed |
| 5693 | by any sequence of characters, is removed from the local part and placed in the |
| 5694 | variable $local_part_suffix. The second suffix option specifies that the |
| 5695 | presence of a suffix in the local part is optional. When a suffix is present, |
| 5696 | the check for a local login uses the local part with the suffix removed. |
| 5697 | |
| 5698 | When a local user account is found, the file called .forward in the user's home |
| 5699 | directory is consulted. If it does not exist, or is empty, the router declines. |
| 5700 | Otherwise, the contents of .forward are interpreted as redirection data (see |
| 5701 | chapter 22 for more details). |
| 5702 | |
| 5703 | Traditional .forward files contain just a list of addresses, pipes, or files. |
| 5704 | Exim supports this by default. However, if allow_filter is set (it is commented |
| 5705 | out by default), the contents of the file are interpreted as a set of Exim or |
| 5706 | Sieve filtering instructions, provided the file begins with "#Exim filter" or " |
| 5707 | #Sieve filter", respectively. User filtering is discussed in the separate |
| 5708 | document entitled Exim's interfaces to mail filtering. |
| 5709 | |
| 5710 | The no_verify and no_expn options mean that this router is skipped when |
| 5711 | verifying addresses, or when running as a consequence of an SMTP EXPN command. |
| 5712 | There are two reasons for doing this: |
| 5713 | |
| 5714 | 1. Whether or not a local user has a .forward file is not really relevant when |
| 5715 | checking an address for validity; it makes sense not to waste resources |
| 5716 | doing unnecessary work. |
| 5717 | |
| 5718 | 2. More importantly, when Exim is verifying addresses or handling an EXPN |
| 5719 | command during an SMTP session, it is running as the Exim user, not as |
| 5720 | root. The group is the Exim group, and no additional groups are set up. It |
| 5721 | may therefore not be possible for Exim to read users' .forward files at |
| 5722 | this time. |
| 5723 | |
| 5724 | The setting of check_ancestor prevents the router from generating a new address |
| 5725 | that is the same as any previous address that was redirected. (This works round |
| 5726 | a problem concerning a bad interaction between aliasing and forwarding - see |
| 5727 | section 22.5). |
| 5728 | |
| 5729 | The final three option settings specify the transports that are to be used when |
| 5730 | forwarding generates a direct delivery to a file, or to a pipe, or sets up an |
| 5731 | auto-reply, respectively. For example, if a .forward file contains |
| 5732 | |
| 5733 | a.nother@elsewhere.example, /home/spqr/archive |
| 5734 | |
| 5735 | the delivery to /home/spqr/archive is done by running the address_file |
| 5736 | transport. |
| 5737 | |
| 5738 | localuser: |
| 5739 | driver = accept |
| 5740 | check_local_user |
| 5741 | # local_part_suffix = +* : -* |
| 5742 | # local_part_suffix_optional |
| 5743 | transport = local_delivery |
| 5744 | |
| 5745 | The final router sets up delivery into local mailboxes, provided that the local |
| 5746 | part is the name of a local login, by accepting the address and assigning it to |
| 5747 | the local_delivery transport. Otherwise, we have reached the end of the |
| 5748 | routers, so the address is bounced. The commented suffix settings fulfil the |
| 5749 | same purpose as they do for the userforward router. |
| 5750 | |
| 5751 | |
| 5752 | 7.4 Transport configuration |
| 5753 | --------------------------- |
| 5754 | |
| 5755 | Transports define mechanisms for actually delivering messages. They operate |
| 5756 | only when referenced from routers, so the order in which they are defined does |
| 5757 | not matter. The transports section of the configuration starts with |
| 5758 | |
| 5759 | begin transports |
| 5760 | |
| 5761 | One remote transport and four local transports are defined. |
| 5762 | |
| 5763 | remote_smtp: |
| 5764 | driver = smtp |
| 5765 | hosts_try_prdr = * |
| 5766 | |
| 5767 | This transport is used for delivering messages over SMTP connections. The list |
| 5768 | of remote hosts comes from the router. The hosts_try_prdr option enables an |
| 5769 | efficiency SMTP option. It is negotiated between client and server and not |
| 5770 | expected to cause problems but can be disabled if needed. All other options are |
| 5771 | defaulted. |
| 5772 | |
| 5773 | local_delivery: |
| 5774 | driver = appendfile |
| 5775 | file = /var/mail/$local_part |
| 5776 | delivery_date_add |
| 5777 | envelope_to_add |
| 5778 | return_path_add |
| 5779 | # group = mail |
| 5780 | # mode = 0660 |
| 5781 | |
| 5782 | This appendfile transport is used for local delivery to user mailboxes in |
| 5783 | traditional BSD mailbox format. By default it runs under the uid and gid of the |
| 5784 | local user, which requires the sticky bit to be set on the /var/mail directory. |
| 5785 | Some systems use the alternative approach of running mail deliveries under a |
| 5786 | particular group instead of using the sticky bit. The commented options show |
| 5787 | how this can be done. |
| 5788 | |
| 5789 | Exim adds three headers to the message as it delivers it: Delivery-date:, |
| 5790 | Envelope-to: and Return-path:. This action is requested by the three |
| 5791 | similarly-named options above. |
| 5792 | |
| 5793 | address_pipe: |
| 5794 | driver = pipe |
| 5795 | return_output |
| 5796 | |
| 5797 | This transport is used for handling deliveries to pipes that are generated by |
| 5798 | redirection (aliasing or users' .forward files). The return_output option |
| 5799 | specifies that any output on stdout or stderr generated by the pipe is to be |
| 5800 | returned to the sender. |
| 5801 | |
| 5802 | address_file: |
| 5803 | driver = appendfile |
| 5804 | delivery_date_add |
| 5805 | envelope_to_add |
| 5806 | return_path_add |
| 5807 | |
| 5808 | This transport is used for handling deliveries to files that are generated by |
| 5809 | redirection. The name of the file is not specified in this instance of |
| 5810 | appendfile, because it comes from the redirect router. |
| 5811 | |
| 5812 | address_reply: |
| 5813 | driver = autoreply |
| 5814 | |
| 5815 | This transport is used for handling automatic replies generated by users' |
| 5816 | filter files. |
| 5817 | |
| 5818 | |
| 5819 | 7.5 Default retry rule |
| 5820 | ---------------------- |
| 5821 | |
| 5822 | The retry section of the configuration file contains rules which affect the way |
| 5823 | Exim retries deliveries that cannot be completed at the first attempt. It is |
| 5824 | introduced by the line |
| 5825 | |
| 5826 | begin retry |
| 5827 | |
| 5828 | In the default configuration, there is just one rule, which applies to all |
| 5829 | errors: |
| 5830 | |
| 5831 | * * F,2h,15m; G,16h,1h,1.5; F,4d,6h |
| 5832 | |
| 5833 | This causes any temporarily failing address to be retried every 15 minutes for |
| 5834 | 2 hours, then at intervals starting at one hour and increasing by a factor of |
| 5835 | 1.5 until 16 hours have passed, then every 6 hours up to 4 days. If an address |
| 5836 | is not delivered after 4 days of temporary failure, it is bounced. The time is |
| 5837 | measured from first failure, not from the time the message was received. |
| 5838 | |
| 5839 | If the retry section is removed from the configuration, or is empty (that is, |
| 5840 | if no retry rules are defined), Exim will not retry deliveries. This turns |
| 5841 | temporary errors into permanent errors. |
| 5842 | |
| 5843 | |
| 5844 | 7.6 Rewriting configuration |
| 5845 | --------------------------- |
| 5846 | |
| 5847 | The rewriting section of the configuration, introduced by |
| 5848 | |
| 5849 | begin rewrite |
| 5850 | |
| 5851 | contains rules for rewriting addresses in messages as they arrive. There are no |
| 5852 | rewriting rules in the default configuration file. |
| 5853 | |
| 5854 | |
| 5855 | 7.7 Authenticators configuration |
| 5856 | -------------------------------- |
| 5857 | |
| 5858 | The authenticators section of the configuration, introduced by |
| 5859 | |
| 5860 | begin authenticators |
| 5861 | |
| 5862 | defines mechanisms for the use of the SMTP AUTH command. The default |
| 5863 | configuration file contains two commented-out example authenticators which |
| 5864 | support plaintext username/password authentication using the standard PLAIN |
| 5865 | mechanism and the traditional but non-standard LOGIN mechanism, with Exim |
| 5866 | acting as the server. PLAIN and LOGIN are enough to support most MUA software. |
| 5867 | |
| 5868 | The example PLAIN authenticator looks like this: |
| 5869 | |
| 5870 | #PLAIN: |
| 5871 | # driver = plaintext |
| 5872 | # server_set_id = $auth2 |
| 5873 | # server_prompts = : |
| 5874 | # server_condition = Authentication is not yet configured |
| 5875 | # server_advertise_condition = ${if def:tls_in_cipher } |
| 5876 | |
| 5877 | And the example LOGIN authenticator looks like this: |
| 5878 | |
| 5879 | #LOGIN: |
| 5880 | # driver = plaintext |
| 5881 | # server_set_id = $auth1 |
| 5882 | # server_prompts = <| Username: | Password: |
| 5883 | # server_condition = Authentication is not yet configured |
| 5884 | # server_advertise_condition = ${if def:tls_in_cipher } |
| 5885 | |
| 5886 | The server_set_id option makes Exim remember the authenticated username in |
| 5887 | $authenticated_id, which can be used later in ACLs or routers. The |
| 5888 | server_prompts option configures the plaintext authenticator so that it |
| 5889 | implements the details of the specific authentication mechanism, i.e. PLAIN or |
| 5890 | LOGIN. The server_advertise_condition setting controls when Exim offers |
| 5891 | authentication to clients; in the examples, this is only when TLS or SSL has |
| 5892 | been started, so to enable the authenticators you also need to add support for |
| 5893 | TLS as described in section 7.1. |
| 5894 | |
| 5895 | The server_condition setting defines how to verify that the username and |
| 5896 | password are correct. In the examples it just produces an error message. To |
| 5897 | make the authenticators work, you can use a string expansion expression like |
| 5898 | one of the examples in chapter 34. |
| 5899 | |
| 5900 | Beware that the sequence of the parameters to PLAIN and LOGIN differ; the |
| 5901 | usercode and password are in different positions. Chapter 34 covers both. |
| 5902 | |
| 5903 | |
| 5904 | |
| 5905 | =============================================================================== |
| 5906 | 8. REGULAR EXPRESSIONS |
| 5907 | |
| 5908 | Exim supports the use of regular expressions in many of its options. It uses |
| 5909 | the PCRE regular expression library; this provides regular expression matching |
| 5910 | that is compatible with Perl 5. The syntax and semantics of regular expressions |
| 5911 | is discussed in online Perl manpages, in many Perl reference books, and also in |
| 5912 | Jeffrey Friedl's Mastering Regular Expressions, which is published by O'Reilly |
| 5913 | (see http://www.oreilly.com/catalog/regex2/). |
| 5914 | |
| 5915 | The documentation for the syntax and semantics of the regular expressions that |
| 5916 | are supported by PCRE is included in the PCRE distribution, and no further |
| 5917 | description is included here. The PCRE functions are called from Exim using the |
| 5918 | default option settings (that is, with no PCRE options set), except that the |
| 5919 | PCRE_CASELESS option is set when the matching is required to be |
| 5920 | case-insensitive. |
| 5921 | |
| 5922 | In most cases, when a regular expression is required in an Exim configuration, |
| 5923 | it has to start with a circumflex, in order to distinguish it from plain text |
| 5924 | or an "ends with" wildcard. In this example of a configuration setting, the |
| 5925 | second item in the colon-separated list is a regular expression. |
| 5926 | |
| 5927 | domains = a.b.c : ^\\d{3} : *.y.z : ... |
| 5928 | |
| 5929 | The doubling of the backslash is required because of string expansion that |
| 5930 | precedes interpretation - see section 11.1 for more discussion of this issue, |
| 5931 | and a way of avoiding the need for doubling backslashes. The regular expression |
| 5932 | that is eventually used in this example contains just one backslash. The |
| 5933 | circumflex is included in the regular expression, and has the normal effect of |
| 5934 | "anchoring" it to the start of the string that is being matched. |
| 5935 | |
| 5936 | There are, however, two cases where a circumflex is not required for the |
| 5937 | recognition of a regular expression: these are the match condition in a string |
| 5938 | expansion, and the matches condition in an Exim filter file. In these cases, |
| 5939 | the relevant string is always treated as a regular expression; if it does not |
| 5940 | start with a circumflex, the expression is not anchored, and can match anywhere |
| 5941 | in the subject string. |
| 5942 | |
| 5943 | In all cases, if you want a regular expression to match at the end of a string, |
| 5944 | you must code the $ metacharacter to indicate this. For example: |
| 5945 | |
| 5946 | domains = ^\\d{3}\\.example |
| 5947 | |
| 5948 | matches the domain 123.example, but it also matches 123.example.com. You need |
| 5949 | to use: |
| 5950 | |
| 5951 | domains = ^\\d{3}\\.example\$ |
| 5952 | |
| 5953 | if you want example to be the top-level domain. The backslash before the $ is |
| 5954 | needed because string expansion also interprets dollar characters. |
| 5955 | |
| 5956 | |
| 5957 | |
| 5958 | =============================================================================== |
| 5959 | 9. FILE AND DATABASE LOOKUPS |
| 5960 | |
| 5961 | Exim can be configured to look up data in files or databases as it processes |
| 5962 | messages. Two different kinds of syntax are used: |
| 5963 | |
| 5964 | 1. A string that is to be expanded may contain explicit lookup requests. These |
| 5965 | cause parts of the string to be replaced by data that is obtained from the |
| 5966 | lookup. Lookups of this type are conditional expansion items. Different |
| 5967 | results can be defined for the cases of lookup success and failure. See |
| 5968 | chapter 11, where string expansions are described in detail. The key for |
| 5969 | the lookup is specified as part of the string expansion. |
| 5970 | |
| 5971 | 2. Lists of domains, hosts, and email addresses can contain lookup requests as |
| 5972 | a way of avoiding excessively long linear lists. In this case, the data |
| 5973 | that is returned by the lookup is often (but not always) discarded; whether |
| 5974 | the lookup succeeds or fails is what really counts. These kinds of list are |
| 5975 | described in chapter 10. The key for the lookup is given by the context in |
| 5976 | which the list is expanded. |
| 5977 | |
| 5978 | String expansions, lists, and lookups interact with each other in such a way |
| 5979 | that there is no order in which to describe any one of them that does not |
| 5980 | involve references to the others. Each of these three chapters makes more sense |
| 5981 | if you have read the other two first. If you are reading this for the first |
| 5982 | time, be aware that some of it will make a lot more sense after you have read |
| 5983 | chapters 10 and 11. |
| 5984 | |
| 5985 | |
| 5986 | 9.1 Examples of different lookup syntax |
| 5987 | --------------------------------------- |
| 5988 | |
| 5989 | It is easy to confuse the two different kinds of lookup, especially as the |
| 5990 | lists that may contain the second kind are always expanded before being |
| 5991 | processed as lists. Therefore, they may also contain lookups of the first kind. |
| 5992 | Be careful to distinguish between the following two examples: |
| 5993 | |
| 5994 | domains = ${lookup{$sender_host_address}lsearch{/some/file}} |
| 5995 | domains = lsearch;/some/file |
| 5996 | |
| 5997 | The first uses a string expansion, the result of which must be a domain list. |
| 5998 | No strings have been specified for a successful or a failing lookup; the |
| 5999 | defaults in this case are the looked-up data and an empty string, respectively. |
| 6000 | The expansion takes place before the string is processed as a list, and the |
| 6001 | file that is searched could contain lines like this: |
| 6002 | |
| 6003 | 192.168.3.4: domain1:domain2:... |
| 6004 | 192.168.1.9: domain3:domain4:... |
| 6005 | |
| 6006 | When the lookup succeeds, the result of the expansion is a list of domains (and |
| 6007 | possibly other types of item that are allowed in domain lists). |
| 6008 | |
| 6009 | In the second example, the lookup is a single item in a domain list. It causes |
| 6010 | Exim to use a lookup to see if the domain that is being processed can be found |
| 6011 | in the file. The file could contains lines like this: |
| 6012 | |
| 6013 | domain1: |
| 6014 | domain2: |
| 6015 | |
| 6016 | Any data that follows the keys is not relevant when checking that the domain |
| 6017 | matches the list item. |
| 6018 | |
| 6019 | It is possible, though no doubt confusing, to use both kinds of lookup at once. |
| 6020 | Consider a file containing lines like this: |
| 6021 | |
| 6022 | 192.168.5.6: lsearch;/another/file |
| 6023 | |
| 6024 | If the value of $sender_host_address is 192.168.5.6, expansion of the first |
| 6025 | domains setting above generates the second setting, which therefore causes a |
| 6026 | second lookup to occur. |
| 6027 | |
| 6028 | The rest of this chapter describes the different lookup types that are |
| 6029 | available. Any of them can be used in any part of the configuration where a |
| 6030 | lookup is permitted. |
| 6031 | |
| 6032 | |
| 6033 | 9.2 Lookup types |
| 6034 | ---------------- |
| 6035 | |
| 6036 | Two different types of data lookup are implemented: |
| 6037 | |
| 6038 | * The single-key type requires the specification of a file in which to look, |
| 6039 | and a single key to search for. The key must be a non-empty string for the |
| 6040 | lookup to succeed. The lookup type determines how the file is searched. |
| 6041 | |
| 6042 | * The query-style type accepts a generalized database query. No particular |
| 6043 | key value is assumed by Exim for query-style lookups. You can use whichever |
| 6044 | Exim variables you need to construct the database query. |
| 6045 | |
| 6046 | The code for each lookup type is in a separate source file that is included in |
| 6047 | the binary of Exim only if the corresponding compile-time option is set. The |
| 6048 | default settings in src/EDITME are: |
| 6049 | |
| 6050 | LOOKUP_DBM=yes |
| 6051 | LOOKUP_LSEARCH=yes |
| 6052 | |
| 6053 | which means that only linear searching and DBM lookups are included by default. |
| 6054 | For some types of lookup (e.g. SQL databases), you need to install appropriate |
| 6055 | libraries and header files before building Exim. |
| 6056 | |
| 6057 | |
| 6058 | 9.3 Single-key lookup types |
| 6059 | --------------------------- |
| 6060 | |
| 6061 | The following single-key lookup types are implemented: |
| 6062 | |
| 6063 | * cdb: The given file is searched as a Constant DataBase file, using the key |
| 6064 | string without a terminating binary zero. The cdb format is designed for |
| 6065 | indexed files that are read frequently and never updated, except by total |
| 6066 | re-creation. As such, it is particularly suitable for large files |
| 6067 | containing aliases or other indexed data referenced by an MTA. Information |
| 6068 | about cdb can be found in several places: |
| 6069 | |
| 6070 | http://www.pobox.com/~djb/cdb.html |
| 6071 | ftp://ftp.corpit.ru/pub/tinycdb/ |
| 6072 | http://packages.debian.org/stable/utils/freecdb.html |
| 6073 | |
| 6074 | A cdb distribution is not needed in order to build Exim with cdb support, |
| 6075 | because the code for reading cdb files is included directly in Exim itself. |
| 6076 | However, no means of building or testing cdb files is provided with Exim, |
| 6077 | so you need to obtain a cdb distribution in order to do this. |
| 6078 | |
| 6079 | * dbm: Calls to DBM library functions are used to extract data from the given |
| 6080 | DBM file by looking up the record with the given key. A terminating binary |
| 6081 | zero is included in the key that is passed to the DBM library. See section |
| 6082 | 4.4 for a discussion of DBM libraries. |
| 6083 | |
| 6084 | For all versions of Berkeley DB, Exim uses the DB_HASH style of database |
| 6085 | when building DBM files using the exim_dbmbuild utility. However, when |
| 6086 | using Berkeley DB versions 3 or 4, it opens existing databases for reading |
| 6087 | with the DB_UNKNOWN option. This enables it to handle any of the types of |
| 6088 | database that the library supports, and can be useful for accessing DBM |
| 6089 | files created by other applications. (For earlier DB versions, DB_HASH is |
| 6090 | always used.) |
| 6091 | |
| 6092 | * dbmjz: This is the same as dbm, except that the lookup key is interpreted |
| 6093 | as an Exim list; the elements of the list are joined together with ASCII |
| 6094 | NUL characters to form the lookup key. An example usage would be to |
| 6095 | authenticate incoming SMTP calls using the passwords from Cyrus SASL's /etc |
| 6096 | /sasldb2 file with the gsasl authenticator or Exim's own cram_md5 |
| 6097 | authenticator. |
| 6098 | |
| 6099 | * dbmnz: This is the same as dbm, except that a terminating binary zero is |
| 6100 | not included in the key that is passed to the DBM library. You may need |
| 6101 | this if you want to look up data in files that are created by or shared |
| 6102 | with some other application that does not use terminating zeros. For |
| 6103 | example, you need to use dbmnz rather than dbm if you want to authenticate |
| 6104 | incoming SMTP calls using the passwords from Courier's /etc/ |
| 6105 | userdbshadow.dat file. Exim's utility program for creating DBM files ( |
| 6106 | exim_dbmbuild) includes the zeros by default, but has an option to omit |
| 6107 | them (see section 53.9). |
| 6108 | |
| 6109 | * dsearch: The given file must be a directory; this is searched for an entry |
| 6110 | whose name is the key by calling the lstat() function. The key may not |
| 6111 | contain any forward slash characters. If lstat() succeeds, the result of |
| 6112 | the lookup is the name of the entry, which may be a file, directory, |
| 6113 | symbolic link, or any other kind of directory entry. An example of how this |
| 6114 | lookup can be used to support virtual domains is given in section 50.7. |
| 6115 | |
| 6116 | * iplsearch: The given file is a text file containing keys and data. A key is |
| 6117 | terminated by a colon or white space or the end of the line. The keys in |
| 6118 | the file must be IP addresses, or IP addresses with CIDR masks. Keys that |
| 6119 | involve IPv6 addresses must be enclosed in quotes to prevent the first |
| 6120 | internal colon being interpreted as a key terminator. For example: |
| 6121 | |
| 6122 | 1.2.3.4: data for 1.2.3.4 |
| 6123 | 192.168.0.0/16: data for 192.168.0.0/16 |
| 6124 | "abcd::cdab": data for abcd::cdab |
| 6125 | "abcd:abcd::/32" data for abcd:abcd::/32 |
| 6126 | |
| 6127 | The key for an iplsearch lookup must be an IP address (without a mask). The |
| 6128 | file is searched linearly, using the CIDR masks where present, until a |
| 6129 | matching key is found. The first key that matches is used; there is no |
| 6130 | attempt to find a "best" match. Apart from the way the keys are matched, |
| 6131 | the processing for iplsearch is the same as for lsearch. |
| 6132 | |
| 6133 | Warning 1: Unlike most other single-key lookup types, a file of data for |
| 6134 | iplsearch can not be turned into a DBM or cdb file, because those lookup |
| 6135 | types support only literal keys. |
| 6136 | |
| 6137 | Warning 2: In a host list, you must always use net-iplsearch so that the |
| 6138 | implicit key is the host's IP address rather than its name (see section |
| 6139 | 10.12). |
| 6140 | |
| 6141 | * lsearch: The given file is a text file that is searched linearly for a line |
| 6142 | beginning with the search key, terminated by a colon or white space or the |
| 6143 | end of the line. The search is case-insensitive; that is, upper and lower |
| 6144 | case letters are treated as the same. The first occurrence of the key that |
| 6145 | is found in the file is used. |
| 6146 | |
| 6147 | White space between the key and the colon is permitted. The remainder of |
| 6148 | the line, with leading and trailing white space removed, is the data. This |
| 6149 | can be continued onto subsequent lines by starting them with any amount of |
| 6150 | white space, but only a single space character is included in the data at |
| 6151 | such a junction. If the data begins with a colon, the key must be |
| 6152 | terminated by a colon, for example: |
| 6153 | |
| 6154 | baduser: :fail: |
| 6155 | |
| 6156 | Empty lines and lines beginning with # are ignored, even if they occur in |
| 6157 | the middle of an item. This is the traditional textual format of alias |
| 6158 | files. Note that the keys in an lsearch file are literal strings. There is |
| 6159 | no wildcarding of any kind. |
| 6160 | |
| 6161 | In most lsearch files, keys are not required to contain colons or # |
| 6162 | characters, or white space. However, if you need this feature, it is |
| 6163 | available. If a key begins with a doublequote character, it is terminated |
| 6164 | only by a matching quote (or end of line), and the normal escaping rules |
| 6165 | apply to its contents (see section 6.17). An optional colon is permitted |
| 6166 | after quoted keys (exactly as for unquoted keys). There is no special |
| 6167 | handling of quotes for the data part of an lsearch line. |
| 6168 | |
| 6169 | * nis: The given file is the name of a NIS map, and a NIS lookup is done with |
| 6170 | the given key, without a terminating binary zero. There is a variant called |
| 6171 | nis0 which does include the terminating binary zero in the key. This is |
| 6172 | reportedly needed for Sun-style alias files. Exim does not recognize NIS |
| 6173 | aliases; the full map names must be used. |
| 6174 | |
| 6175 | * wildlsearch or nwildlsearch: These search a file linearly, like lsearch, |
| 6176 | but instead of being interpreted as a literal string, each key in the file |
| 6177 | may be wildcarded. The difference between these two lookup types is that |
| 6178 | for wildlsearch, each key in the file is string-expanded before being used, |
| 6179 | whereas for nwildlsearch, no expansion takes place. |
| 6180 | |
| 6181 | Like lsearch, the testing is done case-insensitively. However, keys in the |
| 6182 | file that are regular expressions can be made case-sensitive by the use of |
| 6183 | "(-i)" within the pattern. The following forms of wildcard are recognized: |
| 6184 | |
| 6185 | 1. The string may begin with an asterisk to mean "ends with". For example: |
| 6186 | |
| 6187 | *.a.b.c data for anything.a.b.c |
| 6188 | *fish data for anythingfish |
| 6189 | |
| 6190 | 2. The string may begin with a circumflex to indicate a regular |
| 6191 | expression. For example, for wildlsearch: |
| 6192 | |
| 6193 | ^\N\d+\.a\.b\N data for <digits>.a.b |
| 6194 | |
| 6195 | Note the use of "\N" to disable expansion of the contents of the |
| 6196 | regular expression. If you are using nwildlsearch, where the keys are |
| 6197 | not string-expanded, the equivalent entry is: |
| 6198 | |
| 6199 | ^\d+\.a\.b data for <digits>.a.b |
| 6200 | |
| 6201 | The case-insensitive flag is set at the start of compiling the regular |
| 6202 | expression, but it can be turned off by using "(-i)" at an appropriate |
| 6203 | point. For example, to make the entire pattern case-sensitive: |
| 6204 | |
| 6205 | ^(?-i)\d+\.a\.b data for <digits>.a.b |
| 6206 | |
| 6207 | If the regular expression contains white space or colon characters, you |
| 6208 | must either quote it (see lsearch above), or represent these characters |
| 6209 | in other ways. For example, "\s" can be used for white space and "\x3A" |
| 6210 | for a colon. This may be easier than quoting, because if you quote, you |
| 6211 | have to escape all the backslashes inside the quotes. |
| 6212 | |
| 6213 | Note: It is not possible to capture substrings in a regular expression |
| 6214 | match for later use, because the results of all lookups are cached. If |
| 6215 | a lookup is repeated, the result is taken from the cache, and no actual |
| 6216 | pattern matching takes place. The values of all the numeric variables |
| 6217 | are unset after a (n)wildlsearch match. |
| 6218 | |
| 6219 | 3. Although I cannot see it being of much use, the general matching |
| 6220 | function that is used to implement (n)wildlsearch means that the string |
| 6221 | may begin with a lookup name terminated by a semicolon, and followed by |
| 6222 | lookup data. For example: |
| 6223 | |
| 6224 | cdb;/some/file data for keys that match the file |
| 6225 | |
| 6226 | The data that is obtained from the nested lookup is discarded. |
| 6227 | |
| 6228 | Keys that do not match any of these patterns are interpreted literally. The |
| 6229 | continuation rules for the data are the same as for lsearch, and keys may |
| 6230 | be followed by optional colons. |
| 6231 | |
| 6232 | Warning: Unlike most other single-key lookup types, a file of data for (n) |
| 6233 | wildlsearch can not be turned into a DBM or cdb file, because those lookup |
| 6234 | types support only literal keys. |
| 6235 | |
| 6236 | |
| 6237 | 9.4 Query-style lookup types |
| 6238 | ---------------------------- |
| 6239 | |
| 6240 | The supported query-style lookup types are listed below. Further details about |
| 6241 | many of them are given in later sections. |
| 6242 | |
| 6243 | * dnsdb: This does a DNS search for one or more records whose domain names |
| 6244 | are given in the supplied query. The resulting data is the contents of the |
| 6245 | records. See section 9.10. |
| 6246 | |
| 6247 | * ibase: This does a lookup in an InterBase database. |
| 6248 | |
| 6249 | * ldap: This does an LDAP lookup using a query in the form of a URL, and |
| 6250 | returns attributes from a single entry. There is a variant called ldapm |
| 6251 | that permits values from multiple entries to be returned. A third variant |
| 6252 | called ldapdn returns the Distinguished Name of a single entry instead of |
| 6253 | any attribute values. See section 9.14. |
| 6254 | |
| 6255 | * mysql: The format of the query is an SQL statement that is passed to a |
| 6256 | MySQL database. See section 9.21. |
| 6257 | |
| 6258 | * nisplus: This does a NIS+ lookup using a query that can specify the name of |
| 6259 | the field to be returned. See section 9.20. |
| 6260 | |
| 6261 | * oracle: The format of the query is an SQL statement that is passed to an |
| 6262 | Oracle database. See section 9.21. |
| 6263 | |
| 6264 | * passwd is a query-style lookup with queries that are just user names. The |
| 6265 | lookup calls getpwnam() to interrogate the system password data, and on |
| 6266 | success, the result string is the same as you would get from an lsearch |
| 6267 | lookup on a traditional /etc/passwd file, though with "*" for the password |
| 6268 | value. For example: |
| 6269 | |
| 6270 | *:42:42:King Rat:/home/kr:/bin/bash |
| 6271 | |
| 6272 | * pgsql: The format of the query is an SQL statement that is passed to a |
| 6273 | PostgreSQL database. See section 9.21. |
| 6274 | |
| 6275 | * redis: The format of the query is either a simple get or simple set, passed |
| 6276 | to a Redis database. See section 9.21. |
| 6277 | |
| 6278 | * sqlite: The format of the query is a file name followed by an SQL statement |
| 6279 | that is passed to an SQLite database. See section 9.26. |
| 6280 | |
| 6281 | * testdb: This is a lookup type that is used for testing Exim. It is not |
| 6282 | likely to be useful in normal operation. |
| 6283 | |
| 6284 | * whoson: Whoson (http://whoson.sourceforge.net) is a protocol that allows a |
| 6285 | server to check whether a particular (dynamically allocated) IP address is |
| 6286 | currently allocated to a known (trusted) user and, optionally, to obtain |
| 6287 | the identity of the said user. For SMTP servers, Whoson was popular at one |
| 6288 | time for "POP before SMTP" authentication, but that approach has been |
| 6289 | superseded by SMTP authentication. In Exim, Whoson can be used to implement |
| 6290 | "POP before SMTP" checking using ACL statements such as |
| 6291 | |
| 6292 | require condition = \ |
| 6293 | ${lookup whoson {$sender_host_address}{yes}{no}} |
| 6294 | |
| 6295 | The query consists of a single IP address. The value returned is the name |
| 6296 | of the authenticated user, which is stored in the variable $value. However, |
| 6297 | in this example, the data in $value is not used; the result of the lookup |
| 6298 | is one of the fixed strings "yes" or "no". |
| 6299 | |
| 6300 | |
| 6301 | 9.5 Temporary errors in lookups |
| 6302 | ------------------------------- |
| 6303 | |
| 6304 | Lookup functions can return temporary error codes if the lookup cannot be |
| 6305 | completed. For example, an SQL or LDAP database might be unavailable. For this |
| 6306 | reason, it is not advisable to use a lookup that might do this for critical |
| 6307 | options such as a list of local domains. |
| 6308 | |
| 6309 | When a lookup cannot be completed in a router or transport, delivery of the |
| 6310 | message (to the relevant address) is deferred, as for any other temporary |
| 6311 | error. In other circumstances Exim may assume the lookup has failed, or may |
| 6312 | give up altogether. |
| 6313 | |
| 6314 | |
| 6315 | 9.6 Default values in single-key lookups |
| 6316 | ---------------------------------------- |
| 6317 | |
| 6318 | In this context, a "default value" is a value specified by the administrator |
| 6319 | that is to be used if a lookup fails. |
| 6320 | |
| 6321 | Note: This section applies only to single-key lookups. For query-style lookups, |
| 6322 | the facilities of the query language must be used. An attempt to specify a |
| 6323 | default for a query-style lookup provokes an error. |
| 6324 | |
| 6325 | If "*" is added to a single-key lookup type (for example, lsearch*) and the |
| 6326 | initial lookup fails, the key "*" is looked up in the file to provide a default |
| 6327 | value. See also the section on partial matching below. |
| 6328 | |
| 6329 | Alternatively, if "*@" is added to a single-key lookup type (for example dbm*@) |
| 6330 | then, if the initial lookup fails and the key contains an @ character, a second |
| 6331 | lookup is done with everything before the last @ replaced by *. This makes it |
| 6332 | possible to provide per-domain defaults in alias files that include the domains |
| 6333 | in the keys. If the second lookup fails (or doesn't take place because there is |
| 6334 | no @ in the key), "*" is looked up. For example, a redirect router might |
| 6335 | contain: |
| 6336 | |
| 6337 | data = ${lookup{$local_part@$domain}lsearch*@{/etc/mix-aliases}} |
| 6338 | |
| 6339 | Suppose the address that is being processed is jane@eyre.example. Exim looks up |
| 6340 | these keys, in this order: |
| 6341 | |
| 6342 | jane@eyre.example |
| 6343 | *@eyre.example |
| 6344 | * |
| 6345 | |
| 6346 | The data is taken from whichever key it finds first. Note: In an lsearch file, |
| 6347 | this does not mean the first of these keys in the file. A complete scan is done |
| 6348 | for each key, and only if it is not found at all does Exim move on to try the |
| 6349 | next key. |
| 6350 | |
| 6351 | |
| 6352 | 9.7 Partial matching in single-key lookups |
| 6353 | ------------------------------------------ |
| 6354 | |
| 6355 | The normal operation of a single-key lookup is to search the file for an exact |
| 6356 | match with the given key. However, in a number of situations where domains are |
| 6357 | being looked up, it is useful to be able to do partial matching. In this case, |
| 6358 | information in the file that has a key starting with "*." is matched by any |
| 6359 | domain that ends with the components that follow the full stop. For example, if |
| 6360 | a key in a DBM file is |
| 6361 | |
| 6362 | *.dates.fict.example |
| 6363 | |
| 6364 | then when partial matching is enabled this is matched by (amongst others) |
| 6365 | 2001.dates.fict.example and 1984.dates.fict.example. It is also matched by |
| 6366 | dates.fict.example, if that does not appear as a separate key in the file. |
| 6367 | |
| 6368 | Note: Partial matching is not available for query-style lookups. It is also not |
| 6369 | available for any lookup items in address lists (see section 10.19). |
| 6370 | |
| 6371 | Partial matching is implemented by doing a series of separate lookups using |
| 6372 | keys constructed by modifying the original subject key. This means that it can |
| 6373 | be used with any of the single-key lookup types, provided that partial matching |
| 6374 | keys beginning with a special prefix (default "*.") are included in the data |
| 6375 | file. Keys in the file that do not begin with the prefix are matched only by |
| 6376 | unmodified subject keys when partial matching is in use. |
| 6377 | |
| 6378 | Partial matching is requested by adding the string "partial-" to the front of |
| 6379 | the name of a single-key lookup type, for example, partial-dbm. When this is |
| 6380 | done, the subject key is first looked up unmodified; if that fails, "*." is |
| 6381 | added at the start of the subject key, and it is looked up again. If that |
| 6382 | fails, further lookups are tried with dot-separated components removed from the |
| 6383 | start of the subject key, one-by-one, and "*." added on the front of what |
| 6384 | remains. |
| 6385 | |
| 6386 | A minimum number of two non-* components are required. This can be adjusted by |
| 6387 | including a number before the hyphen in the search type. For example, |
| 6388 | partial3-lsearch specifies a minimum of three non-* components in the modified |
| 6389 | keys. Omitting the number is equivalent to "partial2-". If the subject key is |
| 6390 | 2250.dates.fict.example then the following keys are looked up when the minimum |
| 6391 | number of non-* components is two: |
| 6392 | |
| 6393 | 2250.dates.fict.example |
| 6394 | *.2250.dates.fict.example |
| 6395 | *.dates.fict.example |
| 6396 | *.fict.example |
| 6397 | |
| 6398 | As soon as one key in the sequence is successfully looked up, the lookup |
| 6399 | finishes. |
| 6400 | |
| 6401 | The use of "*." as the partial matching prefix is a default that can be |
| 6402 | changed. The motivation for this feature is to allow Exim to operate with file |
| 6403 | formats that are used by other MTAs. A different prefix can be supplied in |
| 6404 | parentheses instead of the hyphen after "partial". For example: |
| 6405 | |
| 6406 | domains = partial(.)lsearch;/some/file |
| 6407 | |
| 6408 | In this example, if the domain is a.b.c, the sequence of lookups is "a.b.c", |
| 6409 | ".a.b.c", and ".b.c" (the default minimum of 2 non-wild components is |
| 6410 | unchanged). The prefix may consist of any punctuation characters other than a |
| 6411 | closing parenthesis. It may be empty, for example: |
| 6412 | |
| 6413 | domains = partial1()cdb;/some/file |
| 6414 | |
| 6415 | For this example, if the domain is a.b.c, the sequence of lookups is "a.b.c", |
| 6416 | "b.c", and "c". |
| 6417 | |
| 6418 | If "partial0" is specified, what happens at the end (when the lookup with just |
| 6419 | one non-wild component has failed, and the original key is shortened right down |
| 6420 | to the null string) depends on the prefix: |
| 6421 | |
| 6422 | * If the prefix has zero length, the whole lookup fails. |
| 6423 | |
| 6424 | * If the prefix has length 1, a lookup for just the prefix is done. For |
| 6425 | example, the final lookup for "partial0(.)" is for "." alone. |
| 6426 | |
| 6427 | * Otherwise, if the prefix ends in a dot, the dot is removed, and the |
| 6428 | remainder is looked up. With the default prefix, therefore, the final |
| 6429 | lookup is for "*" on its own. |
| 6430 | |
| 6431 | * Otherwise, the whole prefix is looked up. |
| 6432 | |
| 6433 | If the search type ends in "*" or "*@" (see section 9.6 above), the search for |
| 6434 | an ultimate default that this implies happens after all partial lookups have |
| 6435 | failed. If "partial0" is specified, adding "*" to the search type has no effect |
| 6436 | with the default prefix, because the "*" key is already included in the |
| 6437 | sequence of partial lookups. However, there might be a use for lookup types |
| 6438 | such as "partial0(.)lsearch*". |
| 6439 | |
| 6440 | The use of "*" in lookup partial matching differs from its use as a wildcard in |
| 6441 | domain lists and the like. Partial matching works only in terms of |
| 6442 | dot-separated components; a key such as "*fict.example" in a database file is |
| 6443 | useless, because the asterisk in a partial matching subject key is always |
| 6444 | followed by a dot. |
| 6445 | |
| 6446 | |
| 6447 | 9.8 Lookup caching |
| 6448 | ------------------ |
| 6449 | |
| 6450 | Exim caches all lookup results in order to avoid needless repetition of |
| 6451 | lookups. However, because (apart from the daemon) Exim operates as a collection |
| 6452 | of independent, short-lived processes, this caching applies only within a |
| 6453 | single Exim process. There is no inter-process lookup caching facility. |
| 6454 | |
| 6455 | For single-key lookups, Exim keeps the relevant files open in case there is |
| 6456 | another lookup that needs them. In some types of configuration this can lead to |
| 6457 | many files being kept open for messages with many recipients. To avoid hitting |
| 6458 | the operating system limit on the number of simultaneously open files, Exim |
| 6459 | closes the least recently used file when it needs to open more files than its |
| 6460 | own internal limit, which can be changed via the lookup_open_max option. |
| 6461 | |
| 6462 | The single-key lookup files are closed and the lookup caches are flushed at |
| 6463 | strategic points during delivery - for example, after all routing is complete. |
| 6464 | |
| 6465 | |
| 6466 | 9.9 Quoting lookup data |
| 6467 | ----------------------- |
| 6468 | |
| 6469 | When data from an incoming message is included in a query-style lookup, there |
| 6470 | is the possibility of special characters in the data messing up the syntax of |
| 6471 | the query. For example, a NIS+ query that contains |
| 6472 | |
| 6473 | [name=$local_part] |
| 6474 | |
| 6475 | will be broken if the local part happens to contain a closing square bracket. |
| 6476 | For NIS+, data can be enclosed in double quotes like this: |
| 6477 | |
| 6478 | [name="$local_part"] |
| 6479 | |
| 6480 | but this still leaves the problem of a double quote in the data. The rule for |
| 6481 | NIS+ is that double quotes must be doubled. Other lookup types have different |
| 6482 | rules, and to cope with the differing requirements, an expansion operator of |
| 6483 | the following form is provided: |
| 6484 | |
| 6485 | ${quote_<lookup-type>:<string>} |
| 6486 | |
| 6487 | For example, the safest way to write the NIS+ query is |
| 6488 | |
| 6489 | [name="${quote_nisplus:$local_part}"] |
| 6490 | |
| 6491 | See chapter 11 for full coverage of string expansions. The quote operator can |
| 6492 | be used for all lookup types, but has no effect for single-key lookups, since |
| 6493 | no quoting is ever needed in their key strings. |
| 6494 | |
| 6495 | |
| 6496 | 9.10 More about dnsdb |
| 6497 | --------------------- |
| 6498 | |
| 6499 | The dnsdb lookup type uses the DNS as its database. A simple query consists of |
| 6500 | a record type and a domain name, separated by an equals sign. For example, an |
| 6501 | expansion string could contain: |
| 6502 | |
| 6503 | ${lookup dnsdb{mx=a.b.example}{$value}fail} |
| 6504 | |
| 6505 | If the lookup succeeds, the result is placed in $value, which in this case is |
| 6506 | used on its own as the result. If the lookup does not succeed, the "fail" |
| 6507 | keyword causes a forced expansion failure - see section 11.4 for an explanation |
| 6508 | of what this means. |
| 6509 | |
| 6510 | The supported DNS record types are A, CNAME, MX, NS, PTR, SOA, SPF, SRV, TLSA |
| 6511 | and TXT, and, when Exim is compiled with IPv6 support, AAAA. If no type is |
| 6512 | given, TXT is assumed. |
| 6513 | |
| 6514 | For any record type, if multiple records are found, the data is returned as a |
| 6515 | concatenation, with newline as the default separator. The order, of course, |
| 6516 | depends on the DNS resolver. You can specify a different separator character |
| 6517 | between multiple records by putting a right angle-bracket followed immediately |
| 6518 | by the new separator at the start of the query. For example: |
| 6519 | |
| 6520 | ${lookup dnsdb{>: a=host1.example}} |
| 6521 | |
| 6522 | It is permitted to specify a space as the separator character. Further white |
| 6523 | space is ignored. For lookup types that return multiple fields per record, an |
| 6524 | alternate field separator can be specified using a comma after the main |
| 6525 | separator character, followed immediately by the field separator. |
| 6526 | |
| 6527 | When the type is PTR, the data can be an IP address, written as normal; |
| 6528 | inversion and the addition of in-addr.arpa or ip6.arpa happens automatically. |
| 6529 | For example: |
| 6530 | |
| 6531 | ${lookup dnsdb{ptr=192.168.4.5}{$value}fail} |
| 6532 | |
| 6533 | If the data for a PTR record is not a syntactically valid IP address, it is not |
| 6534 | altered and nothing is added. |
| 6535 | |
| 6536 | For an MX lookup, both the preference value and the host name are returned for |
| 6537 | each record, separated by a space. For an SRV lookup, the priority, weight, |
| 6538 | port, and host name are returned for each record, separated by spaces. The |
| 6539 | field separator can be modified as above. |
| 6540 | |
| 6541 | For TXT records with multiple items of data, only the first item is returned, |
| 6542 | unless a field separator is specified. To concatenate items without a |
| 6543 | separator, use a semicolon instead. For SPF records the default behaviour is to |
| 6544 | concatenate multiple items without using a separator. |
| 6545 | |
| 6546 | ${lookup dnsdb{>\n,: txt=a.b.example}} |
| 6547 | ${lookup dnsdb{>\n; txt=a.b.example}} |
| 6548 | ${lookup dnsdb{spf=example.org}} |
| 6549 | |
| 6550 | It is permitted to specify a space as the separator character. Further white |
| 6551 | space is ignored. |
| 6552 | |
| 6553 | For an SOA lookup, while no result is obtained the lookup is redone with |
| 6554 | successively more leading components dropped from the given domain. Only the |
| 6555 | primary-nameserver field is returned unless a field separator is specified. |
| 6556 | |
| 6557 | ${lookup dnsdb{>:,; soa=a.b.example.com}} |
| 6558 | |
| 6559 | |
| 6560 | 9.11 Dnsdb lookup modifiers |
| 6561 | --------------------------- |
| 6562 | |
| 6563 | Modifiers for dnsdb lookups are given by optional keywords, each followed by a |
| 6564 | comma, that may appear before the record type. |
| 6565 | |
| 6566 | The dnsdb lookup fails only if all the DNS lookups fail. If there is a |
| 6567 | temporary DNS error for any of them, the behaviour is controlled by a |
| 6568 | defer-option modifier. The possible keywords are "defer_strict", "defer_never", |
| 6569 | and "defer_lax". With "strict" behaviour, any temporary DNS error causes the |
| 6570 | whole lookup to defer. With "never" behaviour, a temporary DNS error is |
| 6571 | ignored, and the behaviour is as if the DNS lookup failed to find anything. |
| 6572 | With "lax" behaviour, all the queries are attempted, but a temporary DNS error |
| 6573 | causes the whole lookup to defer only if none of the other lookups succeed. The |
| 6574 | default is "lax", so the following lookups are equivalent: |
| 6575 | |
| 6576 | ${lookup dnsdb{defer_lax,a=one.host.com:two.host.com}} |
| 6577 | ${lookup dnsdb{a=one.host.com:two.host.com}} |
| 6578 | |
| 6579 | Thus, in the default case, as long as at least one of the DNS lookups yields |
| 6580 | some data, the lookup succeeds. |
| 6581 | |
| 6582 | Use of DNSSEC is controlled by a dnssec modifier. The possible keywords are |
| 6583 | "dnssec_strict", "dnssec_lax", and "dnssec_never". With "strict" or "lax" |
| 6584 | DNSSEC information is requested with the lookup. With "strict" a response from |
| 6585 | the DNS resolver that is not labelled as authenticated data is treated as |
| 6586 | equivalent to a temporary DNS error. The default is "never". |
| 6587 | |
| 6588 | See also the $lookup_dnssec_authenticated variable. |
| 6589 | |
| 6590 | Timeout for the dnsdb lookup can be controlled by a retrans modifier. The form |
| 6591 | is "retrans_VAL" where VAL is an Exim time specification (e.g. "5s"). The |
| 6592 | default value is set by the main configuration option dns_retrans. |
| 6593 | |
| 6594 | Retries for the dnsdb lookup can be controlled by a retry modifier. The form if |
| 6595 | "retry_VAL" where VAL is an integer. The default count is set by the main |
| 6596 | configuration option dns_retry. |
| 6597 | |
| 6598 | Dnsdb lookup results are cached within a single process (and its children). The |
| 6599 | cache entry lifetime is limited to the smallest time-to-live (TTL) value of the |
| 6600 | set of returned DNS records. |
| 6601 | |
| 6602 | |
| 6603 | 9.12 Pseudo dnsdb record types |
| 6604 | ------------------------------ |
| 6605 | |
| 6606 | By default, both the preference value and the host name are returned for each |
| 6607 | MX record, separated by a space. If you want only host names, you can use the |
| 6608 | pseudo-type MXH: |
| 6609 | |
| 6610 | ${lookup dnsdb{mxh=a.b.example}} |
| 6611 | |
| 6612 | In this case, the preference values are omitted, and just the host names are |
| 6613 | returned. |
| 6614 | |
| 6615 | Another pseudo-type is ZNS (for "zone NS"). It performs a lookup for NS records |
| 6616 | on the given domain, but if none are found, it removes the first component of |
| 6617 | the domain name, and tries again. This process continues until NS records are |
| 6618 | found or there are no more components left (or there is a DNS error). In other |
| 6619 | words, it may return the name servers for a top-level domain, but it never |
| 6620 | returns the root name servers. If there are no NS records for the top-level |
| 6621 | domain, the lookup fails. Consider these examples: |
| 6622 | |
| 6623 | ${lookup dnsdb{zns=xxx.quercite.com}} |
| 6624 | ${lookup dnsdb{zns=xxx.edu}} |
| 6625 | |
| 6626 | Assuming that in each case there are no NS records for the full domain name, |
| 6627 | the first returns the name servers for quercite.com, and the second returns the |
| 6628 | name servers for edu. |
| 6629 | |
| 6630 | You should be careful about how you use this lookup because, unless the |
| 6631 | top-level domain does not exist, the lookup always returns some host names. The |
| 6632 | sort of use to which this might be put is for seeing if the name servers for a |
| 6633 | given domain are on a blacklist. You can probably assume that the name servers |
| 6634 | for the high-level domains such as com or co.uk are not going to be on such a |
| 6635 | list. |
| 6636 | |
| 6637 | A third pseudo-type is CSA (Client SMTP Authorization). This looks up SRV |
| 6638 | records according to the CSA rules, which are described in section 43.50. |
| 6639 | Although dnsdb supports SRV lookups directly, this is not sufficient because of |
| 6640 | the extra parent domain search behaviour of CSA. The result of a successful |
| 6641 | lookup such as: |
| 6642 | |
| 6643 | ${lookup dnsdb {csa=$sender_helo_name}} |
| 6644 | |
| 6645 | has two space-separated fields: an authorization code and a target host name. |
| 6646 | The authorization code can be "Y" for yes, "N" for no, "X" for explicit |
| 6647 | authorization required but absent, or "?" for unknown. |
| 6648 | |
| 6649 | The pseudo-type A+ performs an AAAA and then an A lookup. All results are |
| 6650 | returned; defer processing (see below) is handled separately for each lookup. |
| 6651 | Example: |
| 6652 | |
| 6653 | ${lookup dnsdb {>; a+=$sender_helo_name}} |
| 6654 | |
| 6655 | |
| 6656 | 9.13 Multiple dnsdb lookups |
| 6657 | --------------------------- |
| 6658 | |
| 6659 | In the previous sections, dnsdb lookups for a single domain are described. |
| 6660 | However, you can specify a list of domains or IP addresses in a single dnsdb |
| 6661 | lookup. The list is specified in the normal Exim way, with colon as the default |
| 6662 | separator, but with the ability to change this. For example: |
| 6663 | |
| 6664 | ${lookup dnsdb{one.domain.com:two.domain.com}} |
| 6665 | ${lookup dnsdb{a=one.host.com:two.host.com}} |
| 6666 | ${lookup dnsdb{ptr = <; 1.2.3.4 ; 4.5.6.8}} |
| 6667 | |
| 6668 | In order to retain backwards compatibility, there is one special case: if the |
| 6669 | lookup type is PTR and no change of separator is specified, Exim looks to see |
| 6670 | if the rest of the string is precisely one IPv6 address. In this case, it does |
| 6671 | not treat it as a list. |
| 6672 | |
| 6673 | The data from each lookup is concatenated, with newline separators by default, |
| 6674 | in the same way that multiple DNS records for a single item are handled. A |
| 6675 | different separator can be specified, as described above. |
| 6676 | |
| 6677 | |
| 6678 | 9.14 More about LDAP |
| 6679 | -------------------- |
| 6680 | |
| 6681 | The original LDAP implementation came from the University of Michigan; this has |
| 6682 | become "Open LDAP", and there are now two different releases. Another |
| 6683 | implementation comes from Netscape, and Solaris 7 and subsequent releases |
| 6684 | contain inbuilt LDAP support. Unfortunately, though these are all compatible at |
| 6685 | the lookup function level, their error handling is different. For this reason |
| 6686 | it is necessary to set a compile-time variable when building Exim with LDAP, to |
| 6687 | indicate which LDAP library is in use. One of the following should appear in |
| 6688 | your Local/Makefile: |
| 6689 | |
| 6690 | LDAP_LIB_TYPE=UMICHIGAN |
| 6691 | LDAP_LIB_TYPE=OPENLDAP1 |
| 6692 | LDAP_LIB_TYPE=OPENLDAP2 |
| 6693 | LDAP_LIB_TYPE=NETSCAPE |
| 6694 | LDAP_LIB_TYPE=SOLARIS |
| 6695 | |
| 6696 | If LDAP_LIB_TYPE is not set, Exim assumes "OPENLDAP1", which has the same |
| 6697 | interface as the University of Michigan version. |
| 6698 | |
| 6699 | There are three LDAP lookup types in Exim. These behave slightly differently in |
| 6700 | the way they handle the results of a query: |
| 6701 | |
| 6702 | * ldap requires the result to contain just one entry; if there are more, it |
| 6703 | gives an error. |
| 6704 | |
| 6705 | * ldapdn also requires the result to contain just one entry, but it is the |
| 6706 | Distinguished Name that is returned rather than any attribute values. |
| 6707 | |
| 6708 | * ldapm permits the result to contain more than one entry; the attributes |
| 6709 | from all of them are returned. |
| 6710 | |
| 6711 | For ldap and ldapm, if a query finds only entries with no attributes, Exim |
| 6712 | behaves as if the entry did not exist, and the lookup fails. The format of the |
| 6713 | data returned by a successful lookup is described in the next section. First we |
| 6714 | explain how LDAP queries are coded. |
| 6715 | |
| 6716 | |
| 6717 | 9.15 Format of LDAP queries |
| 6718 | --------------------------- |
| 6719 | |
| 6720 | An LDAP query takes the form of a URL as defined in RFC 2255. For example, in |
| 6721 | the configuration of a redirect router one might have this setting: |
| 6722 | |
| 6723 | data = ${lookup ldap \ |
| 6724 | {ldap:///cn=$local_part,o=University%20of%20Cambridge,\ |
| 6725 | c=UK?mailbox?base?}} |
| 6726 | |
| 6727 | The URL may begin with "ldap" or "ldaps" if your LDAP library supports secure |
| 6728 | (encrypted) LDAP connections. The second of these ensures that an encrypted TLS |
| 6729 | connection is used. |
| 6730 | |
| 6731 | With sufficiently modern LDAP libraries, Exim supports forcing TLS over regular |
| 6732 | LDAP connections, rather than the SSL-on-connect "ldaps". See the |
| 6733 | ldap_start_tls option. |
| 6734 | |
| 6735 | Starting with Exim 4.83, the initialization of LDAP with TLS is more tightly |
| 6736 | controlled. Every part of the TLS configuration can be configured by settings |
| 6737 | in exim.conf. Depending on the version of the client libraries installed on |
| 6738 | your system, some of the initialization may have required setting options in / |
| 6739 | etc/ldap.conf or ~/.ldaprc to get TLS working with self-signed certificates. |
| 6740 | This revealed a nuance where the current UID that exim was running as could |
| 6741 | affect which config files it read. With Exim 4.83, these methods become |
| 6742 | optional, only taking effect if not specifically set in exim.conf. |
| 6743 | |
| 6744 | |
| 6745 | 9.16 LDAP quoting |
| 6746 | ----------------- |
| 6747 | |
| 6748 | Two levels of quoting are required in LDAP queries, the first for LDAP itself |
| 6749 | and the second because the LDAP query is represented as a URL. Furthermore, |
| 6750 | within an LDAP query, two different kinds of quoting are required. For this |
| 6751 | reason, there are two different LDAP-specific quoting operators. |
| 6752 | |
| 6753 | The quote_ldap operator is designed for use on strings that are part of filter |
| 6754 | specifications. Conceptually, it first does the following conversions on the |
| 6755 | string: |
| 6756 | |
| 6757 | * => \2A |
| 6758 | ( => \28 |
| 6759 | ) => \29 |
| 6760 | \ => \5C |
| 6761 | |
| 6762 | in accordance with RFC 2254. The resulting string is then quoted according to |
| 6763 | the rules for URLs, that is, all non-alphanumeric characters except |
| 6764 | |
| 6765 | ! $ ' - . _ ( ) * + |
| 6766 | |
| 6767 | are converted to their hex values, preceded by a percent sign. For example: |
| 6768 | |
| 6769 | ${quote_ldap: a(bc)*, a<yz>; } |
| 6770 | |
| 6771 | yields |
| 6772 | |
| 6773 | %20a%5C28bc%5C29%5C2A%2C%20a%3Cyz%3E%3B%20 |
| 6774 | |
| 6775 | Removing the URL quoting, this is (with a leading and a trailing space): |
| 6776 | |
| 6777 | a\28bc\29\2A, a<yz>; |
| 6778 | |
| 6779 | The quote_ldap_dn operator is designed for use on strings that are part of base |
| 6780 | DN specifications in queries. Conceptually, it first converts the string by |
| 6781 | inserting a backslash in front of any of the following characters: |
| 6782 | |
| 6783 | , + " \ < > ; |
| 6784 | |
| 6785 | It also inserts a backslash before any leading spaces or # characters, and |
| 6786 | before any trailing spaces. (These rules are in RFC 2253.) The resulting string |
| 6787 | is then quoted according to the rules for URLs. For example: |
| 6788 | |
| 6789 | ${quote_ldap_dn: a(bc)*, a<yz>; } |
| 6790 | |
| 6791 | yields |
| 6792 | |
| 6793 | %5C%20a(bc)*%5C%2C%20a%5C%3Cyz%5C%3E%5C%3B%5C%20 |
| 6794 | |
| 6795 | Removing the URL quoting, this is (with a trailing space): |
| 6796 | |
| 6797 | \ a(bc)*\, a\<yz\>\;\ |
| 6798 | |
| 6799 | There are some further comments about quoting in the section on LDAP |
| 6800 | authentication below. |
| 6801 | |
| 6802 | |
| 6803 | 9.17 LDAP connections |
| 6804 | --------------------- |
| 6805 | |
| 6806 | The connection to an LDAP server may either be over TCP/IP, or, when OpenLDAP |
| 6807 | is in use, via a Unix domain socket. The example given above does not specify |
| 6808 | an LDAP server. A server that is reached by TCP/IP can be specified in a query |
| 6809 | by starting it with |
| 6810 | |
| 6811 | ldap://<hostname>:<port>/... |
| 6812 | |
| 6813 | If the port (and preceding colon) are omitted, the standard LDAP port (389) is |
| 6814 | used. When no server is specified in a query, a list of default servers is |
| 6815 | taken from the ldap_default_servers configuration option. This supplies a |
| 6816 | colon-separated list of servers which are tried in turn until one successfully |
| 6817 | handles a query, or there is a serious error. Successful handling either |
| 6818 | returns the requested data, or indicates that it does not exist. Serious errors |
| 6819 | are syntactical, or multiple values when only a single value is expected. |
| 6820 | Errors which cause the next server to be tried are connection failures, bind |
| 6821 | failures, and timeouts. |
| 6822 | |
| 6823 | For each server name in the list, a port number can be given. The standard way |
| 6824 | of specifying a host and port is to use a colon separator (RFC 1738). Because |
| 6825 | ldap_default_servers is a colon-separated list, such colons have to be doubled. |
| 6826 | For example |
| 6827 | |
| 6828 | ldap_default_servers = ldap1.example.com::145:ldap2.example.com |
| 6829 | |
| 6830 | If ldap_default_servers is unset, a URL with no server name is passed to the |
| 6831 | LDAP library with no server name, and the library's default (normally the local |
| 6832 | host) is used. |
| 6833 | |
| 6834 | If you are using the OpenLDAP library, you can connect to an LDAP server using |
| 6835 | a Unix domain socket instead of a TCP/IP connection. This is specified by using |
| 6836 | "ldapi" instead of "ldap" in LDAP queries. What follows here applies only to |
| 6837 | OpenLDAP. If Exim is compiled with a different LDAP library, this feature is |
| 6838 | not available. |
| 6839 | |
| 6840 | For this type of connection, instead of a host name for the server, a pathname |
| 6841 | for the socket is required, and the port number is not relevant. The pathname |
| 6842 | can be specified either as an item in ldap_default_servers, or inline in the |
| 6843 | query. In the former case, you can have settings such as |
| 6844 | |
| 6845 | ldap_default_servers = /tmp/ldap.sock : backup.ldap.your.domain |
| 6846 | |
| 6847 | When the pathname is given in the query, you have to escape the slashes as |
| 6848 | "%2F" to fit in with the LDAP URL syntax. For example: |
| 6849 | |
| 6850 | ${lookup ldap {ldapi://%2Ftmp%2Fldap.sock/o=... |
| 6851 | |
| 6852 | When Exim processes an LDAP lookup and finds that the "hostname" is really a |
| 6853 | pathname, it uses the Unix domain socket code, even if the query actually |
| 6854 | specifies "ldap" or "ldaps". In particular, no encryption is used for a socket |
| 6855 | connection. This behaviour means that you can use a setting of |
| 6856 | ldap_default_servers such as in the example above with traditional "ldap" or |
| 6857 | "ldaps" queries, and it will work. First, Exim tries a connection via the Unix |
| 6858 | domain socket; if that fails, it tries a TCP/IP connection to the backup host. |
| 6859 | |
| 6860 | If an explicit "ldapi" type is given in a query when a host name is specified, |
| 6861 | an error is diagnosed. However, if there are more items in ldap_default_servers |
| 6862 | , they are tried. In other words: |
| 6863 | |
| 6864 | * Using a pathname with "ldap" or "ldaps" forces the use of the Unix domain |
| 6865 | interface. |
| 6866 | |
| 6867 | * Using "ldapi" with a host name causes an error. |
| 6868 | |
| 6869 | Using "ldapi" with no host or path in the query, and no setting of |
| 6870 | ldap_default_servers, does whatever the library does by default. |
| 6871 | |
| 6872 | |
| 6873 | 9.18 LDAP authentication and control information |
| 6874 | ------------------------------------------------ |
| 6875 | |
| 6876 | The LDAP URL syntax provides no way of passing authentication and other control |
| 6877 | information to the server. To make this possible, the URL in an LDAP query may |
| 6878 | be preceded by any number of <name>=<value> settings, separated by spaces. If a |
| 6879 | value contains spaces it must be enclosed in double quotes, and when double |
| 6880 | quotes are used, backslash is interpreted in the usual way inside them. The |
| 6881 | following names are recognized: |
| 6882 | |
| 6883 | DEREFERENCE set the dereferencing parameter |
| 6884 | NETTIME set a timeout for a network operation |
| 6885 | USER set the DN, for authenticating the LDAP bind |
| 6886 | PASS set the password, likewise |
| 6887 | REFERRALS set the referrals parameter |
| 6888 | SERVERS set alternate server list for this query only |
| 6889 | SIZE set the limit for the number of entries returned |
| 6890 | TIME set the maximum waiting time for a query |
| 6891 | |
| 6892 | The value of the DEREFERENCE parameter must be one of the words "never", |
| 6893 | "searching", "finding", or "always". The value of the REFERRALS parameter must |
| 6894 | be "follow" (the default) or "nofollow". The latter stops the LDAP library from |
| 6895 | trying to follow referrals issued by the LDAP server. |
| 6896 | |
| 6897 | The name CONNECT is an obsolete name for NETTIME, retained for backwards |
| 6898 | compatibility. This timeout (specified as a number of seconds) is enforced from |
| 6899 | the client end for operations that can be carried out over a network. |
| 6900 | Specifically, it applies to network connections and calls to the ldap_result() |
| 6901 | function. If the value is greater than zero, it is used if |
| 6902 | LDAP_OPT_NETWORK_TIMEOUT is defined in the LDAP headers (OpenLDAP), or if |
| 6903 | LDAP_X_OPT_CONNECT_TIMEOUT is defined in the LDAP headers (Netscape SDK 4.1). A |
| 6904 | value of zero forces an explicit setting of "no timeout" for Netscape SDK; for |
| 6905 | OpenLDAP no action is taken. |
| 6906 | |
| 6907 | The TIME parameter (also a number of seconds) is passed to the server to set a |
| 6908 | server-side limit on the time taken to complete a search. |
| 6909 | |
| 6910 | The SERVERS parameter allows you to specify an alternate list of ldap servers |
| 6911 | to use for an individual lookup. The global ldap_default_servers option |
| 6912 | provides a default list of ldap servers, and a single lookup can specify a |
| 6913 | single ldap server to use. But when you need to do a lookup with a list of |
| 6914 | servers that is different than the default list (maybe different order, maybe a |
| 6915 | completely different set of servers), the SERVERS parameter allows you to |
| 6916 | specify this alternate list (colon-separated). |
| 6917 | |
| 6918 | Here is an example of an LDAP query in an Exim lookup that uses some of these |
| 6919 | values. This is a single line, folded to fit on the page: |
| 6920 | |
| 6921 | ${lookup ldap |
| 6922 | {user="cn=manager,o=University of Cambridge,c=UK" pass=secret |
| 6923 | ldap:///o=University%20of%20Cambridge,c=UK?sn?sub?(cn=foo)} |
| 6924 | {$value}fail} |
| 6925 | |
| 6926 | The encoding of spaces as "%20" is a URL thing which should not be done for any |
| 6927 | of the auxiliary data. Exim configuration settings that include lookups which |
| 6928 | contain password information should be preceded by "hide" to prevent non-admin |
| 6929 | users from using the -bP option to see their values. |
| 6930 | |
| 6931 | The auxiliary data items may be given in any order. The default is no |
| 6932 | connection timeout (the system timeout is used), no user or password, no limit |
| 6933 | on the number of entries returned, and no time limit on queries. |
| 6934 | |
| 6935 | When a DN is quoted in the USER= setting for LDAP authentication, Exim removes |
| 6936 | any URL quoting that it may contain before passing it LDAP. Apparently some |
| 6937 | libraries do this for themselves, but some do not. Removing the URL quoting has |
| 6938 | two advantages: |
| 6939 | |
| 6940 | * It makes it possible to use the same quote_ldap_dn expansion for USER= DNs |
| 6941 | as with DNs inside actual queries. |
| 6942 | |
| 6943 | * It permits spaces inside USER= DNs. |
| 6944 | |
| 6945 | For example, a setting such as |
| 6946 | |
| 6947 | USER=cn=${quote_ldap_dn:$1} |
| 6948 | |
| 6949 | should work even if $1 contains spaces. |
| 6950 | |
| 6951 | Expanded data for the PASS= value should be quoted using the quote expansion |
| 6952 | operator, rather than the LDAP quote operators. The only reason this field |
| 6953 | needs quoting is to ensure that it conforms to the Exim syntax, which does not |
| 6954 | allow unquoted spaces. For example: |
| 6955 | |
| 6956 | PASS=${quote:$3} |
| 6957 | |
| 6958 | The LDAP authentication mechanism can be used to check passwords as part of |
| 6959 | SMTP authentication. See the ldapauth expansion string condition in chapter 11. |
| 6960 | |
| 6961 | |
| 6962 | 9.19 Format of data returned by LDAP |
| 6963 | ------------------------------------ |
| 6964 | |
| 6965 | The ldapdn lookup type returns the Distinguished Name from a single entry as a |
| 6966 | sequence of values, for example |
| 6967 | |
| 6968 | cn=manager,o=University of Cambridge,c=UK |
| 6969 | |
| 6970 | The ldap lookup type generates an error if more than one entry matches the |
| 6971 | search filter, whereas ldapm permits this case, and inserts a newline in the |
| 6972 | result between the data from different entries. It is possible for multiple |
| 6973 | values to be returned for both ldap and ldapm, but in the former case you know |
| 6974 | that whatever values are returned all came from a single entry in the |
| 6975 | directory. |
| 6976 | |
| 6977 | In the common case where you specify a single attribute in your LDAP query, the |
| 6978 | result is not quoted, and does not contain the attribute name. If the attribute |
| 6979 | has multiple values, they are separated by commas. Any comma that is part of an |
| 6980 | attribute's value is doubled. |
| 6981 | |
| 6982 | If you specify multiple attributes, the result contains space-separated, quoted |
| 6983 | strings, each preceded by the attribute name and an equals sign. Within the |
| 6984 | quotes, the quote character, backslash, and newline are escaped with |
| 6985 | backslashes, and commas are used to separate multiple values for the attribute. |
| 6986 | Any commas in attribute values are doubled (permitting treatment of the values |
| 6987 | as a comma-separated list). Apart from the escaping, the string within quotes |
| 6988 | takes the same form as the output when a single attribute is requested. |
| 6989 | Specifying no attributes is the same as specifying all of an entry's |
| 6990 | attributes. |
| 6991 | |
| 6992 | Here are some examples of the output format. The first line of each pair is an |
| 6993 | LDAP query, and the second is the data that is returned. The attribute called |
| 6994 | attr1 has two values, one of them with an embedded comma, whereas attr2 has |
| 6995 | only one value. Both attributes are derived from attr (they have SUP attr in |
| 6996 | their schema definitions). |
| 6997 | |
| 6998 | ldap:///o=base?attr1?sub?(uid=fred) |
| 6999 | value1.1,value1,,2 |
| 7000 | |
| 7001 | ldap:///o=base?attr2?sub?(uid=fred) |
| 7002 | value two |
| 7003 | |
| 7004 | ldap:///o=base?attr?sub?(uid=fred) |
| 7005 | value1.1,value1,,2,value two |
| 7006 | |
| 7007 | ldap:///o=base?attr1,attr2?sub?(uid=fred) |
| 7008 | attr1="value1.1,value1,,2" attr2="value two" |
| 7009 | |
| 7010 | ldap:///o=base??sub?(uid=fred) |
| 7011 | objectClass="top" attr1="value1.1,value1,,2" attr2="value two" |
| 7012 | |
| 7013 | You can make use of Exim's -be option to run expansion tests and thereby check |
| 7014 | the results of LDAP lookups. The extract operator in string expansions can be |
| 7015 | used to pick out individual fields from data that consists of key=value pairs. |
| 7016 | The listextract operator should be used to pick out individual values of |
| 7017 | attributes, even when only a single value is expected. The doubling of embedded |
| 7018 | commas allows you to use the returned data as a comma separated list (using the |
| 7019 | "<," syntax for changing the input list separator). |
| 7020 | |
| 7021 | |
| 7022 | 9.20 More about NIS+ |
| 7023 | -------------------- |
| 7024 | |
| 7025 | NIS+ queries consist of a NIS+ indexed name followed by an optional colon and |
| 7026 | field name. If this is given, the result of a successful query is the contents |
| 7027 | of the named field; otherwise the result consists of a concatenation of |
| 7028 | field-name=field-value pairs, separated by spaces. Empty values and values |
| 7029 | containing spaces are quoted. For example, the query |
| 7030 | |
| 7031 | [name=mg1456],passwd.org_dir |
| 7032 | |
| 7033 | might return the string |
| 7034 | |
| 7035 | name=mg1456 passwd="" uid=999 gid=999 gcos="Martin Guerre" |
| 7036 | home=/home/mg1456 shell=/bin/bash shadow="" |
| 7037 | |
| 7038 | (split over two lines here to fit on the page), whereas |
| 7039 | |
| 7040 | [name=mg1456],passwd.org_dir:gcos |
| 7041 | |
| 7042 | would just return |
| 7043 | |
| 7044 | Martin Guerre |
| 7045 | |
| 7046 | with no quotes. A NIS+ lookup fails if NIS+ returns more than one table entry |
| 7047 | for the given indexed key. The effect of the quote_nisplus expansion operator |
| 7048 | is to double any quote characters within the text. |
| 7049 | |
| 7050 | |
| 7051 | 9.21 SQL lookups |
| 7052 | ---------------- |
| 7053 | |
| 7054 | Exim can support lookups in InterBase, MySQL, Oracle, PostgreSQL, Redis, and |
| 7055 | SQLite databases. Queries for these databases contain SQL statements, so an |
| 7056 | example might be |
| 7057 | |
| 7058 | ${lookup mysql{select mailbox from users where id='userx'}\ |
| 7059 | {$value}fail} |
| 7060 | |
| 7061 | If the result of the query contains more than one field, the data for each |
| 7062 | field in the row is returned, preceded by its name, so the result of |
| 7063 | |
| 7064 | ${lookup pgsql{select home,name from users where id='userx'}\ |
| 7065 | {$value}} |
| 7066 | |
| 7067 | might be |
| 7068 | |
| 7069 | home=/home/userx name="Mister X" |
| 7070 | |
| 7071 | Empty values and values containing spaces are double quoted, with embedded |
| 7072 | quotes escaped by a backslash. If the result of the query contains just one |
| 7073 | field, the value is passed back verbatim, without a field name, for example: |
| 7074 | |
| 7075 | Mister X |
| 7076 | |
| 7077 | If the result of the query yields more than one row, it is all concatenated, |
| 7078 | with a newline between the data for each row. |
| 7079 | |
| 7080 | |
| 7081 | 9.22 More about MySQL, PostgreSQL, Oracle, InterBase, and Redis |
| 7082 | --------------------------------------------------------------- |
| 7083 | |
| 7084 | If any MySQL, PostgreSQL, Oracle, InterBase or Redis lookups are used, the |
| 7085 | mysql_servers, pgsql_servers, oracle_servers, ibase_servers, or redis_servers |
| 7086 | option (as appropriate) must be set to a colon-separated list of server |
| 7087 | information. (For MySQL and PostgreSQL, the global option need not be set if |
| 7088 | all queries contain their own server information - see section 9.23.) For all |
| 7089 | but Redis each item in the list is a slash-separated list of four items: host |
| 7090 | name, database name, user name, and password. In the case of Oracle, the host |
| 7091 | name field is used for the "service name", and the database name field is not |
| 7092 | used and should be empty. For example: |
| 7093 | |
| 7094 | hide oracle_servers = oracle.plc.example//userx/abcdwxyz |
| 7095 | |
| 7096 | Because password data is sensitive, you should always precede the setting with |
| 7097 | "hide", to prevent non-admin users from obtaining the setting via the -bP |
| 7098 | option. Here is an example where two MySQL servers are listed: |
| 7099 | |
| 7100 | hide mysql_servers = localhost/users/root/secret:\ |
| 7101 | otherhost/users/root/othersecret |
| 7102 | |
| 7103 | For MySQL and PostgreSQL, a host may be specified as <name>:<port> but because |
| 7104 | this is a colon-separated list, the colon has to be doubled. For each query, |
| 7105 | these parameter groups are tried in order until a connection is made and a |
| 7106 | query is successfully processed. The result of a query may be that no data is |
| 7107 | found, but that is still a successful query. In other words, the list of |
| 7108 | servers provides a backup facility, not a list of different places to look. |
| 7109 | |
| 7110 | For Redis the global option need not be specified if all queries contain their |
| 7111 | own server information - see section 9.23. If specified, the option must be set |
| 7112 | to a colon-separated list of server information. Each item in the list is a |
| 7113 | slash-separated list of three items: host, database number, and password. |
| 7114 | |
| 7115 | 1. The host is required and may be either an IPv4 address and optional port |
| 7116 | number (separated by a colon, which needs doubling due to the higher-level |
| 7117 | list), or a Unix socket pathname enclosed in parentheses |
| 7118 | |
| 7119 | 2. The database number is optional; if present that number is selected in the |
| 7120 | backend |
| 7121 | |
| 7122 | 3. The password is optional; if present it is used to authenticate to the |
| 7123 | backend |
| 7124 | |
| 7125 | The quote_mysql, quote_pgsql, and quote_oracle expansion operators convert |
| 7126 | newline, tab, carriage return, and backspace to \n, \t, \r, and \b |
| 7127 | respectively, and the characters single-quote, double-quote, and backslash |
| 7128 | itself are escaped with backslashes. |
| 7129 | |
| 7130 | The quote_redis expansion operator escapes whitespace and backslash characters |
| 7131 | with a backslash. |
| 7132 | |
| 7133 | |
| 7134 | 9.23 Specifying the server in the query |
| 7135 | --------------------------------------- |
| 7136 | |
| 7137 | For MySQL, PostgreSQL and Redis lookups (but not currently for Oracle and |
| 7138 | InterBase), it is possible to specify a list of servers with an individual |
| 7139 | query. This is done by starting the query with |
| 7140 | |
| 7141 | servers=server1:server2:server3:...; |
| 7142 | |
| 7143 | Each item in the list may take one of two forms: |
| 7144 | |
| 7145 | 1. If it contains no slashes it is assumed to be just a host name. The |
| 7146 | appropriate global option (mysql_servers or pgsql_servers) is searched for |
| 7147 | a host of the same name, and the remaining parameters (database, user, |
| 7148 | password) are taken from there. |
| 7149 | |
| 7150 | 2. If it contains any slashes, it is taken as a complete parameter set. |
| 7151 | |
| 7152 | The list of servers is used in exactly the same way as the global list. Once a |
| 7153 | connection to a server has happened and a query has been successfully executed, |
| 7154 | processing of the lookup ceases. |
| 7155 | |
| 7156 | This feature is intended for use in master/slave situations where updates are |
| 7157 | occurring and you want to update the master rather than a slave. If the master |
| 7158 | is in the list as a backup for reading, you might have a global setting like |
| 7159 | this: |
| 7160 | |
| 7161 | mysql_servers = slave1/db/name/pw:\ |
| 7162 | slave2/db/name/pw:\ |
| 7163 | master/db/name/pw |
| 7164 | |
| 7165 | In an updating lookup, you could then write: |
| 7166 | |
| 7167 | ${lookup mysql{servers=master; UPDATE ...} } |
| 7168 | |
| 7169 | That query would then be sent only to the master server. If, on the other hand, |
| 7170 | the master is not to be used for reading, and so is not present in the global |
| 7171 | option, you can still update it by a query of this form: |
| 7172 | |
| 7173 | ${lookup pgsql{servers=master/db/name/pw; UPDATE ...} } |
| 7174 | |
| 7175 | |
| 7176 | 9.24 Special MySQL features |
| 7177 | --------------------------- |
| 7178 | |
| 7179 | For MySQL, an empty host name or the use of "localhost" in mysql_servers causes |
| 7180 | a connection to the server on the local host by means of a Unix domain socket. |
| 7181 | An alternate socket can be specified in parentheses. An option group name for |
| 7182 | MySQL option files can be specified in square brackets; the default value is |
| 7183 | "exim". The full syntax of each item in mysql_servers is: |
| 7184 | |
| 7185 | <hostname>::<port>(<socket name>)[<option group>]/<database>/<user>/<password> |
| 7186 | |
| 7187 | Any of the four sub-parts of the first field can be omitted. For normal use on |
| 7188 | the local host it can be left blank or set to just "localhost". |
| 7189 | |
| 7190 | No database need be supplied - but if it is absent here, it must be given in |
| 7191 | the queries. |
| 7192 | |
| 7193 | If a MySQL query is issued that does not request any data (an insert, update, |
| 7194 | or delete command), the result of the lookup is the number of rows affected. |
| 7195 | |
| 7196 | Warning: This can be misleading. If an update does not actually change anything |
| 7197 | (for example, setting a field to the value it already has), the result is zero |
| 7198 | because no rows are affected. |
| 7199 | |
| 7200 | |
| 7201 | 9.25 Special PostgreSQL features |
| 7202 | -------------------------------- |
| 7203 | |
| 7204 | PostgreSQL lookups can also use Unix domain socket connections to the database. |
| 7205 | This is usually faster and costs less CPU time than a TCP/IP connection. |
| 7206 | However it can be used only if the mail server runs on the same machine as the |
| 7207 | database server. A configuration line for PostgreSQL via Unix domain sockets |
| 7208 | looks like this: |
| 7209 | |
| 7210 | hide pgsql_servers = (/tmp/.s.PGSQL.5432)/db/user/password : ... |
| 7211 | |
| 7212 | In other words, instead of supplying a host name, a path to the socket is |
| 7213 | given. The path name is enclosed in parentheses so that its slashes aren't |
| 7214 | visually confused with the delimiters for the other server parameters. |
| 7215 | |
| 7216 | If a PostgreSQL query is issued that does not request any data (an insert, |
| 7217 | update, or delete command), the result of the lookup is the number of rows |
| 7218 | affected. |
| 7219 | |
| 7220 | |
| 7221 | 9.26 More about SQLite |
| 7222 | ---------------------- |
| 7223 | |
| 7224 | SQLite is different to the other SQL lookups because a file name is required in |
| 7225 | addition to the SQL query. An SQLite database is a single file, and there is no |
| 7226 | daemon as in the other SQL databases. The interface to Exim requires the name |
| 7227 | of the file, as an absolute path, to be given at the start of the query. It is |
| 7228 | separated from the query by white space. This means that the path name cannot |
| 7229 | contain white space. Here is a lookup expansion example: |
| 7230 | |
| 7231 | ${lookup sqlite {/some/thing/sqlitedb \ |
| 7232 | select name from aliases where id='userx';}} |
| 7233 | |
| 7234 | In a list, the syntax is similar. For example: |
| 7235 | |
| 7236 | domainlist relay_to_domains = sqlite;/some/thing/sqlitedb \ |
| 7237 | select * from relays where ip='$sender_host_address'; |
| 7238 | |
| 7239 | The only character affected by the quote_sqlite operator is a single quote, |
| 7240 | which it doubles. |
| 7241 | |
| 7242 | The SQLite library handles multiple simultaneous accesses to the database |
| 7243 | internally. Multiple readers are permitted, but only one process can update at |
| 7244 | once. Attempts to access the database while it is being updated are rejected |
| 7245 | after a timeout period, during which the SQLite library waits for the lock to |
| 7246 | be released. In Exim, the default timeout is set to 5 seconds, but it can be |
| 7247 | changed by means of the sqlite_lock_timeout option. |
| 7248 | |
| 7249 | |
| 7250 | 9.27 More about Redis |
| 7251 | --------------------- |
| 7252 | |
| 7253 | Redis is a non-SQL database. Commands are simple get and set. Examples: |
| 7254 | |
| 7255 | ${lookup redis{set keyname ${quote_redis:objvalue plus}}} |
| 7256 | ${lookup redis{get keyname}} |
| 7257 | |
| 7258 | |
| 7259 | |
| 7260 | =============================================================================== |
| 7261 | 10. DOMAIN, HOST, ADDRESS, AND LOCAL PART LISTS |
| 7262 | |
| 7263 | A number of Exim configuration options contain lists of domains, hosts, email |
| 7264 | addresses, or local parts. For example, the hold_domains option contains a list |
| 7265 | of domains whose delivery is currently suspended. These lists are also used as |
| 7266 | data in ACL statements (see chapter 43), and as arguments to expansion |
| 7267 | conditions such as match_domain. |
| 7268 | |
| 7269 | Each item in one of these lists is a pattern to be matched against a domain, |
| 7270 | host, email address, or local part, respectively. In the sections below, the |
| 7271 | different types of pattern for each case are described, but first we cover some |
| 7272 | general facilities that apply to all four kinds of list. |
| 7273 | |
| 7274 | Note that other parts of Exim use a string list which does not support all the |
| 7275 | complexity available in domain, host, address and local part lists. |
| 7276 | |
| 7277 | |
| 7278 | 10.1 Expansion of lists |
| 7279 | ----------------------- |
| 7280 | |
| 7281 | Each list is expanded as a single string before it is used. |
| 7282 | |
| 7283 | Exception: the router headers_remove option, where list-item splitting is done |
| 7284 | before string-expansion. |
| 7285 | |
| 7286 | The result of expansion must be a list, possibly containing empty items, which |
| 7287 | is split up into separate items for matching. By default, colon is the |
| 7288 | separator character, but this can be varied if necessary. See sections 6.20 and |
| 7289 | 6.22 for details of the list syntax; the second of these discusses the way to |
| 7290 | specify empty list items. |
| 7291 | |
| 7292 | If the string expansion is forced to fail, Exim behaves as if the item it is |
| 7293 | testing (domain, host, address, or local part) is not in the list. Other |
| 7294 | expansion failures cause temporary errors. |
| 7295 | |
| 7296 | If an item in a list is a regular expression, backslashes, dollars and possibly |
| 7297 | other special characters in the expression must be protected against |
| 7298 | misinterpretation by the string expander. The easiest way to do this is to use |
| 7299 | the "\N" expansion feature to indicate that the contents of the regular |
| 7300 | expression should not be expanded. For example, in an ACL you might have: |
| 7301 | |
| 7302 | deny senders = \N^\d{8}\w@.*\.baddomain\.example$\N : \ |
| 7303 | ${lookup{$domain}lsearch{/badsenders/bydomain}} |
| 7304 | |
| 7305 | The first item is a regular expression that is protected from expansion by "\ |
| 7306 | N", whereas the second uses the expansion to obtain a list of unwanted senders |
| 7307 | based on the receiving domain. |
| 7308 | |
| 7309 | |
| 7310 | 10.2 Negated items in lists |
| 7311 | --------------------------- |
| 7312 | |
| 7313 | Items in a list may be positive or negative. Negative items are indicated by a |
| 7314 | leading exclamation mark, which may be followed by optional white space. A list |
| 7315 | defines a set of items (domains, etc). When Exim processes one of these lists, |
| 7316 | it is trying to find out whether a domain, host, address, or local part |
| 7317 | (respectively) is in the set that is defined by the list. It works like this: |
| 7318 | |
| 7319 | The list is scanned from left to right. If a positive item is matched, the |
| 7320 | subject that is being checked is in the set; if a negative item is matched, the |
| 7321 | subject is not in the set. If the end of the list is reached without the |
| 7322 | subject having matched any of the patterns, it is in the set if the last item |
| 7323 | was a negative one, but not if it was a positive one. For example, the list in |
| 7324 | |
| 7325 | domainlist relay_to_domains = !a.b.c : *.b.c |
| 7326 | |
| 7327 | matches any domain ending in .b.c except for a.b.c. Domains that match neither |
| 7328 | a.b.c nor *.b.c do not match, because the last item in the list is positive. |
| 7329 | However, if the setting were |
| 7330 | |
| 7331 | domainlist relay_to_domains = !a.b.c |
| 7332 | |
| 7333 | then all domains other than a.b.c would match because the last item in the list |
| 7334 | is negative. In other words, a list that ends with a negative item behaves as |
| 7335 | if it had an extra item ":*" on the end. |
| 7336 | |
| 7337 | Another way of thinking about positive and negative items in lists is to read |
| 7338 | the connector as "or" after a positive item and as "and" after a negative item. |
| 7339 | |
| 7340 | |
| 7341 | 10.3 File names in lists |
| 7342 | ------------------------ |
| 7343 | |
| 7344 | If an item in a domain, host, address, or local part list is an absolute file |
| 7345 | name (beginning with a slash character), each line of the file is read and |
| 7346 | processed as if it were an independent item in the list, except that further |
| 7347 | file names are not allowed, and no expansion of the data from the file takes |
| 7348 | place. Empty lines in the file are ignored, and the file may also contain |
| 7349 | comment lines: |
| 7350 | |
| 7351 | * For domain and host lists, if a # character appears anywhere in a line of |
| 7352 | the file, it and all following characters are ignored. |
| 7353 | |
| 7354 | * Because local parts may legitimately contain # characters, a comment in an |
| 7355 | address list or local part list file is recognized only if # is preceded by |
| 7356 | white space or the start of the line. For example: |
| 7357 | |
| 7358 | not#comment@x.y.z # but this is a comment |
| 7359 | |
| 7360 | Putting a file name in a list has the same effect as inserting each line of the |
| 7361 | file as an item in the list (blank lines and comments excepted). However, there |
| 7362 | is one important difference: the file is read each time the list is processed, |
| 7363 | so if its contents vary over time, Exim's behaviour changes. |
| 7364 | |
| 7365 | If a file name is preceded by an exclamation mark, the sense of any match |
| 7366 | within the file is inverted. For example, if |
| 7367 | |
| 7368 | hold_domains = !/etc/nohold-domains |
| 7369 | |
| 7370 | and the file contains the lines |
| 7371 | |
| 7372 | !a.b.c |
| 7373 | *.b.c |
| 7374 | |
| 7375 | then a.b.c is in the set of domains defined by hold_domains, whereas any domain |
| 7376 | matching "*.b.c" is not. |
| 7377 | |
| 7378 | |
| 7379 | 10.4 An lsearch file is not an out-of-line list |
| 7380 | ----------------------------------------------- |
| 7381 | |
| 7382 | As will be described in the sections that follow, lookups can be used in lists |
| 7383 | to provide indexed methods of checking list membership. There has been some |
| 7384 | confusion about the way lsearch lookups work in lists. Because an lsearch file |
| 7385 | contains plain text and is scanned sequentially, it is sometimes thought that |
| 7386 | it is allowed to contain wild cards and other kinds of non-constant pattern. |
| 7387 | This is not the case. The keys in an lsearch file are always fixed strings, |
| 7388 | just as for any other single-key lookup type. |
| 7389 | |
| 7390 | If you want to use a file to contain wild-card patterns that form part of a |
| 7391 | list, just give the file name on its own, without a search type, as described |
| 7392 | in the previous section. You could also use the wildlsearch or nwildlsearch, |
| 7393 | but there is no advantage in doing this. |
| 7394 | |
| 7395 | |
| 7396 | 10.5 Named lists |
| 7397 | ---------------- |
| 7398 | |
| 7399 | A list of domains, hosts, email addresses, or local parts can be given a name |
| 7400 | which is then used to refer to the list elsewhere in the configuration. This is |
| 7401 | particularly convenient if the same list is required in several different |
| 7402 | places. It also allows lists to be given meaningful names, which can improve |
| 7403 | the readability of the configuration. For example, it is conventional to define |
| 7404 | a domain list called local_domains for all the domains that are handled locally |
| 7405 | on a host, using a configuration line such as |
| 7406 | |
| 7407 | domainlist local_domains = localhost:my.dom.example |
| 7408 | |
| 7409 | Named lists are referenced by giving their name preceded by a plus sign, so, |
| 7410 | for example, a router that is intended to handle local domains would be |
| 7411 | configured with the line |
| 7412 | |
| 7413 | domains = +local_domains |
| 7414 | |
| 7415 | The first router in a configuration is often one that handles all domains |
| 7416 | except the local ones, using a configuration with a negated item like this: |
| 7417 | |
| 7418 | dnslookup: |
| 7419 | driver = dnslookup |
| 7420 | domains = ! +local_domains |
| 7421 | transport = remote_smtp |
| 7422 | no_more |
| 7423 | |
| 7424 | The four kinds of named list are created by configuration lines starting with |
| 7425 | the words domainlist, hostlist, addresslist, or localpartlist, respectively. |
| 7426 | Then there follows the name that you are defining, followed by an equals sign |
| 7427 | and the list itself. For example: |
| 7428 | |
| 7429 | hostlist relay_from_hosts = 192.168.23.0/24 : my.friend.example |
| 7430 | addresslist bad_senders = cdb;/etc/badsenders |
| 7431 | |
| 7432 | A named list may refer to other named lists: |
| 7433 | |
| 7434 | domainlist dom1 = first.example : second.example |
| 7435 | domainlist dom2 = +dom1 : third.example |
| 7436 | domainlist dom3 = fourth.example : +dom2 : fifth.example |
| 7437 | |
| 7438 | Warning: If the last item in a referenced list is a negative one, the effect |
| 7439 | may not be what you intended, because the negation does not propagate out to |
| 7440 | the higher level. For example, consider: |
| 7441 | |
| 7442 | domainlist dom1 = !a.b |
| 7443 | domainlist dom2 = +dom1 : *.b |
| 7444 | |
| 7445 | The second list specifies "either in the dom1 list or *.b". The first list |
| 7446 | specifies just "not a.b", so the domain x.y matches it. That means it matches |
| 7447 | the second list as well. The effect is not the same as |
| 7448 | |
| 7449 | domainlist dom2 = !a.b : *.b |
| 7450 | |
| 7451 | where x.y does not match. It's best to avoid negation altogether in referenced |
| 7452 | lists if you can. |
| 7453 | |
| 7454 | Named lists may have a performance advantage. When Exim is routing an address |
| 7455 | or checking an incoming message, it caches the result of tests on named lists. |
| 7456 | So, if you have a setting such as |
| 7457 | |
| 7458 | domains = +local_domains |
| 7459 | |
| 7460 | on several of your routers or in several ACL statements, the actual test is |
| 7461 | done only for the first one. However, the caching works only if there are no |
| 7462 | expansions within the list itself or any sublists that it references. In other |
| 7463 | words, caching happens only for lists that are known to be the same each time |
| 7464 | they are referenced. |
| 7465 | |
| 7466 | By default, there may be up to 16 named lists of each type. This limit can be |
| 7467 | extended by changing a compile-time variable. The use of domain and host lists |
| 7468 | is recommended for concepts such as local domains, relay domains, and relay |
| 7469 | hosts. The default configuration is set up like this. |
| 7470 | |
| 7471 | |
| 7472 | 10.6 Named lists compared with macros |
| 7473 | ------------------------------------- |
| 7474 | |
| 7475 | At first sight, named lists might seem to be no different from macros in the |
| 7476 | configuration file. However, macros are just textual substitutions. If you |
| 7477 | write |
| 7478 | |
| 7479 | ALIST = host1 : host2 |
| 7480 | auth_advertise_hosts = !ALIST |
| 7481 | |
| 7482 | it probably won't do what you want, because that is exactly the same as |
| 7483 | |
| 7484 | auth_advertise_hosts = !host1 : host2 |
| 7485 | |
| 7486 | Notice that the second host name is not negated. However, if you use a host |
| 7487 | list, and write |
| 7488 | |
| 7489 | hostlist alist = host1 : host2 |
| 7490 | auth_advertise_hosts = ! +alist |
| 7491 | |
| 7492 | the negation applies to the whole list, and so that is equivalent to |
| 7493 | |
| 7494 | auth_advertise_hosts = !host1 : !host2 |
| 7495 | |
| 7496 | |
| 7497 | 10.7 Named list caching |
| 7498 | ----------------------- |
| 7499 | |
| 7500 | While processing a message, Exim caches the result of checking a named list if |
| 7501 | it is sure that the list is the same each time. In practice, this means that |
| 7502 | the cache operates only if the list contains no $ characters, which guarantees |
| 7503 | that it will not change when it is expanded. Sometimes, however, you may have |
| 7504 | an expanded list that you know will be the same each time within a given |
| 7505 | message. For example: |
| 7506 | |
| 7507 | domainlist special_domains = \ |
| 7508 | ${lookup{$sender_host_address}cdb{/some/file}} |
| 7509 | |
| 7510 | This provides a list of domains that depends only on the sending host's IP |
| 7511 | address. If this domain list is referenced a number of times (for example, in |
| 7512 | several ACL lines, or in several routers) the result of the check is not cached |
| 7513 | by default, because Exim does not know that it is going to be the same list |
| 7514 | each time. |
| 7515 | |
| 7516 | By appending "_cache" to "domainlist" you can tell Exim to go ahead and cache |
| 7517 | the result anyway. For example: |
| 7518 | |
| 7519 | domainlist_cache special_domains = ${lookup{... |
| 7520 | |
| 7521 | If you do this, you should be absolutely sure that caching is going to do the |
| 7522 | right thing in all cases. When in doubt, leave it out. |
| 7523 | |
| 7524 | |
| 7525 | 10.8 Domain lists |
| 7526 | ----------------- |
| 7527 | |
| 7528 | Domain lists contain patterns that are to be matched against a mail domain. The |
| 7529 | following types of item may appear in domain lists: |
| 7530 | |
| 7531 | * If a pattern consists of a single @ character, it matches the local host |
| 7532 | name, as set by the primary_hostname option (or defaulted). This makes it |
| 7533 | possible to use the same configuration file on several different hosts that |
| 7534 | differ only in their names. |
| 7535 | |
| 7536 | * If a pattern consists of the string "@[]" it matches an IP address enclosed |
| 7537 | in square brackets (as in an email address that contains a domain literal), |
| 7538 | but only if that IP address is recognized as local for email routing |
| 7539 | purposes. The local_interfaces and extra_local_interfaces options can be |
| 7540 | used to control which of a host's several IP addresses are treated as |
| 7541 | local. In today's Internet, the use of domain literals is controversial. |
| 7542 | |
| 7543 | * If a pattern consists of the string "@mx_any" it matches any domain that |
| 7544 | has an MX record pointing to the local host or to any host that is listed |
| 7545 | in hosts_treat_as_local. The items "@mx_primary" and "@mx_secondary" are |
| 7546 | similar, except that the first matches only when a primary MX target is the |
| 7547 | local host, and the second only when no primary MX target is the local |
| 7548 | host, but a secondary MX target is. "Primary" means an MX record with the |
| 7549 | lowest preference value - there may of course be more than one of them. |
| 7550 | |
| 7551 | The MX lookup that takes place when matching a pattern of this type is |
| 7552 | performed with the resolver options for widening names turned off. Thus, |
| 7553 | for example, a single-component domain will not be expanded by adding the |
| 7554 | resolver's default domain. See the qualify_single and search_parents |
| 7555 | options of the dnslookup router for a discussion of domain widening. |
| 7556 | |
| 7557 | Sometimes you may want to ignore certain IP addresses when using one of |
| 7558 | these patterns. You can specify this by following the pattern with "/ignore |
| 7559 | ="<ip list>, where <ip list> is a list of IP addresses. These addresses are |
| 7560 | ignored when processing the pattern (compare the ignore_target_hosts option |
| 7561 | on a router). For example: |
| 7562 | |
| 7563 | domains = @mx_any/ignore=127.0.0.1 |
| 7564 | |
| 7565 | This example matches any domain that has an MX record pointing to one of |
| 7566 | the local host's IP addresses other than 127.0.0.1. |
| 7567 | |
| 7568 | The list of IP addresses is in fact processed by the same code that |
| 7569 | processes host lists, so it may contain CIDR-coded network specifications |
| 7570 | and it may also contain negative items. |
| 7571 | |
| 7572 | Because the list of IP addresses is a sublist within a domain list, you |
| 7573 | have to be careful about delimiters if there is more than one address. Like |
| 7574 | any other list, the default delimiter can be changed. Thus, you might have: |
| 7575 | |
| 7576 | domains = @mx_any/ignore=<;127.0.0.1;0.0.0.0 : \ |
| 7577 | an.other.domain : ... |
| 7578 | |
| 7579 | so that the sublist uses semicolons for delimiters. When IPv6 addresses are |
| 7580 | involved, it is easiest to change the delimiter for the main list as well: |
| 7581 | |
| 7582 | domains = <? @mx_any/ignore=<;127.0.0.1;::1 ? \ |
| 7583 | an.other.domain ? ... |
| 7584 | |
| 7585 | * If a pattern starts with an asterisk, the remaining characters of the |
| 7586 | pattern are compared with the terminating characters of the domain. The use |
| 7587 | of "*" in domain lists differs from its use in partial matching lookups. In |
| 7588 | a domain list, the character following the asterisk need not be a dot, |
| 7589 | whereas partial matching works only in terms of dot-separated components. |
| 7590 | For example, a domain list item such as "*key.ex" matches donkey.ex as well |
| 7591 | as cipher.key.ex. |
| 7592 | |
| 7593 | * If a pattern starts with a circumflex character, it is treated as a regular |
| 7594 | expression, and matched against the domain using a regular expression |
| 7595 | matching function. The circumflex is treated as part of the regular |
| 7596 | expression. Email domains are case-independent, so this regular expression |
| 7597 | match is by default case-independent, but you can make it case-dependent by |
| 7598 | starting it with "(?-i)". References to descriptions of the syntax of |
| 7599 | regular expressions are given in chapter 8. |
| 7600 | |
| 7601 | Warning: Because domain lists are expanded before being processed, you must |
| 7602 | escape any backslash and dollar characters in the regular expression, or |
| 7603 | use the special "\N" sequence (see chapter 11) to specify that it is not to |
| 7604 | be expanded (unless you really do want to build a regular expression by |
| 7605 | expansion, of course). |
| 7606 | |
| 7607 | * If a pattern starts with the name of a single-key lookup type followed by a |
| 7608 | semicolon (for example, "dbm;" or "lsearch;"), the remainder of the pattern |
| 7609 | must be a file name in a suitable format for the lookup type. For example, |
| 7610 | for "cdb;" it must be an absolute path: |
| 7611 | |
| 7612 | domains = cdb;/etc/mail/local_domains.cdb |
| 7613 | |
| 7614 | The appropriate type of lookup is done on the file using the domain name as |
| 7615 | the key. In most cases, the data that is looked up is not used; Exim is |
| 7616 | interested only in whether or not the key is present in the file. However, |
| 7617 | when a lookup is used for the domains option on a router or a domains |
| 7618 | condition in an ACL statement, the data is preserved in the $domain_data |
| 7619 | variable and can be referred to in other router options or other statements |
| 7620 | in the same ACL. |
| 7621 | |
| 7622 | * Any of the single-key lookup type names may be preceded by "partial"<n>"-", |
| 7623 | where the <n> is optional, for example, |
| 7624 | |
| 7625 | domains = partial-dbm;/partial/domains |
| 7626 | |
| 7627 | This causes partial matching logic to be invoked; a description of how this |
| 7628 | works is given in section 9.7. |
| 7629 | |
| 7630 | * Any of the single-key lookup types may be followed by an asterisk. This |
| 7631 | causes a default lookup for a key consisting of a single asterisk to be |
| 7632 | done if the original lookup fails. This is not a useful feature when using |
| 7633 | a domain list to select particular domains (because any domain would |
| 7634 | match), but it might have value if the result of the lookup is being used |
| 7635 | via the $domain_data expansion variable. |
| 7636 | |
| 7637 | * If the pattern starts with the name of a query-style lookup type followed |
| 7638 | by a semicolon (for example, "nisplus;" or "ldap;"), the remainder of the |
| 7639 | pattern must be an appropriate query for the lookup type, as described in |
| 7640 | chapter 9. For example: |
| 7641 | |
| 7642 | hold_domains = mysql;select domain from holdlist \ |
| 7643 | where domain = '${quote_mysql:$domain}'; |
| 7644 | |
| 7645 | In most cases, the data that is looked up is not used (so for an SQL query, |
| 7646 | for example, it doesn't matter what field you select). Exim is interested |
| 7647 | only in whether or not the query succeeds. However, when a lookup is used |
| 7648 | for the domains option on a router, the data is preserved in the |
| 7649 | $domain_data variable and can be referred to in other options. |
| 7650 | |
| 7651 | * If none of the above cases apply, a caseless textual comparison is made |
| 7652 | between the pattern and the domain. |
| 7653 | |
| 7654 | Here is an example that uses several different kinds of pattern: |
| 7655 | |
| 7656 | domainlist funny_domains = \ |
| 7657 | @ : \ |
| 7658 | lib.unseen.edu : \ |
| 7659 | *.foundation.fict.example : \ |
| 7660 | \N^[1-2]\d{3}\.fict\.example$\N : \ |
| 7661 | partial-dbm;/opt/data/penguin/book : \ |
| 7662 | nis;domains.byname : \ |
| 7663 | nisplus;[name=$domain,status=local],domains.org_dir |
| 7664 | |
| 7665 | There are obvious processing trade-offs among the various matching modes. Using |
| 7666 | an asterisk is faster than a regular expression, and listing a few names |
| 7667 | explicitly probably is too. The use of a file or database lookup is expensive, |
| 7668 | but may be the only option if hundreds of names are required. Because the |
| 7669 | patterns are tested in order, it makes sense to put the most commonly matched |
| 7670 | patterns earlier. |
| 7671 | |
| 7672 | |
| 7673 | 10.9 Host lists |
| 7674 | --------------- |
| 7675 | |
| 7676 | Host lists are used to control what remote hosts are allowed to do. For |
| 7677 | example, some hosts may be allowed to use the local host as a relay, and some |
| 7678 | may be permitted to use the SMTP ETRN command. Hosts can be identified in two |
| 7679 | different ways, by name or by IP address. In a host list, some types of pattern |
| 7680 | are matched to a host name, and some are matched to an IP address. You need to |
| 7681 | be particularly careful with this when single-key lookups are involved, to |
| 7682 | ensure that the right value is being used as the key. |
| 7683 | |
| 7684 | |
| 7685 | 10.10 Special host list patterns |
| 7686 | -------------------------------- |
| 7687 | |
| 7688 | If a host list item is the empty string, it matches only when no remote host is |
| 7689 | involved. This is the case when a message is being received from a local |
| 7690 | process using SMTP on the standard input, that is, when a TCP/IP connection is |
| 7691 | not used. |
| 7692 | |
| 7693 | The special pattern "*" in a host list matches any host or no host. Neither the |
| 7694 | IP address nor the name is actually inspected. |
| 7695 | |
| 7696 | |
| 7697 | 10.11 Host list patterns that match by IP address |
| 7698 | ------------------------------------------------- |
| 7699 | |
| 7700 | If an IPv4 host calls an IPv6 host and the call is accepted on an IPv6 socket, |
| 7701 | the incoming address actually appears in the IPv6 host as "::ffff:"<v4address>. |
| 7702 | When such an address is tested against a host list, it is converted into a |
| 7703 | traditional IPv4 address first. (Not all operating systems accept IPv4 calls on |
| 7704 | IPv6 sockets, as there have been some security concerns.) |
| 7705 | |
| 7706 | The following types of pattern in a host list check the remote host by |
| 7707 | inspecting its IP address: |
| 7708 | |
| 7709 | * If the pattern is a plain domain name (not a regular expression, not |
| 7710 | starting with *, not a lookup of any kind), Exim calls the operating system |
| 7711 | function to find the associated IP address(es). Exim uses the newer |
| 7712 | getipnodebyname() function when available, otherwise gethostbyname(). This |
| 7713 | typically causes a forward DNS lookup of the name. The result is compared |
| 7714 | with the IP address of the subject host. |
| 7715 | |
| 7716 | If there is a temporary problem (such as a DNS timeout) with the host name |
| 7717 | lookup, a temporary error occurs. For example, if the list is being used in |
| 7718 | an ACL condition, the ACL gives a "defer" response, usually leading to a |
| 7719 | temporary SMTP error code. If no IP address can be found for the host name, |
| 7720 | what happens is described in section 10.14 below. |
| 7721 | |
| 7722 | * If the pattern is "@", the primary host name is substituted and used as a |
| 7723 | domain name, as just described. |
| 7724 | |
| 7725 | * If the pattern is an IP address, it is matched against the IP address of |
| 7726 | the subject host. IPv4 addresses are given in the normal "dotted-quad" |
| 7727 | notation. IPv6 addresses can be given in colon-separated format, but the |
| 7728 | colons have to be doubled so as not to be taken as item separators when the |
| 7729 | default list separator is used. IPv6 addresses are recognized even when |
| 7730 | Exim is compiled without IPv6 support. This means that if they appear in a |
| 7731 | host list on an IPv4-only host, Exim will not treat them as host names. |
| 7732 | They are just addresses that can never match a client host. |
| 7733 | |
| 7734 | * If the pattern is "@[]", it matches the IP address of any IP interface on |
| 7735 | the local host. For example, if the local host is an IPv4 host with one |
| 7736 | interface address 10.45.23.56, these two ACL statements have the same |
| 7737 | effect: |
| 7738 | |
| 7739 | accept hosts = 127.0.0.1 : 10.45.23.56 |
| 7740 | accept hosts = @[] |
| 7741 | |
| 7742 | * If the pattern is an IP address followed by a slash and a mask length (for |
| 7743 | example 10.11.42.0/24), it is matched against the IP address of the subject |
| 7744 | host under the given mask. This allows, an entire network of hosts to be |
| 7745 | included (or excluded) by a single item. The mask uses CIDR notation; it |
| 7746 | specifies the number of address bits that must match, starting from the |
| 7747 | most significant end of the address. |
| 7748 | |
| 7749 | Note: The mask is not a count of addresses, nor is it the high number of a |
| 7750 | range of addresses. It is the number of bits in the network portion of the |
| 7751 | address. The above example specifies a 24-bit netmask, so it matches all |
| 7752 | 256 addresses in the 10.11.42.0 network. An item such as |
| 7753 | |
| 7754 | 192.168.23.236/31 |
| 7755 | |
| 7756 | matches just two addresses, 192.168.23.236 and 192.168.23.237. A mask value |
| 7757 | of 32 for an IPv4 address is the same as no mask at all; just a single |
| 7758 | address matches. |
| 7759 | |
| 7760 | Here is another example which shows an IPv4 and an IPv6 network: |
| 7761 | |
| 7762 | recipient_unqualified_hosts = 192.168.0.0/16: \ |
| 7763 | 3ffe::ffff::836f::::/48 |
| 7764 | |
| 7765 | The doubling of list separator characters applies only when these items |
| 7766 | appear inline in a host list. It is not required when indirecting via a |
| 7767 | file. For example: |
| 7768 | |
| 7769 | recipient_unqualified_hosts = /opt/exim/unqualnets |
| 7770 | |
| 7771 | could make use of a file containing |
| 7772 | |
| 7773 | 172.16.0.0/12 |
| 7774 | 3ffe:ffff:836f::/48 |
| 7775 | |
| 7776 | to have exactly the same effect as the previous example. When listing IPv6 |
| 7777 | addresses inline, it is usually more convenient to use the facility for |
| 7778 | changing separator characters. This list contains the same two networks: |
| 7779 | |
| 7780 | recipient_unqualified_hosts = <; 172.16.0.0/12; \ |
| 7781 | 3ffe:ffff:836f::/48 |
| 7782 | |
| 7783 | The separator is changed to semicolon by the leading "<;" at the start of |
| 7784 | the list. |
| 7785 | |
| 7786 | |
| 7787 | 10.12 Host list patterns for single-key lookups by host address |
| 7788 | --------------------------------------------------------------- |
| 7789 | |
| 7790 | When a host is to be identified by a single-key lookup of its complete IP |
| 7791 | address, the pattern takes this form: |
| 7792 | |
| 7793 | net-<single-key-search-type>;<search-data> |
| 7794 | |
| 7795 | For example: |
| 7796 | |
| 7797 | hosts_lookup = net-cdb;/hosts-by-ip.db |
| 7798 | |
| 7799 | The text form of the IP address of the subject host is used as the lookup key. |
| 7800 | IPv6 addresses are converted to an unabbreviated form, using lower case |
| 7801 | letters, with dots as separators because colon is the key terminator in lsearch |
| 7802 | files. [Colons can in fact be used in keys in lsearch files by quoting the |
| 7803 | keys, but this is a facility that was added later.] The data returned by the |
| 7804 | lookup is not used. |
| 7805 | |
| 7806 | Single-key lookups can also be performed using masked IP addresses, using |
| 7807 | patterns of this form: |
| 7808 | |
| 7809 | net<number>-<single-key-search-type>;<search-data> |
| 7810 | |
| 7811 | For example: |
| 7812 | |
| 7813 | net24-dbm;/networks.db |
| 7814 | |
| 7815 | The IP address of the subject host is masked using <number> as the mask length. |
| 7816 | A textual string is constructed from the masked value, followed by the mask, |
| 7817 | and this is used as the lookup key. For example, if the host's IP address is |
| 7818 | 192.168.34.6, the key that is looked up for the above example is "192.168.34.0/ |
| 7819 | 24". |
| 7820 | |
| 7821 | When an IPv6 address is converted to a string, dots are normally used instead |
| 7822 | of colons, so that keys in lsearch files need not contain colons (which |
| 7823 | terminate lsearch keys). This was implemented some time before the ability to |
| 7824 | quote keys was made available in lsearch files. However, the more recently |
| 7825 | implemented iplsearch files do require colons in IPv6 keys (notated using the |
| 7826 | quoting facility) so as to distinguish them from IPv4 keys. For this reason, |
| 7827 | when the lookup type is iplsearch, IPv6 addresses are converted using colons |
| 7828 | and not dots. In all cases, full, unabbreviated IPv6 addresses are always used. |
| 7829 | |
| 7830 | Ideally, it would be nice to tidy up this anomalous situation by changing to |
| 7831 | colons in all cases, given that quoting is now available for lsearch. However, |
| 7832 | this would be an incompatible change that might break some existing |
| 7833 | configurations. |
| 7834 | |
| 7835 | Warning: Specifying net32- (for an IPv4 address) or net128- (for an IPv6 |
| 7836 | address) is not the same as specifying just net- without a number. In the |
| 7837 | former case the key strings include the mask value, whereas in the latter case |
| 7838 | the IP address is used on its own. |
| 7839 | |
| 7840 | |
| 7841 | 10.13 Host list patterns that match by host name |
| 7842 | ------------------------------------------------ |
| 7843 | |
| 7844 | There are several types of pattern that require Exim to know the name of the |
| 7845 | remote host. These are either wildcard patterns or lookups by name. (If a |
| 7846 | complete hostname is given without any wildcarding, it is used to find an IP |
| 7847 | address to match against, as described in section 10.11 above.) |
| 7848 | |
| 7849 | If the remote host name is not already known when Exim encounters one of these |
| 7850 | patterns, it has to be found from the IP address. Although many sites on the |
| 7851 | Internet are conscientious about maintaining reverse DNS data for their hosts, |
| 7852 | there are also many that do not do this. Consequently, a name cannot always be |
| 7853 | found, and this may lead to unwanted effects. Take care when configuring host |
| 7854 | lists with wildcarded name patterns. Consider what will happen if a name cannot |
| 7855 | be found. |
| 7856 | |
| 7857 | Because of the problems of determining host names from IP addresses, matching |
| 7858 | against host names is not as common as matching against IP addresses. |
| 7859 | |
| 7860 | By default, in order to find a host name, Exim first does a reverse DNS lookup; |
| 7861 | if no name is found in the DNS, the system function (gethostbyaddr() or |
| 7862 | getipnodebyaddr() if available) is tried. The order in which these lookups are |
| 7863 | done can be changed by setting the host_lookup_order option. For security, once |
| 7864 | Exim has found one or more names, it looks up the IP addresses for these names |
| 7865 | and compares them with the IP address that it started with. Only those names |
| 7866 | whose IP addresses match are accepted. Any other names are discarded. If no |
| 7867 | names are left, Exim behaves as if the host name cannot be found. In the most |
| 7868 | common case there is only one name and one IP address. |
| 7869 | |
| 7870 | There are some options that control what happens if a host name cannot be |
| 7871 | found. These are described in section 10.14 below. |
| 7872 | |
| 7873 | As a result of aliasing, hosts may have more than one name. When processing any |
| 7874 | of the following types of pattern, all the host's names are checked: |
| 7875 | |
| 7876 | * If a pattern starts with "*" the remainder of the item must match the end |
| 7877 | of the host name. For example, "*.b.c" matches all hosts whose names end in |
| 7878 | .b.c. This special simple form is provided because this is a very common |
| 7879 | requirement. Other kinds of wildcarding require the use of a regular |
| 7880 | expression. |
| 7881 | |
| 7882 | * If the item starts with "^" it is taken to be a regular expression which is |
| 7883 | matched against the host name. Host names are case-independent, so this |
| 7884 | regular expression match is by default case-independent, but you can make |
| 7885 | it case-dependent by starting it with "(?-i)". References to descriptions |
| 7886 | of the syntax of regular expressions are given in chapter 8. For example, |
| 7887 | |
| 7888 | ^(a|b)\.c\.d$ |
| 7889 | |
| 7890 | is a regular expression that matches either of the two hosts a.c.d or b.c.d |
| 7891 | . When a regular expression is used in a host list, you must take care that |
| 7892 | backslash and dollar characters are not misinterpreted as part of the |
| 7893 | string expansion. The simplest way to do this is to use "\N" to mark that |
| 7894 | part of the string as non-expandable. For example: |
| 7895 | |
| 7896 | sender_unqualified_hosts = \N^(a|b)\.c\.d$\N : .... |
| 7897 | |
| 7898 | Warning: If you want to match a complete host name, you must include the |
| 7899 | "$" terminating metacharacter in the regular expression, as in the above |
| 7900 | example. Without it, a match at the start of the host name is all that is |
| 7901 | required. |
| 7902 | |
| 7903 | |
| 7904 | 10.14 Behaviour when an IP address or name cannot be found |
| 7905 | ---------------------------------------------------------- |
| 7906 | |
| 7907 | While processing a host list, Exim may need to look up an IP address from a |
| 7908 | name (see section 10.11), or it may need to look up a host name from an IP |
| 7909 | address (see section 10.13). In either case, the behaviour when it fails to |
| 7910 | find the information it is seeking is the same. |
| 7911 | |
| 7912 | Note: This section applies to permanent lookup failures. It does not apply to |
| 7913 | temporary DNS errors, whose handling is described in the next section. |
| 7914 | |
| 7915 | Exim parses a host list from left to right. If it encounters a permanent lookup |
| 7916 | failure in any item in the host list before it has found a match, Exim treats |
| 7917 | it as a failure and the default behavior is as if the host does not match the |
| 7918 | list. This may not always be what you want to happen. To change Exim's |
| 7919 | behaviour, the special items "+include_unknown" or "+ignore_unknown" may appear |
| 7920 | in the list (at top level - they are not recognized in an indirected file). |
| 7921 | |
| 7922 | * If any item that follows "+include_unknown" requires information that |
| 7923 | cannot found, Exim behaves as if the host does match the list. For example, |
| 7924 | |
| 7925 | host_reject_connection = +include_unknown:*.enemy.ex |
| 7926 | |
| 7927 | rejects connections from any host whose name matches "*.enemy.ex", and also |
| 7928 | any hosts whose name it cannot find. |
| 7929 | |
| 7930 | * If any item that follows "+ignore_unknown" requires information that cannot |
| 7931 | be found, Exim ignores that item and proceeds to the rest of the list. For |
| 7932 | example: |
| 7933 | |
| 7934 | accept hosts = +ignore_unknown : friend.example : \ |
| 7935 | 192.168.4.5 |
| 7936 | |
| 7937 | accepts from any host whose name is friend.example and from 192.168.4.5, |
| 7938 | whether or not its host name can be found. Without "+ignore_unknown", if no |
| 7939 | name can be found for 192.168.4.5, it is rejected. |
| 7940 | |
| 7941 | Both "+include_unknown" and "+ignore_unknown" may appear in the same list. The |
| 7942 | effect of each one lasts until the next, or until the end of the list. |
| 7943 | |
| 7944 | |
| 7945 | 10.15 Mixing wildcarded host names and addresses in host lists |
| 7946 | -------------------------------------------------------------- |
| 7947 | |
| 7948 | This section explains the host/ip processing logic with the same concepts as |
| 7949 | the previous section, but specifically addresses what happens when a wildcarded |
| 7950 | hostname is one of the items in the hostlist. |
| 7951 | |
| 7952 | * If you have name lookups or wildcarded host names and IP addresses in the |
| 7953 | same host list, you should normally put the IP addresses first. For |
| 7954 | example, in an ACL you could have: |
| 7955 | |
| 7956 | accept hosts = 10.9.8.7 : *.friend.example |
| 7957 | |
| 7958 | The reason you normally would order it this way lies in the left-to-right |
| 7959 | way that Exim processes lists. It can test IP addresses without doing any |
| 7960 | DNS lookups, but when it reaches an item that requires a host name, it |
| 7961 | fails if it cannot find a host name to compare with the pattern. If the |
| 7962 | above list is given in the opposite order, the accept statement fails for a |
| 7963 | host whose name cannot be found, even if its IP address is 10.9.8.7. |
| 7964 | |
| 7965 | * If you really do want to do the name check first, and still recognize the |
| 7966 | IP address, you can rewrite the ACL like this: |
| 7967 | |
| 7968 | accept hosts = *.friend.example |
| 7969 | accept hosts = 10.9.8.7 |
| 7970 | |
| 7971 | If the first accept fails, Exim goes on to try the second one. See chapter |
| 7972 | 43 for details of ACLs. Alternatively, you can use "+ignore_unknown", which |
| 7973 | was discussed in depth in the first example in this section. |
| 7974 | |
| 7975 | |
| 7976 | 10.16 Temporary DNS errors when looking up host information |
| 7977 | ----------------------------------------------------------- |
| 7978 | |
| 7979 | A temporary DNS lookup failure normally causes a defer action (except when |
| 7980 | dns_again_means_nonexist converts it into a permanent error). However, host |
| 7981 | lists can include "+ignore_defer" and "+include_defer", analogous to |
| 7982 | "+ignore_unknown" and "+include_unknown", as described in the previous section. |
| 7983 | These options should be used with care, probably only in non-critical host |
| 7984 | lists such as whitelists. |
| 7985 | |
| 7986 | |
| 7987 | 10.17 Host list patterns for single-key lookups by host name |
| 7988 | ------------------------------------------------------------ |
| 7989 | |
| 7990 | If a pattern is of the form |
| 7991 | |
| 7992 | <single-key-search-type>;<search-data> |
| 7993 | |
| 7994 | for example |
| 7995 | |
| 7996 | dbm;/host/accept/list |
| 7997 | |
| 7998 | a single-key lookup is performed, using the host name as its key. If the lookup |
| 7999 | succeeds, the host matches the item. The actual data that is looked up is not |
| 8000 | used. |
| 8001 | |
| 8002 | Reminder: With this kind of pattern, you must have host names as keys in the |
| 8003 | file, not IP addresses. If you want to do lookups based on IP addresses, you |
| 8004 | must precede the search type with "net-" (see section 10.12). There is, |
| 8005 | however, no reason why you could not use two items in the same list, one doing |
| 8006 | an address lookup and one doing a name lookup, both using the same file. |
| 8007 | |
| 8008 | |
| 8009 | 10.18 Host list patterns for query-style lookups |
| 8010 | ------------------------------------------------ |
| 8011 | |
| 8012 | If a pattern is of the form |
| 8013 | |
| 8014 | <query-style-search-type>;<query> |
| 8015 | |
| 8016 | the query is obeyed, and if it succeeds, the host matches the item. The actual |
| 8017 | data that is looked up is not used. The variables $sender_host_address and |
| 8018 | $sender_host_name can be used in the query. For example: |
| 8019 | |
| 8020 | hosts_lookup = pgsql;\ |
| 8021 | select ip from hostlist where ip='$sender_host_address' |
| 8022 | |
| 8023 | The value of $sender_host_address for an IPv6 address contains colons. You can |
| 8024 | use the sg expansion item to change this if you need to. If you want to use |
| 8025 | masked IP addresses in database queries, you can use the mask expansion |
| 8026 | operator. |
| 8027 | |
| 8028 | If the query contains a reference to $sender_host_name, Exim automatically |
| 8029 | looks up the host name if it has not already done so. (See section 10.13 for |
| 8030 | comments on finding host names.) |
| 8031 | |
| 8032 | Historical note: prior to release 4.30, Exim would always attempt to find a |
| 8033 | host name before running the query, unless the search type was preceded by |
| 8034 | "net-". This is no longer the case. For backwards compatibility, "net-" is |
| 8035 | still recognized for query-style lookups, but its presence or absence has no |
| 8036 | effect. (Of course, for single-key lookups, "net-" is important. See section |
| 8037 | 10.12.) |
| 8038 | |
| 8039 | |
| 8040 | 10.19 Address lists |
| 8041 | ------------------- |
| 8042 | |
| 8043 | Address lists contain patterns that are matched against mail addresses. There |
| 8044 | is one special case to be considered: the sender address of a bounce message is |
| 8045 | always empty. You can test for this by providing an empty item in an address |
| 8046 | list. For example, you can set up a router to process bounce messages by using |
| 8047 | this option setting: |
| 8048 | |
| 8049 | senders = : |
| 8050 | |
| 8051 | The presence of the colon creates an empty item. If you do not provide any |
| 8052 | data, the list is empty and matches nothing. The empty sender can also be |
| 8053 | detected by a regular expression that matches an empty string, and by a |
| 8054 | query-style lookup that succeeds when $sender_address is empty. |
| 8055 | |
| 8056 | Non-empty items in an address list can be straightforward email addresses. For |
| 8057 | example: |
| 8058 | |
| 8059 | senders = jbc@askone.example : hs@anacreon.example |
| 8060 | |
| 8061 | A certain amount of wildcarding is permitted. If a pattern contains an @ |
| 8062 | character, but is not a regular expression and does not begin with a |
| 8063 | semicolon-terminated lookup type (described below), the local part of the |
| 8064 | subject address is compared with the local part of the pattern, which may start |
| 8065 | with an asterisk. If the local parts match, the domain is checked in exactly |
| 8066 | the same way as for a pattern in a domain list. For example, the domain can be |
| 8067 | wildcarded, refer to a named list, or be a lookup: |
| 8068 | |
| 8069 | deny senders = *@*.spamming.site:\ |
| 8070 | *@+hostile_domains:\ |
| 8071 | bozo@partial-lsearch;/list/of/dodgy/sites:\ |
| 8072 | *@dbm;/bad/domains.db |
| 8073 | |
| 8074 | If a local part that begins with an exclamation mark is required, it has to be |
| 8075 | specified using a regular expression, because otherwise the exclamation mark is |
| 8076 | treated as a sign of negation, as is standard in lists. |
| 8077 | |
| 8078 | If a non-empty pattern that is not a regular expression or a lookup does not |
| 8079 | contain an @ character, it is matched against the domain part of the subject |
| 8080 | address. The only two formats that are recognized this way are a literal |
| 8081 | domain, or a domain pattern that starts with *. In both these cases, the effect |
| 8082 | is the same as if "*@" preceded the pattern. For example: |
| 8083 | |
| 8084 | deny senders = enemy.domain : *.enemy.domain |
| 8085 | |
| 8086 | The following kinds of more complicated address list pattern can match any |
| 8087 | address, including the empty address that is characteristic of bounce message |
| 8088 | senders: |
| 8089 | |
| 8090 | * If (after expansion) a pattern starts with "^", a regular expression match |
| 8091 | is done against the complete address, with the pattern as the regular |
| 8092 | expression. You must take care that backslash and dollar characters are not |
| 8093 | misinterpreted as part of the string expansion. The simplest way to do this |
| 8094 | is to use "\N" to mark that part of the string as non-expandable. For |
| 8095 | example: |
| 8096 | |
| 8097 | deny senders = \N^.*this.*@example\.com$\N : \ |
| 8098 | \N^\d{8}.+@spamhaus.example$\N : ... |
| 8099 | |
| 8100 | The "\N" sequences are removed by the expansion, so these items do indeed |
| 8101 | start with "^" by the time they are being interpreted as address patterns. |
| 8102 | |
| 8103 | * Complete addresses can be looked up by using a pattern that starts with a |
| 8104 | lookup type terminated by a semicolon, followed by the data for the lookup. |
| 8105 | For example: |
| 8106 | |
| 8107 | deny senders = cdb;/etc/blocked.senders : \ |
| 8108 | mysql;select address from blocked where \ |
| 8109 | address='${quote_mysql:$sender_address}' |
| 8110 | |
| 8111 | Both query-style and single-key lookup types can be used. For a single-key |
| 8112 | lookup type, Exim uses the complete address as the key. However, empty keys |
| 8113 | are not supported for single-key lookups, so a match against the empty |
| 8114 | address always fails. This restriction does not apply to query-style |
| 8115 | lookups. |
| 8116 | |
| 8117 | Partial matching for single-key lookups (section 9.7) cannot be used, and |
| 8118 | is ignored if specified, with an entry being written to the panic log. |
| 8119 | However, you can configure lookup defaults, as described in section 9.6, |
| 8120 | but this is useful only for the "*@" type of default. For example, with |
| 8121 | this lookup: |
| 8122 | |
| 8123 | accept senders = lsearch*@;/some/file |
| 8124 | |
| 8125 | the file could contains lines like this: |
| 8126 | |
| 8127 | user1@domain1.example |
| 8128 | *@domain2.example |
| 8129 | |
| 8130 | and for the sender address nimrod@jaeger.example, the sequence of keys that |
| 8131 | are tried is: |
| 8132 | |
| 8133 | nimrod@jaeger.example |
| 8134 | *@jaeger.example |
| 8135 | * |
| 8136 | |
| 8137 | Warning 1: Do not include a line keyed by "*" in the file, because that |
| 8138 | would mean that every address matches, thus rendering the test useless. |
| 8139 | |
| 8140 | Warning 2: Do not confuse these two kinds of item: |
| 8141 | |
| 8142 | deny recipients = dbm*@;/some/file |
| 8143 | deny recipients = *@dbm;/some/file |
| 8144 | |
| 8145 | The first does a whole address lookup, with defaulting, as just described, |
| 8146 | because it starts with a lookup type. The second matches the local part and |
| 8147 | domain independently, as described in a bullet point below. |
| 8148 | |
| 8149 | The following kinds of address list pattern can match only non-empty addresses. |
| 8150 | If the subject address is empty, a match against any of these pattern types |
| 8151 | always fails. |
| 8152 | |
| 8153 | * If a pattern starts with "@@" followed by a single-key lookup item (for |
| 8154 | example, "@@lsearch;/some/file"), the address that is being checked is |
| 8155 | split into a local part and a domain. The domain is looked up in the file. |
| 8156 | If it is not found, there is no match. If it is found, the data that is |
| 8157 | looked up from the file is treated as a colon-separated list of local part |
| 8158 | patterns, each of which is matched against the subject local part in turn. |
| 8159 | |
| 8160 | The lookup may be a partial one, and/or one involving a search for a |
| 8161 | default keyed by "*" (see section 9.6). The local part patterns that are |
| 8162 | looked up can be regular expressions or begin with "*", or even be further |
| 8163 | lookups. They may also be independently negated. For example, with |
| 8164 | |
| 8165 | deny senders = @@dbm;/etc/reject-by-domain |
| 8166 | |
| 8167 | the data from which the DBM file is built could contain lines like |
| 8168 | |
| 8169 | baddomain.com: !postmaster : * |
| 8170 | |
| 8171 | to reject all senders except postmaster from that domain. |
| 8172 | |
| 8173 | If a local part that actually begins with an exclamation mark is required, |
| 8174 | it has to be specified using a regular expression. In lsearch files, an |
| 8175 | entry may be split over several lines by indenting the second and |
| 8176 | subsequent lines, but the separating colon must still be included at line |
| 8177 | breaks. White space surrounding the colons is ignored. For example: |
| 8178 | |
| 8179 | aol.com: spammer1 : spammer2 : ^[0-9]+$ : |
| 8180 | spammer3 : spammer4 |
| 8181 | |
| 8182 | As in all colon-separated lists in Exim, a colon can be included in an item |
| 8183 | by doubling. |
| 8184 | |
| 8185 | If the last item in the list starts with a right angle-bracket, the |
| 8186 | remainder of the item is taken as a new key to look up in order to obtain a |
| 8187 | continuation list of local parts. The new key can be any sequence of |
| 8188 | characters. Thus one might have entries like |
| 8189 | |
| 8190 | aol.com: spammer1 : spammer 2 : >* |
| 8191 | xyz.com: spammer3 : >* |
| 8192 | *: ^\d{8}$ |
| 8193 | |
| 8194 | in a file that was searched with @@dbm*, to specify a match for 8-digit |
| 8195 | local parts for all domains, in addition to the specific local parts listed |
| 8196 | for each domain. Of course, using this feature costs another lookup each |
| 8197 | time a chain is followed, but the effort needed to maintain the data is |
| 8198 | reduced. |
| 8199 | |
| 8200 | It is possible to construct loops using this facility, and in order to |
| 8201 | catch them, the chains may be no more than fifty items long. |
| 8202 | |
| 8203 | * The @@<lookup> style of item can also be used with a query-style lookup, |
| 8204 | but in this case, the chaining facility is not available. The lookup can |
| 8205 | only return a single list of local parts. |
| 8206 | |
| 8207 | Warning: There is an important difference between the address list items in |
| 8208 | these two examples: |
| 8209 | |
| 8210 | senders = +my_list |
| 8211 | senders = *@+my_list |
| 8212 | |
| 8213 | In the first one, "my_list" is a named address list, whereas in the second |
| 8214 | example it is a named domain list. |
| 8215 | |
| 8216 | |
| 8217 | 10.20 Case of letters in address lists |
| 8218 | -------------------------------------- |
| 8219 | |
| 8220 | Domains in email addresses are always handled caselessly, but for local parts |
| 8221 | case may be significant on some systems (see caseful_local_part for how Exim |
| 8222 | deals with this when routing addresses). However, RFC 2505 (Anti-Spam |
| 8223 | Recommendations for SMTP MTAs) suggests that matching of addresses to blocking |
| 8224 | lists should be done in a case-independent manner. Since most address lists in |
| 8225 | Exim are used for this kind of control, Exim attempts to do this by default. |
| 8226 | |
| 8227 | The domain portion of an address is always lowercased before matching it to an |
| 8228 | address list. The local part is lowercased by default, and any string |
| 8229 | comparisons that take place are done caselessly. This means that the data in |
| 8230 | the address list itself, in files included as plain file names, and in any file |
| 8231 | that is looked up using the "@@" mechanism, can be in any case. However, the |
| 8232 | keys in files that are looked up by a search type other than lsearch (which |
| 8233 | works caselessly) must be in lower case, because these lookups are not |
| 8234 | case-independent. |
| 8235 | |
| 8236 | To allow for the possibility of caseful address list matching, if an item in an |
| 8237 | address list is the string "+caseful", the original case of the local part is |
| 8238 | restored for any comparisons that follow, and string comparisons are no longer |
| 8239 | case-independent. This does not affect the domain, which remains in lower case. |
| 8240 | However, although independent matches on the domain alone are still performed |
| 8241 | caselessly, regular expressions that match against an entire address become |
| 8242 | case-sensitive after "+caseful" has been seen. |
| 8243 | |
| 8244 | |
| 8245 | 10.21 Local part lists |
| 8246 | ---------------------- |
| 8247 | |
| 8248 | Case-sensitivity in local part lists is handled in the same way as for address |
| 8249 | lists, as just described. The "+caseful" item can be used if required. In a |
| 8250 | setting of the local_parts option in a router with caseful_local_part set |
| 8251 | false, the subject is lowercased and the matching is initially |
| 8252 | case-insensitive. In this case, "+caseful" will restore case-sensitive matching |
| 8253 | in the local part list, but not elsewhere in the router. If caseful_local_part |
| 8254 | is set true in a router, matching in the local_parts option is case-sensitive |
| 8255 | from the start. |
| 8256 | |
| 8257 | If a local part list is indirected to a file (see section 10.3), comments are |
| 8258 | handled in the same way as address lists - they are recognized only if the # is |
| 8259 | preceded by white space or the start of the line. Otherwise, local part lists |
| 8260 | are matched in the same way as domain lists, except that the special items that |
| 8261 | refer to the local host ("@", "@[]", "@mx_any", "@mx_primary", and |
| 8262 | "@mx_secondary") are not recognized. Refer to section 10.8 for details of the |
| 8263 | other available item types. |
| 8264 | |
| 8265 | |
| 8266 | |
| 8267 | =============================================================================== |
| 8268 | 11. STRING EXPANSIONS |
| 8269 | |
| 8270 | Many strings in Exim's run time configuration are expanded before use. Some of |
| 8271 | them are expanded every time they are used; others are expanded only once. |
| 8272 | |
| 8273 | When a string is being expanded it is copied verbatim from left to right except |
| 8274 | when a dollar or backslash character is encountered. A dollar specifies the |
| 8275 | start of a portion of the string that is interpreted and replaced as described |
| 8276 | below in section 11.5 onwards. Backslash is used as an escape character, as |
| 8277 | described in the following section. |
| 8278 | |
| 8279 | Whether a string is expanded depends upon the context. Usually this is solely |
| 8280 | dependent upon the option for which a value is sought; in this documentation, |
| 8281 | options for which string expansion is performed are marked with * after the |
| 8282 | data type. ACL rules always expand strings. A couple of expansion conditions do |
| 8283 | not expand some of the brace-delimited branches, for security reasons. |
| 8284 | |
| 8285 | |
| 8286 | 11.1 Literal text in expanded strings |
| 8287 | ------------------------------------- |
| 8288 | |
| 8289 | An uninterpreted dollar can be included in an expanded string by putting a |
| 8290 | backslash in front of it. A backslash can be used to prevent any special |
| 8291 | character being treated specially in an expansion, including backslash itself. |
| 8292 | If the string appears in quotes in the configuration file, two backslashes are |
| 8293 | required because the quotes themselves cause interpretation of backslashes when |
| 8294 | the string is read in (see section 6.17). |
| 8295 | |
| 8296 | A portion of the string can specified as non-expandable by placing it between |
| 8297 | two occurrences of "\N". This is particularly useful for protecting regular |
| 8298 | expressions, which often contain backslashes and dollar signs. For example: |
| 8299 | |
| 8300 | deny senders = \N^\d{8}[a-z]@some\.site\.example$\N |
| 8301 | |
| 8302 | On encountering the first "\N", the expander copies subsequent characters |
| 8303 | without interpretation until it reaches the next "\N" or the end of the string. |
| 8304 | |
| 8305 | |
| 8306 | 11.2 Character escape sequences in expanded strings |
| 8307 | --------------------------------------------------- |
| 8308 | |
| 8309 | A backslash followed by one of the letters "n", "r", or "t" in an expanded |
| 8310 | string is recognized as an escape sequence for the character newline, carriage |
| 8311 | return, or tab, respectively. A backslash followed by up to three octal digits |
| 8312 | is recognized as an octal encoding for a single character, and a backslash |
| 8313 | followed by "x" and up to two hexadecimal digits is a hexadecimal encoding. |
| 8314 | |
| 8315 | These escape sequences are also recognized in quoted strings when they are read |
| 8316 | in. Their interpretation in expansions as well is useful for unquoted strings, |
| 8317 | and for other cases such as looked-up strings that are then expanded. |
| 8318 | |
| 8319 | |
| 8320 | 11.3 Testing string expansions |
| 8321 | ------------------------------ |
| 8322 | |
| 8323 | Many expansions can be tested by calling Exim with the -be option. This takes |
| 8324 | the command arguments, or lines from the standard input if there are no |
| 8325 | arguments, runs them through the string expansion code, and writes the results |
| 8326 | to the standard output. Variables based on configuration values are set up, but |
| 8327 | since no message is being processed, variables such as $local_part have no |
| 8328 | value. Nevertheless the -be option can be useful for checking out file and |
| 8329 | database lookups, and the use of expansion operators such as sg, substr and |
| 8330 | nhash. |
| 8331 | |
| 8332 | Exim gives up its root privilege when it is called with the -be option, and |
| 8333 | instead runs under the uid and gid it was called with, to prevent users from |
| 8334 | using -be for reading files to which they do not have access. |
| 8335 | |
| 8336 | If you want to test expansions that include variables whose values are taken |
| 8337 | from a message, there are two other options that can be used. The -bem option |
| 8338 | is like -be except that it is followed by a file name. The file is read as a |
| 8339 | message before doing the test expansions. For example: |
| 8340 | |
| 8341 | exim -bem /tmp/test.message '$h_subject:' |
| 8342 | |
| 8343 | The -Mset option is used in conjunction with -be and is followed by an Exim |
| 8344 | message identifier. For example: |
| 8345 | |
| 8346 | exim -be -Mset 1GrA8W-0004WS-LQ '$recipients' |
| 8347 | |
| 8348 | This loads the message from Exim's spool before doing the test expansions, and |
| 8349 | is therefore restricted to admin users. |
| 8350 | |
| 8351 | |
| 8352 | 11.4 Forced expansion failure |
| 8353 | ----------------------------- |
| 8354 | |
| 8355 | A number of expansions that are described in the following section have |
| 8356 | alternative "true" and "false" substrings, enclosed in brace characters (which |
| 8357 | are sometimes called "curly brackets"). Which of the two strings is used |
| 8358 | depends on some condition that is evaluated as part of the expansion. If, |
| 8359 | instead of a "false" substring, the word "fail" is used (not in braces), the |
| 8360 | entire string expansion fails in a way that can be detected by the code that |
| 8361 | requested the expansion. This is called "forced expansion failure", and its |
| 8362 | consequences depend on the circumstances. In some cases it is no different from |
| 8363 | any other expansion failure, but in others a different action may be taken. |
| 8364 | Such variations are mentioned in the documentation of the option that is being |
| 8365 | expanded. |
| 8366 | |
| 8367 | |
| 8368 | 11.5 Expansion items |
| 8369 | -------------------- |
| 8370 | |
| 8371 | The following items are recognized in expanded strings. White space may be used |
| 8372 | between sub-items that are keywords or substrings enclosed in braces inside an |
| 8373 | outer set of braces, to improve readability. Warning: Within braces, white |
| 8374 | space is significant. |
| 8375 | |
| 8376 | $<variable name> or ${<variable name>} |
| 8377 | |
| 8378 | Substitute the contents of the named variable, for example: |
| 8379 | |
| 8380 | $local_part |
| 8381 | ${domain} |
| 8382 | |
| 8383 | The second form can be used to separate the name from subsequent |
| 8384 | alphanumeric characters. This form (using braces) is available only for |
| 8385 | variables; it does not apply to message headers. The names of the variables |
| 8386 | are given in section 11.9 below. If the name of a non-existent variable is |
| 8387 | given, the expansion fails. |
| 8388 | |
| 8389 | ${<op>:<string>} |
| 8390 | |
| 8391 | The string is first itself expanded, and then the operation specified by < |
| 8392 | op> is applied to it. For example: |
| 8393 | |
| 8394 | ${lc:$local_part} |
| 8395 | |
| 8396 | The string starts with the first character after the colon, which may be |
| 8397 | leading white space. A list of operators is given in section 11.6 below. |
| 8398 | The operator notation is used for simple expansion items that have just one |
| 8399 | argument, because it reduces the number of braces and therefore makes the |
| 8400 | string easier to understand. |
| 8401 | |
| 8402 | $bheader_<header name>: or $bh_<header name>: |
| 8403 | |
| 8404 | This item inserts "basic" header lines. It is described with the header |
| 8405 | expansion item below. |
| 8406 | |
| 8407 | ${acl{<name>}{<arg>}...} |
| 8408 | |
| 8409 | The name and zero to nine argument strings are first expanded separately. |
| 8410 | The expanded arguments are assigned to the variables $acl_arg1 to $acl_arg9 |
| 8411 | in order. Any unused are made empty. The variable $acl_narg is set to the |
| 8412 | number of arguments. The named ACL (see chapter 43) is called and may use |
| 8413 | the variables; if another acl expansion is used the values are restored |
| 8414 | after it returns. If the ACL sets a value using a "message =" modifier and |
| 8415 | returns accept or deny, the value becomes the result of the expansion. If |
| 8416 | no message is set and the ACL returns accept or deny the expansion result |
| 8417 | is an empty string. If the ACL returns defer the result is a forced-fail. |
| 8418 | Otherwise the expansion fails. |
| 8419 | |
| 8420 | ${certextract{<field>}{<certificate>}{<string2>}{<string3>}} |
| 8421 | |
| 8422 | The <certificate> must be a variable of type certificate. The field name is |
| 8423 | expanded and used to retrieve the relevant field from the certificate. |
| 8424 | Supported fields are: |
| 8425 | |
| 8426 | version |
| 8427 | serial_number |
| 8428 | subject RFC4514 DN |
| 8429 | issuer RFC4514 DN |
| 8430 | notbefore time |
| 8431 | notafter time |
| 8432 | sig_algorithm |
| 8433 | signature |
| 8434 | subj_altname tagged list |
| 8435 | ocsp_uri list |
| 8436 | crl_uri list |
| 8437 | |
| 8438 | If the field is found, <string2> is expanded, and replaces the whole item; |
| 8439 | otherwise <string3> is used. During the expansion of <string2> the variable |
| 8440 | $value contains the value that has been extracted. Afterwards, it is |
| 8441 | restored to any previous value it might have had. |
| 8442 | |
| 8443 | If {<string3>} is omitted, the item is replaced by an empty string if the |
| 8444 | key is not found. If {<string2>} is also omitted, the value that was |
| 8445 | extracted is used. |
| 8446 | |
| 8447 | Some field names take optional modifiers, appended and separated by commas. |
| 8448 | |
| 8449 | The field selectors marked as "RFC4514" above output a Distinguished Name |
| 8450 | string which is not quite parseable by Exim as a comma-separated tagged |
| 8451 | list (the exceptions being elements containing commas). RDN elements of a |
| 8452 | single type may be selected by a modifier of the type label; if so the |
| 8453 | expansion result is a list (newline-separated by default). The separator |
| 8454 | may be changed by another modifier of a right angle-bracket followed |
| 8455 | immediately by the new separator. Recognised RDN type labels include "CN", |
| 8456 | "O", "OU" and "DC". |
| 8457 | |
| 8458 | The field selectors marked as "time" above take an optional modifier of |
| 8459 | "int" for which the result is the number of seconds since epoch. Otherwise |
| 8460 | the result is a human-readable string in the timezone selected by the main |
| 8461 | "timezone" option. |
| 8462 | |
| 8463 | The field selectors marked as "list" above return a list, newline-separated |
| 8464 | by default, (embedded separator characters in elements are doubled). The |
| 8465 | separator may be changed by a modifier of a right angle-bracket followed |
| 8466 | immediately by the new separator. |
| 8467 | |
| 8468 | The field selectors marked as "tagged" above prefix each list element with |
| 8469 | a type string and an equals sign. Elements of only one type may be selected |
| 8470 | by a modifier which is one of "dns", "uri" or "mail"; if so the element |
| 8471 | tags are omitted. |
| 8472 | |
| 8473 | If not otherwise noted field values are presented in human-readable form. |
| 8474 | |
| 8475 | ${dlfunc{<file>}{<function>}{<arg>}{<arg>}...} |
| 8476 | |
| 8477 | This expansion dynamically loads and then calls a locally-written C |
| 8478 | function. This functionality is available only if Exim is compiled with |
| 8479 | |
| 8480 | EXPAND_DLFUNC=yes |
| 8481 | |
| 8482 | set in Local/Makefile. Once loaded, Exim remembers the dynamically loaded |
| 8483 | object so that it doesn't reload the same object file in the same Exim |
| 8484 | process (but of course Exim does start new processes frequently). |
| 8485 | |
| 8486 | There may be from zero to eight arguments to the function. When compiling a |
| 8487 | local function that is to be called in this way, local_scan.h should be |
| 8488 | included. The Exim variables and functions that are defined by that API are |
| 8489 | also available for dynamically loaded functions. The function itself must |
| 8490 | have the following type: |
| 8491 | |
| 8492 | int dlfunction(uschar **yield, int argc, uschar *argv[]) |
| 8493 | |
| 8494 | Where "uschar" is a typedef for "unsigned char" in local_scan.h. The |
| 8495 | function should return one of the following values: |
| 8496 | |
| 8497 | "OK": Success. The string that is placed in the variable yield is put into |
| 8498 | the expanded string that is being built. |
| 8499 | |
| 8500 | "FAIL": A non-forced expansion failure occurs, with the error message taken |
| 8501 | from yield, if it is set. |
| 8502 | |
| 8503 | "FAIL_FORCED": A forced expansion failure occurs, with the error message |
| 8504 | taken from yield if it is set. |
| 8505 | |
| 8506 | "ERROR": Same as "FAIL", except that a panic log entry is written. |
| 8507 | |
| 8508 | When compiling a function that is to be used in this way with gcc, you need |
| 8509 | to add -shared to the gcc command. Also, in the Exim build-time |
| 8510 | configuration, you must add -export-dynamic to EXTRALIBS. |
| 8511 | |
| 8512 | ${env{<key>}{<string1>}{<string2>}} |
| 8513 | |
| 8514 | The key is first expanded separately, and leading and trailing white space |
| 8515 | removed. This is then searched for as a name in the environment. If a |
| 8516 | variable is found then its value is placed in $value and <string1> is |
| 8517 | expanded, otherwise <string2> is expanded. |
| 8518 | |
| 8519 | Instead of {<string2>} the word "fail" (not in curly brackets) can appear, |
| 8520 | for example: |
| 8521 | |
| 8522 | ${env{USER}{$value} fail } |
| 8523 | |
| 8524 | This forces an expansion failure (see section 11.4); {<string1>} must be |
| 8525 | present for "fail" to be recognized. |
| 8526 | |
| 8527 | If {<string2>} is omitted an empty string is substituted on search failure. |
| 8528 | If {<string1>} is omitted the search result is substituted on search |
| 8529 | success. |
| 8530 | |
| 8531 | The environment is adjusted by the keep_environment and add_environment |
| 8532 | main section options. |
| 8533 | |
| 8534 | ${extract{<key>}{<string1>}{<string2>}{<string3>}} |
| 8535 | |
| 8536 | The key and <string1> are first expanded separately. Leading and trailing |
| 8537 | white space is removed from the key (but not from any of the strings). The |
| 8538 | key must not be empty and must not consist entirely of digits. The expanded |
| 8539 | <string1> must be of the form: |
| 8540 | |
| 8541 | <key1> = <value1> <key2> = <value2> ... |
| 8542 | |
| 8543 | where the equals signs and spaces (but not both) are optional. If any of |
| 8544 | the values contain white space, they must be enclosed in double quotes, and |
| 8545 | any values that are enclosed in double quotes are subject to escape |
| 8546 | processing as described in section 6.17. The expanded <string1> is searched |
| 8547 | for the value that corresponds to the key. The search is case-insensitive. |
| 8548 | If the key is found, <string2> is expanded, and replaces the whole item; |
| 8549 | otherwise <string3> is used. During the expansion of <string2> the variable |
| 8550 | $value contains the value that has been extracted. Afterwards, it is |
| 8551 | restored to any previous value it might have had. |
| 8552 | |
| 8553 | If {<string3>} is omitted, the item is replaced by an empty string if the |
| 8554 | key is not found. If {<string2>} is also omitted, the value that was |
| 8555 | extracted is used. Thus, for example, these two expansions are identical, |
| 8556 | and yield "2001": |
| 8557 | |
| 8558 | ${extract{gid}{uid=1984 gid=2001}} |
| 8559 | ${extract{gid}{uid=1984 gid=2001}{$value}} |
| 8560 | |
| 8561 | Instead of {<string3>} the word "fail" (not in curly brackets) can appear, |
| 8562 | for example: |
| 8563 | |
| 8564 | ${extract{Z}{A=... B=...}{$value} fail } |
| 8565 | |
| 8566 | This forces an expansion failure (see section 11.4); {<string2>} must be |
| 8567 | present for "fail" to be recognized. |
| 8568 | |
| 8569 | ${extract{<number>}{<separators>}{<string1>}{<string2>}{<string3>}} |
| 8570 | |
| 8571 | The <number> argument must consist entirely of decimal digits, apart from |
| 8572 | leading and trailing white space, which is ignored. This is what |
| 8573 | distinguishes this form of extract from the previous kind. It behaves in |
| 8574 | the same way, except that, instead of extracting a named field, it extracts |
| 8575 | from <string1> the field whose number is given as the first argument. You |
| 8576 | can use $value in <string2> or "fail" instead of <string3> as before. |
| 8577 | |
| 8578 | The fields in the string are separated by any one of the characters in the |
| 8579 | separator string. These may include space or tab characters. The first |
| 8580 | field is numbered one. If the number is negative, the fields are counted |
| 8581 | from the end of the string, with the rightmost one numbered -1. If the |
| 8582 | number given is zero, the entire string is returned. If the modulus of the |
| 8583 | number is greater than the number of fields in the string, the result is |
| 8584 | the expansion of <string3>, or the empty string if <string3> is not |
| 8585 | provided. For example: |
| 8586 | |
| 8587 | ${extract{2}{:}{x:42:99:& Mailer::/bin/bash}} |
| 8588 | |
| 8589 | yields "42", and |
| 8590 | |
| 8591 | ${extract{-4}{:}{x:42:99:& Mailer::/bin/bash}} |
| 8592 | |
| 8593 | yields "99". Two successive separators mean that the field between them is |
| 8594 | empty (for example, the fifth field above). |
| 8595 | |
| 8596 | ${filter{<string>}{<condition>}} |
| 8597 | |
| 8598 | After expansion, <string> is interpreted as a list, colon-separated by |
| 8599 | default, but the separator can be changed in the usual way. For each item |
| 8600 | in this list, its value is place in $item, and then the condition is |
| 8601 | evaluated. If the condition is true, $item is added to the output as an |
| 8602 | item in a new list; if the condition is false, the item is discarded. The |
| 8603 | separator used for the output list is the same as the one used for the |
| 8604 | input, but a separator setting is not included in the output. For example: |
| 8605 | |
| 8606 | ${filter{a:b:c}{!eq{$item}{b}} |
| 8607 | |
| 8608 | yields "a:c". At the end of the expansion, the value of $item is restored |
| 8609 | to what it was before. See also the map and reduce expansion items. |
| 8610 | |
| 8611 | ${hash{<string1>}{<string2>}{<string3>}} |
| 8612 | |
| 8613 | This is a textual hashing function, and was the first to be implemented in |
| 8614 | early versions of Exim. In current releases, there are other hashing |
| 8615 | functions (numeric, MD5, and SHA-1), which are described below. |
| 8616 | |
| 8617 | The first two strings, after expansion, must be numbers. Call them <m> and |
| 8618 | <n>. If you are using fixed values for these numbers, that is, if <string1> |
| 8619 | and <string2> do not change when they are expanded, you can use the simpler |
| 8620 | operator notation that avoids some of the braces: |
| 8621 | |
| 8622 | ${hash_<n>_<m>:<string>} |
| 8623 | |
| 8624 | The second number is optional (in both notations). If <n> is greater than |
| 8625 | or equal to the length of the string, the expansion item returns the |
| 8626 | string. Otherwise it computes a new string of length <n> by applying a |
| 8627 | hashing function to the string. The new string consists of characters taken |
| 8628 | from the first <m> characters of the string |
| 8629 | |
| 8630 | abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQWRSTUVWXYZ0123456789 |
| 8631 | |
| 8632 | If <m> is not present the value 26 is used, so that only lower case letters |
| 8633 | appear. For example: |
| 8634 | |
| 8635 | $hash{3}{monty}} yields jmg |
| 8636 | $hash{5}{monty}} yields monty |
| 8637 | $hash{4}{62}{monty python}} yields fbWx |
| 8638 | |
| 8639 | $header_<header name>: or $h_<header name>:, $bheader_<header name>: or $bh_< |
| 8640 | header name>:, $rheader_<header name>: or $rh_<header name>: |
| 8641 | |
| 8642 | Substitute the contents of the named message header line, for example |
| 8643 | |
| 8644 | $header_reply-to: |
| 8645 | |
| 8646 | The newline that terminates a header line is not included in the expansion, |
| 8647 | but internal newlines (caused by splitting the header line over several |
| 8648 | physical lines) may be present. |
| 8649 | |
| 8650 | The difference between rheader, bheader, and header is in the way the data |
| 8651 | in the header line is interpreted. |
| 8652 | |
| 8653 | + rheader gives the original "raw" content of the header line, with no |
| 8654 | processing at all, and without the removal of leading and trailing |
| 8655 | white space. |
| 8656 | |
| 8657 | + bheader removes leading and trailing white space, and then decodes |
| 8658 | base64 or quoted-printable MIME "words" within the header text, but |
| 8659 | does no character set translation. If decoding of what looks |
| 8660 | superficially like a MIME "word" fails, the raw string is returned. If |
| 8661 | decoding produces a binary zero character, it is replaced by a question |
| 8662 | mark - this is what Exim does for binary zeros that are actually |
| 8663 | received in header lines. |
| 8664 | |
| 8665 | + header tries to translate the string as decoded by bheader to a |
| 8666 | standard character set. This is an attempt to produce the same string |
| 8667 | as would be displayed on a user's MUA. If translation fails, the |
| 8668 | bheader string is returned. Translation is attempted only on operating |
| 8669 | systems that support the iconv() function. This is indicated by the |
| 8670 | compile-time macro HAVE_ICONV in a system Makefile or in Local/Makefile |
| 8671 | . |
| 8672 | |
| 8673 | In a filter file, the target character set for header can be specified by a |
| 8674 | command of the following form: |
| 8675 | |
| 8676 | headers charset "UTF-8" |
| 8677 | |
| 8678 | This command affects all references to $h_ (or $header_) expansions in |
| 8679 | subsequently obeyed filter commands. In the absence of this command, the |
| 8680 | target character set in a filter is taken from the setting of the |
| 8681 | headers_charset option in the runtime configuration. The value of this |
| 8682 | option defaults to the value of HEADERS_CHARSET in Local/Makefile. The |
| 8683 | ultimate default is ISO-8859-1. |
| 8684 | |
| 8685 | Header names follow the syntax of RFC 2822, which states that they may |
| 8686 | contain any printing characters except space and colon. Consequently, curly |
| 8687 | brackets do not terminate header names, and should not be used to enclose |
| 8688 | them as if they were variables. Attempting to do so causes a syntax error. |
| 8689 | |
| 8690 | Only header lines that are common to all copies of a message are visible to |
| 8691 | this mechanism. These are the original header lines that are received with |
| 8692 | the message, and any that are added by an ACL statement or by a system |
| 8693 | filter. Header lines that are added to a particular copy of a message by a |
| 8694 | router or transport are not accessible. |
| 8695 | |
| 8696 | For incoming SMTP messages, no header lines are visible in |
| 8697 | |
| 8698 | ACLs that are obeyed before the data phase completes, |
| 8699 | |
| 8700 | because the header structure is not set up until the message is received. |
| 8701 | They are visible in DKIM, PRDR and DATA ACLs. Header lines that are added |
| 8702 | in a RCPT ACL (for example) are saved until the message's incoming header |
| 8703 | lines are available, at which point they are added. |
| 8704 | |
| 8705 | When any of the above ACLs ar |
| 8706 | |
| 8707 | running, however, header lines added by earlier ACLs are visible. |
| 8708 | |
| 8709 | Upper case and lower case letters are synonymous in header names. If the |
| 8710 | following character is white space, the terminating colon may be omitted, |
| 8711 | but this is not recommended, because you may then forget it when it is |
| 8712 | needed. When white space terminates the header name, this white space is |
| 8713 | included in the expanded string. If the message does not contain the given |
| 8714 | header, the expansion item is replaced by an empty string. (See the def |
| 8715 | condition in section 11.7 for a means of testing for the existence of a |
| 8716 | header.) |
| 8717 | |
| 8718 | If there is more than one header with the same name, they are all |
| 8719 | concatenated to form the substitution string, up to a maximum length of |
| 8720 | 64K. Unless rheader is being used, leading and trailing white space is |
| 8721 | removed from each header before concatenation, and a completely empty |
| 8722 | header is ignored. A newline character is then inserted between non-empty |
| 8723 | headers, but there is no newline at the very end. For the header and |
| 8724 | bheader expansion, for those headers that contain lists of addresses, a |
| 8725 | comma is also inserted at the junctions between headers. This does not |
| 8726 | happen for the rheader expansion. |
| 8727 | |
| 8728 | ${hmac{<hashname>}{<secret>}{<string>}} |
| 8729 | |
| 8730 | This function uses cryptographic hashing (either MD5 or SHA-1) to convert a |
| 8731 | shared secret and some text into a message authentication code, as |
| 8732 | specified in RFC 2104. This differs from "${md5:secret_text...}" or "$ |
| 8733 | {sha1:secret_text...}" in that the hmac step adds a signature to the |
| 8734 | cryptographic hash, allowing for authentication that is not possible with |
| 8735 | MD5 or SHA-1 alone. The hash name must expand to either "md5" or "sha1" at |
| 8736 | present. For example: |
| 8737 | |
| 8738 | ${hmac{md5}{somesecret}{$primary_hostname $tod_log}} |
| 8739 | |
| 8740 | For the hostname mail.example.com and time 2002-10-17 11:30:59, this |
| 8741 | produces: |
| 8742 | |
| 8743 | dd97e3ba5d1a61b5006108f8c8252953 |
| 8744 | |
| 8745 | As an example of how this might be used, you might put in the main part of |
| 8746 | an Exim configuration: |
| 8747 | |
| 8748 | SPAMSCAN_SECRET=cohgheeLei2thahw |
| 8749 | |
| 8750 | In a router or a transport you could then have: |
| 8751 | |
| 8752 | headers_add = \ |
| 8753 | X-Spam-Scanned: ${primary_hostname} ${message_exim_id} \ |
| 8754 | ${hmac{md5}{SPAMSCAN_SECRET}\ |
| 8755 | {${primary_hostname},${message_exim_id},$h_message-id:}} |
| 8756 | |
| 8757 | Then given a message, you can check where it was scanned by looking at the |
| 8758 | X-Spam-Scanned: header line. If you know the secret, you can check that |
| 8759 | this header line is authentic by recomputing the authentication code from |
| 8760 | the host name, message ID and the Message-id: header line. This can be done |
| 8761 | using Exim's -be option, or by other means, for example by using the |
| 8762 | hmac_md5_hex() function in Perl. |
| 8763 | |
| 8764 | ${if <condition> {<string1>}{<string2>}} |
| 8765 | |
| 8766 | If <condition> is true, <string1> is expanded and replaces the whole item; |
| 8767 | otherwise <string2> is used. The available conditions are described in |
| 8768 | section 11.7 below. For example: |
| 8769 | |
| 8770 | ${if eq {$local_part}{postmaster} {yes}{no} } |
| 8771 | |
| 8772 | The second string need not be present; if it is not and the condition is |
| 8773 | not true, the item is replaced with nothing. Alternatively, the word "fail" |
| 8774 | may be present instead of the second string (without any curly brackets). |
| 8775 | In this case, the expansion is forced to fail if the condition is not true |
| 8776 | (see section 11.4). |
| 8777 | |
| 8778 | If both strings are omitted, the result is the string "true" if the |
| 8779 | condition is true, and the empty string if the condition is false. This |
| 8780 | makes it less cumbersome to write custom ACL and router conditions. For |
| 8781 | example, instead of |
| 8782 | |
| 8783 | condition = ${if >{$acl_m4}{3}{true}{false}} |
| 8784 | |
| 8785 | you can use |
| 8786 | |
| 8787 | condition = ${if >{$acl_m4}{3}} |
| 8788 | |
| 8789 | ${imapfolder{<foldername>}} |
| 8790 | |
| 8791 | This item converts a (possibly multilevel, or with non-ASCII characters) |
| 8792 | folder specification to a Maildir name for filesystem use. For information |
| 8793 | on internationalisation support see 59.2. |
| 8794 | |
| 8795 | ${length{<string1>}{<string2>}} |
| 8796 | |
| 8797 | The length item is used to extract the initial portion of a string. Both |
| 8798 | strings are expanded, and the first one must yield a number, <n>, say. If |
| 8799 | you are using a fixed value for the number, that is, if <string1> does not |
| 8800 | change when expanded, you can use the simpler operator notation that avoids |
| 8801 | some of the braces: |
| 8802 | |
| 8803 | ${length_<n>:<string>} |
| 8804 | |
| 8805 | The result of this item is either the first <n> characters or the whole of |
| 8806 | <string2>, whichever is the shorter. Do not confuse length with strlen, |
| 8807 | which gives the length of a string. |
| 8808 | |
| 8809 | ${listextract{<number>}{<string1>}{<string2>}{<string3>}} |
| 8810 | |
| 8811 | The <number> argument must consist entirely of decimal digits, apart from |
| 8812 | an optional leading minus, and leading and trailing white space (which is |
| 8813 | ignored). |
| 8814 | |
| 8815 | After expansion, <string1> is interpreted as a list, colon-separated by |
| 8816 | default, but the separator can be changed in the usual way. |
| 8817 | |
| 8818 | The first field of the list is numbered one. If the number is negative, the |
| 8819 | fields are counted from the end of the list, with the rightmost one |
| 8820 | numbered -1. The numbered element of the list is extracted and placed in |
| 8821 | $value, then <string2> is expanded as the result. |
| 8822 | |
| 8823 | If the modulus of the number is zero or greater than the number of fields |
| 8824 | in the string, the result is the expansion of <string3>. |
| 8825 | |
| 8826 | For example: |
| 8827 | |
| 8828 | ${listextract{2}{x:42:99}} |
| 8829 | |
| 8830 | yields "42", and |
| 8831 | |
| 8832 | ${listextract{-3}{<, x,42,99,& Mailer,,/bin/bash}{result: $value}} |
| 8833 | |
| 8834 | yields "result: 42". |
| 8835 | |
| 8836 | If {<string3>} is omitted, an empty string is used for string3. If {< |
| 8837 | string2>} is also omitted, the value that was extracted is used. You can |
| 8838 | use "fail" instead of {<string3>} as in a string extract. |
| 8839 | |
| 8840 | ${lookup{<key>} <search type> {<file>} {<string1>} {<string2>}} |
| 8841 | |
| 8842 | This is the first of one of two different types of lookup item, which are |
| 8843 | both described in the next item. |
| 8844 | |
| 8845 | ${lookup <search type> {<query>} {<string1>} {<string2>}} |
| 8846 | |
| 8847 | The two forms of lookup item specify data lookups in files and databases, |
| 8848 | as discussed in chapter 9. The first form is used for single-key lookups, |
| 8849 | and the second is used for query-style lookups. The <key>, <file>, and < |
| 8850 | query> strings are expanded before use. |
| 8851 | |
| 8852 | If there is any white space in a lookup item which is part of a filter |
| 8853 | command, a retry or rewrite rule, a routing rule for the manualroute |
| 8854 | router, or any other place where white space is significant, the lookup |
| 8855 | item must be enclosed in double quotes. The use of data lookups in users' |
| 8856 | filter files may be locked out by the system administrator. |
| 8857 | |
| 8858 | If the lookup succeeds, <string1> is expanded and replaces the entire item. |
| 8859 | During its expansion, the variable $value contains the data returned by the |
| 8860 | lookup. Afterwards it reverts to the value it had previously (at the outer |
| 8861 | level it is empty). If the lookup fails, <string2> is expanded and replaces |
| 8862 | the entire item. If {<string2>} is omitted, the replacement is the empty |
| 8863 | string on failure. If <string2> is provided, it can itself be a nested |
| 8864 | lookup, thus providing a mechanism for looking up a default value when the |
| 8865 | original lookup fails. |
| 8866 | |
| 8867 | If a nested lookup is used as part of <string1>, $value contains the data |
| 8868 | for the outer lookup while the parameters of the second lookup are |
| 8869 | expanded, and also while <string2> of the second lookup is expanded, should |
| 8870 | the second lookup fail. Instead of {<string2>} the word "fail" can appear, |
| 8871 | and in this case, if the lookup fails, the entire expansion is forced to |
| 8872 | fail (see section 11.4). If both {<string1>} and {<string2>} are omitted, |
| 8873 | the result is the looked up value in the case of a successful lookup, and |
| 8874 | nothing in the case of failure. |
| 8875 | |
| 8876 | For single-key lookups, the string "partial" is permitted to precede the |
| 8877 | search type in order to do partial matching, and * or *@ may follow a |
| 8878 | search type to request default lookups if the key does not match (see |
| 8879 | sections 9.6 and 9.7 for details). |
| 8880 | |
| 8881 | If a partial search is used, the variables $1 and $2 contain the wild and |
| 8882 | non-wild parts of the key during the expansion of the replacement text. |
| 8883 | They return to their previous values at the end of the lookup item. |
| 8884 | |
| 8885 | This example looks up the postmaster alias in the conventional alias file: |
| 8886 | |
| 8887 | ${lookup {postmaster} lsearch {/etc/aliases} {$value}} |
| 8888 | |
| 8889 | This example uses NIS+ to look up the full name of the user corresponding |
| 8890 | to the local part of an address, forcing the expansion to fail if it is not |
| 8891 | found: |
| 8892 | |
| 8893 | ${lookup nisplus {[name=$local_part],passwd.org_dir:gcos} \ |
| 8894 | {$value}fail} |
| 8895 | |
| 8896 | ${map{<string1>}{<string2>}} |
| 8897 | |
| 8898 | After expansion, <string1> is interpreted as a list, colon-separated by |
| 8899 | default, but the separator can be changed in the usual way. For each item |
| 8900 | in this list, its value is place in $item, and then <string2> is expanded |
| 8901 | and added to the output as an item in a new list. The separator used for |
| 8902 | the output list is the same as the one used for the input, but a separator |
| 8903 | setting is not included in the output. For example: |
| 8904 | |
| 8905 | ${map{a:b:c}{[$item]}} ${map{<- x-y-z}{($item)}} |
| 8906 | |
| 8907 | expands to "[a]:[b]:[c] (x)-(y)-(z)". At the end of the expansion, the |
| 8908 | value of $item is restored to what it was before. See also the filter and |
| 8909 | reduce expansion items. |
| 8910 | |
| 8911 | ${nhash{<string1>}{<string2>}{<string3>}} |
| 8912 | |
| 8913 | The three strings are expanded; the first two must yield numbers. Call them |
| 8914 | <n> and <m>. If you are using fixed values for these numbers, that is, if < |
| 8915 | string1> and <string2> do not change when they are expanded, you can use |
| 8916 | the simpler operator notation that avoids some of the braces: |
| 8917 | |
| 8918 | ${nhash_<n>_<m>:<string>} |
| 8919 | |
| 8920 | The second number is optional (in both notations). If there is only one |
| 8921 | number, the result is a number in the range 0-<n>-1. Otherwise, the string |
| 8922 | is processed by a div/mod hash function that returns two numbers, separated |
| 8923 | by a slash, in the ranges 0 to <n>-1 and 0 to <m>-1, respectively. For |
| 8924 | example, |
| 8925 | |
| 8926 | ${nhash{8}{64}{supercalifragilisticexpialidocious}} |
| 8927 | |
| 8928 | returns the string "6/33". |
| 8929 | |
| 8930 | ${perl{<subroutine>}{<arg>}{<arg>}...} |
| 8931 | |
| 8932 | This item is available only if Exim has been built to include an embedded |
| 8933 | Perl interpreter. The subroutine name and the arguments are first |
| 8934 | separately expanded, and then the Perl subroutine is called with those |
| 8935 | arguments. No additional arguments need be given; the maximum number |
| 8936 | permitted, including the name of the subroutine, is nine. |
| 8937 | |
| 8938 | The return value of the subroutine is inserted into the expanded string, |
| 8939 | unless the return value is undef. In that case, the expansion fails in the |
| 8940 | same way as an explicit "fail" on a lookup item. The return value is a |
| 8941 | scalar. Whatever you return is evaluated in a scalar context. For example, |
| 8942 | if you return the name of a Perl vector, the return value is the size of |
| 8943 | the vector, not its contents. |
| 8944 | |
| 8945 | If the subroutine exits by calling Perl's die function, the expansion fails |
| 8946 | with the error message that was passed to die. More details of the embedded |
| 8947 | Perl facility are given in chapter 12. |
| 8948 | |
| 8949 | The redirect router has an option called forbid_filter_perl which locks out |
| 8950 | the use of this expansion item in filter files. |
| 8951 | |
| 8952 | ${prvs{<address>}{<secret>}{<keynumber>}} |
| 8953 | |
| 8954 | The first argument is a complete email address and the second is secret |
| 8955 | keystring. The third argument, specifying a key number, is optional. If |
| 8956 | absent, it defaults to 0. The result of the expansion is a prvs-signed |
| 8957 | email address, to be typically used with the return_path option on an smtp |
| 8958 | transport as part of a bounce address tag validation (BATV) scheme. For |
| 8959 | more discussion and an example, see section 43.51. |
| 8960 | |
| 8961 | ${prvscheck{<address>}{<secret>}{<string>}} |
| 8962 | |
| 8963 | This expansion item is the complement of the prvs item. It is used for |
| 8964 | checking prvs-signed addresses. If the expansion of the first argument does |
| 8965 | not yield a syntactically valid prvs-signed address, the whole item expands |
| 8966 | to the empty string. When the first argument does expand to a syntactically |
| 8967 | valid prvs-signed address, the second argument is expanded, with the |
| 8968 | prvs-decoded version of the address and the key number extracted from the |
| 8969 | address in the variables $prvscheck_address and $prvscheck_keynum, |
| 8970 | respectively. |
| 8971 | |
| 8972 | These two variables can be used in the expansion of the second argument to |
| 8973 | retrieve the secret. The validity of the prvs-signed address is then |
| 8974 | checked against the secret. The result is stored in the variable |
| 8975 | $prvscheck_result, which is empty for failure or "1" for success. |
| 8976 | |
| 8977 | The third argument is optional; if it is missing, it defaults to an empty |
| 8978 | string. This argument is now expanded. If the result is an empty string, |
| 8979 | the result of the expansion is the decoded version of the address. This is |
| 8980 | the case whether or not the signature was valid. Otherwise, the result of |
| 8981 | the expansion is the expansion of the third argument. |
| 8982 | |
| 8983 | All three variables can be used in the expansion of the third argument. |
| 8984 | However, once the expansion is complete, only $prvscheck_result remains |
| 8985 | set. For more discussion and an example, see section 43.51. |
| 8986 | |
| 8987 | ${readfile{<file name>}{<eol string>}} |
| 8988 | |
| 8989 | The file name and end-of-line string are first expanded separately. The |
| 8990 | file is then read, and its contents replace the entire item. All newline |
| 8991 | characters in the file are replaced by the end-of-line string if it is |
| 8992 | present. Otherwise, newlines are left in the string. String expansion is |
| 8993 | not applied to the contents of the file. If you want this, you must wrap |
| 8994 | the item in an expand operator. If the file cannot be read, the string |
| 8995 | expansion fails. |
| 8996 | |
| 8997 | The redirect router has an option called forbid_filter_readfile which locks |
| 8998 | out the use of this expansion item in filter files. |
| 8999 | |
| 9000 | ${readsocket{<name>}{<request>}{<timeout>}{<eol string>}{<fail string>}} |
| 9001 | |
| 9002 | This item inserts data from a Unix domain or TCP socket into the expanded |
| 9003 | string. The minimal way of using it uses just two arguments, as in these |
| 9004 | examples: |
| 9005 | |
| 9006 | ${readsocket{/socket/name}{request string}} |
| 9007 | ${readsocket{inet:some.host:1234}{request string}} |
| 9008 | |
| 9009 | For a Unix domain socket, the first substring must be the path to the |
| 9010 | socket. For an Internet socket, the first substring must contain "inet:" |
| 9011 | followed by a host name or IP address, followed by a colon and a port, |
| 9012 | which can be a number or the name of a TCP port in /etc/services. An IP |
| 9013 | address may optionally be enclosed in square brackets. This is best for |
| 9014 | IPv6 addresses. For example: |
| 9015 | |
| 9016 | ${readsocket{inet:[::1]:1234}{request string}} |
| 9017 | |
| 9018 | Only a single host name may be given, but if looking it up yields more than |
| 9019 | one IP address, they are each tried in turn until a connection is made. For |
| 9020 | both kinds of socket, Exim makes a connection, writes the request string |
| 9021 | unless it is an empty string; and no terminating NUL is ever sent) and |
| 9022 | reads from the socket until an end-of-file is read. A timeout of 5 seconds |
| 9023 | is applied. Additional, optional arguments extend what can be done. |
| 9024 | Firstly, you can vary the timeout. For example: |
| 9025 | |
| 9026 | ${readsocket{/socket/name}{request string}{3s}} |
| 9027 | |
| 9028 | A fourth argument allows you to change any newlines that are in the data |
| 9029 | that is read, in the same way as for readfile (see above). This example |
| 9030 | turns them into spaces: |
| 9031 | |
| 9032 | ${readsocket{inet:127.0.0.1:3294}{request string}{3s}{ }} |
| 9033 | |
| 9034 | As with all expansions, the substrings are expanded before the processing |
| 9035 | happens. Errors in these sub-expansions cause the expansion to fail. In |
| 9036 | addition, the following errors can occur: |
| 9037 | |
| 9038 | + Failure to create a socket file descriptor; |
| 9039 | |
| 9040 | + Failure to connect the socket; |
| 9041 | |
| 9042 | + Failure to write the request string; |
| 9043 | |
| 9044 | + Timeout on reading from the socket. |
| 9045 | |
| 9046 | By default, any of these errors causes the expansion to fail. However, if |
| 9047 | you supply a fifth substring, it is expanded and used when any of the above |
| 9048 | errors occurs. For example: |
| 9049 | |
| 9050 | ${readsocket{/socket/name}{request string}{3s}{\n}\ |
| 9051 | {socket failure}} |
| 9052 | |
| 9053 | You can test for the existence of a Unix domain socket by wrapping this |
| 9054 | expansion in "${if exists", but there is a race condition between that test |
| 9055 | and the actual opening of the socket, so it is safer to use the fifth |
| 9056 | argument if you want to be absolutely sure of avoiding an expansion error |
| 9057 | for a non-existent Unix domain socket, or a failure to connect to an |
| 9058 | Internet socket. |
| 9059 | |
| 9060 | The redirect router has an option called forbid_filter_readsocket which |
| 9061 | locks out the use of this expansion item in filter files. |
| 9062 | |
| 9063 | ${reduce{<string1>}{<string2>}{<string3>}} |
| 9064 | |
| 9065 | This operation reduces a list to a single, scalar string. After expansion, |
| 9066 | <string1> is interpreted as a list, colon-separated by default, but the |
| 9067 | separator can be changed in the usual way. Then <string2> is expanded and |
| 9068 | assigned to the $value variable. After this, each item in the <string1> |
| 9069 | list is assigned to $item in turn, and <string3> is expanded for each of |
| 9070 | them. The result of that expansion is assigned to $value before the next |
| 9071 | iteration. When the end of the list is reached, the final value of $value |
| 9072 | is added to the expansion output. The reduce expansion item can be used in |
| 9073 | a number of ways. For example, to add up a list of numbers: |
| 9074 | |
| 9075 | ${reduce {<, 1,2,3}{0}{${eval:$value+$item}}} |
| 9076 | |
| 9077 | The result of that expansion would be "6". The maximum of a list of numbers |
| 9078 | can be found: |
| 9079 | |
| 9080 | ${reduce {3:0:9:4:6}{0}{${if >{$item}{$value}{$item}{$value}}}} |
| 9081 | |
| 9082 | At the end of a reduce expansion, the values of $item and $value are |
| 9083 | restored to what they were before. See also the filter and map expansion |
| 9084 | items. |
| 9085 | |
| 9086 | $rheader_<header name>: or $rh_<header name>: |
| 9087 | |
| 9088 | This item inserts "raw" header lines. It is described with the header |
| 9089 | expansion item above. |
| 9090 | |
| 9091 | ${run{<command> <args>}{<string1>}{<string2>}} |
| 9092 | |
| 9093 | The command and its arguments are first expanded as one string. The string |
| 9094 | is split apart into individual arguments by spaces, and then the command is |
| 9095 | run in a separate process, but under the same uid and gid. As in other |
| 9096 | command executions from Exim, a shell is not used by default. If the |
| 9097 | command requires a shell, you must explicitly code it. |
| 9098 | |
| 9099 | Since the arguments are split by spaces, when there is a variable expansion |
| 9100 | which has an empty result, it will cause the situation that the argument |
| 9101 | will simply be omitted when the program is actually executed by Exim. If |
| 9102 | the script/program requires a specific number of arguments and the expanded |
| 9103 | variable could possibly result in this empty expansion, the variable must |
| 9104 | be quoted. This is more difficult if the expanded variable itself could |
| 9105 | result in a string containing quotes, because it would interfere with the |
| 9106 | quotes around the command arguments. A possible guard against this is to |
| 9107 | wrap the variable in the sg operator to change any quote marks to some |
| 9108 | other character. |
| 9109 | |
| 9110 | The standard input for the command exists, but is empty. The standard |
| 9111 | output and standard error are set to the same file descriptor. If the |
| 9112 | command succeeds (gives a zero return code) <string1> is expanded and |
| 9113 | replaces the entire item; during this expansion, the standard output/error |
| 9114 | from the command is in the variable $value. If the command fails, <string2 |
| 9115 | >, if present, is expanded and used. Once again, during the expansion, the |
| 9116 | standard output/error from the command is in the variable $value. |
| 9117 | |
| 9118 | If <string2> is absent, the result is empty. Alternatively, <string2> can |
| 9119 | be the word "fail" (not in braces) to force expansion failure if the |
| 9120 | command does not succeed. If both strings are omitted, the result is |
| 9121 | contents of the standard output/error on success, and nothing on failure. |
| 9122 | |
| 9123 | The standard output/error of the command is put in the variable $value. In |
| 9124 | this ACL example, the output of a command is logged for the admin to |
| 9125 | troubleshoot: |
| 9126 | |
| 9127 | warn condition = ${run{/usr/bin/id}{yes}{no}} |
| 9128 | log_message = Output of id: $value |
| 9129 | |
| 9130 | If the command requires shell idioms, such as the > redirect operator, the |
| 9131 | shell must be invoked directly, such as with: |
| 9132 | |
| 9133 | ${run{/bin/bash -c "/usr/bin/id >/tmp/id"}{yes}{yes}} |
| 9134 | |
| 9135 | The return code from the command is put in the variable $runrc, and this |
| 9136 | remains set afterwards, so in a filter file you can do things like this: |
| 9137 | |
| 9138 | if "${run{x y z}{}}$runrc" is 1 then ... |
| 9139 | elif $runrc is 2 then ... |
| 9140 | ... |
| 9141 | endif |
| 9142 | |
| 9143 | If execution of the command fails (for example, the command does not |
| 9144 | exist), the return code is 127 - the same code that shells use for |
| 9145 | non-existent commands. |
| 9146 | |
| 9147 | Warning: In a router or transport, you cannot assume the order in which |
| 9148 | option values are expanded, except for those preconditions whose order of |
| 9149 | testing is documented. Therefore, you cannot reliably expect to set $runrc |
| 9150 | by the expansion of one option, and use it in another. |
| 9151 | |
| 9152 | The redirect router has an option called forbid_filter_run which locks out |
| 9153 | the use of this expansion item in filter files. |
| 9154 | |
| 9155 | ${sg{<subject>}{<regex>}{<replacement>}} |
| 9156 | |
| 9157 | This item works like Perl's substitution operator (s) with the global (/g) |
| 9158 | option; hence its name. However, unlike the Perl equivalent, Exim does not |
| 9159 | modify the subject string; instead it returns the modified string for |
| 9160 | insertion into the overall expansion. The item takes three arguments: the |
| 9161 | subject string, a regular expression, and a substitution string. For |
| 9162 | example: |
| 9163 | |
| 9164 | ${sg{abcdefabcdef}{abc}{xyz}} |
| 9165 | |
| 9166 | yields "xyzdefxyzdef". Because all three arguments are expanded before use, |
| 9167 | if any $ or \ characters are required in the regular expression or in the |
| 9168 | substitution string, they have to be escaped. For example: |
| 9169 | |
| 9170 | ${sg{abcdef}{^(...)(...)\$}{\$2\$1}} |
| 9171 | |
| 9172 | yields "defabc", and |
| 9173 | |
| 9174 | ${sg{1=A 4=D 3=C}{\N(\d+)=\N}{K\$1=}} |
| 9175 | |
| 9176 | yields "K1=A K4=D K3=C". Note the use of "\N" to protect the contents of |
| 9177 | the regular expression from string expansion. |
| 9178 | |
| 9179 | ${sort{<string>}{<comparator>}{<extractor>}} |
| 9180 | |
| 9181 | After expansion, <string> is interpreted as a list, colon-separated by |
| 9182 | default, but the separator can be changed in the usual way. The <comparator |
| 9183 | > argument is interpreted as the operator of a two-argument expansion |
| 9184 | condition. The numeric operators plus ge, gt, le, lt (and ~i variants) are |
| 9185 | supported. The comparison should return true when applied to two values if |
| 9186 | the first value should sort before the second value. The <extractor> |
| 9187 | expansion is applied repeatedly to elements of the list, the element being |
| 9188 | placed in $item, to give values for comparison. |
| 9189 | |
| 9190 | The item result is a sorted list, with the original list separator, of the |
| 9191 | list elements (in full) of the original. |
| 9192 | |
| 9193 | Examples: |
| 9194 | |
| 9195 | ${sort{3:2:1:4}{<}{$item}} |
| 9196 | |
| 9197 | sorts a list of numbers, and |
| 9198 | |
| 9199 | ${sort {${lookup dnsdb{>:,,mx=example.com}}} {<} {${listextract{1}{<,$item}}}} |
| 9200 | |
| 9201 | will sort an MX lookup into priority order. |
| 9202 | |
| 9203 | ${substr{<string1>}{<string2>}{<string3>}} |
| 9204 | |
| 9205 | The three strings are expanded; the first two must yield numbers. Call them |
| 9206 | <n> and <m>. If you are using fixed values for these numbers, that is, if < |
| 9207 | string1> and <string2> do not change when they are expanded, you can use |
| 9208 | the simpler operator notation that avoids some of the braces: |
| 9209 | |
| 9210 | ${substr_<n>_<m>:<string>} |
| 9211 | |
| 9212 | The second number is optional (in both notations). If it is absent in the |
| 9213 | simpler format, the preceding underscore must also be omitted. |
| 9214 | |
| 9215 | The substr item can be used to extract more general substrings than length. |
| 9216 | The first number, <n>, is a starting offset, and <m> is the length |
| 9217 | required. For example |
| 9218 | |
| 9219 | ${substr{3}{2}{$local_part}} |
| 9220 | |
| 9221 | If the starting offset is greater than the string length the result is the |
| 9222 | null string; if the length plus starting offset is greater than the string |
| 9223 | length, the result is the right-hand part of the string, starting from the |
| 9224 | given offset. The first character in the string has offset zero. |
| 9225 | |
| 9226 | The substr expansion item can take negative offset values to count from the |
| 9227 | right-hand end of its operand. The last character is offset -1, the |
| 9228 | second-last is offset -2, and so on. Thus, for example, |
| 9229 | |
| 9230 | ${substr{-5}{2}{1234567}} |
| 9231 | |
| 9232 | yields "34". If the absolute value of a negative offset is greater than the |
| 9233 | length of the string, the substring starts at the beginning of the string, |
| 9234 | and the length is reduced by the amount of overshoot. Thus, for example, |
| 9235 | |
| 9236 | ${substr{-5}{2}{12}} |
| 9237 | |
| 9238 | yields an empty string, but |
| 9239 | |
| 9240 | ${substr{-3}{2}{12}} |
| 9241 | |
| 9242 | yields "1". |
| 9243 | |
| 9244 | When the second number is omitted from substr, the remainder of the string |
| 9245 | is taken if the offset is positive. If it is negative, all characters in |
| 9246 | the string preceding the offset point are taken. For example, an offset of |
| 9247 | -1 and no length, as in these semantically identical examples: |
| 9248 | |
| 9249 | ${substr_-1:abcde} |
| 9250 | ${substr{-1}{abcde}} |
| 9251 | |
| 9252 | yields all but the last character of the string, that is, "abcd". |
| 9253 | |
| 9254 | ${tr{<subject>}{<characters>}{<replacements>}} |
| 9255 | |
| 9256 | This item does single-character translation on its subject string. The |
| 9257 | second argument is a list of characters to be translated in the subject |
| 9258 | string. Each matching character is replaced by the corresponding character |
| 9259 | from the replacement list. For example |
| 9260 | |
| 9261 | ${tr{abcdea}{ac}{13}} |
| 9262 | |
| 9263 | yields "1b3de1". If there are duplicates in the second character string, |
| 9264 | the last occurrence is used. If the third string is shorter than the |
| 9265 | second, its last character is replicated. However, if it is empty, no |
| 9266 | translation takes place. |
| 9267 | |
| 9268 | |
| 9269 | 11.6 Expansion operators |
| 9270 | ------------------------ |
| 9271 | |
| 9272 | For expansion items that perform transformations on a single argument string, |
| 9273 | the "operator" notation is used because it is simpler and uses fewer braces. |
| 9274 | The substring is first expanded before the operation is applied to it. The |
| 9275 | following operations can be performed: |
| 9276 | |
| 9277 | ${address:<string>} |
| 9278 | |
| 9279 | The string is interpreted as an RFC 2822 address, as it might appear in a |
| 9280 | header line, and the effective address is extracted from it. If the string |
| 9281 | does not parse successfully, the result is empty. |
| 9282 | |
| 9283 | ${addresses:<string>} |
| 9284 | |
| 9285 | The string (after expansion) is interpreted as a list of addresses in RFC |
| 9286 | 2822 format, such as can be found in a To: or Cc: header line. The |
| 9287 | operative address (local-part@domain) is extracted from each item, and the |
| 9288 | result of the expansion is a colon-separated list, with appropriate |
| 9289 | doubling of colons should any happen to be present in the email addresses. |
| 9290 | Syntactically invalid RFC2822 address items are omitted from the output. |
| 9291 | |
| 9292 | It is possible to specify a character other than colon for the output |
| 9293 | separator by starting the string with > followed by the new separator |
| 9294 | character. For example: |
| 9295 | |
| 9296 | ${addresses:>& Chief <ceo@up.stairs>, sec@base.ment (dogsbody)} |
| 9297 | |
| 9298 | expands to "ceo@up.stairs&sec@base.ment". Compare the address (singular) |
| 9299 | expansion item, which extracts the working address from a single RFC2822 |
| 9300 | address. See the filter, map, and reduce items for ways of processing |
| 9301 | lists. |
| 9302 | |
| 9303 | To clarify "list of addresses in RFC 2822 format" mentioned above, Exim |
| 9304 | follows a strict interpretation of header line formatting. Exim parses the |
| 9305 | bare, unquoted portion of an email address and if it finds a comma, treats |
| 9306 | it as an email address separator. For the example header line: |
| 9307 | |
| 9308 | From: =?iso-8859-2?Q?Last=2C_First?= <user@example.com> |
| 9309 | |
| 9310 | The first example below demonstrates that Q-encoded email addresses are |
| 9311 | parsed properly if it is given the raw header (in this example, |
| 9312 | "$rheader_from:"). It does not see the comma because it's still encoded as |
| 9313 | "=2C". The second example below is passed the contents of "$header_from:", |
| 9314 | meaning it gets de-mimed. Exim sees the decoded "," so it treats it as two |
| 9315 | email addresses. The third example shows that the presence of a comma is |
| 9316 | skipped when it is quoted. |
| 9317 | |
| 9318 | # exim -be '${addresses:From: \ |
| 9319 | =?iso-8859-2?Q?Last=2C_First?= <user@example.com>}' |
| 9320 | user@example.com |
| 9321 | # exim -be '${addresses:From: Last, First <user@example.com>}' |
| 9322 | Last:user@example.com |
| 9323 | # exim -be '${addresses:From: "Last, First" <user@example.com>}' |
| 9324 | user@example.com |
| 9325 | |
| 9326 | ${base32:<digits>} |
| 9327 | |
| 9328 | The string must consist entirely of decimal digits. The number is converted |
| 9329 | to base 32 and output as a (empty, for zero) string of characters. Only |
| 9330 | lowercase letters are used. |
| 9331 | |
| 9332 | ${base32d:<base-32 digits>} |
| 9333 | |
| 9334 | The string must consist entirely of base-32 digits. The number is converted |
| 9335 | to decimal and output as a string. |
| 9336 | |
| 9337 | ${base62:<digits>} |
| 9338 | |
| 9339 | The string must consist entirely of decimal digits. The number is converted |
| 9340 | to base 62 and output as a string of six characters, including leading |
| 9341 | zeros. In the few operating environments where Exim uses base 36 instead of |
| 9342 | base 62 for its message identifiers (because those systems do not have |
| 9343 | case-sensitive file names), base 36 is used by this operator, despite its |
| 9344 | name. Note: Just to be absolutely clear: this is not base64 encoding. |
| 9345 | |
| 9346 | ${base62d:<base-62 digits>} |
| 9347 | |
| 9348 | The string must consist entirely of base-62 digits, or, in operating |
| 9349 | environments where Exim uses base 36 instead of base 62 for its message |
| 9350 | identifiers, base-36 digits. The number is converted to decimal and output |
| 9351 | as a string. |
| 9352 | |
| 9353 | ${base64:<string>} |
| 9354 | |
| 9355 | This operator converts a string into one that is base64 encoded. |
| 9356 | |
| 9357 | If the string is a single variable of type certificate, returns the base64 |
| 9358 | encoding of the DER form of the certificate. |
| 9359 | |
| 9360 | ${base64d:<string>} |
| 9361 | |
| 9362 | This operator converts a base64-encoded string into the un-coded form. |
| 9363 | |
| 9364 | ${domain:<string>} |
| 9365 | |
| 9366 | The string is interpreted as an RFC 2822 address and the domain is |
| 9367 | extracted from it. If the string does not parse successfully, the result is |
| 9368 | empty. |
| 9369 | |
| 9370 | ${escape:<string>} |
| 9371 | |
| 9372 | If the string contains any non-printing characters, they are converted to |
| 9373 | escape sequences starting with a backslash. Whether characters with the |
| 9374 | most significant bit set (so-called "8-bit characters") count as printing |
| 9375 | or not is controlled by the print_topbitchars option. |
| 9376 | |
| 9377 | ${escape8bit:<string>} |
| 9378 | |
| 9379 | If the string contains and characters with the most significant bit set, |
| 9380 | they are converted to escape sequences starting with a backslash. |
| 9381 | Backslashes and DEL characters are also converted. |
| 9382 | |
| 9383 | ${eval:<string>} and ${eval10:<string>} |
| 9384 | |
| 9385 | These items supports simple arithmetic and bitwise logical operations in |
| 9386 | expansion strings. The string (after expansion) must be a conventional |
| 9387 | arithmetic expression, but it is limited to basic arithmetic operators, |
| 9388 | bitwise logical operators, and parentheses. All operations are carried out |
| 9389 | using integer arithmetic. The operator priorities are as follows (the same |
| 9390 | as in the C programming language): |
| 9391 | |
| 9392 | highest: not (~), negate (-) |
| 9393 | multiply (*), divide (/), remainder (%) |
| 9394 | plus (+), minus (-) |
| 9395 | shift-left (<<), shift-right (>>) |
| 9396 | and (&) |
| 9397 | xor (^) |
| 9398 | lowest: or (|) |
| 9399 | |
| 9400 | Binary operators with the same priority are evaluated from left to right. |
| 9401 | White space is permitted before or after operators. |
| 9402 | |
| 9403 | For eval, numbers may be decimal, octal (starting with "0") or hexadecimal |
| 9404 | (starting with "0x"). For eval10, all numbers are taken as decimal, even if |
| 9405 | they start with a leading zero; hexadecimal numbers are not permitted. This |
| 9406 | can be useful when processing numbers extracted from dates or times, which |
| 9407 | often do have leading zeros. |
| 9408 | |
| 9409 | A number may be followed by "K", "M" or "G" to multiply it by 1024, |
| 9410 | 1024*1024 or 1024*1024*1024, respectively. Negative numbers are supported. |
| 9411 | The result of the computation is a decimal representation of the answer |
| 9412 | (without "K", "M" or "G"). For example: |
| 9413 | |
| 9414 | ${eval:1+1} yields 2 |
| 9415 | ${eval:1+2*3} yields 7 |
| 9416 | ${eval:(1+2)*3} yields 9 |
| 9417 | ${eval:2+42%5} yields 4 |
| 9418 | ${eval:0xc&5} yields 4 |
| 9419 | ${eval:0xc|5} yields 13 |
| 9420 | ${eval:0xc^5} yields 9 |
| 9421 | ${eval:0xc>>1} yields 6 |
| 9422 | ${eval:0xc<<1} yields 24 |
| 9423 | ${eval:~255&0x1234} yields 4608 |
| 9424 | ${eval:-(~255&0x1234)} yields -4608 |
| 9425 | |
| 9426 | As a more realistic example, in an ACL you might have |
| 9427 | |
| 9428 | deny message = Too many bad recipients |
| 9429 | condition = \ |
| 9430 | ${if and { \ |
| 9431 | {>{$rcpt_count}{10}} \ |
| 9432 | { \ |
| 9433 | < \ |
| 9434 | {$recipients_count} \ |
| 9435 | {${eval:$rcpt_count/2}} \ |
| 9436 | } \ |
| 9437 | }{yes}{no}} |
| 9438 | |
| 9439 | The condition is true if there have been more than 10 RCPT commands and |
| 9440 | fewer than half of them have resulted in a valid recipient. |
| 9441 | |
| 9442 | ${expand:<string>} |
| 9443 | |
| 9444 | The expand operator causes a string to be expanded for a second time. For |
| 9445 | example, |
| 9446 | |
| 9447 | ${expand:${lookup{$domain}dbm{/some/file}{$value}}} |
| 9448 | |
| 9449 | first looks up a string in a file while expanding the operand for expand, |
| 9450 | and then re-expands what it has found. |
| 9451 | |
| 9452 | ${from_utf8:<string>} |
| 9453 | |
| 9454 | The world is slowly moving towards Unicode, although there are no standards |
| 9455 | for email yet. However, other applications (including some databases) are |
| 9456 | starting to store data in Unicode, using UTF-8 encoding. This operator |
| 9457 | converts from a UTF-8 string to an ISO-8859-1 string. UTF-8 code values |
| 9458 | greater than 255 are converted to underscores. The input must be a valid |
| 9459 | UTF-8 string. If it is not, the result is an undefined sequence of bytes. |
| 9460 | |
| 9461 | Unicode code points with values less than 256 are compatible with ASCII and |
| 9462 | ISO-8859-1 (also known as Latin-1). For example, character 169 is the |
| 9463 | copyright symbol in both cases, though the way it is encoded is different. |
| 9464 | In UTF-8, more than one byte is needed for characters with code values |
| 9465 | greater than 127, whereas ISO-8859-1 is a single-byte encoding (but thereby |
| 9466 | limited to 256 characters). This makes translation from UTF-8 to ISO-8859-1 |
| 9467 | straightforward. |
| 9468 | |
| 9469 | ${hash_<n>_<m>:<string>} |
| 9470 | |
| 9471 | The hash operator is a simpler interface to the hashing function that can |
| 9472 | be used when the two parameters are fixed numbers (as opposed to strings |
| 9473 | that change when expanded). The effect is the same as |
| 9474 | |
| 9475 | ${hash{<n>}{<m>}{<string>}} |
| 9476 | |
| 9477 | See the description of the general hash item above for details. The |
| 9478 | abbreviation h can be used when hash is used as an operator. |
| 9479 | |
| 9480 | ${hex2b64:<hexstring>} |
| 9481 | |
| 9482 | This operator converts a hex string into one that is base64 encoded. This |
| 9483 | can be useful for processing the output of the MD5 and SHA-1 hashing |
| 9484 | functions. |
| 9485 | |
| 9486 | ${hexquote:<string>} |
| 9487 | |
| 9488 | This operator converts non-printable characters in a string into a hex |
| 9489 | escape form. Byte values between 33 (!) and 126 (~) inclusive are left as |
| 9490 | is, and other byte values are converted to "\xNN", for example a byte value |
| 9491 | 127 is converted to "\x7f". |
| 9492 | |
| 9493 | ${ipv6denorm:<string>} |
| 9494 | |
| 9495 | This expands an IPv6 address to a full eight-element colon-separated set of |
| 9496 | hex digits including leading zeroes. A trailing ipv4-style dotted-decimal |
| 9497 | set is converted to hex. Pure IPv4 addresses are converted to IPv4-mapped |
| 9498 | IPv6. |
| 9499 | |
| 9500 | ${ipv6norm:<string>} |
| 9501 | |
| 9502 | This converts an IPv6 address to canonical form. Leading zeroes of groups |
| 9503 | are omitted, and the longest set of zero-valued groups is replaced with a |
| 9504 | double colon. A trailing ipv4-style dotted-decimal set is converted to hex. |
| 9505 | Pure IPv4 addresses are converted to IPv4-mapped IPv6. |
| 9506 | |
| 9507 | ${lc:<string>} |
| 9508 | |
| 9509 | This forces the letters in the string into lower-case, for example: |
| 9510 | |
| 9511 | ${lc:$local_part} |
| 9512 | |
| 9513 | ${length_<number>:<string>} |
| 9514 | |
| 9515 | The length operator is a simpler interface to the length function that can |
| 9516 | be used when the parameter is a fixed number (as opposed to a string that |
| 9517 | changes when expanded). The effect is the same as |
| 9518 | |
| 9519 | ${length{<number>}{<string>}} |
| 9520 | |
| 9521 | See the description of the general length item above for details. Note that |
| 9522 | length is not the same as strlen. The abbreviation l can be used when |
| 9523 | length is used as an operator. |
| 9524 | |
| 9525 | ${listcount:<string>} |
| 9526 | |
| 9527 | The string is interpreted as a list and the number of items is returned. |
| 9528 | |
| 9529 | ${listnamed:<name>} and ${listnamed_<type>:<name>} |
| 9530 | |
| 9531 | The name is interpreted as a named list and the content of the list is |
| 9532 | returned, expanding any referenced lists, re-quoting as needed for |
| 9533 | colon-separation. If the optional type is given it must be one of "a", "d", |
| 9534 | "h" or "l" and selects address-, domain-, host- or localpart- lists to |
| 9535 | search among respectively. Otherwise all types are searched in an undefined |
| 9536 | order and the first matching list is returned. |
| 9537 | |
| 9538 | ${local_part:<string>} |
| 9539 | |
| 9540 | The string is interpreted as an RFC 2822 address and the local part is |
| 9541 | extracted from it. If the string does not parse successfully, the result is |
| 9542 | empty. |
| 9543 | |
| 9544 | ${mask:<IP address>/<bit count>} |
| 9545 | |
| 9546 | If the form of the string to be operated on is not an IP address followed |
| 9547 | by a slash and an integer (that is, a network address in CIDR notation), |
| 9548 | the expansion fails. Otherwise, this operator converts the IP address to |
| 9549 | binary, masks off the least significant bits according to the bit count, |
| 9550 | and converts the result back to text, with mask appended. For example, |
| 9551 | |
| 9552 | ${mask:10.111.131.206/28} |
| 9553 | |
| 9554 | returns the string "10.111.131.192/28". Since this operation is expected to |
| 9555 | be mostly used for looking up masked addresses in files, the result for an |
| 9556 | IPv6 address uses dots to separate components instead of colons, because |
| 9557 | colon terminates a key string in lsearch files. So, for example, |
| 9558 | |
| 9559 | ${mask:3ffe:ffff:836f:0a00:000a:0800:200a:c031/99} |
| 9560 | |
| 9561 | returns the string |
| 9562 | |
| 9563 | 3ffe.ffff.836f.0a00.000a.0800.2000.0000/99 |
| 9564 | |
| 9565 | Letters in IPv6 addresses are always output in lower case. |
| 9566 | |
| 9567 | ${md5:<string>} |
| 9568 | |
| 9569 | The md5 operator computes the MD5 hash value of the string, and returns it |
| 9570 | as a 32-digit hexadecimal number, in which any letters are in lower case. |
| 9571 | |
| 9572 | If the string is a single variable of type certificate, returns the MD5 |
| 9573 | hash fingerprint of the certificate. |
| 9574 | |
| 9575 | ${nhash_<n>_<m>:<string>} |
| 9576 | |
| 9577 | The nhash operator is a simpler interface to the numeric hashing function |
| 9578 | that can be used when the two parameters are fixed numbers (as opposed to |
| 9579 | strings that change when expanded). The effect is the same as |
| 9580 | |
| 9581 | ${nhash{<n>}{<m>}{<string>}} |
| 9582 | |
| 9583 | See the description of the general nhash item above for details. |
| 9584 | |
| 9585 | ${quote:<string>} |
| 9586 | |
| 9587 | The quote operator puts its argument into double quotes if it is an empty |
| 9588 | string or contains anything other than letters, digits, underscores, dots, |
| 9589 | and hyphens. Any occurrences of double quotes and backslashes are escaped |
| 9590 | with a backslash. Newlines and carriage returns are converted to "\n" and " |
| 9591 | \r", respectively For example, |
| 9592 | |
| 9593 | ${quote:ab"*"cd} |
| 9594 | |
| 9595 | becomes |
| 9596 | |
| 9597 | "ab\"*\"cd" |
| 9598 | |
| 9599 | The place where this is useful is when the argument is a substitution from |
| 9600 | a variable or a message header. |
| 9601 | |
| 9602 | ${quote_local_part:<string>} |
| 9603 | |
| 9604 | This operator is like quote, except that it quotes the string only if |
| 9605 | required to do so by the rules of RFC 2822 for quoting local parts. For |
| 9606 | example, a plus sign would not cause quoting (but it would for quote). If |
| 9607 | you are creating a new email address from the contents of $local_part (or |
| 9608 | any other unknown data), you should always use this operator. |
| 9609 | |
| 9610 | ${quote_<lookup-type>:<string>} |
| 9611 | |
| 9612 | This operator applies lookup-specific quoting rules to the string. Each |
| 9613 | query-style lookup type has its own quoting rules which are described with |
| 9614 | the lookups in chapter 9. For example, |
| 9615 | |
| 9616 | ${quote_ldap:two * two} |
| 9617 | |
| 9618 | returns |
| 9619 | |
| 9620 | two%20%5C2A%20two |
| 9621 | |
| 9622 | For single-key lookup types, no quoting is ever necessary and this operator |
| 9623 | yields an unchanged string. |
| 9624 | |
| 9625 | ${randint:<n>} |
| 9626 | |
| 9627 | This operator returns a somewhat random number which is less than the |
| 9628 | supplied number and is at least 0. The quality of this randomness depends |
| 9629 | on how Exim was built; the values are not suitable for keying material. If |
| 9630 | Exim is linked against OpenSSL then RAND_pseudo_bytes() is used. If Exim is |
| 9631 | linked against GnuTLS then gnutls_rnd(GNUTLS_RND_NONCE) is used, for |
| 9632 | versions of GnuTLS with that function. Otherwise, the implementation may be |
| 9633 | arc4random(), random() seeded by srandomdev() or srandom(), or a custom |
| 9634 | implementation even weaker than random(). |
| 9635 | |
| 9636 | ${reverse_ip:<ipaddr>} |
| 9637 | |
| 9638 | This operator reverses an IP address; for IPv4 addresses, the result is in |
| 9639 | dotted-quad decimal form, while for IPv6 addresses the result is in |
| 9640 | dotted-nibble hexadecimal form. In both cases, this is the "natural" form |
| 9641 | for DNS. For example, |
| 9642 | |
| 9643 | ${reverse_ip:192.0.2.4} |
| 9644 | ${reverse_ip:2001:0db8:c42:9:1:abcd:192.0.2.127} |
| 9645 | |
| 9646 | returns |
| 9647 | |
| 9648 | 4.2.0.192 |
| 9649 | f.7.2.0.0.0.0.c.d.c.b.a.1.0.0.0.9.0.0.0.2.4.c.0.8.b.d.0.1.0.0.2 |
| 9650 | |
| 9651 | ${rfc2047:<string>} |
| 9652 | |
| 9653 | This operator encodes text according to the rules of RFC 2047. This is an |
| 9654 | encoding that is used in header lines to encode non-ASCII characters. It is |
| 9655 | assumed that the input string is in the encoding specified by the |
| 9656 | headers_charset option, which gets its default at build time. If the string |
| 9657 | contains only characters in the range 33-126, and no instances of the |
| 9658 | characters |
| 9659 | |
| 9660 | ? = ( ) < > @ , ; : \ " . [ ] _ |
| 9661 | |
| 9662 | it is not modified. Otherwise, the result is the RFC 2047 encoding of the |
| 9663 | string, using as many "encoded words" as necessary to encode all the |
| 9664 | characters. |
| 9665 | |
| 9666 | ${rfc2047d:<string>} |
| 9667 | |
| 9668 | This operator decodes strings that are encoded as per RFC 2047. Binary zero |
| 9669 | bytes are replaced by question marks. Characters are converted into the |
| 9670 | character set defined by headers_charset. Overlong RFC 2047 "words" are not |
| 9671 | recognized unless check_rfc2047_length is set false. |
| 9672 | |
| 9673 | Note: If you use $header_xxx: (or $h_xxx:) to access a header line, RFC |
| 9674 | 2047 decoding is done automatically. You do not need to use this operator |
| 9675 | as well. |
| 9676 | |
| 9677 | ${rxquote:<string>} |
| 9678 | |
| 9679 | The rxquote operator inserts a backslash before any non-alphanumeric |
| 9680 | characters in its argument. This is useful when substituting the values of |
| 9681 | variables or headers inside regular expressions. |
| 9682 | |
| 9683 | ${sha1:<string>} |
| 9684 | |
| 9685 | The sha1 operator computes the SHA-1 hash value of the string, and returns |
| 9686 | it as a 40-digit hexadecimal number, in which any letters are in upper |
| 9687 | case. |
| 9688 | |
| 9689 | If the string is a single variable of type certificate, returns the SHA-1 |
| 9690 | hash fingerprint of the certificate. |
| 9691 | |
| 9692 | ${sha256:<string>} |
| 9693 | |
| 9694 | The sha256 operator computes the SHA-256 hash value of the string and |
| 9695 | returns it as a 64-digit hexadecimal number, in which any letters are in |
| 9696 | upper case. |
| 9697 | |
| 9698 | If the string is a single variable of type certificate, returns the SHA-256 |
| 9699 | hash fingerprint of the certificate. |
| 9700 | |
| 9701 | ${sha3:<string>}, ${sha3_<n>:<string>} |
| 9702 | |
| 9703 | The sha3 operator computes the SHA3-256 hash value of the string and |
| 9704 | returns it as a 64-digit hexadecimal number, in which any letters are in |
| 9705 | upper case. |
| 9706 | |
| 9707 | If a number is appended, separated by an underbar, it specifies the output |
| 9708 | length. Values of 224, 256, 384 and 512 are accepted; with 256 being the |
| 9709 | default. |
| 9710 | |
| 9711 | The sha3 expansion item is only supported if Exim has been compiled with |
| 9712 | GnuTLS 3.5.0 or later. |
| 9713 | |
| 9714 | ${stat:<string>} |
| 9715 | |
| 9716 | The string, after expansion, must be a file path. A call to the stat() |
| 9717 | function is made for this path. If stat() fails, an error occurs and the |
| 9718 | expansion fails. If it succeeds, the data from the stat replaces the item, |
| 9719 | as a series of <name>=<value> pairs, where the values are all numerical, |
| 9720 | except for the value of "smode". The names are: "mode" (giving the mode as |
| 9721 | a 4-digit octal number), "smode" (giving the mode in symbolic format as a |
| 9722 | 10-character string, as for the ls command), "inode", "device", "links", |
| 9723 | "uid", "gid", "size", "atime", "mtime", and "ctime". You can extract |
| 9724 | individual fields using the extract expansion item. |
| 9725 | |
| 9726 | The use of the stat expansion in users' filter files can be locked out by |
| 9727 | the system administrator. Warning: The file size may be incorrect on 32-bit |
| 9728 | systems for files larger than 2GB. |
| 9729 | |
| 9730 | ${str2b64:<string>} |
| 9731 | |
| 9732 | Now deprecated, a synonym for the base64 expansion operator. |
| 9733 | |
| 9734 | ${strlen:<string>} |
| 9735 | |
| 9736 | The item is replace by the length of the expanded string, expressed as a |
| 9737 | decimal number. Note: Do not confuse strlen with length. |
| 9738 | |
| 9739 | ${substr_<start>_<length>:<string>} |
| 9740 | |
| 9741 | The substr operator is a simpler interface to the substr function that can |
| 9742 | be used when the two parameters are fixed numbers (as opposed to strings |
| 9743 | that change when expanded). The effect is the same as |
| 9744 | |
| 9745 | ${substr{<start>}{<length>}{<string>}} |
| 9746 | |
| 9747 | See the description of the general substr item above for details. The |
| 9748 | abbreviation s can be used when substr is used as an operator. |
| 9749 | |
| 9750 | ${time_eval:<string>} |
| 9751 | |
| 9752 | This item converts an Exim time interval such as "2d4h5m" into a number of |
| 9753 | seconds. |
| 9754 | |
| 9755 | ${time_interval:<string>} |
| 9756 | |
| 9757 | The argument (after sub-expansion) must be a sequence of decimal digits |
| 9758 | that represents an interval of time as a number of seconds. It is converted |
| 9759 | into a number of larger units and output in Exim's normal time format, for |
| 9760 | example, "1w3d4h2m6s". |
| 9761 | |
| 9762 | ${uc:<string>} |
| 9763 | |
| 9764 | This forces the letters in the string into upper-case. |
| 9765 | |
| 9766 | ${utf8clean:<string>} |
| 9767 | |
| 9768 | This replaces any invalid utf-8 sequence in the string by the character "? |
| 9769 | ". |
| 9770 | |
| 9771 | ${utf8_domain_to_alabel:<string>}, ${utf8_domain_from_alabel:<string>}, $ |
| 9772 | {utf8_localpart_to_alabel:<string>}, ${utf8_localpart_from_alabel:<string>} |
| 9773 | |
| 9774 | These convert EAI mail name components between UTF-8 and a-label forms. For |
| 9775 | information on internationalisation support see 59.1. |
| 9776 | |
| 9777 | |
| 9778 | 11.7 Expansion conditions |
| 9779 | ------------------------- |
| 9780 | |
| 9781 | The following conditions are available for testing by the ${if construct while |
| 9782 | expanding strings: |
| 9783 | |
| 9784 | !<condition> |
| 9785 | |
| 9786 | Preceding any condition with an exclamation mark negates the result of the |
| 9787 | condition. |
| 9788 | |
| 9789 | <symbolic operator> {<string1>}{<string2>} |
| 9790 | |
| 9791 | There are a number of symbolic operators for doing numeric comparisons. |
| 9792 | They are: |
| 9793 | |
| 9794 | = equal |
| 9795 | == equal |
| 9796 | > greater |
| 9797 | >= greater or equal |
| 9798 | < less |
| 9799 | <= less or equal |
| 9800 | |
| 9801 | For example: |
| 9802 | |
| 9803 | ${if >{$message_size}{10M} ... |
| 9804 | |
| 9805 | Note that the general negation operator provides for inequality testing. |
| 9806 | The two strings must take the form of optionally signed decimal integers, |
| 9807 | optionally followed by one of the letters "K", "M" or "G" (in either upper |
| 9808 | or lower case), signifying multiplication by 1024, 1024*1024 or |
| 9809 | 1024*1024*1024, respectively. As a special case, the numerical value of an |
| 9810 | empty string is taken as zero. |
| 9811 | |
| 9812 | In all cases, a relative comparator OP is testing if <string1> OP <string2 |
| 9813 | >; the above example is checking if $message_size is larger than 10M, not |
| 9814 | if 10M is larger than $message_size. |
| 9815 | |
| 9816 | acl {{<name>}{<arg1>}{<arg2>}...} |
| 9817 | |
| 9818 | The name and zero to nine argument strings are first expanded separately. |
| 9819 | The expanded arguments are assigned to the variables $acl_arg1 to $acl_arg9 |
| 9820 | in order. Any unused are made empty. The variable $acl_narg is set to the |
| 9821 | number of arguments. The named ACL (see chapter 43) is called and may use |
| 9822 | the variables; if another acl expansion is used the values are restored |
| 9823 | after it returns. If the ACL sets a value using a "message =" modifier the |
| 9824 | variable $value becomes the result of the expansion, otherwise it is empty. |
| 9825 | If the ACL returns accept the condition is true; if deny, false. If the ACL |
| 9826 | returns defer the result is a forced-fail. |
| 9827 | |
| 9828 | bool {<string>} |
| 9829 | |
| 9830 | This condition turns a string holding a true or false representation into a |
| 9831 | boolean state. It parses "true", "false", "yes" and "no" |
| 9832 | (case-insensitively); also integer numbers map to true if non-zero, false |
| 9833 | if zero. An empty string is treated as false. Leading and trailing |
| 9834 | whitespace is ignored; thus a string consisting only of whitespace is |
| 9835 | false. All other string values will result in expansion failure. |
| 9836 | |
| 9837 | When combined with ACL variables, this expansion condition will let you |
| 9838 | make decisions in one place and act on those decisions in another place. |
| 9839 | For example: |
| 9840 | |
| 9841 | ${if bool{$acl_m_privileged_sender} ... |
| 9842 | |
| 9843 | bool_lax {<string>} |
| 9844 | |
| 9845 | Like bool, this condition turns a string into a boolean state. But where |
| 9846 | bool accepts a strict set of strings, bool_lax uses the same loose |
| 9847 | definition that the Router condition option uses. The empty string and the |
| 9848 | values "false", "no" and "0" map to false, all others map to true. Leading |
| 9849 | and trailing whitespace is ignored. |
| 9850 | |
| 9851 | Note that where "bool{00}" is false, "bool_lax{00}" is true. |
| 9852 | |
| 9853 | crypteq {<string1>}{<string2>} |
| 9854 | |
| 9855 | This condition is included in the Exim binary if it is built to support any |
| 9856 | authentication mechanisms (see chapter 33). Otherwise, it is necessary to |
| 9857 | define SUPPORT_CRYPTEQ in Local/Makefile to get crypteq included in the |
| 9858 | binary. |
| 9859 | |
| 9860 | The crypteq condition has two arguments. The first is encrypted and |
| 9861 | compared against the second, which is already encrypted. The second string |
| 9862 | may be in the LDAP form for storing encrypted strings, which starts with |
| 9863 | the encryption type in curly brackets, followed by the data. If the second |
| 9864 | string does not begin with "{" it is assumed to be encrypted with crypt() |
| 9865 | or crypt16() (see below), since such strings cannot begin with "{". |
| 9866 | Typically this will be a field from a password file. An example of an |
| 9867 | encrypted string in LDAP form is: |
| 9868 | |
| 9869 | {md5}CY9rzUYh03PK3k6DJie09g== |
| 9870 | |
| 9871 | If such a string appears directly in an expansion, the curly brackets have |
| 9872 | to be quoted, because they are part of the expansion syntax. For example: |
| 9873 | |
| 9874 | ${if crypteq {test}{\{md5\}CY9rzUYh03PK3k6DJie09g==}{yes}{no}} |
| 9875 | |
| 9876 | The following encryption types (whose names are matched case-independently) |
| 9877 | are supported: |
| 9878 | |
| 9879 | + {md5} computes the MD5 digest of the first string, and expresses this |
| 9880 | as printable characters to compare with the remainder of the second |
| 9881 | string. If the length of the comparison string is 24, Exim assumes that |
| 9882 | it is base64 encoded (as in the above example). If the length is 32, |
| 9883 | Exim assumes that it is a hexadecimal encoding of the MD5 digest. If |
| 9884 | the length not 24 or 32, the comparison fails. |
| 9885 | |
| 9886 | + {sha1} computes the SHA-1 digest of the first string, and expresses |
| 9887 | this as printable characters to compare with the remainder of the |
| 9888 | second string. If the length of the comparison string is 28, Exim |
| 9889 | assumes that it is base64 encoded. If the length is 40, Exim assumes |
| 9890 | that it is a hexadecimal encoding of the SHA-1 digest. If the length is |
| 9891 | not 28 or 40, the comparison fails. |
| 9892 | |
| 9893 | + {crypt} calls the crypt() function, which traditionally used to use |
| 9894 | only the first eight characters of the password. However, in modern |
| 9895 | operating systems this is no longer true, and in many cases the entire |
| 9896 | password is used, whatever its length. |
| 9897 | |
| 9898 | + {crypt16} calls the crypt16() function, which was originally created to |
| 9899 | use up to 16 characters of the password in some operating systems. |
| 9900 | Again, in modern operating systems, more characters may be used. |
| 9901 | |
| 9902 | Exim has its own version of crypt16(), which is just a double call to crypt |
| 9903 | (). For operating systems that have their own version, setting HAVE_CRYPT16 |
| 9904 | in Local/Makefile when building Exim causes it to use the operating system |
| 9905 | version instead of its own. This option is set by default in the |
| 9906 | OS-dependent Makefile for those operating systems that are known to support |
| 9907 | crypt16(). |
| 9908 | |
| 9909 | Some years after Exim's crypt16() was implemented, a user discovered that |
| 9910 | it was not using the same algorithm as some operating systems' versions. It |
| 9911 | turns out that as well as crypt16() there is a function called bigcrypt() |
| 9912 | in some operating systems. This may or may not use the same algorithm, and |
| 9913 | both of them may be different to Exim's built-in crypt16(). |
| 9914 | |
| 9915 | However, since there is now a move away from the traditional crypt() |
| 9916 | functions towards using SHA1 and other algorithms, tidying up this area of |
| 9917 | Exim is seen as very low priority. |
| 9918 | |
| 9919 | If you do not put a encryption type (in curly brackets) in a crypteq |
| 9920 | comparison, the default is usually either "{crypt}" or "{crypt16}", as |
| 9921 | determined by the setting of DEFAULT_CRYPT in Local/Makefile. The default |
| 9922 | default is "{crypt}". Whatever the default, you can always use either |
| 9923 | function by specifying it explicitly in curly brackets. |
| 9924 | |
| 9925 | def:<variable name> |
| 9926 | |
| 9927 | The def condition must be followed by the name of one of the expansion |
| 9928 | variables defined in section 11.9. The condition is true if the variable |
| 9929 | does not contain the empty string. For example: |
| 9930 | |
| 9931 | ${if def:sender_ident {from $sender_ident}} |
| 9932 | |
| 9933 | Note that the variable name is given without a leading $ character. If the |
| 9934 | variable does not exist, the expansion fails. |
| 9935 | |
| 9936 | def:header_<header name>: or def:h_<header name>: |
| 9937 | |
| 9938 | This condition is true if a message is being processed and the named header |
| 9939 | exists in the message. For example, |
| 9940 | |
| 9941 | ${if def:header_reply-to:{$h_reply-to:}{$h_from:}} |
| 9942 | |
| 9943 | Note: No $ appears before header_ or h_ in the condition, and the header |
| 9944 | name must be terminated by a colon if white space does not follow. |
| 9945 | |
| 9946 | eq {<string1>}{<string2>}, eqi {<string1>}{<string2>} |
| 9947 | |
| 9948 | The two substrings are first expanded. The condition is true if the two |
| 9949 | resulting strings are identical. For eq the comparison includes the case of |
| 9950 | letters, whereas for eqi the comparison is case-independent. |
| 9951 | |
| 9952 | exists {<file name>} |
| 9953 | |
| 9954 | The substring is first expanded and then interpreted as an absolute path. |
| 9955 | The condition is true if the named file (or directory) exists. The |
| 9956 | existence test is done by calling the stat() function. The use of the |
| 9957 | exists test in users' filter files may be locked out by the system |
| 9958 | administrator. |
| 9959 | |
| 9960 | first_delivery |
| 9961 | |
| 9962 | This condition, which has no data, is true during a message's first |
| 9963 | delivery attempt. It is false during any subsequent delivery attempts. |
| 9964 | |
| 9965 | forall{<a list>}{<a condition>}, forany{<a list>}{<a condition>} |
| 9966 | |
| 9967 | These conditions iterate over a list. The first argument is expanded to |
| 9968 | form the list. By default, the list separator is a colon, but it can be |
| 9969 | changed by the normal method. The second argument is interpreted as a |
| 9970 | condition that is to be applied to each item in the list in turn. During |
| 9971 | the interpretation of the condition, the current list item is placed in a |
| 9972 | variable called $item. |
| 9973 | |
| 9974 | + For forany, interpretation stops if the condition is true for any item, |
| 9975 | and the result of the whole condition is true. If the condition is |
| 9976 | false for all items in the list, the overall condition is false. |
| 9977 | |
| 9978 | + For forall, interpretation stops if the condition is false for any |
| 9979 | item, and the result of the whole condition is false. If the condition |
| 9980 | is true for all items in the list, the overall condition is true. |
| 9981 | |
| 9982 | Note that negation of forany means that the condition must be false for all |
| 9983 | items for the overall condition to succeed, and negation of forall means |
| 9984 | that the condition must be false for at least one item. In this example, |
| 9985 | the list separator is changed to a comma: |
| 9986 | |
| 9987 | ${if forany{<, $recipients}{match{$item}{^user3@}}{yes}{no}} |
| 9988 | |
| 9989 | The value of $item is saved and restored while forany or forall is being |
| 9990 | processed, to enable these expansion items to be nested. |
| 9991 | |
| 9992 | To scan a named list, expand it with the listnamed operator. |
| 9993 | |
| 9994 | ge {<string1>}{<string2>}, gei {<string1>}{<string2>} |
| 9995 | |
| 9996 | The two substrings are first expanded. The condition is true if the first |
| 9997 | string is lexically greater than or equal to the second string. For ge the |
| 9998 | comparison includes the case of letters, whereas for gei the comparison is |
| 9999 | case-independent. |
| 10000 | |
| 10001 | gt {<string1>}{<string2>}, gti {<string1>}{<string2>} |
| 10002 | |
| 10003 | The two substrings are first expanded. The condition is true if the first |
| 10004 | string is lexically greater than the second string. For gt the comparison |
| 10005 | includes the case of letters, whereas for gti the comparison is |
| 10006 | case-independent. |
| 10007 | |
| 10008 | inlist {<string1>}{<string2>}, inlisti {<string1>}{<string2>} |
| 10009 | |
| 10010 | Both strings are expanded; the second string is treated as a list of simple |
| 10011 | strings; if the first string is a member of the second, then the condition |
| 10012 | is true. |
| 10013 | |
| 10014 | These are simpler to use versions of the more powerful forany condition. |
| 10015 | Examples, and the forany equivalents: |
| 10016 | |
| 10017 | ${if inlist{needle}{foo:needle:bar}} |
| 10018 | ${if forany{foo:needle:bar}{eq{$item}{needle}}} |
| 10019 | ${if inlisti{Needle}{fOo:NeeDLE:bAr}} |
| 10020 | ${if forany{fOo:NeeDLE:bAr}{eqi{$item}{Needle}}} |
| 10021 | |
| 10022 | isip {<string>}, isip4 {<string>}, isip6 {<string>} |
| 10023 | |
| 10024 | The substring is first expanded, and then tested to see if it has the form |
| 10025 | of an IP address. Both IPv4 and IPv6 addresses are valid for isip, whereas |
| 10026 | isip4 and isip6 test specifically for IPv4 or IPv6 addresses. |
| 10027 | |
| 10028 | For an IPv4 address, the test is for four dot-separated components, each of |
| 10029 | which consists of from one to three digits. For an IPv6 address, up to |
| 10030 | eight colon-separated components are permitted, each containing from one to |
| 10031 | four hexadecimal digits. There may be fewer than eight components if an |
| 10032 | empty component (adjacent colons) is present. Only one empty component is |
| 10033 | permitted. |
| 10034 | |
| 10035 | Note: The checks are just on the form of the address; actual numerical |
| 10036 | values are not considered. Thus, for example, 999.999.999.999 passes the |
| 10037 | IPv4 check. The main use of these tests is to distinguish between IP |
| 10038 | addresses and host names, or between IPv4 and IPv6 addresses. For example, |
| 10039 | you could use |
| 10040 | |
| 10041 | ${if isip4{$sender_host_address}... |
| 10042 | |
| 10043 | to test which IP version an incoming SMTP connection is using. |
| 10044 | |
| 10045 | ldapauth {<ldap query>} |
| 10046 | |
| 10047 | This condition supports user authentication using LDAP. See section 9.14 |
| 10048 | for details of how to use LDAP in lookups and the syntax of queries. For |
| 10049 | this use, the query must contain a user name and password. The query itself |
| 10050 | is not used, and can be empty. The condition is true if the password is not |
| 10051 | empty, and the user name and password are accepted by the LDAP server. An |
| 10052 | empty password is rejected without calling LDAP because LDAP binds with an |
| 10053 | empty password are considered anonymous regardless of the username, and |
| 10054 | will succeed in most configurations. See chapter 33 for details of SMTP |
| 10055 | authentication, and chapter 34 for an example of how this can be used. |
| 10056 | |
| 10057 | le {<string1>}{<string2>}, lei {<string1>}{<string2>} |
| 10058 | |
| 10059 | The two substrings are first expanded. The condition is true if the first |
| 10060 | string is lexically less than or equal to the second string. For le the |
| 10061 | comparison includes the case of letters, whereas for lei the comparison is |
| 10062 | case-independent. |
| 10063 | |
| 10064 | lt {<string1>}{<string2>}, lti {<string1>}{<string2>} |
| 10065 | |
| 10066 | The two substrings are first expanded. The condition is true if the first |
| 10067 | string is lexically less than the second string. For lt the comparison |
| 10068 | includes the case of letters, whereas for lti the comparison is |
| 10069 | case-independent. |
| 10070 | |
| 10071 | match {<string1>}{<string2>} |
| 10072 | |
| 10073 | The two substrings are first expanded. The second is then treated as a |
| 10074 | regular expression and applied to the first. Because of the pre-expansion, |
| 10075 | if the regular expression contains dollar, or backslash characters, they |
| 10076 | must be escaped. Care must also be taken if the regular expression contains |
| 10077 | braces (curly brackets). A closing brace must be escaped so that it is not |
| 10078 | taken as a premature termination of <string2>. The easiest approach is to |
| 10079 | use the "\N" feature to disable expansion of the regular expression. For |
| 10080 | example, |
| 10081 | |
| 10082 | ${if match {$local_part}{\N^\d{3}\N} ... |
| 10083 | |
| 10084 | If the whole expansion string is in double quotes, further escaping of |
| 10085 | backslashes is also required. |
| 10086 | |
| 10087 | The condition is true if the regular expression match succeeds. The regular |
| 10088 | expression is not required to begin with a circumflex metacharacter, but if |
| 10089 | there is no circumflex, the expression is not anchored, and it may match |
| 10090 | anywhere in the subject, not just at the start. If you want the pattern to |
| 10091 | match at the end of the subject, you must include the "$" metacharacter at |
| 10092 | an appropriate point. |
| 10093 | |
| 10094 | At the start of an if expansion the values of the numeric variable |
| 10095 | substitutions $1 etc. are remembered. Obeying a match condition that |
| 10096 | succeeds causes them to be reset to the substrings of that condition and |
| 10097 | they will have these values during the expansion of the success string. At |
| 10098 | the end of the if expansion, the previous values are restored. After |
| 10099 | testing a combination of conditions using or, the subsequent values of the |
| 10100 | numeric variables are those of the condition that succeeded. |
| 10101 | |
| 10102 | match_address {<string1>}{<string2>} |
| 10103 | |
| 10104 | See match_local_part. |
| 10105 | |
| 10106 | match_domain {<string1>}{<string2>} |
| 10107 | |
| 10108 | See match_local_part. |
| 10109 | |
| 10110 | match_ip {<string1>}{<string2>} |
| 10111 | |
| 10112 | This condition matches an IP address to a list of IP address patterns. It |
| 10113 | must be followed by two argument strings. The first (after expansion) must |
| 10114 | be an IP address or an empty string. The second (not expanded) is a |
| 10115 | restricted host list that can match only an IP address, not a host name. |
| 10116 | For example: |
| 10117 | |
| 10118 | ${if match_ip{$sender_host_address}{1.2.3.4:5.6.7.8}{...}{...}} |
| 10119 | |
| 10120 | The specific types of host list item that are permitted in the list are: |
| 10121 | |
| 10122 | + An IP address, optionally with a CIDR mask. |
| 10123 | |
| 10124 | + A single asterisk, which matches any IP address. |
| 10125 | |
| 10126 | + An empty item, which matches only if the IP address is empty. This |
| 10127 | could be useful for testing for a locally submitted message or one from |
| 10128 | specific hosts in a single test such as |
| 10129 | |
| 10130 | ${if match_ip{$sender_host_address}{:4.3.2.1:...}{...}{...}} |
| 10131 | |
| 10132 | where the first item in the list is the empty string. |
| 10133 | |
| 10134 | + The item @[] matches any of the local host's interface addresses. |
| 10135 | |
| 10136 | + Single-key lookups are assumed to be like "net-" style lookups in host |
| 10137 | lists, even if "net-" is not specified. There is never any attempt to |
| 10138 | turn the IP address into a host name. The most common type of linear |
| 10139 | search for match_ip is likely to be iplsearch, in which the file can |
| 10140 | contain CIDR masks. For example: |
| 10141 | |
| 10142 | ${if match_ip{$sender_host_address}{iplsearch;/some/file}... |
| 10143 | |
| 10144 | It is of course possible to use other kinds of lookup, and in such a |
| 10145 | case, you do need to specify the "net-" prefix if you want to specify a |
| 10146 | specific address mask, for example: |
| 10147 | |
| 10148 | ${if match_ip{$sender_host_address}{net24-dbm;/some/file}... |
| 10149 | |
| 10150 | However, unless you are combining a match_ip condition with others, it |
| 10151 | is just as easy to use the fact that a lookup is itself a condition, |
| 10152 | and write: |
| 10153 | |
| 10154 | ${lookup{${mask:$sender_host_address/24}}dbm{/a/file}... |
| 10155 | |
| 10156 | Note that <string2> is not itself subject to string expansion, unless Exim |
| 10157 | was built with the EXPAND_LISTMATCH_RHS option. |
| 10158 | |
| 10159 | Consult section 10.11 for further details of these patterns. |
| 10160 | |
| 10161 | match_local_part {<string1>}{<string2>} |
| 10162 | |
| 10163 | This condition, together with match_address and match_domain, make it |
| 10164 | possible to test domain, address, and local part lists within expansions. |
| 10165 | Each condition requires two arguments: an item and a list to match. A |
| 10166 | trivial example is: |
| 10167 | |
| 10168 | ${if match_domain{a.b.c}{x.y.z:a.b.c:p.q.r}{yes}{no}} |
| 10169 | |
| 10170 | In each case, the second argument may contain any of the allowable items |
| 10171 | for a list of the appropriate type. Also, because the second argument |
| 10172 | (after expansion) is a standard form of list, it is possible to refer to a |
| 10173 | named list. Thus, you can use conditions like this: |
| 10174 | |
| 10175 | ${if match_domain{$domain}{+local_domains}{... |
| 10176 | |
| 10177 | For address lists, the matching starts off caselessly, but the "+caseful" |
| 10178 | item can be used, as in all address lists, to cause subsequent items to |
| 10179 | have their local parts matched casefully. Domains are always matched |
| 10180 | caselessly. |
| 10181 | |
| 10182 | Note that <string2> is not itself subject to string expansion, unless Exim |
| 10183 | was built with the EXPAND_LISTMATCH_RHS option. |
| 10184 | |
| 10185 | Note: Host lists are not supported in this way. This is because hosts have |
| 10186 | two identities: a name and an IP address, and it is not clear how to |
| 10187 | specify cleanly how such a test would work. However, IP addresses can be |
| 10188 | matched using match_ip. |
| 10189 | |
| 10190 | pam {<string1>:<string2>:...} |
| 10191 | |
| 10192 | Pluggable Authentication Modules (http://www.kernel.org/pub/linux/libs/pam/ |
| 10193 | ) are a facility that is available in the latest releases of Solaris and in |
| 10194 | some GNU/Linux distributions. The Exim support, which is intended for use |
| 10195 | in conjunction with the SMTP AUTH command, is available only if Exim is |
| 10196 | compiled with |
| 10197 | |
| 10198 | SUPPORT_PAM=yes |
| 10199 | |
| 10200 | in Local/Makefile. You probably need to add -lpam to EXTRALIBS, and in some |
| 10201 | releases of GNU/Linux -ldl is also needed. |
| 10202 | |
| 10203 | The argument string is first expanded, and the result must be a |
| 10204 | colon-separated list of strings. Leading and trailing white space is |
| 10205 | ignored. The PAM module is initialized with the service name "exim" and the |
| 10206 | user name taken from the first item in the colon-separated data string (< |
| 10207 | string1>). The remaining items in the data string are passed over in |
| 10208 | response to requests from the authentication function. In the simple case |
| 10209 | there will only be one request, for a password, so the data consists of |
| 10210 | just two strings. |
| 10211 | |
| 10212 | There can be problems if any of the strings are permitted to contain colon |
| 10213 | characters. In the usual way, these have to be doubled to avoid being taken |
| 10214 | as separators. If the data is being inserted from a variable, the sg |
| 10215 | expansion item can be used to double any existing colons. For example, the |
| 10216 | configuration of a LOGIN authenticator might contain this setting: |
| 10217 | |
| 10218 | server_condition = ${if pam{$auth1:${sg{$auth2}{:}{::}}}} |
| 10219 | |
| 10220 | For a PLAIN authenticator you could use: |
| 10221 | |
| 10222 | server_condition = ${if pam{$auth2:${sg{$auth3}{:}{::}}}} |
| 10223 | |
| 10224 | In some operating systems, PAM authentication can be done only from a |
| 10225 | process running as root. Since Exim is running as the Exim user when |
| 10226 | receiving messages, this means that PAM cannot be used directly in those |
| 10227 | systems. A patched version of the pam_unix module that comes with the Linux |
| 10228 | PAM package is available from http://www.e-admin.de/pam_exim/. The patched |
| 10229 | module allows one special uid/gid combination, in addition to root, to |
| 10230 | authenticate. If you build the patched module to allow the Exim user and |
| 10231 | group, PAM can then be used from an Exim authenticator. |
| 10232 | |
| 10233 | pwcheck {<string1>:<string2>} |
| 10234 | |
| 10235 | This condition supports user authentication using the Cyrus pwcheck daemon. |
| 10236 | This is one way of making it possible for passwords to be checked by a |
| 10237 | process that is not running as root. Note: The use of pwcheck is now |
| 10238 | deprecated. Its replacement is saslauthd (see below). |
| 10239 | |
| 10240 | The pwcheck support is not included in Exim by default. You need to specify |
| 10241 | the location of the pwcheck daemon's socket in Local/Makefile before |
| 10242 | building Exim. For example: |
| 10243 | |
| 10244 | CYRUS_PWCHECK_SOCKET=/var/pwcheck/pwcheck |
| 10245 | |
| 10246 | You do not need to install the full Cyrus software suite in order to use |
| 10247 | the pwcheck daemon. You can compile and install just the daemon alone from |
| 10248 | the Cyrus SASL library. Ensure that exim is the only user that has access |
| 10249 | to the /var/pwcheck directory. |
| 10250 | |
| 10251 | The pwcheck condition takes one argument, which must be the user name and |
| 10252 | password, separated by a colon. For example, in a LOGIN authenticator |
| 10253 | configuration, you might have this: |
| 10254 | |
| 10255 | server_condition = ${if pwcheck{$auth1:$auth2}} |
| 10256 | |
| 10257 | Again, for a PLAIN authenticator configuration, this would be: |
| 10258 | |
| 10259 | server_condition = ${if pwcheck{$auth2:$auth3}} |
| 10260 | |
| 10261 | queue_running |
| 10262 | |
| 10263 | This condition, which has no data, is true during delivery attempts that |
| 10264 | are initiated by queue runner processes, and false otherwise. |
| 10265 | |
| 10266 | radius {<authentication string>} |
| 10267 | |
| 10268 | Radius authentication (RFC 2865) is supported in a similar way to PAM. You |
| 10269 | must set RADIUS_CONFIG_FILE in Local/Makefile to specify the location of |
| 10270 | the Radius client configuration file in order to build Exim with Radius |
| 10271 | support. |
| 10272 | |
| 10273 | With just that one setting, Exim expects to be linked with the radiusclient |
| 10274 | library, using the original API. If you are using release 0.4.0 or later of |
| 10275 | this library, you need to set |
| 10276 | |
| 10277 | RADIUS_LIB_TYPE=RADIUSCLIENTNEW |
| 10278 | |
| 10279 | in Local/Makefile when building Exim. You can also link Exim with the |
| 10280 | libradius library that comes with FreeBSD. To do this, set |
| 10281 | |
| 10282 | RADIUS_LIB_TYPE=RADLIB |
| 10283 | |
| 10284 | in Local/Makefile, in addition to setting RADIUS_CONFIGURE_FILE. You may |
| 10285 | also have to supply a suitable setting in EXTRALIBS so that the Radius |
| 10286 | library can be found when Exim is linked. |
| 10287 | |
| 10288 | The string specified by RADIUS_CONFIG_FILE is expanded and passed to the |
| 10289 | Radius client library, which calls the Radius server. The condition is true |
| 10290 | if the authentication is successful. For example: |
| 10291 | |
| 10292 | server_condition = ${if radius{<arguments>}} |
| 10293 | |
| 10294 | saslauthd {{<user>}{<password>}{<service>}{<realm>}} |
| 10295 | |
| 10296 | This condition supports user authentication using the Cyrus saslauthd |
| 10297 | daemon. This replaces the older pwcheck daemon, which is now deprecated. |
| 10298 | Using this daemon is one way of making it possible for passwords to be |
| 10299 | checked by a process that is not running as root. |
| 10300 | |
| 10301 | The saslauthd support is not included in Exim by default. You need to |
| 10302 | specify the location of the saslauthd daemon's socket in Local/Makefile |
| 10303 | before building Exim. For example: |
| 10304 | |
| 10305 | CYRUS_SASLAUTHD_SOCKET=/var/state/saslauthd/mux |
| 10306 | |
| 10307 | You do not need to install the full Cyrus software suite in order to use |
| 10308 | the saslauthd daemon. You can compile and install just the daemon alone |
| 10309 | from the Cyrus SASL library. |
| 10310 | |
| 10311 | Up to four arguments can be supplied to the saslauthd condition, but only |
| 10312 | two are mandatory. For example: |
| 10313 | |
| 10314 | server_condition = ${if saslauthd{{$auth1}{$auth2}}} |
| 10315 | |
| 10316 | The service and the realm are optional (which is why the arguments are |
| 10317 | enclosed in their own set of braces). For details of the meaning of the |
| 10318 | service and realm, and how to run the daemon, consult the Cyrus |
| 10319 | documentation. |
| 10320 | |
| 10321 | |
| 10322 | 11.8 Combining expansion conditions |
| 10323 | ----------------------------------- |
| 10324 | |
| 10325 | Several conditions can be tested at once by combining them using the and and or |
| 10326 | combination conditions. Note that and and or are complete conditions on their |
| 10327 | own, and precede their lists of sub-conditions. Each sub-condition must be |
| 10328 | enclosed in braces within the overall braces that contain the list. No |
| 10329 | repetition of if is used. |
| 10330 | |
| 10331 | or {{<cond1>}{<cond2>}...} |
| 10332 | |
| 10333 | The sub-conditions are evaluated from left to right. The condition is true |
| 10334 | if any one of the sub-conditions is true. For example, |
| 10335 | |
| 10336 | ${if or {{eq{$local_part}{spqr}}{eq{$domain}{testing.com}}}... |
| 10337 | |
| 10338 | When a true sub-condition is found, the following ones are parsed but not |
| 10339 | evaluated. If there are several "match" sub-conditions the values of the |
| 10340 | numeric variables afterwards are taken from the first one that succeeds. |
| 10341 | |
| 10342 | and {{<cond1>}{<cond2>}...} |
| 10343 | |
| 10344 | The sub-conditions are evaluated from left to right. The condition is true |
| 10345 | if all of the sub-conditions are true. If there are several "match" |
| 10346 | sub-conditions, the values of the numeric variables afterwards are taken |
| 10347 | from the last one. When a false sub-condition is found, the following ones |
| 10348 | are parsed but not evaluated. |
| 10349 | |
| 10350 | |
| 10351 | 11.9 Expansion variables |
| 10352 | ------------------------ |
| 10353 | |
| 10354 | This section contains an alphabetical list of all the expansion variables. Some |
| 10355 | of them are available only when Exim is compiled with specific options such as |
| 10356 | support for TLS or the content scanning extension. |
| 10357 | |
| 10358 | $0, $1, etc |
| 10359 | |
| 10360 | When a match expansion condition succeeds, these variables contain the |
| 10361 | captured substrings identified by the regular expression during subsequent |
| 10362 | processing of the success string of the containing if expansion item. In |
| 10363 | the expansion condition case they do not retain their values afterwards; in |
| 10364 | fact, their previous values are restored at the end of processing an if |
| 10365 | item. The numerical variables may also be set externally by some other |
| 10366 | matching process which precedes the expansion of the string. For example, |
| 10367 | the commands available in Exim filter files include an if command with its |
| 10368 | own regular expression matching condition. |
| 10369 | |
| 10370 | $acl_arg1, $acl_arg2, etc |
| 10371 | |
| 10372 | Within an acl condition, expansion condition or expansion item any |
| 10373 | arguments are copied to these variables, any unused variables being made |
| 10374 | empty. |
| 10375 | |
| 10376 | $acl_c... |
| 10377 | |
| 10378 | Values can be placed in these variables by the set modifier in an ACL. They |
| 10379 | can be given any name that starts with $acl_c and is at least six |
| 10380 | characters long, but the sixth character must be either a digit or an |
| 10381 | underscore. For example: $acl_c5, $acl_c_mycount. The values of the |
| 10382 | $acl_c... variables persist throughout the lifetime of an SMTP connection. |
| 10383 | They can be used to pass information between ACLs and between different |
| 10384 | invocations of the same ACL. When a message is received, the values of |
| 10385 | these variables are saved with the message, and can be accessed by filters, |
| 10386 | routers, and transports during subsequent delivery. |
| 10387 | |
| 10388 | $acl_m... |
| 10389 | |
| 10390 | These variables are like the $acl_c... variables, except that their values |
| 10391 | are reset after a message has been received. Thus, if several messages are |
| 10392 | received in one SMTP connection, $acl_m... values are not passed on from |
| 10393 | one message to the next, as $acl_c... values are. The $acl_m... variables |
| 10394 | are also reset by MAIL, RSET, EHLO, HELO, and after starting a TLS session. |
| 10395 | When a message is received, the values of these variables are saved with |
| 10396 | the message, and can be accessed by filters, routers, and transports during |
| 10397 | subsequent delivery. |
| 10398 | |
| 10399 | $acl_narg |
| 10400 | |
| 10401 | Within an acl condition, expansion condition or expansion item this |
| 10402 | variable has the number of arguments. |
| 10403 | |
| 10404 | $acl_verify_message |
| 10405 | |
| 10406 | After an address verification has failed, this variable contains the |
| 10407 | failure message. It retains its value for use in subsequent modifiers. The |
| 10408 | message can be preserved by coding like this: |
| 10409 | |
| 10410 | warn !verify = sender |
| 10411 | set acl_m0 = $acl_verify_message |
| 10412 | |
| 10413 | You can use $acl_verify_message during the expansion of the message or |
| 10414 | log_message modifiers, to include information about the verification |
| 10415 | failure. |
| 10416 | |
| 10417 | $address_data |
| 10418 | |
| 10419 | This variable is set by means of the address_data option in routers. The |
| 10420 | value then remains with the address while it is processed by subsequent |
| 10421 | routers and eventually a transport. If the transport is handling multiple |
| 10422 | addresses, the value from the first address is used. See chapter 15 for |
| 10423 | more details. Note: The contents of $address_data are visible in user |
| 10424 | filter files. |
| 10425 | |
| 10426 | If $address_data is set when the routers are called from an ACL to verify a |
| 10427 | recipient address, the final value is still in the variable for subsequent |
| 10428 | conditions and modifiers of the ACL statement. If routing the address |
| 10429 | caused it to be redirected to just one address, the child address is also |
| 10430 | routed as part of the verification, and in this case the final value of |
| 10431 | $address_data is from the child's routing. |
| 10432 | |
| 10433 | If $address_data is set when the routers are called from an ACL to verify a |
| 10434 | sender address, the final value is also preserved, but this time in |
| 10435 | $sender_address_data, to distinguish it from data from a recipient address. |
| 10436 | |
| 10437 | In both cases (recipient and sender verification), the value does not |
| 10438 | persist after the end of the current ACL statement. If you want to preserve |
| 10439 | these values for longer, you can save them in ACL variables. |
| 10440 | |
| 10441 | $address_file |
| 10442 | |
| 10443 | When, as a result of aliasing, forwarding, or filtering, a message is |
| 10444 | directed to a specific file, this variable holds the name of the file when |
| 10445 | the transport is running. At other times, the variable is empty. For |
| 10446 | example, using the default configuration, if user r2d2 has a .forward file |
| 10447 | containing |
| 10448 | |
| 10449 | /home/r2d2/savemail |
| 10450 | |
| 10451 | then when the address_file transport is running, $address_file contains the |
| 10452 | text string "/home/r2d2/savemail". For Sieve filters, the value may be |
| 10453 | "inbox" or a relative folder name. It is then up to the transport |
| 10454 | configuration to generate an appropriate absolute path to the relevant |
| 10455 | file. |
| 10456 | |
| 10457 | $address_pipe |
| 10458 | |
| 10459 | When, as a result of aliasing or forwarding, a message is directed to a |
| 10460 | pipe, this variable holds the pipe command when the transport is running. |
| 10461 | |
| 10462 | $auth1 - $auth3 |
| 10463 | |
| 10464 | These variables are used in SMTP authenticators (see chapters 34-41). |
| 10465 | Elsewhere, they are empty. |
| 10466 | |
| 10467 | $authenticated_id |
| 10468 | |
| 10469 | When a server successfully authenticates a client it may be configured to |
| 10470 | preserve some of the authentication information in the variable |
| 10471 | $authenticated_id (see chapter 33). For example, a user/password |
| 10472 | authenticator configuration might preserve the user name for use in the |
| 10473 | routers. Note that this is not the same information that is saved in |
| 10474 | $sender_host_authenticated. When a message is submitted locally (that is, |
| 10475 | not over a TCP connection) the value of $authenticated_id is normally the |
| 10476 | login name of the calling process. However, a trusted user can override |
| 10477 | this by means of the -oMai command line option. |
| 10478 | |
| 10479 | $authenticated_fail_id |
| 10480 | |
| 10481 | When an authentication attempt fails, the variable $authenticated_fail_id |
| 10482 | will contain the failed authentication id. If more than one authentication |
| 10483 | id is attempted, it will contain only the last one. The variable is |
| 10484 | available for processing in the ACL's, generally the quit or notquit ACL. A |
| 10485 | message to a local recipient could still be accepted without requiring |
| 10486 | authentication, which means this variable could also be visible in all of |
| 10487 | the ACL's as well. |
| 10488 | |
| 10489 | $authenticated_sender |
| 10490 | |
| 10491 | When acting as a server, Exim takes note of the AUTH= parameter on an |
| 10492 | incoming SMTP MAIL command if it believes the sender is sufficiently |
| 10493 | trusted, as described in section 33.2. Unless the data is the string "<>", |
| 10494 | it is set as the authenticated sender of the message, and the value is |
| 10495 | available during delivery in the $authenticated_sender variable. If the |
| 10496 | sender is not trusted, Exim accepts the syntax of AUTH=, but ignores the |
| 10497 | data. |
| 10498 | |
| 10499 | When a message is submitted locally (that is, not over a TCP connection), |
| 10500 | the value of $authenticated_sender is an address constructed from the login |
| 10501 | name of the calling process and $qualify_domain, except that a trusted user |
| 10502 | can override this by means of the -oMas command line option. |
| 10503 | |
| 10504 | $authentication_failed |
| 10505 | |
| 10506 | This variable is set to "1" in an Exim server if a client issues an AUTH |
| 10507 | command that does not succeed. Otherwise it is set to "0". This makes it |
| 10508 | possible to distinguish between "did not try to authenticate" ( |
| 10509 | $sender_host_authenticated is empty and $authentication_failed is set to |
| 10510 | "0") and "tried to authenticate but failed" ($sender_host_authenticated is |
| 10511 | empty and $authentication_failed is set to "1"). Failure includes any |
| 10512 | negative response to an AUTH command, including (for example) an attempt to |
| 10513 | use an undefined mechanism. |
| 10514 | |
| 10515 | $av_failed |
| 10516 | |
| 10517 | This variable is available when Exim is compiled with the content-scanning |
| 10518 | extension. It is set to "0" by default, but will be set to "1" if any |
| 10519 | problem occurs with the virus scanner (specified by av_scanner) during the |
| 10520 | ACL malware condition. |
| 10521 | |
| 10522 | $body_linecount |
| 10523 | |
| 10524 | When a message is being received or delivered, this variable contains the |
| 10525 | number of lines in the message's body. See also $message_linecount. |
| 10526 | |
| 10527 | $body_zerocount |
| 10528 | |
| 10529 | When a message is being received or delivered, this variable contains the |
| 10530 | number of binary zero bytes (ASCII NULs) in the message's body. |
| 10531 | |
| 10532 | $bounce_recipient |
| 10533 | |
| 10534 | This is set to the recipient address of a bounce message while Exim is |
| 10535 | creating it. It is useful if a customized bounce message text file is in |
| 10536 | use (see chapter 49). |
| 10537 | |
| 10538 | $bounce_return_size_limit |
| 10539 | |
| 10540 | This contains the value set in the bounce_return_size_limit option, rounded |
| 10541 | up to a multiple of 1000. It is useful when a customized error message text |
| 10542 | file is in use (see chapter 49). |
| 10543 | |
| 10544 | $caller_gid |
| 10545 | |
| 10546 | The real group id under which the process that called Exim was running. |
| 10547 | This is not the same as the group id of the originator of a message (see |
| 10548 | $originator_gid). If Exim re-execs itself, this variable in the new |
| 10549 | incarnation normally contains the Exim gid. |
| 10550 | |
| 10551 | $caller_uid |
| 10552 | |
| 10553 | The real user id under which the process that called Exim was running. This |
| 10554 | is not the same as the user id of the originator of a message (see |
| 10555 | $originator_uid). If Exim re-execs itself, this variable in the new |
| 10556 | incarnation normally contains the Exim uid. |
| 10557 | |
| 10558 | $callout_address |
| 10559 | |
| 10560 | After a callout for verification, spamd or malware daemon service, the |
| 10561 | address that was connected to. |
| 10562 | |
| 10563 | $compile_number |
| 10564 | |
| 10565 | The building process for Exim keeps a count of the number of times it has |
| 10566 | been compiled. This serves to distinguish different compilations of the |
| 10567 | same version of the program. |
| 10568 | |
| 10569 | $config_dir |
| 10570 | |
| 10571 | The directory name of the main configuration file. That is, the content of |
| 10572 | $config_file with the last component stripped. The value does not contain |
| 10573 | the trailing slash. If $config_file does not contain a slash, $config_dir |
| 10574 | is ".". |
| 10575 | |
| 10576 | $config_file |
| 10577 | |
| 10578 | The name of the main configuration file Exim is using. |
| 10579 | |
| 10580 | $dkim_cur_signer, $dkim_verify_status, $dkim_verify_reason, $dkim_domain, |
| 10581 | $dkim_identity, $dkim_selector, $dkim_algo, $dkim_canon_body, |
| 10582 | $dkim_canon_headers, $dkim_copiedheaders, $dkim_bodylength, $dkim_created, |
| 10583 | $dkim_expires, $dkim_headernames, $dkim_key_testing, $dkim_key_nosubdomains |
| 10584 | , $dkim_key_srvtype, $dkim_key_granularity, $dkim_key_notes, |
| 10585 | $dkim_key_length |
| 10586 | |
| 10587 | These variables are only available within the DKIM ACL. For details see |
| 10588 | chapter 57. |
| 10589 | |
| 10590 | $dkim_signers |
| 10591 | |
| 10592 | When a message has been received this variable contains a colon-separated |
| 10593 | list of signer domains and identities for the message. For details see |
| 10594 | chapter 57. |
| 10595 | |
| 10596 | $dnslist_domain, $dnslist_matched, $dnslist_text, $dnslist_value |
| 10597 | |
| 10598 | When a DNS (black) list lookup succeeds, these variables are set to contain |
| 10599 | the following data from the lookup: the list's domain name, the key that |
| 10600 | was looked up, the contents of any associated TXT record, and the value |
| 10601 | from the main A record. See section 43.32 for more details. |
| 10602 | |
| 10603 | $domain |
| 10604 | |
| 10605 | When an address is being routed, or delivered on its own, this variable |
| 10606 | contains the domain. Uppercase letters in the domain are converted into |
| 10607 | lower case for $domain. |
| 10608 | |
| 10609 | Global address rewriting happens when a message is received, so the value |
| 10610 | of $domain during routing and delivery is the value after rewriting. |
| 10611 | $domain is set during user filtering, but not during system filtering, |
| 10612 | because a message may have many recipients and the system filter is called |
| 10613 | just once. |
| 10614 | |
| 10615 | When more than one address is being delivered at once (for example, several |
| 10616 | RCPT commands in one SMTP delivery), $domain is set only if they all have |
| 10617 | the same domain. Transports can be restricted to handling only one domain |
| 10618 | at a time if the value of $domain is required at transport time - this is |
| 10619 | the default for local transports. For further details of the environment in |
| 10620 | which local transports are run, see chapter 23. |
| 10621 | |
| 10622 | At the end of a delivery, if all deferred addresses have the same domain, |
| 10623 | it is set in $domain during the expansion of delay_warning_condition. |
| 10624 | |
| 10625 | The $domain variable is also used in some other circumstances: |
| 10626 | |
| 10627 | + When an ACL is running for a RCPT command, $domain contains the domain |
| 10628 | of the recipient address. The domain of the sender address is in |
| 10629 | $sender_address_domain at both MAIL time and at RCPT time. $domain is |
| 10630 | not normally set during the running of the MAIL ACL. However, if the |
| 10631 | sender address is verified with a callout during the MAIL ACL, the |
| 10632 | sender domain is placed in $domain during the expansions of hosts, |
| 10633 | interface, and port in the smtp transport. |
| 10634 | |
| 10635 | + When a rewrite item is being processed (see chapter 31), $domain |
| 10636 | contains the domain portion of the address that is being rewritten; it |
| 10637 | can be used in the expansion of the replacement address, for example, |
| 10638 | to rewrite domains by file lookup. |
| 10639 | |
| 10640 | + With one important exception, whenever a domain list is being scanned, |
| 10641 | $domain contains the subject domain. Exception: When a domain list in a |
| 10642 | sender_domains condition in an ACL is being processed, the subject |
| 10643 | domain is in $sender_address_domain and not in $domain. It works this |
| 10644 | way so that, in a RCPT ACL, the sender domain list can be dependent on |
| 10645 | the recipient domain (which is what is in $domain at this time). |
| 10646 | |
| 10647 | + When the smtp_etrn_command option is being expanded, $domain contains |
| 10648 | the complete argument of the ETRN command (see section 48.8). |
| 10649 | |
| 10650 | $domain_data |
| 10651 | |
| 10652 | When the domains option on a router matches a domain by means of a lookup, |
| 10653 | the data read by the lookup is available during the running of the router |
| 10654 | as $domain_data. In addition, if the driver routes the address to a |
| 10655 | transport, the value is available in that transport. If the transport is |
| 10656 | handling multiple addresses, the value from the first address is used. |
| 10657 | |
| 10658 | $domain_data is also set when the domains condition in an ACL matches a |
| 10659 | domain by means of a lookup. The data read by the lookup is available |
| 10660 | during the rest of the ACL statement. In all other situations, this |
| 10661 | variable expands to nothing. |
| 10662 | |
| 10663 | $exim_gid |
| 10664 | |
| 10665 | This variable contains the numerical value of the Exim group id. |
| 10666 | |
| 10667 | $exim_path |
| 10668 | |
| 10669 | This variable contains the path to the Exim binary. |
| 10670 | |
| 10671 | $exim_uid |
| 10672 | |
| 10673 | This variable contains the numerical value of the Exim user id. |
| 10674 | |
| 10675 | $exim_version |
| 10676 | |
| 10677 | This variable contains the version string of the Exim build. The first |
| 10678 | character is a major version number, currently 4. Then after a dot, the |
| 10679 | next group of digits is a minor version number. There may be other |
| 10680 | characters following the minor version. |
| 10681 | |
| 10682 | $header_<name> |
| 10683 | |
| 10684 | This is not strictly an expansion variable. It is expansion syntax for |
| 10685 | inserting the message header line with the given name. Note that the name |
| 10686 | must be terminated by colon or white space, because it may contain a wide |
| 10687 | variety of characters. Note also that braces must not be used. |
| 10688 | |
| 10689 | $headers_added |
| 10690 | |
| 10691 | Within an ACL this variable contains the headers added so far by the ACL |
| 10692 | modifier add_header (section 43.24). The headers are a newline-separated |
| 10693 | list. |
| 10694 | |
| 10695 | $home |
| 10696 | |
| 10697 | When the check_local_user option is set for a router, the user's home |
| 10698 | directory is placed in $home when the check succeeds. In particular, this |
| 10699 | means it is set during the running of users' filter files. A router may |
| 10700 | also explicitly set a home directory for use by a transport; this can be |
| 10701 | overridden by a setting on the transport itself. |
| 10702 | |
| 10703 | When running a filter test via the -bf option, $home is set to the value of |
| 10704 | the environment variable HOME, which is subject to the keep_environment and |
| 10705 | add_environment main config options. |
| 10706 | |
| 10707 | $host |
| 10708 | |
| 10709 | If a router assigns an address to a transport (any transport), and passes a |
| 10710 | list of hosts with the address, the value of $host when the transport |
| 10711 | starts to run is the name of the first host on the list. Note that this |
| 10712 | applies both to local and remote transports. |
| 10713 | |
| 10714 | For the smtp transport, if there is more than one host, the value of $host |
| 10715 | changes as the transport works its way through the list. In particular, |
| 10716 | when the smtp transport is expanding its options for encryption using TLS, |
| 10717 | or for specifying a transport filter (see chapter 24), $host contains the |
| 10718 | name of the host to which it is connected. |
| 10719 | |
| 10720 | When used in the client part of an authenticator configuration (see chapter |
| 10721 | 33), $host contains the name of the server to which the client is |
| 10722 | connected. |
| 10723 | |
| 10724 | $host_address |
| 10725 | |
| 10726 | This variable is set to the remote host's IP address whenever $host is set |
| 10727 | for a remote connection. It is also set to the IP address that is being |
| 10728 | checked when the ignore_target_hosts option is being processed. |
| 10729 | |
| 10730 | $host_data |
| 10731 | |
| 10732 | If a hosts condition in an ACL is satisfied by means of a lookup, the |
| 10733 | result of the lookup is made available in the $host_data variable. This |
| 10734 | allows you, for example, to do things like this: |
| 10735 | |
| 10736 | deny hosts = net-lsearch;/some/file |
| 10737 | message = $host_data |
| 10738 | |
| 10739 | $host_lookup_deferred |
| 10740 | |
| 10741 | This variable normally contains "0", as does $host_lookup_failed. When a |
| 10742 | message comes from a remote host and there is an attempt to look up the |
| 10743 | host's name from its IP address, and the attempt is not successful, one of |
| 10744 | these variables is set to "1". |
| 10745 | |
| 10746 | + If the lookup receives a definite negative response (for example, a DNS |
| 10747 | lookup succeeded, but no records were found), $host_lookup_failed is |
| 10748 | set to "1". |
| 10749 | |
| 10750 | + If there is any kind of problem during the lookup, such that Exim |
| 10751 | cannot tell whether or not the host name is defined (for example, a |
| 10752 | timeout for a DNS lookup), $host_lookup_deferred is set to "1". |
| 10753 | |
| 10754 | Looking up a host's name from its IP address consists of more than just a |
| 10755 | single reverse lookup. Exim checks that a forward lookup of at least one of |
| 10756 | the names it receives from a reverse lookup yields the original IP address. |
| 10757 | If this is not the case, Exim does not accept the looked up name(s), and |
| 10758 | $host_lookup_failed is set to "1". Thus, being able to find a name from an |
| 10759 | IP address (for example, the existence of a PTR record in the DNS) is not |
| 10760 | sufficient on its own for the success of a host name lookup. If the reverse |
| 10761 | lookup succeeds, but there is a lookup problem such as a timeout when |
| 10762 | checking the result, the name is not accepted, and $host_lookup_deferred is |
| 10763 | set to "1". See also $sender_host_name. |
| 10764 | |
| 10765 | $host_lookup_failed |
| 10766 | |
| 10767 | See $host_lookup_deferred. |
| 10768 | |
| 10769 | $host_port |
| 10770 | |
| 10771 | This variable is set to the remote host's TCP port whenever $host is set |
| 10772 | for an outbound connection. |
| 10773 | |
| 10774 | $initial_cwd |
| 10775 | |
| 10776 | This variable contains the full path name of the initial working directory |
| 10777 | of the current Exim process. This may differ from the current working |
| 10778 | directory, as Exim changes this to "/" during early startup, and to |
| 10779 | $spool_directory later. |
| 10780 | |
| 10781 | $inode |
| 10782 | |
| 10783 | The only time this variable is set is while expanding the directory_file |
| 10784 | option in the appendfile transport. The variable contains the inode number |
| 10785 | of the temporary file which is about to be renamed. It can be used to |
| 10786 | construct a unique name for the file. |
| 10787 | |
| 10788 | $interface_address |
| 10789 | |
| 10790 | This is an obsolete name for $received_ip_address. |
| 10791 | |
| 10792 | $interface_port |
| 10793 | |
| 10794 | This is an obsolete name for $received_port. |
| 10795 | |
| 10796 | $item |
| 10797 | |
| 10798 | This variable is used during the expansion of forall and forany conditions |
| 10799 | (see section 11.7), and filter, map, and reduce items (see section 11.7). |
| 10800 | In other circumstances, it is empty. |
| 10801 | |
| 10802 | $ldap_dn |
| 10803 | |
| 10804 | This variable, which is available only when Exim is compiled with LDAP |
| 10805 | support, contains the DN from the last entry in the most recently |
| 10806 | successful LDAP lookup. |
| 10807 | |
| 10808 | $load_average |
| 10809 | |
| 10810 | This variable contains the system load average, multiplied by 1000 so that |
| 10811 | it is an integer. For example, if the load average is 0.21, the value of |
| 10812 | the variable is 210. The value is recomputed every time the variable is |
| 10813 | referenced. |
| 10814 | |
| 10815 | $local_part |
| 10816 | |
| 10817 | When an address is being routed, or delivered on its own, this variable |
| 10818 | contains the local part. When a number of addresses are being delivered |
| 10819 | together (for example, multiple RCPT commands in an SMTP session), |
| 10820 | $local_part is not set. |
| 10821 | |
| 10822 | Global address rewriting happens when a message is received, so the value |
| 10823 | of $local_part during routing and delivery is the value after rewriting. |
| 10824 | $local_part is set during user filtering, but not during system filtering, |
| 10825 | because a message may have many recipients and the system filter is called |
| 10826 | just once. |
| 10827 | |
| 10828 | If a local part prefix or suffix has been recognized, it is not included in |
| 10829 | the value of $local_part during routing and subsequent delivery. The values |
| 10830 | of any prefix or suffix are in $local_part_prefix and $local_part_suffix, |
| 10831 | respectively. |
| 10832 | |
| 10833 | When a message is being delivered to a file, pipe, or autoreply transport |
| 10834 | as a result of aliasing or forwarding, $local_part is set to the local part |
| 10835 | of the parent address, not to the file name or command (see $address_file |
| 10836 | and $address_pipe). |
| 10837 | |
| 10838 | When an ACL is running for a RCPT command, $local_part contains the local |
| 10839 | part of the recipient address. |
| 10840 | |
| 10841 | When a rewrite item is being processed (see chapter 31), $local_part |
| 10842 | contains the local part of the address that is being rewritten; it can be |
| 10843 | used in the expansion of the replacement address, for example. |
| 10844 | |
| 10845 | In all cases, all quoting is removed from the local part. For example, for |
| 10846 | both the addresses |
| 10847 | |
| 10848 | "abc:xyz"@test.example |
| 10849 | abc\:xyz@test.example |
| 10850 | |
| 10851 | the value of $local_part is |
| 10852 | |
| 10853 | abc:xyz |
| 10854 | |
| 10855 | If you use $local_part to create another address, you should always wrap it |
| 10856 | inside a quoting operator. For example, in a redirect router you could |
| 10857 | have: |
| 10858 | |
| 10859 | data = ${quote_local_part:$local_part}@new.domain.example |
| 10860 | |
| 10861 | Note: The value of $local_part is normally lower cased. If you want to |
| 10862 | process local parts in a case-dependent manner in a router, you can set the |
| 10863 | caseful_local_part option (see chapter 15). |
| 10864 | |
| 10865 | $local_part_data |
| 10866 | |
| 10867 | When the local_parts option on a router matches a local part by means of a |
| 10868 | lookup, the data read by the lookup is available during the running of the |
| 10869 | router as $local_part_data. In addition, if the driver routes the address |
| 10870 | to a transport, the value is available in that transport. If the transport |
| 10871 | is handling multiple addresses, the value from the first address is used. |
| 10872 | |
| 10873 | $local_part_data is also set when the local_parts condition in an ACL |
| 10874 | matches a local part by means of a lookup. The data read by the lookup is |
| 10875 | available during the rest of the ACL statement. In all other situations, |
| 10876 | this variable expands to nothing. |
| 10877 | |
| 10878 | $local_part_prefix |
| 10879 | |
| 10880 | When an address is being routed or delivered, and a specific prefix for the |
| 10881 | local part was recognized, it is available in this variable, having been |
| 10882 | removed from $local_part. |
| 10883 | |
| 10884 | $local_part_suffix |
| 10885 | |
| 10886 | When an address is being routed or delivered, and a specific suffix for the |
| 10887 | local part was recognized, it is available in this variable, having been |
| 10888 | removed from $local_part. |
| 10889 | |
| 10890 | $local_scan_data |
| 10891 | |
| 10892 | This variable contains the text returned by the local_scan() function when |
| 10893 | a message is received. See chapter 45 for more details. |
| 10894 | |
| 10895 | $local_user_gid |
| 10896 | |
| 10897 | See $local_user_uid. |
| 10898 | |
| 10899 | $local_user_uid |
| 10900 | |
| 10901 | This variable and $local_user_gid are set to the uid and gid after the |
| 10902 | check_local_user router precondition succeeds. This means that their values |
| 10903 | are available for the remaining preconditions (senders, require_files, and |
| 10904 | condition), for the address_data expansion, and for any router-specific |
| 10905 | expansions. At all other times, the values in these variables are "(uid_t) |
| 10906 | (-1)" and "(gid_t)(-1)", respectively. |
| 10907 | |
| 10908 | $localhost_number |
| 10909 | |
| 10910 | This contains the expanded value of the localhost_number option. The |
| 10911 | expansion happens after the main options have been read. |
| 10912 | |
| 10913 | $log_inodes |
| 10914 | |
| 10915 | The number of free inodes in the disk partition where Exim's log files are |
| 10916 | being written. The value is recalculated whenever the variable is |
| 10917 | referenced. If the relevant file system does not have the concept of |
| 10918 | inodes, the value of is -1. See also the check_log_inodes option. |
| 10919 | |
| 10920 | $log_space |
| 10921 | |
| 10922 | The amount of free space (as a number of kilobytes) in the disk partition |
| 10923 | where Exim's log files are being written. The value is recalculated |
| 10924 | whenever the variable is referenced. If the operating system does not have |
| 10925 | the ability to find the amount of free space (only true for experimental |
| 10926 | systems), the space value is -1. See also the check_log_space option. |
| 10927 | |
| 10928 | $lookup_dnssec_authenticated |
| 10929 | |
| 10930 | This variable is set after a DNS lookup done by a dnsdb lookup expansion, |
| 10931 | dnslookup router or smtp transport. It will be empty if DNSSEC was not |
| 10932 | requested, "no" if the result was not labelled as authenticated data and |
| 10933 | "yes" if it was. Results that are labelled as authoritative answer that |
| 10934 | match the dns_trust_aa configuration variable count also as authenticated |
| 10935 | data. |
| 10936 | |
| 10937 | $mailstore_basename |
| 10938 | |
| 10939 | This variable is set only when doing deliveries in "mailstore" format in |
| 10940 | the appendfile transport. During the expansion of the mailstore_prefix, |
| 10941 | mailstore_suffix, message_prefix, and message_suffix options, it contains |
| 10942 | the basename of the files that are being written, that is, the name without |
| 10943 | the ".tmp", ".env", or ".msg" suffix. At all other times, this variable is |
| 10944 | empty. |
| 10945 | |
| 10946 | $malware_name |
| 10947 | |
| 10948 | This variable is available when Exim is compiled with the content-scanning |
| 10949 | extension. It is set to the name of the virus that was found when the ACL |
| 10950 | malware condition is true (see section 44.1). |
| 10951 | |
| 10952 | $max_received_linelength |
| 10953 | |
| 10954 | This variable contains the number of bytes in the longest line that was |
| 10955 | received as part of the message, not counting the line termination |
| 10956 | character(s). |
| 10957 | |
| 10958 | $message_age |
| 10959 | |
| 10960 | This variable is set at the start of a delivery attempt to contain the |
| 10961 | number of seconds since the message was received. It does not change during |
| 10962 | a single delivery attempt. |
| 10963 | |
| 10964 | $message_body |
| 10965 | |
| 10966 | This variable contains the initial portion of a message's body while it is |
| 10967 | being delivered, and is intended mainly for use in filter files. The |
| 10968 | maximum number of characters of the body that are put into the variable is |
| 10969 | set by the message_body_visible configuration option; the default is 500. |
| 10970 | |
| 10971 | By default, newlines are converted into spaces in $message_body, to make it |
| 10972 | easier to search for phrases that might be split over a line break. |
| 10973 | However, this can be disabled by setting message_body_newlines to be true. |
| 10974 | Binary zeros are always converted into spaces. |
| 10975 | |
| 10976 | $message_body_end |
| 10977 | |
| 10978 | This variable contains the final portion of a message's body while it is |
| 10979 | being delivered. The format and maximum size are as for $message_body. |
| 10980 | |
| 10981 | $message_body_size |
| 10982 | |
| 10983 | When a message is being delivered, this variable contains the size of the |
| 10984 | body in bytes. The count starts from the character after the blank line |
| 10985 | that separates the body from the header. Newlines are included in the |
| 10986 | count. See also $message_size, $body_linecount, and $body_zerocount. |
| 10987 | |
| 10988 | $message_exim_id |
| 10989 | |
| 10990 | When a message is being received or delivered, this variable contains the |
| 10991 | unique message id that is generated and used by Exim to identify the |
| 10992 | message. An id is not created for a message until after its header has been |
| 10993 | successfully received. Note: This is not the contents of the Message-ID: |
| 10994 | header line; it is the local id that Exim assigns to the message, for |
| 10995 | example: "1BXTIK-0001yO-VA". |
| 10996 | |
| 10997 | $message_headers |
| 10998 | |
| 10999 | This variable contains a concatenation of all the header lines when a |
| 11000 | message is being processed, except for lines added by routers or |
| 11001 | transports. The header lines are separated by newline characters. Their |
| 11002 | contents are decoded in the same way as a header line that is inserted by |
| 11003 | bheader. |
| 11004 | |
| 11005 | $message_headers_raw |
| 11006 | |
| 11007 | This variable is like $message_headers except that no processing of the |
| 11008 | contents of header lines is done. |
| 11009 | |
| 11010 | $message_id |
| 11011 | |
| 11012 | This is an old name for $message_exim_id. It is now deprecated. |
| 11013 | |
| 11014 | $message_linecount |
| 11015 | |
| 11016 | This variable contains the total number of lines in the header and body of |
| 11017 | the message. Compare $body_linecount, which is the count for the body only. |
| 11018 | During the DATA and content-scanning ACLs, $message_linecount contains the |
| 11019 | number of lines received. Before delivery happens (that is, before filters, |
| 11020 | routers, and transports run) the count is increased to include the |
| 11021 | Received: header line that Exim standardly adds, and also any other header |
| 11022 | lines that are added by ACLs. The blank line that separates the message |
| 11023 | header from the body is not counted. |
| 11024 | |
| 11025 | As with the special case of $message_size, during the expansion of the |
| 11026 | appendfile transport's maildir_tag option in maildir format, the value of |
| 11027 | $message_linecount is the precise size of the number of newlines in the |
| 11028 | file that has been written (minus one for the blank line between the header |
| 11029 | and the body). |
| 11030 | |
| 11031 | Here is an example of the use of this variable in a DATA ACL: |
| 11032 | |
| 11033 | deny message = Too many lines in message header |
| 11034 | condition = \ |
| 11035 | ${if <{250}{${eval:$message_linecount - $body_linecount}}} |
| 11036 | |
| 11037 | In the MAIL and RCPT ACLs, the value is zero because at that stage the |
| 11038 | message has not yet been received. |
| 11039 | |
| 11040 | $message_size |
| 11041 | |
| 11042 | When a message is being processed, this variable contains its size in |
| 11043 | bytes. In most cases, the size includes those headers that were received |
| 11044 | with the message, but not those (such as Envelope-to:) that are added to |
| 11045 | individual deliveries as they are written. However, there is one special |
| 11046 | case: during the expansion of the maildir_tag option in the appendfile |
| 11047 | transport while doing a delivery in maildir format, the value of |
| 11048 | $message_size is the precise size of the file that has been written. See |
| 11049 | also $message_body_size, $body_linecount, and $body_zerocount. |
| 11050 | |
| 11051 | While running a per message ACL (mail/rcpt/predata), $message_size contains |
| 11052 | the size supplied on the MAIL command, or -1 if no size was given. The |
| 11053 | value may not, of course, be truthful. |
| 11054 | |
| 11055 | $mime_xxx |
| 11056 | |
| 11057 | A number of variables whose names start with $mime are available when Exim |
| 11058 | is compiled with the content-scanning extension. For details, see section |
| 11059 | 44.4. |
| 11060 | |
| 11061 | $n0 - $n9 |
| 11062 | |
| 11063 | These variables are counters that can be incremented by means of the add |
| 11064 | command in filter files. |
| 11065 | |
| 11066 | $original_domain |
| 11067 | |
| 11068 | When a top-level address is being processed for delivery, this contains the |
| 11069 | same value as $domain. However, if a "child" address (for example, |
| 11070 | generated by an alias, forward, or filter file) is being processed, this |
| 11071 | variable contains the domain of the original address (lower cased). This |
| 11072 | differs from $parent_domain only when there is more than one level of |
| 11073 | aliasing or forwarding. When more than one address is being delivered in a |
| 11074 | single transport run, $original_domain is not set. |
| 11075 | |
| 11076 | If a new address is created by means of a deliver command in a system |
| 11077 | filter, it is set up with an artificial "parent" address. This has the |
| 11078 | local part system-filter and the default qualify domain. |
| 11079 | |
| 11080 | $original_local_part |
| 11081 | |
| 11082 | When a top-level address is being processed for delivery, this contains the |
| 11083 | same value as $local_part, unless a prefix or suffix was removed from the |
| 11084 | local part, because $original_local_part always contains the full local |
| 11085 | part. When a "child" address (for example, generated by an alias, forward, |
| 11086 | or filter file) is being processed, this variable contains the full local |
| 11087 | part of the original address. |
| 11088 | |
| 11089 | If the router that did the redirection processed the local part |
| 11090 | case-insensitively, the value in $original_local_part is in lower case. |
| 11091 | This variable differs from $parent_local_part only when there is more than |
| 11092 | one level of aliasing or forwarding. When more than one address is being |
| 11093 | delivered in a single transport run, $original_local_part is not set. |
| 11094 | |
| 11095 | If a new address is created by means of a deliver command in a system |
| 11096 | filter, it is set up with an artificial "parent" address. This has the |
| 11097 | local part system-filter and the default qualify domain. |
| 11098 | |
| 11099 | $originator_gid |
| 11100 | |
| 11101 | This variable contains the value of $caller_gid that was set when the |
| 11102 | message was received. For messages received via the command line, this is |
| 11103 | the gid of the sending user. For messages received by SMTP over TCP/IP, |
| 11104 | this is normally the gid of the Exim user. |
| 11105 | |
| 11106 | $originator_uid |
| 11107 | |
| 11108 | The value of $caller_uid that was set when the message was received. For |
| 11109 | messages received via the command line, this is the uid of the sending |
| 11110 | user. For messages received by SMTP over TCP/IP, this is normally the uid |
| 11111 | of the Exim user. |
| 11112 | |
| 11113 | $parent_domain |
| 11114 | |
| 11115 | This variable is similar to $original_domain (see above), except that it |
| 11116 | refers to the immediately preceding parent address. |
| 11117 | |
| 11118 | $parent_local_part |
| 11119 | |
| 11120 | This variable is similar to $original_local_part (see above), except that |
| 11121 | it refers to the immediately preceding parent address. |
| 11122 | |
| 11123 | $pid |
| 11124 | |
| 11125 | This variable contains the current process id. |
| 11126 | |
| 11127 | $pipe_addresses |
| 11128 | |
| 11129 | This is not an expansion variable, but is mentioned here because the string |
| 11130 | "$pipe_addresses" is handled specially in the command specification for the |
| 11131 | pipe transport (chapter 29) and in transport filters (described under |
| 11132 | transport_filter in chapter 24). It cannot be used in general expansion |
| 11133 | strings, and provokes an "unknown variable" error if encountered. |
| 11134 | |
| 11135 | $primary_hostname |
| 11136 | |
| 11137 | This variable contains the value set by primary_hostname in the |
| 11138 | configuration file, or read by the uname() function. If uname() returns a |
| 11139 | single-component name, Exim calls gethostbyname() (or getipnodebyname() |
| 11140 | where available) in an attempt to acquire a fully qualified host name. See |
| 11141 | also $smtp_active_hostname. |
| 11142 | |
| 11143 | $proxy_external_address, $proxy_external_port, $proxy_local_address, |
| 11144 | $proxy_local_port, $proxy_session |
| 11145 | |
| 11146 | These variables are only available when built with Proxy Protocol or SOCKS5 |
| 11147 | support. For details see chapter 58.1. |
| 11148 | |
| 11149 | $prdr_requested |
| 11150 | |
| 11151 | This variable is set to "yes" if PRDR was requested by the client for the |
| 11152 | current message, otherwise "no". |
| 11153 | |
| 11154 | $prvscheck_address |
| 11155 | |
| 11156 | This variable is used in conjunction with the prvscheck expansion item, |
| 11157 | which is described in sections 11.5 and 43.51. |
| 11158 | |
| 11159 | $prvscheck_keynum |
| 11160 | |
| 11161 | This variable is used in conjunction with the prvscheck expansion item, |
| 11162 | which is described in sections 11.5 and 43.51. |
| 11163 | |
| 11164 | $prvscheck_result |
| 11165 | |
| 11166 | This variable is used in conjunction with the prvscheck expansion item, |
| 11167 | which is described in sections 11.5 and 43.51. |
| 11168 | |
| 11169 | $qualify_domain |
| 11170 | |
| 11171 | The value set for the qualify_domain option in the configuration file. |
| 11172 | |
| 11173 | $qualify_recipient |
| 11174 | |
| 11175 | The value set for the qualify_recipient option in the configuration file, |
| 11176 | or if not set, the value of $qualify_domain. |
| 11177 | |
| 11178 | $queue_name |
| 11179 | |
| 11180 | The name of the spool queue in use; empty for the default queue. |
| 11181 | |
| 11182 | $rcpt_count |
| 11183 | |
| 11184 | When a message is being received by SMTP, this variable contains the number |
| 11185 | of RCPT commands received for the current message. If this variable is used |
| 11186 | in a RCPT ACL, its value includes the current command. |
| 11187 | |
| 11188 | $rcpt_defer_count |
| 11189 | |
| 11190 | When a message is being received by SMTP, this variable contains the number |
| 11191 | of RCPT commands in the current message that have previously been rejected |
| 11192 | with a temporary (4xx) response. |
| 11193 | |
| 11194 | $rcpt_fail_count |
| 11195 | |
| 11196 | When a message is being received by SMTP, this variable contains the number |
| 11197 | of RCPT commands in the current message that have previously been rejected |
| 11198 | with a permanent (5xx) response. |
| 11199 | |
| 11200 | $received_count |
| 11201 | |
| 11202 | This variable contains the number of Received: header lines in the message, |
| 11203 | including the one added by Exim (so its value is always greater than zero). |
| 11204 | It is available in the DATA ACL, the non-SMTP ACL, and while routing and |
| 11205 | delivering. |
| 11206 | |
| 11207 | $received_for |
| 11208 | |
| 11209 | If there is only a single recipient address in an incoming message, this |
| 11210 | variable contains that address when the Received: header line is being |
| 11211 | built. The value is copied after recipient rewriting has happened, but |
| 11212 | before the local_scan() function is run. |
| 11213 | |
| 11214 | $received_ip_address |
| 11215 | |
| 11216 | As soon as an Exim server starts processing an incoming TCP/IP connection, |
| 11217 | this variable is set to the address of the local IP interface, and |
| 11218 | $received_port is set to the local port number. (The remote IP address and |
| 11219 | port are in $sender_host_address and $sender_host_port.) When testing with |
| 11220 | -bh, the port value is -1 unless it has been set using the -oMi command |
| 11221 | line option. |
| 11222 | |
| 11223 | As well as being useful in ACLs (including the "connect" ACL), these |
| 11224 | variable could be used, for example, to make the file name for a TLS |
| 11225 | certificate depend on which interface and/or port is being used for the |
| 11226 | incoming connection. The values of $received_ip_address and $received_port |
| 11227 | are saved with any messages that are received, thus making these variables |
| 11228 | available at delivery time. For outbound connections see |
| 11229 | $sending_ip_address. |
| 11230 | |
| 11231 | $received_port |
| 11232 | |
| 11233 | See $received_ip_address. |
| 11234 | |
| 11235 | $received_protocol |
| 11236 | |
| 11237 | When a message is being processed, this variable contains the name of the |
| 11238 | protocol by which it was received. Most of the names used by Exim are |
| 11239 | defined by RFCs 821, 2821, and 3848. They start with "smtp" (the client |
| 11240 | used HELO) or "esmtp" (the client used EHLO). This can be followed by "s" |
| 11241 | for secure (encrypted) and/or "a" for authenticated. Thus, for example, if |
| 11242 | the protocol is set to "esmtpsa", the message was received over an |
| 11243 | encrypted SMTP connection and the client was successfully authenticated. |
| 11244 | |
| 11245 | Exim uses the protocol name "smtps" for the case when encryption is |
| 11246 | automatically set up on connection without the use of STARTTLS (see |
| 11247 | tls_on_connect_ports), and the client uses HELO to initiate the encrypted |
| 11248 | SMTP session. The name "smtps" is also used for the rare situation where |
| 11249 | the client initially uses EHLO, sets up an encrypted connection using |
| 11250 | STARTTLS, and then uses HELO afterwards. |
| 11251 | |
| 11252 | The -oMr option provides a way of specifying a custom protocol name for |
| 11253 | messages that are injected locally by trusted callers. This is commonly |
| 11254 | used to identify messages that are being re-injected after some kind of |
| 11255 | scanning. |
| 11256 | |
| 11257 | $received_time |
| 11258 | |
| 11259 | This variable contains the date and time when the current message was |
| 11260 | received, as a number of seconds since the start of the Unix epoch. |
| 11261 | |
| 11262 | $recipient_data |
| 11263 | |
| 11264 | This variable is set after an indexing lookup success in an ACL recipients |
| 11265 | condition. It contains the data from the lookup, and the value remains set |
| 11266 | until the next recipients test. Thus, you can do things like this: |
| 11267 | |
| 11268 | require recipients = cdb*@;/some/file |
| 11269 | deny some further test involving $recipient_data |
| 11270 | |
| 11271 | Warning: This variable is set only when a lookup is used as an indexing |
| 11272 | method in the address list, using the semicolon syntax as in the example |
| 11273 | above. The variable is not set for a lookup that is used as part of the |
| 11274 | string expansion that all such lists undergo before being interpreted. |
| 11275 | |
| 11276 | $recipient_verify_failure |
| 11277 | |
| 11278 | In an ACL, when a recipient verification fails, this variable contains |
| 11279 | information about the failure. It is set to one of the following words: |
| 11280 | |
| 11281 | + "qualify": The address was unqualified (no domain), and the message was |
| 11282 | neither local nor came from an exempted host. |
| 11283 | |
| 11284 | + "route": Routing failed. |
| 11285 | |
| 11286 | + "mail": Routing succeeded, and a callout was attempted; rejection |
| 11287 | occurred at or before the MAIL command (that is, on initial connection, |
| 11288 | HELO, or MAIL). |
| 11289 | |
| 11290 | + "recipient": The RCPT command in a callout was rejected. |
| 11291 | |
| 11292 | + "postmaster": The postmaster check in a callout was rejected. |
| 11293 | |
| 11294 | The main use of this variable is expected to be to distinguish between |
| 11295 | rejections of MAIL and rejections of RCPT. |
| 11296 | |
| 11297 | $recipients |
| 11298 | |
| 11299 | This variable contains a list of envelope recipients for a message. A comma |
| 11300 | and a space separate the addresses in the replacement text. However, the |
| 11301 | variable is not generally available, to prevent exposure of Bcc recipients |
| 11302 | in unprivileged users' filter files. You can use $recipients only in these |
| 11303 | cases: |
| 11304 | |
| 11305 | 1. In a system filter file. |
| 11306 | |
| 11307 | 2. In the ACLs associated with the DATA command and with non-SMTP |
| 11308 | messages, that is, the ACLs defined by acl_smtp_predata, acl_smtp_data, |
| 11309 | acl_smtp_mime, acl_not_smtp_start, acl_not_smtp, and acl_not_smtp_mime. |
| 11310 | |
| 11311 | 3. From within a local_scan() function. |
| 11312 | |
| 11313 | $recipients_count |
| 11314 | |
| 11315 | When a message is being processed, this variable contains the number of |
| 11316 | envelope recipients that came with the message. Duplicates are not excluded |
| 11317 | from the count. While a message is being received over SMTP, the number |
| 11318 | increases for each accepted recipient. It can be referenced in an ACL. |
| 11319 | |
| 11320 | $regex_match_string |
| 11321 | |
| 11322 | This variable is set to contain the matching regular expression after a |
| 11323 | regex ACL condition has matched (see section 44.5). |
| 11324 | |
| 11325 | $regex1, $regex2, etc |
| 11326 | |
| 11327 | When a regex or mime_regex ACL condition succeeds, these variables contain |
| 11328 | the captured substrings identified by the regular expression. |
| 11329 | |
| 11330 | $reply_address |
| 11331 | |
| 11332 | When a message is being processed, this variable contains the contents of |
| 11333 | the Reply-To: header line if one exists and it is not empty, or otherwise |
| 11334 | the contents of the From: header line. Apart from the removal of leading |
| 11335 | white space, the value is not processed in any way. In particular, no RFC |
| 11336 | 2047 decoding or character code translation takes place. |
| 11337 | |
| 11338 | $return_path |
| 11339 | |
| 11340 | When a message is being delivered, this variable contains the return path - |
| 11341 | the sender field that will be sent as part of the envelope. It is not |
| 11342 | enclosed in <> characters. At the start of routing an address, $return_path |
| 11343 | has the same value as $sender_address, but if, for example, an incoming |
| 11344 | message to a mailing list has been expanded by a router which specifies a |
| 11345 | different address for bounce messages, $return_path subsequently contains |
| 11346 | the new bounce address, whereas $sender_address always contains the |
| 11347 | original sender address that was received with the message. In other words, |
| 11348 | $sender_address contains the incoming envelope sender, and $return_path |
| 11349 | contains the outgoing envelope sender. |
| 11350 | |
| 11351 | $return_size_limit |
| 11352 | |
| 11353 | This is an obsolete name for $bounce_return_size_limit. |
| 11354 | |
| 11355 | $router_name |
| 11356 | |
| 11357 | During the running of a router this variable contains its name. |
| 11358 | |
| 11359 | $runrc |
| 11360 | |
| 11361 | This variable contains the return code from a command that is run by the $ |
| 11362 | {run...} expansion item. Warning: In a router or transport, you cannot |
| 11363 | assume the order in which option values are expanded, except for those |
| 11364 | preconditions whose order of testing is documented. Therefore, you cannot |
| 11365 | reliably expect to set $runrc by the expansion of one option, and use it in |
| 11366 | another. |
| 11367 | |
| 11368 | $self_hostname |
| 11369 | |
| 11370 | When an address is routed to a supposedly remote host that turns out to be |
| 11371 | the local host, what happens is controlled by the self generic router |
| 11372 | option. One of its values causes the address to be passed to another |
| 11373 | router. When this happens, $self_hostname is set to the name of the local |
| 11374 | host that the original router encountered. In other circumstances its |
| 11375 | contents are null. |
| 11376 | |
| 11377 | $sender_address |
| 11378 | |
| 11379 | When a message is being processed, this variable contains the sender's |
| 11380 | address that was received in the message's envelope. The case of letters in |
| 11381 | the address is retained, in both the local part and the domain. For bounce |
| 11382 | messages, the value of this variable is the empty string. See also |
| 11383 | $return_path. |
| 11384 | |
| 11385 | $sender_address_data |
| 11386 | |
| 11387 | If $address_data is set when the routers are called from an ACL to verify a |
| 11388 | sender address, the final value is preserved in $sender_address_data, to |
| 11389 | distinguish it from data from a recipient address. The value does not |
| 11390 | persist after the end of the current ACL statement. If you want to preserve |
| 11391 | it for longer, you can save it in an ACL variable. |
| 11392 | |
| 11393 | $sender_address_domain |
| 11394 | |
| 11395 | The domain portion of $sender_address. |
| 11396 | |
| 11397 | $sender_address_local_part |
| 11398 | |
| 11399 | The local part portion of $sender_address. |
| 11400 | |
| 11401 | $sender_data |
| 11402 | |
| 11403 | This variable is set after a lookup success in an ACL senders condition or |
| 11404 | in a router senders option. It contains the data from the lookup, and the |
| 11405 | value remains set until the next senders test. Thus, you can do things like |
| 11406 | this: |
| 11407 | |
| 11408 | require senders = cdb*@;/some/file |
| 11409 | deny some further test involving $sender_data |
| 11410 | |
| 11411 | Warning: This variable is set only when a lookup is used as an indexing |
| 11412 | method in the address list, using the semicolon syntax as in the example |
| 11413 | above. The variable is not set for a lookup that is used as part of the |
| 11414 | string expansion that all such lists undergo before being interpreted. |
| 11415 | |
| 11416 | $sender_fullhost |
| 11417 | |
| 11418 | When a message is received from a remote host, this variable contains the |
| 11419 | host name and IP address in a single string. It ends with the IP address in |
| 11420 | square brackets, followed by a colon and a port number if the logging of |
| 11421 | ports is enabled. The format of the rest of the string depends on whether |
| 11422 | the host issued a HELO or EHLO SMTP command, and whether the host name was |
| 11423 | verified by looking up its IP address. (Looking up the IP address can be |
| 11424 | forced by the host_lookup option, independent of verification.) A plain |
| 11425 | host name at the start of the string is a verified host name; if this is |
| 11426 | not present, verification either failed or was not requested. A host name |
| 11427 | in parentheses is the argument of a HELO or EHLO command. This is omitted |
| 11428 | if it is identical to the verified host name or to the host's IP address in |
| 11429 | square brackets. |
| 11430 | |
| 11431 | $sender_helo_dnssec |
| 11432 | |
| 11433 | This boolean variable is true if a successful HELO verification was done |
| 11434 | using DNS information the resolver library stated was authenticated data. |
| 11435 | |
| 11436 | $sender_helo_name |
| 11437 | |
| 11438 | When a message is received from a remote host that has issued a HELO or |
| 11439 | EHLO command, the argument of that command is placed in this variable. It |
| 11440 | is also set if HELO or EHLO is used when a message is received using SMTP |
| 11441 | locally via the -bs or -bS options. |
| 11442 | |
| 11443 | $sender_host_address |
| 11444 | |
| 11445 | When a message is received from a remote host using SMTP, this variable |
| 11446 | contains that host's IP address. For locally non-SMTP submitted messages, |
| 11447 | it is empty. |
| 11448 | |
| 11449 | $sender_host_authenticated |
| 11450 | |
| 11451 | This variable contains the name (not the public name) of the authenticator |
| 11452 | driver that successfully authenticated the client from which the message |
| 11453 | was received. It is empty if there was no successful authentication. See |
| 11454 | also $authenticated_id. |
| 11455 | |
| 11456 | $sender_host_dnssec |
| 11457 | |
| 11458 | If an attempt to populate $sender_host_name has been made (by reference, |
| 11459 | hosts_lookup or otherwise) then this boolean will have been set true if, |
| 11460 | and only if, the resolver library states that both the reverse and forward |
| 11461 | DNS were authenticated data. At all other times, this variable is false. |
| 11462 | |
| 11463 | It is likely that you will need to coerce DNSSEC support on in the resolver |
| 11464 | library, by setting: |
| 11465 | |
| 11466 | dns_dnssec_ok = 1 |
| 11467 | |
| 11468 | Exim does not perform DNSSEC validation itself, instead leaving that to a |
| 11469 | validating resolver (e.g. unbound, or bind with suitable configuration). |
| 11470 | |
| 11471 | If you have changed host_lookup_order so that "bydns" is not the first |
| 11472 | mechanism in the list, then this variable will be false. |
| 11473 | |
| 11474 | This requires that your system resolver library support EDNS0 (and that |
| 11475 | DNSSEC flags exist in the system headers). If the resolver silently drops |
| 11476 | all EDNS0 options, then this will have no effect. OpenBSD's asr resolver is |
| 11477 | known to currently ignore EDNS0, documented in CAVEATS of asr_run(3). |
| 11478 | |
| 11479 | $sender_host_name |
| 11480 | |
| 11481 | When a message is received from a remote host, this variable contains the |
| 11482 | host's name as obtained by looking up its IP address. For messages received |
| 11483 | by other means, this variable is empty. |
| 11484 | |
| 11485 | If the host name has not previously been looked up, a reference to |
| 11486 | $sender_host_name triggers a lookup (for messages from remote hosts). A |
| 11487 | looked up name is accepted only if it leads back to the original IP address |
| 11488 | via a forward lookup. If either the reverse or the forward lookup fails to |
| 11489 | find any data, or if the forward lookup does not yield the original IP |
| 11490 | address, $sender_host_name remains empty, and $host_lookup_failed is set to |
| 11491 | "1". |
| 11492 | |
| 11493 | However, if either of the lookups cannot be completed (for example, there |
| 11494 | is a DNS timeout), $host_lookup_deferred is set to "1", and |
| 11495 | $host_lookup_failed remains set to "0". |
| 11496 | |
| 11497 | Once $host_lookup_failed is set to "1", Exim does not try to look up the |
| 11498 | host name again if there is a subsequent reference to $sender_host_name in |
| 11499 | the same Exim process, but it does try again if $host_lookup_deferred is |
| 11500 | set to "1". |
| 11501 | |
| 11502 | Exim does not automatically look up every calling host's name. If you want |
| 11503 | maximum efficiency, you should arrange your configuration so that it avoids |
| 11504 | these lookups altogether. The lookup happens only if one or more of the |
| 11505 | following are true: |
| 11506 | |
| 11507 | + A string containing $sender_host_name is expanded. |
| 11508 | |
| 11509 | + The calling host matches the list in host_lookup. In the default |
| 11510 | configuration, this option is set to *, so it must be changed if |
| 11511 | lookups are to be avoided. (In the code, the default for host_lookup is |
| 11512 | unset.) |
| 11513 | |
| 11514 | + Exim needs the host name in order to test an item in a host list. The |
| 11515 | items that require this are described in sections 10.13 and 10.17. |
| 11516 | |
| 11517 | + The calling host matches helo_try_verify_hosts or helo_verify_hosts. In |
| 11518 | this case, the host name is required to compare with the name quoted in |
| 11519 | any EHLO or HELO commands that the client issues. |
| 11520 | |
| 11521 | + The remote host issues a EHLO or HELO command that quotes one of the |
| 11522 | domains in helo_lookup_domains. The default value of this option is |
| 11523 | |
| 11524 | helo_lookup_domains = @ : @[] |
| 11525 | |
| 11526 | which causes a lookup if a remote host (incorrectly) gives the server's |
| 11527 | name or IP address in an EHLO or HELO command. |
| 11528 | |
| 11529 | $sender_host_port |
| 11530 | |
| 11531 | When a message is received from a remote host, this variable contains the |
| 11532 | port number that was used on the remote host. |
| 11533 | |
| 11534 | $sender_ident |
| 11535 | |
| 11536 | When a message is received from a remote host, this variable contains the |
| 11537 | identification received in response to an RFC 1413 request. When a message |
| 11538 | has been received locally, this variable contains the login name of the |
| 11539 | user that called Exim. |
| 11540 | |
| 11541 | $sender_rate_xxx |
| 11542 | |
| 11543 | A number of variables whose names begin $sender_rate_ are set as part of |
| 11544 | the ratelimit ACL condition. Details are given in section 43.38. |
| 11545 | |
| 11546 | $sender_rcvhost |
| 11547 | |
| 11548 | This is provided specifically for use in Received: headers. It starts with |
| 11549 | either the verified host name (as obtained from a reverse DNS lookup) or, |
| 11550 | if there is no verified host name, the IP address in square brackets. After |
| 11551 | that there may be text in parentheses. When the first item is a verified |
| 11552 | host name, the first thing in the parentheses is the IP address in square |
| 11553 | brackets, followed by a colon and a port number if port logging is enabled. |
| 11554 | When the first item is an IP address, the port is recorded as "port=xxxx" |
| 11555 | inside the parentheses. |
| 11556 | |
| 11557 | There may also be items of the form "helo=xxxx" if HELO or EHLO was used |
| 11558 | and its argument was not identical to the real host name or IP address, and |
| 11559 | "ident=xxxx" if an RFC 1413 ident string is available. If all three items |
| 11560 | are present in the parentheses, a newline and tab are inserted into the |
| 11561 | string, to improve the formatting of the Received: header. |
| 11562 | |
| 11563 | $sender_verify_failure |
| 11564 | |
| 11565 | In an ACL, when a sender verification fails, this variable contains |
| 11566 | information about the failure. The details are the same as for |
| 11567 | $recipient_verify_failure. |
| 11568 | |
| 11569 | $sending_ip_address |
| 11570 | |
| 11571 | This variable is set whenever an outgoing SMTP connection to another host |
| 11572 | has been set up. It contains the IP address of the local interface that is |
| 11573 | being used. This is useful if a host that has more than one IP address |
| 11574 | wants to take on different personalities depending on which one is being |
| 11575 | used. For incoming connections, see $received_ip_address. |
| 11576 | |
| 11577 | $sending_port |
| 11578 | |
| 11579 | This variable is set whenever an outgoing SMTP connection to another host |
| 11580 | has been set up. It contains the local port that is being used. For |
| 11581 | incoming connections, see $received_port. |
| 11582 | |
| 11583 | $smtp_active_hostname |
| 11584 | |
| 11585 | During an incoming SMTP session, this variable contains the value of the |
| 11586 | active host name, as specified by the smtp_active_hostname option. The |
| 11587 | value of $smtp_active_hostname is saved with any message that is received, |
| 11588 | so its value can be consulted during routing and delivery. |
| 11589 | |
| 11590 | $smtp_command |
| 11591 | |
| 11592 | During the processing of an incoming SMTP command, this variable contains |
| 11593 | the entire command. This makes it possible to distinguish between HELO and |
| 11594 | EHLO in the HELO ACL, and also to distinguish between commands such as |
| 11595 | these: |
| 11596 | |
| 11597 | MAIL FROM:<> |
| 11598 | MAIL FROM: <> |
| 11599 | |
| 11600 | For a MAIL command, extra parameters such as SIZE can be inspected. For a |
| 11601 | RCPT command, the address in $smtp_command is the original address before |
| 11602 | any rewriting, whereas the values in $local_part and $domain are taken from |
| 11603 | the address after SMTP-time rewriting. |
| 11604 | |
| 11605 | $smtp_command_argument |
| 11606 | |
| 11607 | While an ACL is running to check an SMTP command, this variable contains |
| 11608 | the argument, that is, the text that follows the command name, with leading |
| 11609 | white space removed. Following the introduction of $smtp_command, this |
| 11610 | variable is somewhat redundant, but is retained for backwards |
| 11611 | compatibility. |
| 11612 | |
| 11613 | $smtp_count_at_connection_start |
| 11614 | |
| 11615 | This variable is set greater than zero only in processes spawned by the |
| 11616 | Exim daemon for handling incoming SMTP connections. The name is |
| 11617 | deliberately long, in order to emphasize what the contents are. When the |
| 11618 | daemon accepts a new connection, it increments this variable. A copy of the |
| 11619 | variable is passed to the child process that handles the connection, but |
| 11620 | its value is fixed, and never changes. It is only an approximation of how |
| 11621 | many incoming connections there actually are, because many other |
| 11622 | connections may come and go while a single connection is being processed. |
| 11623 | When a child process terminates, the daemon decrements its copy of the |
| 11624 | variable. |
| 11625 | |
| 11626 | $sn0 - $sn9 |
| 11627 | |
| 11628 | These variables are copies of the values of the $n0 - $n9 accumulators that |
| 11629 | were current at the end of the system filter file. This allows a system |
| 11630 | filter file to set values that can be tested in users' filter files. For |
| 11631 | example, a system filter could set a value indicating how likely it is that |
| 11632 | a message is junk mail. |
| 11633 | |
| 11634 | $spam_xxx |
| 11635 | |
| 11636 | A number of variables whose names start with $spam are available when Exim |
| 11637 | is compiled with the content-scanning extension. For details, see section |
| 11638 | 44.2. |
| 11639 | |
| 11640 | $spool_directory |
| 11641 | |
| 11642 | The name of Exim's spool directory. |
| 11643 | |
| 11644 | $spool_inodes |
| 11645 | |
| 11646 | The number of free inodes in the disk partition where Exim's spool files |
| 11647 | are being written. The value is recalculated whenever the variable is |
| 11648 | referenced. If the relevant file system does not have the concept of |
| 11649 | inodes, the value of is -1. See also the check_spool_inodes option. |
| 11650 | |
| 11651 | $spool_space |
| 11652 | |
| 11653 | The amount of free space (as a number of kilobytes) in the disk partition |
| 11654 | where Exim's spool files are being written. The value is recalculated |
| 11655 | whenever the variable is referenced. If the operating system does not have |
| 11656 | the ability to find the amount of free space (only true for experimental |
| 11657 | systems), the space value is -1. For example, to check in an ACL that there |
| 11658 | is at least 50 megabytes free on the spool, you could write: |
| 11659 | |
| 11660 | condition = ${if > {$spool_space}{50000}} |
| 11661 | |
| 11662 | See also the check_spool_space option. |
| 11663 | |
| 11664 | $thisaddress |
| 11665 | |
| 11666 | This variable is set only during the processing of the foranyaddress |
| 11667 | command in a filter file. Its use is explained in the description of that |
| 11668 | command, which can be found in the separate document entitled Exim's |
| 11669 | interfaces to mail filtering. |
| 11670 | |
| 11671 | $tls_in_bits |
| 11672 | |
| 11673 | Contains an approximation of the TLS cipher's bit-strength on the inbound |
| 11674 | connection; the meaning of this depends upon the TLS implementation used. |
| 11675 | If TLS has not been negotiated, the value will be 0. The value of this is |
| 11676 | automatically fed into the Cyrus SASL authenticator when acting as a |
| 11677 | server, to specify the "external SSF" (a SASL term). |
| 11678 | |
| 11679 | The deprecated $tls_bits variable refers to the inbound side except when |
| 11680 | used in the context of an outbound SMTP delivery, when it refers to the |
| 11681 | outbound. |
| 11682 | |
| 11683 | $tls_out_bits |
| 11684 | |
| 11685 | Contains an approximation of the TLS cipher's bit-strength on an outbound |
| 11686 | SMTP connection; the meaning of this depends upon the TLS implementation |
| 11687 | used. If TLS has not been negotiated, the value will be 0. |
| 11688 | |
| 11689 | $tls_in_ourcert |
| 11690 | |
| 11691 | This variable refers to the certificate presented to the peer of an inbound |
| 11692 | connection when the message was received. It is only useful as the argument |
| 11693 | of a certextract expansion item, md5, sha1 or sha256 operator, or a def |
| 11694 | condition. |
| 11695 | |
| 11696 | $tls_in_peercert |
| 11697 | |
| 11698 | This variable refers to the certificate presented by the peer of an inbound |
| 11699 | connection when the message was received. It is only useful as the argument |
| 11700 | of a certextract expansion item, md5, sha1 or sha256 operator, or a def |
| 11701 | condition. If certificate verification fails it may refer to a failing |
| 11702 | chain element which is not the leaf. |
| 11703 | |
| 11704 | $tls_out_ourcert |
| 11705 | |
| 11706 | This variable refers to the certificate presented to the peer of an |
| 11707 | outbound connection. It is only useful as the argument of a certextract |
| 11708 | expansion item, md5, sha1 or sha256 operator, or a def condition. |
| 11709 | |
| 11710 | $tls_out_peercert |
| 11711 | |
| 11712 | This variable refers to the certificate presented by the peer of an |
| 11713 | outbound connection. It is only useful as the argument of a certextract |
| 11714 | expansion item, md5, sha1 or sha256 operator, or a def condition. If |
| 11715 | certificate verification fails it may refer to a failing chain element |
| 11716 | which is not the leaf. |
| 11717 | |
| 11718 | $tls_in_certificate_verified |
| 11719 | |
| 11720 | This variable is set to "1" if a TLS certificate was verified when the |
| 11721 | message was received, and "0" otherwise. |
| 11722 | |
| 11723 | The deprecated $tls_certificate_verified variable refers to the inbound |
| 11724 | side except when used in the context of an outbound SMTP delivery, when it |
| 11725 | refers to the outbound. |
| 11726 | |
| 11727 | $tls_out_certificate_verified |
| 11728 | |
| 11729 | This variable is set to "1" if a TLS certificate was verified when an |
| 11730 | outbound SMTP connection was made, and "0" otherwise. |
| 11731 | |
| 11732 | $tls_in_cipher |
| 11733 | |
| 11734 | When a message is received from a remote host over an encrypted SMTP |
| 11735 | connection, this variable is set to the cipher suite that was negotiated, |
| 11736 | for example DES-CBC3-SHA. In other circumstances, in particular, for |
| 11737 | message received over unencrypted connections, the variable is empty. |
| 11738 | Testing $tls_in_cipher for emptiness is one way of distinguishing between |
| 11739 | encrypted and non-encrypted connections during ACL processing. |
| 11740 | |
| 11741 | The deprecated $tls_cipher variable is the same as $tls_in_cipher during |
| 11742 | message reception, but in the context of an outward SMTP delivery taking |
| 11743 | place via the smtp transport becomes the same as $tls_out_cipher. |
| 11744 | |
| 11745 | $tls_out_cipher |
| 11746 | |
| 11747 | This variable is cleared before any outgoing SMTP connection is made, and |
| 11748 | then set to the outgoing cipher suite if one is negotiated. See chapter 42 |
| 11749 | for details of TLS support and chapter 30 for details of the smtp |
| 11750 | transport. |
| 11751 | |
| 11752 | $tls_in_ocsp |
| 11753 | |
| 11754 | When a message is received from a remote client connection the result of |
| 11755 | any OCSP request from the client is encoded in this variable: |
| 11756 | |
| 11757 | 0 OCSP proof was not requested (default value) |
| 11758 | 1 No response to request |
| 11759 | 2 Response not verified |
| 11760 | 3 Verification failed |
| 11761 | 4 Verification succeeded |
| 11762 | |
| 11763 | $tls_out_ocsp |
| 11764 | |
| 11765 | When a message is sent to a remote host connection the result of any OCSP |
| 11766 | request made is encoded in this variable. See $tls_in_ocsp for values. |
| 11767 | |
| 11768 | $tls_in_peerdn |
| 11769 | |
| 11770 | When a message is received from a remote host over an encrypted SMTP |
| 11771 | connection, and Exim is configured to request a certificate from the |
| 11772 | client, the value of the Distinguished Name of the certificate is made |
| 11773 | available in the $tls_in_peerdn during subsequent processing. If |
| 11774 | certificate verification fails it may refer to a failing chain element |
| 11775 | which is not the leaf. |
| 11776 | |
| 11777 | The deprecated $tls_peerdn variable refers to the inbound side except when |
| 11778 | used in the context of an outbound SMTP delivery, when it refers to the |
| 11779 | outbound. |
| 11780 | |
| 11781 | $tls_out_peerdn |
| 11782 | |
| 11783 | When a message is being delivered to a remote host over an encrypted SMTP |
| 11784 | connection, and Exim is configured to request a certificate from the |
| 11785 | server, the value of the Distinguished Name of the certificate is made |
| 11786 | available in the $tls_out_peerdn during subsequent processing. If |
| 11787 | certificate verification fails it may refer to a failing chain element |
| 11788 | which is not the leaf. |
| 11789 | |
| 11790 | $tls_in_sni |
| 11791 | |
| 11792 | When a TLS session is being established, if the client sends the Server |
| 11793 | Name Indication extension, the value will be placed in this variable. If |
| 11794 | the variable appears in tls_certificate then this option and some others, |
| 11795 | described in 42.10, will be re-expanded early in the TLS session, to permit |
| 11796 | a different certificate to be presented (and optionally a different key to |
| 11797 | be used) to the client, based upon the value of the SNI extension. |
| 11798 | |
| 11799 | The deprecated $tls_sni variable refers to the inbound side except when |
| 11800 | used in the context of an outbound SMTP delivery, when it refers to the |
| 11801 | outbound. |
| 11802 | |
| 11803 | $tls_out_sni |
| 11804 | |
| 11805 | During outbound SMTP deliveries, this variable reflects the value of the |
| 11806 | tls_sni option on the transport. |
| 11807 | |
| 11808 | $tod_bsdinbox |
| 11809 | |
| 11810 | The time of day and the date, in the format required for BSD-style mailbox |
| 11811 | files, for example: Thu Oct 17 17:14:09 1995. |
| 11812 | |
| 11813 | $tod_epoch |
| 11814 | |
| 11815 | The time and date as a number of seconds since the start of the Unix epoch. |
| 11816 | |
| 11817 | $tod_epoch_l |
| 11818 | |
| 11819 | The time and date as a number of microseconds since the start of the Unix |
| 11820 | epoch. |
| 11821 | |
| 11822 | $tod_full |
| 11823 | |
| 11824 | A full version of the time and date, for example: Wed, 16 Oct 1995 09:51:40 |
| 11825 | +0100. The timezone is always given as a numerical offset from UTC, with |
| 11826 | positive values used for timezones that are ahead (east) of UTC, and |
| 11827 | negative values for those that are behind (west). |
| 11828 | |
| 11829 | $tod_log |
| 11830 | |
| 11831 | The time and date in the format used for writing Exim's log files, for |
| 11832 | example: 1995-10-12 15:32:29, but without a timezone. |
| 11833 | |
| 11834 | $tod_logfile |
| 11835 | |
| 11836 | This variable contains the date in the format yyyymmdd. This is the format |
| 11837 | that is used for datestamping log files when log_file_path contains the |
| 11838 | "%D" flag. |
| 11839 | |
| 11840 | $tod_zone |
| 11841 | |
| 11842 | This variable contains the numerical value of the local timezone, for |
| 11843 | example: -0500. |
| 11844 | |
| 11845 | $tod_zulu |
| 11846 | |
| 11847 | This variable contains the UTC date and time in "Zulu" format, as specified |
| 11848 | by ISO 8601, for example: 20030221154023Z. |
| 11849 | |
| 11850 | $transport_name |
| 11851 | |
| 11852 | During the running of a transport, this variable contains its name. |
| 11853 | |
| 11854 | $value |
| 11855 | |
| 11856 | This variable contains the result of an expansion lookup, extraction |
| 11857 | operation, or external command, as described above. It is also used during |
| 11858 | a reduce expansion. |
| 11859 | |
| 11860 | $verify_mode |
| 11861 | |
| 11862 | While a router or transport is being run in verify mode or for cutthrough |
| 11863 | delivery, contains "S" for sender-verification or "R" for |
| 11864 | recipient-verification. Otherwise, empty. |
| 11865 | |
| 11866 | $version_number |
| 11867 | |
| 11868 | The version number of Exim. |
| 11869 | |
| 11870 | $warn_message_delay |
| 11871 | |
| 11872 | This variable is set only during the creation of a message warning about a |
| 11873 | delivery delay. Details of its use are explained in section 49.2. |
| 11874 | |
| 11875 | $warn_message_recipients |
| 11876 | |
| 11877 | This variable is set only during the creation of a message warning about a |
| 11878 | delivery delay. Details of its use are explained in section 49.2. |
| 11879 | |
| 11880 | |
| 11881 | |
| 11882 | =============================================================================== |
| 11883 | 12. EMBEDDED PERL |
| 11884 | |
| 11885 | Exim can be built to include an embedded Perl interpreter. When this is done, |
| 11886 | Perl subroutines can be called as part of the string expansion process. To make |
| 11887 | use of the Perl support, you need version 5.004 or later of Perl installed on |
| 11888 | your system. To include the embedded interpreter in the Exim binary, include |
| 11889 | the line |
| 11890 | |
| 11891 | EXIM_PERL = perl.o |
| 11892 | |
| 11893 | in your Local/Makefile and then build Exim in the normal way. |
| 11894 | |
| 11895 | |
| 11896 | 12.1 Setting up so Perl can be used |
| 11897 | ----------------------------------- |
| 11898 | |
| 11899 | Access to Perl subroutines is via a global configuration option called |
| 11900 | perl_startup and an expansion string operator ${perl ...}. If there is no |
| 11901 | perl_startup option in the Exim configuration file then no Perl interpreter is |
| 11902 | started and there is almost no overhead for Exim (since none of the Perl |
| 11903 | library will be paged in unless used). If there is a perl_startup option then |
| 11904 | the associated value is taken to be Perl code which is executed in a newly |
| 11905 | created Perl interpreter. |
| 11906 | |
| 11907 | The value of perl_startup is not expanded in the Exim sense, so you do not need |
| 11908 | backslashes before any characters to escape special meanings. The option should |
| 11909 | usually be something like |
| 11910 | |
| 11911 | perl_startup = do '/etc/exim.pl' |
| 11912 | |
| 11913 | where /etc/exim.pl is Perl code which defines any subroutines you want to use |
| 11914 | from Exim. Exim can be configured either to start up a Perl interpreter as soon |
| 11915 | as it is entered, or to wait until the first time it is needed. Starting the |
| 11916 | interpreter at the beginning ensures that it is done while Exim still has its |
| 11917 | setuid privilege, but can impose an unnecessary overhead if Perl is not in fact |
| 11918 | used in a particular run. Also, note that this does not mean that Exim is |
| 11919 | necessarily running as root when Perl is called at a later time. By default, |
| 11920 | the interpreter is started only when it is needed, but this can be changed in |
| 11921 | two ways: |
| 11922 | |
| 11923 | * Setting perl_at_start (a boolean option) in the configuration requests a |
| 11924 | startup when Exim is entered. |
| 11925 | |
| 11926 | * The command line option -ps also requests a startup when Exim is entered, |
| 11927 | overriding the setting of perl_at_start. |
| 11928 | |
| 11929 | There is also a command line option -pd (for delay) which suppresses the |
| 11930 | initial startup, even if perl_at_start is set. |
| 11931 | |
| 11932 | * To provide more security executing Perl code via the embedded Perl |
| 11933 | interpreter, the perl_taintmode option can be set. This enables the taint |
| 11934 | mode of the Perl interpreter. You are encouraged to set this option to a |
| 11935 | true value. To avoid breaking existing installations, it defaults to false. |
| 11936 | |
| 11937 | |
| 11938 | 12.2 Calling Perl subroutines |
| 11939 | ----------------------------- |
| 11940 | |
| 11941 | When the configuration file includes a perl_startup option you can make use of |
| 11942 | the string expansion item to call the Perl subroutines that are defined by the |
| 11943 | perl_startup code. The operator is used in any of the following forms: |
| 11944 | |
| 11945 | ${perl{foo}} |
| 11946 | ${perl{foo}{argument}} |
| 11947 | ${perl{foo}{argument1}{argument2} ... } |
| 11948 | |
| 11949 | which calls the subroutine foo with the given arguments. A maximum of eight |
| 11950 | arguments may be passed. Passing more than this results in an expansion failure |
| 11951 | with an error message of the form |
| 11952 | |
| 11953 | Too many arguments passed to Perl subroutine "foo" (max is 8) |
| 11954 | |
| 11955 | The return value of the Perl subroutine is evaluated in a scalar context before |
| 11956 | it is passed back to Exim to be inserted into the expanded string. If the |
| 11957 | return value is undef, the expansion is forced to fail in the same way as an |
| 11958 | explicit "fail" on an if or lookup item. If the subroutine aborts by obeying |
| 11959 | Perl's die function, the expansion fails with the error message that was passed |
| 11960 | to die. |
| 11961 | |
| 11962 | |
| 11963 | 12.3 Calling Exim functions from Perl |
| 11964 | ------------------------------------- |
| 11965 | |
| 11966 | Within any Perl code called from Exim, the function Exim::expand_string() is |
| 11967 | available to call back into Exim's string expansion function. For example, the |
| 11968 | Perl code |
| 11969 | |
| 11970 | my $lp = Exim::expand_string('$local_part'); |
| 11971 | |
| 11972 | makes the current Exim $local_part available in the Perl variable $lp. Note |
| 11973 | those are single quotes and not double quotes to protect against $local_part |
| 11974 | being interpolated as a Perl variable. |
| 11975 | |
| 11976 | If the string expansion is forced to fail by a "fail" item, the result of |
| 11977 | Exim::expand_string() is undef. If there is a syntax error in the expansion |
| 11978 | string, the Perl call from the original expansion string fails with an |
| 11979 | appropriate error message, in the same way as if die were used. |
| 11980 | |
| 11981 | Two other Exim functions are available for use from within Perl code. |
| 11982 | Exim::debug_write() writes a string to the standard error stream if Exim's |
| 11983 | debugging is enabled. If you want a newline at the end, you must supply it. |
| 11984 | Exim::log_write() writes a string to Exim's main log, adding a leading |
| 11985 | timestamp. In this case, you should not supply a terminating newline. |
| 11986 | |
| 11987 | |
| 11988 | 12.4 Use of standard output and error by Perl |
| 11989 | --------------------------------------------- |
| 11990 | |
| 11991 | You should not write to the standard error or output streams from within your |
| 11992 | Perl code, as it is not defined how these are set up. In versions of Exim |
| 11993 | before 4.50, it is possible for the standard output or error to refer to the |
| 11994 | SMTP connection during message reception via the daemon. Writing to this stream |
| 11995 | is certain to cause chaos. From Exim 4.50 onwards, the standard output and |
| 11996 | error streams are connected to /dev/null in the daemon. The chaos is avoided, |
| 11997 | but the output is lost. |
| 11998 | |
| 11999 | The Perl warn statement writes to the standard error stream by default. Calls |
| 12000 | to warn may be embedded in Perl modules that you use, but over which you have |
| 12001 | no control. When Exim starts up the Perl interpreter, it arranges for output |
| 12002 | from the warn statement to be written to the Exim main log. You can change this |
| 12003 | by including appropriate Perl magic somewhere in your Perl code. For example, |
| 12004 | to discard warn output completely, you need this: |
| 12005 | |
| 12006 | $SIG{__WARN__} = sub { }; |
| 12007 | |
| 12008 | Whenever a warn is obeyed, the anonymous subroutine is called. In this example, |
| 12009 | the code for the subroutine is empty, so it does nothing, but you can include |
| 12010 | any Perl code that you like. The text of the warn message is passed as the |
| 12011 | first subroutine argument. |
| 12012 | |
| 12013 | |
| 12014 | |
| 12015 | =============================================================================== |
| 12016 | 13. STARTING THE DAEMON AND THE USE OF NETWORK INTERFACES |
| 12017 | |
| 12018 | A host that is connected to a TCP/IP network may have one or more physical |
| 12019 | hardware network interfaces. Each of these interfaces may be configured as one |
| 12020 | or more "logical" interfaces, which are the entities that a program actually |
| 12021 | works with. Each of these logical interfaces is associated with an IP address. |
| 12022 | In addition, TCP/IP software supports "loopback" interfaces (127.0.0.1 in IPv4 |
| 12023 | and ::1 in IPv6), which do not use any physical hardware. Exim requires |
| 12024 | knowledge about the host's interfaces for use in three different circumstances: |
| 12025 | |
| 12026 | 1. When a listening daemon is started, Exim needs to know which interfaces and |
| 12027 | ports to listen on. |
| 12028 | |
| 12029 | 2. When Exim is routing an address, it needs to know which IP addresses are |
| 12030 | associated with local interfaces. This is required for the correct |
| 12031 | processing of MX lists by removing the local host and others with the same |
| 12032 | or higher priority values. Also, Exim needs to detect cases when an address |
| 12033 | is routed to an IP address that in fact belongs to the local host. Unless |
| 12034 | the self router option or the allow_localhost option of the smtp transport |
| 12035 | is set (as appropriate), this is treated as an error situation. |
| 12036 | |
| 12037 | 3. When Exim connects to a remote host, it may need to know which interface to |
| 12038 | use for the outgoing connection. |
| 12039 | |
| 12040 | Exim's default behaviour is likely to be appropriate in the vast majority of |
| 12041 | cases. If your host has only one interface, and you want all its IP addresses |
| 12042 | to be treated in the same way, and you are using only the standard SMTP port, |
| 12043 | you should not need to take any special action. The rest of this chapter does |
| 12044 | not apply to you. |
| 12045 | |
| 12046 | In a more complicated situation you may want to listen only on certain |
| 12047 | interfaces, or on different ports, and for this reason there are a number of |
| 12048 | options that can be used to influence Exim's behaviour. The rest of this |
| 12049 | chapter describes how they operate. |
| 12050 | |
| 12051 | When a message is received over TCP/IP, the interface and port that were |
| 12052 | actually used are set in $received_ip_address and $received_port. |
| 12053 | |
| 12054 | |
| 12055 | 13.1 Starting a listening daemon |
| 12056 | -------------------------------- |
| 12057 | |
| 12058 | When a listening daemon is started (by means of the -bd command line option), |
| 12059 | the interfaces and ports on which it listens are controlled by the following |
| 12060 | options: |
| 12061 | |
| 12062 | * daemon_smtp_ports contains a list of default ports or service names. (For |
| 12063 | backward compatibility, this option can also be specified in the singular.) |
| 12064 | |
| 12065 | * local_interfaces contains list of interface IP addresses on which to |
| 12066 | listen. Each item may optionally also specify a port. |
| 12067 | |
| 12068 | The default list separator in both cases is a colon, but this can be changed as |
| 12069 | described in section 6.20. When IPv6 addresses are involved, it is usually best |
| 12070 | to change the separator to avoid having to double all the colons. For example: |
| 12071 | |
| 12072 | local_interfaces = <; 127.0.0.1 ; \ |
| 12073 | 192.168.23.65 ; \ |
| 12074 | ::1 ; \ |
| 12075 | 3ffe:ffff:836f::fe86:a061 |
| 12076 | |
| 12077 | There are two different formats for specifying a port along with an IP address |
| 12078 | in local_interfaces: |
| 12079 | |
| 12080 | 1. The port is added onto the address with a dot separator. For example, to |
| 12081 | listen on port 1234 on two different IP addresses: |
| 12082 | |
| 12083 | local_interfaces = <; 192.168.23.65.1234 ; \ |
| 12084 | 3ffe:ffff:836f::fe86:a061.1234 |
| 12085 | |
| 12086 | 2. The IP address is enclosed in square brackets, and the port is added with a |
| 12087 | colon separator, for example: |
| 12088 | |
| 12089 | local_interfaces = <; [192.168.23.65]:1234 ; \ |
| 12090 | [3ffe:ffff:836f::fe86:a061]:1234 |
| 12091 | |
| 12092 | When a port is not specified, the value of daemon_smtp_ports is used. The |
| 12093 | default setting contains just one port: |
| 12094 | |
| 12095 | daemon_smtp_ports = smtp |
| 12096 | |
| 12097 | If more than one port is listed, each interface that does not have its own port |
| 12098 | specified listens on all of them. Ports that are listed in daemon_smtp_ports |
| 12099 | can be identified either by name (defined in /etc/services) or by number. |
| 12100 | However, when ports are given with individual IP addresses in local_interfaces, |
| 12101 | only numbers (not names) can be used. |
| 12102 | |
| 12103 | |
| 12104 | 13.2 Special IP listening addresses |
| 12105 | ----------------------------------- |
| 12106 | |
| 12107 | The addresses 0.0.0.0 and ::0 are treated specially. They are interpreted as |
| 12108 | "all IPv4 interfaces" and "all IPv6 interfaces", respectively. In each case, |
| 12109 | Exim tells the TCP/IP stack to "listen on all IPvx interfaces" instead of |
| 12110 | setting up separate listening sockets for each interface. The default value of |
| 12111 | local_interfaces is |
| 12112 | |
| 12113 | local_interfaces = 0.0.0.0 |
| 12114 | |
| 12115 | when Exim is built without IPv6 support; otherwise it is: |
| 12116 | |
| 12117 | local_interfaces = <; ::0 ; 0.0.0.0 |
| 12118 | |
| 12119 | Thus, by default, Exim listens on all available interfaces, on the SMTP port. |
| 12120 | |
| 12121 | |
| 12122 | 13.3 Overriding local_interfaces and daemon_smtp_ports |
| 12123 | ------------------------------------------------------ |
| 12124 | |
| 12125 | The -oX command line option can be used to override the values of |
| 12126 | daemon_smtp_ports and/or local_interfaces for a particular daemon instance. |
| 12127 | Another way of doing this would be to use macros and the -D option. However, |
| 12128 | -oX can be used by any admin user, whereas modification of the runtime |
| 12129 | configuration by -D is allowed only when the caller is root or exim. |
| 12130 | |
| 12131 | The value of -oX is a list of items. The default colon separator can be changed |
| 12132 | in the usual way if required. If there are any items that do not contain dots |
| 12133 | or colons (that is, are not IP addresses), the value of daemon_smtp_ports is |
| 12134 | replaced by the list of those items. If there are any items that do contain |
| 12135 | dots or colons, the value of local_interfaces is replaced by those items. Thus, |
| 12136 | for example, |
| 12137 | |
| 12138 | -oX 1225 |
| 12139 | |
| 12140 | overrides daemon_smtp_ports, but leaves local_interfaces unchanged, whereas |
| 12141 | |
| 12142 | -oX 192.168.34.5.1125 |
| 12143 | |
| 12144 | overrides local_interfaces, leaving daemon_smtp_ports unchanged. (However, |
| 12145 | since local_interfaces now contains no items without ports, the value of |
| 12146 | daemon_smtp_ports is no longer relevant in this example.) |
| 12147 | |
| 12148 | |
| 12149 | 13.4 Support for the obsolete SSMTP (or SMTPS) protocol |
| 12150 | ------------------------------------------------------- |
| 12151 | |
| 12152 | Exim supports the obsolete SSMTP protocol (also known as SMTPS) that was used |
| 12153 | before the STARTTLS command was standardized for SMTP. Some legacy clients |
| 12154 | still use this protocol. If the tls_on_connect_ports option is set to a list of |
| 12155 | port numbers or service names, connections to those ports must use SSMTP. The |
| 12156 | most common use of this option is expected to be |
| 12157 | |
| 12158 | tls_on_connect_ports = 465 |
| 12159 | |
| 12160 | because 465 is the usual port number used by the legacy clients. There is also |
| 12161 | a command line option -tls-on-connect, which forces all ports to behave in this |
| 12162 | way when a daemon is started. |
| 12163 | |
| 12164 | Warning: Setting tls_on_connect_ports does not of itself cause the daemon to |
| 12165 | listen on those ports. You must still specify them in daemon_smtp_ports, |
| 12166 | local_interfaces, or the -oX option. (This is because tls_on_connect_ports |
| 12167 | applies to inetd connections as well as to connections via the daemon.) |
| 12168 | |
| 12169 | |
| 12170 | 13.5 IPv6 address scopes |
| 12171 | ------------------------ |
| 12172 | |
| 12173 | IPv6 addresses have "scopes", and a host with multiple hardware interfaces can, |
| 12174 | in principle, have the same link-local IPv6 address on different interfaces. |
| 12175 | Thus, additional information is needed, over and above the IP address, to |
| 12176 | distinguish individual interfaces. A convention of using a percent sign |
| 12177 | followed by something (often the interface name) has been adopted in some |
| 12178 | cases, leading to addresses like this: |
| 12179 | |
| 12180 | fe80::202:b3ff:fe03:45c1%eth0 |
| 12181 | |
| 12182 | To accommodate this usage, a percent sign followed by an arbitrary string is |
| 12183 | allowed at the end of an IPv6 address. By default, Exim calls getaddrinfo() to |
| 12184 | convert a textual IPv6 address for actual use. This function recognizes the |
| 12185 | percent convention in operating systems that support it, and it processes the |
| 12186 | address appropriately. Unfortunately, some older libraries have problems with |
| 12187 | getaddrinfo(). If |
| 12188 | |
| 12189 | IPV6_USE_INET_PTON=yes |
| 12190 | |
| 12191 | is set in Local/Makefile (or an OS-dependent Makefile) when Exim is built, Exim |
| 12192 | uses inet_pton() to convert a textual IPv6 address for actual use, instead of |
| 12193 | getaddrinfo(). (Before version 4.14, it always used this function.) Of course, |
| 12194 | this means that the additional functionality of getaddrinfo() - recognizing |
| 12195 | scoped addresses - is lost. |
| 12196 | |
| 12197 | |
| 12198 | 13.6 Disabling IPv6 |
| 12199 | ------------------- |
| 12200 | |
| 12201 | Sometimes it happens that an Exim binary that was compiled with IPv6 support is |
| 12202 | run on a host whose kernel does not support IPv6. The binary will fall back to |
| 12203 | using IPv4, but it may waste resources looking up AAAA records, and trying to |
| 12204 | connect to IPv6 addresses, causing delays to mail delivery. If you set the |
| 12205 | disable_ipv6 option true, even if the Exim binary has IPv6 support, no IPv6 |
| 12206 | activities take place. AAAA records are never looked up, and any IPv6 addresses |
| 12207 | that are listed in local_interfaces, data for the manualroute router, etc. are |
| 12208 | ignored. If IP literals are enabled, the ipliteral router declines to handle |
| 12209 | IPv6 literal addresses. |
| 12210 | |
| 12211 | On the other hand, when IPv6 is in use, there may be times when you want to |
| 12212 | disable it for certain hosts or domains. You can use the dns_ipv4_lookup option |
| 12213 | to globally suppress the lookup of AAAA records for specified domains, and you |
| 12214 | can use the ignore_target_hosts generic router option to ignore IPv6 addresses |
| 12215 | in an individual router. |
| 12216 | |
| 12217 | |
| 12218 | 13.7 Examples of starting a listening daemon |
| 12219 | -------------------------------------------- |
| 12220 | |
| 12221 | The default case in an IPv6 environment is |
| 12222 | |
| 12223 | daemon_smtp_ports = smtp |
| 12224 | local_interfaces = <; ::0 ; 0.0.0.0 |
| 12225 | |
| 12226 | This specifies listening on the smtp port on all IPv6 and IPv4 interfaces. |
| 12227 | Either one or two sockets may be used, depending on the characteristics of the |
| 12228 | TCP/IP stack. (This is complicated and messy; for more information, read the |
| 12229 | comments in the daemon.c source file.) |
| 12230 | |
| 12231 | To specify listening on ports 25 and 26 on all interfaces: |
| 12232 | |
| 12233 | daemon_smtp_ports = 25 : 26 |
| 12234 | |
| 12235 | (leaving local_interfaces at the default setting) or, more explicitly: |
| 12236 | |
| 12237 | local_interfaces = <; ::0.25 ; ::0.26 \ |
| 12238 | 0.0.0.0.25 ; 0.0.0.0.26 |
| 12239 | |
| 12240 | To listen on the default port on all IPv4 interfaces, and on port 26 on the |
| 12241 | IPv4 loopback address only: |
| 12242 | |
| 12243 | local_interfaces = 0.0.0.0 : 127.0.0.1.26 |
| 12244 | |
| 12245 | To specify listening on the default port on specific interfaces only: |
| 12246 | |
| 12247 | local_interfaces = 10.0.0.67 : 192.168.34.67 |
| 12248 | |
| 12249 | Warning: Such a setting excludes listening on the loopback interfaces. |
| 12250 | |
| 12251 | |
| 12252 | 13.8 Recognizing the local host |
| 12253 | ------------------------------- |
| 12254 | |
| 12255 | The local_interfaces option is also used when Exim needs to determine whether |
| 12256 | or not an IP address refers to the local host. That is, the IP addresses of all |
| 12257 | the interfaces on which a daemon is listening are always treated as local. |
| 12258 | |
| 12259 | For this usage, port numbers in local_interfaces are ignored. If either of the |
| 12260 | items 0.0.0.0 or ::0 are encountered, Exim gets a complete list of available |
| 12261 | interfaces from the operating system, and extracts the relevant (that is, IPv4 |
| 12262 | or IPv6) addresses to use for checking. |
| 12263 | |
| 12264 | Some systems set up large numbers of virtual interfaces in order to provide |
| 12265 | many virtual web servers. In this situation, you may want to listen for email |
| 12266 | on only a few of the available interfaces, but nevertheless treat all |
| 12267 | interfaces as local when routing. You can do this by setting |
| 12268 | extra_local_interfaces to a list of IP addresses, possibly including the "all" |
| 12269 | wildcard values. These addresses are recognized as local, but are not used for |
| 12270 | listening. Consider this example: |
| 12271 | |
| 12272 | local_interfaces = <; 127.0.0.1 ; ::1 ; \ |
| 12273 | 192.168.53.235 ; \ |
| 12274 | 3ffe:2101:12:1:a00:20ff:fe86:a061 |
| 12275 | |
| 12276 | extra_local_interfaces = <; ::0 ; 0.0.0.0 |
| 12277 | |
| 12278 | The daemon listens on the loopback interfaces and just one IPv4 and one IPv6 |
| 12279 | address, but all available interface addresses are treated as local when Exim |
| 12280 | is routing. |
| 12281 | |
| 12282 | In some environments the local host name may be in an MX list, but with an IP |
| 12283 | address that is not assigned to any local interface. In other cases it may be |
| 12284 | desirable to treat other host names as if they referred to the local host. Both |
| 12285 | these cases can be handled by setting the hosts_treat_as_local option. This |
| 12286 | contains host names rather than IP addresses. When a host is referenced during |
| 12287 | routing, either via an MX record or directly, it is treated as the local host |
| 12288 | if its name matches hosts_treat_as_local, or if any of its IP addresses match |
| 12289 | local_interfaces or extra_local_interfaces. |
| 12290 | |
| 12291 | |
| 12292 | 13.9 Delivering to a remote host |
| 12293 | -------------------------------- |
| 12294 | |
| 12295 | Delivery to a remote host is handled by the smtp transport. By default, it |
| 12296 | allows the system's TCP/IP functions to choose which interface to use (if there |
| 12297 | is more than one) when connecting to a remote host. However, the interface |
| 12298 | option can be set to specify which interface is used. See the description of |
| 12299 | the smtp transport in chapter 30 for more details. |
| 12300 | |
| 12301 | |
| 12302 | |
| 12303 | =============================================================================== |
| 12304 | 14. MAIN CONFIGURATION |
| 12305 | |
| 12306 | The first part of the run time configuration file contains three types of item: |
| 12307 | |
| 12308 | * Macro definitions: These lines start with an upper case letter. See section |
| 12309 | 6.4 for details of macro processing. |
| 12310 | |
| 12311 | * Named list definitions: These lines start with one of the words |
| 12312 | "domainlist", "hostlist", "addresslist", or "localpartlist". Their use is |
| 12313 | described in section 10.5. |
| 12314 | |
| 12315 | * Main configuration settings: Each setting occupies one line of the file |
| 12316 | (with possible continuations). If any setting is preceded by the word |
| 12317 | "hide", the -bP command line option displays its value to admin users only. |
| 12318 | See section 6.11 for a description of the syntax of these option settings. |
| 12319 | |
| 12320 | This chapter specifies all the main configuration options, along with their |
| 12321 | types and default values. For ease of finding a particular option, they appear |
| 12322 | in alphabetical order in section 14.23 below. However, because there are now so |
| 12323 | many options, they are first listed briefly in functional groups, as an aid to |
| 12324 | finding the name of the option you are looking for. Some options are listed in |
| 12325 | more than one group. |
| 12326 | |
| 12327 | |
| 12328 | 14.1 Miscellaneous |
| 12329 | ------------------ |
| 12330 | |
| 12331 | bi_command to run for -bi command line option |
| 12332 | debug_store do extra internal checks |
| 12333 | disable_ipv6 do no IPv6 processing |
| 12334 | keep_malformed for broken files - should not happen |
| 12335 | localhost_number for unique message ids in clusters |
| 12336 | message_body_newlines retain newlines in $message_body |
| 12337 | message_body_visible how much to show in $message_body |
| 12338 | mua_wrapper run in "MUA wrapper" mode |
| 12339 | print_topbitchars top-bit characters are printing |
| 12340 | timezone force time zone |
| 12341 | |
| 12342 | |
| 12343 | 14.2 Exim parameters |
| 12344 | -------------------- |
| 12345 | |
| 12346 | exim_group override compiled-in value |
| 12347 | exim_path override compiled-in value |
| 12348 | exim_user override compiled-in value |
| 12349 | primary_hostname default from uname() |
| 12350 | split_spool_directory use multiple directories |
| 12351 | spool_directory override compiled-in value |
| 12352 | |
| 12353 | |
| 12354 | 14.3 Privilege controls |
| 12355 | ----------------------- |
| 12356 | |
| 12357 | admin_groups groups that are Exim admin users |
| 12358 | deliver_drop_privilege drop root for delivery processes |
| 12359 | local_from_check insert Sender: if necessary |
| 12360 | local_from_prefix for testing From: for local sender |
| 12361 | local_from_suffix for testing From: for local sender |
| 12362 | local_sender_retain keep Sender: from untrusted user |
| 12363 | never_users do not run deliveries as these |
| 12364 | prod_requires_admin forced delivery requires admin user |
| 12365 | queue_list_requires_admin queue listing requires admin user |
| 12366 | trusted_groups groups that are trusted |
| 12367 | trusted_users users that are trusted |
| 12368 | |
| 12369 | |
| 12370 | 14.4 Logging |
| 12371 | ------------ |
| 12372 | |
| 12373 | event_action custom logging |
| 12374 | hosts_connection_nolog exemption from connect logging |
| 12375 | log_file_path override compiled-in value |
| 12376 | log_selector set/unset optional logging |
| 12377 | log_timezone add timezone to log lines |
| 12378 | message_logs create per-message logs |
| 12379 | preserve_message_logs after message completion |
| 12380 | process_log_path for SIGUSR1 and exiwhat |
| 12381 | slow_lookup_log control logging of slow DNS lookups |
| 12382 | syslog_duplication controls duplicate log lines on syslog |
| 12383 | syslog_facility set syslog "facility" field |
| 12384 | syslog_pid pid in syslog lines |
| 12385 | syslog_processname set syslog "ident" field |
| 12386 | syslog_timestamp timestamp syslog lines |
| 12387 | write_rejectlog control use of message log |
| 12388 | |
| 12389 | |
| 12390 | 14.5 Frozen messages |
| 12391 | -------------------- |
| 12392 | |
| 12393 | auto_thaw sets time for retrying frozen messages |
| 12394 | freeze_tell send message when freezing |
| 12395 | move_frozen_messages to another directory |
| 12396 | timeout_frozen_after keep frozen messages only so long |
| 12397 | |
| 12398 | |
| 12399 | 14.6 Data lookups |
| 12400 | ----------------- |
| 12401 | |
| 12402 | ibase_servers InterBase servers |
| 12403 | ldap_ca_cert_dir dir of CA certs to verify LDAP server's |
| 12404 | ldap_ca_cert_file file of CA certs to verify LDAP server's |
| 12405 | ldap_cert_file client cert file for LDAP |
| 12406 | ldap_cert_key client key file for LDAP |
| 12407 | ldap_cipher_suite TLS negotiation preference control |
| 12408 | ldap_default_servers used if no server in query |
| 12409 | ldap_require_cert action to take without LDAP server cert |
| 12410 | ldap_start_tls require TLS within LDAP |
| 12411 | ldap_version set protocol version |
| 12412 | lookup_open_max lookup files held open |
| 12413 | mysql_servers default MySQL servers |
| 12414 | oracle_servers Oracle servers |
| 12415 | pgsql_servers default PostgreSQL servers |
| 12416 | sqlite_lock_timeout as it says |
| 12417 | |
| 12418 | |
| 12419 | 14.7 Message ids |
| 12420 | ---------------- |
| 12421 | |
| 12422 | message_id_header_domain used to build Message-ID: header |
| 12423 | message_id_header_text ditto |
| 12424 | |
| 12425 | |
| 12426 | 14.8 Embedded Perl Startup |
| 12427 | -------------------------- |
| 12428 | |
| 12429 | perl_at_start always start the interpreter |
| 12430 | perl_startup code to obey when starting Perl |
| 12431 | perl_taintmode enable taint mode in Perl |
| 12432 | |
| 12433 | |
| 12434 | 14.9 Daemon |
| 12435 | ----------- |
| 12436 | |
| 12437 | daemon_smtp_ports default ports |
| 12438 | daemon_startup_retries number of times to retry |
| 12439 | daemon_startup_sleep time to sleep between tries |
| 12440 | extra_local_interfaces not necessarily listened on |
| 12441 | local_interfaces on which to listen, with optional ports |
| 12442 | pid_file_path override compiled-in value |
| 12443 | queue_run_max maximum simultaneous queue runners |
| 12444 | |
| 12445 | |
| 12446 | 14.10 Resource control |
| 12447 | ---------------------- |
| 12448 | |
| 12449 | check_log_inodes before accepting a message |
| 12450 | check_log_space before accepting a message |
| 12451 | check_spool_inodes before accepting a message |
| 12452 | check_spool_space before accepting a message |
| 12453 | deliver_queue_load_max no queue deliveries if load high |
| 12454 | queue_only_load queue incoming if load high |
| 12455 | queue_only_load_latch don't re-evaluate load for each message |
| 12456 | queue_run_max maximum simultaneous queue runners |
| 12457 | remote_max_parallel parallel SMTP delivery per message |
| 12458 | smtp_accept_max simultaneous incoming connections |
| 12459 | smtp_accept_max_nonmail non-mail commands |
| 12460 | smtp_accept_max_nonmail_hosts hosts to which the limit applies |
| 12461 | smtp_accept_max_per_connection messages per connection |
| 12462 | smtp_accept_max_per_host connections from one host |
| 12463 | smtp_accept_queue queue mail if more connections |
| 12464 | smtp_accept_queue_per_connection queue if more messages per connection |
| 12465 | smtp_accept_reserve only reserve hosts if more connections |
| 12466 | smtp_check_spool_space from SIZE on MAIL command |
| 12467 | smtp_connect_backlog passed to TCP/IP stack |
| 12468 | smtp_load_reserve SMTP from reserved hosts if load high |
| 12469 | smtp_reserve_hosts these are the reserve hosts |
| 12470 | |
| 12471 | |
| 12472 | 14.11 Policy controls |
| 12473 | --------------------- |
| 12474 | |
| 12475 | acl_not_smtp ACL for non-SMTP messages |
| 12476 | acl_not_smtp_mime ACL for non-SMTP MIME parts |
| 12477 | acl_not_smtp_start ACL for start of non-SMTP message |
| 12478 | acl_smtp_auth ACL for AUTH |
| 12479 | acl_smtp_connect ACL for connection |
| 12480 | acl_smtp_data ACL for DATA |
| 12481 | acl_smtp_data_prdr ACL for DATA, per-recipient |
| 12482 | acl_smtp_dkim ACL for DKIM verification |
| 12483 | acl_smtp_etrn ACL for ETRN |
| 12484 | acl_smtp_expn ACL for EXPN |
| 12485 | acl_smtp_helo ACL for EHLO or HELO |
| 12486 | acl_smtp_mail ACL for MAIL |
| 12487 | acl_smtp_mailauth ACL for AUTH on MAIL command |
| 12488 | acl_smtp_mime ACL for MIME parts |
| 12489 | acl_smtp_notquit ACL for non-QUIT terminations |
| 12490 | acl_smtp_predata ACL for start of data |
| 12491 | acl_smtp_quit ACL for QUIT |
| 12492 | acl_smtp_rcpt ACL for RCPT |
| 12493 | acl_smtp_starttls ACL for STARTTLS |
| 12494 | acl_smtp_vrfy ACL for VRFY |
| 12495 | av_scanner specify virus scanner |
| 12496 | check_rfc2047_length check length of RFC 2047 "encoded words" |
| 12497 | dns_csa_search_limit control CSA parent search depth |
| 12498 | dns_csa_use_reverse en/disable CSA IP reverse search |
| 12499 | header_maxsize total size of message header |
| 12500 | header_line_maxsize individual header line limit |
| 12501 | helo_accept_junk_hosts allow syntactic junk from these hosts |
| 12502 | helo_allow_chars allow illegal chars in HELO names |
| 12503 | helo_lookup_domains lookup hostname for these HELO names |
| 12504 | helo_try_verify_hosts HELO soft-checked for these hosts |
| 12505 | helo_verify_hosts HELO hard-checked for these hosts |
| 12506 | host_lookup host name looked up for these hosts |
| 12507 | host_lookup_order order of DNS and local name lookups |
| 12508 | hosts_proxy use proxy protocol for these hosts |
| 12509 | host_reject_connection reject connection from these hosts |
| 12510 | hosts_treat_as_local useful in some cluster configurations |
| 12511 | local_scan_timeout timeout for local_scan() |
| 12512 | message_size_limit for all messages |
| 12513 | percent_hack_domains recognize %-hack for these domains |
| 12514 | spamd_address set interface to SpamAssassin |
| 12515 | strict_acl_vars object to unset ACL variables |
| 12516 | |
| 12517 | |
| 12518 | 14.12 Callout cache |
| 12519 | ------------------- |
| 12520 | |
| 12521 | callout_domain_negative_expire timeout for negative domain cache item |
| 12522 | callout_domain_positive_expire timeout for positive domain cache item |
| 12523 | callout_negative_expire timeout for negative address cache item |
| 12524 | callout_positive_expire timeout for positive address cache item |
| 12525 | callout_random_local_part string to use for "random" testing |
| 12526 | |
| 12527 | |
| 12528 | 14.13 TLS |
| 12529 | --------- |
| 12530 | |
| 12531 | gnutls_compat_mode use GnuTLS compatibility mode |
| 12532 | gnutls_allow_auto_pkcs11 allow GnuTLS to autoload PKCS11 modules |
| 12533 | openssl_options adjust OpenSSL compatibility options |
| 12534 | tls_advertise_hosts advertise TLS to these hosts |
| 12535 | tls_certificate location of server certificate |
| 12536 | tls_crl certificate revocation list |
| 12537 | tls_dh_max_bits clamp D-H bit count suggestion |
| 12538 | tls_dhparam DH parameters for server |
| 12539 | tls_eccurve EC curve selection for server |
| 12540 | tls_ocsp_file location of server certificate status proof |
| 12541 | tls_on_connect_ports specify SSMTP (SMTPS) ports |
| 12542 | tls_privatekey location of server private key |
| 12543 | tls_remember_esmtp don't reset after starting TLS |
| 12544 | tls_require_ciphers specify acceptable ciphers |
| 12545 | tls_try_verify_hosts try to verify client certificate |
| 12546 | tls_verify_certificates expected client certificates |
| 12547 | tls_verify_hosts insist on client certificate verify |
| 12548 | |
| 12549 | |
| 12550 | 14.14 Local user handling |
| 12551 | ------------------------- |
| 12552 | |
| 12553 | finduser_retries useful in NIS environments |
| 12554 | gecos_name used when creating Sender: |
| 12555 | gecos_pattern ditto |
| 12556 | max_username_length for systems that truncate |
| 12557 | unknown_login used when no login name found |
| 12558 | unknown_username ditto |
| 12559 | uucp_from_pattern for recognizing "From " lines |
| 12560 | uucp_from_sender ditto |
| 12561 | |
| 12562 | |
| 12563 | 14.15 All incoming messages (SMTP and non-SMTP) |
| 12564 | ----------------------------------------------- |
| 12565 | |
| 12566 | header_maxsize total size of message header |
| 12567 | header_line_maxsize individual header line limit |
| 12568 | message_size_limit applies to all messages |
| 12569 | percent_hack_domains recognize %-hack for these domains |
| 12570 | received_header_text expanded to make Received: |
| 12571 | received_headers_max for mail loop detection |
| 12572 | recipients_max limit per message |
| 12573 | recipients_max_reject permanently reject excess recipients |
| 12574 | |
| 12575 | |
| 12576 | 14.16 Non-SMTP incoming messages |
| 12577 | -------------------------------- |
| 12578 | |
| 12579 | receive_timeout for non-SMTP messages |
| 12580 | |
| 12581 | |
| 12582 | 14.17 Incoming SMTP messages |
| 12583 | ---------------------------- |
| 12584 | |
| 12585 | See also the Policy controls section above. |
| 12586 | |
| 12587 | dkim_verify_signers DKIM domain for which DKIM ACL is run |
| 12588 | host_lookup host name looked up for these hosts |
| 12589 | host_lookup_order order of DNS and local name lookups |
| 12590 | recipient_unqualified_hosts may send unqualified recipients |
| 12591 | rfc1413_hosts make ident calls to these hosts |
| 12592 | rfc1413_query_timeout zero disables ident calls |
| 12593 | sender_unqualified_hosts may send unqualified senders |
| 12594 | smtp_accept_keepalive some TCP/IP magic |
| 12595 | smtp_accept_max simultaneous incoming connections |
| 12596 | smtp_accept_max_nonmail non-mail commands |
| 12597 | smtp_accept_max_nonmail_hosts hosts to which the limit applies |
| 12598 | smtp_accept_max_per_connection messages per connection |
| 12599 | smtp_accept_max_per_host connections from one host |
| 12600 | smtp_accept_queue queue mail if more connections |
| 12601 | smtp_accept_queue_per_connection queue if more messages per connection |
| 12602 | smtp_accept_reserve only reserve hosts if more connections |
| 12603 | smtp_active_hostname host name to use in messages |
| 12604 | smtp_banner text for welcome banner |
| 12605 | smtp_check_spool_space from SIZE on MAIL command |
| 12606 | smtp_connect_backlog passed to TCP/IP stack |
| 12607 | smtp_enforce_sync of SMTP command/responses |
| 12608 | smtp_etrn_command what to run for ETRN |
| 12609 | smtp_etrn_serialize only one at once |
| 12610 | smtp_load_reserve only reserve hosts if this load |
| 12611 | smtp_max_unknown_commands before dropping connection |
| 12612 | smtp_ratelimit_hosts apply ratelimiting to these hosts |
| 12613 | smtp_ratelimit_mail ratelimit for MAIL commands |
| 12614 | smtp_ratelimit_rcpt ratelimit for RCPT commands |
| 12615 | smtp_receive_timeout per command or data line |
| 12616 | smtp_reserve_hosts these are the reserve hosts |
| 12617 | smtp_return_error_details give detail on rejections |
| 12618 | |
| 12619 | |
| 12620 | 14.18 SMTP extensions |
| 12621 | --------------------- |
| 12622 | |
| 12623 | accept_8bitmime advertise 8BITMIME |
| 12624 | auth_advertise_hosts advertise AUTH to these hosts |
| 12625 | chunking_advertise_hosts advertise CHUNKING to these hosts |
| 12626 | dsn_advertise_hosts advertise DSN extensions to these hosts |
| 12627 | ignore_fromline_hosts allow "From " from these hosts |
| 12628 | ignore_fromline_local allow "From " from local SMTP |
| 12629 | pipelining_advertise_hosts advertise pipelining to these hosts |
| 12630 | prdr_enable advertise PRDR to all hosts |
| 12631 | smtputf8_advertise_hosts advertise SMTPUTF8 to these hosts |
| 12632 | tls_advertise_hosts advertise TLS to these hosts |
| 12633 | |
| 12634 | |
| 12635 | 14.19 Processing messages |
| 12636 | ------------------------- |
| 12637 | |
| 12638 | allow_domain_literals recognize domain literal syntax |
| 12639 | allow_mx_to_ip allow MX to point to IP address |
| 12640 | allow_utf8_domains in addresses |
| 12641 | check_rfc2047_length check length of RFC 2047 "encoded words" |
| 12642 | delivery_date_remove from incoming messages |
| 12643 | envelope_to_remove from incoming messages |
| 12644 | extract_addresses_remove_arguments affects -t processing |
| 12645 | headers_charset default for translations |
| 12646 | qualify_domain default for senders |
| 12647 | qualify_recipient default for recipients |
| 12648 | return_path_remove from incoming messages |
| 12649 | strip_excess_angle_brackets in addresses |
| 12650 | strip_trailing_dot at end of addresses |
| 12651 | untrusted_set_sender untrusted can set envelope sender |
| 12652 | |
| 12653 | |
| 12654 | 14.20 System filter |
| 12655 | ------------------- |
| 12656 | |
| 12657 | system_filter locate system filter |
| 12658 | system_filter_directory_transport transport for delivery to a directory |
| 12659 | system_filter_file_transport transport for delivery to a file |
| 12660 | system_filter_group group for filter running |
| 12661 | system_filter_pipe_transport transport for delivery to a pipe |
| 12662 | system_filter_reply_transport transport for autoreply delivery |
| 12663 | system_filter_user user for filter running |
| 12664 | |
| 12665 | |
| 12666 | 14.21 Routing and delivery |
| 12667 | -------------------------- |
| 12668 | |
| 12669 | disable_ipv6 do no IPv6 processing |
| 12670 | dns_again_means_nonexist for broken domains |
| 12671 | dns_check_names_pattern pre-DNS syntax check |
| 12672 | dns_dnssec_ok parameter for resolver |
| 12673 | dns_ipv4_lookup only v4 lookup for these domains |
| 12674 | dns_retrans parameter for resolver |
| 12675 | dns_retry parameter for resolver |
| 12676 | dns_trust_aa DNS zones trusted as authentic |
| 12677 | dns_use_edns0 parameter for resolver |
| 12678 | hold_domains hold delivery for these domains |
| 12679 | local_interfaces for routing checks |
| 12680 | queue_domains no immediate delivery for these |
| 12681 | queue_only no immediate delivery at all |
| 12682 | queue_only_file no immediate delivery if file exists |
| 12683 | queue_only_load no immediate delivery if load is high |
| 12684 | queue_only_load_latch don't re-evaluate load for each message |
| 12685 | queue_only_override allow command line to override |
| 12686 | queue_run_in_order order of arrival |
| 12687 | queue_run_max of simultaneous queue runners |
| 12688 | queue_smtp_domains no immediate SMTP delivery for these |
| 12689 | remote_max_parallel parallel SMTP delivery per message |
| 12690 | remote_sort_domains order of remote deliveries |
| 12691 | retry_data_expire timeout for retry data |
| 12692 | retry_interval_max safety net for retry rules |
| 12693 | |
| 12694 | |
| 12695 | 14.22 Bounce and warning messages |
| 12696 | --------------------------------- |
| 12697 | |
| 12698 | bounce_message_file content of bounce |
| 12699 | bounce_message_text content of bounce |
| 12700 | bounce_return_body include body if returning message |
| 12701 | bounce_return_linesize_limit limit on returned message line length |
| 12702 | bounce_return_message include original message in bounce |
| 12703 | bounce_return_size_limit limit on returned message |
| 12704 | bounce_sender_authentication send authenticated sender with bounce |
| 12705 | dsn_from set From: contents in bounces |
| 12706 | errors_copy copy bounce messages |
| 12707 | errors_reply_to Reply-to: in bounces |
| 12708 | delay_warning time schedule |
| 12709 | delay_warning_condition condition for warning messages |
| 12710 | ignore_bounce_errors_after discard undeliverable bounces |
| 12711 | smtp_return_error_details give detail on rejections |
| 12712 | warn_message_file content of warning message |
| 12713 | |
| 12714 | |
| 12715 | 14.23 Alphabetical list of main options |
| 12716 | --------------------------------------- |
| 12717 | |
| 12718 | Those options that undergo string expansion before use are marked with *. |
| 12719 | |
| 12720 | +-----------------------------------------------------+ |
| 12721 | |accept_8bitmime|Use: main|Type: boolean|Default: true| |
| 12722 | +-----------------------------------------------------+ |
| 12723 | |
| 12724 | This option causes Exim to send 8BITMIME in its response to an SMTP EHLO |
| 12725 | command, and to accept the BODY= parameter on MAIL commands. However, though |
| 12726 | Exim is 8-bit clean, it is not a protocol converter, and it takes no steps to |
| 12727 | do anything special with messages received by this route. |
| 12728 | |
| 12729 | Historically Exim kept this option off by default, but the maintainers feel |
| 12730 | that in today's Internet, this causes more problems than it solves. It now |
| 12731 | defaults to true. A more detailed analysis of the issues is provided by Dan |
| 12732 | Bernstein: |
| 12733 | |
| 12734 | http://cr.yp.to/smtp/8bitmime.html |
| 12735 | |
| 12736 | To log received 8BITMIME status use |
| 12737 | |
| 12738 | log_selector = +8bitmime |
| 12739 | |
| 12740 | +---------------------------------------------------+ |
| 12741 | |acl_not_smtp|Use: main|Type: string*|Default: unset| |
| 12742 | +---------------------------------------------------+ |
| 12743 | |
| 12744 | This option defines the ACL that is run when a non-SMTP message has been read |
| 12745 | and is on the point of being accepted. See chapter 43 for further details. |
| 12746 | |
| 12747 | +--------------------------------------------------------+ |
| 12748 | |acl_not_smtp_mime|Use: main|Type: string*|Default: unset| |
| 12749 | +--------------------------------------------------------+ |
| 12750 | |
| 12751 | This option defines the ACL that is run for individual MIME parts of non-SMTP |
| 12752 | messages. It operates in exactly the same way as acl_smtp_mime operates for |
| 12753 | SMTP messages. |
| 12754 | |
| 12755 | +---------------------------------------------------------+ |
| 12756 | |acl_not_smtp_start|Use: main|Type: string*|Default: unset| |
| 12757 | +---------------------------------------------------------+ |
| 12758 | |
| 12759 | This option defines the ACL that is run before Exim starts reading a non-SMTP |
| 12760 | message. See chapter 43 for further details. |
| 12761 | |
| 12762 | +----------------------------------------------------+ |
| 12763 | |acl_smtp_auth|Use: main|Type: string*|Default: unset| |
| 12764 | +----------------------------------------------------+ |
| 12765 | |
| 12766 | This option defines the ACL that is run when an SMTP AUTH command is received. |
| 12767 | See chapter 43 for further details. |
| 12768 | |
| 12769 | +-------------------------------------------------------+ |
| 12770 | |acl_smtp_connect|Use: main|Type: string*|Default: unset| |
| 12771 | +-------------------------------------------------------+ |
| 12772 | |
| 12773 | This option defines the ACL that is run when an SMTP connection is received. |
| 12774 | See chapter 43 for further details. |
| 12775 | |
| 12776 | +----------------------------------------------------+ |
| 12777 | |acl_smtp_data|Use: main|Type: string*|Default: unset| |
| 12778 | +----------------------------------------------------+ |
| 12779 | |
| 12780 | This option defines the ACL that is run after an SMTP DATA command has been |
| 12781 | processed and the message itself has been received, but before the final |
| 12782 | acknowledgment is sent. See chapter 43 for further details. |
| 12783 | |
| 12784 | +----------------------------------------------------------+ |
| 12785 | |acl_smtp_data_prdr|Use: main|Type: string*|Default: accept| |
| 12786 | +----------------------------------------------------------+ |
| 12787 | |
| 12788 | This option defines the ACL that, if the PRDR feature has been negotiated, is |
| 12789 | run for each recipient after an SMTP DATA command has been processed and the |
| 12790 | message itself has been received, but before the acknowledgment is sent. See |
| 12791 | chapter 43 for further details. |
| 12792 | |
| 12793 | +----------------------------------------------------+ |
| 12794 | |acl_smtp_dkim|Use: main|Type: string*|Default: unset| |
| 12795 | +----------------------------------------------------+ |
| 12796 | |
| 12797 | This option defines the ACL that is run for each DKIM signature (by default, or |
| 12798 | as specified in the dkim_verify_signers option) of a received message. See |
| 12799 | chapter 57 for further details. |
| 12800 | |
| 12801 | +----------------------------------------------------+ |
| 12802 | |acl_smtp_etrn|Use: main|Type: string*|Default: unset| |
| 12803 | +----------------------------------------------------+ |
| 12804 | |
| 12805 | This option defines the ACL that is run when an SMTP ETRN command is received. |
| 12806 | See chapter 43 for further details. |
| 12807 | |
| 12808 | +----------------------------------------------------+ |
| 12809 | |acl_smtp_expn|Use: main|Type: string*|Default: unset| |
| 12810 | +----------------------------------------------------+ |
| 12811 | |
| 12812 | This option defines the ACL that is run when an SMTP EXPN command is received. |
| 12813 | See chapter 43 for further details. |
| 12814 | |
| 12815 | +----------------------------------------------------+ |
| 12816 | |acl_smtp_helo|Use: main|Type: string*|Default: unset| |
| 12817 | +----------------------------------------------------+ |
| 12818 | |
| 12819 | This option defines the ACL that is run when an SMTP EHLO or HELO command is |
| 12820 | received. See chapter 43 for further details. |
| 12821 | |
| 12822 | +----------------------------------------------------+ |
| 12823 | |acl_smtp_mail|Use: main|Type: string*|Default: unset| |
| 12824 | +----------------------------------------------------+ |
| 12825 | |
| 12826 | This option defines the ACL that is run when an SMTP MAIL command is received. |
| 12827 | See chapter 43 for further details. |
| 12828 | |
| 12829 | +--------------------------------------------------------+ |
| 12830 | |acl_smtp_mailauth|Use: main|Type: string*|Default: unset| |
| 12831 | +--------------------------------------------------------+ |
| 12832 | |
| 12833 | This option defines the ACL that is run when there is an AUTH parameter on a |
| 12834 | MAIL command. See chapter 43 for details of ACLs, and chapter 33 for details of |
| 12835 | authentication. |
| 12836 | |
| 12837 | +----------------------------------------------------+ |
| 12838 | |acl_smtp_mime|Use: main|Type: string*|Default: unset| |
| 12839 | +----------------------------------------------------+ |
| 12840 | |
| 12841 | This option is available when Exim is built with the content-scanning |
| 12842 | extension. It defines the ACL that is run for each MIME part in a message. See |
| 12843 | section 44.4 for details. |
| 12844 | |
| 12845 | +-------------------------------------------------------+ |
| 12846 | |acl_smtp_notquit|Use: main|Type: string*|Default: unset| |
| 12847 | +-------------------------------------------------------+ |
| 12848 | |
| 12849 | This option defines the ACL that is run when an SMTP session ends without a |
| 12850 | QUIT command being received. See chapter 43 for further details. |
| 12851 | |
| 12852 | +-------------------------------------------------------+ |
| 12853 | |acl_smtp_predata|Use: main|Type: string*|Default: unset| |
| 12854 | +-------------------------------------------------------+ |
| 12855 | |
| 12856 | This option defines the ACL that is run when an SMTP DATA command is received, |
| 12857 | before the message itself is received. See chapter 43 for further details. |
| 12858 | |
| 12859 | +----------------------------------------------------+ |
| 12860 | |acl_smtp_quit|Use: main|Type: string*|Default: unset| |
| 12861 | +----------------------------------------------------+ |
| 12862 | |
| 12863 | This option defines the ACL that is run when an SMTP QUIT command is received. |
| 12864 | See chapter 43 for further details. |
| 12865 | |
| 12866 | +----------------------------------------------------+ |
| 12867 | |acl_smtp_rcpt|Use: main|Type: string*|Default: unset| |
| 12868 | +----------------------------------------------------+ |
| 12869 | |
| 12870 | This option defines the ACL that is run when an SMTP RCPT command is received. |
| 12871 | See chapter 43 for further details. |
| 12872 | |
| 12873 | +--------------------------------------------------------+ |
| 12874 | |acl_smtp_starttls|Use: main|Type: string*|Default: unset| |
| 12875 | +--------------------------------------------------------+ |
| 12876 | |
| 12877 | This option defines the ACL that is run when an SMTP STARTTLS command is |
| 12878 | received. See chapter 43 for further details. |
| 12879 | |
| 12880 | +----------------------------------------------------+ |
| 12881 | |acl_smtp_vrfy|Use: main|Type: string*|Default: unset| |
| 12882 | +----------------------------------------------------+ |
| 12883 | |
| 12884 | This option defines the ACL that is run when an SMTP VRFY command is received. |
| 12885 | See chapter 43 for further details. |
| 12886 | |
| 12887 | +----------------------------------------------------------+ |
| 12888 | |add_environment|Use: main|Type: string list|Default: empty| |
| 12889 | +----------------------------------------------------------+ |
| 12890 | |
| 12891 | This option allows to set individual environment variables that the currently |
| 12892 | linked libraries and programs in child processes use. See 29.4 for the |
| 12893 | environment of pipe transports. |
| 12894 | |
| 12895 | +--------------------------------------------------------+ |
| 12896 | |admin_groups|Use: main|Type: string list*|Default: unset| |
| 12897 | +--------------------------------------------------------+ |
| 12898 | |
| 12899 | This option is expanded just once, at the start of Exim's processing. If the |
| 12900 | current group or any of the supplementary groups of an Exim caller is in this |
| 12901 | colon-separated list, the caller has admin privileges. If all your system |
| 12902 | programmers are in a specific group, for example, you can give them all Exim |
| 12903 | admin privileges by putting that group in admin_groups. However, this does not |
| 12904 | permit them to read Exim's spool files (whose group owner is the Exim gid). To |
| 12905 | permit this, you have to add individuals to the Exim group. |
| 12906 | |
| 12907 | +------------------------------------------------------------+ |
| 12908 | |allow_domain_literals|Use: main|Type: boolean|Default: false| |
| 12909 | +------------------------------------------------------------+ |
| 12910 | |
| 12911 | If this option is set, the RFC 2822 domain literal format is permitted in email |
| 12912 | addresses. The option is not set by default, because the domain literal format |
| 12913 | is not normally required these days, and few people know about it. It has, |
| 12914 | however, been exploited by mail abusers. |
| 12915 | |
| 12916 | Unfortunately, it seems that some DNS black list maintainers are using this |
| 12917 | format to report black listing to postmasters. If you want to accept messages |
| 12918 | addressed to your hosts by IP address, you need to set allow_domain_literals |
| 12919 | true, and also to add "@[]" to the list of local domains (defined in the named |
| 12920 | domain list local_domains in the default configuration). This "magic string" |
| 12921 | matches the domain literal form of all the local host's IP addresses. |
| 12922 | |
| 12923 | +-----------------------------------------------------+ |
| 12924 | |allow_mx_to_ip|Use: main|Type: boolean|Default: false| |
| 12925 | +-----------------------------------------------------+ |
| 12926 | |
| 12927 | It appears that more and more DNS zone administrators are breaking the rules |
| 12928 | and putting domain names that look like IP addresses on the right hand side of |
| 12929 | MX records. Exim follows the rules and rejects this, giving an error message |
| 12930 | that explains the misconfiguration. However, some other MTAs support this |
| 12931 | practice, so to avoid "Why can't Exim do this?" complaints, allow_mx_to_ip |
| 12932 | exists, in order to enable this heinous activity. It is not recommended, except |
| 12933 | when you have no other choice. |
| 12934 | |
| 12935 | +---------------------------------------------------------+ |
| 12936 | |allow_utf8_domains|Use: main|Type: boolean|Default: false| |
| 12937 | +---------------------------------------------------------+ |
| 12938 | |
| 12939 | Lots of discussion is going on about internationalized domain names. One camp |
| 12940 | is strongly in favour of just using UTF-8 characters, and it seems that at |
| 12941 | least two other MTAs permit this. This option allows Exim users to experiment |
| 12942 | if they wish. |
| 12943 | |
| 12944 | If it is set true, Exim's domain parsing function allows valid UTF-8 |
| 12945 | multicharacters to appear in domain name components, in addition to letters, |
| 12946 | digits, and hyphens. However, just setting this option is not enough; if you |
| 12947 | want to look up these domain names in the DNS, you must also adjust the value |
| 12948 | of dns_check_names_pattern to match the extended form. A suitable setting is: |
| 12949 | |
| 12950 | dns_check_names_pattern = (?i)^(?>(?(1)\.|())[a-z0-9\xc0-\xff]\ |
| 12951 | (?>[-a-z0-9\x80-\xff]*[a-z0-9\x80-\xbf])?)+$ |
| 12952 | |
| 12953 | Alternatively, you can just disable this feature by setting |
| 12954 | |
| 12955 | dns_check_names_pattern = |
| 12956 | |
| 12957 | That is, set the option to an empty string so that no check is done. |
| 12958 | |
| 12959 | +----------------------------------------------------------+ |
| 12960 | |auth_advertise_hosts|Use: main|Type: host list*|Default: *| |
| 12961 | +----------------------------------------------------------+ |
| 12962 | |
| 12963 | If any server authentication mechanisms are configured, Exim advertises them in |
| 12964 | response to an EHLO command only if the calling host matches this list. |
| 12965 | Otherwise, Exim does not advertise AUTH. Exim does not accept AUTH commands |
| 12966 | from clients to which it has not advertised the availability of AUTH. The |
| 12967 | advertising of individual authentication mechanisms can be controlled by the |
| 12968 | use of the server_advertise_condition generic authenticator option on the |
| 12969 | individual authenticators. See chapter 33 for further details. |
| 12970 | |
| 12971 | Certain mail clients (for example, Netscape) require the user to provide a name |
| 12972 | and password for authentication if AUTH is advertised, even though it may not |
| 12973 | be needed (the host may accept messages from hosts on its local LAN without |
| 12974 | authentication, for example). The auth_advertise_hosts option can be used to |
| 12975 | make these clients more friendly by excluding them from the set of hosts to |
| 12976 | which Exim advertises AUTH. |
| 12977 | |
| 12978 | If you want to advertise the availability of AUTH only when the connection is |
| 12979 | encrypted using TLS, you can make use of the fact that the value of this option |
| 12980 | is expanded, with a setting like this: |
| 12981 | |
| 12982 | auth_advertise_hosts = ${if eq{$tls_in_cipher}{}{}{*}} |
| 12983 | |
| 12984 | If $tls_in_cipher is empty, the session is not encrypted, and the result of the |
| 12985 | expansion is empty, thus matching no hosts. Otherwise, the result of the |
| 12986 | expansion is *, which matches all hosts. |
| 12987 | |
| 12988 | +------------------------------------------+ |
| 12989 | |auto_thaw|Use: main|Type: time|Default: 0s| |
| 12990 | +------------------------------------------+ |
| 12991 | |
| 12992 | If this option is set to a time greater than zero, a queue runner will try a |
| 12993 | new delivery attempt on any frozen message, other than a bounce message, if |
| 12994 | this much time has passed since it was frozen. This may result in the message |
| 12995 | being re-frozen if nothing has changed since the last attempt. It is a way of |
| 12996 | saying "keep on trying, even though there are big problems". |
| 12997 | |
| 12998 | Note: This is an old option, which predates timeout_frozen_after and |
| 12999 | ignore_bounce_errors_after. It is retained for compatibility, but it is not |
| 13000 | thought to be very useful any more, and its use should probably be avoided. |
| 13001 | |
| 13002 | +----------------------------------------------------+ |
| 13003 | |av_scanner|Use: main|Type: string|Default: see below| |
| 13004 | +----------------------------------------------------+ |
| 13005 | |
| 13006 | This option is available if Exim is built with the content-scanning extension. |
| 13007 | It specifies which anti-virus scanner to use. The default value is: |
| 13008 | |
| 13009 | sophie:/var/run/sophie |
| 13010 | |
| 13011 | If the value of av_scanner starts with a dollar character, it is expanded |
| 13012 | before use. See section 44.1 for further details. |
| 13013 | |
| 13014 | +------------------------------------------------+ |
| 13015 | |bi_command|Use: main|Type: string|Default: unset| |
| 13016 | +------------------------------------------------+ |
| 13017 | |
| 13018 | This option supplies the name of a command that is run when Exim is called with |
| 13019 | the -bi option (see chapter 5). The string value is just the command name, it |
| 13020 | is not a complete command line. If an argument is required, it must come from |
| 13021 | the -oA command line option. |
| 13022 | |
| 13023 | +---------------------------------------------------------+ |
| 13024 | |bounce_message_file|Use: main|Type: string|Default: unset| |
| 13025 | +---------------------------------------------------------+ |
| 13026 | |
| 13027 | This option defines a template file containing paragraphs of text to be used |
| 13028 | for constructing bounce messages. Details of the file's contents are given in |
| 13029 | chapter 49. See also warn_message_file. |
| 13030 | |
| 13031 | +---------------------------------------------------------+ |
| 13032 | |bounce_message_text|Use: main|Type: string|Default: unset| |
| 13033 | +---------------------------------------------------------+ |
| 13034 | |
| 13035 | When this option is set, its contents are included in the default bounce |
| 13036 | message immediately after "This message was created automatically by mail |
| 13037 | delivery software." It is not used if bounce_message_file is set. |
| 13038 | |
| 13039 | +--------------------------------------------------------+ |
| 13040 | |bounce_return_body|Use: main|Type: boolean|Default: true| |
| 13041 | +--------------------------------------------------------+ |
| 13042 | |
| 13043 | This option controls whether the body of an incoming message is included in a |
| 13044 | bounce message when bounce_return_message is true. The default setting causes |
| 13045 | the entire message, both header and body, to be returned (subject to the value |
| 13046 | of bounce_return_size_limit). If this option is false, only the message header |
| 13047 | is included. In the case of a non-SMTP message containing an error that is |
| 13048 | detected during reception, only those header lines preceding the point at which |
| 13049 | the error was detected are returned. |
| 13050 | |
| 13051 | +-----------------------------------------------------------------+ |
| 13052 | |bounce_return_linesize_limit|Use: main|Type: integer|Default: 998| |
| 13053 | +-----------------------------------------------------------------+ |
| 13054 | |
| 13055 | This option sets a limit in bytes on the line length of messages that are |
| 13056 | returned to senders due to delivery problems, when bounce_return_message is |
| 13057 | true. The default value corresponds to RFC limits. If the message being |
| 13058 | returned has lines longer than this value it is treated as if the |
| 13059 | bounce_return_size_limit (below) restriction was exceeded. |
| 13060 | |
| 13061 | The option also applies to bounces returned when an error is detected during |
| 13062 | reception of a message. In this case lines from the original are truncated. |
| 13063 | |
| 13064 | The option does not apply to messages generated by an autoreply transport. |
| 13065 | |
| 13066 | +-----------------------------------------------------------+ |
| 13067 | |bounce_return_message|Use: main|Type: boolean|Default: true| |
| 13068 | +-----------------------------------------------------------+ |
| 13069 | |
| 13070 | If this option is set false, none of the original message is included in bounce |
| 13071 | messages generated by Exim. See also bounce_return_size_limit and |
| 13072 | bounce_return_body. |
| 13073 | |
| 13074 | +--------------------------------------------------------------+ |
| 13075 | |bounce_return_size_limit|Use: main|Type: integer|Default: 100K| |
| 13076 | +--------------------------------------------------------------+ |
| 13077 | |
| 13078 | This option sets a limit in bytes on the size of messages that are returned to |
| 13079 | senders as part of bounce messages when bounce_return_message is true. The |
| 13080 | limit should be less than the value of the global message_size_limit and of any |
| 13081 | message_size_limit settings on transports, to allow for the bounce text that |
| 13082 | Exim generates. If this option is set to zero there is no limit. |
| 13083 | |
| 13084 | When the body of any message that is to be included in a bounce message is |
| 13085 | greater than the limit, it is truncated, and a comment pointing this out is |
| 13086 | added at the top. The actual cutoff may be greater than the value given, owing |
| 13087 | to the use of buffering for transferring the message in chunks (typically 8K in |
| 13088 | size). The idea is to save bandwidth on those undeliverable 15-megabyte |
| 13089 | messages. |
| 13090 | |
| 13091 | +------------------------------------------------------------------+ |
| 13092 | |bounce_sender_authentication|Use: main|Type: string|Default: unset| |
| 13093 | +------------------------------------------------------------------+ |
| 13094 | |
| 13095 | This option provides an authenticated sender address that is sent with any |
| 13096 | bounce messages generated by Exim that are sent over an authenticated SMTP |
| 13097 | connection. A typical setting might be: |
| 13098 | |
| 13099 | bounce_sender_authentication = mailer-daemon@my.domain.example |
| 13100 | |
| 13101 | which would cause bounce messages to be sent using the SMTP command: |
| 13102 | |
| 13103 | MAIL FROM:<> AUTH=mailer-daemon@my.domain.example |
| 13104 | |
| 13105 | The value of bounce_sender_authentication must always be a complete email |
| 13106 | address. |
| 13107 | |
| 13108 | +---------------------------------------------------------------+ |
| 13109 | |callout_domain_negative_expire|Use: main|Type: time|Default: 3h| |
| 13110 | +---------------------------------------------------------------+ |
| 13111 | |
| 13112 | This option specifies the expiry time for negative callout cache data for a |
| 13113 | domain. See section 43.45 for details of callout verification, and section |
| 13114 | 43.47 for details of the caching. |
| 13115 | |
| 13116 | +---------------------------------------------------------------+ |
| 13117 | |callout_domain_positive_expire|Use: main|Type: time|Default: 7d| |
| 13118 | +---------------------------------------------------------------+ |
| 13119 | |
| 13120 | This option specifies the expiry time for positive callout cache data for a |
| 13121 | domain. See section 43.45 for details of callout verification, and section |
| 13122 | 43.47 for details of the caching. |
| 13123 | |
| 13124 | +--------------------------------------------------------+ |
| 13125 | |callout_negative_expire|Use: main|Type: time|Default: 2h| |
| 13126 | +--------------------------------------------------------+ |
| 13127 | |
| 13128 | This option specifies the expiry time for negative callout cache data for an |
| 13129 | address. See section 43.45 for details of callout verification, and section |
| 13130 | 43.47 for details of the caching. |
| 13131 | |
| 13132 | +---------------------------------------------------------+ |
| 13133 | |callout_positive_expire|Use: main|Type: time|Default: 24h| |
| 13134 | +---------------------------------------------------------+ |
| 13135 | |
| 13136 | This option specifies the expiry time for positive callout cache data for an |
| 13137 | address. See section 43.45 for details of callout verification, and section |
| 13138 | 43.47 for details of the caching. |
| 13139 | |
| 13140 | +--------------------------------------------------------------------+ |
| 13141 | |callout_random_local_part|Use: main|Type: string*|Default: see below| |
| 13142 | +--------------------------------------------------------------------+ |
| 13143 | |
| 13144 | This option defines the "random" local part that can be used as part of callout |
| 13145 | verification. The default value is |
| 13146 | |
| 13147 | $primary_hostname-$tod_epoch-testing |
| 13148 | |
| 13149 | See section 43.46 for details of how this value is used. |
| 13150 | |
| 13151 | +-----------------------------------------------------+ |
| 13152 | |check_log_inodes|Use: main|Type: integer|Default: 100| |
| 13153 | +-----------------------------------------------------+ |
| 13154 | |
| 13155 | See check_spool_space below. |
| 13156 | |
| 13157 | +----------------------------------------------------+ |
| 13158 | |check_log_space|Use: main|Type: integer|Default: 10M| |
| 13159 | +----------------------------------------------------+ |
| 13160 | |
| 13161 | See check_spool_space below. |
| 13162 | |
| 13163 | +----------------------------------------------------------+ |
| 13164 | |check_rfc2047_length|Use: main|Type: boolean|Default: true| |
| 13165 | +----------------------------------------------------------+ |
| 13166 | |
| 13167 | RFC 2047 defines a way of encoding non-ASCII characters in headers using a |
| 13168 | system of "encoded words". The RFC specifies a maximum length for an encoded |
| 13169 | word; strings to be encoded that exceed this length are supposed to use |
| 13170 | multiple encoded words. By default, Exim does not recognize encoded words that |
| 13171 | exceed the maximum length. However, it seems that some software, in violation |
| 13172 | of the RFC, generates overlong encoded words. If check_rfc2047_length is set |
| 13173 | false, Exim recognizes encoded words of any length. |
| 13174 | |
| 13175 | +-------------------------------------------------------+ |
| 13176 | |check_spool_inodes|Use: main|Type: integer|Default: 100| |
| 13177 | +-------------------------------------------------------+ |
| 13178 | |
| 13179 | See check_spool_space below. |
| 13180 | |
| 13181 | +------------------------------------------------------+ |
| 13182 | |check_spool_space|Use: main|Type: integer|Default: 10M| |
| 13183 | +------------------------------------------------------+ |
| 13184 | |
| 13185 | The four check_... options allow for checking of disk resources before a |
| 13186 | message is accepted. |
| 13187 | |
| 13188 | When any of these options are nonzero, they apply to all incoming messages. If |
| 13189 | you want to apply different checks to different kinds of message, you can do so |
| 13190 | by testing the variables $log_inodes, $log_space, $spool_inodes, and |
| 13191 | $spool_space in an ACL with appropriate additional conditions. |
| 13192 | |
| 13193 | check_spool_space and check_spool_inodes check the spool partition if either |
| 13194 | value is greater than zero, for example: |
| 13195 | |
| 13196 | check_spool_space = 100M |
| 13197 | check_spool_inodes = 100 |
| 13198 | |
| 13199 | The spool partition is the one that contains the directory defined by |
| 13200 | SPOOL_DIRECTORY in Local/Makefile. It is used for holding messages in transit. |
| 13201 | |
| 13202 | check_log_space and check_log_inodes check the partition in which log files are |
| 13203 | written if either is greater than zero. These should be set only if |
| 13204 | log_file_path and spool_directory refer to different partitions. |
| 13205 | |
| 13206 | If there is less space or fewer inodes than requested, Exim refuses to accept |
| 13207 | incoming mail. In the case of SMTP input this is done by giving a 452 temporary |
| 13208 | error response to the MAIL command. If ESMTP is in use and there was a SIZE |
| 13209 | parameter on the MAIL command, its value is added to the check_spool_space |
| 13210 | value, and the check is performed even if check_spool_space is zero, unless |
| 13211 | no_smtp_check_spool_space is set. |
| 13212 | |
| 13213 | The values for check_spool_space and check_log_space are held as a number of |
| 13214 | kilobytes (though specified in bytes). If a non-multiple of 1024 is specified, |
| 13215 | it is rounded up. |
| 13216 | |
| 13217 | For non-SMTP input and for batched SMTP input, the test is done at start-up; on |
| 13218 | failure a message is written to stderr and Exim exits with a non-zero code, as |
| 13219 | it obviously cannot send an error message of any kind. |
| 13220 | |
| 13221 | There is a slight performance penalty for these checks. Versions of Exim |
| 13222 | preceding 4.88 had these disabled by default; high-rate installations confident |
| 13223 | they will never run out of resources may wish to deliberately disable them. |
| 13224 | |
| 13225 | +--------------------------------------------------------------+ |
| 13226 | |chunking_advertise_hosts|Use: main|Type: host list*|Default: *| |
| 13227 | +--------------------------------------------------------------+ |
| 13228 | |
| 13229 | The CHUNKING extension (RFC3030) will be advertised in the EHLO message to |
| 13230 | these hosts. Hosts may use the BDAT command as an alternate to DATA. |
| 13231 | |
| 13232 | +----------------------------------------------------+ |
| 13233 | |debug_store|Use: main|Type: boolean|Default: "false"| |
| 13234 | +----------------------------------------------------+ |
| 13235 | |
| 13236 | This option, when true, enables extra checking in Exim's internal memory |
| 13237 | management. For use when a memory corruption issue is being investigated, it |
| 13238 | should normally be left as default. |
| 13239 | |
| 13240 | +--------------------------------------------------------+ |
| 13241 | |daemon_smtp_ports|Use: main|Type: string|Default: "smtp"| |
| 13242 | +--------------------------------------------------------+ |
| 13243 | |
| 13244 | This option specifies one or more default SMTP ports on which the Exim daemon |
| 13245 | listens. See chapter 13 for details of how it is used. For backward |
| 13246 | compatibility, daemon_smtp_port (singular) is a synonym. |
| 13247 | |
| 13248 | +---------------------------------------------------------+ |
| 13249 | |daemon_startup_retries|Use: main|Type: integer|Default: 9| |
| 13250 | +---------------------------------------------------------+ |
| 13251 | |
| 13252 | This option, along with daemon_startup_sleep, controls the retrying done by the |
| 13253 | daemon at startup when it cannot immediately bind a listening socket (typically |
| 13254 | because the socket is already in use): daemon_startup_retries defines the |
| 13255 | number of retries after the first failure, and daemon_startup_sleep defines the |
| 13256 | length of time to wait between retries. |
| 13257 | |
| 13258 | +------------------------------------------------------+ |
| 13259 | |daemon_startup_sleep|Use: main|Type: time|Default: 30s| |
| 13260 | +------------------------------------------------------+ |
| 13261 | |
| 13262 | See daemon_startup_retries. |
| 13263 | |
| 13264 | +----------------------------------------------------+ |
| 13265 | |delay_warning|Use: main|Type: time list|Default: 24h| |
| 13266 | +----------------------------------------------------+ |
| 13267 | |
| 13268 | When a message is delayed, Exim sends a warning message to the sender at |
| 13269 | intervals specified by this option. The data is a colon-separated list of times |
| 13270 | after which to send warning messages. If the value of the option is an empty |
| 13271 | string or a zero time, no warnings are sent. Up to 10 times may be given. If a |
| 13272 | message has been on the queue for longer than the last time, the last interval |
| 13273 | between the times is used to compute subsequent warning times. For example, |
| 13274 | with |
| 13275 | |
| 13276 | delay_warning = 4h:8h:24h |
| 13277 | |
| 13278 | the first message is sent after 4 hours, the second after 8 hours, and the |
| 13279 | third one after 24 hours. After that, messages are sent every 16 hours, because |
| 13280 | that is the interval between the last two times on the list. If you set just |
| 13281 | one time, it specifies the repeat interval. For example, with: |
| 13282 | |
| 13283 | delay_warning = 6h |
| 13284 | |
| 13285 | messages are repeated every six hours. To stop warnings after a given time, set |
| 13286 | a very large time at the end of the list. For example: |
| 13287 | |
| 13288 | delay_warning = 2h:12h:99d |
| 13289 | |
| 13290 | Note that the option is only evaluated at the time a delivery attempt fails, |
| 13291 | which depends on retry and queue-runner configuration. Typically retries will |
| 13292 | be configured more frequently than warning messages. |
| 13293 | |
| 13294 | +------------------------------------------------------------------+ |
| 13295 | |delay_warning_condition|Use: main|Type: string*|Default: see below| |
| 13296 | +------------------------------------------------------------------+ |
| 13297 | |
| 13298 | The string is expanded at the time a warning message might be sent. If all the |
| 13299 | deferred addresses have the same domain, it is set in $domain during the |
| 13300 | expansion. Otherwise $domain is empty. If the result of the expansion is a |
| 13301 | forced failure, an empty string, or a string matching any of "0", "no" or |
| 13302 | "false" (the comparison being done caselessly) then the warning message is not |
| 13303 | sent. The default is: |
| 13304 | |
| 13305 | delay_warning_condition = ${if or {\ |
| 13306 | { !eq{$h_list-id:$h_list-post:$h_list-subscribe:}{} }\ |
| 13307 | { match{$h_precedence:}{(?i)bulk|list|junk} }\ |
| 13308 | { match{$h_auto-submitted:}{(?i)auto-generated|auto-replied} }\ |
| 13309 | } {no}{yes}} |
| 13310 | |
| 13311 | This suppresses the sending of warnings for messages that contain List-ID:, |
| 13312 | List-Post:, or List-Subscribe: headers, or have "bulk", "list" or "junk" in a |
| 13313 | Precedence: header, or have "auto-generated" or "auto-replied" in an |
| 13314 | Auto-Submitted: header. |
| 13315 | |
| 13316 | +-------------------------------------------------------------+ |
| 13317 | |deliver_drop_privilege|Use: main|Type: boolean|Default: false| |
| 13318 | +-------------------------------------------------------------+ |
| 13319 | |
| 13320 | If this option is set true, Exim drops its root privilege at the start of a |
| 13321 | delivery process, and runs as the Exim user throughout. This severely restricts |
| 13322 | the kinds of local delivery that are possible, but is viable in certain types |
| 13323 | of configuration. There is a discussion about the use of root privilege in |
| 13324 | chapter 55. |
| 13325 | |
| 13326 | +-----------------------------------------------------------------+ |
| 13327 | |deliver_queue_load_max|Use: main|Type: fixed-point|Default: unset| |
| 13328 | +-----------------------------------------------------------------+ |
| 13329 | |
| 13330 | When this option is set, a queue run is abandoned if the system load average |
| 13331 | becomes greater than the value of the option. The option has no effect on |
| 13332 | ancient operating systems on which Exim cannot determine the load average. See |
| 13333 | also queue_only_load and smtp_load_reserve. |
| 13334 | |
| 13335 | +----------------------------------------------------------+ |
| 13336 | |delivery_date_remove|Use: main|Type: boolean|Default: true| |
| 13337 | +----------------------------------------------------------+ |
| 13338 | |
| 13339 | Exim's transports have an option for adding a Delivery-date: header to a |
| 13340 | message when it is delivered, in exactly the same way as Return-path: is |
| 13341 | handled. Delivery-date: records the actual time of delivery. Such headers |
| 13342 | should not be present in incoming messages, and this option causes them to be |
| 13343 | removed at the time the message is received, to avoid any problems that might |
| 13344 | occur when a delivered message is subsequently sent on to some other recipient. |
| 13345 | |
| 13346 | +----------------------------------------------------+ |
| 13347 | |disable_fsync|Use: main|Type: boolean|Default: false| |
| 13348 | +----------------------------------------------------+ |
| 13349 | |
| 13350 | This option is available only if Exim was built with the compile-time option |
| 13351 | ENABLE_DISABLE_FSYNC. When this is not set, a reference to disable_fsync in a |
| 13352 | runtime configuration generates an "unknown option" error. You should not build |
| 13353 | Exim with ENABLE_DISABLE_FSYNC or set disable_fsync unless you really, really, |
| 13354 | really understand what you are doing. No pre-compiled distributions of Exim |
| 13355 | should ever make this option available. |
| 13356 | |
| 13357 | When disable_fsync is set true, Exim no longer calls fsync() to force updated |
| 13358 | files' data to be written to disc before continuing. Unexpected events such as |
| 13359 | crashes and power outages may cause data to be lost or scrambled. Here be |
| 13360 | Dragons. Beware. |
| 13361 | |
| 13362 | +---------------------------------------------------+ |
| 13363 | |disable_ipv6|Use: main|Type: boolean|Default: false| |
| 13364 | +---------------------------------------------------+ |
| 13365 | |
| 13366 | If this option is set true, even if the Exim binary has IPv6 support, no IPv6 |
| 13367 | activities take place. AAAA records are never looked up, and any IPv6 addresses |
| 13368 | that are listed in local_interfaces, data for the manualroute router, etc. are |
| 13369 | ignored. If IP literals are enabled, the ipliteral router declines to handle |
| 13370 | IPv6 literal addresses. |
| 13371 | |
| 13372 | +-----------------------------------------------------------------------+ |
| 13373 | |dkim_verify_signers|Use: main|Type: domain list*|Default: $dkim_signers| |
| 13374 | +-----------------------------------------------------------------------+ |
| 13375 | |
| 13376 | This option gives a list of DKIM domains for which the DKIM ACL is run. It is |
| 13377 | expanded after the message is received; by default it runs the ACL once for |
| 13378 | each signature in the message. See chapter 57. |
| 13379 | |
| 13380 | +--------------------------------------------------------------------+ |
| 13381 | |dns_again_means_nonexist|Use: main|Type: domain list*|Default: unset| |
| 13382 | +--------------------------------------------------------------------+ |
| 13383 | |
| 13384 | DNS lookups give a "try again" response for the DNS errors "non-authoritative |
| 13385 | host not found" and "SERVERFAIL". This can cause Exim to keep trying to deliver |
| 13386 | a message, or to give repeated temporary errors to incoming mail. Sometimes the |
| 13387 | effect is caused by a badly set up name server and may persist for a long time. |
| 13388 | If a domain which exhibits this problem matches anything in |
| 13389 | dns_again_means_nonexist, it is treated as if it did not exist. This option |
| 13390 | should be used with care. You can make it apply to reverse lookups by a setting |
| 13391 | such as this: |
| 13392 | |
| 13393 | dns_again_means_nonexist = *.in-addr.arpa |
| 13394 | |
| 13395 | This option applies to all DNS lookups that Exim does. It also applies when the |
| 13396 | gethostbyname() or getipnodebyname() functions give temporary errors, since |
| 13397 | these are most likely to be caused by DNS lookup problems. The dnslookup router |
| 13398 | has some options of its own for controlling what happens when lookups for MX or |
| 13399 | SRV records give temporary errors. These more specific options are applied |
| 13400 | after this global option. |
| 13401 | |
| 13402 | +-----------------------------------------------------------------+ |
| 13403 | |dns_check_names_pattern|Use: main|Type: string|Default: see below| |
| 13404 | +-----------------------------------------------------------------+ |
| 13405 | |
| 13406 | When this option is set to a non-empty string, it causes Exim to check domain |
| 13407 | names for characters that are not allowed in host names before handing them to |
| 13408 | the DNS resolver, because some resolvers give temporary errors for names that |
| 13409 | contain unusual characters. If a domain name contains any unwanted characters, |
| 13410 | a "not found" result is forced, and the resolver is not called. The check is |
| 13411 | done by matching the domain name against a regular expression, which is the |
| 13412 | value of this option. The default pattern is |
| 13413 | |
| 13414 | dns_check_names_pattern = \ |
| 13415 | (?i)^(?>(?(1)\.|())[^\W_](?>[a-z0-9/-]*[^\W_])?)+$ |
| 13416 | |
| 13417 | which permits only letters, digits, slashes, and hyphens in components, but |
| 13418 | they must start and end with a letter or digit. Slashes are not, in fact, |
| 13419 | permitted in host names, but they are found in certain NS records (which can be |
| 13420 | accessed in Exim by using a dnsdb lookup). If you set allow_utf8_domains, you |
| 13421 | must modify this pattern, or set the option to an empty string. |
| 13422 | |
| 13423 | +-------------------------------------------------------+ |
| 13424 | |dns_csa_search_limit|Use: main|Type: integer|Default: 5| |
| 13425 | +-------------------------------------------------------+ |
| 13426 | |
| 13427 | This option controls the depth of parental searching for CSA SRV records in the |
| 13428 | DNS, as described in more detail in section 43.50. |
| 13429 | |
| 13430 | +---------------------------------------------------------+ |
| 13431 | |dns_csa_use_reverse|Use: main|Type: boolean|Default: true| |
| 13432 | +---------------------------------------------------------+ |
| 13433 | |
| 13434 | This option controls whether or not an IP address, given as a CSA domain, is |
| 13435 | reversed and looked up in the reverse DNS, as described in more detail in |
| 13436 | section 43.50. |
| 13437 | |
| 13438 | +-------------------------------------------------+ |
| 13439 | |dns_dnssec_ok|Use: main|Type: integer|Default: -1| |
| 13440 | +-------------------------------------------------+ |
| 13441 | |
| 13442 | If this option is set to a non-negative number then Exim will initialise the |
| 13443 | DNS resolver library to either use or not use DNSSEC, overriding the system |
| 13444 | default. A value of 0 coerces DNSSEC off, a value of 1 coerces DNSSEC on. |
| 13445 | |
| 13446 | If the resolver library does not support DNSSEC then this option has no effect. |
| 13447 | |
| 13448 | +-----------------------------------------------------------+ |
| 13449 | |dns_ipv4_lookup|Use: main|Type: domain list*|Default: unset| |
| 13450 | +-----------------------------------------------------------+ |
| 13451 | |
| 13452 | When Exim is compiled with IPv6 support and disable_ipv6 is not set, it looks |
| 13453 | for IPv6 address records (AAAA records) as well as IPv4 address records (A |
| 13454 | records) when trying to find IP addresses for hosts, unless the host's domain |
| 13455 | matches this list. |
| 13456 | |
| 13457 | This is a fudge to help with name servers that give big delays or otherwise do |
| 13458 | not work for the AAAA record type. In due course, when the world's name servers |
| 13459 | have all been upgraded, there should be no need for this option. |
| 13460 | |
| 13461 | +--------------------------------------------+ |
| 13462 | |dns_retrans|Use: main|Type: time|Default: 0s| |
| 13463 | +--------------------------------------------+ |
| 13464 | |
| 13465 | The options dns_retrans and dns_retry can be used to set the retransmission and |
| 13466 | retry parameters for DNS lookups. Values of zero (the defaults) leave the |
| 13467 | system default settings unchanged. The first value is the time between retries, |
| 13468 | and the second is the number of retries. It isn't totally clear exactly how |
| 13469 | these settings affect the total time a DNS lookup may take. I haven't found any |
| 13470 | documentation about timeouts on DNS lookups; these parameter values are |
| 13471 | available in the external resolver interface structure, but nowhere does it |
| 13472 | seem to describe how they are used or what you might want to set in them. See |
| 13473 | also the slow_lookup_log option. |
| 13474 | |
| 13475 | +--------------------------------------------+ |
| 13476 | |dns_retry|Use: main|Type: integer|Default: 0| |
| 13477 | +--------------------------------------------+ |
| 13478 | |
| 13479 | See dns_retrans above. |
| 13480 | |
| 13481 | +--------------------------------------------------------+ |
| 13482 | |dns_trust_aa|Use: main|Type: domain list*|Default: unset| |
| 13483 | +--------------------------------------------------------+ |
| 13484 | |
| 13485 | If this option is set then lookup results marked with the AA bit (Authoritative |
| 13486 | Answer) are trusted the same way as if they were DNSSEC-verified. The authority |
| 13487 | section's name of the answer must match with this expanded domain list. |
| 13488 | |
| 13489 | Use this option only if you talk directly to a resolver that is authoritative |
| 13490 | for some zones and does not set the AD (Authentic Data) bit in the answer. Some |
| 13491 | DNS servers may have an configuration option to mark the answers from their own |
| 13492 | zones as verified (they set the AD bit). Others do not have this option. It is |
| 13493 | considered as poor practice using a resolver that is an authoritative server |
| 13494 | for some zones. |
| 13495 | |
| 13496 | Use this option only if you really have to (e.g. if you want to use DANE for |
| 13497 | remote delivery to a server that is listed in the DNS zones that your resolver |
| 13498 | is authoritative for). |
| 13499 | |
| 13500 | If the DNS answer packet has the AA bit set and contains resource record in the |
| 13501 | answer section, the name of the first NS record appearing in the authority |
| 13502 | section is compared against the list. If the answer packet is authoritative but |
| 13503 | the answer section is empty, the name of the first SOA record in the |
| 13504 | authoritative section is used instead. |
| 13505 | |
| 13506 | +-------------------------------------------------+ |
| 13507 | |dns_use_edns0|Use: main|Type: integer|Default: -1| |
| 13508 | +-------------------------------------------------+ |
| 13509 | |
| 13510 | If this option is set to a non-negative number then Exim will initialise the |
| 13511 | DNS resolver library to either use or not use EDNS0 extensions, overriding the |
| 13512 | system default. A value of 0 coerces EDNS0 off, a value of 1 coerces EDNS0 on. |
| 13513 | |
| 13514 | If the resolver library does not support EDNS0 then this option has no effect. |
| 13515 | |
| 13516 | OpenBSD's asr resolver routines are known to ignore the EDNS0 option; this |
| 13517 | means that DNSSEC will not work with Exim on that platform either, unless Exim |
| 13518 | is linked against an alternative DNS client library. |
| 13519 | |
| 13520 | +----------------------------------------------+ |
| 13521 | |drop_cr|Use: main|Type: boolean|Default: false| |
| 13522 | +----------------------------------------------+ |
| 13523 | |
| 13524 | This is an obsolete option that is now a no-op. It used to affect the way Exim |
| 13525 | handled CR and LF characters in incoming messages. What happens now is |
| 13526 | described in section 47.2. |
| 13527 | |
| 13528 | +-------------------------------------------------------------+ |
| 13529 | |dsn_advertise_hosts|Use: main|Type: host list*|Default: unset| |
| 13530 | +-------------------------------------------------------------+ |
| 13531 | |
| 13532 | DSN extensions (RFC3461) will be advertised in the EHLO message to, and |
| 13533 | accepted from, these hosts. Hosts may use the NOTIFY and ENVID options on RCPT |
| 13534 | TO commands, and RET and ORCPT options on MAIL FROM commands. A NOTIFY=SUCCESS |
| 13535 | option requests success-DSN messages. A NOTIFY= option with no argument |
| 13536 | requests that no delay or failure DSNs are sent. |
| 13537 | |
| 13538 | +---------------------------------------------------+ |
| 13539 | |dsn_from|Use: main|Type: string*|Default: see below| |
| 13540 | +---------------------------------------------------+ |
| 13541 | |
| 13542 | This option can be used to vary the contents of From: header lines in bounces |
| 13543 | and other automatically generated messages ("Delivery Status Notifications" - |
| 13544 | hence the name of the option). The default setting is: |
| 13545 | |
| 13546 | dsn_from = Mail Delivery System <Mailer-Daemon@$qualify_domain> |
| 13547 | |
| 13548 | The value is expanded every time it is needed. If the expansion fails, a panic |
| 13549 | is logged, and the default value is used. |
| 13550 | |
| 13551 | +--------------------------------------------------------+ |
| 13552 | |envelope_to_remove|Use: main|Type: boolean|Default: true| |
| 13553 | +--------------------------------------------------------+ |
| 13554 | |
| 13555 | Exim's transports have an option for adding an Envelope-to: header to a message |
| 13556 | when it is delivered, in exactly the same way as Return-path: is handled. |
| 13557 | Envelope-to: records the original recipient address from the message's envelope |
| 13558 | that caused the delivery to happen. Such headers should not be present in |
| 13559 | incoming messages, and this option causes them to be removed at the time the |
| 13560 | message is received, to avoid any problems that might occur when a delivered |
| 13561 | message is subsequently sent on to some other recipient. |
| 13562 | |
| 13563 | +-------------------------------------------------------+ |
| 13564 | |errors_copy|Use: main|Type: string list*|Default: unset| |
| 13565 | +-------------------------------------------------------+ |
| 13566 | |
| 13567 | Setting this option causes Exim to send bcc copies of bounce messages that it |
| 13568 | generates to other addresses. Note: This does not apply to bounce messages |
| 13569 | coming from elsewhere. The value of the option is a colon-separated list of |
| 13570 | items. Each item consists of a pattern, terminated by white space, followed by |
| 13571 | a comma-separated list of email addresses. If a pattern contains spaces, it |
| 13572 | must be enclosed in double quotes. |
| 13573 | |
| 13574 | Each pattern is processed in the same way as a single item in an address list |
| 13575 | (see section 10.19). When a pattern matches the recipient of the bounce |
| 13576 | message, the message is copied to the addresses on the list. The items are |
| 13577 | scanned in order, and once a matching one is found, no further items are |
| 13578 | examined. For example: |
| 13579 | |
| 13580 | errors_copy = spqr@mydomain postmaster@mydomain.example :\ |
| 13581 | rqps@mydomain hostmaster@mydomain.example,\ |
| 13582 | postmaster@mydomain.example |
| 13583 | |
| 13584 | The address list is expanded before use. The expansion variables $local_part |
| 13585 | and $domain are set from the original recipient of the error message, and if |
| 13586 | there was any wildcard matching in the pattern, the expansion variables $0, $1, |
| 13587 | etc. are set in the normal way. |
| 13588 | |
| 13589 | +-----------------------------------------------------+ |
| 13590 | |errors_reply_to|Use: main|Type: string|Default: unset| |
| 13591 | +-----------------------------------------------------+ |
| 13592 | |
| 13593 | By default, Exim's bounce and delivery warning messages contain the header line |
| 13594 | |
| 13595 | From: Mail Delivery System <Mailer-Daemon@qualify-domain> |
| 13596 | |
| 13597 | where qualify-domain is the value of the qualify_domain option. A warning |
| 13598 | message that is generated by the quota_warn_message option in an appendfile |
| 13599 | transport may contain its own From: header line that overrides the default. |
| 13600 | |
| 13601 | Experience shows that people reply to bounce messages. If the errors_reply_to |
| 13602 | option is set, a Reply-To: header is added to bounce and warning messages. For |
| 13603 | example: |
| 13604 | |
| 13605 | errors_reply_to = postmaster@my.domain.example |
| 13606 | |
| 13607 | The value of the option is not expanded. It must specify a valid RFC 2822 |
| 13608 | address. However, if a warning message that is generated by the |
| 13609 | quota_warn_message option in an appendfile transport contain its own Reply-To: |
| 13610 | header line, the value of the errors_reply_to option is not used. |
| 13611 | |
| 13612 | +---------------------------------------------------+ |
| 13613 | |event_action|Use: main|Type: string*|Default: unset| |
| 13614 | +---------------------------------------------------+ |
| 13615 | |
| 13616 | This option declares a string to be expanded for Exim's events mechanism. For |
| 13617 | details see chapter 60. |
| 13618 | |
| 13619 | +------------------------------------------------------------------+ |
| 13620 | |exim_group|Use: main|Type: string|Default: compile-time configured| |
| 13621 | +------------------------------------------------------------------+ |
| 13622 | |
| 13623 | This option changes the gid under which Exim runs when it gives up root |
| 13624 | privilege. The default value is compiled into the binary. The value of this |
| 13625 | option is used only when exim_user is also set. Unless it consists entirely of |
| 13626 | digits, the string is looked up using getgrnam(), and failure causes a |
| 13627 | configuration error. See chapter 55 for a discussion of security issues. |
| 13628 | |
| 13629 | +---------------------------------------------------+ |
| 13630 | |exim_path|Use: main|Type: string|Default: see below| |
| 13631 | +---------------------------------------------------+ |
| 13632 | |
| 13633 | This option specifies the path name of the Exim binary, which is used when Exim |
| 13634 | needs to re-exec itself. The default is set up to point to the file exim in the |
| 13635 | directory configured at compile time by the BIN_DIRECTORY setting. It is |
| 13636 | necessary to change exim_path if, exceptionally, Exim is run from some other |
| 13637 | place. Warning: Do not use a macro to define the value of this option, because |
| 13638 | you will break those Exim utilities that scan the configuration file to find |
| 13639 | where the binary is. (They then use the -bP option to extract option settings |
| 13640 | such as the value of spool_directory.) |
| 13641 | |
| 13642 | +-----------------------------------------------------------------+ |
| 13643 | |exim_user|Use: main|Type: string|Default: compile-time configured| |
| 13644 | +-----------------------------------------------------------------+ |
| 13645 | |
| 13646 | This option changes the uid under which Exim runs when it gives up root |
| 13647 | privilege. The default value is compiled into the binary. Ownership of the run |
| 13648 | time configuration file and the use of the -C and -D command line options is |
| 13649 | checked against the values in the binary, not what is set here. |
| 13650 | |
| 13651 | Unless it consists entirely of digits, the string is looked up using getpwnam() |
| 13652 | , and failure causes a configuration error. If exim_group is not also supplied, |
| 13653 | the gid is taken from the result of getpwnam() if it is used. See chapter 55 |
| 13654 | for a discussion of security issues. |
| 13655 | |
| 13656 | +-----------------------------------------------------------------+ |
| 13657 | |extra_local_interfaces|Use: main|Type: string list|Default: unset| |
| 13658 | +-----------------------------------------------------------------+ |
| 13659 | |
| 13660 | This option defines network interfaces that are to be considered local when |
| 13661 | routing, but which are not used for listening by the daemon. See section 13.8 |
| 13662 | for details. |
| 13663 | |
| 13664 | +------------------------------------------------------------------------+ |
| 13665 | |extract_addresses_remove_arguments|Use: main|Type: boolean|Default: true| |
| 13666 | +------------------------------------------------------------------------+ |
| 13667 | |
| 13668 | According to some Sendmail documentation (Sun, IRIX, HP-UX), if any addresses |
| 13669 | are present on the command line when the -t option is used to build an envelope |
| 13670 | from a message's To:, Cc: and Bcc: headers, the command line addresses are |
| 13671 | removed from the recipients list. This is also how Smail behaves. However, |
| 13672 | other Sendmail documentation (the O'Reilly book) states that command line |
| 13673 | addresses are added to those obtained from the header lines. When |
| 13674 | extract_addresses_remove_arguments is true (the default), Exim subtracts |
| 13675 | argument headers. If it is set false, Exim adds rather than removes argument |
| 13676 | addresses. |
| 13677 | |
| 13678 | +---------------------------------------------------+ |
| 13679 | |finduser_retries|Use: main|Type: integer|Default: 0| |
| 13680 | +---------------------------------------------------+ |
| 13681 | |
| 13682 | On systems running NIS or other schemes in which user and group information is |
| 13683 | distributed from a remote system, there can be times when getpwnam() and |
| 13684 | related functions fail, even when given valid data, because things time out. |
| 13685 | Unfortunately these failures cannot be distinguished from genuine "not found" |
| 13686 | errors. If finduser_retries is set greater than zero, Exim will try that many |
| 13687 | extra times to find a user or a group, waiting for one second between retries. |
| 13688 | |
| 13689 | You should not set this option greater than zero if your user information is in |
| 13690 | a traditional /etc/passwd file, because it will cause Exim needlessly to search |
| 13691 | the file multiple times for non-existent users, and also cause delay. |
| 13692 | |
| 13693 | +-----------------------------------------------------------------------+ |
| 13694 | |freeze_tell|Use: main|Type: string list, comma separated|Default: unset| |
| 13695 | +-----------------------------------------------------------------------+ |
| 13696 | |
| 13697 | On encountering certain errors, or when configured to do so in a system filter, |
| 13698 | ACL, or special router, Exim freezes a message. This means that no further |
| 13699 | delivery attempts take place until an administrator thaws the message, or the |
| 13700 | auto_thaw, ignore_bounce_errors_after, or timeout_frozen_after feature cause it |
| 13701 | to be processed. If freeze_tell is set, Exim generates a warning message |
| 13702 | whenever it freezes something, unless the message it is freezing is a |
| 13703 | locally-generated bounce message. (Without this exception there is the |
| 13704 | possibility of looping.) The warning message is sent to the addresses supplied |
| 13705 | as the comma-separated value of this option. If several of the message's |
| 13706 | addresses cause freezing, only a single message is sent. If the freezing was |
| 13707 | automatic, the reason(s) for freezing can be found in the message log. If you |
| 13708 | configure freezing in a filter or ACL, you must arrange for any logging that |
| 13709 | you require. |
| 13710 | |
| 13711 | +-------------------------------------------------+ |
| 13712 | |gecos_name|Use: main|Type: string*|Default: unset| |
| 13713 | +-------------------------------------------------+ |
| 13714 | |
| 13715 | Some operating systems, notably HP-UX, use the "gecos" field in the system |
| 13716 | password file to hold other information in addition to users' real names. Exim |
| 13717 | looks up this field for use when it is creating Sender: or From: headers. If |
| 13718 | either gecos_pattern or gecos_name are unset, the contents of the field are |
| 13719 | used unchanged, except that, if an ampersand is encountered, it is replaced by |
| 13720 | the user's login name with the first character forced to upper case, since this |
| 13721 | is a convention that is observed on many systems. |
| 13722 | |
| 13723 | When these options are set, gecos_pattern is treated as a regular expression |
| 13724 | that is to be applied to the field (again with & replaced by the login name), |
| 13725 | and if it matches, gecos_name is expanded and used as the user's name. |
| 13726 | |
| 13727 | Numeric variables such as $1, $2, etc. can be used in the expansion to pick up |
| 13728 | sub-fields that were matched by the pattern. In HP-UX, where the user's name |
| 13729 | terminates at the first comma, the following can be used: |
| 13730 | |
| 13731 | gecos_pattern = ([^,]*) |
| 13732 | gecos_name = $1 |
| 13733 | |
| 13734 | +---------------------------------------------------+ |
| 13735 | |gecos_pattern|Use: main|Type: string|Default: unset| |
| 13736 | +---------------------------------------------------+ |
| 13737 | |
| 13738 | See gecos_name above. |
| 13739 | |
| 13740 | +---------------------------------------------------------+ |
| 13741 | |gnutls_compat_mode|Use: main|Type: boolean|Default: unset| |
| 13742 | +---------------------------------------------------------+ |
| 13743 | |
| 13744 | This option controls whether GnuTLS is used in compatibility mode in an Exim |
| 13745 | server. This reduces security slightly, but improves interworking with older |
| 13746 | implementations of TLS. |
| 13747 | |
| 13748 | option gnutls_allow_auto_pkcs11 main boolean unset This option will let GnuTLS |
| 13749 | (2.12.0 or later) autoload PKCS11 modules with the p11-kit configuration files |
| 13750 | in /etc/pkcs11/modules/. |
| 13751 | |
| 13752 | See http://www.gnutls.org/manual/gnutls.html#Smart-cards-and-HSMs for |
| 13753 | documentation. |
| 13754 | |
| 13755 | +---------------------------------------------------------+ |
| 13756 | |headers_charset|Use: main|Type: string|Default: see below| |
| 13757 | +---------------------------------------------------------+ |
| 13758 | |
| 13759 | This option sets a default character set for translating from encoded MIME |
| 13760 | "words" in header lines, when referenced by an $h_xxx expansion item. The |
| 13761 | default is the value of HEADERS_CHARSET in Local/Makefile. The ultimate default |
| 13762 | is ISO-8859-1. For more details see the description of header insertions in |
| 13763 | section 11.5. |
| 13764 | |
| 13765 | +---------------------------------------------------------+ |
| 13766 | |header_maxsize|Use: main|Type: integer|Default: see below| |
| 13767 | +---------------------------------------------------------+ |
| 13768 | |
| 13769 | This option controls the overall maximum size of a message's header section. |
| 13770 | The default is the value of HEADER_MAXSIZE in Local/Makefile; the default for |
| 13771 | that is 1M. Messages with larger header sections are rejected. |
| 13772 | |
| 13773 | +------------------------------------------------------+ |
| 13774 | |header_line_maxsize|Use: main|Type: integer|Default: 0| |
| 13775 | +------------------------------------------------------+ |
| 13776 | |
| 13777 | This option limits the length of any individual header line in a message, after |
| 13778 | all the continuations have been joined together. Messages with individual |
| 13779 | header lines that are longer than the limit are rejected. The default value of |
| 13780 | zero means "no limit". |
| 13781 | |
| 13782 | +----------------------------------------------------------------+ |
| 13783 | |helo_accept_junk_hosts|Use: main|Type: host list*|Default: unset| |
| 13784 | +----------------------------------------------------------------+ |
| 13785 | |
| 13786 | Exim checks the syntax of HELO and EHLO commands for incoming SMTP mail, and |
| 13787 | gives an error response for invalid data. Unfortunately, there are some SMTP |
| 13788 | clients that send syntactic junk. They can be accommodated by setting this |
| 13789 | option. Note that this is a syntax check only. See helo_verify_hosts if you |
| 13790 | want to do semantic checking. See also helo_allow_chars for a way of extending |
| 13791 | the permitted character set. |
| 13792 | |
| 13793 | +------------------------------------------------------+ |
| 13794 | |helo_allow_chars|Use: main|Type: string|Default: unset| |
| 13795 | +------------------------------------------------------+ |
| 13796 | |
| 13797 | This option can be set to a string of rogue characters that are permitted in |
| 13798 | all EHLO and HELO names in addition to the standard letters, digits, hyphens, |
| 13799 | and dots. If you really must allow underscores, you can set |
| 13800 | |
| 13801 | helo_allow_chars = _ |
| 13802 | |
| 13803 | Note that the value is one string, not a list. |
| 13804 | |
| 13805 | +-----------------------------------------------------------------+ |
| 13806 | |helo_lookup_domains|Use: main|Type: domain list*|Default: "@:@[]"| |
| 13807 | +-----------------------------------------------------------------+ |
| 13808 | |
| 13809 | If the domain given by a client in a HELO or EHLO command matches this list, a |
| 13810 | reverse lookup is done in order to establish the host's true name. The default |
| 13811 | forces a lookup if the client host gives the server's name or any of its IP |
| 13812 | addresses (in brackets), something that broken clients have been seen to do. |
| 13813 | |
| 13814 | +---------------------------------------------------------------+ |
| 13815 | |helo_try_verify_hosts|Use: main|Type: host list*|Default: unset| |
| 13816 | +---------------------------------------------------------------+ |
| 13817 | |
| 13818 | By default, Exim just checks the syntax of HELO and EHLO commands (see |
| 13819 | helo_accept_junk_hosts and helo_allow_chars). However, some sites like to do |
| 13820 | more extensive checking of the data supplied by these commands. The ACL |
| 13821 | condition "verify = helo" is provided to make this possible. Formerly, it was |
| 13822 | necessary also to set this option (helo_try_verify_hosts) to force the check to |
| 13823 | occur. From release 4.53 onwards, this is no longer necessary. If the check has |
| 13824 | not been done before "verify = helo" is encountered, it is done at that time. |
| 13825 | Consequently, this option is obsolete. Its specification is retained here for |
| 13826 | backwards compatibility. |
| 13827 | |
| 13828 | When an EHLO or HELO command is received, if the calling host matches |
| 13829 | helo_try_verify_hosts, Exim checks that the host name given in the HELO or EHLO |
| 13830 | command either: |
| 13831 | |
| 13832 | * is an IP literal matching the calling address of the host, or |
| 13833 | |
| 13834 | * matches the host name that Exim obtains by doing a reverse lookup of the |
| 13835 | calling host address, or |
| 13836 | |
| 13837 | * when looked up in DNS yields the calling host address. |
| 13838 | |
| 13839 | However, the EHLO or HELO command is not rejected if any of the checks fail. |
| 13840 | Processing continues, but the result of the check is remembered, and can be |
| 13841 | detected later in an ACL by the "verify = helo" condition. |
| 13842 | |
| 13843 | If DNS was used for successful verification, the variable $helo_verify_dnssec |
| 13844 | records the DNSSEC status of the lookups. |
| 13845 | |
| 13846 | +-----------------------------------------------------------+ |
| 13847 | |helo_verify_hosts|Use: main|Type: host list*|Default: unset| |
| 13848 | +-----------------------------------------------------------+ |
| 13849 | |
| 13850 | Like helo_try_verify_hosts, this option is obsolete, and retained only for |
| 13851 | backwards compatibility. For hosts that match this option, Exim checks the host |
| 13852 | name given in the HELO or EHLO in the same way as for helo_try_verify_hosts. If |
| 13853 | the check fails, the HELO or EHLO command is rejected with a 550 error, and |
| 13854 | entries are written to the main and reject logs. If a MAIL command is received |
| 13855 | before EHLO or HELO, it is rejected with a 503 error. |
| 13856 | |
| 13857 | +--------------------------------------------------------+ |
| 13858 | |hold_domains|Use: main|Type: domain list*|Default: unset| |
| 13859 | +--------------------------------------------------------+ |
| 13860 | |
| 13861 | This option allows mail for particular domains to be held on the queue |
| 13862 | manually. The option is overridden if a message delivery is forced with the -M, |
| 13863 | -qf, -Rf or -Sf options, and also while testing or verifying addresses using |
| 13864 | -bt or -bv. Otherwise, if a domain matches an item in hold_domains, no routing |
| 13865 | or delivery for that address is done, and it is deferred every time the message |
| 13866 | is looked at. |
| 13867 | |
| 13868 | This option is intended as a temporary operational measure for delaying the |
| 13869 | delivery of mail while some problem is being sorted out, or some new |
| 13870 | configuration tested. If you just want to delay the processing of some domains |
| 13871 | until a queue run occurs, you should use queue_domains or queue_smtp_domains, |
| 13872 | not hold_domains. |
| 13873 | |
| 13874 | A setting of hold_domains does not override Exim's code for removing messages |
| 13875 | from the queue if they have been there longer than the longest retry time in |
| 13876 | any retry rule. If you want to hold messages for longer than the normal retry |
| 13877 | times, insert a dummy retry rule with a long retry time. |
| 13878 | |
| 13879 | +-----------------------------------------------------+ |
| 13880 | |host_lookup|Use: main|Type: host list*|Default: unset| |
| 13881 | +-----------------------------------------------------+ |
| 13882 | |
| 13883 | Exim does not look up the name of a calling host from its IP address unless it |
| 13884 | is required to compare against some host list, or the host matches |
| 13885 | helo_try_verify_hosts or helo_verify_hosts, or the host matches this option |
| 13886 | (which normally contains IP addresses rather than host names). The default |
| 13887 | configuration file contains |
| 13888 | |
| 13889 | host_lookup = * |
| 13890 | |
| 13891 | which causes a lookup to happen for all hosts. If the expense of these lookups |
| 13892 | is felt to be too great, the setting can be changed or removed. |
| 13893 | |
| 13894 | After a successful reverse lookup, Exim does a forward lookup on the name it |
| 13895 | has obtained, to verify that it yields the IP address that it started with. If |
| 13896 | this check fails, Exim behaves as if the name lookup failed. |
| 13897 | |
| 13898 | After any kind of failure, the host name (in $sender_host_name) remains unset, |
| 13899 | and $host_lookup_failed is set to the string "1". See also |
| 13900 | dns_again_means_nonexist, helo_lookup_domains, and "verify = |
| 13901 | reverse_host_lookup" in ACLs. |
| 13902 | |
| 13903 | +---------------------------------------------------------------------+ |
| 13904 | |host_lookup_order|Use: main|Type: string list|Default: "bydns:byaddr"| |
| 13905 | +---------------------------------------------------------------------+ |
| 13906 | |
| 13907 | This option specifies the order of different lookup methods when Exim is trying |
| 13908 | to find a host name from an IP address. The default is to do a DNS lookup |
| 13909 | first, and then to try a local lookup (using gethostbyaddr() or equivalent) if |
| 13910 | that fails. You can change the order of these lookups, or omit one entirely, if |
| 13911 | you want. |
| 13912 | |
| 13913 | Warning: The "byaddr" method does not always yield aliases when there are |
| 13914 | multiple PTR records in the DNS and the IP address is not listed in /etc/hosts. |
| 13915 | Different operating systems give different results in this case. That is why |
| 13916 | the default tries a DNS lookup first. |
| 13917 | |
| 13918 | +----------------------------------------------------------------+ |
| 13919 | |host_reject_connection|Use: main|Type: host list*|Default: unset| |
| 13920 | +----------------------------------------------------------------+ |
| 13921 | |
| 13922 | If this option is set, incoming SMTP calls from the hosts listed are rejected |
| 13923 | as soon as the connection is made. This option is obsolete, and retained only |
| 13924 | for backward compatibility, because nowadays the ACL specified by |
| 13925 | acl_smtp_connect can also reject incoming connections immediately. |
| 13926 | |
| 13927 | The ability to give an immediate rejection (either by this option or using an |
| 13928 | ACL) is provided for use in unusual cases. Many hosts will just try again, |
| 13929 | sometimes without much delay. Normally, it is better to use an ACL to reject |
| 13930 | incoming messages at a later stage, such as after RCPT commands. See chapter 43 |
| 13931 | . |
| 13932 | |
| 13933 | +----------------------------------------------------------------+ |
| 13934 | |hosts_connection_nolog|Use: main|Type: host list*|Default: unset| |
| 13935 | +----------------------------------------------------------------+ |
| 13936 | |
| 13937 | This option defines a list of hosts for which connection logging does not |
| 13938 | happen, even though the smtp_connection log selector is set. For example, you |
| 13939 | might want not to log SMTP connections from local processes, or from 127.0.0.1, |
| 13940 | or from your local LAN. This option is consulted in the main loop of the |
| 13941 | daemon; you should therefore strive to restrict its value to a short inline |
| 13942 | list of IP addresses and networks. To disable logging SMTP connections from |
| 13943 | local processes, you must create a host list with an empty item. For example: |
| 13944 | |
| 13945 | hosts_connection_nolog = : |
| 13946 | |
| 13947 | If the smtp_connection log selector is not set, this option has no effect. |
| 13948 | |
| 13949 | +-----------------------------------------------------+ |
| 13950 | |hosts_proxy|Use: main|Type: host list*|Default: unset| |
| 13951 | +-----------------------------------------------------+ |
| 13952 | |
| 13953 | This option enables use of Proxy Protocol proxies for incoming connections. For |
| 13954 | details see section 58.1. |
| 13955 | |
| 13956 | +----------------------------------------------------------------+ |
| 13957 | |hosts_treat_as_local|Use: main|Type: domain list*|Default: unset| |
| 13958 | +----------------------------------------------------------------+ |
| 13959 | |
| 13960 | If this option is set, any host names that match the domain list are treated as |
| 13961 | if they were the local host when Exim is scanning host lists obtained from MX |
| 13962 | records or other sources. Note that the value of this option is a domain list, |
| 13963 | not a host list, because it is always used to check host names, not IP |
| 13964 | addresses. |
| 13965 | |
| 13966 | This option also applies when Exim is matching the special items "@mx_any", |
| 13967 | "@mx_primary", and "@mx_secondary" in a domain list (see section 10.8), and |
| 13968 | when checking the hosts option in the smtp transport for the local host (see |
| 13969 | the allow_localhost option in that transport). See also local_interfaces, |
| 13970 | extra_local_interfaces, and chapter 13, which contains a discussion about local |
| 13971 | network interfaces and recognizing the local host. |
| 13972 | |
| 13973 | +--------------------------------------------------------+ |
| 13974 | |ibase_servers|Use: main|Type: string list|Default: unset| |
| 13975 | +--------------------------------------------------------+ |
| 13976 | |
| 13977 | This option provides a list of InterBase servers and associated connection |
| 13978 | data, to be used in conjunction with ibase lookups (see section 9.22). The |
| 13979 | option is available only if Exim has been built with InterBase support. |
| 13980 | |
| 13981 | +------------------------------------------------------------+ |
| 13982 | |ignore_bounce_errors_after|Use: main|Type: time|Default: 10w| |
| 13983 | +------------------------------------------------------------+ |
| 13984 | |
| 13985 | This option affects the processing of bounce messages that cannot be delivered, |
| 13986 | that is, those that suffer a permanent delivery failure. (Bounce messages that |
| 13987 | suffer temporary delivery failures are of course retried in the usual way.) |
| 13988 | |
| 13989 | After a permanent delivery failure, bounce messages are frozen, because there |
| 13990 | is no sender to whom they can be returned. When a frozen bounce message has |
| 13991 | been on the queue for more than the given time, it is unfrozen at the next |
| 13992 | queue run, and a further delivery is attempted. If delivery fails again, the |
| 13993 | bounce message is discarded. This makes it possible to keep failed bounce |
| 13994 | messages around for a shorter time than the normal maximum retry time for |
| 13995 | frozen messages. For example, |
| 13996 | |
| 13997 | ignore_bounce_errors_after = 12h |
| 13998 | |
| 13999 | retries failed bounce message deliveries after 12 hours, discarding any further |
| 14000 | failures. If the value of this option is set to a zero time period, bounce |
| 14001 | failures are discarded immediately. Setting a very long time (as in the default |
| 14002 | value) has the effect of disabling this option. For ways of automatically |
| 14003 | dealing with other kinds of frozen message, see auto_thaw and |
| 14004 | timeout_frozen_after. |
| 14005 | |
| 14006 | +---------------------------------------------------------------+ |
| 14007 | |ignore_fromline_hosts|Use: main|Type: host list*|Default: unset| |
| 14008 | +---------------------------------------------------------------+ |
| 14009 | |
| 14010 | Some broken SMTP clients insist on sending a UUCP-like "From " line before the |
| 14011 | headers of a message. By default this is treated as the start of the message's |
| 14012 | body, which means that any following headers are not recognized as such. Exim |
| 14013 | can be made to ignore it by setting ignore_fromline_hosts to match those hosts |
| 14014 | that insist on sending it. If the sender is actually a local process rather |
| 14015 | than a remote host, and is using -bs to inject the messages, |
| 14016 | ignore_fromline_local must be set to achieve this effect. |
| 14017 | |
| 14018 | +------------------------------------------------------------+ |
| 14019 | |ignore_fromline_local|Use: main|Type: boolean|Default: false| |
| 14020 | +------------------------------------------------------------+ |
| 14021 | |
| 14022 | See ignore_fromline_hosts above. |
| 14023 | |
| 14024 | +-----------------------------------------------------------+ |
| 14025 | |keep_environment|Use: main|Type: string list|Default: unset| |
| 14026 | +-----------------------------------------------------------+ |
| 14027 | |
| 14028 | This option contains a string list of environment variables to keep. You have |
| 14029 | to trust these variables or you have to be sure that these variables do not |
| 14030 | impose any security risk. Keep in mind that during the startup phase Exim is |
| 14031 | running with an effective UID 0 in most installations. As the default value is |
| 14032 | an empty list, the default environment for using libraries, running embedded |
| 14033 | Perl code, or running external binaries is empty, and does not not even contain |
| 14034 | PATH or HOME. |
| 14035 | |
| 14036 | Actually the list is interpreted as a list of patterns (10.1), except that it |
| 14037 | is not expanded first. |
| 14038 | |
| 14039 | WARNING: Macro substitution is still done first, so having a macro FOO and |
| 14040 | having FOO_HOME in your keep_environment option may have unexpected results. |
| 14041 | You may work around this using a regular expression that does not match the |
| 14042 | macro name: ^[F]OO_HOME$. |
| 14043 | |
| 14044 | Current versions of Exim issue a warning during startup if you do not mention |
| 14045 | keep_environment in your runtime configuration file and if your current |
| 14046 | environment is not empty. Future versions may not issue that warning anymore. |
| 14047 | |
| 14048 | See the add_environment main config option for a way to set environment |
| 14049 | variables to a fixed value. The environment for pipe transports is handled |
| 14050 | separately, see section 29.4 for details. |
| 14051 | |
| 14052 | +-----------------------------------------------+ |
| 14053 | |keep_malformed|Use: main|Type: time|Default: 4d| |
| 14054 | +-----------------------------------------------+ |
| 14055 | |
| 14056 | This option specifies the length of time to keep messages whose spool files |
| 14057 | have been corrupted in some way. This should, of course, never happen. At the |
| 14058 | next attempt to deliver such a message, it gets removed. The incident is |
| 14059 | logged. |
| 14060 | |
| 14061 | +------------------------------------------------------+ |
| 14062 | |ldap_ca_cert_dir|Use: main|Type: string|Default: unset| |
| 14063 | +------------------------------------------------------+ |
| 14064 | |
| 14065 | This option indicates which directory contains CA certificates for verifying a |
| 14066 | TLS certificate presented by an LDAP server. While Exim does not provide a |
| 14067 | default value, your SSL library may. Analogous to tls_verify_certificates but |
| 14068 | as a client-side option for LDAP and constrained to be a directory. |
| 14069 | |
| 14070 | +-------------------------------------------------------+ |
| 14071 | |ldap_ca_cert_file|Use: main|Type: string|Default: unset| |
| 14072 | +-------------------------------------------------------+ |
| 14073 | |
| 14074 | This option indicates which file contains CA certificates for verifying a TLS |
| 14075 | certificate presented by an LDAP server. While Exim does not provide a default |
| 14076 | value, your SSL library may. Analogous to tls_verify_certificates but as a |
| 14077 | client-side option for LDAP and constrained to be a file. |
| 14078 | |
| 14079 | +----------------------------------------------------+ |
| 14080 | |ldap_cert_file|Use: main|Type: string|Default: unset| |
| 14081 | +----------------------------------------------------+ |
| 14082 | |
| 14083 | This option indicates which file contains an TLS client certificate which Exim |
| 14084 | should present to the LDAP server during TLS negotiation. Should be used |
| 14085 | together with ldap_cert_key. |
| 14086 | |
| 14087 | +---------------------------------------------------+ |
| 14088 | |ldap_cert_key|Use: main|Type: string|Default: unset| |
| 14089 | +---------------------------------------------------+ |
| 14090 | |
| 14091 | This option indicates which file contains the secret/private key to use to |
| 14092 | prove identity to the LDAP server during TLS negotiation. Should be used |
| 14093 | together with ldap_cert_file, which contains the identity to be proven. |
| 14094 | |
| 14095 | +-------------------------------------------------------+ |
| 14096 | |ldap_cipher_suite|Use: main|Type: string|Default: unset| |
| 14097 | +-------------------------------------------------------+ |
| 14098 | |
| 14099 | This controls the TLS cipher-suite negotiation during TLS negotiation with the |
| 14100 | LDAP server. See 42.4 for more details of the format of cipher-suite options |
| 14101 | with OpenSSL (as used by LDAP client libraries). |
| 14102 | |
| 14103 | +---------------------------------------------------------------+ |
| 14104 | |ldap_default_servers|Use: main|Type: string list|Default: unset| |
| 14105 | +---------------------------------------------------------------+ |
| 14106 | |
| 14107 | This option provides a list of LDAP servers which are tried in turn when an |
| 14108 | LDAP query does not contain a server. See section 9.15 for details of LDAP |
| 14109 | queries. This option is available only when Exim has been built with LDAP |
| 14110 | support. |
| 14111 | |
| 14112 | +--------------------------------------------------------+ |
| 14113 | |ldap_require_cert|Use: main|Type: string|Default: unset.| |
| 14114 | +--------------------------------------------------------+ |
| 14115 | |
| 14116 | This should be one of the values "hard", "demand", "allow", "try" or "never". A |
| 14117 | value other than one of these is interpreted as "never". See the entry |
| 14118 | "TLS_REQCERT" in your system man page for ldap.conf(5). Although Exim does not |
| 14119 | set a default, the LDAP library probably defaults to hard/demand. |
| 14120 | |
| 14121 | +-----------------------------------------------------+ |
| 14122 | |ldap_start_tls|Use: main|Type: boolean|Default: false| |
| 14123 | +-----------------------------------------------------+ |
| 14124 | |
| 14125 | If set, Exim will attempt to negotiate TLS with the LDAP server when connecting |
| 14126 | on a regular LDAP port. This is the LDAP equivalent of SMTP's "STARTTLS". This |
| 14127 | is distinct from using "ldaps", which is the LDAP form of SSL-on-connect. In |
| 14128 | the event of failure to negotiate TLS, the action taken is controlled by |
| 14129 | ldap_require_cert. |
| 14130 | |
| 14131 | This option is ignored for "ldapi" connections. |
| 14132 | |
| 14133 | +---------------------------------------------------+ |
| 14134 | |ldap_version|Use: main|Type: integer|Default: unset| |
| 14135 | +---------------------------------------------------+ |
| 14136 | |
| 14137 | This option can be used to force Exim to set a specific protocol version for |
| 14138 | LDAP. If it option is unset, it is shown by the -bP command line option as -1. |
| 14139 | When this is the case, the default is 3 if LDAP_VERSION3 is defined in the LDAP |
| 14140 | headers; otherwise it is 2. This option is available only when Exim has been |
| 14141 | built with LDAP support. |
| 14142 | |
| 14143 | +------------------------------------------------------+ |
| 14144 | |local_from_check|Use: main|Type: boolean|Default: true| |
| 14145 | +------------------------------------------------------+ |
| 14146 | |
| 14147 | When a message is submitted locally (that is, not over a TCP/IP connection) by |
| 14148 | an untrusted user, Exim removes any existing Sender: header line, and checks |
| 14149 | that the From: header line matches the login of the calling user and the domain |
| 14150 | specified by qualify_domain. |
| 14151 | |
| 14152 | Note: An unqualified address (no domain) in the From: header in a locally |
| 14153 | submitted message is automatically qualified by Exim, unless the -bnq command |
| 14154 | line option is used. |
| 14155 | |
| 14156 | You can use local_from_prefix and local_from_suffix to permit affixes on the |
| 14157 | local part. If the From: header line does not match, Exim adds a Sender: header |
| 14158 | with an address constructed from the calling user's login and the default |
| 14159 | qualify domain. |
| 14160 | |
| 14161 | If local_from_check is set false, the From: header check is disabled, and no |
| 14162 | Sender: header is ever added. If, in addition, you want to retain Sender: |
| 14163 | header lines supplied by untrusted users, you must also set local_sender_retain |
| 14164 | to be true. |
| 14165 | |
| 14166 | These options affect only the header lines in the message. The envelope sender |
| 14167 | is still forced to be the login id at the qualify domain unless |
| 14168 | untrusted_set_sender permits the user to supply an envelope sender. |
| 14169 | |
| 14170 | For messages received over TCP/IP, an ACL can specify "submission mode" to |
| 14171 | request similar header line checking. See section 47.16, which has more details |
| 14172 | about Sender: processing. |
| 14173 | |
| 14174 | +-------------------------------------------------------+ |
| 14175 | |local_from_prefix|Use: main|Type: string|Default: unset| |
| 14176 | +-------------------------------------------------------+ |
| 14177 | |
| 14178 | When Exim checks the From: header line of locally submitted messages for |
| 14179 | matching the login id (see local_from_check above), it can be configured to |
| 14180 | ignore certain prefixes and suffixes in the local part of the address. This is |
| 14181 | done by setting local_from_prefix and/or local_from_suffix to appropriate |
| 14182 | lists, in the same form as the local_part_prefix and local_part_suffix router |
| 14183 | options (see chapter 15). For example, if |
| 14184 | |
| 14185 | local_from_prefix = *- |
| 14186 | |
| 14187 | is set, a From: line containing |
| 14188 | |
| 14189 | From: anything-user@your.domain.example |
| 14190 | |
| 14191 | will not cause a Sender: header to be added if user@your.domain.example matches |
| 14192 | the actual sender address that is constructed from the login name and qualify |
| 14193 | domain. |
| 14194 | |
| 14195 | +-------------------------------------------------------+ |
| 14196 | |local_from_suffix|Use: main|Type: string|Default: unset| |
| 14197 | +-------------------------------------------------------+ |
| 14198 | |
| 14199 | See local_from_prefix above. |
| 14200 | |
| 14201 | +---------------------------------------------------------------+ |
| 14202 | |local_interfaces|Use: main|Type: string list|Default: see below| |
| 14203 | +---------------------------------------------------------------+ |
| 14204 | |
| 14205 | This option controls which network interfaces are used by the daemon for |
| 14206 | listening; they are also used to identify the local host when routing. Chapter |
| 14207 | 13 contains a full description of this option and the related options |
| 14208 | daemon_smtp_ports, extra_local_interfaces, hosts_treat_as_local, and |
| 14209 | tls_on_connect_ports. The default value for local_interfaces is |
| 14210 | |
| 14211 | local_interfaces = 0.0.0.0 |
| 14212 | |
| 14213 | when Exim is built without IPv6 support; otherwise it is |
| 14214 | |
| 14215 | local_interfaces = <; ::0 ; 0.0.0.0 |
| 14216 | |
| 14217 | +---------------------------------------------------+ |
| 14218 | |local_scan_timeout|Use: main|Type: time|Default: 5m| |
| 14219 | +---------------------------------------------------+ |
| 14220 | |
| 14221 | This timeout applies to the local_scan() function (see chapter 45). Zero means |
| 14222 | "no timeout". If the timeout is exceeded, the incoming message is rejected with |
| 14223 | a temporary error if it is an SMTP message. For a non-SMTP message, the message |
| 14224 | is dropped and Exim ends with a non-zero code. The incident is logged on the |
| 14225 | main and reject logs. |
| 14226 | |
| 14227 | +----------------------------------------------------------+ |
| 14228 | |local_sender_retain|Use: main|Type: boolean|Default: false| |
| 14229 | +----------------------------------------------------------+ |
| 14230 | |
| 14231 | When a message is submitted locally (that is, not over a TCP/IP connection) by |
| 14232 | an untrusted user, Exim removes any existing Sender: header line. If you do not |
| 14233 | want this to happen, you must set local_sender_retain, and you must also set |
| 14234 | local_from_check to be false (Exim will complain if you do not). See also the |
| 14235 | ACL modifier "control = suppress_local_fixups". Section 47.16 has more details |
| 14236 | about Sender: processing. |
| 14237 | |
| 14238 | +-------------------------------------------------------+ |
| 14239 | |localhost_number|Use: main|Type: string*|Default: unset| |
| 14240 | +-------------------------------------------------------+ |
| 14241 | |
| 14242 | Exim's message ids are normally unique only within the local host. If |
| 14243 | uniqueness among a set of hosts is required, each host must set a different |
| 14244 | value for the localhost_number option. The string is expanded immediately after |
| 14245 | reading the configuration file (so that a number can be computed from the host |
| 14246 | name, for example) and the result of the expansion must be a number in the |
| 14247 | range 0-16 (or 0-10 on operating systems with case-insensitive file systems). |
| 14248 | This is available in subsequent string expansions via the variable |
| 14249 | $localhost_number. When localhost_number is set, the final two characters of |
| 14250 | the message id, instead of just being a fractional part of the time, are |
| 14251 | computed from the time and the local host number as described in section 3.4. |
| 14252 | |
| 14253 | +-----------------------------------------------------------------------+ |
| 14254 | |log_file_path|Use: main|Type: string list*|Default: set at compile time| |
| 14255 | +-----------------------------------------------------------------------+ |
| 14256 | |
| 14257 | This option sets the path which is used to determine the names of Exim's log |
| 14258 | files, or indicates that logging is to be to syslog, or both. It is expanded |
| 14259 | when Exim is entered, so it can, for example, contain a reference to the host |
| 14260 | name. If no specific path is set for the log files at compile or run time, or |
| 14261 | if the option is unset at run time (i.e. "log_file_path = ") they are written |
| 14262 | in a sub-directory called log in Exim's spool directory. Chapter 52 contains |
| 14263 | further details about Exim's logging, and section 52.1 describes how the |
| 14264 | contents of log_file_path are used. If this string is fixed at your |
| 14265 | installation (contains no expansion variables) it is recommended that you do |
| 14266 | not set this option in the configuration file, but instead supply the path |
| 14267 | using LOG_FILE_PATH in Local/Makefile so that it is available to Exim for |
| 14268 | logging errors detected early on - in particular, failure to read the |
| 14269 | configuration file. |
| 14270 | |
| 14271 | +--------------------------------------------------+ |
| 14272 | |log_selector|Use: main|Type: string|Default: unset| |
| 14273 | +--------------------------------------------------+ |
| 14274 | |
| 14275 | This option can be used to reduce or increase the number of things that Exim |
| 14276 | writes to its log files. Its argument is made up of names preceded by plus or |
| 14277 | minus characters. For example: |
| 14278 | |
| 14279 | log_selector = +arguments -retry_defer |
| 14280 | |
| 14281 | A list of possible names and what they control is given in the chapter on |
| 14282 | logging, in section 52.15. |
| 14283 | |
| 14284 | +---------------------------------------------------+ |
| 14285 | |log_timezone|Use: main|Type: boolean|Default: false| |
| 14286 | +---------------------------------------------------+ |
| 14287 | |
| 14288 | By default, the timestamps on log lines are in local time without the timezone. |
| 14289 | This means that if your timezone changes twice a year, the timestamps in log |
| 14290 | lines are ambiguous for an hour when the clocks go back. One way of avoiding |
| 14291 | this problem is to set the timezone to UTC. An alternative is to set |
| 14292 | log_timezone true. This turns on the addition of the timezone offset to |
| 14293 | timestamps in log lines. Turning on this option can add quite a lot to the size |
| 14294 | of log files because each line is extended by 6 characters. Note that the |
| 14295 | $tod_log variable contains the log timestamp without the zone, but there is |
| 14296 | another variable called $tod_zone that contains just the timezone offset. |
| 14297 | |
| 14298 | +---------------------------------------------------+ |
| 14299 | |lookup_open_max|Use: main|Type: integer|Default: 25| |
| 14300 | +---------------------------------------------------+ |
| 14301 | |
| 14302 | This option limits the number of simultaneously open files for single-key |
| 14303 | lookups that use regular files (that is, lsearch, dbm, and cdb). Exim normally |
| 14304 | keeps these files open during routing, because often the same file is required |
| 14305 | several times. If the limit is reached, Exim closes the least recently used |
| 14306 | file. Note that if you are using the ndbm library, it actually opens two files |
| 14307 | for each logical DBM database, though it still counts as one for the purposes |
| 14308 | of lookup_open_max. If you are getting "too many open files" errors with NDBM, |
| 14309 | you need to reduce the value of lookup_open_max. |
| 14310 | |
| 14311 | +------------------------------------------------------+ |
| 14312 | |max_username_length|Use: main|Type: integer|Default: 0| |
| 14313 | +------------------------------------------------------+ |
| 14314 | |
| 14315 | Some operating systems are broken in that they truncate long arguments to |
| 14316 | getpwnam() to eight characters, instead of returning "no such user". If this |
| 14317 | option is set greater than zero, any attempt to call getpwnam() with an |
| 14318 | argument that is longer behaves as if getpwnam() failed. |
| 14319 | |
| 14320 | +---------------------------------------------------------+ |
| 14321 | |message_body_newlines|Use: main|Type: bool|Default: false| |
| 14322 | +---------------------------------------------------------+ |
| 14323 | |
| 14324 | By default, newlines in the message body are replaced by spaces when setting |
| 14325 | the $message_body and $message_body_end expansion variables. If this option is |
| 14326 | set true, this no longer happens. |
| 14327 | |
| 14328 | +---------------------------------------------------------+ |
| 14329 | |message_body_visible|Use: main|Type: integer|Default: 500| |
| 14330 | +---------------------------------------------------------+ |
| 14331 | |
| 14332 | This option specifies how much of a message's body is to be included in the |
| 14333 | $message_body and $message_body_end expansion variables. |
| 14334 | |
| 14335 | +---------------------------------------------------------------+ |
| 14336 | |message_id_header_domain|Use: main|Type: string*|Default: unset| |
| 14337 | +---------------------------------------------------------------+ |
| 14338 | |
| 14339 | If this option is set, the string is expanded and used as the right hand side |
| 14340 | (domain) of the Message-ID: header that Exim creates if a locally-originated |
| 14341 | incoming message does not have one. "Locally-originated" means "not received |
| 14342 | over TCP/IP." Otherwise, the primary host name is used. Only letters, digits, |
| 14343 | dot and hyphen are accepted; any other characters are replaced by hyphens. If |
| 14344 | the expansion is forced to fail, or if the result is an empty string, the |
| 14345 | option is ignored. |
| 14346 | |
| 14347 | +-------------------------------------------------------------+ |
| 14348 | |message_id_header_text|Use: main|Type: string*|Default: unset| |
| 14349 | +-------------------------------------------------------------+ |
| 14350 | |
| 14351 | If this variable is set, the string is expanded and used to augment the text of |
| 14352 | the Message-id: header that Exim creates if a locally-originated incoming |
| 14353 | message does not have one. The text of this header is required by RFC 2822 to |
| 14354 | take the form of an address. By default, Exim uses its internal message id as |
| 14355 | the local part, and the primary host name as the domain. If this option is set, |
| 14356 | it is expanded, and provided the expansion is not forced to fail, and does not |
| 14357 | yield an empty string, the result is inserted into the header immediately |
| 14358 | before the @, separated from the internal message id by a dot. Any characters |
| 14359 | that are illegal in an address are automatically converted into hyphens. This |
| 14360 | means that variables such as $tod_log can be used, because the spaces and |
| 14361 | colons will become hyphens. |
| 14362 | |
| 14363 | +--------------------------------------------------+ |
| 14364 | |message_logs|Use: main|Type: boolean|Default: true| |
| 14365 | +--------------------------------------------------+ |
| 14366 | |
| 14367 | If this option is turned off, per-message log files are not created in the |
| 14368 | msglog spool sub-directory. This reduces the amount of disk I/O required by |
| 14369 | Exim, by reducing the number of files involved in handling a message from a |
| 14370 | minimum of four (header spool file, body spool file, delivery journal, and |
| 14371 | per-message log) to three. The other major I/O activity is Exim's main log, |
| 14372 | which is not affected by this option. |
| 14373 | |
| 14374 | +-------------------------------------------------------+ |
| 14375 | |message_size_limit|Use: main|Type: string*|Default: 50M| |
| 14376 | +-------------------------------------------------------+ |
| 14377 | |
| 14378 | This option limits the maximum size of message that Exim will process. The |
| 14379 | value is expanded for each incoming connection so, for example, it can be made |
| 14380 | to depend on the IP address of the remote host for messages arriving via TCP/ |
| 14381 | IP. After expansion, the value must be a sequence of decimal digits, optionally |
| 14382 | followed by K or M. |
| 14383 | |
| 14384 | Note: This limit cannot be made to depend on a message's sender or any other |
| 14385 | properties of an individual message, because it has to be advertised in the |
| 14386 | server's response to EHLO. String expansion failure causes a temporary error. A |
| 14387 | value of zero means no limit, but its use is not recommended. See also |
| 14388 | bounce_return_size_limit. |
| 14389 | |
| 14390 | Incoming SMTP messages are failed with a 552 error if the limit is exceeded; |
| 14391 | locally-generated messages either get a stderr message or a delivery failure |
| 14392 | message to the sender, depending on the -oe setting. Rejection of an oversized |
| 14393 | message is logged in both the main and the reject logs. See also the generic |
| 14394 | transport option message_size_limit, which limits the size of message that an |
| 14395 | individual transport can process. |
| 14396 | |
| 14397 | If you use a virus-scanner and set this option to to a value larger than the |
| 14398 | maximum size that your virus-scanner is configured to support, you may get |
| 14399 | failures triggered by large mails. The right size to configure for the |
| 14400 | virus-scanner depends upon what data is passed and the options in use but it's |
| 14401 | probably safest to just set it to a little larger than this value. E.g., with a |
| 14402 | default Exim message size of 50M and a default ClamAV StreamMaxLength of 10M, |
| 14403 | some problems may result. |
| 14404 | |
| 14405 | A value of 0 will disable size limit checking; Exim will still advertise the |
| 14406 | SIZE extension in an EHLO response, but without a limit, so as to permit SMTP |
| 14407 | clients to still indicate the message size along with the MAIL verb. |
| 14408 | |
| 14409 | +-----------------------------------------------------------+ |
| 14410 | |move_frozen_messages|Use: main|Type: boolean|Default: false| |
| 14411 | +-----------------------------------------------------------+ |
| 14412 | |
| 14413 | This option, which is available only if Exim has been built with the setting |
| 14414 | |
| 14415 | SUPPORT_MOVE_FROZEN_MESSAGES=yes |
| 14416 | |
| 14417 | in Local/Makefile, causes frozen messages and their message logs to be moved |
| 14418 | from the input and msglog directories on the spool to Finput and Fmsglog, |
| 14419 | respectively. There is currently no support in Exim or the standard utilities |
| 14420 | for handling such moved messages, and they do not show up in lists generated by |
| 14421 | -bp or by the Exim monitor. |
| 14422 | |
| 14423 | +--------------------------------------------------+ |
| 14424 | |mua_wrapper|Use: main|Type: boolean|Default: false| |
| 14425 | +--------------------------------------------------+ |
| 14426 | |
| 14427 | Setting this option true causes Exim to run in a very restrictive mode in which |
| 14428 | it passes messages synchronously to a smart host. Chapter 51 contains a full |
| 14429 | description of this facility. |
| 14430 | |
| 14431 | +--------------------------------------------------------+ |
| 14432 | |mysql_servers|Use: main|Type: string list|Default: unset| |
| 14433 | +--------------------------------------------------------+ |
| 14434 | |
| 14435 | This option provides a list of MySQL servers and associated connection data, to |
| 14436 | be used in conjunction with mysql lookups (see section 9.22). The option is |
| 14437 | available only if Exim has been built with MySQL support. |
| 14438 | |
| 14439 | +-------------------------------------------------------+ |
| 14440 | |never_users|Use: main|Type: string list*|Default: unset| |
| 14441 | +-------------------------------------------------------+ |
| 14442 | |
| 14443 | This option is expanded just once, at the start of Exim's processing. Local |
| 14444 | message deliveries are normally run in processes that are setuid to the |
| 14445 | recipient, and remote deliveries are normally run under Exim's own uid and gid. |
| 14446 | It is usually desirable to prevent any deliveries from running as root, as a |
| 14447 | safety precaution. |
| 14448 | |
| 14449 | When Exim is built, an option called FIXED_NEVER_USERS can be set to a list of |
| 14450 | users that must not be used for local deliveries. This list is fixed in the |
| 14451 | binary and cannot be overridden by the configuration file. By default, it |
| 14452 | contains just the single user name "root". The never_users runtime option can |
| 14453 | be used to add more users to the fixed list. |
| 14454 | |
| 14455 | If a message is to be delivered as one of the users on the fixed list or the |
| 14456 | never_users list, an error occurs, and delivery is deferred. A common example |
| 14457 | is |
| 14458 | |
| 14459 | never_users = root:daemon:bin |
| 14460 | |
| 14461 | Including root is redundant if it is also on the fixed list, but it does no |
| 14462 | harm. This option overrides the pipe_as_creator option of the pipe transport |
| 14463 | driver. |
| 14464 | |
| 14465 | +-----------------------------------------------------------------------------+ |
| 14466 | |openssl_options|Use: main|Type: string list|Default: +no_sslv2 +single_dh_use| |
| 14467 | +-----------------------------------------------------------------------------+ |
| 14468 | |
| 14469 | This option allows an administrator to adjust the SSL options applied by |
| 14470 | OpenSSL to connections. It is given as a space-separated list of items, each |
| 14471 | one to be +added or -subtracted from the current value. |
| 14472 | |
| 14473 | This option is only available if Exim is built against OpenSSL. The values |
| 14474 | available for this option vary according to the age of your OpenSSL install. |
| 14475 | The "all" value controls a subset of flags which are available, typically the |
| 14476 | bug workaround options. The SSL_CTX_set_options man page will list the values |
| 14477 | known on your system and Exim should support all the "bug workaround" options |
| 14478 | and many of the "modifying" options. The Exim names lose the leading "SSL_OP_" |
| 14479 | and are lower-cased. |
| 14480 | |
| 14481 | Note that adjusting the options can have severe impact upon the security of SSL |
| 14482 | as used by Exim. It is possible to disable safety checks and shoot yourself in |
| 14483 | the foot in various unpleasant ways. This option should not be adjusted |
| 14484 | lightly. An unrecognised item will be detected at startup, by invoking Exim |
| 14485 | with the -bV flag. |
| 14486 | |
| 14487 | The option affects Exim operating both as a server and as a client. |
| 14488 | |
| 14489 | Historical note: prior to release 4.80, Exim defaulted this value to |
| 14490 | "+dont_insert_empty_fragments", which may still be needed for compatibility |
| 14491 | with some clients, but which lowers security by increasing exposure to some now |
| 14492 | infamous attacks. |
| 14493 | |
| 14494 | Examples: |
| 14495 | |
| 14496 | # Make both old MS and old Eudora happy: |
| 14497 | openssl_options = -all +microsoft_big_sslv3_buffer \ |
| 14498 | +dont_insert_empty_fragments |
| 14499 | |
| 14500 | # Disable older protocol versions: |
| 14501 | openssl_options = +no_sslv2 +no_sslv3 |
| 14502 | |
| 14503 | Possible options may include: |
| 14504 | |
| 14505 | * "all" |
| 14506 | |
| 14507 | * "allow_unsafe_legacy_renegotiation" |
| 14508 | |
| 14509 | * "cipher_server_preference" |
| 14510 | |
| 14511 | * "dont_insert_empty_fragments" |
| 14512 | |
| 14513 | * "ephemeral_rsa" |
| 14514 | |
| 14515 | * "legacy_server_connect" |
| 14516 | |
| 14517 | * "microsoft_big_sslv3_buffer" |
| 14518 | |
| 14519 | * "microsoft_sess_id_bug" |
| 14520 | |
| 14521 | * "msie_sslv2_rsa_padding" |
| 14522 | |
| 14523 | * "netscape_challenge_bug" |
| 14524 | |
| 14525 | * "netscape_reuse_cipher_change_bug" |
| 14526 | |
| 14527 | * "no_compression" |
| 14528 | |
| 14529 | * "no_session_resumption_on_renegotiation" |
| 14530 | |
| 14531 | * "no_sslv2" |
| 14532 | |
| 14533 | * "no_sslv3" |
| 14534 | |
| 14535 | * "no_ticket" |
| 14536 | |
| 14537 | * "no_tlsv1" |
| 14538 | |
| 14539 | * "no_tlsv1_1" |
| 14540 | |
| 14541 | * "no_tlsv1_2" |
| 14542 | |
| 14543 | * "safari_ecdhe_ecdsa_bug" |
| 14544 | |
| 14545 | * "single_dh_use" |
| 14546 | |
| 14547 | * "single_ecdh_use" |
| 14548 | |
| 14549 | * "ssleay_080_client_dh_bug" |
| 14550 | |
| 14551 | * "sslref2_reuse_cert_type_bug" |
| 14552 | |
| 14553 | * "tls_block_padding_bug" |
| 14554 | |
| 14555 | * "tls_d5_bug" |
| 14556 | |
| 14557 | * "tls_rollback_bug" |
| 14558 | |
| 14559 | As an aside, the "safari_ecdhe_ecdsa_bug" item is a misnomer and affects all |
| 14560 | clients connecting using the MacOS SecureTransport TLS facility prior to MacOS |
| 14561 | 10.8.4, including email clients. If you see old MacOS clients failing to |
| 14562 | negotiate TLS then this option value might help, provided that your OpenSSL |
| 14563 | release is new enough to contain this work-around. This may be a situation |
| 14564 | where you have to upgrade OpenSSL to get buggy clients working. |
| 14565 | |
| 14566 | +---------------------------------------------------------+ |
| 14567 | |oracle_servers|Use: main|Type: string list|Default: unset| |
| 14568 | +---------------------------------------------------------+ |
| 14569 | |
| 14570 | This option provides a list of Oracle servers and associated connection data, |
| 14571 | to be used in conjunction with oracle lookups (see section 9.22). The option is |
| 14572 | available only if Exim has been built with Oracle support. |
| 14573 | |
| 14574 | +----------------------------------------------------------------+ |
| 14575 | |percent_hack_domains|Use: main|Type: domain list*|Default: unset| |
| 14576 | +----------------------------------------------------------------+ |
| 14577 | |
| 14578 | The "percent hack" is the convention whereby a local part containing a percent |
| 14579 | sign is re-interpreted as a new email address, with the percent replaced by @. |
| 14580 | This is sometimes called "source routing", though that term is also applied to |
| 14581 | RFC 2822 addresses that begin with an @ character. If this option is set, Exim |
| 14582 | implements the percent facility for those domains listed, but no others. This |
| 14583 | happens before an incoming SMTP address is tested against an ACL. |
| 14584 | |
| 14585 | Warning: The "percent hack" has often been abused by people who are trying to |
| 14586 | get round relaying restrictions. For this reason, it is best avoided if at all |
| 14587 | possible. Unfortunately, a number of less security-conscious MTAs implement it |
| 14588 | unconditionally. If you are running Exim on a gateway host, and routing mail |
| 14589 | through to internal MTAs without processing the local parts, it is a good idea |
| 14590 | to reject recipient addresses with percent characters in their local parts. |
| 14591 | Exim's default configuration does this. |
| 14592 | |
| 14593 | +----------------------------------------------------+ |
| 14594 | |perl_at_start|Use: main|Type: boolean|Default: false| |
| 14595 | +----------------------------------------------------+ |
| 14596 | |
| 14597 | This option is available only when Exim is built with an embedded Perl |
| 14598 | interpreter. See chapter 12 for details of its use. |
| 14599 | |
| 14600 | +--------------------------------------------------+ |
| 14601 | |perl_startup|Use: main|Type: string|Default: unset| |
| 14602 | +--------------------------------------------------+ |
| 14603 | |
| 14604 | This option is available only when Exim is built with an embedded Perl |
| 14605 | interpreter. See chapter 12 for details of its use. |
| 14606 | |
| 14607 | +---------------------------------------------------+ |
| 14608 | |perl_startup|Use: main|Type: boolean|Default: false| |
| 14609 | +---------------------------------------------------+ |
| 14610 | |
| 14611 | This Option enables the taint mode of the embedded Perl interpreter. |
| 14612 | |
| 14613 | +--------------------------------------------------------+ |
| 14614 | |pgsql_servers|Use: main|Type: string list|Default: unset| |
| 14615 | +--------------------------------------------------------+ |
| 14616 | |
| 14617 | This option provides a list of PostgreSQL servers and associated connection |
| 14618 | data, to be used in conjunction with pgsql lookups (see section 9.22). The |
| 14619 | option is available only if Exim has been built with PostgreSQL support. |
| 14620 | |
| 14621 | +------------------------------------------------------------------+ |
| 14622 | |pid_file_path|Use: main|Type: string*|Default: set at compile time| |
| 14623 | +------------------------------------------------------------------+ |
| 14624 | |
| 14625 | This option sets the name of the file to which the Exim daemon writes its |
| 14626 | process id. The string is expanded, so it can contain, for example, references |
| 14627 | to the host name: |
| 14628 | |
| 14629 | pid_file_path = /var/log/$primary_hostname/exim.pid |
| 14630 | |
| 14631 | If no path is set, the pid is written to the file exim-daemon.pid in Exim's |
| 14632 | spool directory. The value set by the option can be overridden by the -oP |
| 14633 | command line option. A pid file is not written if a "non-standard" daemon is |
| 14634 | run by means of the -oX option, unless a path is explicitly supplied by -oP. |
| 14635 | |
| 14636 | +----------------------------------------------------------------+ |
| 14637 | |pipelining_advertise_hosts|Use: main|Type: host list*|Default: *| |
| 14638 | +----------------------------------------------------------------+ |
| 14639 | |
| 14640 | This option can be used to suppress the advertisement of the SMTP PIPELINING |
| 14641 | extension to specific hosts. See also the no_pipelining control in section |
| 14642 | 43.22. When PIPELINING is not advertised and smtp_enforce_sync is true, an Exim |
| 14643 | server enforces strict synchronization for each SMTP command and response. When |
| 14644 | PIPELINING is advertised, Exim assumes that clients will use it; "out of order" |
| 14645 | commands that are "expected" do not count as protocol errors (see |
| 14646 | smtp_max_synprot_errors). |
| 14647 | |
| 14648 | +--------------------------------------------------+ |
| 14649 | |prdr_enable|Use: main|Type: boolean|Default: false| |
| 14650 | +--------------------------------------------------+ |
| 14651 | |
| 14652 | This option can be used to enable the Per-Recipient Data Response extension to |
| 14653 | SMTP, defined by Eric Hall. If the option is set, PRDR is advertised by Exim |
| 14654 | when operating as a server. If the client requests PRDR, and more than one |
| 14655 | recipient, for a message an additional ACL is called for each recipient after |
| 14656 | the message content is received. See section 43.9. |
| 14657 | |
| 14658 | +------------------------------------------------------------+ |
| 14659 | |preserve_message_logs|Use: main|Type: boolean|Default: false| |
| 14660 | +------------------------------------------------------------+ |
| 14661 | |
| 14662 | If this option is set, message log files are not deleted when messages are |
| 14663 | completed. Instead, they are moved to a sub-directory of the spool directory |
| 14664 | called msglog.OLD, where they remain available for statistical or debugging |
| 14665 | purposes. This is a dangerous option to set on systems with any appreciable |
| 14666 | volume of mail. Use with care! |
| 14667 | |
| 14668 | +----------------------------------------------------------+ |
| 14669 | |primary_hostname|Use: main|Type: string|Default: see below| |
| 14670 | +----------------------------------------------------------+ |
| 14671 | |
| 14672 | This specifies the name of the current host. It is used in the default EHLO or |
| 14673 | HELO command for outgoing SMTP messages (changeable via the helo_data option in |
| 14674 | the smtp transport), and as the default for qualify_domain. The value is also |
| 14675 | used by default in some SMTP response messages from an Exim server. This can be |
| 14676 | changed dynamically by setting smtp_active_hostname. |
| 14677 | |
| 14678 | If primary_hostname is not set, Exim calls uname() to find the host name. If |
| 14679 | this fails, Exim panics and dies. If the name returned by uname() contains only |
| 14680 | one component, Exim passes it to gethostbyname() (or getipnodebyname() when |
| 14681 | available) in order to obtain the fully qualified version. The variable |
| 14682 | $primary_hostname contains the host name, whether set explicitly by this |
| 14683 | option, or defaulted. |
| 14684 | |
| 14685 | +--------------------------------------------------------+ |
| 14686 | |print_topbitchars|Use: main|Type: boolean|Default: false| |
| 14687 | +--------------------------------------------------------+ |
| 14688 | |
| 14689 | By default, Exim considers only those characters whose codes lie in the range |
| 14690 | 32-126 to be printing characters. In a number of circumstances (for example, |
| 14691 | when writing log entries) non-printing characters are converted into escape |
| 14692 | sequences, primarily to avoid messing up the layout. If print_topbitchars is |
| 14693 | set, code values of 128 and above are also considered to be printing |
| 14694 | characters. |
| 14695 | |
| 14696 | This option also affects the header syntax checks performed by the autoreply |
| 14697 | transport, and whether Exim uses RFC 2047 encoding of the user's full name when |
| 14698 | constructing From: and Sender: addresses (as described in section 47.18). |
| 14699 | Setting this option can cause Exim to generate eight bit message headers that |
| 14700 | do not conform to the standards. |
| 14701 | |
| 14702 | +------------------------------------------------------+ |
| 14703 | |process_log_path|Use: main|Type: string|Default: unset| |
| 14704 | +------------------------------------------------------+ |
| 14705 | |
| 14706 | This option sets the name of the file to which an Exim process writes its |
| 14707 | "process log" when sent a USR1 signal. This is used by the exiwhat utility |
| 14708 | script. If this option is unset, the file called exim-process.info in Exim's |
| 14709 | spool directory is used. The ability to specify the name explicitly can be |
| 14710 | useful in environments where two different Exims are running, using different |
| 14711 | spool directories. |
| 14712 | |
| 14713 | +---------------------------------------------------------+ |
| 14714 | |prod_requires_admin|Use: main|Type: boolean|Default: true| |
| 14715 | +---------------------------------------------------------+ |
| 14716 | |
| 14717 | The -M, -R, and -q command-line options require the caller to be an admin user |
| 14718 | unless prod_requires_admin is set false. See also queue_list_requires_admin. |
| 14719 | |
| 14720 | +--------------------------------------------------------+ |
| 14721 | |qualify_domain|Use: main|Type: string|Default: see below| |
| 14722 | +--------------------------------------------------------+ |
| 14723 | |
| 14724 | This option specifies the domain name that is added to any envelope sender |
| 14725 | addresses that do not have a domain qualification. It also applies to recipient |
| 14726 | addresses if qualify_recipient is not set. Unqualified addresses are accepted |
| 14727 | by default only for locally-generated messages. Qualification is also applied |
| 14728 | to addresses in header lines such as From: and To: for locally-generated |
| 14729 | messages, unless the -bnq command line option is used. |
| 14730 | |
| 14731 | Messages from external sources must always contain fully qualified addresses, |
| 14732 | unless the sending host matches sender_unqualified_hosts or |
| 14733 | recipient_unqualified_hosts (as appropriate), in which case incoming addresses |
| 14734 | are qualified with qualify_domain or qualify_recipient as necessary. |
| 14735 | Internally, Exim always works with fully qualified envelope addresses. If |
| 14736 | qualify_domain is not set, it defaults to the primary_hostname value. |
| 14737 | |
| 14738 | +-----------------------------------------------------------+ |
| 14739 | |qualify_recipient|Use: main|Type: string|Default: see below| |
| 14740 | +-----------------------------------------------------------+ |
| 14741 | |
| 14742 | This option allows you to specify a different domain for qualifying recipient |
| 14743 | addresses to the one that is used for senders. See qualify_domain above. |
| 14744 | |
| 14745 | +---------------------------------------------------------+ |
| 14746 | |queue_domains|Use: main|Type: domain list*|Default: unset| |
| 14747 | +---------------------------------------------------------+ |
| 14748 | |
| 14749 | This option lists domains for which immediate delivery is not required. A |
| 14750 | delivery process is started whenever a message is received, but only those |
| 14751 | domains that do not match are processed. All other deliveries wait until the |
| 14752 | next queue run. See also hold_domains and queue_smtp_domains. |
| 14753 | |
| 14754 | +---------------------------------------------------------------+ |
| 14755 | |queue_list_requires_admin|Use: main|Type: boolean|Default: true| |
| 14756 | +---------------------------------------------------------------+ |
| 14757 | |
| 14758 | The -bp command-line option, which lists the messages that are on the queue, |
| 14759 | requires the caller to be an admin user unless queue_list_requires_admin is set |
| 14760 | false. See also prod_requires_admin. |
| 14761 | |
| 14762 | +-------------------------------------------------+ |
| 14763 | |queue_only|Use: main|Type: boolean|Default: false| |
| 14764 | +-------------------------------------------------+ |
| 14765 | |
| 14766 | If queue_only is set, a delivery process is not automatically started whenever |
| 14767 | a message is received. Instead, the message waits on the queue for the next |
| 14768 | queue run. Even if queue_only is false, incoming messages may not get delivered |
| 14769 | immediately when certain conditions (such as heavy load) occur. |
| 14770 | |
| 14771 | The -odq command line has the same effect as queue_only. The -odb and -odi |
| 14772 | command line options override queue_only unless queue_only_override is set |
| 14773 | false. See also queue_only_file, queue_only_load, and smtp_accept_queue. |
| 14774 | |
| 14775 | +-----------------------------------------------------+ |
| 14776 | |queue_only_file|Use: main|Type: string|Default: unset| |
| 14777 | +-----------------------------------------------------+ |
| 14778 | |
| 14779 | This option can be set to a colon-separated list of absolute path names, each |
| 14780 | one optionally preceded by "smtp". When Exim is receiving a message, it tests |
| 14781 | for the existence of each listed path using a call to stat(). For each path |
| 14782 | that exists, the corresponding queueing option is set. For paths with no |
| 14783 | prefix, queue_only is set; for paths prefixed by "smtp", queue_smtp_domains is |
| 14784 | set to match all domains. So, for example, |
| 14785 | |
| 14786 | queue_only_file = smtp/some/file |
| 14787 | |
| 14788 | causes Exim to behave as if queue_smtp_domains were set to "*" whenever /some/ |
| 14789 | file exists. |
| 14790 | |
| 14791 | +----------------------------------------------------------+ |
| 14792 | |queue_only_load|Use: main|Type: fixed-point|Default: unset| |
| 14793 | +----------------------------------------------------------+ |
| 14794 | |
| 14795 | If the system load average is higher than this value, incoming messages from |
| 14796 | all sources are queued, and no automatic deliveries are started. If this |
| 14797 | happens during local or remote SMTP input, all subsequent messages received on |
| 14798 | the same SMTP connection are queued by default, whatever happens to the load in |
| 14799 | the meantime, but this can be changed by setting queue_only_load_latch false. |
| 14800 | |
| 14801 | Deliveries will subsequently be performed by queue runner processes. This |
| 14802 | option has no effect on ancient operating systems on which Exim cannot |
| 14803 | determine the load average. See also deliver_queue_load_max and |
| 14804 | smtp_load_reserve. |
| 14805 | |
| 14806 | +-----------------------------------------------------------+ |
| 14807 | |queue_only_load_latch|Use: main|Type: boolean|Default: true| |
| 14808 | +-----------------------------------------------------------+ |
| 14809 | |
| 14810 | When this option is true (the default), once one message has been queued |
| 14811 | because the load average is higher than the value set by queue_only_load, all |
| 14812 | subsequent messages received on the same SMTP connection are also queued. This |
| 14813 | is a deliberate choice; even though the load average may fall below the |
| 14814 | threshold, it doesn't seem right to deliver later messages on the same |
| 14815 | connection when not delivering earlier ones. However, there are special |
| 14816 | circumstances such as very long-lived connections from scanning appliances |
| 14817 | where this is not the best strategy. In such cases, queue_only_load_latch |
| 14818 | should be set false. This causes the value of the load average to be |
| 14819 | re-evaluated for each message. |
| 14820 | |
| 14821 | +---------------------------------------------------------+ |
| 14822 | |queue_only_override|Use: main|Type: boolean|Default: true| |
| 14823 | +---------------------------------------------------------+ |
| 14824 | |
| 14825 | When this option is true, the -odx command line options override the setting of |
| 14826 | queue_only or queue_only_file in the configuration file. If queue_only_override |
| 14827 | is set false, the -odx options cannot be used to override; they are accepted, |
| 14828 | but ignored. |
| 14829 | |
| 14830 | +---------------------------------------------------------+ |
| 14831 | |queue_run_in_order|Use: main|Type: boolean|Default: false| |
| 14832 | +---------------------------------------------------------+ |
| 14833 | |
| 14834 | If this option is set, queue runs happen in order of message arrival instead of |
| 14835 | in an arbitrary order. For this to happen, a complete list of the entire queue |
| 14836 | must be set up before the deliveries start. When the queue is all held in a |
| 14837 | single directory (the default), a single list is created for both the ordered |
| 14838 | and the non-ordered cases. However, if split_spool_directory is set, a single |
| 14839 | list is not created when queue_run_in_order is false. In this case, the |
| 14840 | sub-directories are processed one at a time (in a random order), and this |
| 14841 | avoids setting up one huge list for the whole queue. Thus, setting |
| 14842 | queue_run_in_order with split_spool_directory may degrade performance when the |
| 14843 | queue is large, because of the extra work in setting up the single, large list. |
| 14844 | In most situations, queue_run_in_order should not be set. |
| 14845 | |
| 14846 | +-------------------------------------------------+ |
| 14847 | |queue_run_max|Use: main|Type: integer*|Default: 5| |
| 14848 | +-------------------------------------------------+ |
| 14849 | |
| 14850 | This controls the maximum number of queue runner processes that an Exim daemon |
| 14851 | can run simultaneously. This does not mean that it starts them all at once, but |
| 14852 | rather that if the maximum number are still running when the time comes to |
| 14853 | start another one, it refrains from starting another one. This can happen with |
| 14854 | very large queues and/or very sluggish deliveries. This option does not, |
| 14855 | however, interlock with other processes, so additional queue runners can be |
| 14856 | started by other means, or by killing and restarting the daemon. |
| 14857 | |
| 14858 | Setting this option to zero does not suppress queue runs; rather, it disables |
| 14859 | the limit, allowing any number of simultaneous queue runner processes to be |
| 14860 | run. If you do not want queue runs to occur, omit the -qxx setting on the |
| 14861 | daemon's command line. |
| 14862 | |
| 14863 | To set limits for different named queues use an expansion depending on the |
| 14864 | $queue_name variable. |
| 14865 | |
| 14866 | +--------------------------------------------------------------+ |
| 14867 | |queue_smtp_domains|Use: main|Type: domain list*|Default: unset| |
| 14868 | +--------------------------------------------------------------+ |
| 14869 | |
| 14870 | When this option is set, a delivery process is started whenever a message is |
| 14871 | received, routing is performed, and local deliveries take place. However, if |
| 14872 | any SMTP deliveries are required for domains that match queue_smtp_domains, |
| 14873 | they are not immediately delivered, but instead the message waits on the queue |
| 14874 | for the next queue run. Since routing of the message has taken place, Exim |
| 14875 | knows to which remote hosts it must be delivered, and so when the queue run |
| 14876 | happens, multiple messages for the same host are delivered over a single SMTP |
| 14877 | connection. The -odqs command line option causes all SMTP deliveries to be |
| 14878 | queued in this way, and is equivalent to setting queue_smtp_domains to "*". See |
| 14879 | also hold_domains and queue_domains. |
| 14880 | |
| 14881 | +------------------------------------------------+ |
| 14882 | |receive_timeout|Use: main|Type: time|Default: 0s| |
| 14883 | +------------------------------------------------+ |
| 14884 | |
| 14885 | This option sets the timeout for accepting a non-SMTP message, that is, the |
| 14886 | maximum time that Exim waits when reading a message on the standard input. If |
| 14887 | the value is zero, it will wait for ever. This setting is overridden by the -or |
| 14888 | command line option. The timeout for incoming SMTP messages is controlled by |
| 14889 | smtp_receive_timeout. |
| 14890 | |
| 14891 | +---------------------------------------------------------------+ |
| 14892 | |received_header_text|Use: main|Type: string*|Default: see below| |
| 14893 | +---------------------------------------------------------------+ |
| 14894 | |
| 14895 | This string defines the contents of the Received: message header that is added |
| 14896 | to each message, except for the timestamp, which is automatically added on at |
| 14897 | the end (preceded by a semicolon). The string is expanded each time it is used. |
| 14898 | If the expansion yields an empty string, no Received: header line is added to |
| 14899 | the message. Otherwise, the string should start with the text "Received:" and |
| 14900 | conform to the RFC 2822 specification for Received: header lines. The default |
| 14901 | setting is: |
| 14902 | |
| 14903 | received_header_text = Received: \ |
| 14904 | ${if def:sender_rcvhost {from $sender_rcvhost\n\t}\ |
| 14905 | {${if def:sender_ident \ |
| 14906 | {from ${quote_local_part:$sender_ident} }}\ |
| 14907 | ${if def:sender_helo_name {(helo=$sender_helo_name)\n\t}}}}\ |
| 14908 | by $primary_hostname \ |
| 14909 | ${if def:received_protocol {with $received_protocol}} \ |
| 14910 | ${if def:tls_in_cipher {($tls_in_cipher)\n\t}}\ |
| 14911 | (Exim $version_number)\n\t\ |
| 14912 | ${if def:sender_address \ |
| 14913 | {(envelope-from <$sender_address>)\n\t}}\ |
| 14914 | id $message_exim_id\ |
| 14915 | ${if def:received_for {\n\tfor $received_for}} |
| 14916 | |
| 14917 | The reference to the TLS cipher is omitted when Exim is built without TLS |
| 14918 | support. The use of conditional expansions ensures that this works for both |
| 14919 | locally generated messages and messages received from remote hosts, giving |
| 14920 | header lines such as the following: |
| 14921 | |
| 14922 | Received: from scrooge.carol.example ([192.168.12.25] ident=root) |
| 14923 | by marley.carol.example with esmtp (Exim 4.00) |
| 14924 | (envelope-from <bob@carol.example>) |
| 14925 | id 16IOWa-00019l-00 |
| 14926 | for chas@dickens.example; Tue, 25 Dec 2001 14:43:44 +0000 |
| 14927 | Received: by scrooge.carol.example with local (Exim 4.00) |
| 14928 | id 16IOWW-000083-00; Tue, 25 Dec 2001 14:43:41 +0000 |
| 14929 | |
| 14930 | Until the body of the message has been received, the timestamp is the time when |
| 14931 | the message started to be received. Once the body has arrived, and all policy |
| 14932 | checks have taken place, the timestamp is updated to the time at which the |
| 14933 | message was accepted. |
| 14934 | |
| 14935 | +--------------------------------------------------------+ |
| 14936 | |received_headers_max|Use: main|Type: integer|Default: 30| |
| 14937 | +--------------------------------------------------------+ |
| 14938 | |
| 14939 | When a message is to be delivered, the number of Received: headers is counted, |
| 14940 | and if it is greater than this parameter, a mail loop is assumed to have |
| 14941 | occurred, the delivery is abandoned, and an error message is generated. This |
| 14942 | applies to both local and remote deliveries. |
| 14943 | |
| 14944 | +---------------------------------------------------------------------+ |
| 14945 | |recipient_unqualified_hosts|Use: main|Type: host list*|Default: unset| |
| 14946 | +---------------------------------------------------------------------+ |
| 14947 | |
| 14948 | This option lists those hosts from which Exim is prepared to accept unqualified |
| 14949 | recipient addresses in message envelopes. The addresses are made fully |
| 14950 | qualified by the addition of the qualify_recipient value. This option also |
| 14951 | affects message header lines. Exim does not reject unqualified recipient |
| 14952 | addresses in headers, but it qualifies them only if the message came from a |
| 14953 | host that matches recipient_unqualified_hosts, or if the message was submitted |
| 14954 | locally (not using TCP/IP), and the -bnq option was not set. |
| 14955 | |
| 14956 | +-------------------------------------------------+ |
| 14957 | |recipients_max|Use: main|Type: integer|Default: 0| |
| 14958 | +-------------------------------------------------+ |
| 14959 | |
| 14960 | If this option is set greater than zero, it specifies the maximum number of |
| 14961 | original recipients for any message. Additional recipients that are generated |
| 14962 | by aliasing or forwarding do not count. SMTP messages get a 452 response for |
| 14963 | all recipients over the limit; earlier recipients are delivered as normal. |
| 14964 | Non-SMTP messages with too many recipients are failed, and no deliveries are |
| 14965 | done. |
| 14966 | |
| 14967 | Note: The RFCs specify that an SMTP server should accept at least 100 RCPT |
| 14968 | commands in a single message. |
| 14969 | |
| 14970 | +------------------------------------------------------------+ |
| 14971 | |recipients_max_reject|Use: main|Type: boolean|Default: false| |
| 14972 | +------------------------------------------------------------+ |
| 14973 | |
| 14974 | If this option is set true, Exim rejects SMTP messages containing too many |
| 14975 | recipients by giving 552 errors to the surplus RCPT commands, and a 554 error |
| 14976 | to the eventual DATA command. Otherwise (the default) it gives a 452 error to |
| 14977 | the surplus RCPT commands and accepts the message on behalf of the initial set |
| 14978 | of recipients. The remote server should then re-send the message for the |
| 14979 | remaining recipients at a later time. |
| 14980 | |
| 14981 | +------------------------------------------------------+ |
| 14982 | |remote_max_parallel|Use: main|Type: integer|Default: 2| |
| 14983 | +------------------------------------------------------+ |
| 14984 | |
| 14985 | This option controls parallel delivery of one message to a number of remote |
| 14986 | hosts. If the value is less than 2, parallel delivery is disabled, and Exim |
| 14987 | does all the remote deliveries for a message one by one. Otherwise, if a single |
| 14988 | message has to be delivered to more than one remote host, or if several copies |
| 14989 | have to be sent to the same remote host, up to remote_max_parallel deliveries |
| 14990 | are done simultaneously. If more than remote_max_parallel deliveries are |
| 14991 | required, the maximum number of processes are started, and as each one |
| 14992 | finishes, another is begun. The order of starting processes is the same as if |
| 14993 | sequential delivery were being done, and can be controlled by the |
| 14994 | remote_sort_domains option. If parallel delivery takes place while running with |
| 14995 | debugging turned on, the debugging output from each delivery process is tagged |
| 14996 | with its process id. |
| 14997 | |
| 14998 | This option controls only the maximum number of parallel deliveries for one |
| 14999 | message in one Exim delivery process. Because Exim has no central queue |
| 15000 | manager, there is no way of controlling the total number of simultaneous |
| 15001 | deliveries if the configuration allows a delivery attempt as soon as a message |
| 15002 | is received. |
| 15003 | |
| 15004 | If you want to control the total number of deliveries on the system, you need |
| 15005 | to set the queue_only option. This ensures that all incoming messages are added |
| 15006 | to the queue without starting a delivery process. Then set up an Exim daemon to |
| 15007 | start queue runner processes at appropriate intervals (probably fairly often, |
| 15008 | for example, every minute), and limit the total number of queue runners by |
| 15009 | setting the queue_run_max parameter. Because each queue runner delivers only |
| 15010 | one message at a time, the maximum number of deliveries that can then take |
| 15011 | place at once is queue_run_max multiplied by remote_max_parallel. |
| 15012 | |
| 15013 | If it is purely remote deliveries you want to control, use queue_smtp_domains |
| 15014 | instead of queue_only. This has the added benefit of doing the SMTP routing |
| 15015 | before queueing, so that several messages for the same host will eventually get |
| 15016 | delivered down the same connection. |
| 15017 | |
| 15018 | +---------------------------------------------------------------+ |
| 15019 | |remote_sort_domains|Use: main|Type: domain list*|Default: unset| |
| 15020 | +---------------------------------------------------------------+ |
| 15021 | |
| 15022 | When there are a number of remote deliveries for a message, they are sorted by |
| 15023 | domain into the order given by this list. For example, |
| 15024 | |
| 15025 | remote_sort_domains = *.cam.ac.uk:*.uk |
| 15026 | |
| 15027 | would attempt to deliver to all addresses in the cam.ac.uk domain first, then |
| 15028 | to those in the uk domain, then to any others. |
| 15029 | |
| 15030 | +--------------------------------------------------+ |
| 15031 | |retry_data_expire|Use: main|Type: time|Default: 7d| |
| 15032 | +--------------------------------------------------+ |
| 15033 | |
| 15034 | This option sets a "use before" time on retry information in Exim's hints |
| 15035 | database. Any older retry data is ignored. This means that, for example, once a |
| 15036 | host has not been tried for 7 days, Exim behaves as if it has no knowledge of |
| 15037 | past failures. |
| 15038 | |
| 15039 | +----------------------------------------------------+ |
| 15040 | |retry_interval_max|Use: main|Type: time|Default: 24h| |
| 15041 | +----------------------------------------------------+ |
| 15042 | |
| 15043 | Chapter 32 describes Exim's mechanisms for controlling the intervals between |
| 15044 | delivery attempts for messages that cannot be delivered straight away. This |
| 15045 | option sets an overall limit to the length of time between retries. It cannot |
| 15046 | be set greater than 24 hours; any attempt to do so forces the default value. |
| 15047 | |
| 15048 | +--------------------------------------------------------+ |
| 15049 | |return_path_remove|Use: main|Type: boolean|Default: true| |
| 15050 | +--------------------------------------------------------+ |
| 15051 | |
| 15052 | RFC 2821, section 4.4, states that an SMTP server must insert a Return-path: |
| 15053 | header line into a message when it makes a "final delivery". The Return-path: |
| 15054 | header preserves the sender address as received in the MAIL command. This |
| 15055 | description implies that this header should not be present in an incoming |
| 15056 | message. If return_path_remove is true, any existing Return-path: headers are |
| 15057 | removed from messages at the time they are received. Exim's transports have |
| 15058 | options for adding Return-path: headers at the time of delivery. They are |
| 15059 | normally used only for final local deliveries. |
| 15060 | |
| 15061 | +-------------------------------------------------------+ |
| 15062 | |return_size_limit|Use: main|Type: integer|Default: 100K| |
| 15063 | +-------------------------------------------------------+ |
| 15064 | |
| 15065 | This option is an obsolete synonym for bounce_return_size_limit. |
| 15066 | |
| 15067 | +-----------------------------------------------------+ |
| 15068 | |rfc1413_hosts|Use: main|Type: host list*|Default: @[]| |
| 15069 | +-----------------------------------------------------+ |
| 15070 | |
| 15071 | RFC 1413 identification calls are made to any client host which matches an item |
| 15072 | in the list. The default value specifies just this host, being any local |
| 15073 | interface for the system. |
| 15074 | |
| 15075 | +------------------------------------------------------+ |
| 15076 | |rfc1413_query_timeout|Use: main|Type: time|Default: 0s| |
| 15077 | +------------------------------------------------------+ |
| 15078 | |
| 15079 | This sets the timeout on RFC 1413 identification calls. If it is set to zero, |
| 15080 | no RFC 1413 calls are ever made. |
| 15081 | |
| 15082 | +------------------------------------------------------------------+ |
| 15083 | |sender_unqualified_hosts|Use: main|Type: host list*|Default: unset| |
| 15084 | +------------------------------------------------------------------+ |
| 15085 | |
| 15086 | This option lists those hosts from which Exim is prepared to accept unqualified |
| 15087 | sender addresses. The addresses are made fully qualified by the addition of |
| 15088 | qualify_domain. This option also affects message header lines. Exim does not |
| 15089 | reject unqualified addresses in headers that contain sender addresses, but it |
| 15090 | qualifies them only if the message came from a host that matches |
| 15091 | sender_unqualified_hosts, or if the message was submitted locally (not using |
| 15092 | TCP/IP), and the -bnq option was not set. |
| 15093 | |
| 15094 | +----------------------------------------------------------+ |
| 15095 | |set_environment|Use: main|Type: string list|Default: empty| |
| 15096 | +----------------------------------------------------------+ |
| 15097 | |
| 15098 | This option allows to set individual environment variables that the currently |
| 15099 | linked libraries and programs in child processes use. The default list is |
| 15100 | empty, |
| 15101 | |
| 15102 | +--------------------------------------------------+ |
| 15103 | |slow_lookup_log|Use: main|Type: integer|Default: 0| |
| 15104 | +--------------------------------------------------+ |
| 15105 | |
| 15106 | This option controls logging of slow lookups. If the value is nonzero it is |
| 15107 | taken as a number of milliseconds and lookups taking longer than this are |
| 15108 | logged. Currently this applies only to DNS lookups. |
| 15109 | |
| 15110 | +-----------------------------------------------------------+ |
| 15111 | |smtp_accept_keepalive|Use: main|Type: boolean|Default: true| |
| 15112 | +-----------------------------------------------------------+ |
| 15113 | |
| 15114 | This option controls the setting of the SO_KEEPALIVE option on incoming TCP/IP |
| 15115 | socket connections. When set, it causes the kernel to probe idle connections |
| 15116 | periodically, by sending packets with "old" sequence numbers. The other end of |
| 15117 | the connection should send an acknowledgment if the connection is still okay or |
| 15118 | a reset if the connection has been aborted. The reason for doing this is that |
| 15119 | it has the beneficial effect of freeing up certain types of connection that can |
| 15120 | get stuck when the remote host is disconnected without tidying up the TCP/IP |
| 15121 | call properly. The keepalive mechanism takes several hours to detect |
| 15122 | unreachable hosts. |
| 15123 | |
| 15124 | +---------------------------------------------------+ |
| 15125 | |smtp_accept_max|Use: main|Type: integer|Default: 20| |
| 15126 | +---------------------------------------------------+ |
| 15127 | |
| 15128 | This option specifies the maximum number of simultaneous incoming SMTP calls |
| 15129 | that Exim will accept. It applies only to the listening daemon; there is no |
| 15130 | control (in Exim) when incoming SMTP is being handled by inetd. If the value is |
| 15131 | set to zero, no limit is applied. However, it is required to be non-zero if |
| 15132 | either smtp_accept_max_per_host or smtp_accept_queue is set. See also |
| 15133 | smtp_accept_reserve and smtp_load_reserve. |
| 15134 | |
| 15135 | A new SMTP connection is immediately rejected if the smtp_accept_max limit has |
| 15136 | been reached. If not, Exim first checks smtp_accept_max_per_host. If that limit |
| 15137 | has not been reached for the client host, smtp_accept_reserve and |
| 15138 | smtp_load_reserve are then checked before accepting the connection. |
| 15139 | |
| 15140 | +-----------------------------------------------------------+ |
| 15141 | |smtp_accept_max_nonmail|Use: main|Type: integer|Default: 10| |
| 15142 | +-----------------------------------------------------------+ |
| 15143 | |
| 15144 | Exim counts the number of "non-mail" commands in an SMTP session, and drops the |
| 15145 | connection if there are too many. This option defines "too many". The check |
| 15146 | catches some denial-of-service attacks, repeated failing AUTHs, or a mad client |
| 15147 | looping sending EHLO, for example. The check is applied only if the client host |
| 15148 | matches smtp_accept_max_nonmail_hosts. |
| 15149 | |
| 15150 | When a new message is expected, one occurrence of RSET is not counted. This |
| 15151 | allows a client to send one RSET between messages (this is not necessary, but |
| 15152 | some clients do it). Exim also allows one uncounted occurrence of HELO or EHLO, |
| 15153 | and one occurrence of STARTTLS between messages. After starting up a TLS |
| 15154 | session, another EHLO is expected, and so it too is not counted. The first |
| 15155 | occurrence of AUTH in a connection, or immediately following STARTTLS is not |
| 15156 | counted. Otherwise, all commands other than MAIL, RCPT, DATA, and QUIT are |
| 15157 | counted. |
| 15158 | |
| 15159 | +-------------------------------------------------------------------+ |
| 15160 | |smtp_accept_max_nonmail_hosts|Use: main|Type: host list*|Default: *| |
| 15161 | +-------------------------------------------------------------------+ |
| 15162 | |
| 15163 | You can control which hosts are subject to the smtp_accept_max_nonmail check by |
| 15164 | setting this option. The default value makes it apply to all hosts. By changing |
| 15165 | the value, you can exclude any badly-behaved hosts that you have to live with. |
| 15166 | |
| 15167 | +--------------------------------------------------------------------+ |
| 15168 | |smtp_accept_max_per_connection|Use: main|Type: integer|Default: 1000| |
| 15169 | +--------------------------------------------------------------------+ |
| 15170 | |
| 15171 | The value of this option limits the number of MAIL commands that Exim is |
| 15172 | prepared to accept over a single SMTP connection, whether or not each command |
| 15173 | results in the transfer of a message. After the limit is reached, a 421 |
| 15174 | response is given to subsequent MAIL commands. This limit is a safety |
| 15175 | precaution against a client that goes mad (incidents of this type have been |
| 15176 | seen). |
| 15177 | |
| 15178 | +---------------------------------------------------------------+ |
| 15179 | |smtp_accept_max_per_host|Use: main|Type: string*|Default: unset| |
| 15180 | +---------------------------------------------------------------+ |
| 15181 | |
| 15182 | This option restricts the number of simultaneous IP connections from a single |
| 15183 | host (strictly, from a single IP address) to the Exim daemon. The option is |
| 15184 | expanded, to enable different limits to be applied to different hosts by |
| 15185 | reference to $sender_host_address. Once the limit is reached, additional |
| 15186 | connection attempts from the same host are rejected with error code 421. This |
| 15187 | is entirely independent of smtp_accept_reserve. The option's default value of |
| 15188 | zero imposes no limit. If this option is set greater than zero, it is required |
| 15189 | that smtp_accept_max be non-zero. |
| 15190 | |
| 15191 | Warning: When setting this option you should not use any expansion |
| 15192 | constructions that take an appreciable amount of time. The expansion and test |
| 15193 | happen in the main daemon loop, in order to reject additional connections |
| 15194 | without forking additional processes (otherwise a denial-of-service attack |
| 15195 | could cause a vast number or processes to be created). While the daemon is |
| 15196 | doing this processing, it cannot accept any other incoming connections. |
| 15197 | |
| 15198 | +----------------------------------------------------+ |
| 15199 | |smtp_accept_queue|Use: main|Type: integer|Default: 0| |
| 15200 | +----------------------------------------------------+ |
| 15201 | |
| 15202 | If the number of simultaneous incoming SMTP connections being handled via the |
| 15203 | listening daemon exceeds this value, messages received by SMTP are just placed |
| 15204 | on the queue; no delivery processes are started automatically. The count is |
| 15205 | fixed at the start of an SMTP connection. It cannot be updated in the |
| 15206 | subprocess that receives messages, and so the queueing or not queueing applies |
| 15207 | to all messages received in the same connection. |
| 15208 | |
| 15209 | A value of zero implies no limit, and clearly any non-zero value is useful only |
| 15210 | if it is less than the smtp_accept_max value (unless that is zero). See also |
| 15211 | queue_only, queue_only_load, queue_smtp_domains, and the various -odx command |
| 15212 | line options. |
| 15213 | |
| 15214 | +--------------------------------------------------------------------+ |
| 15215 | |smtp_accept_queue_per_connection|Use: main|Type: integer|Default: 10| |
| 15216 | +--------------------------------------------------------------------+ |
| 15217 | |
| 15218 | This option limits the number of delivery processes that Exim starts |
| 15219 | automatically when receiving messages via SMTP, whether via the daemon or by |
| 15220 | the use of -bs or -bS. If the value of the option is greater than zero, and the |
| 15221 | number of messages received in a single SMTP session exceeds this number, |
| 15222 | subsequent messages are placed on the queue, but no delivery processes are |
| 15223 | started. This helps to limit the number of Exim processes when a server |
| 15224 | restarts after downtime and there is a lot of mail waiting for it on other |
| 15225 | systems. On large systems, the default should probably be increased, and on |
| 15226 | dial-in client systems it should probably be set to zero (that is, disabled). |
| 15227 | |
| 15228 | +------------------------------------------------------+ |
| 15229 | |smtp_accept_reserve|Use: main|Type: integer|Default: 0| |
| 15230 | +------------------------------------------------------+ |
| 15231 | |
| 15232 | When smtp_accept_max is set greater than zero, this option specifies a number |
| 15233 | of SMTP connections that are reserved for connections from the hosts that are |
| 15234 | specified in smtp_reserve_hosts. The value set in smtp_accept_max includes this |
| 15235 | reserve pool. The specified hosts are not restricted to this number of |
| 15236 | connections; the option specifies a minimum number of connection slots for |
| 15237 | them, not a maximum. It is a guarantee that this group of hosts can always get |
| 15238 | at least smtp_accept_reserve connections. However, the limit specified by |
| 15239 | smtp_accept_max_per_host is still applied to each individual host. |
| 15240 | |
| 15241 | For example, if smtp_accept_max is set to 50 and smtp_accept_reserve is set to |
| 15242 | 5, once there are 45 active connections (from any hosts), new connections are |
| 15243 | accepted only from hosts listed in smtp_reserve_hosts, provided the other |
| 15244 | criteria for acceptance are met. |
| 15245 | |
| 15246 | +-----------------------------------------------------------+ |
| 15247 | |smtp_active_hostname|Use: main|Type: string*|Default: unset| |
| 15248 | +-----------------------------------------------------------+ |
| 15249 | |
| 15250 | This option is provided for multi-homed servers that want to masquerade as |
| 15251 | several different hosts. At the start of an incoming SMTP connection, its value |
| 15252 | is expanded and used instead of the value of $primary_hostname in SMTP |
| 15253 | responses. For example, it is used as domain name in the response to an |
| 15254 | incoming HELO or EHLO command. |
| 15255 | |
| 15256 | The active hostname is placed in the $smtp_active_hostname variable, which is |
| 15257 | saved with any messages that are received. It is therefore available for use in |
| 15258 | routers and transports when the message is later delivered. |
| 15259 | |
| 15260 | If this option is unset, or if its expansion is forced to fail, or if the |
| 15261 | expansion results in an empty string, the value of $primary_hostname is used. |
| 15262 | Other expansion failures cause a message to be written to the main and panic |
| 15263 | logs, and the SMTP command receives a temporary error. Typically, the value of |
| 15264 | smtp_active_hostname depends on the incoming interface address. For example: |
| 15265 | |
| 15266 | smtp_active_hostname = ${if eq{$received_ip_address}{10.0.0.1}\ |
| 15267 | {cox.mydomain}{box.mydomain}} |
| 15268 | |
| 15269 | Although $smtp_active_hostname is primarily concerned with incoming messages, |
| 15270 | it is also used as the default for HELO commands in callout verification if |
| 15271 | there is no remote transport from which to obtain a helo_data value. |
| 15272 | |
| 15273 | +------------------------------------------------------+ |
| 15274 | |smtp_banner|Use: main|Type: string*|Default: see below| |
| 15275 | +------------------------------------------------------+ |
| 15276 | |
| 15277 | This string, which is expanded every time it is used, is output as the initial |
| 15278 | positive response to an SMTP connection. The default setting is: |
| 15279 | |
| 15280 | smtp_banner = $smtp_active_hostname ESMTP Exim \ |
| 15281 | $version_number $tod_full |
| 15282 | |
| 15283 | Failure to expand the string causes a panic error. If you want to create a |
| 15284 | multiline response to the initial SMTP connection, use "\n" in the string at |
| 15285 | appropriate points, but not at the end. Note that the 220 code is not included |
| 15286 | in this string. Exim adds it automatically (several times in the case of a |
| 15287 | multiline response). |
| 15288 | |
| 15289 | +------------------------------------------------------------+ |
| 15290 | |smtp_check_spool_space|Use: main|Type: boolean|Default: true| |
| 15291 | +------------------------------------------------------------+ |
| 15292 | |
| 15293 | When this option is set, if an incoming SMTP session encounters the SIZE option |
| 15294 | on a MAIL command, it checks that there is enough space in the spool |
| 15295 | directory's partition to accept a message of that size, while still leaving |
| 15296 | free the amount specified by check_spool_space (even if that value is zero). If |
| 15297 | there isn't enough space, a temporary error code is returned. |
| 15298 | |
| 15299 | +--------------------------------------------------------+ |
| 15300 | |smtp_connect_backlog|Use: main|Type: integer|Default: 20| |
| 15301 | +--------------------------------------------------------+ |
| 15302 | |
| 15303 | This option specifies a maximum number of waiting SMTP connections. Exim passes |
| 15304 | this value to the TCP/IP system when it sets up its listener. Once this number |
| 15305 | of connections are waiting for the daemon's attention, subsequent connection |
| 15306 | attempts are refused at the TCP/IP level. At least, that is what the manuals |
| 15307 | say; in some circumstances such connection attempts have been observed to time |
| 15308 | out instead. For large systems it is probably a good idea to increase the value |
| 15309 | (to 50, say). It also gives some protection against denial-of-service attacks |
| 15310 | by SYN flooding. |
| 15311 | |
| 15312 | +-------------------------------------------------------+ |
| 15313 | |smtp_enforce_sync|Use: main|Type: boolean|Default: true| |
| 15314 | +-------------------------------------------------------+ |
| 15315 | |
| 15316 | The SMTP protocol specification requires the client to wait for a response from |
| 15317 | the server at certain points in the dialogue. Without PIPELINING these |
| 15318 | synchronization points are after every command; with PIPELINING they are fewer, |
| 15319 | but they still exist. |
| 15320 | |
| 15321 | Some spamming sites send out a complete set of SMTP commands without waiting |
| 15322 | for any response. Exim protects against this by rejecting a message if the |
| 15323 | client has sent further input when it should not have. The error response "554 |
| 15324 | SMTP synchronization error" is sent, and the connection is dropped. Testing for |
| 15325 | this error cannot be perfect because of transmission delays (unexpected input |
| 15326 | may be on its way but not yet received when Exim checks). However, it does |
| 15327 | detect many instances. |
| 15328 | |
| 15329 | The check can be globally disabled by setting smtp_enforce_sync false. If you |
| 15330 | want to disable the check selectively (for example, only for certain hosts), |
| 15331 | you can do so by an appropriate use of a control modifier in an ACL (see |
| 15332 | section 43.22). See also pipelining_advertise_hosts. |
| 15333 | |
| 15334 | +--------------------------------------------------------+ |
| 15335 | |smtp_etrn_command|Use: main|Type: string*|Default: unset| |
| 15336 | +--------------------------------------------------------+ |
| 15337 | |
| 15338 | If this option is set, the given command is run whenever an SMTP ETRN command |
| 15339 | is received from a host that is permitted to issue such commands (see chapter |
| 15340 | 43). The string is split up into separate arguments which are independently |
| 15341 | expanded. The expansion variable $domain is set to the argument of the ETRN |
| 15342 | command, and no syntax checking is done on it. For example: |
| 15343 | |
| 15344 | smtp_etrn_command = /etc/etrn_command $domain \ |
| 15345 | $sender_host_address |
| 15346 | |
| 15347 | A new process is created to run the command, but Exim does not wait for it to |
| 15348 | complete. Consequently, its status cannot be checked. If the command cannot be |
| 15349 | run, a line is written to the panic log, but the ETRN caller still receives a |
| 15350 | 250 success response. Exim is normally running under its own uid when receiving |
| 15351 | SMTP, so it is not possible for it to change the uid before running the |
| 15352 | command. |
| 15353 | |
| 15354 | +---------------------------------------------------------+ |
| 15355 | |smtp_etrn_serialize|Use: main|Type: boolean|Default: true| |
| 15356 | +---------------------------------------------------------+ |
| 15357 | |
| 15358 | When this option is set, it prevents the simultaneous execution of more than |
| 15359 | one identical command as a result of ETRN in an SMTP connection. See section |
| 15360 | 48.8 for details. |
| 15361 | |
| 15362 | +------------------------------------------------------------+ |
| 15363 | |smtp_load_reserve|Use: main|Type: fixed-point|Default: unset| |
| 15364 | +------------------------------------------------------------+ |
| 15365 | |
| 15366 | If the system load average ever gets higher than this, incoming SMTP calls are |
| 15367 | accepted only from those hosts that match an entry in smtp_reserve_hosts. If |
| 15368 | smtp_reserve_hosts is not set, no incoming SMTP calls are accepted when the |
| 15369 | load is over the limit. The option has no effect on ancient operating systems |
| 15370 | on which Exim cannot determine the load average. See also |
| 15371 | deliver_queue_load_max and queue_only_load. |
| 15372 | |
| 15373 | +----------------------------------------------------------+ |
| 15374 | |smtp_max_synprot_errors|Use: main|Type: integer|Default: 3| |
| 15375 | +----------------------------------------------------------+ |
| 15376 | |
| 15377 | Exim rejects SMTP commands that contain syntax or protocol errors. In |
| 15378 | particular, a syntactically invalid email address, as in this command: |
| 15379 | |
| 15380 | RCPT TO:<abc xyz@a.b.c> |
| 15381 | |
| 15382 | causes immediate rejection of the command, before any other tests are done. |
| 15383 | (The ACL cannot be run if there is no valid address to set up for it.) An |
| 15384 | example of a protocol error is receiving RCPT before MAIL. If there are too |
| 15385 | many syntax or protocol errors in one SMTP session, the connection is dropped. |
| 15386 | The limit is set by this option. |
| 15387 | |
| 15388 | When the PIPELINING extension to SMTP is in use, some protocol errors are |
| 15389 | "expected", for instance, a RCPT command after a rejected MAIL command. Exim |
| 15390 | assumes that PIPELINING will be used if it advertises it (see |
| 15391 | pipelining_advertise_hosts), and in this situation, "expected" errors do not |
| 15392 | count towards the limit. |
| 15393 | |
| 15394 | +------------------------------------------------------------+ |
| 15395 | |smtp_max_unknown_commands|Use: main|Type: integer|Default: 3| |
| 15396 | +------------------------------------------------------------+ |
| 15397 | |
| 15398 | If there are too many unrecognized commands in an incoming SMTP session, an |
| 15399 | Exim server drops the connection. This is a defence against some kinds of abuse |
| 15400 | that subvert web clients into making connections to SMTP ports; in these |
| 15401 | circumstances, a number of non-SMTP command lines are sent first. |
| 15402 | |
| 15403 | +--------------------------------------------------------------+ |
| 15404 | |smtp_ratelimit_hosts|Use: main|Type: host list*|Default: unset| |
| 15405 | +--------------------------------------------------------------+ |
| 15406 | |
| 15407 | Some sites find it helpful to be able to limit the rate at which certain hosts |
| 15408 | can send them messages, and the rate at which an individual message can specify |
| 15409 | recipients. |
| 15410 | |
| 15411 | Exim has two rate-limiting facilities. This section describes the older |
| 15412 | facility, which can limit rates within a single connection. The newer ratelimit |
| 15413 | ACL condition can limit rates across all connections. See section 43.38 for |
| 15414 | details of the newer facility. |
| 15415 | |
| 15416 | When a host matches smtp_ratelimit_hosts, the values of smtp_ratelimit_mail and |
| 15417 | smtp_ratelimit_rcpt are used to control the rate of acceptance of MAIL and RCPT |
| 15418 | commands in a single SMTP session, respectively. Each option, if set, must |
| 15419 | contain a set of four comma-separated values: |
| 15420 | |
| 15421 | * A threshold, before which there is no rate limiting. |
| 15422 | |
| 15423 | * An initial time delay. Unlike other times in Exim, numbers with decimal |
| 15424 | fractional parts are allowed here. |
| 15425 | |
| 15426 | * A factor by which to increase the delay each time. |
| 15427 | |
| 15428 | * A maximum value for the delay. This should normally be less than 5 minutes, |
| 15429 | because after that time, the client is liable to timeout the SMTP command. |
| 15430 | |
| 15431 | For example, these settings have been used successfully at the site which first |
| 15432 | suggested this feature, for controlling mail from their customers: |
| 15433 | |
| 15434 | smtp_ratelimit_mail = 2,0.5s,1.05,4m |
| 15435 | smtp_ratelimit_rcpt = 4,0.25s,1.015,4m |
| 15436 | |
| 15437 | The first setting specifies delays that are applied to MAIL commands after two |
| 15438 | have been received over a single connection. The initial delay is 0.5 seconds, |
| 15439 | increasing by a factor of 1.05 each time. The second setting applies delays to |
| 15440 | RCPT commands when more than four occur in a single message. |
| 15441 | |
| 15442 | +---------------------------------------------------------+ |
| 15443 | |smtp_ratelimit_mail|Use: main|Type: string|Default: unset| |
| 15444 | +---------------------------------------------------------+ |
| 15445 | |
| 15446 | See smtp_ratelimit_hosts above. |
| 15447 | |
| 15448 | +---------------------------------------------------------+ |
| 15449 | |smtp_ratelimit_rcpt|Use: main|Type: string|Default: unset| |
| 15450 | +---------------------------------------------------------+ |
| 15451 | |
| 15452 | See smtp_ratelimit_hosts above. |
| 15453 | |
| 15454 | +------------------------------------------------------+ |
| 15455 | |smtp_receive_timeout|Use: main|Type: time*|Default: 5m| |
| 15456 | +------------------------------------------------------+ |
| 15457 | |
| 15458 | This sets a timeout value for SMTP reception. It applies to all forms of SMTP |
| 15459 | input, including batch SMTP. If a line of input (either an SMTP command or a |
| 15460 | data line) is not received within this time, the SMTP connection is dropped and |
| 15461 | the message is abandoned. A line is written to the log containing one of the |
| 15462 | following messages: |
| 15463 | |
| 15464 | SMTP command timeout on connection from... |
| 15465 | SMTP data timeout on connection from... |
| 15466 | |
| 15467 | The former means that Exim was expecting to read an SMTP command; the latter |
| 15468 | means that it was in the DATA phase, reading the contents of a message. |
| 15469 | |
| 15470 | If the first character of the option is a "$" the option is expanded before use |
| 15471 | and may depend on $sender_host_name, $sender_host_address and $sender_host_port |
| 15472 | . |
| 15473 | |
| 15474 | The value set by this option can be overridden by the -os command-line option. |
| 15475 | A setting of zero time disables the timeout, but this should never be used for |
| 15476 | SMTP over TCP/IP. (It can be useful in some cases of local input using -bs or |
| 15477 | -bS.) For non-SMTP input, the reception timeout is controlled by |
| 15478 | receive_timeout and -or. |
| 15479 | |
| 15480 | +------------------------------------------------------------+ |
| 15481 | |smtp_reserve_hosts|Use: main|Type: host list*|Default: unset| |
| 15482 | +------------------------------------------------------------+ |
| 15483 | |
| 15484 | This option defines hosts for which SMTP connections are reserved; see |
| 15485 | smtp_accept_reserve and smtp_load_reserve above. |
| 15486 | |
| 15487 | +----------------------------------------------------------------+ |
| 15488 | |smtp_return_error_details|Use: main|Type: boolean|Default: false| |
| 15489 | +----------------------------------------------------------------+ |
| 15490 | |
| 15491 | In the default state, Exim uses bland messages such as "Administrative |
| 15492 | prohibition" when it rejects SMTP commands for policy reasons. Many sysadmins |
| 15493 | like this because it gives away little information to spammers. However, some |
| 15494 | other sysadmins who are applying strict checking policies want to give out much |
| 15495 | fuller information about failures. Setting smtp_return_error_details true |
| 15496 | causes Exim to be more forthcoming. For example, instead of "Administrative |
| 15497 | prohibition", it might give: |
| 15498 | |
| 15499 | 550-Rejected after DATA: '>' missing at end of address: |
| 15500 | 550 failing address in "From" header is: <user@dom.ain |
| 15501 | |
| 15502 | +--------------------------------------------------------------+ |
| 15503 | |smtputf8_advertise_hosts|Use: main|Type: host list*|Default: *| |
| 15504 | +--------------------------------------------------------------+ |
| 15505 | |
| 15506 | When Exim is built with support for internationalised mail names, the |
| 15507 | availability thereof is advertised in response to EHLO only to those client |
| 15508 | hosts that match this option. See chapter 59 for details of Exim's support for |
| 15509 | internationalisation. |
| 15510 | |
| 15511 | +-------------------------------------------------------+ |
| 15512 | |spamd_address|Use: main|Type: string|Default: see below| |
| 15513 | +-------------------------------------------------------+ |
| 15514 | |
| 15515 | This option is available when Exim is compiled with the content-scanning |
| 15516 | extension. It specifies how Exim connects to SpamAssassin's spamd daemon. The |
| 15517 | default value is |
| 15518 | |
| 15519 | 127.0.0.1 783 |
| 15520 | |
| 15521 | See section 44.2 for more details. |
| 15522 | |
| 15523 | +------------------------------------------------------------+ |
| 15524 | |split_spool_directory|Use: main|Type: boolean|Default: false| |
| 15525 | +------------------------------------------------------------+ |
| 15526 | |
| 15527 | If this option is set, it causes Exim to split its input directory into 62 |
| 15528 | subdirectories, each with a single alphanumeric character as its name. The |
| 15529 | sixth character of the message id is used to allocate messages to |
| 15530 | subdirectories; this is the least significant base-62 digit of the time of |
| 15531 | arrival of the message. |
| 15532 | |
| 15533 | Splitting up the spool in this way may provide better performance on systems |
| 15534 | where there are long mail queues, by reducing the number of files in any one |
| 15535 | directory. The msglog directory is also split up in a similar way to the input |
| 15536 | directory; however, if preserve_message_logs is set, all old msglog files are |
| 15537 | still placed in the single directory msglog.OLD. |
| 15538 | |
| 15539 | It is not necessary to take any special action for existing messages when |
| 15540 | changing split_spool_directory. Exim notices messages that are in the "wrong" |
| 15541 | place, and continues to process them. If the option is turned off after a |
| 15542 | period of being on, the subdirectories will eventually empty and be |
| 15543 | automatically deleted. |
| 15544 | |
| 15545 | When split_spool_directory is set, the behaviour of queue runner processes |
| 15546 | changes. Instead of creating a list of all messages in the queue, and then |
| 15547 | trying to deliver each one in turn, it constructs a list of those in one |
| 15548 | sub-directory and tries to deliver them, before moving on to the next |
| 15549 | sub-directory. The sub-directories are processed in a random order. This |
| 15550 | spreads out the scanning of the input directories, and uses less memory. It is |
| 15551 | particularly beneficial when there are lots of messages on the queue. However, |
| 15552 | if queue_run_in_order is set, none of this new processing happens. The entire |
| 15553 | queue has to be scanned and sorted before any deliveries can start. |
| 15554 | |
| 15555 | +--------------------------------------------------------------------+ |
| 15556 | |spool_directory|Use: main|Type: string*|Default: set at compile time| |
| 15557 | +--------------------------------------------------------------------+ |
| 15558 | |
| 15559 | This defines the directory in which Exim keeps its spool, that is, the messages |
| 15560 | it is waiting to deliver. The default value is taken from the compile-time |
| 15561 | configuration setting, if there is one. If not, this option must be set. The |
| 15562 | string is expanded, so it can contain, for example, a reference to |
| 15563 | $primary_hostname. |
| 15564 | |
| 15565 | If the spool directory name is fixed on your installation, it is recommended |
| 15566 | that you set it at build time rather than from this option, particularly if the |
| 15567 | log files are being written to the spool directory (see log_file_path). |
| 15568 | Otherwise log files cannot be used for errors that are detected early on, such |
| 15569 | as failures in the configuration file. |
| 15570 | |
| 15571 | By using this option to override the compiled-in path, it is possible to run |
| 15572 | tests of Exim without using the standard spool. |
| 15573 | |
| 15574 | +----------------------------------------------------+ |
| 15575 | |sqlite_lock_timeout|Use: main|Type: time|Default: 5s| |
| 15576 | +----------------------------------------------------+ |
| 15577 | |
| 15578 | This option controls the timeout that the sqlite lookup uses when trying to |
| 15579 | access an SQLite database. See section 9.26 for more details. |
| 15580 | |
| 15581 | +------------------------------------------------------+ |
| 15582 | |strict_acl_vars|Use: main|Type: boolean|Default: false| |
| 15583 | +------------------------------------------------------+ |
| 15584 | |
| 15585 | This option controls what happens if a syntactically valid but undefined ACL |
| 15586 | variable is referenced. If it is false (the default), an empty string is |
| 15587 | substituted; if it is true, an error is generated. See section 43.19 for |
| 15588 | details of ACL variables. |
| 15589 | |
| 15590 | +------------------------------------------------------------------+ |
| 15591 | |strip_excess_angle_brackets|Use: main|Type: boolean|Default: false| |
| 15592 | +------------------------------------------------------------------+ |
| 15593 | |
| 15594 | If this option is set, redundant pairs of angle brackets round "route-addr" |
| 15595 | items in addresses are stripped. For example, <<xxx@a.b.c.d>> is treated as |
| 15596 | <xxx@a.b.c.d>. If this is in the envelope and the message is passed on to |
| 15597 | another MTA, the excess angle brackets are not passed on. If this option is not |
| 15598 | set, multiple pairs of angle brackets cause a syntax error. |
| 15599 | |
| 15600 | +---------------------------------------------------------+ |
| 15601 | |strip_trailing_dot|Use: main|Type: boolean|Default: false| |
| 15602 | +---------------------------------------------------------+ |
| 15603 | |
| 15604 | If this option is set, a trailing dot at the end of a domain in an address is |
| 15605 | ignored. If this is in the envelope and the message is passed on to another |
| 15606 | MTA, the dot is not passed on. If this option is not set, a dot at the end of a |
| 15607 | domain causes a syntax error. However, addresses in header lines are checked |
| 15608 | only when an ACL requests header syntax checking. |
| 15609 | |
| 15610 | +--------------------------------------------------------+ |
| 15611 | |syslog_duplication|Use: main|Type: boolean|Default: true| |
| 15612 | +--------------------------------------------------------+ |
| 15613 | |
| 15614 | When Exim is logging to syslog, it writes the log lines for its three separate |
| 15615 | logs at different syslog priorities so that they can in principle be separated |
| 15616 | on the logging hosts. Some installations do not require this separation, and in |
| 15617 | those cases, the duplication of certain log lines is a nuisance. If |
| 15618 | syslog_duplication is set false, only one copy of any particular log line is |
| 15619 | written to syslog. For lines that normally go to both the main log and the |
| 15620 | reject log, the reject log version (possibly containing message header lines) |
| 15621 | is written, at LOG_NOTICE priority. Lines that normally go to both the main and |
| 15622 | the panic log are written at the LOG_ALERT priority. |
| 15623 | |
| 15624 | +-----------------------------------------------------+ |
| 15625 | |syslog_facility|Use: main|Type: string|Default: unset| |
| 15626 | +-----------------------------------------------------+ |
| 15627 | |
| 15628 | This option sets the syslog "facility" name, used when Exim is logging to |
| 15629 | syslog. The value must be one of the strings "mail", "user", "news", "uucp", |
| 15630 | "daemon", or "localx" where x is a digit between 0 and 7. If this option is |
| 15631 | unset, "mail" is used. See chapter 52 for details of Exim's logging. |
| 15632 | |
| 15633 | +------------------------------------------------+ |
| 15634 | |syslog_pid|Use: main|Type: boolean|Default: true| |
| 15635 | +------------------------------------------------+ |
| 15636 | |
| 15637 | If syslog_pid is set false, the PID on Exim's log lines are omitted when these |
| 15638 | lines are sent to syslog. (Syslog normally prefixes the log lines with the PID |
| 15639 | of the logging process automatically.) You need to enable the "+pid" log |
| 15640 | selector item, if you want Exim to write it's PID into the logs.) See chapter |
| 15641 | 52 for details of Exim's logging. |
| 15642 | |
| 15643 | +---------------------------------------------------------+ |
| 15644 | |syslog_processname|Use: main|Type: string|Default: "exim"| |
| 15645 | +---------------------------------------------------------+ |
| 15646 | |
| 15647 | This option sets the syslog "ident" name, used when Exim is logging to syslog. |
| 15648 | The value must be no longer than 32 characters. See chapter 52 for details of |
| 15649 | Exim's logging. |
| 15650 | |
| 15651 | +------------------------------------------------------+ |
| 15652 | |syslog_timestamp|Use: main|Type: boolean|Default: true| |
| 15653 | +------------------------------------------------------+ |
| 15654 | |
| 15655 | If syslog_timestamp is set false, the timestamps on Exim's log lines are |
| 15656 | omitted when these lines are sent to syslog. See chapter 52 for details of |
| 15657 | Exim's logging. |
| 15658 | |
| 15659 | +----------------------------------------------------+ |
| 15660 | |system_filter|Use: main|Type: string*|Default: unset| |
| 15661 | +----------------------------------------------------+ |
| 15662 | |
| 15663 | This option specifies an Exim filter file that is applied to all messages at |
| 15664 | the start of each delivery attempt, before any routing is done. System filters |
| 15665 | must be Exim filters; they cannot be Sieve filters. If the system filter |
| 15666 | generates any deliveries to files or pipes, or any new mail messages, the |
| 15667 | appropriate system_filter_..._transport option(s) must be set, to define which |
| 15668 | transports are to be used. Details of this facility are given in chapter 46. |
| 15669 | |
| 15670 | A forced expansion failure results in no filter operation. |
| 15671 | |
| 15672 | +------------------------------------------------------------------------+ |
| 15673 | |system_filter_directory_transport|Use: main|Type: string*|Default: unset| |
| 15674 | +------------------------------------------------------------------------+ |
| 15675 | |
| 15676 | This sets the name of the transport driver that is to be used when the save |
| 15677 | command in a system message filter specifies a path ending in "/", implying |
| 15678 | delivery of each message into a separate file in some directory. During the |
| 15679 | delivery, the variable $address_file contains the path name. |
| 15680 | |
| 15681 | +-------------------------------------------------------------------+ |
| 15682 | |system_filter_file_transport|Use: main|Type: string*|Default: unset| |
| 15683 | +-------------------------------------------------------------------+ |
| 15684 | |
| 15685 | This sets the name of the transport driver that is to be used when the save |
| 15686 | command in a system message filter specifies a path not ending in "/". During |
| 15687 | the delivery, the variable $address_file contains the path name. |
| 15688 | |
| 15689 | +---------------------------------------------------------+ |
| 15690 | |system_filter_group|Use: main|Type: string|Default: unset| |
| 15691 | +---------------------------------------------------------+ |
| 15692 | |
| 15693 | This option is used only when system_filter_user is also set. It sets the gid |
| 15694 | under which the system filter is run, overriding any gid that is associated |
| 15695 | with the user. The value may be numerical or symbolic. |
| 15696 | |
| 15697 | +-------------------------------------------------------------------+ |
| 15698 | |system_filter_pipe_transport|Use: main|Type: string*|Default: unset| |
| 15699 | +-------------------------------------------------------------------+ |
| 15700 | |
| 15701 | This specifies the transport driver that is to be used when a pipe command is |
| 15702 | used in a system filter. During the delivery, the variable $address_pipe |
| 15703 | contains the pipe command. |
| 15704 | |
| 15705 | +--------------------------------------------------------------------+ |
| 15706 | |system_filter_reply_transport|Use: main|Type: string*|Default: unset| |
| 15707 | +--------------------------------------------------------------------+ |
| 15708 | |
| 15709 | This specifies the transport driver that is to be used when a mail command is |
| 15710 | used in a system filter. |
| 15711 | |
| 15712 | +--------------------------------------------------------+ |
| 15713 | |system_filter_user|Use: main|Type: string|Default: unset| |
| 15714 | +--------------------------------------------------------+ |
| 15715 | |
| 15716 | If this option is set to root, the system filter is run in the main Exim |
| 15717 | delivery process, as root. Otherwise, the system filter runs in a separate |
| 15718 | process, as the given user, defaulting to the Exim run-time user. Unless the |
| 15719 | string consists entirely of digits, it is looked up in the password data. |
| 15720 | Failure to find the named user causes a configuration error. The gid is either |
| 15721 | taken from the password data, or specified by system_filter_group. When the uid |
| 15722 | is specified numerically, system_filter_group is required to be set. |
| 15723 | |
| 15724 | If the system filter generates any pipe, file, or reply deliveries, the uid |
| 15725 | under which the filter is run is used when transporting them, unless a |
| 15726 | transport option overrides. |
| 15727 | |
| 15728 | +-------------------------------------------------+ |
| 15729 | |tcp_nodelay|Use: main|Type: boolean|Default: true| |
| 15730 | +-------------------------------------------------+ |
| 15731 | |
| 15732 | If this option is set false, it stops the Exim daemon setting the TCP_NODELAY |
| 15733 | option on its listening sockets. Setting TCP_NODELAY turns off the "Nagle |
| 15734 | algorithm", which is a way of improving network performance in interactive |
| 15735 | (character-by-character) situations. Turning it off should improve Exim's |
| 15736 | performance a bit, so that is what happens by default. However, it appears that |
| 15737 | some broken clients cannot cope, and time out. Hence this option. It affects |
| 15738 | only those sockets that are set up for listening by the daemon. Sockets created |
| 15739 | by the smtp transport for delivering mail always set TCP_NODELAY. |
| 15740 | |
| 15741 | +-----------------------------------------------------+ |
| 15742 | |timeout_frozen_after|Use: main|Type: time|Default: 0s| |
| 15743 | +-----------------------------------------------------+ |
| 15744 | |
| 15745 | If timeout_frozen_after is set to a time greater than zero, a frozen message of |
| 15746 | any kind that has been on the queue for longer than the given time is |
| 15747 | automatically cancelled at the next queue run. If the frozen message is a |
| 15748 | bounce message, it is just discarded; otherwise, a bounce is sent to the |
| 15749 | sender, in a similar manner to cancellation by the -Mg command line option. If |
| 15750 | you want to timeout frozen bounce messages earlier than other kinds of frozen |
| 15751 | message, see ignore_bounce_errors_after. |
| 15752 | |
| 15753 | Note: the default value of zero means no timeouts; with this setting, frozen |
| 15754 | messages remain on the queue forever (except for any frozen bounce messages |
| 15755 | that are released by ignore_bounce_errors_after). |
| 15756 | |
| 15757 | +----------------------------------------------+ |
| 15758 | |timezone|Use: main|Type: string|Default: unset| |
| 15759 | +----------------------------------------------+ |
| 15760 | |
| 15761 | The value of timezone is used to set the environment variable TZ while running |
| 15762 | Exim (if it is different on entry). This ensures that all timestamps created by |
| 15763 | Exim are in the required timezone. If you want all your timestamps to be in UTC |
| 15764 | (aka GMT) you should set |
| 15765 | |
| 15766 | timezone = UTC |
| 15767 | |
| 15768 | The default value is taken from TIMEZONE_DEFAULT in Local/Makefile, or, if that |
| 15769 | is not set, from the value of the TZ environment variable when Exim is built. |
| 15770 | If timezone is set to the empty string, either at build or run time, any |
| 15771 | existing TZ variable is removed from the environment when Exim runs. This is |
| 15772 | appropriate behaviour for obtaining wall-clock time on some, but unfortunately |
| 15773 | not all, operating systems. |
| 15774 | |
| 15775 | +---------------------------------------------------------+ |
| 15776 | |tls_advertise_hosts|Use: main|Type: host list*|Default: *| |
| 15777 | +---------------------------------------------------------+ |
| 15778 | |
| 15779 | When Exim is built with support for TLS encrypted connections, the availability |
| 15780 | of the STARTTLS command to set up an encrypted session is advertised in |
| 15781 | response to EHLO only to those client hosts that match this option. See chapter |
| 15782 | 42 for details of Exim's support for TLS. Note that the default value requires |
| 15783 | that a certificate be supplied using the tls_certificate option. If TLS support |
| 15784 | for incoming connections is not required the tls_advertise_hosts option should |
| 15785 | be set empty. |
| 15786 | |
| 15787 | +------------------------------------------------------+ |
| 15788 | |tls_certificate|Use: main|Type: string*|Default: unset| |
| 15789 | +------------------------------------------------------+ |
| 15790 | |
| 15791 | The value of this option is expanded, and must then be the absolute path to a |
| 15792 | file which contains the server's certificates. The server's private key is also |
| 15793 | assumed to be in this file if tls_privatekey is unset. See chapter 42 for |
| 15794 | further details. |
| 15795 | |
| 15796 | Note: The certificates defined by this option are used only when Exim is |
| 15797 | receiving incoming messages as a server. If you want to supply certificates for |
| 15798 | use when sending messages as a client, you must set the tls_certificate option |
| 15799 | in the relevant smtp transport. |
| 15800 | |
| 15801 | If the option contains $tls_out_sni and Exim is built against OpenSSL, then if |
| 15802 | the OpenSSL build supports TLS extensions and the TLS client sends the Server |
| 15803 | Name Indication extension, then this option and others documented in 42.10 will |
| 15804 | be re-expanded. |
| 15805 | |
| 15806 | If this option is unset or empty a fresh self-signed certificate will be |
| 15807 | generated for every connection. |
| 15808 | |
| 15809 | +----------------------------------------------+ |
| 15810 | |tls_crl|Use: main|Type: string*|Default: unset| |
| 15811 | +----------------------------------------------+ |
| 15812 | |
| 15813 | This option specifies a certificate revocation list. The expanded value must be |
| 15814 | the name of a file that contains a CRL in PEM format. |
| 15815 | |
| 15816 | See 42.10 for discussion of when this option might be re-expanded. |
| 15817 | |
| 15818 | +-----------------------------------------------------+ |
| 15819 | |tls_dh_max_bits|Use: main|Type: integer|Default: 2236| |
| 15820 | +-----------------------------------------------------+ |
| 15821 | |
| 15822 | The number of bits used for Diffie-Hellman key-exchange may be suggested by the |
| 15823 | chosen TLS library. That value might prove to be too high for interoperability. |
| 15824 | This option provides a maximum clamp on the value suggested, trading off |
| 15825 | security for interoperability. |
| 15826 | |
| 15827 | The value must be at least 1024. |
| 15828 | |
| 15829 | The value 2236 was chosen because, at time of adding the option, it was the |
| 15830 | hard-coded maximum value supported by the NSS cryptographic library, as used by |
| 15831 | Thunderbird, while GnuTLS was suggesting 2432 bits as normal. |
| 15832 | |
| 15833 | If you prefer more security and are willing to break some clients, raise this |
| 15834 | number. |
| 15835 | |
| 15836 | Note that the value passed to GnuTLS for *generating* a new prime may be a |
| 15837 | little less than this figure, because GnuTLS is inexact and may produce a |
| 15838 | larger prime than requested. |
| 15839 | |
| 15840 | +--------------------------------------------------+ |
| 15841 | |tls_dhparam|Use: main|Type: string*|Default: unset| |
| 15842 | +--------------------------------------------------+ |
| 15843 | |
| 15844 | The value of this option is expanded and indicates the source of DH parameters |
| 15845 | to be used by Exim. |
| 15846 | |
| 15847 | Note: The Exim Maintainers strongly recommend using a filename with |
| 15848 | site-generated local DH parameters, which has been supported across all |
| 15849 | versions of Exim. The other specific constants available are a fallback so that |
| 15850 | even when "unconfigured", Exim can offer Perfect Forward Secrecy in older |
| 15851 | ciphersuites in TLS. |
| 15852 | |
| 15853 | If tls_dhparam is a filename starting with a "/", then it names a file from |
| 15854 | which DH parameters should be loaded. If the file exists, it should hold a |
| 15855 | PEM-encoded PKCS#3 representation of the DH prime. If the file does not exist, |
| 15856 | for OpenSSL it is an error. For GnuTLS, Exim will attempt to create the file |
| 15857 | and fill it with a generated DH prime. For OpenSSL, if the DH bit-count from |
| 15858 | loading the file is greater than tls_dh_max_bits then it will be ignored, and |
| 15859 | treated as though the tls_dhparam were set to "none". |
| 15860 | |
| 15861 | If this option expands to the string "none", then no DH parameters will be |
| 15862 | loaded by Exim. |
| 15863 | |
| 15864 | If this option expands to the string "historic" and Exim is using GnuTLS, then |
| 15865 | Exim will attempt to load a file from inside the spool directory. If the file |
| 15866 | does not exist, Exim will attempt to create it. See section 42.3 for further |
| 15867 | details. |
| 15868 | |
| 15869 | If Exim is using OpenSSL and this option is empty or unset, then Exim will load |
| 15870 | a default DH prime; the default is Exim-specific but lacks verifiable |
| 15871 | provenance. |
| 15872 | |
| 15873 | In older versions of Exim the default was the 2048 bit prime described in |
| 15874 | section 2.2 of RFC 5114, "2048-bit MODP Group with 224-bit Prime Order |
| 15875 | Subgroup", which in IKE is assigned number 23. |
| 15876 | |
| 15877 | Otherwise, the option must expand to the name used by Exim for any of a number |
| 15878 | of DH primes specified in RFC 2409, RFC 3526, RFC 5114, RFC 7919, or from other |
| 15879 | sources. As names, Exim uses a standard specified name, else "ike" followed by |
| 15880 | the number used by IKE, or "default" which corresponds to |
| 15881 | "exim.dev.20160529.3". |
| 15882 | |
| 15883 | The available standard primes are: "ffdhe2048", "ffdhe3072", "ffdhe4096", |
| 15884 | "ffdhe6144", "ffdhe8192", "ike1", "ike2", "ike5", "ike14", "ike15", "ike16", |
| 15885 | "ike17", "ike18", "ike22", "ike23" and "ike24". |
| 15886 | |
| 15887 | The available additional primes are: "exim.dev.20160529.1", |
| 15888 | "exim.dev.20160529.2" and "exim.dev.20160529.3". |
| 15889 | |
| 15890 | Some of these will be too small to be accepted by clients. Some may be too |
| 15891 | large to be accepted by clients. The open cryptographic community has |
| 15892 | suspicions about the integrity of some of the later IKE values, which led into |
| 15893 | RFC7919 providing new fixed constants (the "ffdhe" identifiers). |
| 15894 | |
| 15895 | At this point, all of the "ike" values should be considered obsolete; they're |
| 15896 | still in Exim to avoid breaking unusual configurations, but are candidates for |
| 15897 | removal the next time we have backwards-incompatible changes. |
| 15898 | |
| 15899 | The TLS protocol does not negotiate an acceptable size for this; clients tend |
| 15900 | to hard-drop connections if what is offered by the server is unacceptable, |
| 15901 | whether too large or too small, and there's no provision for the client to tell |
| 15902 | the server what these constraints are. Thus, as a server operator, you need to |
| 15903 | make an educated guess as to what is most likely to work for your userbase. |
| 15904 | |
| 15905 | Some known size constraints suggest that a bit-size in the range 2048 to 2236 |
| 15906 | is most likely to maximise interoperability. The upper bound comes from |
| 15907 | applications using the Mozilla Network Security Services (NSS) library, which |
| 15908 | used to set its "DH_MAX_P_BITS" upper-bound to 2236. This affects many mail |
| 15909 | user agents (MUAs). The lower bound comes from Debian installs of Exim4 prior |
| 15910 | to the 4.80 release, as Debian used to patch Exim to raise the minimum |
| 15911 | acceptable bound from 1024 to 2048. |
| 15912 | |
| 15913 | +---------------------------------------------------+ |
| 15914 | |tls_eccurve|Use: main|Type: string*|Default: "auto"| |
| 15915 | +---------------------------------------------------+ |
| 15916 | |
| 15917 | This option selects a EC curve for use by Exim. |
| 15918 | |
| 15919 | After expansion it must contain a valid EC curve parameter, such as |
| 15920 | "prime256v1", "secp384r1", or "P-512". Consult your OpenSSL manual for valid |
| 15921 | selections. |
| 15922 | |
| 15923 | For OpenSSL versions before (and not including) 1.0.2, the string "auto" |
| 15924 | selects "prime256v1". For more recent OpenSSL versions "auto" tells the library |
| 15925 | to choose. |
| 15926 | |
| 15927 | If the option expands to an empty string, no EC curves will be enabled. |
| 15928 | |
| 15929 | +----------------------------------------------------+ |
| 15930 | |tls_ocsp_file|Use: main|Type: string*|Default: unset| |
| 15931 | +----------------------------------------------------+ |
| 15932 | |
| 15933 | This option must if set expand to the absolute path to a file which contains a |
| 15934 | current status proof for the server's certificate, as obtained from the |
| 15935 | Certificate Authority. |
| 15936 | |
| 15937 | Usable for GnuTLS 3.4.4 or 3.3.17 or OpenSSL 1.1.0 (or later). |
| 15938 | |
| 15939 | +---------------------------------------------------------------+ |
| 15940 | |tls_on_connect_ports|Use: main|Type: string list|Default: unset| |
| 15941 | +---------------------------------------------------------------+ |
| 15942 | |
| 15943 | This option specifies a list of incoming SSMTP (aka SMTPS) ports that should |
| 15944 | operate the obsolete SSMTP (SMTPS) protocol, where a TLS session is immediately |
| 15945 | set up without waiting for the client to issue a STARTTLS command. For further |
| 15946 | details, see section 13.4. |
| 15947 | |
| 15948 | +-----------------------------------------------------+ |
| 15949 | |tls_privatekey|Use: main|Type: string*|Default: unset| |
| 15950 | +-----------------------------------------------------+ |
| 15951 | |
| 15952 | The value of this option is expanded, and must then be the absolute path to a |
| 15953 | file which contains the server's private key. If this option is unset, or if |
| 15954 | the expansion is forced to fail, or the result is an empty string, the private |
| 15955 | key is assumed to be in the same file as the server's certificates. See chapter |
| 15956 | 42 for further details. |
| 15957 | |
| 15958 | See 42.10 for discussion of when this option might be re-expanded. |
| 15959 | |
| 15960 | +---------------------------------------------------------+ |
| 15961 | |tls_remember_esmtp|Use: main|Type: boolean|Default: false| |
| 15962 | +---------------------------------------------------------+ |
| 15963 | |
| 15964 | If this option is set true, Exim violates the RFCs by remembering that it is in |
| 15965 | "esmtp" state after successfully negotiating a TLS session. This provides |
| 15966 | support for broken clients that fail to send a new EHLO after starting a TLS |
| 15967 | session. |
| 15968 | |
| 15969 | +----------------------------------------------------------+ |
| 15970 | |tls_require_ciphers|Use: main|Type: string*|Default: unset| |
| 15971 | +----------------------------------------------------------+ |
| 15972 | |
| 15973 | This option controls which ciphers can be used for incoming TLS connections. |
| 15974 | The smtp transport has an option of the same name for controlling outgoing |
| 15975 | connections. This option is expanded for each connection, so can be varied for |
| 15976 | different clients if required. The value of this option must be a list of |
| 15977 | permitted cipher suites. The OpenSSL and GnuTLS libraries handle cipher control |
| 15978 | in somewhat different ways. If GnuTLS is being used, the client controls the |
| 15979 | preference order of the available ciphers. Details are given in sections 42.4 |
| 15980 | and 42.5. |
| 15981 | |
| 15982 | +--------------------------------------------------------------+ |
| 15983 | |tls_try_verify_hosts|Use: main|Type: host list*|Default: unset| |
| 15984 | +--------------------------------------------------------------+ |
| 15985 | |
| 15986 | See tls_verify_hosts below. |
| 15987 | |
| 15988 | +---------------------------------------------------------------+ |
| 15989 | |tls_verify_certificates|Use: main|Type: string*|Default: system| |
| 15990 | +---------------------------------------------------------------+ |
| 15991 | |
| 15992 | The value of this option is expanded, and must then be either the word "system" |
| 15993 | or the absolute path to a file or directory containing permitted certificates |
| 15994 | for clients that match tls_verify_hosts or tls_try_verify_hosts. |
| 15995 | |
| 15996 | The "system" value for the option will use a system default location compiled |
| 15997 | into the SSL library. This is not available for GnuTLS versions preceding |
| 15998 | 3.0.20, and will be taken as empty; an explicit location must be specified. |
| 15999 | |
| 16000 | The use of a directory for the option value is not available for GnuTLS |
| 16001 | versions preceding 3.3.6 and a single file must be used. |
| 16002 | |
| 16003 | With OpenSSL the certificates specified explicitly either by file or directory |
| 16004 | are added to those given by the system default location. |
| 16005 | |
| 16006 | These certificates should be for the certificate authorities trusted, rather |
| 16007 | than the public cert of individual clients. With both OpenSSL and GnuTLS, if |
| 16008 | the value is a file then the certificates are sent by Exim as a server to |
| 16009 | connecting clients, defining the list of accepted certificate authorities. Thus |
| 16010 | the values defined should be considered public data. To avoid this, use the |
| 16011 | explicit directory version. |
| 16012 | |
| 16013 | See 42.10 for discussion of when this option might be re-expanded. |
| 16014 | |
| 16015 | A forced expansion failure or setting to an empty string is equivalent to being |
| 16016 | unset. |
| 16017 | |
| 16018 | +----------------------------------------------------------+ |
| 16019 | |tls_verify_hosts|Use: main|Type: host list*|Default: unset| |
| 16020 | +----------------------------------------------------------+ |
| 16021 | |
| 16022 | This option, along with tls_try_verify_hosts, controls the checking of |
| 16023 | certificates from clients. The expected certificates are defined by |
| 16024 | tls_verify_certificates, which must be set. A configuration error occurs if |
| 16025 | either tls_verify_hosts or tls_try_verify_hosts is set and |
| 16026 | tls_verify_certificates is not set. |
| 16027 | |
| 16028 | Any client that matches tls_verify_hosts is constrained by |
| 16029 | tls_verify_certificates. When the client initiates a TLS session, it must |
| 16030 | present one of the listed certificates. If it does not, the connection is |
| 16031 | aborted. Warning: Including a host in tls_verify_hosts does not require the |
| 16032 | host to use TLS. It can still send SMTP commands through unencrypted |
| 16033 | connections. Forcing a client to use TLS has to be done separately using an ACL |
| 16034 | to reject inappropriate commands when the connection is not encrypted. |
| 16035 | |
| 16036 | A weaker form of checking is provided by tls_try_verify_hosts. If a client |
| 16037 | matches this option (but not tls_verify_hosts), Exim requests a certificate and |
| 16038 | checks it against tls_verify_certificates, but does not abort the connection if |
| 16039 | there is no certificate or if it does not match. This state can be detected in |
| 16040 | an ACL, which makes it possible to implement policies such as "accept for relay |
| 16041 | only if a verified certificate has been received, but accept for local delivery |
| 16042 | if encrypted, even without a verified certificate". |
| 16043 | |
| 16044 | Client hosts that match neither of these lists are not asked to present |
| 16045 | certificates. |
| 16046 | |
| 16047 | +----------------------------------------------------------+ |
| 16048 | |trusted_groups|Use: main|Type: string list*|Default: unset| |
| 16049 | +----------------------------------------------------------+ |
| 16050 | |
| 16051 | This option is expanded just once, at the start of Exim's processing. If this |
| 16052 | option is set, any process that is running in one of the listed groups, or |
| 16053 | which has one of them as a supplementary group, is trusted. The groups can be |
| 16054 | specified numerically or by name. See section 5.2 for details of what trusted |
| 16055 | callers are permitted to do. If neither trusted_groups nor trusted_users is |
| 16056 | set, only root and the Exim user are trusted. |
| 16057 | |
| 16058 | +---------------------------------------------------------+ |
| 16059 | |trusted_users|Use: main|Type: string list*|Default: unset| |
| 16060 | +---------------------------------------------------------+ |
| 16061 | |
| 16062 | This option is expanded just once, at the start of Exim's processing. If this |
| 16063 | option is set, any process that is running as one of the listed users is |
| 16064 | trusted. The users can be specified numerically or by name. See section 5.2 for |
| 16065 | details of what trusted callers are permitted to do. If neither trusted_groups |
| 16066 | nor trusted_users is set, only root and the Exim user are trusted. |
| 16067 | |
| 16068 | +----------------------------------------------------+ |
| 16069 | |unknown_login|Use: main|Type: string*|Default: unset| |
| 16070 | +----------------------------------------------------+ |
| 16071 | |
| 16072 | This is a specialized feature for use in unusual configurations. By default, if |
| 16073 | the uid of the caller of Exim cannot be looked up using getpwuid(), Exim gives |
| 16074 | up. The unknown_login option can be used to set a login name to be used in this |
| 16075 | circumstance. It is expanded, so values like user$caller_uid can be set. When |
| 16076 | unknown_login is used, the value of unknown_username is used for the user's |
| 16077 | real name (gecos field), unless this has been set by the -F option. |
| 16078 | |
| 16079 | +------------------------------------------------------+ |
| 16080 | |unknown_username|Use: main|Type: string|Default: unset| |
| 16081 | +------------------------------------------------------+ |
| 16082 | |
| 16083 | See unknown_login. |
| 16084 | |
| 16085 | +-----------------------------------------------------------------+ |
| 16086 | |untrusted_set_sender|Use: main|Type: address list*|Default: unset| |
| 16087 | +-----------------------------------------------------------------+ |
| 16088 | |
| 16089 | When an untrusted user submits a message to Exim using the standard input, Exim |
| 16090 | normally creates an envelope sender address from the user's login and the |
| 16091 | default qualification domain. Data from the -f option (for setting envelope |
| 16092 | senders on non-SMTP messages) or the SMTP MAIL command (if -bs or -bS is used) |
| 16093 | is ignored. |
| 16094 | |
| 16095 | However, untrusted users are permitted to set an empty envelope sender address, |
| 16096 | to declare that a message should never generate any bounces. For example: |
| 16097 | |
| 16098 | exim -f '<>' user@domain.example |
| 16099 | |
| 16100 | The untrusted_set_sender option allows you to permit untrusted users to set |
| 16101 | other envelope sender addresses in a controlled way. When it is set, untrusted |
| 16102 | users are allowed to set envelope sender addresses that match any of the |
| 16103 | patterns in the list. Like all address lists, the string is expanded. The |
| 16104 | identity of the user is in $sender_ident, so you can, for example, restrict |
| 16105 | users to setting senders that start with their login ids followed by a hyphen |
| 16106 | by a setting like this: |
| 16107 | |
| 16108 | untrusted_set_sender = ^$sender_ident- |
| 16109 | |
| 16110 | If you want to allow untrusted users to set envelope sender addresses without |
| 16111 | restriction, you can use |
| 16112 | |
| 16113 | untrusted_set_sender = * |
| 16114 | |
| 16115 | The untrusted_set_sender option applies to all forms of local input, but only |
| 16116 | to the setting of the envelope sender. It does not permit untrusted users to |
| 16117 | use the other options which trusted user can use to override message |
| 16118 | parameters. Furthermore, it does not stop Exim from removing an existing |
| 16119 | Sender: header in the message, or from adding a Sender: header if necessary. |
| 16120 | See local_sender_retain and local_from_check for ways of overriding these |
| 16121 | actions. The handling of the Sender: header is also described in section 47.16. |
| 16122 | |
| 16123 | The log line for a message's arrival shows the envelope sender following "<=". |
| 16124 | For local messages, the user's login always follows, after "U=". In -bp |
| 16125 | displays, and in the Exim monitor, if an untrusted user sets an envelope sender |
| 16126 | address, the user's login is shown in parentheses after the sender address. |
| 16127 | |
| 16128 | +-----------------------------------------------------------+ |
| 16129 | |uucp_from_pattern|Use: main|Type: string|Default: see below| |
| 16130 | +-----------------------------------------------------------+ |
| 16131 | |
| 16132 | Some applications that pass messages to an MTA via a command line interface use |
| 16133 | an initial line starting with "From " to pass the envelope sender. In |
| 16134 | particular, this is used by UUCP software. Exim recognizes such a line by means |
| 16135 | of a regular expression that is set in uucp_from_pattern. When the pattern |
| 16136 | matches, the sender address is constructed by expanding the contents of |
| 16137 | uucp_from_sender, provided that the caller of Exim is a trusted user. The |
| 16138 | default pattern recognizes lines in the following two forms: |
| 16139 | |
| 16140 | From ph10 Fri Jan 5 12:35 GMT 1996 |
| 16141 | From ph10 Fri, 7 Jan 97 14:00:00 GMT |
| 16142 | |
| 16143 | The pattern can be seen by running |
| 16144 | |
| 16145 | exim -bP uucp_from_pattern |
| 16146 | |
| 16147 | It checks only up to the hours and minutes, and allows for a 2-digit or 4-digit |
| 16148 | year in the second case. The first word after "From " is matched in the regular |
| 16149 | expression by a parenthesized subpattern. The default value for |
| 16150 | uucp_from_sender is "$1", which therefore just uses this first word ("ph10" in |
| 16151 | the example above) as the message's sender. See also ignore_fromline_hosts. |
| 16152 | |
| 16153 | +------------------------------------------------------+ |
| 16154 | |uucp_from_sender|Use: main|Type: string*|Default: "$1"| |
| 16155 | +------------------------------------------------------+ |
| 16156 | |
| 16157 | See uucp_from_pattern above. |
| 16158 | |
| 16159 | +-------------------------------------------------------+ |
| 16160 | |warn_message_file|Use: main|Type: string|Default: unset| |
| 16161 | +-------------------------------------------------------+ |
| 16162 | |
| 16163 | This option defines a template file containing paragraphs of text to be used |
| 16164 | for constructing the warning message which is sent by Exim when a message has |
| 16165 | been on the queue for a specified amount of time, as specified by delay_warning |
| 16166 | . Details of the file's contents are given in chapter 49. See also |
| 16167 | bounce_message_file. |
| 16168 | |
| 16169 | +-----------------------------------------------------+ |
| 16170 | |write_rejectlog|Use: main|Type: boolean|Default: true| |
| 16171 | +-----------------------------------------------------+ |
| 16172 | |
| 16173 | If this option is set false, Exim no longer writes anything to the reject log. |
| 16174 | See chapter 52 for details of what Exim writes to its logs. |
| 16175 | |
| 16176 | |
| 16177 | |
| 16178 | =============================================================================== |
| 16179 | 15. GENERIC OPTIONS FOR ROUTERS |
| 16180 | |
| 16181 | This chapter describes the generic options that apply to all routers. Those |
| 16182 | that are preconditions are marked with ** in the "use" field. |
| 16183 | |
| 16184 | For a general description of how a router operates, see sections 3.10 and 3.12. |
| 16185 | The latter specifies the order in which the preconditions are tested. The order |
| 16186 | of expansion of the options that provide data for a transport is: errors_to, |
| 16187 | headers_add, headers_remove, transport. |
| 16188 | |
| 16189 | +------------------------------------------------------+ |
| 16190 | |address_data|Use: routers|Type: string*|Default: unset| |
| 16191 | +------------------------------------------------------+ |
| 16192 | |
| 16193 | The string is expanded just before the router is run, that is, after all the |
| 16194 | precondition tests have succeeded. If the expansion is forced to fail, the |
| 16195 | router declines, the value of address_data remains unchanged, and the more |
| 16196 | option controls what happens next. Other expansion failures cause delivery of |
| 16197 | the address to be deferred. |
| 16198 | |
| 16199 | When the expansion succeeds, the value is retained with the address, and can be |
| 16200 | accessed using the variable $address_data in the current router, subsequent |
| 16201 | routers, and the eventual transport. |
| 16202 | |
| 16203 | Warning: If the current or any subsequent router is a redirect router that runs |
| 16204 | a user's filter file, the contents of $address_data are accessible in the |
| 16205 | filter. This is not normally a problem, because such data is usually either not |
| 16206 | confidential or it "belongs" to the current user, but if you do put |
| 16207 | confidential data into $address_data you need to remember this point. |
| 16208 | |
| 16209 | Even if the router declines or passes, the value of $address_data remains with |
| 16210 | the address, though it can be changed by another address_data setting on a |
| 16211 | subsequent router. If a router generates child addresses, the value of |
| 16212 | $address_data propagates to them. This also applies to the special kind of |
| 16213 | "child" that is generated by a router with the unseen option. |
| 16214 | |
| 16215 | The idea of address_data is that you can use it to look up a lot of data for |
| 16216 | the address once, and then pick out parts of the data later. For example, you |
| 16217 | could use a single LDAP lookup to return a string of the form |
| 16218 | |
| 16219 | uid=1234 gid=5678 mailbox=/mail/xyz forward=/home/xyz/.forward |
| 16220 | |
| 16221 | In the transport you could pick out the mailbox by a setting such as |
| 16222 | |
| 16223 | file = ${extract{mailbox}{$address_data}} |
| 16224 | |
| 16225 | This makes the configuration file less messy, and also reduces the number of |
| 16226 | lookups (though Exim does cache lookups). |
| 16227 | |
| 16228 | The address_data facility is also useful as a means of passing information from |
| 16229 | one router to another, and from a router to a transport. In addition, if |
| 16230 | $address_data is set by a router when verifying a recipient address from an |
| 16231 | ACL, it remains available for use in the rest of the ACL statement. After |
| 16232 | verifying a sender, the value is transferred to $sender_address_data. |
| 16233 | |
| 16234 | +-------------------------------------------------------+ |
| 16235 | |address_test|Use: routers**|Type: boolean|Default: true| |
| 16236 | +-------------------------------------------------------+ |
| 16237 | |
| 16238 | If this option is set false, the router is skipped when routing is being tested |
| 16239 | by means of the -bt command line option. This can be a convenience when your |
| 16240 | first router sends messages to an external scanner, because it saves you having |
| 16241 | to set the "already scanned" indicator when testing real address routing. |
| 16242 | |
| 16243 | +--------------------------------------------------------------+ |
| 16244 | |cannot_route_message|Use: routers|Type: string*|Default: unset| |
| 16245 | +--------------------------------------------------------------+ |
| 16246 | |
| 16247 | This option specifies a text message that is used when an address cannot be |
| 16248 | routed because Exim has run out of routers. The default message is "Unrouteable |
| 16249 | address". This option is useful only on routers that have more set false, or on |
| 16250 | the very last router in a configuration, because the value that is used is |
| 16251 | taken from the last router that is considered. This includes a router that is |
| 16252 | skipped because its preconditions are not met, as well as a router that |
| 16253 | declines. For example, using the default configuration, you could put: |
| 16254 | |
| 16255 | cannot_route_message = Remote domain not found in DNS |
| 16256 | |
| 16257 | on the first router, which is a dnslookup router with more set false, and |
| 16258 | |
| 16259 | cannot_route_message = Unknown local user |
| 16260 | |
| 16261 | on the final router that checks for local users. If string expansion fails for |
| 16262 | this option, the default message is used. Unless the expansion failure was |
| 16263 | explicitly forced, a message about the failure is written to the main and panic |
| 16264 | logs, in addition to the normal message about the routing failure. |
| 16265 | |
| 16266 | +------------------------------------------------------------+ |
| 16267 | |caseful_local_part|Use: routers|Type: boolean|Default: false| |
| 16268 | +------------------------------------------------------------+ |
| 16269 | |
| 16270 | By default, routers handle the local parts of addresses in a case-insensitive |
| 16271 | manner, though the actual case is preserved for transmission with the message. |
| 16272 | If you want the case of letters to be significant in a router, you must set |
| 16273 | this option true. For individual router options that contain address or local |
| 16274 | part lists (for example, local_parts), case-sensitive matching can be turned on |
| 16275 | by "+caseful" as a list item. See section 10.20 for more details. |
| 16276 | |
| 16277 | The value of the $local_part variable is forced to lower case while a router is |
| 16278 | running unless caseful_local_part is set. When a router assigns an address to a |
| 16279 | transport, the value of $local_part when the transport runs is the same as it |
| 16280 | was in the router. Similarly, when a router generates child addresses by |
| 16281 | aliasing or forwarding, the values of $original_local_part and |
| 16282 | $parent_local_part are those that were used by the redirecting router. |
| 16283 | |
| 16284 | This option applies to the processing of an address by a router. When a |
| 16285 | recipient address is being processed in an ACL, there is a separate control |
| 16286 | modifier that can be used to specify case-sensitive processing within the ACL |
| 16287 | (see section 43.22). |
| 16288 | |
| 16289 | +------------------------------------------------------------+ |
| 16290 | |check_local_user|Use: routers**|Type: boolean|Default: false| |
| 16291 | +------------------------------------------------------------+ |
| 16292 | |
| 16293 | When this option is true, Exim checks that the local part of the recipient |
| 16294 | address (with affixes removed if relevant) is the name of an account on the |
| 16295 | local system. The check is done by calling the getpwnam() function rather than |
| 16296 | trying to read /etc/passwd directly. This means that other methods of holding |
| 16297 | password data (such as NIS) are supported. If the local part is a local user, |
| 16298 | $home is set from the password data, and can be tested in other preconditions |
| 16299 | that are evaluated after this one (the order of evaluation is given in section |
| 16300 | 3.12). However, the value of $home can be overridden by router_home_directory. |
| 16301 | If the local part is not a local user, the router is skipped. |
| 16302 | |
| 16303 | If you want to check that the local part is either the name of a local user or |
| 16304 | matches something else, you cannot combine check_local_user with a setting of |
| 16305 | local_parts, because that specifies the logical and of the two conditions. |
| 16306 | However, you can use a passwd lookup in a local_parts setting to achieve this. |
| 16307 | For example: |
| 16308 | |
| 16309 | local_parts = passwd;$local_part : lsearch;/etc/other/users |
| 16310 | |
| 16311 | Note, however, that the side effects of check_local_user (such as setting up a |
| 16312 | home directory) do not occur when a passwd lookup is used in a local_parts (or |
| 16313 | any other) precondition. |
| 16314 | |
| 16315 | +-----------------------------------------------------+ |
| 16316 | |condition|Use: routers**|Type: string*|Default: unset| |
| 16317 | +-----------------------------------------------------+ |
| 16318 | |
| 16319 | This option specifies a general precondition test that has to succeed for the |
| 16320 | router to be called. The condition option is the last precondition to be |
| 16321 | evaluated (see section 3.12). The string is expanded, and if the result is a |
| 16322 | forced failure, or an empty string, or one of the strings "0" or "no" or |
| 16323 | "false" (checked without regard to the case of the letters), the router is |
| 16324 | skipped, and the address is offered to the next one. |
| 16325 | |
| 16326 | If the result is any other value, the router is run (as this is the last |
| 16327 | precondition to be evaluated, all the other preconditions must be true). |
| 16328 | |
| 16329 | This option is unusual in that multiple condition options may be present. All |
| 16330 | condition options must succeed. |
| 16331 | |
| 16332 | The condition option provides a means of applying custom conditions to the |
| 16333 | running of routers. Note that in the case of a simple conditional expansion, |
| 16334 | the default expansion values are exactly what is wanted. For example: |
| 16335 | |
| 16336 | condition = ${if >{$message_age}{600}} |
| 16337 | |
| 16338 | Because of the default behaviour of the string expansion, this is equivalent to |
| 16339 | |
| 16340 | condition = ${if >{$message_age}{600}{true}{}} |
| 16341 | |
| 16342 | A multiple condition example, which succeeds: |
| 16343 | |
| 16344 | condition = ${if >{$message_age}{600}} |
| 16345 | condition = ${if !eq{${lc:$local_part}}{postmaster}} |
| 16346 | condition = foobar |
| 16347 | |
| 16348 | If the expansion fails (other than forced failure) delivery is deferred. Some |
| 16349 | of the other precondition options are common special cases that could in fact |
| 16350 | be specified using condition. |
| 16351 | |
| 16352 | Historical note: We have condition on ACLs and on Routers. Routers are far |
| 16353 | older, and use one set of semantics. ACLs are newer and when they were created, |
| 16354 | the ACL condition process was given far stricter parse semantics. The bool{} |
| 16355 | expansion condition uses the same rules as ACLs. The bool_lax{} expansion |
| 16356 | condition uses the same rules as Routers. More pointedly, the bool_lax{} was |
| 16357 | written to match the existing Router rules processing behavior. |
| 16358 | |
| 16359 | This is best illustrated in an example: |
| 16360 | |
| 16361 | # If used in an ACL condition will fail with a syntax error, but |
| 16362 | # in a router condition any extra characters are treated as a string |
| 16363 | |
| 16364 | $ exim -be '${if eq {${lc:GOOGLE.com}} {google.com}} {yes} {no}}' |
| 16365 | true {yes} {no}} |
| 16366 | |
| 16367 | $ exim -be '${if eq {${lc:WHOIS.com}} {google.com}} {yes} {no}}' |
| 16368 | {yes} {no}} |
| 16369 | |
| 16370 | In each example above, the if statement actually ends after "{google.com}}". |
| 16371 | Since no true or false braces were defined, the default if behavior is to |
| 16372 | return a boolean true or a null answer (which evaluates to false). The rest of |
| 16373 | the line is then treated as a string. So the first example resulted in the |
| 16374 | boolean answer "true" with the string " {yes} {no}}" appended to it. The second |
| 16375 | example resulted in the null output (indicating false) with the string " {yes} |
| 16376 | {no}}" appended to it. |
| 16377 | |
| 16378 | In fact you can put excess forward braces in too. In the router condition, |
| 16379 | Exim's parser only looks for "{" symbols when they mean something, like after a |
| 16380 | "$" or when required as part of a conditional. But otherwise "{" and "}" are |
| 16381 | treated as ordinary string characters. |
| 16382 | |
| 16383 | Thus, in a Router, the above expansion strings will both always evaluate true, |
| 16384 | as the result of expansion is a non-empty string which doesn't match an |
| 16385 | explicit false value. This can be tricky to debug. By contrast, in an ACL |
| 16386 | either of those strings will always result in an expansion error because the |
| 16387 | result doesn't look sufficiently boolean. |
| 16388 | |
| 16389 | +-----------------------------------------------------+ |
| 16390 | |debug_print|Use: routers|Type: string*|Default: unset| |
| 16391 | +-----------------------------------------------------+ |
| 16392 | |
| 16393 | If this option is set and debugging is enabled (see the -d command line option) |
| 16394 | or in address-testing mode (see the -bt command line option), the string is |
| 16395 | expanded and included in the debugging output. If expansion of the string |
| 16396 | fails, the error message is written to the debugging output, and Exim carries |
| 16397 | on processing. This option is provided to help with checking out the values of |
| 16398 | variables and so on when debugging router configurations. For example, if a |
| 16399 | condition option appears not to be working, debug_print can be used to output |
| 16400 | the variables it references. The output happens after checks for domains, |
| 16401 | local_parts, and check_local_user but before any other preconditions are |
| 16402 | tested. A newline is added to the text if it does not end with one. The |
| 16403 | variable $router_name contains the name of the router. |
| 16404 | |
| 16405 | +---------------------------------------------------------+ |
| 16406 | |disable_logging|Use: routers|Type: boolean|Default: false| |
| 16407 | +---------------------------------------------------------+ |
| 16408 | |
| 16409 | If this option is set true, nothing is logged for any routing errors or for any |
| 16410 | deliveries caused by this router. You should not set this option unless you |
| 16411 | really, really know what you are doing. See also the generic transport option |
| 16412 | of the same name. |
| 16413 | |
| 16414 | +---------------------------------------------------------------------+ |
| 16415 | |dnssec_request_domains|Use: routers|Type: domain list*|Default: unset| |
| 16416 | +---------------------------------------------------------------------+ |
| 16417 | |
| 16418 | DNS lookups for domains matching dnssec_request_domains will be done with the |
| 16419 | dnssec request bit set. This applies to all of the SRV, MX, AAAA, A lookup |
| 16420 | sequence. |
| 16421 | |
| 16422 | +---------------------------------------------------------------------+ |
| 16423 | |dnssec_require_domains|Use: routers|Type: domain list*|Default: unset| |
| 16424 | +---------------------------------------------------------------------+ |
| 16425 | |
| 16426 | DNS lookups for domains matching dnssec_require_domains will be done with the |
| 16427 | dnssec request bit set. Any returns not having the Authenticated Data bit (AD |
| 16428 | bit) set will be ignored and logged as a host-lookup failure. This applies to |
| 16429 | all of the SRV, MX, AAAA, A lookup sequence. |
| 16430 | |
| 16431 | +--------------------------------------------------------+ |
| 16432 | |domains|Use: routers**|Type: domain list*|Default: unset| |
| 16433 | +--------------------------------------------------------+ |
| 16434 | |
| 16435 | If this option is set, the router is skipped unless the current domain matches |
| 16436 | the list. If the match is achieved by means of a file lookup, the data that the |
| 16437 | lookup returned for the domain is placed in $domain_data for use in string |
| 16438 | expansions of the driver's private options. See section 3.12 for a list of the |
| 16439 | order in which preconditions are evaluated. |
| 16440 | |
| 16441 | +-----------------------------------------------+ |
| 16442 | |driver|Use: routers|Type: string|Default: unset| |
| 16443 | +-----------------------------------------------+ |
| 16444 | |
| 16445 | This option must always be set. It specifies which of the available routers is |
| 16446 | to be used. |
| 16447 | |
| 16448 | +-----------------------------------------------------+ |
| 16449 | |dsn_lasthop|Use: routers|Type: boolean|Default: false| |
| 16450 | +-----------------------------------------------------+ |
| 16451 | |
| 16452 | If this option is set true, and extended DSN (RFC3461) processing is in effect, |
| 16453 | Exim will not pass on DSN requests to downstream DSN-aware hosts but will |
| 16454 | instead send a success DSN as if the next hop does not support DSN. Not |
| 16455 | effective on redirect routers. |
| 16456 | |
| 16457 | +---------------------------------------------------+ |
| 16458 | |errors_to|Use: routers|Type: string*|Default: unset| |
| 16459 | +---------------------------------------------------+ |
| 16460 | |
| 16461 | If a router successfully handles an address, it may assign the address to a |
| 16462 | transport for delivery or it may generate child addresses. In both cases, if |
| 16463 | there is a delivery problem during later processing, the resulting bounce |
| 16464 | message is sent to the address that results from expanding this string, |
| 16465 | provided that the address verifies successfully. The errors_to option is |
| 16466 | expanded before headers_add, headers_remove, and transport. |
| 16467 | |
| 16468 | The errors_to setting associated with an address can be overridden if it |
| 16469 | subsequently passes through other routers that have their own errors_to |
| 16470 | settings, or if the message is delivered by a transport with a return_path |
| 16471 | setting. |
| 16472 | |
| 16473 | If errors_to is unset, or the expansion is forced to fail, or the result of the |
| 16474 | expansion fails to verify, the errors address associated with the incoming |
| 16475 | address is used. At top level, this is the envelope sender. A non-forced |
| 16476 | expansion failure causes delivery to be deferred. |
| 16477 | |
| 16478 | If an address for which errors_to has been set ends up being delivered over |
| 16479 | SMTP, the envelope sender for that delivery is the errors_to value, so that any |
| 16480 | bounces that are generated by other MTAs on the delivery route are also sent |
| 16481 | there. You can set errors_to to the empty string by either of these settings: |
| 16482 | |
| 16483 | errors_to = |
| 16484 | errors_to = "" |
| 16485 | |
| 16486 | An expansion item that yields an empty string has the same effect. If you do |
| 16487 | this, a locally detected delivery error for addresses processed by this router |
| 16488 | no longer gives rise to a bounce message; the error is discarded. If the |
| 16489 | address is delivered to a remote host, the return path is set to "<>", unless |
| 16490 | overridden by the return_path option on the transport. |
| 16491 | |
| 16492 | If for some reason you want to discard local errors, but use a non-empty MAIL |
| 16493 | command for remote delivery, you can preserve the original return path in |
| 16494 | $address_data in the router, and reinstate it in the transport by setting |
| 16495 | return_path. |
| 16496 | |
| 16497 | The most common use of errors_to is to direct mailing list bounces to the |
| 16498 | manager of the list, as described in section 50.2, or to implement VERP |
| 16499 | (Variable Envelope Return Paths) (see section 50.6). |
| 16500 | |
| 16501 | +-----------------------------------------------+ |
| 16502 | |expn|Use: routers**|Type: boolean|Default: true| |
| 16503 | +-----------------------------------------------+ |
| 16504 | |
| 16505 | If this option is turned off, the router is skipped when testing an address as |
| 16506 | a result of processing an SMTP EXPN command. You might, for example, want to |
| 16507 | turn it off on a router for users' .forward files, while leaving it on for the |
| 16508 | system alias file. See section 3.12 for a list of the order in which |
| 16509 | preconditions are evaluated. |
| 16510 | |
| 16511 | The use of the SMTP EXPN command is controlled by an ACL (see chapter 43). When |
| 16512 | Exim is running an EXPN command, it is similar to testing an address with -bt. |
| 16513 | Compare VRFY, whose counterpart is -bv. |
| 16514 | |
| 16515 | +-----------------------------------------------------+ |
| 16516 | |fail_verify|Use: routers|Type: boolean|Default: false| |
| 16517 | +-----------------------------------------------------+ |
| 16518 | |
| 16519 | Setting this option has the effect of setting both fail_verify_sender and |
| 16520 | fail_verify_recipient to the same value. |
| 16521 | |
| 16522 | +---------------------------------------------------------------+ |
| 16523 | |fail_verify_recipient|Use: routers|Type: boolean|Default: false| |
| 16524 | +---------------------------------------------------------------+ |
| 16525 | |
| 16526 | If this option is true and an address is accepted by this router when verifying |
| 16527 | a recipient, verification fails. |
| 16528 | |
| 16529 | +------------------------------------------------------------+ |
| 16530 | |fail_verify_sender|Use: routers|Type: boolean|Default: false| |
| 16531 | +------------------------------------------------------------+ |
| 16532 | |
| 16533 | If this option is true and an address is accepted by this router when verifying |
| 16534 | a sender, verification fails. |
| 16535 | |
| 16536 | +------------------------------------------------------------+ |
| 16537 | |fallback_hosts|Use: routers|Type: string list|Default: unset| |
| 16538 | +------------------------------------------------------------+ |
| 16539 | |
| 16540 | String expansion is not applied to this option. The argument must be a |
| 16541 | colon-separated list of host names or IP addresses. The list separator can be |
| 16542 | changed (see section 6.20), and a port can be specified with each name or |
| 16543 | address. In fact, the format of each item is exactly the same as defined for |
| 16544 | the list of hosts in a manualroute router (see section 20.5). |
| 16545 | |
| 16546 | If a router queues an address for a remote transport, this host list is |
| 16547 | associated with the address, and used instead of the transport's fallback host |
| 16548 | list. If hosts_randomize is set on the transport, the order of the list is |
| 16549 | randomized for each use. See the fallback_hosts option of the smtp transport |
| 16550 | for further details. |
| 16551 | |
| 16552 | +---------------------------------------------------+ |
| 16553 | |group|Use: routers|Type: string*|Default: see below| |
| 16554 | +---------------------------------------------------+ |
| 16555 | |
| 16556 | When a router queues an address for a transport, and the transport does not |
| 16557 | specify a group, the group given here is used when running the delivery |
| 16558 | process. The group may be specified numerically or by name. If expansion fails, |
| 16559 | the error is logged and delivery is deferred. The default is unset, unless |
| 16560 | check_local_user is set, when the default is taken from the password |
| 16561 | information. See also initgroups and user and the discussion in chapter 23. |
| 16562 | |
| 16563 | +---------------------------------------------------+ |
| 16564 | |headers_add|Use: routers|Type: list*|Default: unset| |
| 16565 | +---------------------------------------------------+ |
| 16566 | |
| 16567 | This option specifies a list of text headers, newline-separated (by default, |
| 16568 | changeable in the usual way), that is associated with any addresses that are |
| 16569 | accepted by the router. Each item is separately expanded, at routing time. |
| 16570 | However, this option has no effect when an address is just being verified. The |
| 16571 | way in which the text is used to add header lines at transport time is |
| 16572 | described in section 47.17. New header lines are not actually added until the |
| 16573 | message is in the process of being transported. This means that references to |
| 16574 | header lines in string expansions in the transport's configuration do not "see" |
| 16575 | the added header lines. |
| 16576 | |
| 16577 | The headers_add option is expanded after errors_to, but before headers_remove |
| 16578 | and transport. If an item is empty, or if an item expansion is forced to fail, |
| 16579 | the item has no effect. Other expansion failures are treated as configuration |
| 16580 | errors. |
| 16581 | |
| 16582 | Unlike most options, headers_add can be specified multiple times for a router; |
| 16583 | all listed headers are added. |
| 16584 | |
| 16585 | Warning 1: The headers_add option cannot be used for a redirect router that has |
| 16586 | the one_time option set. |
| 16587 | |
| 16588 | Warning 2: If the unseen option is set on the router, all header additions are |
| 16589 | deleted when the address is passed on to subsequent routers. For a redirect |
| 16590 | router, if a generated address is the same as the incoming address, this can |
| 16591 | lead to duplicate addresses with different header modifications. Exim does not |
| 16592 | do duplicate deliveries (except, in certain circumstances, to pipes -- see |
| 16593 | section 22.7), but it is undefined which of the duplicates is discarded, so |
| 16594 | this ambiguous situation should be avoided. The repeat_use option of the |
| 16595 | redirect router may be of help. |
| 16596 | |
| 16597 | +------------------------------------------------------+ |
| 16598 | |headers_remove|Use: routers|Type: list*|Default: unset| |
| 16599 | +------------------------------------------------------+ |
| 16600 | |
| 16601 | This option specifies a list of text headers, colon-separated (by default, |
| 16602 | changeable in the usual way), that is associated with any addresses that are |
| 16603 | accepted by the router. Each item is separately expanded, at routing time. |
| 16604 | However, this option has no effect when an address is just being verified. The |
| 16605 | way in which the text is used to remove header lines at transport time is |
| 16606 | described in section 47.17. Header lines are not actually removed until the |
| 16607 | message is in the process of being transported. This means that references to |
| 16608 | header lines in string expansions in the transport's configuration still "see" |
| 16609 | the original header lines. |
| 16610 | |
| 16611 | The headers_remove option is expanded after errors_to and headers_add, but |
| 16612 | before transport. If an item expansion is forced to fail, the item has no |
| 16613 | effect. Other expansion failures are treated as configuration errors. |
| 16614 | |
| 16615 | Unlike most options, headers_remove can be specified multiple times for a |
| 16616 | router; all listed headers are removed. |
| 16617 | |
| 16618 | Warning 1: The headers_remove option cannot be used for a redirect router that |
| 16619 | has the one_time option set. |
| 16620 | |
| 16621 | Warning 2: If the unseen option is set on the router, all header removal |
| 16622 | requests are deleted when the address is passed on to subsequent routers, and |
| 16623 | this can lead to problems with duplicates -- see the similar warning for |
| 16624 | headers_add above. |
| 16625 | |
| 16626 | Warning 3: Because of the separate expansion of the list items, items that |
| 16627 | contain a list separator must have it doubled. To avoid this, change the list |
| 16628 | separator (6.21). |
| 16629 | |
| 16630 | +----------------------------------------------------------------+ |
| 16631 | |ignore_target_hosts|Use: routers|Type: host list*|Default: unset| |
| 16632 | +----------------------------------------------------------------+ |
| 16633 | |
| 16634 | Although this option is a host list, it should normally contain IP address |
| 16635 | entries rather than names. If any host that is looked up by the router has an |
| 16636 | IP address that matches an item in this list, Exim behaves as if that IP |
| 16637 | address did not exist. This option allows you to cope with rogue DNS entries |
| 16638 | like |
| 16639 | |
| 16640 | remote.domain.example. A 127.0.0.1 |
| 16641 | |
| 16642 | by setting |
| 16643 | |
| 16644 | ignore_target_hosts = 127.0.0.1 |
| 16645 | |
| 16646 | on the relevant router. If all the hosts found by a dnslookup router are |
| 16647 | discarded in this way, the router declines. In a conventional configuration, an |
| 16648 | attempt to mail to such a domain would normally provoke the "unrouteable |
| 16649 | domain" error, and an attempt to verify an address in the domain would fail. |
| 16650 | Similarly, if ignore_target_hosts is set on an ipliteral router, the router |
| 16651 | declines if presented with one of the listed addresses. |
| 16652 | |
| 16653 | You can use this option to disable the use of IPv4 or IPv6 for mail delivery by |
| 16654 | means of the first or the second of the following settings, respectively: |
| 16655 | |
| 16656 | ignore_target_hosts = 0.0.0.0/0 |
| 16657 | ignore_target_hosts = <; 0::0/0 |
| 16658 | |
| 16659 | The pattern in the first line matches all IPv4 addresses, whereas the pattern |
| 16660 | in the second line matches all IPv6 addresses. |
| 16661 | |
| 16662 | This option may also be useful for ignoring link-local and site-local IPv6 |
| 16663 | addresses. Because, like all host lists, the value of ignore_target_hosts is |
| 16664 | expanded before use as a list, it is possible to make it dependent on the |
| 16665 | domain that is being routed. |
| 16666 | |
| 16667 | During its expansion, $host_address is set to the IP address that is being |
| 16668 | checked. |
| 16669 | |
| 16670 | +----------------------------------------------------+ |
| 16671 | |initgroups|Use: routers|Type: boolean|Default: false| |
| 16672 | +----------------------------------------------------+ |
| 16673 | |
| 16674 | If the router queues an address for a transport, and this option is true, and |
| 16675 | the uid supplied by the router is not overridden by the transport, the |
| 16676 | initgroups() function is called when running the transport to ensure that any |
| 16677 | additional groups associated with the uid are set up. See also group and user |
| 16678 | and the discussion in chapter 23. |
| 16679 | |
| 16680 | +-----------------------------------------------------------------+ |
| 16681 | |local_part_prefix|Use: routers**|Type: string list|Default: unset| |
| 16682 | +-----------------------------------------------------------------+ |
| 16683 | |
| 16684 | If this option is set, the router is skipped unless the local part starts with |
| 16685 | one of the given strings, or local_part_prefix_optional is true. See section |
| 16686 | 3.12 for a list of the order in which preconditions are evaluated. |
| 16687 | |
| 16688 | The list is scanned from left to right, and the first prefix that matches is |
| 16689 | used. A limited form of wildcard is available; if the prefix begins with an |
| 16690 | asterisk, it matches the longest possible sequence of arbitrary characters at |
| 16691 | the start of the local part. An asterisk should therefore always be followed by |
| 16692 | some character that does not occur in normal local parts. Wildcarding can be |
| 16693 | used to set up multiple user mailboxes, as described in section 50.8. |
| 16694 | |
| 16695 | During the testing of the local_parts option, and while the router is running, |
| 16696 | the prefix is removed from the local part, and is available in the expansion |
| 16697 | variable $local_part_prefix. When a message is being delivered, if the router |
| 16698 | accepts the address, this remains true during subsequent delivery by a |
| 16699 | transport. In particular, the local part that is transmitted in the RCPT |
| 16700 | command for LMTP, SMTP, and BSMTP deliveries has the prefix removed by default. |
| 16701 | This behaviour can be overridden by setting rcpt_include_affixes true on the |
| 16702 | relevant transport. |
| 16703 | |
| 16704 | When an address is being verified, local_part_prefix affects only the behaviour |
| 16705 | of the router. If the callout feature of verification is in use, this means |
| 16706 | that the full address, including the prefix, will be used during the callout. |
| 16707 | |
| 16708 | The prefix facility is commonly used to handle local parts of the form |
| 16709 | owner-something. Another common use is to support local parts of the form |
| 16710 | real-username to bypass a user's .forward file - helpful when trying to tell a |
| 16711 | user their forwarding is broken - by placing a router like this one immediately |
| 16712 | before the router that handles .forward files: |
| 16713 | |
| 16714 | real_localuser: |
| 16715 | driver = accept |
| 16716 | local_part_prefix = real- |
| 16717 | check_local_user |
| 16718 | transport = local_delivery |
| 16719 | |
| 16720 | For security, it would probably be a good idea to restrict the use of this |
| 16721 | router to locally-generated messages, using a condition such as this: |
| 16722 | |
| 16723 | condition = ${if match {$sender_host_address}\ |
| 16724 | {\N^(|127\.0\.0\.1)$\N}} |
| 16725 | |
| 16726 | If both local_part_prefix and local_part_suffix are set for a router, both |
| 16727 | conditions must be met if not optional. Care must be taken if wildcards are |
| 16728 | used in both a prefix and a suffix on the same router. Different separator |
| 16729 | characters must be used to avoid ambiguity. |
| 16730 | |
| 16731 | +--------------------------------------------------------------------+ |
| 16732 | |local_part_prefix_optional|Use: routers|Type: boolean|Default: false| |
| 16733 | +--------------------------------------------------------------------+ |
| 16734 | |
| 16735 | See local_part_prefix above. |
| 16736 | |
| 16737 | +-----------------------------------------------------------------+ |
| 16738 | |local_part_suffix|Use: routers**|Type: string list|Default: unset| |
| 16739 | +-----------------------------------------------------------------+ |
| 16740 | |
| 16741 | This option operates in the same way as local_part_prefix, except that the |
| 16742 | local part must end (rather than start) with the given string, the |
| 16743 | local_part_suffix_optional option determines whether the suffix is mandatory, |
| 16744 | and the wildcard * character, if present, must be the last character of the |
| 16745 | suffix. This option facility is commonly used to handle local parts of the form |
| 16746 | something-request and multiple user mailboxes of the form username-foo. |
| 16747 | |
| 16748 | +--------------------------------------------------------------------+ |
| 16749 | |local_part_suffix_optional|Use: routers|Type: boolean|Default: false| |
| 16750 | +--------------------------------------------------------------------+ |
| 16751 | |
| 16752 | See local_part_suffix above. |
| 16753 | |
| 16754 | +----------------------------------------------------------------+ |
| 16755 | |local_parts|Use: routers**|Type: local part list*|Default: unset| |
| 16756 | +----------------------------------------------------------------+ |
| 16757 | |
| 16758 | The router is run only if the local part of the address matches the list. See |
| 16759 | section 3.12 for a list of the order in which preconditions are evaluated, and |
| 16760 | section 10.21 for a discussion of local part lists. Because the string is |
| 16761 | expanded, it is possible to make it depend on the domain, for example: |
| 16762 | |
| 16763 | local_parts = dbm;/usr/local/specials/$domain |
| 16764 | |
| 16765 | If the match is achieved by a lookup, the data that the lookup returned for the |
| 16766 | local part is placed in the variable $local_part_data for use in expansions of |
| 16767 | the router's private options. You might use this option, for example, if you |
| 16768 | have a large number of local virtual domains, and you want to send all |
| 16769 | postmaster mail to the same place without having to set up an alias in each |
| 16770 | virtual domain: |
| 16771 | |
| 16772 | postmaster: |
| 16773 | driver = redirect |
| 16774 | local_parts = postmaster |
| 16775 | data = postmaster@real.domain.example |
| 16776 | |
| 16777 | +----------------------------------------------------------+ |
| 16778 | |log_as_local|Use: routers|Type: boolean|Default: see below| |
| 16779 | +----------------------------------------------------------+ |
| 16780 | |
| 16781 | Exim has two logging styles for delivery, the idea being to make local |
| 16782 | deliveries stand out more visibly from remote ones. In the "local" style, the |
| 16783 | recipient address is given just as the local part, without a domain. The use of |
| 16784 | this style is controlled by this option. It defaults to true for the accept |
| 16785 | router, and false for all the others. This option applies only when a router |
| 16786 | assigns an address to a transport. It has no effect on routers that redirect |
| 16787 | addresses. |
| 16788 | |
| 16789 | +----------------------------------------------+ |
| 16790 | |more|Use: routers|Type: boolean*|Default: true| |
| 16791 | +----------------------------------------------+ |
| 16792 | |
| 16793 | The result of string expansion for this option must be a valid boolean value, |
| 16794 | that is, one of the strings "yes", "no", "true", or "false". Any other result |
| 16795 | causes an error, and delivery is deferred. If the expansion is forced to fail, |
| 16796 | the default value for the option (true) is used. Other failures cause delivery |
| 16797 | to be deferred. |
| 16798 | |
| 16799 | If this option is set false, and the router declines to handle the address, no |
| 16800 | further routers are tried, routing fails, and the address is bounced. However, |
| 16801 | if the router explicitly passes an address to the following router by means of |
| 16802 | the setting |
| 16803 | |
| 16804 | self = pass |
| 16805 | |
| 16806 | or otherwise, the setting of more is ignored. Also, the setting of more does |
| 16807 | not affect the behaviour if one of the precondition tests fails. In that case, |
| 16808 | the address is always passed to the next router. |
| 16809 | |
| 16810 | Note that address_data is not considered to be a precondition. If its expansion |
| 16811 | is forced to fail, the router declines, and the value of more controls what |
| 16812 | happens next. |
| 16813 | |
| 16814 | +---------------------------------------------------------+ |
| 16815 | |pass_on_timeout|Use: routers|Type: boolean|Default: false| |
| 16816 | +---------------------------------------------------------+ |
| 16817 | |
| 16818 | If a router times out during a host lookup, it normally causes deferral of the |
| 16819 | address. If pass_on_timeout is set, the address is passed on to the next |
| 16820 | router, overriding no_more. This may be helpful for systems that are |
| 16821 | intermittently connected to the Internet, or those that want to pass to a smart |
| 16822 | host any messages that cannot immediately be delivered. |
| 16823 | |
| 16824 | There are occasional other temporary errors that can occur while doing DNS |
| 16825 | lookups. They are treated in the same way as a timeout, and this option applies |
| 16826 | to all of them. |
| 16827 | |
| 16828 | +----------------------------------------------------+ |
| 16829 | |pass_router|Use: routers|Type: string|Default: unset| |
| 16830 | +----------------------------------------------------+ |
| 16831 | |
| 16832 | Routers that recognize the generic self option (dnslookup, ipliteral, and |
| 16833 | manualroute) are able to return "pass", forcing routing to continue, and |
| 16834 | overriding a false setting of more. When one of these routers returns "pass", |
| 16835 | the address is normally handed on to the next router in sequence. This can be |
| 16836 | changed by setting pass_router to the name of another router. However (unlike |
| 16837 | redirect_router) the named router must be below the current router, to avoid |
| 16838 | loops. Note that this option applies only to the special case of "pass". It |
| 16839 | does not apply when a router returns "decline" because it cannot handle an |
| 16840 | address. |
| 16841 | |
| 16842 | +--------------------------------------------------------+ |
| 16843 | |redirect_router|Use: routers|Type: string|Default: unset| |
| 16844 | +--------------------------------------------------------+ |
| 16845 | |
| 16846 | Sometimes an administrator knows that it is pointless to reprocess addresses |
| 16847 | generated from alias or forward files with the same router again. For example, |
| 16848 | if an alias file translates real names into login ids there is no point |
| 16849 | searching the alias file a second time, especially if it is a large file. |
| 16850 | |
| 16851 | The redirect_router option can be set to the name of any router instance. It |
| 16852 | causes the routing of any generated addresses to start at the named router |
| 16853 | instead of at the first router. This option has no effect if the router in |
| 16854 | which it is set does not generate new addresses. |
| 16855 | |
| 16856 | +--------------------------------------------------------------+ |
| 16857 | |require_files|Use: routers**|Type: string list*|Default: unset| |
| 16858 | +--------------------------------------------------------------+ |
| 16859 | |
| 16860 | This option provides a general mechanism for predicating the running of a |
| 16861 | router on the existence or non-existence of certain files or directories. |
| 16862 | Before running a router, as one of its precondition tests, Exim works its way |
| 16863 | through the require_files list, expanding each item separately. |
| 16864 | |
| 16865 | Because the list is split before expansion, any colons in expansion items must |
| 16866 | be doubled, or the facility for using a different list separator must be used. |
| 16867 | If any expansion is forced to fail, the item is ignored. Other expansion |
| 16868 | failures cause routing of the address to be deferred. |
| 16869 | |
| 16870 | If any expanded string is empty, it is ignored. Otherwise, except as described |
| 16871 | below, each string must be a fully qualified file path, optionally preceded by |
| 16872 | "!". The paths are passed to the stat() function to test for the existence of |
| 16873 | the files or directories. The router is skipped if any paths not preceded by "! |
| 16874 | " do not exist, or if any paths preceded by "!" do exist. |
| 16875 | |
| 16876 | If stat() cannot determine whether a file exists or not, delivery of the |
| 16877 | message is deferred. This can happen when NFS-mounted filesystems are |
| 16878 | unavailable. |
| 16879 | |
| 16880 | This option is checked after the domains, local_parts, and senders options, so |
| 16881 | you cannot use it to check for the existence of a file in which to look up a |
| 16882 | domain, local part, or sender. (See section 3.12 for a full list of the order |
| 16883 | in which preconditions are evaluated.) However, as these options are all |
| 16884 | expanded, you can use the exists expansion condition to make such tests. The |
| 16885 | require_files option is intended for checking files that the router may be |
| 16886 | going to use internally, or which are needed by a transport (for example |
| 16887 | .procmailrc). |
| 16888 | |
| 16889 | During delivery, the stat() function is run as root, but there is a facility |
| 16890 | for some checking of the accessibility of a file by another user. This is not a |
| 16891 | proper permissions check, but just a "rough" check that operates as follows: |
| 16892 | |
| 16893 | If an item in a require_files list does not contain any forward slash |
| 16894 | characters, it is taken to be the user (and optional group, separated by a |
| 16895 | comma) to be checked for subsequent files in the list. If no group is specified |
| 16896 | but the user is specified symbolically, the gid associated with the uid is |
| 16897 | used. For example: |
| 16898 | |
| 16899 | require_files = mail:/some/file |
| 16900 | require_files = $local_part:$home/.procmailrc |
| 16901 | |
| 16902 | If a user or group name in a require_files list does not exist, the |
| 16903 | require_files condition fails. |
| 16904 | |
| 16905 | Exim performs the check by scanning along the components of the file path, and |
| 16906 | checking the access for the given uid and gid. It checks for "x" access on |
| 16907 | directories, and "r" access on the final file. Note that this means that file |
| 16908 | access control lists, if the operating system has them, are ignored. |
| 16909 | |
| 16910 | Warning 1: When the router is being run to verify addresses for an incoming |
| 16911 | SMTP message, Exim is not running as root, but under its own uid. This may |
| 16912 | affect the result of a require_files check. In particular, stat() may yield the |
| 16913 | error EACCES ("Permission denied"). This means that the Exim user is not |
| 16914 | permitted to read one of the directories on the file's path. |
| 16915 | |
| 16916 | Warning 2: Even when Exim is running as root while delivering a message, stat() |
| 16917 | can yield EACCES for a file in an NFS directory that is mounted without root |
| 16918 | access. In this case, if a check for access by a particular user is requested, |
| 16919 | Exim creates a subprocess that runs as that user, and tries the check again in |
| 16920 | that process. |
| 16921 | |
| 16922 | The default action for handling an unresolved EACCES is to consider it to be |
| 16923 | caused by a configuration error, and routing is deferred because the existence |
| 16924 | or non-existence of the file cannot be determined. However, in some |
| 16925 | circumstances it may be desirable to treat this condition as if the file did |
| 16926 | not exist. If the file name (or the exclamation mark that precedes the file |
| 16927 | name for non-existence) is preceded by a plus sign, the EACCES error is treated |
| 16928 | as if the file did not exist. For example: |
| 16929 | |
| 16930 | require_files = +/some/file |
| 16931 | |
| 16932 | If the router is not an essential part of verification (for example, it handles |
| 16933 | users' .forward files), another solution is to set the verify option false so |
| 16934 | that the router is skipped when verifying. |
| 16935 | |
| 16936 | +------------------------------------------------------------------+ |
| 16937 | |retry_use_local_part|Use: routers|Type: boolean|Default: see below| |
| 16938 | +------------------------------------------------------------------+ |
| 16939 | |
| 16940 | When a delivery suffers a temporary routing failure, a retry record is created |
| 16941 | in Exim's hints database. For addresses whose routing depends only on the |
| 16942 | domain, the key for the retry record should not involve the local part, but for |
| 16943 | other addresses, both the domain and the local part should be included. |
| 16944 | Usually, remote routing is of the former kind, and local routing is of the |
| 16945 | latter kind. |
| 16946 | |
| 16947 | This option controls whether the local part is used to form the key for retry |
| 16948 | hints for addresses that suffer temporary errors while being handled by this |
| 16949 | router. The default value is true for any router that has check_local_user set, |
| 16950 | and false otherwise. Note that this option does not apply to hints keys for |
| 16951 | transport delays; they are controlled by a generic transport option of the same |
| 16952 | name. |
| 16953 | |
| 16954 | The setting of retry_use_local_part applies only to the router on which it |
| 16955 | appears. If the router generates child addresses, they are routed |
| 16956 | independently; this setting does not become attached to them. |
| 16957 | |
| 16958 | +---------------------------------------------------------------+ |
| 16959 | |router_home_directory|Use: routers|Type: string*|Default: unset| |
| 16960 | +---------------------------------------------------------------+ |
| 16961 | |
| 16962 | This option sets a home directory for use while the router is running. (Compare |
| 16963 | transport_home_directory, which sets a home directory for later transporting.) |
| 16964 | In particular, if used on a redirect router, this option sets a value for $home |
| 16965 | while a filter is running. The value is expanded; forced expansion failure |
| 16966 | causes the option to be ignored - other failures cause the router to defer. |
| 16967 | |
| 16968 | Expansion of router_home_directory happens immediately after the |
| 16969 | check_local_user test (if configured), before any further expansions take |
| 16970 | place. (See section 3.12 for a list of the order in which preconditions are |
| 16971 | evaluated.) While the router is running, router_home_directory overrides the |
| 16972 | value of $home that came from check_local_user. |
| 16973 | |
| 16974 | When a router accepts an address and assigns it to a local transport (including |
| 16975 | the cases when a redirect router generates a pipe, file, or autoreply |
| 16976 | delivery), the home directory setting for the transport is taken from the first |
| 16977 | of these values that is set: |
| 16978 | |
| 16979 | * The home_directory option on the transport; |
| 16980 | |
| 16981 | * The transport_home_directory option on the router; |
| 16982 | |
| 16983 | * The password data if check_local_user is set on the router; |
| 16984 | |
| 16985 | * The router_home_directory option on the router. |
| 16986 | |
| 16987 | In other words, router_home_directory overrides the password data for the |
| 16988 | router, but not for the transport. |
| 16989 | |
| 16990 | +----------------------------------------------+ |
| 16991 | |self|Use: routers|Type: string|Default: freeze| |
| 16992 | +----------------------------------------------+ |
| 16993 | |
| 16994 | This option applies to those routers that use a recipient address to find a |
| 16995 | list of remote hosts. Currently, these are the dnslookup, ipliteral, and |
| 16996 | manualroute routers. Certain configurations of the queryprogram router can also |
| 16997 | specify a list of remote hosts. Usually such routers are configured to send the |
| 16998 | message to a remote host via an smtp transport. The self option specifies what |
| 16999 | happens when the first host on the list turns out to be the local host. The way |
| 17000 | in which Exim checks for the local host is described in section 13.8. |
| 17001 | |
| 17002 | Normally this situation indicates either an error in Exim's configuration (for |
| 17003 | example, the router should be configured not to process this domain), or an |
| 17004 | error in the DNS (for example, the MX should not point to this host). For this |
| 17005 | reason, the default action is to log the incident, defer the address, and |
| 17006 | freeze the message. The following alternatives are provided for use in special |
| 17007 | cases: |
| 17008 | |
| 17009 | defer |
| 17010 | |
| 17011 | Delivery of the message is tried again later, but the message is not |
| 17012 | frozen. |
| 17013 | |
| 17014 | reroute: <domain> |
| 17015 | |
| 17016 | The domain is changed to the given domain, and the address is passed back |
| 17017 | to be reprocessed by the routers. No rewriting of headers takes place. This |
| 17018 | behaviour is essentially a redirection. |
| 17019 | |
| 17020 | reroute: rewrite: <domain> |
| 17021 | |
| 17022 | The domain is changed to the given domain, and the address is passed back |
| 17023 | to be reprocessed by the routers. Any headers that contain the original |
| 17024 | domain are rewritten. |
| 17025 | |
| 17026 | pass |
| 17027 | |
| 17028 | The router passes the address to the next router, or to the router named in |
| 17029 | the pass_router option if it is set. This overrides no_more. During |
| 17030 | subsequent routing and delivery, the variable $self_hostname contains the |
| 17031 | name of the local host that the router encountered. This can be used to |
| 17032 | distinguish between different cases for hosts with multiple names. The |
| 17033 | combination |
| 17034 | |
| 17035 | self = pass |
| 17036 | no_more |
| 17037 | |
| 17038 | ensures that only those addresses that routed to the local host are passed |
| 17039 | on. Without no_more, addresses that were declined for other reasons would |
| 17040 | also be passed to the next router. |
| 17041 | |
| 17042 | fail |
| 17043 | |
| 17044 | Delivery fails and an error report is generated. |
| 17045 | |
| 17046 | send |
| 17047 | |
| 17048 | The anomaly is ignored and the address is queued for the transport. This |
| 17049 | setting should be used with extreme caution. For an smtp transport, it |
| 17050 | makes sense only in cases where the program that is listening on the SMTP |
| 17051 | port is not this version of Exim. That is, it must be some other MTA, or |
| 17052 | Exim with a different configuration file that handles the domain in another |
| 17053 | way. |
| 17054 | |
| 17055 | +---------------------------------------------------------+ |
| 17056 | |senders|Use: routers**|Type: address list*|Default: unset| |
| 17057 | +---------------------------------------------------------+ |
| 17058 | |
| 17059 | If this option is set, the router is skipped unless the message's sender |
| 17060 | address matches something on the list. See section 3.12 for a list of the order |
| 17061 | in which preconditions are evaluated. |
| 17062 | |
| 17063 | There are issues concerning verification when the running of routers is |
| 17064 | dependent on the sender. When Exim is verifying the address in an errors_to |
| 17065 | setting, it sets the sender to the null string. When using the -bt option to |
| 17066 | check a configuration file, it is necessary also to use the -f option to set an |
| 17067 | appropriate sender. For incoming mail, the sender is unset when verifying the |
| 17068 | sender, but is available when verifying any recipients. If the SMTP VRFY |
| 17069 | command is enabled, it must be used after MAIL if the sender address matters. |
| 17070 | |
| 17071 | +--------------------------------------------------------------+ |
| 17072 | |translate_ip_address|Use: routers|Type: string*|Default: unset| |
| 17073 | +--------------------------------------------------------------+ |
| 17074 | |
| 17075 | There exist some rare networking situations (for example, packet radio) where |
| 17076 | it is helpful to be able to translate IP addresses generated by normal routing |
| 17077 | mechanisms into other IP addresses, thus performing a kind of manual IP |
| 17078 | routing. This should be done only if the normal IP routing of the TCP/IP stack |
| 17079 | is inadequate or broken. Because this is an extremely uncommon requirement, the |
| 17080 | code to support this option is not included in the Exim binary unless |
| 17081 | SUPPORT_TRANSLATE_IP_ADDRESS=yes is set in Local/Makefile. |
| 17082 | |
| 17083 | The translate_ip_address string is expanded for every IP address generated by |
| 17084 | the router, with the generated address set in $host_address. If the expansion |
| 17085 | is forced to fail, no action is taken. For any other expansion error, delivery |
| 17086 | of the message is deferred. If the result of the expansion is an IP address, |
| 17087 | that replaces the original address; otherwise the result is assumed to be a |
| 17088 | host name - this is looked up using gethostbyname() (or getipnodebyname() when |
| 17089 | available) to produce one or more replacement IP addresses. For example, to |
| 17090 | subvert all IP addresses in some specific networks, this could be added to a |
| 17091 | router: |
| 17092 | |
| 17093 | translate_ip_address = \ |
| 17094 | ${lookup{${mask:$host_address/26}}lsearch{/some/file}\ |
| 17095 | {$value}fail}} |
| 17096 | |
| 17097 | The file would contain lines like |
| 17098 | |
| 17099 | 10.2.3.128/26 some.host |
| 17100 | 10.8.4.34/26 10.44.8.15 |
| 17101 | |
| 17102 | You should not make use of this facility unless you really understand what you |
| 17103 | are doing. |
| 17104 | |
| 17105 | +---------------------------------------------------+ |
| 17106 | |transport|Use: routers|Type: string*|Default: unset| |
| 17107 | +---------------------------------------------------+ |
| 17108 | |
| 17109 | This option specifies the transport to be used when a router accepts an address |
| 17110 | and sets it up for delivery. A transport is never needed if a router is used |
| 17111 | only for verification. The value of the option is expanded at routing time, |
| 17112 | after the expansion of errors_to, headers_add, and headers_remove, and result |
| 17113 | must be the name of one of the configured transports. If it is not, delivery is |
| 17114 | deferred. |
| 17115 | |
| 17116 | The transport option is not used by the redirect router, but it does have some |
| 17117 | private options that set up transports for pipe and file deliveries (see |
| 17118 | chapter 22). |
| 17119 | |
| 17120 | +---------------------------------------------------------------------+ |
| 17121 | |transport_current_directory|Use: routers|Type: string*|Default: unset| |
| 17122 | +---------------------------------------------------------------------+ |
| 17123 | |
| 17124 | This option associates a current directory with any address that is routed to a |
| 17125 | local transport. This can happen either because a transport is explicitly |
| 17126 | configured for the router, or because it generates a delivery to a file or a |
| 17127 | pipe. During the delivery process (that is, at transport time), this option |
| 17128 | string is expanded and is set as the current directory, unless overridden by a |
| 17129 | setting on the transport. If the expansion fails for any reason, including |
| 17130 | forced failure, an error is logged, and delivery is deferred. See chapter 23 |
| 17131 | for details of the local delivery environment. |
| 17132 | |
| 17133 | +----------------------------------------------------------------------+ |
| 17134 | |transport_home_directory|Use: routers|Type: string*|Default: see below| |
| 17135 | +----------------------------------------------------------------------+ |
| 17136 | |
| 17137 | This option associates a home directory with any address that is routed to a |
| 17138 | local transport. This can happen either because a transport is explicitly |
| 17139 | configured for the router, or because it generates a delivery to a file or a |
| 17140 | pipe. During the delivery process (that is, at transport time), the option |
| 17141 | string is expanded and is set as the home directory, unless overridden by a |
| 17142 | setting of home_directory on the transport. If the expansion fails for any |
| 17143 | reason, including forced failure, an error is logged, and delivery is deferred. |
| 17144 | |
| 17145 | If the transport does not specify a home directory, and |
| 17146 | transport_home_directory is not set for the router, the home directory for the |
| 17147 | transport is taken from the password data if check_local_user is set for the |
| 17148 | router. Otherwise it is taken from router_home_directory if that option is set; |
| 17149 | if not, no home directory is set for the transport. |
| 17150 | |
| 17151 | See chapter 23 for further details of the local delivery environment. |
| 17152 | |
| 17153 | +-------------------------------------------------+ |
| 17154 | |unseen|Use: routers|Type: boolean*|Default: false| |
| 17155 | +-------------------------------------------------+ |
| 17156 | |
| 17157 | The result of string expansion for this option must be a valid boolean value, |
| 17158 | that is, one of the strings "yes", "no", "true", or "false". Any other result |
| 17159 | causes an error, and delivery is deferred. If the expansion is forced to fail, |
| 17160 | the default value for the option (false) is used. Other failures cause delivery |
| 17161 | to be deferred. |
| 17162 | |
| 17163 | When this option is set true, routing does not cease if the router accepts the |
| 17164 | address. Instead, a copy of the incoming address is passed to the next router, |
| 17165 | overriding a false setting of more. There is little point in setting more false |
| 17166 | if unseen is always true, but it may be useful in cases when the value of |
| 17167 | unseen contains expansion items (and therefore, presumably, is sometimes true |
| 17168 | and sometimes false). |
| 17169 | |
| 17170 | Setting the unseen option has a similar effect to the unseen command qualifier |
| 17171 | in filter files. It can be used to cause copies of messages to be delivered to |
| 17172 | some other destination, while also carrying out a normal delivery. In effect, |
| 17173 | the current address is made into a "parent" that has two children - one that is |
| 17174 | delivered as specified by this router, and a clone that goes on to be routed |
| 17175 | further. For this reason, unseen may not be combined with the one_time option |
| 17176 | in a redirect router. |
| 17177 | |
| 17178 | Warning: Header lines added to the address (or specified for removal) by this |
| 17179 | router or by previous routers affect the "unseen" copy of the message only. The |
| 17180 | clone that continues to be processed by further routers starts with no added |
| 17181 | headers and none specified for removal. For a redirect router, if a generated |
| 17182 | address is the same as the incoming address, this can lead to duplicate |
| 17183 | addresses with different header modifications. Exim does not do duplicate |
| 17184 | deliveries (except, in certain circumstances, to pipes -- see section 22.7), |
| 17185 | but it is undefined which of the duplicates is discarded, so this ambiguous |
| 17186 | situation should be avoided. The repeat_use option of the redirect router may |
| 17187 | be of help. |
| 17188 | |
| 17189 | Unlike the handling of header modifications, any data that was set by the |
| 17190 | address_data option in the current or previous routers is passed on to |
| 17191 | subsequent routers. |
| 17192 | |
| 17193 | +--------------------------------------------------+ |
| 17194 | |user|Use: routers|Type: string*|Default: see below| |
| 17195 | +--------------------------------------------------+ |
| 17196 | |
| 17197 | When a router queues an address for a transport, and the transport does not |
| 17198 | specify a user, the user given here is used when running the delivery process. |
| 17199 | The user may be specified numerically or by name. If expansion fails, the error |
| 17200 | is logged and delivery is deferred. This user is also used by the redirect |
| 17201 | router when running a filter file. The default is unset, except when |
| 17202 | check_local_user is set. In this case, the default is taken from the password |
| 17203 | information. If the user is specified as a name, and group is not set, the |
| 17204 | group associated with the user is used. See also initgroups and group and the |
| 17205 | discussion in chapter 23. |
| 17206 | |
| 17207 | +-------------------------------------------------+ |
| 17208 | |verify|Use: routers**|Type: boolean|Default: true| |
| 17209 | +-------------------------------------------------+ |
| 17210 | |
| 17211 | Setting this option has the effect of setting verify_sender and |
| 17212 | verify_recipient to the same value. |
| 17213 | |
| 17214 | +-------------------------------------------------------+ |
| 17215 | |verify_only|Use: routers**|Type: boolean|Default: false| |
| 17216 | +-------------------------------------------------------+ |
| 17217 | |
| 17218 | If this option is set, the router is used only when verifying an address, |
| 17219 | delivering in cutthrough mode or testing with the -bv option, not when actually |
| 17220 | doing a delivery, testing with the -bt option, or running the SMTP EXPN |
| 17221 | command. It can be further restricted to verifying only senders or recipients |
| 17222 | by means of verify_sender and verify_recipient. |
| 17223 | |
| 17224 | Warning: When the router is being run to verify addresses for an incoming SMTP |
| 17225 | message, Exim is not running as root, but under its own uid. If the router |
| 17226 | accesses any files, you need to make sure that they are accessible to the Exim |
| 17227 | user or group. |
| 17228 | |
| 17229 | +-----------------------------------------------------------+ |
| 17230 | |verify_recipient|Use: routers**|Type: boolean|Default: true| |
| 17231 | +-----------------------------------------------------------+ |
| 17232 | |
| 17233 | If this option is false, the router is skipped when verifying recipient |
| 17234 | addresses, delivering in cutthrough mode or testing recipient verification |
| 17235 | using -bv. See section 3.12 for a list of the order in which preconditions are |
| 17236 | evaluated. See also the $verify_mode variable. |
| 17237 | |
| 17238 | +--------------------------------------------------------+ |
| 17239 | |verify_sender|Use: routers**|Type: boolean|Default: true| |
| 17240 | +--------------------------------------------------------+ |
| 17241 | |
| 17242 | If this option is false, the router is skipped when verifying sender addresses |
| 17243 | or testing sender verification using -bvs. See section 3.12 for a list of the |
| 17244 | order in which preconditions are evaluated. See also the $verify_mode variable. |
| 17245 | |
| 17246 | |
| 17247 | |
| 17248 | =============================================================================== |
| 17249 | 16. THE ACCEPT ROUTER |
| 17250 | |
| 17251 | The accept router has no private options of its own. Unless it is being used |
| 17252 | purely for verification (see verify_only) a transport is required to be defined |
| 17253 | by the generic transport option. If the preconditions that are specified by |
| 17254 | generic options are met, the router accepts the address and queues it for the |
| 17255 | given transport. The most common use of this router is for setting up |
| 17256 | deliveries to local mailboxes. For example: |
| 17257 | |
| 17258 | localusers: |
| 17259 | driver = accept |
| 17260 | domains = mydomain.example |
| 17261 | check_local_user |
| 17262 | transport = local_delivery |
| 17263 | |
| 17264 | The domains condition in this example checks the domain of the address, and |
| 17265 | check_local_user checks that the local part is the login of a local user. When |
| 17266 | both preconditions are met, the accept router runs, and queues the address for |
| 17267 | the local_delivery transport. |
| 17268 | |
| 17269 | |
| 17270 | |
| 17271 | =============================================================================== |
| 17272 | 17. THE DNSLOOKUP ROUTER |
| 17273 | |
| 17274 | The dnslookup router looks up the hosts that handle mail for the recipient's |
| 17275 | domain in the DNS. A transport must always be set for this router, unless |
| 17276 | verify_only is set. |
| 17277 | |
| 17278 | If SRV support is configured (see check_srv below), Exim first searches for SRV |
| 17279 | records. If none are found, or if SRV support is not configured, MX records are |
| 17280 | looked up. If no MX records exist, address records are sought. However, |
| 17281 | mx_domains can be set to disable the direct use of address records. |
| 17282 | |
| 17283 | MX records of equal priority are sorted by Exim into a random order. Exim then |
| 17284 | looks for address records for the host names obtained from MX or SRV records. |
| 17285 | When a host has more than one IP address, they are sorted into a random order, |
| 17286 | except that IPv6 addresses are always sorted before IPv4 addresses. If all the |
| 17287 | IP addresses found are discarded by a setting of the ignore_target_hosts |
| 17288 | generic option, the router declines. |
| 17289 | |
| 17290 | Unless they have the highest priority (lowest MX value), MX records that point |
| 17291 | to the local host, or to any host name that matches hosts_treat_as_local, are |
| 17292 | discarded, together with any other MX records of equal or lower priority. |
| 17293 | |
| 17294 | If the host pointed to by the highest priority MX record, or looked up as an |
| 17295 | address record, is the local host, or matches hosts_treat_as_local, what |
| 17296 | happens is controlled by the generic self option. |
| 17297 | |
| 17298 | |
| 17299 | 17.1 Problems with DNS lookups |
| 17300 | ------------------------------ |
| 17301 | |
| 17302 | There have been problems with DNS servers when SRV records are looked up. Some |
| 17303 | misbehaving servers return a DNS error or timeout when a non-existent SRV |
| 17304 | record is sought. Similar problems have in the past been reported for MX |
| 17305 | records. The global dns_again_means_nonexist option can help with this problem, |
| 17306 | but it is heavy-handed because it is a global option. |
| 17307 | |
| 17308 | For this reason, there are two options, srv_fail_domains and mx_fail_domains, |
| 17309 | that control what happens when a DNS lookup in a dnslookup router results in a |
| 17310 | DNS failure or a "try again" response. If an attempt to look up an SRV or MX |
| 17311 | record causes one of these results, and the domain matches the relevant list, |
| 17312 | Exim behaves as if the DNS had responded "no such record". In the case of an |
| 17313 | SRV lookup, this means that the router proceeds to look for MX records; in the |
| 17314 | case of an MX lookup, it proceeds to look for A or AAAA records, unless the |
| 17315 | domain matches mx_domains, in which case routing fails. |
| 17316 | |
| 17317 | |
| 17318 | 17.2 Declining addresses by dnslookup |
| 17319 | ------------------------------------- |
| 17320 | |
| 17321 | There are a few cases where a dnslookup router will decline to accept an |
| 17322 | address; if such a router is expected to handle "all remaining non-local |
| 17323 | domains", then it is important to set no_more. |
| 17324 | |
| 17325 | The router will defer rather than decline if the domain is found in the |
| 17326 | fail_defer_domains router option. |
| 17327 | |
| 17328 | Reasons for a dnslookup router to decline currently include: |
| 17329 | |
| 17330 | * The domain does not exist in DNS |
| 17331 | |
| 17332 | * The domain exists but the MX record's host part is just "."; this is a |
| 17333 | common convention (borrowed from SRV) used to indicate that there is no |
| 17334 | such service for this domain and to not fall back to trying A/AAAA records. |
| 17335 | |
| 17336 | * Ditto, but for SRV records, when check_srv is set on this router. |
| 17337 | |
| 17338 | * MX record points to a non-existent host. |
| 17339 | |
| 17340 | * MX record points to an IP address and the main section option |
| 17341 | allow_mx_to_ip is not set. |
| 17342 | |
| 17343 | * MX records exist and point to valid hosts, but all hosts resolve only to |
| 17344 | addresses blocked by the ignore_target_hosts generic option on this router. |
| 17345 | |
| 17346 | * The domain is not syntactically valid (see also allow_utf8_domains and |
| 17347 | dns_check_names_pattern for handling one variant of this) |
| 17348 | |
| 17349 | * check_secondary_mx is set on this router but the local host can not be |
| 17350 | found in the MX records (see below) |
| 17351 | |
| 17352 | |
| 17353 | 17.3 Private options for dnslookup |
| 17354 | ---------------------------------- |
| 17355 | |
| 17356 | The private options for the dnslookup router are as follows: |
| 17357 | |
| 17358 | +--------------------------------------------------------------+ |
| 17359 | |check_secondary_mx|Use: dnslookup|Type: boolean|Default: false| |
| 17360 | +--------------------------------------------------------------+ |
| 17361 | |
| 17362 | If this option is set, the router declines unless the local host is found in |
| 17363 | (and removed from) the list of hosts obtained by MX lookup. This can be used to |
| 17364 | process domains for which the local host is a secondary mail exchanger |
| 17365 | differently to other domains. The way in which Exim decides whether a host is |
| 17366 | the local host is described in section 13.8. |
| 17367 | |
| 17368 | +-----------------------------------------------------+ |
| 17369 | |check_srv|Use: dnslookup|Type: string*|Default: unset| |
| 17370 | +-----------------------------------------------------+ |
| 17371 | |
| 17372 | The dnslookup router supports the use of SRV records (see RFC 2782) in addition |
| 17373 | to MX and address records. The support is disabled by default. To enable SRV |
| 17374 | support, set the check_srv option to the name of the service required. For |
| 17375 | example, |
| 17376 | |
| 17377 | check_srv = smtp |
| 17378 | |
| 17379 | looks for SRV records that refer to the normal smtp service. The option is |
| 17380 | expanded, so the service name can vary from message to message or address to |
| 17381 | address. This might be helpful if SRV records are being used for a submission |
| 17382 | service. If the expansion is forced to fail, the check_srv option is ignored, |
| 17383 | and the router proceeds to look for MX records in the normal way. |
| 17384 | |
| 17385 | When the expansion succeeds, the router searches first for SRV records for the |
| 17386 | given service (it assumes TCP protocol). A single SRV record with a host name |
| 17387 | that consists of just a single dot indicates "no such service for this domain"; |
| 17388 | if this is encountered, the router declines. If other kinds of SRV record are |
| 17389 | found, they are used to construct a host list for delivery according to the |
| 17390 | rules of RFC 2782. MX records are not sought in this case. |
| 17391 | |
| 17392 | When no SRV records are found, MX records (and address records) are sought in |
| 17393 | the traditional way. In other words, SRV records take precedence over MX |
| 17394 | records, just as MX records take precedence over address records. Note that |
| 17395 | this behaviour is not sanctioned by RFC 2782, though a previous draft RFC |
| 17396 | defined it. It is apparently believed that MX records are sufficient for email |
| 17397 | and that SRV records should not be used for this purpose. However, SRV records |
| 17398 | have an additional "weight" feature which some people might find useful when |
| 17399 | trying to split an SMTP load between hosts of different power. |
| 17400 | |
| 17401 | See section 17.1 above for a discussion of Exim's behaviour when there is a DNS |
| 17402 | lookup error. |
| 17403 | |
| 17404 | +-------------------------------------------------------------------+ |
| 17405 | |fail_defer_domains|Use: dnslookup|Type: domain list*|Default: unset| |
| 17406 | +-------------------------------------------------------------------+ |
| 17407 | |
| 17408 | DNS lookups for domains matching fail_defer_domains which find no matching |
| 17409 | record will cause the router to defer rather than the default behaviour of |
| 17410 | decline. This maybe be useful for queueing messages for a newly created domain |
| 17411 | while the DNS configuration is not ready. However, it will result in any |
| 17412 | message with mistyped domains also being queued. |
| 17413 | |
| 17414 | +-----------------------------------------------------------+ |
| 17415 | |mx_domains|Use: dnslookup|Type: domain list*|Default: unset| |
| 17416 | +-----------------------------------------------------------+ |
| 17417 | |
| 17418 | A domain that matches mx_domains is required to have either an MX or an SRV |
| 17419 | record in order to be recognized. (The name of this option could be improved.) |
| 17420 | For example, if all the mail hosts in fict.example are known to have MX |
| 17421 | records, except for those in discworld.fict.example, you could use this |
| 17422 | setting: |
| 17423 | |
| 17424 | mx_domains = ! *.discworld.fict.example : *.fict.example |
| 17425 | |
| 17426 | This specifies that messages addressed to a domain that matches the list but |
| 17427 | has no MX record should be bounced immediately instead of being routed using |
| 17428 | the address record. |
| 17429 | |
| 17430 | +----------------------------------------------------------------+ |
| 17431 | |mx_fail_domains|Use: dnslookup|Type: domain list*|Default: unset| |
| 17432 | +----------------------------------------------------------------+ |
| 17433 | |
| 17434 | If the DNS lookup for MX records for one of the domains in this list causes a |
| 17435 | DNS lookup error, Exim behaves as if no MX records were found. See section 17.1 |
| 17436 | for more discussion. |
| 17437 | |
| 17438 | +---------------------------------------------------------+ |
| 17439 | |qualify_single|Use: dnslookup|Type: boolean|Default: true| |
| 17440 | +---------------------------------------------------------+ |
| 17441 | |
| 17442 | When this option is true, the resolver option RES_DEFNAMES is set for DNS |
| 17443 | lookups. Typically, but not standardly, this causes the resolver to qualify |
| 17444 | single-component names with the default domain. For example, on a machine |
| 17445 | called dictionary.ref.example, the domain thesaurus would be changed to |
| 17446 | thesaurus.ref.example inside the resolver. For details of what your resolver |
| 17447 | actually does, consult your man pages for resolver and resolv.conf. |
| 17448 | |
| 17449 | +----------------------------------------------------------+ |
| 17450 | |rewrite_headers|Use: dnslookup|Type: boolean|Default: true| |
| 17451 | +----------------------------------------------------------+ |
| 17452 | |
| 17453 | If the domain name in the address that is being processed is not fully |
| 17454 | qualified, it may be expanded to its full form by a DNS lookup. For example, if |
| 17455 | an address is specified as dormouse@teaparty, the domain might be expanded to |
| 17456 | teaparty.wonderland.fict.example. Domain expansion can also occur as a result |
| 17457 | of setting the widen_domains option. If rewrite_headers is true, all |
| 17458 | occurrences of the abbreviated domain name in any Bcc:, Cc:, From:, Reply-to:, |
| 17459 | Sender:, and To: header lines of the message are rewritten with the full domain |
| 17460 | name. |
| 17461 | |
| 17462 | This option should be turned off only when it is known that no message is ever |
| 17463 | going to be sent outside an environment where the abbreviation makes sense. |
| 17464 | |
| 17465 | When an MX record is looked up in the DNS and matches a wildcard record, name |
| 17466 | servers normally return a record containing the name that has been looked up, |
| 17467 | making it impossible to detect whether a wildcard was present or not. However, |
| 17468 | some name servers have recently been seen to return the wildcard entry. If the |
| 17469 | name returned by a DNS lookup begins with an asterisk, it is not used for |
| 17470 | header rewriting. |
| 17471 | |
| 17472 | +--------------------------------------------------------------------+ |
| 17473 | |same_domain_copy_routing|Use: dnslookup|Type: boolean|Default: false| |
| 17474 | +--------------------------------------------------------------------+ |
| 17475 | |
| 17476 | Addresses with the same domain are normally routed by the dnslookup router to |
| 17477 | the same list of hosts. However, this cannot be presumed, because the router |
| 17478 | options and preconditions may refer to the local part of the address. By |
| 17479 | default, therefore, Exim routes each address in a message independently. DNS |
| 17480 | servers run caches, so repeated DNS lookups are not normally expensive, and in |
| 17481 | any case, personal messages rarely have more than a few recipients. |
| 17482 | |
| 17483 | If you are running mailing lists with large numbers of subscribers at the same |
| 17484 | domain, and you are using a dnslookup router which is independent of the local |
| 17485 | part, you can set same_domain_copy_routing to bypass repeated DNS lookups for |
| 17486 | identical domains in one message. In this case, when dnslookup routes an |
| 17487 | address to a remote transport, any other unrouted addresses in the message that |
| 17488 | have the same domain are automatically given the same routing without |
| 17489 | processing them independently, provided the following conditions are met: |
| 17490 | |
| 17491 | * No router that processed the address specified headers_add or |
| 17492 | headers_remove. |
| 17493 | |
| 17494 | * The router did not change the address in any way, for example, by |
| 17495 | "widening" the domain. |
| 17496 | |
| 17497 | +----------------------------------------------------------+ |
| 17498 | |search_parents|Use: dnslookup|Type: boolean|Default: false| |
| 17499 | +----------------------------------------------------------+ |
| 17500 | |
| 17501 | When this option is true, the resolver option RES_DNSRCH is set for DNS |
| 17502 | lookups. This is different from the qualify_single option in that it applies to |
| 17503 | domains containing dots. Typically, but not standardly, it causes the resolver |
| 17504 | to search for the name in the current domain and in parent domains. For |
| 17505 | example, on a machine in the fict.example domain, if looking up |
| 17506 | teaparty.wonderland failed, the resolver would try |
| 17507 | teaparty.wonderland.fict.example. For details of what your resolver actually |
| 17508 | does, consult your man pages for resolver and resolv.conf. |
| 17509 | |
| 17510 | Setting this option true can cause problems in domains that have a wildcard MX |
| 17511 | record, because any domain that does not have its own MX record matches the |
| 17512 | local wildcard. |
| 17513 | |
| 17514 | +-----------------------------------------------------------------+ |
| 17515 | |srv_fail_domains|Use: dnslookup|Type: domain list*|Default: unset| |
| 17516 | +-----------------------------------------------------------------+ |
| 17517 | |
| 17518 | If the DNS lookup for SRV records for one of the domains in this list causes a |
| 17519 | DNS lookup error, Exim behaves as if no SRV records were found. See section |
| 17520 | 17.1 for more discussion. |
| 17521 | |
| 17522 | +-------------------------------------------------------------+ |
| 17523 | |widen_domains|Use: dnslookup|Type: string list|Default: unset| |
| 17524 | +-------------------------------------------------------------+ |
| 17525 | |
| 17526 | If a DNS lookup fails and this option is set, each of its strings in turn is |
| 17527 | added onto the end of the domain, and the lookup is tried again. For example, |
| 17528 | if |
| 17529 | |
| 17530 | widen_domains = fict.example:ref.example |
| 17531 | |
| 17532 | is set and a lookup of klingon.dictionary fails, |
| 17533 | klingon.dictionary.fict.example is looked up, and if this fails, |
| 17534 | klingon.dictionary.ref.example is tried. Note that the qualify_single and |
| 17535 | search_parents options can cause some widening to be undertaken inside the DNS |
| 17536 | resolver. widen_domains is not applied to sender addresses when verifying, |
| 17537 | unless rewrite_headers is false (not the default). |
| 17538 | |
| 17539 | |
| 17540 | 17.4 Effect of qualify_single and search_parents |
| 17541 | ------------------------------------------------ |
| 17542 | |
| 17543 | When a domain from an envelope recipient is changed by the resolver as a result |
| 17544 | of the qualify_single or search_parents options, Exim rewrites the |
| 17545 | corresponding address in the message's header lines unless rewrite_headers is |
| 17546 | set false. Exim then re-routes the address, using the full domain. |
| 17547 | |
| 17548 | These two options affect only the DNS lookup that takes place inside the router |
| 17549 | for the domain of the address that is being routed. They do not affect lookups |
| 17550 | such as that implied by |
| 17551 | |
| 17552 | domains = @mx_any |
| 17553 | |
| 17554 | that may happen while processing a router precondition before the router is |
| 17555 | entered. No widening ever takes place for these lookups. |
| 17556 | |
| 17557 | |
| 17558 | |
| 17559 | =============================================================================== |
| 17560 | 18. THE IPLITERAL ROUTER |
| 17561 | |
| 17562 | This router has no private options. Unless it is being used purely for |
| 17563 | verification (see verify_only) a transport is required to be defined by the |
| 17564 | generic transport option. The router accepts the address if its domain part |
| 17565 | takes the form of an RFC 2822 domain literal. For example, the ipliteral router |
| 17566 | handles the address |
| 17567 | |
| 17568 | root@[192.168.1.1] |
| 17569 | |
| 17570 | by setting up delivery to the host with that IP address. IPv4 domain literals |
| 17571 | consist of an IPv4 address enclosed in square brackets. IPv6 domain literals |
| 17572 | are similar, but the address is preceded by "ipv6:". For example: |
| 17573 | |
| 17574 | postmaster@[ipv6:fe80::a00:20ff:fe86:a061.5678] |
| 17575 | |
| 17576 | Exim allows "ipv4:" before IPv4 addresses, for consistency, and on the grounds |
| 17577 | that sooner or later somebody will try it. |
| 17578 | |
| 17579 | If the IP address matches something in ignore_target_hosts, the router |
| 17580 | declines. If an IP literal turns out to refer to the local host, the generic |
| 17581 | self option determines what happens. |
| 17582 | |
| 17583 | The RFCs require support for domain literals; however, their use is |
| 17584 | controversial in today's Internet. If you want to use this router, you must |
| 17585 | also set the main configuration option allow_domain_literals. Otherwise, Exim |
| 17586 | will not recognize the domain literal syntax in addresses. |
| 17587 | |
| 17588 | |
| 17589 | |
| 17590 | =============================================================================== |
| 17591 | 19. THE IPLOOKUP ROUTER |
| 17592 | |
| 17593 | The iplookup router was written to fulfil a specific requirement in Cambridge |
| 17594 | University (which in fact no longer exists). For this reason, it is not |
| 17595 | included in the binary of Exim by default. If you want to include it, you must |
| 17596 | set |
| 17597 | |
| 17598 | ROUTER_IPLOOKUP=yes |
| 17599 | |
| 17600 | in your Local/Makefile configuration file. |
| 17601 | |
| 17602 | The iplookup router routes an address by sending it over a TCP or UDP |
| 17603 | connection to one or more specific hosts. The host can then return the same or |
| 17604 | a different address - in effect rewriting the recipient address in the |
| 17605 | message's envelope. The new address is then passed on to subsequent routers. If |
| 17606 | this process fails, the address can be passed on to other routers, or delivery |
| 17607 | can be deferred. Since iplookup is just a rewriting router, a transport must |
| 17608 | not be specified for it. |
| 17609 | |
| 17610 | +-----------------------------------------------+ |
| 17611 | |hosts|Use: iplookup|Type: string|Default: unset| |
| 17612 | +-----------------------------------------------+ |
| 17613 | |
| 17614 | This option must be supplied. Its value is a colon-separated list of host |
| 17615 | names. The hosts are looked up using gethostbyname() (or getipnodebyname() when |
| 17616 | available) and are tried in order until one responds to the query. If none |
| 17617 | respond, what happens is controlled by optional. |
| 17618 | |
| 17619 | +---------------------------------------------------+ |
| 17620 | |optional|Use: iplookup|Type: boolean|Default: false| |
| 17621 | +---------------------------------------------------+ |
| 17622 | |
| 17623 | If optional is true, if no response is obtained from any host, the address is |
| 17624 | passed to the next router, overriding no_more. If optional is false, delivery |
| 17625 | to the address is deferred. |
| 17626 | |
| 17627 | +-------------------------------------------+ |
| 17628 | |port|Use: iplookup|Type: integer|Default: 0| |
| 17629 | +-------------------------------------------+ |
| 17630 | |
| 17631 | This option must be supplied. It specifies the port number for the TCP or UDP |
| 17632 | call. |
| 17633 | |
| 17634 | +------------------------------------------------+ |
| 17635 | |protocol|Use: iplookup|Type: string|Default: udp| |
| 17636 | +------------------------------------------------+ |
| 17637 | |
| 17638 | This option can be set to "udp" or "tcp" to specify which of the two protocols |
| 17639 | is to be used. |
| 17640 | |
| 17641 | +----------------------------------------------------+ |
| 17642 | |query|Use: iplookup|Type: string*|Default: see below| |
| 17643 | +----------------------------------------------------+ |
| 17644 | |
| 17645 | This defines the content of the query that is sent to the remote hosts. The |
| 17646 | default value is: |
| 17647 | |
| 17648 | $local_part@$domain $local_part@$domain |
| 17649 | |
| 17650 | The repetition serves as a way of checking that a response is to the correct |
| 17651 | query in the default case (see response_pattern below). |
| 17652 | |
| 17653 | +--------------------------------------------------+ |
| 17654 | |reroute|Use: iplookup|Type: string*|Default: unset| |
| 17655 | +--------------------------------------------------+ |
| 17656 | |
| 17657 | If this option is not set, the rerouted address is precisely the byte string |
| 17658 | returned by the remote host, up to the first white space, if any. If set, the |
| 17659 | string is expanded to form the rerouted address. It can include parts matched |
| 17660 | in the response by response_pattern by means of numeric variables such as $1, |
| 17661 | $2, etc. The variable $0 refers to the entire input string, whether or not a |
| 17662 | pattern is in use. In all cases, the rerouted address must end up in the form |
| 17663 | local_part@domain. |
| 17664 | |
| 17665 | +----------------------------------------------------------+ |
| 17666 | |response_pattern|Use: iplookup|Type: string|Default: unset| |
| 17667 | +----------------------------------------------------------+ |
| 17668 | |
| 17669 | This option can be set to a regular expression that is applied to the string |
| 17670 | returned from the remote host. If the pattern does not match the response, the |
| 17671 | router declines. If response_pattern is not set, no checking of the response is |
| 17672 | done, unless the query was defaulted, in which case there is a check that the |
| 17673 | text returned after the first white space is the original address. This checks |
| 17674 | that the answer that has been received is in response to the correct question. |
| 17675 | For example, if the response is just a new domain, the following could be used: |
| 17676 | |
| 17677 | response_pattern = ^([^@]+)$ |
| 17678 | reroute = $local_part@$1 |
| 17679 | |
| 17680 | +--------------------------------------------+ |
| 17681 | |timeout|Use: iplookup|Type: time|Default: 5s| |
| 17682 | +--------------------------------------------+ |
| 17683 | |
| 17684 | This specifies the amount of time to wait for a response from the remote |
| 17685 | machine. The same timeout is used for the connect() function for a TCP call. It |
| 17686 | does not apply to UDP. |
| 17687 | |
| 17688 | |
| 17689 | |
| 17690 | =============================================================================== |
| 17691 | 20. THE MANUALROUTE ROUTER |
| 17692 | |
| 17693 | The manualroute router is so-called because it provides a way of manually |
| 17694 | routing an address according to its domain. It is mainly used when you want to |
| 17695 | route addresses to remote hosts according to your own rules, bypassing the |
| 17696 | normal DNS routing that looks up MX records. However, manualroute can also |
| 17697 | route to local transports, a facility that may be useful if you want to save |
| 17698 | messages for dial-in hosts in local files. |
| 17699 | |
| 17700 | The manualroute router compares a list of domain patterns with the domain it is |
| 17701 | trying to route. If there is no match, the router declines. Each pattern has |
| 17702 | associated with it a list of hosts and some other optional data, which may |
| 17703 | include a transport. The combination of a pattern and its data is called a |
| 17704 | "routing rule". For patterns that do not have an associated transport, the |
| 17705 | generic transport option must specify a transport, unless the router is being |
| 17706 | used purely for verification (see verify_only). |
| 17707 | |
| 17708 | In the case of verification, matching the domain pattern is sufficient for the |
| 17709 | router to accept the address. When actually routing an address for delivery, an |
| 17710 | address that matches a domain pattern is queued for the associated transport. |
| 17711 | If the transport is not a local one, a host list must be associated with the |
| 17712 | pattern; IP addresses are looked up for the hosts, and these are passed to the |
| 17713 | transport along with the mail address. For local transports, a host list is |
| 17714 | optional. If it is present, it is passed in $host as a single text string. |
| 17715 | |
| 17716 | The list of routing rules can be provided as an inline string in route_list, or |
| 17717 | the data can be obtained by looking up the domain in a file or database by |
| 17718 | setting route_data. Only one of these settings may appear in any one instance |
| 17719 | of manualroute. The format of routing rules is described below, following the |
| 17720 | list of private options. |
| 17721 | |
| 17722 | |
| 17723 | 20.1 Private options for manualroute |
| 17724 | ------------------------------------ |
| 17725 | |
| 17726 | The private options for the manualroute router are as follows: |
| 17727 | |
| 17728 | +-------------------------------------------------------------+ |
| 17729 | |host_all_ignored|Use: manualroute|Type: string|Default: defer| |
| 17730 | +-------------------------------------------------------------+ |
| 17731 | |
| 17732 | See host_find_failed. |
| 17733 | |
| 17734 | +--------------------------------------------------------------+ |
| 17735 | |host_find_failed|Use: manualroute|Type: string|Default: freeze| |
| 17736 | +--------------------------------------------------------------+ |
| 17737 | |
| 17738 | This option controls what happens when manualroute tries to find an IP address |
| 17739 | for a host, and the host does not exist. The option can be set to one of the |
| 17740 | following values: |
| 17741 | |
| 17742 | decline |
| 17743 | defer |
| 17744 | fail |
| 17745 | freeze |
| 17746 | ignore |
| 17747 | pass |
| 17748 | |
| 17749 | The default ("freeze") assumes that this state is a serious configuration |
| 17750 | error. The difference between "pass" and "decline" is that the former forces |
| 17751 | the address to be passed to the next router (or the router defined by |
| 17752 | pass_router), overriding no_more, whereas the latter passes the address to the |
| 17753 | next router only if more is true. |
| 17754 | |
| 17755 | The value "ignore" causes Exim to completely ignore a host whose IP address |
| 17756 | cannot be found. If all the hosts in the list are ignored, the behaviour is |
| 17757 | controlled by the host_all_ignored option. This takes the same values as |
| 17758 | host_find_failed, except that it cannot be set to "ignore". |
| 17759 | |
| 17760 | The host_find_failed option applies only to a definite "does not exist" state; |
| 17761 | if a host lookup gets a temporary error, delivery is deferred unless the |
| 17762 | generic pass_on_timeout option is set. |
| 17763 | |
| 17764 | +-------------------------------------------------------------+ |
| 17765 | |hosts_randomize|Use: manualroute|Type: boolean|Default: false| |
| 17766 | +-------------------------------------------------------------+ |
| 17767 | |
| 17768 | If this option is set, the order of the items in a host list in a routing rule |
| 17769 | is randomized each time the list is used, unless an option in the routing rule |
| 17770 | overrides (see below). Randomizing the order of a host list can be used to do |
| 17771 | crude load sharing. However, if more than one mail address is routed by the |
| 17772 | same router to the same host list, the host lists are considered to be the same |
| 17773 | (even though they may be randomized into different orders) for the purpose of |
| 17774 | deciding whether to batch the deliveries into a single SMTP transaction. |
| 17775 | |
| 17776 | When hosts_randomize is true, a host list may be split into groups whose order |
| 17777 | is separately randomized. This makes it possible to set up MX-like behaviour. |
| 17778 | The boundaries between groups are indicated by an item that is just "+" in the |
| 17779 | host list. For example: |
| 17780 | |
| 17781 | route_list = * host1:host2:host3:+:host4:host5 |
| 17782 | |
| 17783 | The order of the first three hosts and the order of the last two hosts is |
| 17784 | randomized for each use, but the first three always end up before the last two. |
| 17785 | If hosts_randomize is not set, a "+" item in the list is ignored. If a |
| 17786 | randomized host list is passed to an smtp transport that also has |
| 17787 | hosts_randomize set, the list is not re-randomized. |
| 17788 | |
| 17789 | +--------------------------------------------------------+ |
| 17790 | |route_data|Use: manualroute|Type: string*|Default: unset| |
| 17791 | +--------------------------------------------------------+ |
| 17792 | |
| 17793 | If this option is set, it must expand to yield the data part of a routing rule. |
| 17794 | Typically, the expansion string includes a lookup based on the domain. For |
| 17795 | example: |
| 17796 | |
| 17797 | route_data = ${lookup{$domain}dbm{/etc/routes}} |
| 17798 | |
| 17799 | If the expansion is forced to fail, or the result is an empty string, the |
| 17800 | router declines. Other kinds of expansion failure cause delivery to be |
| 17801 | deferred. |
| 17802 | |
| 17803 | +------------------------------------------------------------+ |
| 17804 | |route_list|Use: manualroute|Type: string list|Default: unset| |
| 17805 | +------------------------------------------------------------+ |
| 17806 | |
| 17807 | This string is a list of routing rules, in the form defined below. Note that, |
| 17808 | unlike most string lists, the items are separated by semicolons. This is so |
| 17809 | that they may contain colon-separated host lists. |
| 17810 | |
| 17811 | +----------------------------------------------------------------------+ |
| 17812 | |same_domain_copy_routing|Use: manualroute|Type: boolean|Default: false| |
| 17813 | +----------------------------------------------------------------------+ |
| 17814 | |
| 17815 | Addresses with the same domain are normally routed by the manualroute router to |
| 17816 | the same list of hosts. However, this cannot be presumed, because the router |
| 17817 | options and preconditions may refer to the local part of the address. By |
| 17818 | default, therefore, Exim routes each address in a message independently. DNS |
| 17819 | servers run caches, so repeated DNS lookups are not normally expensive, and in |
| 17820 | any case, personal messages rarely have more than a few recipients. |
| 17821 | |
| 17822 | If you are running mailing lists with large numbers of subscribers at the same |
| 17823 | domain, and you are using a manualroute router which is independent of the |
| 17824 | local part, you can set same_domain_copy_routing to bypass repeated DNS lookups |
| 17825 | for identical domains in one message. In this case, when manualroute routes an |
| 17826 | address to a remote transport, any other unrouted addresses in the message that |
| 17827 | have the same domain are automatically given the same routing without |
| 17828 | processing them independently. However, this is only done if headers_add and |
| 17829 | headers_remove are unset. |
| 17830 | |
| 17831 | |
| 17832 | 20.2 Routing rules in route_list |
| 17833 | -------------------------------- |
| 17834 | |
| 17835 | The value of route_list is a string consisting of a sequence of routing rules, |
| 17836 | separated by semicolons. If a semicolon is needed in a rule, it can be entered |
| 17837 | as two semicolons. Alternatively, the list separator can be changed as |
| 17838 | described (for colon-separated lists) in section 6.20. Empty rules are ignored. |
| 17839 | The format of each rule is |
| 17840 | |
| 17841 | <domain pattern> <list of hosts> <options> |
| 17842 | |
| 17843 | The following example contains two rules, each with a simple domain pattern and |
| 17844 | no options: |
| 17845 | |
| 17846 | route_list = \ |
| 17847 | dict.ref.example mail-1.ref.example:mail-2.ref.example ; \ |
| 17848 | thes.ref.example mail-3.ref.example:mail-4.ref.example |
| 17849 | |
| 17850 | The three parts of a rule are separated by white space. The pattern and the |
| 17851 | list of hosts can be enclosed in quotes if necessary, and if they are, the |
| 17852 | usual quoting rules apply. Each rule in a route_list must start with a single |
| 17853 | domain pattern, which is the only mandatory item in the rule. The pattern is in |
| 17854 | the same format as one item in a domain list (see section 10.8), except that it |
| 17855 | may not be the name of an interpolated file. That is, it may be wildcarded, or |
| 17856 | a regular expression, or a file or database lookup (with semicolons doubled, |
| 17857 | because of the use of semicolon as a separator in a route_list). |
| 17858 | |
| 17859 | The rules in route_list are searched in order until one of the patterns matches |
| 17860 | the domain that is being routed. The list of hosts and then options are then |
| 17861 | used as described below. If there is no match, the router declines. When |
| 17862 | route_list is set, route_data must not be set. |
| 17863 | |
| 17864 | |
| 17865 | 20.3 Routing rules in route_data |
| 17866 | -------------------------------- |
| 17867 | |
| 17868 | The use of route_list is convenient when there are only a small number of |
| 17869 | routing rules. For larger numbers, it is easier to use a file or database to |
| 17870 | hold the routing information, and use the route_data option instead. The value |
| 17871 | of route_data is a list of hosts, followed by (optional) options. Most |
| 17872 | commonly, route_data is set as a string that contains an expansion lookup. For |
| 17873 | example, suppose we place two routing rules in a file like this: |
| 17874 | |
| 17875 | dict.ref.example: mail-1.ref.example:mail-2.ref.example |
| 17876 | thes.ref.example: mail-3.ref.example:mail-4.ref.example |
| 17877 | |
| 17878 | This data can be accessed by setting |
| 17879 | |
| 17880 | route_data = ${lookup{$domain}lsearch{/the/file/name}} |
| 17881 | |
| 17882 | Failure of the lookup results in an empty string, causing the router to |
| 17883 | decline. However, you do not have to use a lookup in route_data. The only |
| 17884 | requirement is that the result of expanding the string is a list of hosts, |
| 17885 | possibly followed by options, separated by white space. The list of hosts must |
| 17886 | be enclosed in quotes if it contains white space. |
| 17887 | |
| 17888 | |
| 17889 | 20.4 Format of the list of hosts |
| 17890 | -------------------------------- |
| 17891 | |
| 17892 | A list of hosts, whether obtained via route_data or route_list, is always |
| 17893 | separately expanded before use. If the expansion fails, the router declines. |
| 17894 | The result of the expansion must be a colon-separated list of names and/or IP |
| 17895 | addresses, optionally also including ports. The format of each item in the list |
| 17896 | is described in the next section. The list separator can be changed as |
| 17897 | described in section 6.20. |
| 17898 | |
| 17899 | If the list of hosts was obtained from a route_list item, the following |
| 17900 | variables are set during its expansion: |
| 17901 | |
| 17902 | * If the domain was matched against a regular expression, the numeric |
| 17903 | variables $1, $2, etc. may be set. For example: |
| 17904 | |
| 17905 | route_list = ^domain(\d+) host-$1.text.example |
| 17906 | |
| 17907 | * $0 is always set to the entire domain. |
| 17908 | |
| 17909 | * $1 is also set when partial matching is done in a file lookup. |
| 17910 | |
| 17911 | * If the pattern that matched the domain was a lookup item, the data that was |
| 17912 | looked up is available in the expansion variable $value. For example: |
| 17913 | |
| 17914 | route_list = lsearch;;/some/file.routes $value |
| 17915 | |
| 17916 | Note the doubling of the semicolon in the pattern that is necessary because |
| 17917 | semicolon is the default route list separator. |
| 17918 | |
| 17919 | |
| 17920 | 20.5 Format of one host item |
| 17921 | ---------------------------- |
| 17922 | |
| 17923 | Each item in the list of hosts is either a host name or an IP address, |
| 17924 | optionally with an attached port number. When no port is given, an IP address |
| 17925 | is not enclosed in brackets. When a port is specified, it overrides the port |
| 17926 | specification on the transport. The port is separated from the name or address |
| 17927 | by a colon. This leads to some complications: |
| 17928 | |
| 17929 | * Because colon is the default separator for the list of hosts, either the |
| 17930 | colon that specifies a port must be doubled, or the list separator must be |
| 17931 | changed. The following two examples have the same effect: |
| 17932 | |
| 17933 | route_list = * "host1.tld::1225 : host2.tld::1226" |
| 17934 | route_list = * "<+ host1.tld:1225 + host2.tld:1226" |
| 17935 | |
| 17936 | * When IPv6 addresses are involved, it gets worse, because they contain |
| 17937 | colons of their own. To make this case easier, it is permitted to enclose |
| 17938 | an IP address (either v4 or v6) in square brackets if a port number |
| 17939 | follows. For example: |
| 17940 | |
| 17941 | route_list = * "</ [10.1.1.1]:1225 / [::1]:1226" |
| 17942 | |
| 17943 | |
| 17944 | 20.6 How the list of hosts is used |
| 17945 | ---------------------------------- |
| 17946 | |
| 17947 | When an address is routed to an smtp transport by manualroute, each of the |
| 17948 | hosts is tried, in the order specified, when carrying out the SMTP delivery. |
| 17949 | However, the order can be changed by setting the hosts_randomize option, either |
| 17950 | on the router (see section 20.1 above), or on the transport. |
| 17951 | |
| 17952 | Hosts may be listed by name or by IP address. An unadorned name in the list of |
| 17953 | hosts is interpreted as a host name. A name that is followed by "/MX" is |
| 17954 | interpreted as an indirection to a sublist of hosts obtained by looking up MX |
| 17955 | records in the DNS. For example: |
| 17956 | |
| 17957 | route_list = * x.y.z:p.q.r/MX:e.f.g |
| 17958 | |
| 17959 | If this feature is used with a port specifier, the port must come last. For |
| 17960 | example: |
| 17961 | |
| 17962 | route_list = * dom1.tld/mx::1225 |
| 17963 | |
| 17964 | If the hosts_randomize option is set, the order of the items in the list is |
| 17965 | randomized before any lookups are done. Exim then scans the list; for any name |
| 17966 | that is not followed by "/MX" it looks up an IP address. If this turns out to |
| 17967 | be an interface on the local host and the item is not the first in the list, |
| 17968 | Exim discards it and any subsequent items. If it is the first item, what |
| 17969 | happens is controlled by the self option of the router. |
| 17970 | |
| 17971 | A name on the list that is followed by "/MX" is replaced with the list of hosts |
| 17972 | obtained by looking up MX records for the name. This is always a DNS lookup; |
| 17973 | the bydns and byname options (see section 20.7 below) are not relevant here. |
| 17974 | The order of these hosts is determined by the preference values in the MX |
| 17975 | records, according to the usual rules. Because randomizing happens before the |
| 17976 | MX lookup, it does not affect the order that is defined by MX preferences. |
| 17977 | |
| 17978 | If the local host is present in the sublist obtained from MX records, but is |
| 17979 | not the most preferred host in that list, it and any equally or less preferred |
| 17980 | hosts are removed before the sublist is inserted into the main list. |
| 17981 | |
| 17982 | If the local host is the most preferred host in the MX list, what happens |
| 17983 | depends on where in the original list of hosts the "/MX" item appears. If it is |
| 17984 | not the first item (that is, there are previous hosts in the main list), Exim |
| 17985 | discards this name and any subsequent items in the main list. |
| 17986 | |
| 17987 | If the MX item is first in the list of hosts, and the local host is the most |
| 17988 | preferred host, what happens is controlled by the self option of the router. |
| 17989 | |
| 17990 | DNS failures when lookup up the MX records are treated in the same way as DNS |
| 17991 | failures when looking up IP addresses: pass_on_timeout and host_find_failed are |
| 17992 | used when relevant. |
| 17993 | |
| 17994 | The generic ignore_target_hosts option applies to all hosts in the list, |
| 17995 | whether obtained from an MX lookup or not. |
| 17996 | |
| 17997 | |
| 17998 | 20.7 How the options are used |
| 17999 | ----------------------------- |
| 18000 | |
| 18001 | The options are a sequence of words; in practice no more than three are ever |
| 18002 | present. One of the words can be the name of a transport; this overrides the |
| 18003 | transport option on the router for this particular routing rule only. The other |
| 18004 | words (if present) control randomization of the list of hosts on a per-rule |
| 18005 | basis, and how the IP addresses of the hosts are to be found when routing to a |
| 18006 | remote transport. These options are as follows: |
| 18007 | |
| 18008 | * randomize: randomize the order of the hosts in this list, overriding the |
| 18009 | setting of hosts_randomize for this routing rule only. |
| 18010 | |
| 18011 | * no_randomize: do not randomize the order of the hosts in this list, |
| 18012 | overriding the setting of hosts_randomize for this routing rule only. |
| 18013 | |
| 18014 | * byname: use getipnodebyname() (gethostbyname() on older systems) to find IP |
| 18015 | addresses. This function may ultimately cause a DNS lookup, but it may also |
| 18016 | look in /etc/hosts or other sources of information. |
| 18017 | |
| 18018 | * bydns: look up address records for the hosts directly in the DNS; fail if |
| 18019 | no address records are found. If there is a temporary DNS error (such as a |
| 18020 | timeout), delivery is deferred. |
| 18021 | |
| 18022 | For example: |
| 18023 | |
| 18024 | route_list = domain1 host1:host2:host3 randomize bydns;\ |
| 18025 | domain2 host4:host5 |
| 18026 | |
| 18027 | If neither byname nor bydns is given, Exim behaves as follows: First, a DNS |
| 18028 | lookup is done. If this yields anything other than HOST_NOT_FOUND, that result |
| 18029 | is used. Otherwise, Exim goes on to try a call to getipnodebyname() or |
| 18030 | gethostbyname(), and the result of the lookup is the result of that call. |
| 18031 | |
| 18032 | Warning: It has been discovered that on some systems, if a DNS lookup called |
| 18033 | via getipnodebyname() times out, HOST_NOT_FOUND is returned instead of |
| 18034 | TRY_AGAIN. That is why the default action is to try a DNS lookup first. Only if |
| 18035 | that gives a definite "no such host" is the local function called. |
| 18036 | |
| 18037 | If no IP address for a host can be found, what happens is controlled by the |
| 18038 | host_find_failed option. |
| 18039 | |
| 18040 | When an address is routed to a local transport, IP addresses are not looked up. |
| 18041 | The host list is passed to the transport in the $host variable. |
| 18042 | |
| 18043 | |
| 18044 | 20.8 Manualroute examples |
| 18045 | ------------------------- |
| 18046 | |
| 18047 | In some of the examples that follow, the presence of the remote_smtp transport, |
| 18048 | as defined in the default configuration file, is assumed: |
| 18049 | |
| 18050 | * The manualroute router can be used to forward all external mail to a smart |
| 18051 | host. If you have set up, in the main part of the configuration, a named |
| 18052 | domain list that contains your local domains, for example: |
| 18053 | |
| 18054 | domainlist local_domains = my.domain.example |
| 18055 | |
| 18056 | You can arrange for all other domains to be routed to a smart host by |
| 18057 | making your first router something like this: |
| 18058 | |
| 18059 | smart_route: |
| 18060 | driver = manualroute |
| 18061 | domains = !+local_domains |
| 18062 | transport = remote_smtp |
| 18063 | route_list = * smarthost.ref.example |
| 18064 | |
| 18065 | This causes all non-local addresses to be sent to the single host |
| 18066 | smarthost.ref.example. If a colon-separated list of smart hosts is given, |
| 18067 | they are tried in order (but you can use hosts_randomize to vary the order |
| 18068 | each time). Another way of configuring the same thing is this: |
| 18069 | |
| 18070 | smart_route: |
| 18071 | driver = manualroute |
| 18072 | transport = remote_smtp |
| 18073 | route_list = !+local_domains smarthost.ref.example |
| 18074 | |
| 18075 | There is no difference in behaviour between these two routers as they |
| 18076 | stand. However, they behave differently if no_more is added to them. In the |
| 18077 | first example, the router is skipped if the domain does not match the |
| 18078 | domains precondition; the following router is always tried. If the router |
| 18079 | runs, it always matches the domain and so can never decline. Therefore, |
| 18080 | no_more would have no effect. In the second case, the router is never |
| 18081 | skipped; it always runs. However, if it doesn't match the domain, it |
| 18082 | declines. In this case no_more would prevent subsequent routers from |
| 18083 | running. |
| 18084 | |
| 18085 | * A mail hub is a host which receives mail for a number of domains via MX |
| 18086 | records in the DNS and delivers it via its own private routing mechanism. |
| 18087 | Often the final destinations are behind a firewall, with the mail hub being |
| 18088 | the one machine that can connect to machines both inside and outside the |
| 18089 | firewall. The manualroute router is usually used on a mail hub to route |
| 18090 | incoming messages to the correct hosts. For a small number of domains, the |
| 18091 | routing can be inline, using the route_list option, but for a larger number |
| 18092 | a file or database lookup is easier to manage. |
| 18093 | |
| 18094 | If the domain names are in fact the names of the machines to which the mail |
| 18095 | is to be sent by the mail hub, the configuration can be quite simple. For |
| 18096 | example: |
| 18097 | |
| 18098 | hub_route: |
| 18099 | driver = manualroute |
| 18100 | transport = remote_smtp |
| 18101 | route_list = *.rhodes.tvs.example $domain |
| 18102 | |
| 18103 | This configuration routes domains that match "*.rhodes.tvs.example" to |
| 18104 | hosts whose names are the same as the mail domains. A similar approach can |
| 18105 | be taken if the host name can be obtained from the domain name by a string |
| 18106 | manipulation that the expansion facilities can handle. Otherwise, a lookup |
| 18107 | based on the domain can be used to find the host: |
| 18108 | |
| 18109 | through_firewall: |
| 18110 | driver = manualroute |
| 18111 | transport = remote_smtp |
| 18112 | route_data = ${lookup {$domain} cdb {/internal/host/routes}} |
| 18113 | |
| 18114 | The result of the lookup must be the name or IP address of the host (or |
| 18115 | hosts) to which the address is to be routed. If the lookup fails, the route |
| 18116 | data is empty, causing the router to decline. The address then passes to |
| 18117 | the next router. |
| 18118 | |
| 18119 | * You can use manualroute to deliver messages to pipes or files in batched |
| 18120 | SMTP format for onward transportation by some other means. This is one way |
| 18121 | of storing mail for a dial-up host when it is not connected. The route list |
| 18122 | entry can be as simple as a single domain name in a configuration like |
| 18123 | this: |
| 18124 | |
| 18125 | save_in_file: |
| 18126 | driver = manualroute |
| 18127 | transport = batchsmtp_appendfile |
| 18128 | route_list = saved.domain.example |
| 18129 | |
| 18130 | though often a pattern is used to pick up more than one domain. If there |
| 18131 | are several domains or groups of domains with different transport |
| 18132 | requirements, different transports can be listed in the routing |
| 18133 | information: |
| 18134 | |
| 18135 | save_in_file: |
| 18136 | driver = manualroute |
| 18137 | route_list = \ |
| 18138 | *.saved.domain1.example $domain batch_appendfile; \ |
| 18139 | *.saved.domain2.example \ |
| 18140 | ${lookup{$domain}dbm{/domain2/hosts}{$value}fail} \ |
| 18141 | batch_pipe |
| 18142 | |
| 18143 | The first of these just passes the domain in the $host variable, which |
| 18144 | doesn't achieve much (since it is also in $domain), but the second does a |
| 18145 | file lookup to find a value to pass, causing the router to decline to |
| 18146 | handle the address if the lookup fails. |
| 18147 | |
| 18148 | * Routing mail directly to UUCP software is a specific case of the use of |
| 18149 | manualroute in a gateway to another mail environment. This is an example of |
| 18150 | one way it can be done: |
| 18151 | |
| 18152 | # Transport |
| 18153 | uucp: |
| 18154 | driver = pipe |
| 18155 | user = nobody |
| 18156 | command = /usr/local/bin/uux -r - \ |
| 18157 | ${substr_-5:$host}!rmail ${local_part} |
| 18158 | return_fail_output = true |
| 18159 | |
| 18160 | # Router |
| 18161 | uucphost: |
| 18162 | transport = uucp |
| 18163 | driver = manualroute |
| 18164 | route_data = \ |
| 18165 | ${lookup{$domain}lsearch{/usr/local/exim/uucphosts}} |
| 18166 | |
| 18167 | The file /usr/local/exim/uucphosts contains entries like |
| 18168 | |
| 18169 | darksite.ethereal.example: darksite.UUCP |
| 18170 | |
| 18171 | It can be set up more simply without adding and removing ".UUCP" but this |
| 18172 | way makes clear the distinction between the domain name |
| 18173 | darksite.ethereal.example and the UUCP host name darksite. |
| 18174 | |
| 18175 | |
| 18176 | |
| 18177 | =============================================================================== |
| 18178 | 21. THE QUERYPROGRAM ROUTER |
| 18179 | |
| 18180 | The queryprogram router routes an address by running an external command and |
| 18181 | acting on its output. This is an expensive way to route, and is intended mainly |
| 18182 | for use in lightly-loaded systems, or for performing experiments. However, if |
| 18183 | it is possible to use the precondition options (domains, local_parts, etc) to |
| 18184 | skip this router for most addresses, it could sensibly be used in special |
| 18185 | cases, even on a busy host. There are the following private options: |
| 18186 | |
| 18187 | +------------------------------------------------------+ |
| 18188 | |command|Use: queryprogram|Type: string*|Default: unset| |
| 18189 | +------------------------------------------------------+ |
| 18190 | |
| 18191 | This option must be set. It specifies the command that is to be run. The |
| 18192 | command is split up into a command name and arguments, and then each is |
| 18193 | expanded separately (exactly as for a pipe transport, described in chapter 29). |
| 18194 | |
| 18195 | +-----------------------------------------------------------+ |
| 18196 | |command_group|Use: queryprogram|Type: string|Default: unset| |
| 18197 | +-----------------------------------------------------------+ |
| 18198 | |
| 18199 | This option specifies a gid to be set when running the command while routing an |
| 18200 | address for deliver. It must be set if command_user specifies a numerical uid. |
| 18201 | If it begins with a digit, it is interpreted as the numerical value of the gid. |
| 18202 | Otherwise it is looked up using getgrnam(). |
| 18203 | |
| 18204 | +----------------------------------------------------------+ |
| 18205 | |command_user|Use: queryprogram|Type: string|Default: unset| |
| 18206 | +----------------------------------------------------------+ |
| 18207 | |
| 18208 | This option must be set. It specifies the uid which is set when running the |
| 18209 | command while routing an address for delivery. If the value begins with a |
| 18210 | digit, it is interpreted as the numerical value of the uid. Otherwise, it is |
| 18211 | looked up using getpwnam() to obtain a value for the uid and, if command_group |
| 18212 | is not set, a value for the gid also. |
| 18213 | |
| 18214 | Warning: Changing uid and gid is possible only when Exim is running as root, |
| 18215 | which it does during a normal delivery in a conventional configuration. |
| 18216 | However, when an address is being verified during message reception, Exim is |
| 18217 | usually running as the Exim user, not as root. If the queryprogram router is |
| 18218 | called from a non-root process, Exim cannot change uid or gid before running |
| 18219 | the command. In this circumstance the command runs under the current uid and |
| 18220 | gid. |
| 18221 | |
| 18222 | +-----------------------------------------------------------+ |
| 18223 | |current_directory|Use: queryprogram|Type: string|Default: /| |
| 18224 | +-----------------------------------------------------------+ |
| 18225 | |
| 18226 | This option specifies an absolute path which is made the current directory |
| 18227 | before running the command. |
| 18228 | |
| 18229 | +------------------------------------------------+ |
| 18230 | |timeout|Use: queryprogram|Type: time|Default: 1h| |
| 18231 | +------------------------------------------------+ |
| 18232 | |
| 18233 | If the command does not complete within the timeout period, its process group |
| 18234 | is killed and the message is frozen. A value of zero time specifies no timeout. |
| 18235 | |
| 18236 | The standard output of the command is connected to a pipe, which is read when |
| 18237 | the command terminates. It should consist of a single line of output, |
| 18238 | containing up to five fields, separated by white space. The maximum length of |
| 18239 | the line is 1023 characters. Longer lines are silently truncated. The first |
| 18240 | field is one of the following words (case-insensitive): |
| 18241 | |
| 18242 | * Accept: routing succeeded; the remaining fields specify what to do (see |
| 18243 | below). |
| 18244 | |
| 18245 | * Decline: the router declines; pass the address to the next router, unless |
| 18246 | no_more is set. |
| 18247 | |
| 18248 | * Fail: routing failed; do not pass the address to any more routers. Any |
| 18249 | subsequent text on the line is an error message. If the router is run as |
| 18250 | part of address verification during an incoming SMTP message, the message |
| 18251 | is included in the SMTP response. |
| 18252 | |
| 18253 | * Defer: routing could not be completed at this time; try again later. Any |
| 18254 | subsequent text on the line is an error message which is logged. It is not |
| 18255 | included in any SMTP response. |
| 18256 | |
| 18257 | * Freeze: the same as defer, except that the message is frozen. |
| 18258 | |
| 18259 | * Pass: pass the address to the next router (or the router specified by |
| 18260 | pass_router), overriding no_more. |
| 18261 | |
| 18262 | * Redirect: the message is redirected. The remainder of the line is a list of |
| 18263 | new addresses, which are routed independently, starting with the first |
| 18264 | router, or the router specified by redirect_router, if set. |
| 18265 | |
| 18266 | When the first word is accept, the remainder of the line consists of a number |
| 18267 | of keyed data values, as follows (split into two lines here, to fit on the |
| 18268 | page): |
| 18269 | |
| 18270 | ACCEPT TRANSPORT=<transport> HOSTS=<list of hosts> |
| 18271 | LOOKUP=byname|bydns DATA=<text> |
| 18272 | |
| 18273 | The data items can be given in any order, and all are optional. If no transport |
| 18274 | is included, the transport specified by the generic transport option is used. |
| 18275 | The list of hosts and the lookup type are needed only if the transport is an |
| 18276 | smtp transport that does not itself supply a list of hosts. |
| 18277 | |
| 18278 | The format of the list of hosts is the same as for the manualroute router. As |
| 18279 | well as host names and IP addresses with optional port numbers, as described in |
| 18280 | section 20.5, it may contain names followed by "/MX" to specify sublists of |
| 18281 | hosts that are obtained by looking up MX records (see section 20.6). |
| 18282 | |
| 18283 | If the lookup type is not specified, Exim behaves as follows when trying to |
| 18284 | find an IP address for each host: First, a DNS lookup is done. If this yields |
| 18285 | anything other than HOST_NOT_FOUND, that result is used. Otherwise, Exim goes |
| 18286 | on to try a call to getipnodebyname() or gethostbyname(), and the result of the |
| 18287 | lookup is the result of that call. |
| 18288 | |
| 18289 | If the DATA field is set, its value is placed in the $address_data variable. |
| 18290 | For example, this return line |
| 18291 | |
| 18292 | accept hosts=x1.y.example:x2.y.example data="rule1" |
| 18293 | |
| 18294 | routes the address to the default transport, passing a list of two hosts. When |
| 18295 | the transport runs, the string "rule1" is in $address_data. |
| 18296 | |
| 18297 | |
| 18298 | |
| 18299 | =============================================================================== |
| 18300 | 22. THE REDIRECT ROUTER |
| 18301 | |
| 18302 | The redirect router handles several kinds of address redirection. Its most |
| 18303 | common uses are for resolving local part aliases from a central alias file |
| 18304 | (usually called /etc/aliases) and for handling users' personal .forward files, |
| 18305 | but it has many other potential uses. The incoming address can be redirected in |
| 18306 | several different ways: |
| 18307 | |
| 18308 | * It can be replaced by one or more new addresses which are themselves routed |
| 18309 | independently. |
| 18310 | |
| 18311 | * It can be routed to be delivered to a given file or directory. |
| 18312 | |
| 18313 | * It can be routed to be delivered to a specified pipe command. |
| 18314 | |
| 18315 | * It can cause an automatic reply to be generated. |
| 18316 | |
| 18317 | * It can be forced to fail, optionally with a custom error message. |
| 18318 | |
| 18319 | * It can be temporarily deferred, optionally with a custom message. |
| 18320 | |
| 18321 | * It can be discarded. |
| 18322 | |
| 18323 | The generic transport option must not be set for redirect routers. However, |
| 18324 | there are some private options which define transports for delivery to files |
| 18325 | and pipes, and for generating autoreplies. See the file_transport, |
| 18326 | pipe_transport and reply_transport descriptions below. |
| 18327 | |
| 18328 | If success DSNs have been requested redirection triggers one and the DSN |
| 18329 | options are not passed any further. |
| 18330 | |
| 18331 | |
| 18332 | 22.1 Redirection data |
| 18333 | --------------------- |
| 18334 | |
| 18335 | The router operates by interpreting a text string which it obtains either by |
| 18336 | expanding the contents of the data option, or by reading the entire contents of |
| 18337 | a file whose name is given in the file option. These two options are mutually |
| 18338 | exclusive. The first is commonly used for handling system aliases, in a |
| 18339 | configuration like this: |
| 18340 | |
| 18341 | system_aliases: |
| 18342 | driver = redirect |
| 18343 | data = ${lookup{$local_part}lsearch{/etc/aliases}} |
| 18344 | |
| 18345 | If the lookup fails, the expanded string in this example is empty. When the |
| 18346 | expansion of data results in an empty string, the router declines. A forced |
| 18347 | expansion failure also causes the router to decline; other expansion failures |
| 18348 | cause delivery to be deferred. |
| 18349 | |
| 18350 | A configuration using file is commonly used for handling users' .forward files, |
| 18351 | like this: |
| 18352 | |
| 18353 | userforward: |
| 18354 | driver = redirect |
| 18355 | check_local_user |
| 18356 | file = $home/.forward |
| 18357 | no_verify |
| 18358 | |
| 18359 | If the file does not exist, or causes no action to be taken (for example, it is |
| 18360 | empty or consists only of comments), the router declines. Warning: This is not |
| 18361 | the case when the file contains syntactically valid items that happen to yield |
| 18362 | empty addresses, for example, items containing only RFC 2822 address comments. |
| 18363 | |
| 18364 | |
| 18365 | 22.2 Forward files and address verification |
| 18366 | ------------------------------------------- |
| 18367 | |
| 18368 | It is usual to set no_verify on redirect routers which handle users' .forward |
| 18369 | files, as in the example above. There are two reasons for this: |
| 18370 | |
| 18371 | * When Exim is receiving an incoming SMTP message from a remote host, it is |
| 18372 | running under the Exim uid, not as root. Exim is unable to change uid to |
| 18373 | read the file as the user, and it may not be able to read it as the Exim |
| 18374 | user. So in practice the router may not be able to operate. |
| 18375 | |
| 18376 | * However, even when the router can operate, the existence of a .forward file |
| 18377 | is unimportant when verifying an address. What should be checked is whether |
| 18378 | the local part is a valid user name or not. Cutting out the redirection |
| 18379 | processing saves some resources. |
| 18380 | |
| 18381 | |
| 18382 | 22.3 Interpreting redirection data |
| 18383 | ---------------------------------- |
| 18384 | |
| 18385 | The contents of the data string, whether obtained from data or file, can be |
| 18386 | interpreted in two different ways: |
| 18387 | |
| 18388 | * If the allow_filter option is set true, and the data begins with the text " |
| 18389 | #Exim filter" or "#Sieve filter", it is interpreted as a list of filtering |
| 18390 | instructions in the form of an Exim or Sieve filter file, respectively. |
| 18391 | Details of the syntax and semantics of filter files are described in a |
| 18392 | separate document entitled Exim's interfaces to mail filtering; this |
| 18393 | document is intended for use by end users. |
| 18394 | |
| 18395 | * Otherwise, the data must be a comma-separated list of redirection items, as |
| 18396 | described in the next section. |
| 18397 | |
| 18398 | When a message is redirected to a file (a "mail folder"), the file name given |
| 18399 | in a non-filter redirection list must always be an absolute path. A filter may |
| 18400 | generate a relative path - how this is handled depends on the transport's |
| 18401 | configuration. See section 26.1 for a discussion of this issue for the |
| 18402 | appendfile transport. |
| 18403 | |
| 18404 | |
| 18405 | 22.4 Items in a non-filter redirection list |
| 18406 | ------------------------------------------- |
| 18407 | |
| 18408 | When the redirection data is not an Exim or Sieve filter, for example, if it |
| 18409 | comes from a conventional alias or forward file, it consists of a list of |
| 18410 | addresses, file names, pipe commands, or certain special items (see section |
| 18411 | 22.6 below). The special items can be individually enabled or disabled by means |
| 18412 | of options whose names begin with allow_ or forbid_, depending on their default |
| 18413 | values. The items in the list are separated by commas or newlines. If a comma |
| 18414 | is required in an item, the entire item must be enclosed in double quotes. |
| 18415 | |
| 18416 | Lines starting with a # character are comments, and are ignored, and # may also |
| 18417 | appear following a comma, in which case everything between the # and the next |
| 18418 | newline character is ignored. |
| 18419 | |
| 18420 | If an item is entirely enclosed in double quotes, these are removed. Otherwise |
| 18421 | double quotes are retained because some forms of mail address require their use |
| 18422 | (but never to enclose the entire address). In the following description, "item" |
| 18423 | refers to what remains after any surrounding double quotes have been removed. |
| 18424 | |
| 18425 | Warning: If you use an Exim expansion to construct a redirection address, and |
| 18426 | the expansion contains a reference to $local_part, you should make use of the |
| 18427 | quote_local_part expansion operator, in case the local part contains special |
| 18428 | characters. For example, to redirect all mail for the domain obsolete.example, |
| 18429 | retaining the existing local part, you could use this setting: |
| 18430 | |
| 18431 | data = ${quote_local_part:$local_part}@newdomain.example |
| 18432 | |
| 18433 | |
| 18434 | 22.5 Redirecting to a local mailbox |
| 18435 | ----------------------------------- |
| 18436 | |
| 18437 | A redirection item may safely be the same as the address currently under |
| 18438 | consideration. This does not cause a routing loop, because a router is |
| 18439 | automatically skipped if any ancestor of the address that is being processed is |
| 18440 | the same as the current address and was processed by the current router. Such |
| 18441 | an address is therefore passed to the following routers, so it is handled as if |
| 18442 | there were no redirection. When making this loop-avoidance test, the complete |
| 18443 | local part, including any prefix or suffix, is used. |
| 18444 | |
| 18445 | Specifying the same local part without a domain is a common usage in personal |
| 18446 | filter files when the user wants to have messages delivered to the local |
| 18447 | mailbox and also forwarded elsewhere. For example, the user whose login is cleo |
| 18448 | might have a .forward file containing this: |
| 18449 | |
| 18450 | cleo, cleopatra@egypt.example |
| 18451 | |
| 18452 | For compatibility with other MTAs, such unqualified local parts may be preceded |
| 18453 | by "\", but this is not a requirement for loop prevention. However, it does |
| 18454 | make a difference if more than one domain is being handled synonymously. |
| 18455 | |
| 18456 | If an item begins with "\" and the rest of the item parses as a valid RFC 2822 |
| 18457 | address that does not include a domain, the item is qualified using the domain |
| 18458 | of the incoming address. In the absence of a leading "\", unqualified addresses |
| 18459 | are qualified using the value in qualify_recipient, but you can force the |
| 18460 | incoming domain to be used by setting qualify_preserve_domain. |
| 18461 | |
| 18462 | Care must be taken if there are alias names for local users. Consider an MTA |
| 18463 | handling a single local domain where the system alias file contains: |
| 18464 | |
| 18465 | Sam.Reman: spqr |
| 18466 | |
| 18467 | Now suppose that Sam (whose login id is spqr) wants to save copies of messages |
| 18468 | in the local mailbox, and also forward copies elsewhere. He creates this |
| 18469 | forward file: |
| 18470 | |
| 18471 | Sam.Reman, spqr@reme.elsewhere.example |
| 18472 | |
| 18473 | With these settings, an incoming message addressed to Sam.Reman fails. The |
| 18474 | redirect router for system aliases does not process Sam.Reman the second time |
| 18475 | round, because it has previously routed it, and the following routers |
| 18476 | presumably cannot handle the alias. The forward file should really contain |
| 18477 | |
| 18478 | spqr, spqr@reme.elsewhere.example |
| 18479 | |
| 18480 | but because this is such a common error, the check_ancestor option (see below) |
| 18481 | exists to provide a way to get round it. This is normally set on a redirect |
| 18482 | router that is handling users' .forward files. |
| 18483 | |
| 18484 | |
| 18485 | 22.6 Special items in redirection lists |
| 18486 | --------------------------------------- |
| 18487 | |
| 18488 | In addition to addresses, the following types of item may appear in redirection |
| 18489 | lists (that is, in non-filter redirection data): |
| 18490 | |
| 18491 | * An item is treated as a pipe command if it begins with "|" and does not |
| 18492 | parse as a valid RFC 2822 address that includes a domain. A transport for |
| 18493 | running the command must be specified by the pipe_transport option. |
| 18494 | Normally, either the router or the transport specifies a user and a group |
| 18495 | under which to run the delivery. The default is to use the Exim user and |
| 18496 | group. |
| 18497 | |
| 18498 | Single or double quotes can be used for enclosing the individual arguments |
| 18499 | of the pipe command; no interpretation of escapes is done for single |
| 18500 | quotes. If the command contains a comma character, it is necessary to put |
| 18501 | the whole item in double quotes, for example: |
| 18502 | |
| 18503 | "|/some/command ready,steady,go" |
| 18504 | |
| 18505 | since items in redirection lists are terminated by commas. Do not, however, |
| 18506 | quote just the command. An item such as |
| 18507 | |
| 18508 | |"/some/command ready,steady,go" |
| 18509 | |
| 18510 | is interpreted as a pipe with a rather strange command name, and no |
| 18511 | arguments. |
| 18512 | |
| 18513 | Note that the above example assumes that the text comes from a lookup |
| 18514 | source of some sort, so that the quotes are part of the data. If composing |
| 18515 | a redirect router with a data option directly specifying this command, the |
| 18516 | quotes will be used by the configuration parser to define the extent of one |
| 18517 | string, but will not be passed down into the redirect router itself. There |
| 18518 | are two main approaches to get around this: escape quotes to be part of the |
| 18519 | data itself, or avoid using this mechanism and instead create a custom |
| 18520 | transport with the command option set and reference that transport from an |
| 18521 | accept router. |
| 18522 | |
| 18523 | * An item is interpreted as a path name if it begins with "/" and does not |
| 18524 | parse as a valid RFC 2822 address that includes a domain. For example, |
| 18525 | |
| 18526 | /home/world/minbari |
| 18527 | |
| 18528 | is treated as a file name, but |
| 18529 | |
| 18530 | /s=molari/o=babylon/@x400gate.way |
| 18531 | |
| 18532 | is treated as an address. For a file name, a transport must be specified |
| 18533 | using the file_transport option. However, if the generated path name ends |
| 18534 | with a forward slash character, it is interpreted as a directory name |
| 18535 | rather than a file name, and directory_transport is used instead. |
| 18536 | |
| 18537 | Normally, either the router or the transport specifies a user and a group |
| 18538 | under which to run the delivery. The default is to use the Exim user and |
| 18539 | group. |
| 18540 | |
| 18541 | However, if a redirection item is the path /dev/null, delivery to it is |
| 18542 | bypassed at a high level, and the log entry shows "**bypassed**" instead of |
| 18543 | a transport name. In this case the user and group are not used. |
| 18544 | |
| 18545 | * If an item is of the form |
| 18546 | |
| 18547 | :include:<path name> |
| 18548 | |
| 18549 | a list of further items is taken from the given file and included at that |
| 18550 | point. Note: Such a file can not be a filter file; it is just an |
| 18551 | out-of-line addition to the list. The items in the included list are |
| 18552 | separated by commas or newlines and are not subject to expansion. If this |
| 18553 | is the first item in an alias list in an lsearch file, a colon must be used |
| 18554 | to terminate the alias name. This example is incorrect: |
| 18555 | |
| 18556 | list1 :include:/opt/lists/list1 |
| 18557 | |
| 18558 | It must be given as |
| 18559 | |
| 18560 | list1: :include:/opt/lists/list1 |
| 18561 | |
| 18562 | * Sometimes you want to throw away mail to a particular local part. Making |
| 18563 | the data option expand to an empty string does not work, because that |
| 18564 | causes the router to decline. Instead, the alias item |
| 18565 | |
| 18566 | :blackhole: |
| 18567 | |
| 18568 | can be used. It does what its name implies. No delivery is done, and no |
| 18569 | error message is generated. This has the same effect as specifying /dev/ |
| 18570 | null as a destination, but it can be independently disabled. |
| 18571 | |
| 18572 | Warning: If :blackhole: appears anywhere in a redirection list, no delivery |
| 18573 | is done for the original local part, even if other redirection items are |
| 18574 | present. If you are generating a multi-item list (for example, by reading a |
| 18575 | database) and need the ability to provide a no-op item, you must use /dev/ |
| 18576 | null. |
| 18577 | |
| 18578 | * An attempt to deliver a particular address can be deferred or forced to |
| 18579 | fail by redirection items of the form |
| 18580 | |
| 18581 | :defer: |
| 18582 | :fail: |
| 18583 | |
| 18584 | respectively. When a redirection list contains such an item, it applies to |
| 18585 | the entire redirection; any other items in the list are ignored. Any text |
| 18586 | following :fail: or :defer: is placed in the error text associated with the |
| 18587 | failure. For example, an alias file might contain: |
| 18588 | |
| 18589 | X.Employee: :fail: Gone away, no forwarding address |
| 18590 | |
| 18591 | In the case of an address that is being verified from an ACL or as the |
| 18592 | subject of a VRFY command, the text is included in the SMTP error response |
| 18593 | by default. The text is not included in the response to an EXPN command. In |
| 18594 | non-SMTP cases the text is included in the error message that Exim |
| 18595 | generates. |
| 18596 | |
| 18597 | By default, Exim sends a 451 SMTP code for a :defer:, and 550 for :fail:. |
| 18598 | However, if the message starts with three digits followed by a space, |
| 18599 | optionally followed by an extended code of the form n.n.n, also followed by |
| 18600 | a space, and the very first digit is the same as the default error code, |
| 18601 | the code from the message is used instead. If the very first digit is |
| 18602 | incorrect, a panic error is logged, and the default code is used. You can |
| 18603 | suppress the use of the supplied code in a redirect router by setting the |
| 18604 | forbid_smtp_code option true. In this case, any SMTP code is quietly |
| 18605 | ignored. |
| 18606 | |
| 18607 | In an ACL, an explicitly provided message overrides the default, but the |
| 18608 | default message is available in the variable $acl_verify_message and can |
| 18609 | therefore be included in a custom message if this is desired. |
| 18610 | |
| 18611 | Normally the error text is the rest of the redirection list - a comma does |
| 18612 | not terminate it - but a newline does act as a terminator. Newlines are not |
| 18613 | normally present in alias expansions. In lsearch lookups they are removed |
| 18614 | as part of the continuation process, but they may exist in other kinds of |
| 18615 | lookup and in :include: files. |
| 18616 | |
| 18617 | During routing for message delivery (as opposed to verification), a |
| 18618 | redirection containing :fail: causes an immediate failure of the incoming |
| 18619 | address, whereas :defer: causes the message to remain on the queue so that |
| 18620 | a subsequent delivery attempt can happen at a later time. If an address is |
| 18621 | deferred for too long, it will ultimately fail, because the normal retry |
| 18622 | rules still apply. |
| 18623 | |
| 18624 | * Sometimes it is useful to use a single-key search type with a default (see |
| 18625 | chapter 9) to look up aliases. However, there may be a need for exceptions |
| 18626 | to the default. These can be handled by aliasing them to :unknown:. This |
| 18627 | differs from :fail: in that it causes the redirect router to decline, |
| 18628 | whereas :fail: forces routing to fail. A lookup which results in an empty |
| 18629 | redirection list has the same effect. |
| 18630 | |
| 18631 | |
| 18632 | 22.7 Duplicate addresses |
| 18633 | ------------------------ |
| 18634 | |
| 18635 | Exim removes duplicate addresses from the list to which it is delivering, so as |
| 18636 | to deliver just one copy to each address. This does not apply to deliveries |
| 18637 | routed to pipes by different immediate parent addresses, but an indirect |
| 18638 | aliasing scheme of the type |
| 18639 | |
| 18640 | pipe: |/some/command $local_part |
| 18641 | localpart1: pipe |
| 18642 | localpart2: pipe |
| 18643 | |
| 18644 | does not work with a message that is addressed to both local parts, because |
| 18645 | when the second is aliased to the intermediate local part "pipe" it gets |
| 18646 | discarded as being the same as a previously handled address. However, a scheme |
| 18647 | such as |
| 18648 | |
| 18649 | localpart1: |/some/command $local_part |
| 18650 | localpart2: |/some/command $local_part |
| 18651 | |
| 18652 | does result in two different pipe deliveries, because the immediate parents of |
| 18653 | the pipes are distinct. |
| 18654 | |
| 18655 | |
| 18656 | 22.8 Repeated redirection expansion |
| 18657 | ----------------------------------- |
| 18658 | |
| 18659 | When a message cannot be delivered to all of its recipients immediately, |
| 18660 | leading to two or more delivery attempts, redirection expansion is carried out |
| 18661 | afresh each time for those addresses whose children were not all previously |
| 18662 | delivered. If redirection is being used as a mailing list, this can lead to new |
| 18663 | members of the list receiving copies of old messages. The one_time option can |
| 18664 | be used to avoid this. |
| 18665 | |
| 18666 | |
| 18667 | 22.9 Errors in redirection lists |
| 18668 | -------------------------------- |
| 18669 | |
| 18670 | If skip_syntax_errors is set, a malformed address that causes a parsing error |
| 18671 | is skipped, and an entry is written to the main log. This may be useful for |
| 18672 | mailing lists that are automatically managed. Otherwise, if an error is |
| 18673 | detected while generating the list of new addresses, the original address is |
| 18674 | deferred. See also syntax_errors_to. |
| 18675 | |
| 18676 | |
| 18677 | 22.10 Private options for the redirect router |
| 18678 | --------------------------------------------- |
| 18679 | |
| 18680 | The private options for the redirect router are as follows: |
| 18681 | |
| 18682 | +------------------------------------------------------+ |
| 18683 | |allow_defer|Use: redirect|Type: boolean|Default: false| |
| 18684 | +------------------------------------------------------+ |
| 18685 | |
| 18686 | Setting this option allows the use of :defer: in non-filter redirection data, |
| 18687 | or the defer command in an Exim filter file. |
| 18688 | |
| 18689 | +-----------------------------------------------------+ |
| 18690 | |allow_fail|Use: redirect|Type: boolean|Default: false| |
| 18691 | +-----------------------------------------------------+ |
| 18692 | |
| 18693 | If this option is true, the :fail: item can be used in a redirection list, and |
| 18694 | the fail command may be used in an Exim filter file. |
| 18695 | |
| 18696 | +-------------------------------------------------------+ |
| 18697 | |allow_filter|Use: redirect|Type: boolean|Default: false| |
| 18698 | +-------------------------------------------------------+ |
| 18699 | |
| 18700 | Setting this option allows Exim to interpret redirection data that starts with |
| 18701 | "#Exim filter" or "#Sieve filter" as a set of filtering instructions. There are |
| 18702 | some features of Exim filter files that some administrators may wish to lock |
| 18703 | out; see the forbid_filter_xxx options below. |
| 18704 | |
| 18705 | It is also possible to lock out Exim filters or Sieve filters while allowing |
| 18706 | the other type; see forbid_exim_filter and forbid_sieve_filter. |
| 18707 | |
| 18708 | The filter is run using the uid and gid set by the generic user and group |
| 18709 | options. These take their defaults from the password data if check_local_user |
| 18710 | is set, so in the normal case of users' personal filter files, the filter is |
| 18711 | run as the relevant user. When allow_filter is set true, Exim insists that |
| 18712 | either check_local_user or user is set. |
| 18713 | |
| 18714 | +-------------------------------------------------------+ |
| 18715 | |allow_freeze|Use: redirect|Type: boolean|Default: false| |
| 18716 | +-------------------------------------------------------+ |
| 18717 | |
| 18718 | Setting this option allows the use of the freeze command in an Exim filter. |
| 18719 | This command is more normally encountered in system filters, and is disabled by |
| 18720 | default for redirection filters because it isn't something you usually want to |
| 18721 | let ordinary users do. |
| 18722 | |
| 18723 | +---------------------------------------------------------+ |
| 18724 | |check_ancestor|Use: redirect|Type: boolean|Default: false| |
| 18725 | +---------------------------------------------------------+ |
| 18726 | |
| 18727 | This option is concerned with handling generated addresses that are the same as |
| 18728 | some address in the list of redirection ancestors of the current address. |
| 18729 | Although it is turned off by default in the code, it is set in the default |
| 18730 | configuration file for handling users' .forward files. It is recommended for |
| 18731 | this use of the redirect router. |
| 18732 | |
| 18733 | When check_ancestor is set, if a generated address (including the domain) is |
| 18734 | the same as any ancestor of the current address, it is replaced by a copy of |
| 18735 | the current address. This helps in the case where local part A is aliased to B, |
| 18736 | and B has a .forward file pointing back to A. For example, within a single |
| 18737 | domain, the local part "Joe.Bloggs" is aliased to "jb" and jb/.forward |
| 18738 | contains: |
| 18739 | |
| 18740 | \Joe.Bloggs, <other item(s)> |
| 18741 | |
| 18742 | Without the check_ancestor setting, either local part ("jb" or "joe.bloggs") |
| 18743 | gets processed once by each router and so ends up as it was originally. If "jb" |
| 18744 | is the real mailbox name, mail to "jb" gets delivered (having been turned into |
| 18745 | "joe.bloggs" by the .forward file and back to "jb" by the alias), but mail to |
| 18746 | "joe.bloggs" fails. Setting check_ancestor on the redirect router that handles |
| 18747 | the .forward file prevents it from turning "jb" back into "joe.bloggs" when |
| 18748 | that was the original address. See also the repeat_use option below. |
| 18749 | |
| 18750 | +----------------------------------------------------------+ |
| 18751 | |check_group|Use: redirect|Type: boolean|Default: see below| |
| 18752 | +----------------------------------------------------------+ |
| 18753 | |
| 18754 | When the file option is used, the group owner of the file is checked only when |
| 18755 | this option is set. The permitted groups are those listed in the owngroups |
| 18756 | option, together with the user's default group if check_local_user is set. If |
| 18757 | the file has the wrong group, routing is deferred. The default setting for this |
| 18758 | option is true if check_local_user is set and the modemask option permits the |
| 18759 | group write bit, or if the owngroups option is set. Otherwise it is false, and |
| 18760 | no group check occurs. |
| 18761 | |
| 18762 | +----------------------------------------------------------+ |
| 18763 | |check_owner|Use: redirect|Type: boolean|Default: see below| |
| 18764 | +----------------------------------------------------------+ |
| 18765 | |
| 18766 | When the file option is used, the owner of the file is checked only when this |
| 18767 | option is set. If check_local_user is set, the local user is permitted; |
| 18768 | otherwise the owner must be one of those listed in the owners option. The |
| 18769 | default value for this option is true if check_local_user or owners is set. |
| 18770 | Otherwise the default is false, and no owner check occurs. |
| 18771 | |
| 18772 | +-----------------------------------------------+ |
| 18773 | |data|Use: redirect|Type: string*|Default: unset| |
| 18774 | +-----------------------------------------------+ |
| 18775 | |
| 18776 | This option is mutually exclusive with file. One or other of them must be set, |
| 18777 | but not both. The contents of data are expanded, and then used as the list of |
| 18778 | forwarding items, or as a set of filtering instructions. If the expansion is |
| 18779 | forced to fail, or the result is an empty string or a string that has no effect |
| 18780 | (consists entirely of comments), the router declines. |
| 18781 | |
| 18782 | When filtering instructions are used, the string must begin with "#Exim |
| 18783 | filter", and all comments in the string, including this initial one, must be |
| 18784 | terminated with newline characters. For example: |
| 18785 | |
| 18786 | data = #Exim filter\n\ |
| 18787 | if $h_to: contains Exim then save $home/mail/exim endif |
| 18788 | |
| 18789 | If you are reading the data from a database where newlines cannot be included, |
| 18790 | you can use the ${sg} expansion item to turn the escape string of your choice |
| 18791 | into a newline. |
| 18792 | |
| 18793 | +--------------------------------------------------------------+ |
| 18794 | |directory_transport|Use: redirect|Type: string*|Default: unset| |
| 18795 | +--------------------------------------------------------------+ |
| 18796 | |
| 18797 | A redirect router sets up a direct delivery to a directory when a path name |
| 18798 | ending with a slash is specified as a new "address". The transport used is |
| 18799 | specified by this option, which, after expansion, must be the name of a |
| 18800 | configured transport. This should normally be an appendfile transport. |
| 18801 | |
| 18802 | +-----------------------------------------------+ |
| 18803 | |file|Use: redirect|Type: string*|Default: unset| |
| 18804 | +-----------------------------------------------+ |
| 18805 | |
| 18806 | This option specifies the name of a file that contains the redirection data. It |
| 18807 | is mutually exclusive with the data option. The string is expanded before use; |
| 18808 | if the expansion is forced to fail, the router declines. Other expansion |
| 18809 | failures cause delivery to be deferred. The result of a successful expansion |
| 18810 | must be an absolute path. The entire file is read and used as the redirection |
| 18811 | data. If the data is an empty string or a string that has no effect (consists |
| 18812 | entirely of comments), the router declines. |
| 18813 | |
| 18814 | If the attempt to open the file fails with a "does not exist" error, Exim runs |
| 18815 | a check on the containing directory, unless ignore_enotdir is true (see below). |
| 18816 | If the directory does not appear to exist, delivery is deferred. This can |
| 18817 | happen when users' .forward files are in NFS-mounted directories, and there is |
| 18818 | a mount problem. If the containing directory does exist, but the file does not, |
| 18819 | the router declines. |
| 18820 | |
| 18821 | +---------------------------------------------------------+ |
| 18822 | |file_transport|Use: redirect|Type: string*|Default: unset| |
| 18823 | +---------------------------------------------------------+ |
| 18824 | |
| 18825 | A redirect router sets up a direct delivery to a file when a path name not |
| 18826 | ending in a slash is specified as a new "address". The transport used is |
| 18827 | specified by this option, which, after expansion, must be the name of a |
| 18828 | configured transport. This should normally be an appendfile transport. When it |
| 18829 | is running, the file name is in $address_file. |
| 18830 | |
| 18831 | +-------------------------------------------------------------+ |
| 18832 | |filter_prepend_home|Use: redirect|Type: boolean|Default: true| |
| 18833 | +-------------------------------------------------------------+ |
| 18834 | |
| 18835 | When this option is true, if a save command in an Exim filter specifies a |
| 18836 | relative path, and $home is defined, it is automatically prepended to the |
| 18837 | relative path. If this option is set false, this action does not happen. The |
| 18838 | relative path is then passed to the transport unmodified. |
| 18839 | |
| 18840 | +-----------------------------------------------------------+ |
| 18841 | |forbid_blackhole|Use: redirect|Type: boolean|Default: false| |
| 18842 | +-----------------------------------------------------------+ |
| 18843 | |
| 18844 | If this option is true, the :blackhole: item may not appear in a redirection |
| 18845 | list. |
| 18846 | |
| 18847 | +-------------------------------------------------------------+ |
| 18848 | |forbid_exim_filter|Use: redirect|Type: boolean|Default: false| |
| 18849 | +-------------------------------------------------------------+ |
| 18850 | |
| 18851 | If this option is set true, only Sieve filters are permitted when allow_filter |
| 18852 | is true. |
| 18853 | |
| 18854 | +------------------------------------------------------+ |
| 18855 | |forbid_file|Use: redirect|Type: boolean|Default: false| |
| 18856 | +------------------------------------------------------+ |
| 18857 | |
| 18858 | If this option is true, this router may not generate a new address that |
| 18859 | specifies delivery to a local file or directory, either from a filter or from a |
| 18860 | conventional forward file. This option is forced to be true if one_time is set. |
| 18861 | It applies to Sieve filters as well as to Exim filters, but if true, it locks |
| 18862 | out the Sieve's "keep" facility. |
| 18863 | |
| 18864 | +---------------------------------------------------------------+ |
| 18865 | |forbid_filter_dlfunc|Use: redirect|Type: boolean|Default: false| |
| 18866 | +---------------------------------------------------------------+ |
| 18867 | |
| 18868 | If this option is true, string expansions in Exim filters are not allowed to |
| 18869 | make use of the dlfunc expansion facility to run dynamically loaded functions. |
| 18870 | |
| 18871 | +-------------------------------------------------------------------+ |
| 18872 | |forbid_filter_existstest|Use: redirect|Type: boolean|Default: false| |
| 18873 | +-------------------------------------------------------------------+ |
| 18874 | |
| 18875 | If this option is true, string expansions in Exim filters are not allowed to |
| 18876 | make use of the exists condition or the stat expansion item. |
| 18877 | |
| 18878 | +-----------------------------------------------------------------+ |
| 18879 | |forbid_filter_logwrite|Use: redirect|Type: boolean|Default: false| |
| 18880 | +-----------------------------------------------------------------+ |
| 18881 | |
| 18882 | If this option is true, use of the logging facility in Exim filters is not |
| 18883 | permitted. Logging is in any case available only if the filter is being run |
| 18884 | under some unprivileged uid (which is normally the case for ordinary users' |
| 18885 | .forward files). |
| 18886 | |
| 18887 | +---------------------------------------------------------------+ |
| 18888 | |forbid_filter_lookup|Use: redirect|Type: boolean|Default: false| |
| 18889 | +---------------------------------------------------------------+ |
| 18890 | |
| 18891 | If this option is true, string expansions in Exim filter files are not allowed |
| 18892 | to make use of lookup items. |
| 18893 | |
| 18894 | +-------------------------------------------------------------+ |
| 18895 | |forbid_filter_perl|Use: redirect|Type: boolean|Default: false| |
| 18896 | +-------------------------------------------------------------+ |
| 18897 | |
| 18898 | This option has an effect only if Exim is built with embedded Perl support. If |
| 18899 | it is true, string expansions in Exim filter files are not allowed to make use |
| 18900 | of the embedded Perl support. |
| 18901 | |
| 18902 | +-----------------------------------------------------------------+ |
| 18903 | |forbid_filter_readfile|Use: redirect|Type: boolean|Default: false| |
| 18904 | +-----------------------------------------------------------------+ |
| 18905 | |
| 18906 | If this option is true, string expansions in Exim filter files are not allowed |
| 18907 | to make use of readfile items. |
| 18908 | |
| 18909 | +-------------------------------------------------------------------+ |
| 18910 | |forbid_filter_readsocket|Use: redirect|Type: boolean|Default: false| |
| 18911 | +-------------------------------------------------------------------+ |
| 18912 | |
| 18913 | If this option is true, string expansions in Exim filter files are not allowed |
| 18914 | to make use of readsocket items. |
| 18915 | |
| 18916 | +--------------------------------------------------------------+ |
| 18917 | |forbid_filter_reply|Use: redirect|Type: boolean|Default: false| |
| 18918 | +--------------------------------------------------------------+ |
| 18919 | |
| 18920 | If this option is true, this router may not generate an automatic reply |
| 18921 | message. Automatic replies can be generated only from Exim or Sieve filter |
| 18922 | files, not from traditional forward files. This option is forced to be true if |
| 18923 | one_time is set. |
| 18924 | |
| 18925 | +------------------------------------------------------------+ |
| 18926 | |forbid_filter_run|Use: redirect|Type: boolean|Default: false| |
| 18927 | +------------------------------------------------------------+ |
| 18928 | |
| 18929 | If this option is true, string expansions in Exim filter files are not allowed |
| 18930 | to make use of run items. |
| 18931 | |
| 18932 | +---------------------------------------------------------+ |
| 18933 | |forbid_include|Use: redirect|Type: boolean|Default: false| |
| 18934 | +---------------------------------------------------------+ |
| 18935 | |
| 18936 | If this option is true, items of the form |
| 18937 | |
| 18938 | :include:<path name> |
| 18939 | |
| 18940 | are not permitted in non-filter redirection lists. |
| 18941 | |
| 18942 | +------------------------------------------------------+ |
| 18943 | |forbid_pipe|Use: redirect|Type: boolean|Default: false| |
| 18944 | +------------------------------------------------------+ |
| 18945 | |
| 18946 | If this option is true, this router may not generate a new address which |
| 18947 | specifies delivery to a pipe, either from an Exim filter or from a conventional |
| 18948 | forward file. This option is forced to be true if one_time is set. |
| 18949 | |
| 18950 | +--------------------------------------------------------------+ |
| 18951 | |forbid_sieve_filter|Use: redirect|Type: boolean|Default: false| |
| 18952 | +--------------------------------------------------------------+ |
| 18953 | |
| 18954 | If this option is set true, only Exim filters are permitted when allow_filter |
| 18955 | is true. |
| 18956 | |
| 18957 | +-----------------------------------------------------------+ |
| 18958 | |forbid_smtp_code|Use: redirect|Type: boolean|Default: false| |
| 18959 | +-----------------------------------------------------------+ |
| 18960 | |
| 18961 | If this option is set true, any SMTP error codes that are present at the start |
| 18962 | of messages specified for ":defer:" or ":fail:" are quietly ignored, and the |
| 18963 | default codes (451 and 550, respectively) are always used. |
| 18964 | |
| 18965 | +---------------------------------------------------------------+ |
| 18966 | |hide_child_in_errmsg|Use: redirect|Type: boolean|Default: false| |
| 18967 | +---------------------------------------------------------------+ |
| 18968 | |
| 18969 | If this option is true, it prevents Exim from quoting a child address if it |
| 18970 | generates a bounce or delay message for it. Instead it says "an address |
| 18971 | generated from <the top level address>". Of course, this applies only to |
| 18972 | bounces generated locally. If a message is forwarded to another host, its |
| 18973 | bounce may well quote the generated address. |
| 18974 | |
| 18975 | +--------------------------------------------------------+ |
| 18976 | |ignore_eacces|Use: redirect|Type: boolean|Default: false| |
| 18977 | +--------------------------------------------------------+ |
| 18978 | |
| 18979 | If this option is set and an attempt to open a redirection file yields the |
| 18980 | EACCES error (permission denied), the redirect router behaves as if the file |
| 18981 | did not exist. |
| 18982 | |
| 18983 | +---------------------------------------------------------+ |
| 18984 | |ignore_enotdir|Use: redirect|Type: boolean|Default: false| |
| 18985 | +---------------------------------------------------------+ |
| 18986 | |
| 18987 | If this option is set and an attempt to open a redirection file yields the |
| 18988 | ENOTDIR error (something on the path is not a directory), the redirect router |
| 18989 | behaves as if the file did not exist. |
| 18990 | |
| 18991 | Setting ignore_enotdir has another effect as well: When a redirect router that |
| 18992 | has the file option set discovers that the file does not exist (the ENOENT |
| 18993 | error), it tries to stat() the parent directory, as a check against unmounted |
| 18994 | NFS directories. If the parent can not be statted, delivery is deferred. |
| 18995 | However, it seems wrong to do this check when ignore_enotdir is set, because |
| 18996 | that option tells Exim to ignore "something on the path is not a directory" |
| 18997 | (the ENOTDIR error). This is a confusing area, because it seems that some |
| 18998 | operating systems give ENOENT where others give ENOTDIR. |
| 18999 | |
| 19000 | +-----------------------------------------------------------+ |
| 19001 | |include_directory|Use: redirect|Type: string|Default: unset| |
| 19002 | +-----------------------------------------------------------+ |
| 19003 | |
| 19004 | If this option is set, the path names of any :include: items in a redirection |
| 19005 | list must start with this directory. |
| 19006 | |
| 19007 | +-------------------------------------------------------+ |
| 19008 | |modemask|Use: redirect|Type: octal integer|Default: 022| |
| 19009 | +-------------------------------------------------------+ |
| 19010 | |
| 19011 | This specifies mode bits which must not be set for a file specified by the file |
| 19012 | option. If any of the forbidden bits are set, delivery is deferred. |
| 19013 | |
| 19014 | +---------------------------------------------------+ |
| 19015 | |one_time|Use: redirect|Type: boolean|Default: false| |
| 19016 | +---------------------------------------------------+ |
| 19017 | |
| 19018 | Sometimes the fact that Exim re-evaluates aliases and reprocesses redirection |
| 19019 | files each time it tries to deliver a message causes a problem when one or more |
| 19020 | of the generated addresses fails be delivered at the first attempt. The problem |
| 19021 | is not one of duplicate delivery - Exim is clever enough to handle that - but |
| 19022 | of what happens when the redirection list changes during the time that the |
| 19023 | message is on Exim's queue. This is particularly true in the case of mailing |
| 19024 | lists, where new subscribers might receive copies of messages that were posted |
| 19025 | before they subscribed. |
| 19026 | |
| 19027 | If one_time is set and any addresses generated by the router fail to deliver at |
| 19028 | the first attempt, the failing addresses are added to the message as "top |
| 19029 | level" addresses, and the parent address that generated them is marked |
| 19030 | "delivered". Thus, redirection does not happen again at the next delivery |
| 19031 | attempt. |
| 19032 | |
| 19033 | Warning 1: Any header line addition or removal that is specified by this router |
| 19034 | would be lost if delivery did not succeed at the first attempt. For this |
| 19035 | reason, the headers_add and headers_remove generic options are not permitted |
| 19036 | when one_time is set. |
| 19037 | |
| 19038 | Warning 2: To ensure that the router generates only addresses (as opposed to |
| 19039 | pipe or file deliveries or auto-replies) forbid_file, forbid_pipe, and |
| 19040 | forbid_filter_reply are forced to be true when one_time is set. |
| 19041 | |
| 19042 | Warning 3: The unseen generic router option may not be set with one_time. |
| 19043 | |
| 19044 | The original top-level address is remembered with each of the generated |
| 19045 | addresses, and is output in any log messages. However, any intermediate parent |
| 19046 | addresses are not recorded. This makes a difference to the log only if |
| 19047 | all_parents log selector is set. It is expected that one_time will typically be |
| 19048 | used for mailing lists, where there is normally just one level of expansion. |
| 19049 | |
| 19050 | +-----------------------------------------------------+ |
| 19051 | |owners|Use: redirect|Type: string list|Default: unset| |
| 19052 | +-----------------------------------------------------+ |
| 19053 | |
| 19054 | This specifies a list of permitted owners for the file specified by file. This |
| 19055 | list is in addition to the local user when check_local_user is set. See |
| 19056 | check_owner above. |
| 19057 | |
| 19058 | +--------------------------------------------------------+ |
| 19059 | |owngroups|Use: redirect|Type: string list|Default: unset| |
| 19060 | +--------------------------------------------------------+ |
| 19061 | |
| 19062 | This specifies a list of permitted groups for the file specified by file. The |
| 19063 | list is in addition to the local user's primary group when check_local_user is |
| 19064 | set. See check_group above. |
| 19065 | |
| 19066 | +---------------------------------------------------------+ |
| 19067 | |pipe_transport|Use: redirect|Type: string*|Default: unset| |
| 19068 | +---------------------------------------------------------+ |
| 19069 | |
| 19070 | A redirect router sets up a direct delivery to a pipe when a string starting |
| 19071 | with a vertical bar character is specified as a new "address". The transport |
| 19072 | used is specified by this option, which, after expansion, must be the name of a |
| 19073 | configured transport. This should normally be a pipe transport. When the |
| 19074 | transport is run, the pipe command is in $address_pipe. |
| 19075 | |
| 19076 | +---------------------------------------------------------+ |
| 19077 | |qualify_domain|Use: redirect|Type: string*|Default: unset| |
| 19078 | +---------------------------------------------------------+ |
| 19079 | |
| 19080 | If this option is set, and an unqualified address (one without a domain) is |
| 19081 | generated, and that address would normally be qualified by the global setting |
| 19082 | in qualify_recipient, it is instead qualified with the domain specified by |
| 19083 | expanding this string. If the expansion fails, the router declines. If you want |
| 19084 | to revert to the default, you can have the expansion generate |
| 19085 | $qualify_recipient. |
| 19086 | |
| 19087 | This option applies to all unqualified addresses generated by Exim filters, but |
| 19088 | for traditional .forward files, it applies only to addresses that are not |
| 19089 | preceded by a backslash. Sieve filters cannot generate unqualified addresses. |
| 19090 | |
| 19091 | +------------------------------------------------------------------+ |
| 19092 | |qualify_preserve_domain|Use: redirect|Type: boolean|Default: false| |
| 19093 | +------------------------------------------------------------------+ |
| 19094 | |
| 19095 | If this option is set, the router's local qualify_domain option must not be set |
| 19096 | (a configuration error occurs if it is). If an unqualified address (one without |
| 19097 | a domain) is generated, it is qualified with the domain of the parent address |
| 19098 | (the immediately preceding ancestor) instead of the global qualify_recipient |
| 19099 | value. In the case of a traditional .forward file, this applies whether or not |
| 19100 | the address is preceded by a backslash. |
| 19101 | |
| 19102 | +----------------------------------------------------+ |
| 19103 | |repeat_use|Use: redirect|Type: boolean|Default: true| |
| 19104 | +----------------------------------------------------+ |
| 19105 | |
| 19106 | If this option is set false, the router is skipped for a child address that has |
| 19107 | any ancestor that was routed by this router. This test happens before any of |
| 19108 | the other preconditions are tested. Exim's default anti-looping rules skip only |
| 19109 | when the ancestor is the same as the current address. See also check_ancestor |
| 19110 | above and the generic redirect_router option. |
| 19111 | |
| 19112 | +----------------------------------------------------------+ |
| 19113 | |reply_transport|Use: redirect|Type: string*|Default: unset| |
| 19114 | +----------------------------------------------------------+ |
| 19115 | |
| 19116 | A redirect router sets up an automatic reply when a mail or vacation command is |
| 19117 | used in a filter file. The transport used is specified by this option, which, |
| 19118 | after expansion, must be the name of a configured transport. This should |
| 19119 | normally be an autoreply transport. Other transports are unlikely to do |
| 19120 | anything sensible or useful. |
| 19121 | |
| 19122 | +-------------------------------------------------+ |
| 19123 | |rewrite|Use: redirect|Type: boolean|Default: true| |
| 19124 | +-------------------------------------------------+ |
| 19125 | |
| 19126 | If this option is set false, addresses generated by the router are not subject |
| 19127 | to address rewriting. Otherwise, they are treated like new addresses and are |
| 19128 | rewritten according to the global rewriting rules. |
| 19129 | |
| 19130 | +-----------------------------------------------------------+ |
| 19131 | |sieve_subaddress|Use: redirect|Type: string*|Default: unset| |
| 19132 | +-----------------------------------------------------------+ |
| 19133 | |
| 19134 | The value of this option is passed to a Sieve filter to specify the :subaddress |
| 19135 | part of an address. |
| 19136 | |
| 19137 | +------------------------------------------------------------+ |
| 19138 | |sieve_useraddress|Use: redirect|Type: string*|Default: unset| |
| 19139 | +------------------------------------------------------------+ |
| 19140 | |
| 19141 | The value of this option is passed to a Sieve filter to specify the :user part |
| 19142 | of an address. However, if it is unset, the entire original local part |
| 19143 | (including any prefix or suffix) is used for :user. |
| 19144 | |
| 19145 | +-------------------------------------------------------------------+ |
| 19146 | |sieve_vacation_directory|Use: redirect|Type: string*|Default: unset| |
| 19147 | +-------------------------------------------------------------------+ |
| 19148 | |
| 19149 | To enable the "vacation" extension for Sieve filters, you must set |
| 19150 | sieve_vacation_directory to the directory where vacation databases are held (do |
| 19151 | not put anything else in that directory), and ensure that the reply_transport |
| 19152 | option refers to an autoreply transport. Each user needs their own directory; |
| 19153 | Exim will create it if necessary. |
| 19154 | |
| 19155 | +-------------------------------------------------------------+ |
| 19156 | |skip_syntax_errors|Use: redirect|Type: boolean|Default: false| |
| 19157 | +-------------------------------------------------------------+ |
| 19158 | |
| 19159 | If skip_syntax_errors is set, syntactically malformed addresses in non-filter |
| 19160 | redirection data are skipped, and each failing address is logged. If |
| 19161 | syntax_errors_to is set, a message is sent to the address it defines, giving |
| 19162 | details of the failures. If syntax_errors_text is set, its contents are |
| 19163 | expanded and placed at the head of the error message generated by |
| 19164 | syntax_errors_to. Usually it is appropriate to set syntax_errors_to to be the |
| 19165 | same address as the generic errors_to option. The skip_syntax_errors option is |
| 19166 | often used when handling mailing lists. |
| 19167 | |
| 19168 | If all the addresses in a redirection list are skipped because of syntax |
| 19169 | errors, the router declines to handle the original address, and it is passed to |
| 19170 | the following routers. |
| 19171 | |
| 19172 | If skip_syntax_errors is set when an Exim filter is interpreted, any syntax |
| 19173 | error in the filter causes filtering to be abandoned without any action being |
| 19174 | taken. The incident is logged, and the router declines to handle the address, |
| 19175 | so it is passed to the following routers. |
| 19176 | |
| 19177 | Syntax errors in a Sieve filter file cause the "keep" action to occur. This |
| 19178 | action is specified by RFC 3028. The values of skip_syntax_errors, |
| 19179 | syntax_errors_to, and syntax_errors_text are not used. |
| 19180 | |
| 19181 | skip_syntax_errors can be used to specify that errors in users' forward lists |
| 19182 | or filter files should not prevent delivery. The syntax_errors_to option, used |
| 19183 | with an address that does not get redirected, can be used to notify users of |
| 19184 | these errors, by means of a router like this: |
| 19185 | |
| 19186 | userforward: |
| 19187 | driver = redirect |
| 19188 | allow_filter |
| 19189 | check_local_user |
| 19190 | file = $home/.forward |
| 19191 | file_transport = address_file |
| 19192 | pipe_transport = address_pipe |
| 19193 | reply_transport = address_reply |
| 19194 | no_verify |
| 19195 | skip_syntax_errors |
| 19196 | syntax_errors_to = real-$local_part@$domain |
| 19197 | syntax_errors_text = \ |
| 19198 | This is an automatically generated message. An error has\n\ |
| 19199 | been found in your .forward file. Details of the error are\n\ |
| 19200 | reported below. While this error persists, you will receive\n\ |
| 19201 | a copy of this message for every message that is addressed\n\ |
| 19202 | to you. If your .forward file is a filter file, or if it is\n\ |
| 19203 | a non-filter file containing no valid forwarding addresses,\n\ |
| 19204 | a copy of each incoming message will be put in your normal\n\ |
| 19205 | mailbox. If a non-filter file contains at least one valid\n\ |
| 19206 | forwarding address, forwarding to the valid addresses will\n\ |
| 19207 | happen, and those will be the only deliveries that occur. |
| 19208 | |
| 19209 | You also need a router to ensure that local addresses that are prefixed by |
| 19210 | "real-" are recognized, but not forwarded or filtered. For example, you could |
| 19211 | put this immediately before the userforward router: |
| 19212 | |
| 19213 | real_localuser: |
| 19214 | driver = accept |
| 19215 | check_local_user |
| 19216 | local_part_prefix = real- |
| 19217 | transport = local_delivery |
| 19218 | |
| 19219 | For security, it would probably be a good idea to restrict the use of this |
| 19220 | router to locally-generated messages, using a condition such as this: |
| 19221 | |
| 19222 | condition = ${if match {$sender_host_address}\ |
| 19223 | {\N^(|127\.0\.0\.1)$\N}} |
| 19224 | |
| 19225 | +-------------------------------------------------------------+ |
| 19226 | |syntax_errors_text|Use: redirect|Type: string*|Default: unset| |
| 19227 | +-------------------------------------------------------------+ |
| 19228 | |
| 19229 | See skip_syntax_errors above. |
| 19230 | |
| 19231 | +----------------------------------------------------------+ |
| 19232 | |syntax_errors_to|Use: redirect|Type: string|Default: unset| |
| 19233 | +----------------------------------------------------------+ |
| 19234 | |
| 19235 | See skip_syntax_errors above. |
| 19236 | |
| 19237 | |
| 19238 | |
| 19239 | =============================================================================== |
| 19240 | 23. ENVIRONMENT FOR RUNNING LOCAL TRANSPORTS |
| 19241 | |
| 19242 | Local transports handle deliveries to files and pipes. (The autoreply transport |
| 19243 | can be thought of as similar to a pipe.) Exim always runs transports in |
| 19244 | subprocesses, under specified uids and gids. Typical deliveries to local |
| 19245 | mailboxes run under the uid and gid of the local user. |
| 19246 | |
| 19247 | Exim also sets a specific current directory while running the transport; for |
| 19248 | some transports a home directory setting is also relevant. The pipe transport |
| 19249 | is the only one that sets up environment variables; see section 29.4 for |
| 19250 | details. |
| 19251 | |
| 19252 | The values used for the uid, gid, and the directories may come from several |
| 19253 | different places. In many cases, the router that handles the address associates |
| 19254 | settings with that address as a result of its check_local_user, group, or user |
| 19255 | options. However, values may also be given in the transport's own |
| 19256 | configuration, and these override anything that comes from the router. |
| 19257 | |
| 19258 | |
| 19259 | 23.1 Concurrent deliveries |
| 19260 | -------------------------- |
| 19261 | |
| 19262 | If two different messages for the same local recipient arrive more or less |
| 19263 | simultaneously, the two delivery processes are likely to run concurrently. When |
| 19264 | the appendfile transport is used to write to a file, Exim applies locking rules |
| 19265 | to stop concurrent processes from writing to the same file at the same time. |
| 19266 | |
| 19267 | However, when you use a pipe transport, it is up to you to arrange any locking |
| 19268 | that is needed. Here is a silly example: |
| 19269 | |
| 19270 | my_transport: |
| 19271 | driver = pipe |
| 19272 | command = /bin/sh -c 'cat >>/some/file' |
| 19273 | |
| 19274 | This is supposed to write the message at the end of the file. However, if two |
| 19275 | messages arrive at the same time, the file will be scrambled. You can use the |
| 19276 | exim_lock utility program (see section 53.15) to lock a file using the same |
| 19277 | algorithm that Exim itself uses. |
| 19278 | |
| 19279 | |
| 19280 | 23.2 Uids and gids |
| 19281 | ------------------ |
| 19282 | |
| 19283 | All transports have the options group and user. If group is set, it overrides |
| 19284 | any group that the router set in the address, even if user is not set for the |
| 19285 | transport. This makes it possible, for example, to run local mail delivery |
| 19286 | under the uid of the recipient (set by the router), but in a special group (set |
| 19287 | by the transport). For example: |
| 19288 | |
| 19289 | # Routers ... |
| 19290 | # User/group are set by check_local_user in this router |
| 19291 | local_users: |
| 19292 | driver = accept |
| 19293 | check_local_user |
| 19294 | transport = group_delivery |
| 19295 | |
| 19296 | # Transports ... |
| 19297 | # This transport overrides the group |
| 19298 | group_delivery: |
| 19299 | driver = appendfile |
| 19300 | file = /var/spool/mail/$local_part |
| 19301 | group = mail |
| 19302 | |
| 19303 | If user is set for a transport, its value overrides what is set in the address |
| 19304 | by the router. If user is non-numeric and group is not set, the gid associated |
| 19305 | with the user is used. If user is numeric, group must be set. |
| 19306 | |
| 19307 | When the uid is taken from the transport's configuration, the initgroups() |
| 19308 | function is called for the groups associated with that uid if the initgroups |
| 19309 | option is set for the transport. When the uid is not specified by the |
| 19310 | transport, but is associated with the address by a router, the option for |
| 19311 | calling initgroups() is taken from the router configuration. |
| 19312 | |
| 19313 | The pipe transport contains the special option pipe_as_creator. If this is set |
| 19314 | and user is not set, the uid of the process that called Exim to receive the |
| 19315 | message is used, and if group is not set, the corresponding original gid is |
| 19316 | also used. |
| 19317 | |
| 19318 | This is the detailed preference order for obtaining a gid; the first of the |
| 19319 | following that is set is used: |
| 19320 | |
| 19321 | * A group setting of the transport; |
| 19322 | |
| 19323 | * A group setting of the router; |
| 19324 | |
| 19325 | * A gid associated with a user setting of the router, either as a result of |
| 19326 | check_local_user or an explicit non-numeric user setting; |
| 19327 | |
| 19328 | * The group associated with a non-numeric user setting of the transport; |
| 19329 | |
| 19330 | * In a pipe transport, the creator's gid if deliver_as_creator is set and the |
| 19331 | uid is the creator's uid; |
| 19332 | |
| 19333 | * The Exim gid if the Exim uid is being used as a default. |
| 19334 | |
| 19335 | If, for example, the user is specified numerically on the router and there are |
| 19336 | no group settings, no gid is available. In this situation, an error occurs. |
| 19337 | This is different for the uid, for which there always is an ultimate default. |
| 19338 | The first of the following that is set is used: |
| 19339 | |
| 19340 | * A user setting of the transport; |
| 19341 | |
| 19342 | * In a pipe transport, the creator's uid if deliver_as_creator is set; |
| 19343 | |
| 19344 | * A user setting of the router; |
| 19345 | |
| 19346 | * A check_local_user setting of the router; |
| 19347 | |
| 19348 | * The Exim uid. |
| 19349 | |
| 19350 | Of course, an error will still occur if the uid that is chosen is on the |
| 19351 | never_users list. |
| 19352 | |
| 19353 | |
| 19354 | 23.3 Current and home directories |
| 19355 | --------------------------------- |
| 19356 | |
| 19357 | Routers may set current and home directories for local transports by means of |
| 19358 | the transport_current_directory and transport_home_directory options. However, |
| 19359 | if the transport's current_directory or home_directory options are set, they |
| 19360 | override the router's values. In detail, the home directory for a local |
| 19361 | transport is taken from the first of these values that is set: |
| 19362 | |
| 19363 | * The home_directory option on the transport; |
| 19364 | |
| 19365 | * The transport_home_directory option on the router; |
| 19366 | |
| 19367 | * The password data if check_local_user is set on the router; |
| 19368 | |
| 19369 | * The router_home_directory option on the router. |
| 19370 | |
| 19371 | The current directory is taken from the first of these values that is set: |
| 19372 | |
| 19373 | * The current_directory option on the transport; |
| 19374 | |
| 19375 | * The transport_current_directory option on the router. |
| 19376 | |
| 19377 | If neither the router nor the transport sets a current directory, Exim uses the |
| 19378 | value of the home directory, if it is set. Otherwise it sets the current |
| 19379 | directory to / before running a local transport. |
| 19380 | |
| 19381 | |
| 19382 | 23.4 Expansion variables derived from the address |
| 19383 | ------------------------------------------------- |
| 19384 | |
| 19385 | Normally a local delivery is handling a single address, and in that case the |
| 19386 | variables such as $domain and $local_part are set during local deliveries. |
| 19387 | However, in some circumstances more than one address may be handled at once |
| 19388 | (for example, while writing batch SMTP for onward transmission by some other |
| 19389 | means). In this case, the variables associated with the local part are never |
| 19390 | set, $domain is set only if all the addresses have the same domain, and |
| 19391 | $original_domain is never set. |
| 19392 | |
| 19393 | |
| 19394 | |
| 19395 | =============================================================================== |
| 19396 | 24. GENERIC OPTIONS FOR TRANSPORTS |
| 19397 | |
| 19398 | The following generic options apply to all transports: |
| 19399 | |
| 19400 | +------------------------------------------------------+ |
| 19401 | |body_only|Use: transports|Type: boolean|Default: false| |
| 19402 | +------------------------------------------------------+ |
| 19403 | |
| 19404 | If this option is set, the message's headers are not transported. It is |
| 19405 | mutually exclusive with headers_only. If it is used with the appendfile or pipe |
| 19406 | transports, the settings of message_prefix and message_suffix should be |
| 19407 | checked, because this option does not automatically suppress them. |
| 19408 | |
| 19409 | +--------------------------------------------------------------+ |
| 19410 | |current_directory|Use: transports|Type: string*|Default: unset| |
| 19411 | +--------------------------------------------------------------+ |
| 19412 | |
| 19413 | This specifies the current directory that is to be set while running the |
| 19414 | transport, overriding any value that may have been set by the router. If the |
| 19415 | expansion fails for any reason, including forced failure, an error is logged, |
| 19416 | and delivery is deferred. |
| 19417 | |
| 19418 | +------------------------------------------------------------+ |
| 19419 | |disable_logging|Use: transports|Type: boolean|Default: false| |
| 19420 | +------------------------------------------------------------+ |
| 19421 | |
| 19422 | If this option is set true, nothing is logged for any deliveries by the |
| 19423 | transport or for any transport errors. You should not set this option unless |
| 19424 | you really, really know what you are doing. |
| 19425 | |
| 19426 | +--------------------------------------------------------+ |
| 19427 | |debug_print|Use: transports|Type: string*|Default: unset| |
| 19428 | +--------------------------------------------------------+ |
| 19429 | |
| 19430 | If this option is set and debugging is enabled (see the -d command line |
| 19431 | option), the string is expanded and included in the debugging output when the |
| 19432 | transport is run. If expansion of the string fails, the error message is |
| 19433 | written to the debugging output, and Exim carries on processing. This facility |
| 19434 | is provided to help with checking out the values of variables and so on when |
| 19435 | debugging driver configurations. For example, if a headers_add option is not |
| 19436 | working properly, debug_print could be used to output the variables it |
| 19437 | references. A newline is added to the text if it does not end with one. The |
| 19438 | variables $transport_name and $router_name contain the name of the transport |
| 19439 | and the router that called it. |
| 19440 | |
| 19441 | +--------------------------------------------------------------+ |
| 19442 | |delivery_date_add|Use: transports|Type: boolean|Default: false| |
| 19443 | +--------------------------------------------------------------+ |
| 19444 | |
| 19445 | If this option is true, a Delivery-date: header is added to the message. This |
| 19446 | gives the actual time the delivery was made. As this is not a standard header, |
| 19447 | Exim has a configuration option (delivery_date_remove) which requests its |
| 19448 | removal from incoming messages, so that delivered messages can safely be resent |
| 19449 | to other recipients. |
| 19450 | |
| 19451 | +--------------------------------------------------+ |
| 19452 | |driver|Use: transports|Type: string|Default: unset| |
| 19453 | +--------------------------------------------------+ |
| 19454 | |
| 19455 | This specifies which of the available transport drivers is to be used. There is |
| 19456 | no default, and this option must be set for every transport. |
| 19457 | |
| 19458 | +------------------------------------------------------------+ |
| 19459 | |envelope_to_add|Use: transports|Type: boolean|Default: false| |
| 19460 | +------------------------------------------------------------+ |
| 19461 | |
| 19462 | If this option is true, an Envelope-to: header is added to the message. This |
| 19463 | gives the original address(es) in the incoming envelope that caused this |
| 19464 | delivery to happen. More than one address may be present if the transport is |
| 19465 | configured to handle several addresses at once, or if more than one original |
| 19466 | address was redirected to the same final address. As this is not a standard |
| 19467 | header, Exim has a configuration option (envelope_to_remove) which requests its |
| 19468 | removal from incoming messages, so that delivered messages can safely be resent |
| 19469 | to other recipients. |
| 19470 | |
| 19471 | +---------------------------------------------------------+ |
| 19472 | |event_action|Use: transports|Type: string*|Default: unset| |
| 19473 | +---------------------------------------------------------+ |
| 19474 | |
| 19475 | This option declares a string to be expanded for Exim's events mechanism. For |
| 19476 | details see chapter 60. |
| 19477 | |
| 19478 | +-------------------------------------------------------+ |
| 19479 | |group|Use: transports|Type: string*|Default: Exim group| |
| 19480 | +-------------------------------------------------------+ |
| 19481 | |
| 19482 | This option specifies a gid for running the transport process, overriding any |
| 19483 | value that the router supplies, and also overriding any value associated with |
| 19484 | user (see below). |
| 19485 | |
| 19486 | +------------------------------------------------------+ |
| 19487 | |headers_add|Use: transports|Type: list*|Default: unset| |
| 19488 | +------------------------------------------------------+ |
| 19489 | |
| 19490 | This option specifies a list of text headers, newline-separated (by default, |
| 19491 | changeable in the usual way), which are (separately) expanded and added to the |
| 19492 | header portion of a message as it is transported, as described in section 47.17 |
| 19493 | . Additional header lines can also be specified by routers. If the result of |
| 19494 | the expansion is an empty string, or if the expansion is forced to fail, no |
| 19495 | action is taken. Other expansion failures are treated as errors and cause the |
| 19496 | delivery to be deferred. |
| 19497 | |
| 19498 | Unlike most options, headers_add can be specified multiple times for a |
| 19499 | transport; all listed headers are added. |
| 19500 | |
| 19501 | +---------------------------------------------------------+ |
| 19502 | |headers_only|Use: transports|Type: boolean|Default: false| |
| 19503 | +---------------------------------------------------------+ |
| 19504 | |
| 19505 | If this option is set, the message's body is not transported. It is mutually |
| 19506 | exclusive with body_only. If it is used with the appendfile or pipe transports, |
| 19507 | the settings of message_prefix and message_suffix should be checked, since this |
| 19508 | option does not automatically suppress them. |
| 19509 | |
| 19510 | +---------------------------------------------------------+ |
| 19511 | |headers_remove|Use: transports|Type: list*|Default: unset| |
| 19512 | +---------------------------------------------------------+ |
| 19513 | |
| 19514 | This option specifies a list of header names, colon-separated (by default, |
| 19515 | changeable in the usual way); these headers are omitted from the message as it |
| 19516 | is transported, as described in section 47.17. Header removal can also be |
| 19517 | specified by routers. Each list item is separately expanded. If the result of |
| 19518 | the expansion is an empty string, or if the expansion is forced to fail, no |
| 19519 | action is taken. Other expansion failures are treated as errors and cause the |
| 19520 | delivery to be deferred. |
| 19521 | |
| 19522 | Unlike most options, headers_remove can be specified multiple times for a |
| 19523 | transport; all listed headers are removed. |
| 19524 | |
| 19525 | Warning: Because of the separate expansion of the list items, items that |
| 19526 | contain a list separator must have it doubled. To avoid this, change the list |
| 19527 | separator (6.21). |
| 19528 | |
| 19529 | +-----------------------------------------------------------+ |
| 19530 | |headers_rewrite|Use: transports|Type: string|Default: unset| |
| 19531 | +-----------------------------------------------------------+ |
| 19532 | |
| 19533 | This option allows addresses in header lines to be rewritten at transport time, |
| 19534 | that is, as the message is being copied to its destination. The contents of the |
| 19535 | option are a colon-separated list of rewriting rules. Each rule is in exactly |
| 19536 | the same form as one of the general rewriting rules that are applied when a |
| 19537 | message is received. These are described in chapter 31. For example, |
| 19538 | |
| 19539 | headers_rewrite = a@b c@d f : \ |
| 19540 | x@y w@z |
| 19541 | |
| 19542 | changes a@b into c@d in From: header lines, and x@y into w@z in all |
| 19543 | address-bearing header lines. The rules are applied to the header lines just |
| 19544 | before they are written out at transport time, so they affect only those copies |
| 19545 | of the message that pass through the transport. However, only the message's |
| 19546 | original header lines, and any that were added by a system filter, are |
| 19547 | rewritten. If a router or transport adds header lines, they are not affected by |
| 19548 | this option. These rewriting rules are not applied to the envelope. You can |
| 19549 | change the return path using return_path, but you cannot change envelope |
| 19550 | recipients at this time. |
| 19551 | |
| 19552 | +-----------------------------------------------------------+ |
| 19553 | |home_directory|Use: transports|Type: string*|Default: unset| |
| 19554 | +-----------------------------------------------------------+ |
| 19555 | |
| 19556 | This option specifies a home directory setting for a local transport, |
| 19557 | overriding any value that may be set by the router. The home directory is |
| 19558 | placed in $home while expanding the transport's private options. It is also |
| 19559 | used as the current directory if no current directory is set by the |
| 19560 | current_directory option on the transport or the transport_current_directory |
| 19561 | option on the router. If the expansion fails for any reason, including forced |
| 19562 | failure, an error is logged, and delivery is deferred. |
| 19563 | |
| 19564 | +-------------------------------------------------------+ |
| 19565 | |initgroups|Use: transports|Type: boolean|Default: false| |
| 19566 | +-------------------------------------------------------+ |
| 19567 | |
| 19568 | If this option is true and the uid for the delivery process is provided by the |
| 19569 | transport, the initgroups() function is called when running the transport to |
| 19570 | ensure that any additional groups associated with the uid are set up. |
| 19571 | |
| 19572 | +----------------------------------------------------------+ |
| 19573 | |max_parallel|Use: transports|Type: integer*|Default: unset| |
| 19574 | +----------------------------------------------------------+ |
| 19575 | |
| 19576 | If this option is set and expands to an integer greater than zero it limits the |
| 19577 | number of concurrent runs of the transport. The control does not apply to |
| 19578 | shadow transports. |
| 19579 | |
| 19580 | Exim implements this control by means of a hints database in which a record is |
| 19581 | incremented whenever a transport process is being created. The record is |
| 19582 | decremented and possibly removed when the process terminates. Obviously there |
| 19583 | is scope for records to get left lying around if there is a system or program |
| 19584 | crash. To guard against this, Exim ignores any records that are more than six |
| 19585 | hours old. |
| 19586 | |
| 19587 | If you use this option, you should also arrange to delete the relevant hints |
| 19588 | database whenever your system reboots. The names of the files start with misc |
| 19589 | and they are kept in the spool/db directory. There may be one or two files, |
| 19590 | depending on the type of DBM in use. The same files are used for ETRN and smtp |
| 19591 | transport serialization. |
| 19592 | |
| 19593 | +-----------------------------------------------------------+ |
| 19594 | |message_size_limit|Use: transports|Type: string*|Default: 0| |
| 19595 | +-----------------------------------------------------------+ |
| 19596 | |
| 19597 | This option controls the size of messages passed through the transport. It is |
| 19598 | expanded before use; the result of the expansion must be a sequence of decimal |
| 19599 | digits, optionally followed by K or M. If the expansion fails for any reason, |
| 19600 | including forced failure, or if the result is not of the required form, |
| 19601 | delivery is deferred. If the value is greater than zero and the size of a |
| 19602 | message exceeds this limit, the address is failed. If there is any chance that |
| 19603 | the resulting bounce message could be routed to the same transport, you should |
| 19604 | ensure that return_size_limit is less than the transport's message_size_limit, |
| 19605 | as otherwise the bounce message will fail to get delivered. |
| 19606 | |
| 19607 | +-----------------------------------------------------------------+ |
| 19608 | |rcpt_include_affixes|Use: transports|Type: boolean|Default: false| |
| 19609 | +-----------------------------------------------------------------+ |
| 19610 | |
| 19611 | When this option is false (the default), and an address that has had any |
| 19612 | affixes (prefixes or suffixes) removed from the local part is delivered by any |
| 19613 | form of SMTP or LMTP, the affixes are not included. For example, if a router |
| 19614 | that contains |
| 19615 | |
| 19616 | local_part_prefix = *- |
| 19617 | |
| 19618 | routes the address abc-xyz@some.domain to an SMTP transport, the envelope is |
| 19619 | delivered with |
| 19620 | |
| 19621 | RCPT TO:<xyz@some.domain> |
| 19622 | |
| 19623 | This is also the case when an ACL-time callout is being used to verify a |
| 19624 | recipient address. However, if rcpt_include_affixes is set true, the whole |
| 19625 | local part is included in the RCPT command. This option applies to BSMTP |
| 19626 | deliveries by the appendfile and pipe transports as well as to the lmtp and |
| 19627 | smtp transports. |
| 19628 | |
| 19629 | +---------------------------------------------------------------------+ |
| 19630 | |retry_use_local_part|Use: transports|Type: boolean|Default: see below| |
| 19631 | +---------------------------------------------------------------------+ |
| 19632 | |
| 19633 | When a delivery suffers a temporary failure, a retry record is created in |
| 19634 | Exim's hints database. For remote deliveries, the key for the retry record is |
| 19635 | based on the name and/or IP address of the failing remote host. For local |
| 19636 | deliveries, the key is normally the entire address, including both the local |
| 19637 | part and the domain. This is suitable for most common cases of local delivery |
| 19638 | temporary failure - for example, exceeding a mailbox quota should delay only |
| 19639 | deliveries to that mailbox, not to the whole domain. |
| 19640 | |
| 19641 | However, in some special cases you may want to treat a temporary local delivery |
| 19642 | as a failure associated with the domain, and not with a particular local part. |
| 19643 | (For example, if you are storing all mail for some domain in files.) You can do |
| 19644 | this by setting retry_use_local_part false. |
| 19645 | |
| 19646 | For all the local transports, its default value is true. For remote transports, |
| 19647 | the default value is false for tidiness, but changing the value has no effect |
| 19648 | on a remote transport in the current implementation. |
| 19649 | |
| 19650 | +--------------------------------------------------------+ |
| 19651 | |return_path|Use: transports|Type: string*|Default: unset| |
| 19652 | +--------------------------------------------------------+ |
| 19653 | |
| 19654 | If this option is set, the string is expanded at transport time and replaces |
| 19655 | the existing return path (envelope sender) value in the copy of the message |
| 19656 | that is being delivered. An empty return path is permitted. This feature is |
| 19657 | designed for remote deliveries, where the value of this option is used in the |
| 19658 | SMTP MAIL command. If you set return_path for a local transport, the only |
| 19659 | effect is to change the address that is placed in the Return-path: header line, |
| 19660 | if one is added to the message (see the next option). |
| 19661 | |
| 19662 | Note: A changed return path is not logged unless you add |
| 19663 | return_path_on_delivery to the log selector. |
| 19664 | |
| 19665 | The expansion can refer to the existing value via $return_path. This is either |
| 19666 | the message's envelope sender, or an address set by the errors_to option on a |
| 19667 | router. If the expansion is forced to fail, no replacement occurs; if it fails |
| 19668 | for another reason, delivery is deferred. This option can be used to support |
| 19669 | VERP (Variable Envelope Return Paths) - see section 50.6. |
| 19670 | |
| 19671 | Note: If a delivery error is detected locally, including the case when a remote |
| 19672 | server rejects a message at SMTP time, the bounce message is not sent to the |
| 19673 | value of this option. It is sent to the previously set errors address. This |
| 19674 | defaults to the incoming sender address, but can be changed by setting |
| 19675 | errors_to in a router. |
| 19676 | |
| 19677 | +------------------------------------------------------------+ |
| 19678 | |return_path_add|Use: transports|Type: boolean|Default: false| |
| 19679 | +------------------------------------------------------------+ |
| 19680 | |
| 19681 | If this option is true, a Return-path: header is added to the message. Although |
| 19682 | the return path is normally available in the prefix line of BSD mailboxes, this |
| 19683 | is commonly not displayed by MUAs, and so the user does not have easy access to |
| 19684 | it. |
| 19685 | |
| 19686 | RFC 2821 states that the Return-path: header is added to a message "when the |
| 19687 | delivery SMTP server makes the final delivery". This implies that this header |
| 19688 | should not be present in incoming messages. Exim has a configuration option, |
| 19689 | return_path_remove, which requests removal of this header from incoming |
| 19690 | messages, so that delivered messages can safely be resent to other recipients. |
| 19691 | |
| 19692 | +-------------------------------------------------------------+ |
| 19693 | |shadow_condition|Use: transports|Type: string*|Default: unset| |
| 19694 | +-------------------------------------------------------------+ |
| 19695 | |
| 19696 | See shadow_transport below. |
| 19697 | |
| 19698 | +------------------------------------------------------------+ |
| 19699 | |shadow_transport|Use: transports|Type: string|Default: unset| |
| 19700 | +------------------------------------------------------------+ |
| 19701 | |
| 19702 | A local transport may set the shadow_transport option to the name of another |
| 19703 | local transport. Shadow remote transports are not supported. |
| 19704 | |
| 19705 | Whenever a delivery to the main transport succeeds, and either shadow_condition |
| 19706 | is unset, or its expansion does not result in the empty string or one of the |
| 19707 | strings "0" or "no" or "false", the message is also passed to the shadow |
| 19708 | transport, with the same delivery address or addresses. If expansion fails, no |
| 19709 | action is taken except that non-forced expansion failures cause a log line to |
| 19710 | be written. |
| 19711 | |
| 19712 | The result of the shadow transport is discarded and does not affect the |
| 19713 | subsequent processing of the message. Only a single level of shadowing is |
| 19714 | provided; the shadow_transport option is ignored on any transport when it is |
| 19715 | running as a shadow. Options concerned with output from pipes are also ignored. |
| 19716 | The log line for the successful delivery has an item added on the end, of the |
| 19717 | form |
| 19718 | |
| 19719 | ST=<shadow transport name> |
| 19720 | |
| 19721 | If the shadow transport did not succeed, the error message is put in |
| 19722 | parentheses afterwards. Shadow transports can be used for a number of different |
| 19723 | purposes, including keeping more detailed log information than Exim normally |
| 19724 | provides, and implementing automatic acknowledgment policies based on message |
| 19725 | headers that some sites insist on. |
| 19726 | |
| 19727 | +-------------------------------------------------------------+ |
| 19728 | |transport_filter|Use: transports|Type: string*|Default: unset| |
| 19729 | +-------------------------------------------------------------+ |
| 19730 | |
| 19731 | This option sets up a filtering (in the Unix shell sense) process for messages |
| 19732 | at transport time. It should not be confused with mail filtering as set up by |
| 19733 | individual users or via a system filter. If unset, or expanding to an empty |
| 19734 | string, no filtering is done. |
| 19735 | |
| 19736 | When the message is about to be written out, the command specified by |
| 19737 | transport_filter is started up in a separate, parallel process, and the entire |
| 19738 | message, including the header lines, is passed to it on its standard input |
| 19739 | (this in fact is done from a third process, to avoid deadlock). The command |
| 19740 | must be specified as an absolute path. |
| 19741 | |
| 19742 | The lines of the message that are written to the transport filter are |
| 19743 | terminated by newline ("\n"). The message is passed to the filter before any |
| 19744 | SMTP-specific processing, such as turning "\n" into "\r\n" and escaping lines |
| 19745 | beginning with a dot, and also before any processing implied by the settings of |
| 19746 | check_string and escape_string in the appendfile or pipe transports. |
| 19747 | |
| 19748 | The standard error for the filter process is set to the same destination as its |
| 19749 | standard output; this is read and written to the message's ultimate |
| 19750 | destination. The process that writes the message to the filter, the filter |
| 19751 | itself, and the original process that reads the result and delivers it are all |
| 19752 | run in parallel, like a shell pipeline. |
| 19753 | |
| 19754 | The filter can perform any transformations it likes, but of course should take |
| 19755 | care not to break RFC 2822 syntax. Exim does not check the result, except to |
| 19756 | test for a final newline when SMTP is in use. All messages transmitted over |
| 19757 | SMTP must end with a newline, so Exim supplies one if it is missing. |
| 19758 | |
| 19759 | A transport filter can be used to provide content-scanning on a per-user basis |
| 19760 | at delivery time if the only required effect of the scan is to modify the |
| 19761 | message. For example, a content scan could insert a new header line containing |
| 19762 | a spam score. This could be interpreted by a filter in the user's MUA. It is |
| 19763 | not possible to discard a message at this stage. |
| 19764 | |
| 19765 | A problem might arise if the filter increases the size of a message that is |
| 19766 | being sent down an SMTP connection. If the receiving SMTP server has indicated |
| 19767 | support for the SIZE parameter, Exim will have sent the size of the message at |
| 19768 | the start of the SMTP session. If what is actually sent is substantially more, |
| 19769 | the server might reject the message. This can be worked round by setting the |
| 19770 | size_addition option on the smtp transport, either to allow for additions to |
| 19771 | the message, or to disable the use of SIZE altogether. |
| 19772 | |
| 19773 | The value of the transport_filter option is the command string for starting the |
| 19774 | filter, which is run directly from Exim, not under a shell. The string is |
| 19775 | parsed by Exim in the same way as a command string for the pipe transport: Exim |
| 19776 | breaks it up into arguments and then expands each argument separately (see |
| 19777 | section 29.3). Any kind of expansion failure causes delivery to be deferred. |
| 19778 | The special argument $pipe_addresses is replaced by a number of arguments, one |
| 19779 | for each address that applies to this delivery. (This isn't an ideal name for |
| 19780 | this feature here, but as it was already implemented for the pipe transport, it |
| 19781 | seemed sensible not to change it.) |
| 19782 | |
| 19783 | The expansion variables $host and $host_address are available when the |
| 19784 | transport is a remote one. They contain the name and IP address of the host to |
| 19785 | which the message is being sent. For example: |
| 19786 | |
| 19787 | transport_filter = /some/directory/transport-filter.pl \ |
| 19788 | $host $host_address $sender_address $pipe_addresses |
| 19789 | |
| 19790 | Two problems arise if you want to use more complicated expansion items to |
| 19791 | generate transport filter commands, both of which due to the fact that the |
| 19792 | command is split up before expansion. |
| 19793 | |
| 19794 | * If an expansion item contains white space, you must quote it, so that it is |
| 19795 | all part of the same command item. If the entire option setting is one such |
| 19796 | expansion item, you have to take care what kind of quoting you use. For |
| 19797 | example: |
| 19798 | |
| 19799 | transport_filter = '/bin/cmd${if eq{$host}{a.b.c}{1}{2}}' |
| 19800 | |
| 19801 | This runs the command /bin/cmd1 if the host name is a.b.c, and /bin/cmd2 |
| 19802 | otherwise. If double quotes had been used, they would have been stripped by |
| 19803 | Exim when it read the option's value. When the value is used, if the single |
| 19804 | quotes were missing, the line would be split into two items, "/bin/cmd${if" |
| 19805 | and "eq{$host}{a.b.c}{1}{2}", and an error would occur when Exim tried to |
| 19806 | expand the first one. |
| 19807 | |
| 19808 | * Except for the special case of $pipe_addresses that is mentioned above, an |
| 19809 | expansion cannot generate multiple arguments, or a command name followed by |
| 19810 | arguments. Consider this example: |
| 19811 | |
| 19812 | transport_filter = ${lookup{$host}lsearch{/a/file}\ |
| 19813 | {$value}{/bin/cat}} |
| 19814 | |
| 19815 | The result of the lookup is interpreted as the name of the command, even if |
| 19816 | it contains white space. The simplest way round this is to use a shell: |
| 19817 | |
| 19818 | transport_filter = /bin/sh -c ${lookup{$host}lsearch{/a/file}\ |
| 19819 | {$value}{/bin/cat}} |
| 19820 | |
| 19821 | The filter process is run under the same uid and gid as the normal delivery. |
| 19822 | For remote deliveries this is the Exim uid/gid by default. The command should |
| 19823 | normally yield a zero return code. Transport filters are not supposed to fail. |
| 19824 | A non-zero code is taken to mean that the transport filter encountered some |
| 19825 | serious problem. Delivery of the message is deferred; the message remains on |
| 19826 | the queue and is tried again later. It is not possible to cause a message to be |
| 19827 | bounced from a transport filter. |
| 19828 | |
| 19829 | If a transport filter is set on an autoreply transport, the original message is |
| 19830 | passed through the filter as it is being copied into the newly generated |
| 19831 | message, which happens if the return_message option is set. |
| 19832 | |
| 19833 | +---------------------------------------------------------------+ |
| 19834 | |transport_filter_timeout|Use: transports|Type: time|Default: 5m| |
| 19835 | +---------------------------------------------------------------+ |
| 19836 | |
| 19837 | When Exim is reading the output of a transport filter, it applies a timeout |
| 19838 | that can be set by this option. Exceeding the timeout is normally treated as a |
| 19839 | temporary delivery failure. However, if a transport filter is used with a pipe |
| 19840 | transport, a timeout in the transport filter is treated in the same way as a |
| 19841 | timeout in the pipe command itself. By default, a timeout is a hard error, but |
| 19842 | if the pipe transport's timeout_defer option is set true, it becomes a |
| 19843 | temporary error. |
| 19844 | |
| 19845 | +-----------------------------------------------------+ |
| 19846 | |user|Use: transports|Type: string*|Default: Exim user| |
| 19847 | +-----------------------------------------------------+ |
| 19848 | |
| 19849 | This option specifies the user under whose uid the delivery process is to be |
| 19850 | run, overriding any uid that may have been set by the router. If the user is |
| 19851 | given as a name, the uid is looked up from the password data, and the |
| 19852 | associated group is taken as the value of the gid to be used if the group |
| 19853 | option is not set. |
| 19854 | |
| 19855 | For deliveries that use local transports, a user and group are normally |
| 19856 | specified explicitly or implicitly (for example, as a result of |
| 19857 | check_local_user) by the router or transport. |
| 19858 | |
| 19859 | For remote transports, you should leave this option unset unless you really are |
| 19860 | sure you know what you are doing. When a remote transport is running, it needs |
| 19861 | to be able to access Exim's hints databases, because each host may have its own |
| 19862 | retry data. |
| 19863 | |
| 19864 | |
| 19865 | |
| 19866 | =============================================================================== |
| 19867 | 25. ADDRESS BATCHING IN LOCAL TRANSPORTS |
| 19868 | |
| 19869 | The only remote transport (smtp) is normally configured to handle more than one |
| 19870 | address at a time, so that when several addresses are routed to the same remote |
| 19871 | host, just one copy of the message is sent. Local transports, however, normally |
| 19872 | handle one address at a time. That is, a separate instance of the transport is |
| 19873 | run for each address that is routed to the transport. A separate copy of the |
| 19874 | message is delivered each time. |
| 19875 | |
| 19876 | In special cases, it may be desirable to handle several addresses at once in a |
| 19877 | local transport, for example: |
| 19878 | |
| 19879 | * In an appendfile transport, when storing messages in files for later |
| 19880 | delivery by some other means, a single copy of the message with multiple |
| 19881 | recipients saves space. |
| 19882 | |
| 19883 | * In an lmtp transport, when delivering over "local SMTP" to some process, a |
| 19884 | single copy saves time, and is the normal way LMTP is expected to work. |
| 19885 | |
| 19886 | * In a pipe transport, when passing the message to a scanner program or to |
| 19887 | some other delivery mechanism such as UUCP, multiple recipients may be |
| 19888 | acceptable. |
| 19889 | |
| 19890 | These three local transports all have the same options for controlling multiple |
| 19891 | ("batched") deliveries, namely batch_max and batch_id. To save repeating the |
| 19892 | information for each transport, these options are described here. |
| 19893 | |
| 19894 | The batch_max option specifies the maximum number of addresses that can be |
| 19895 | delivered together in a single run of the transport. Its default value is one |
| 19896 | (no batching). When more than one address is routed to a transport that has a |
| 19897 | batch_max value greater than one, the addresses are delivered in a batch (that |
| 19898 | is, in a single run of the transport with multiple recipients), subject to |
| 19899 | certain conditions: |
| 19900 | |
| 19901 | * If any of the transport's options contain a reference to $local_part, no |
| 19902 | batching is possible. |
| 19903 | |
| 19904 | * If any of the transport's options contain a reference to $domain, only |
| 19905 | addresses with the same domain are batched. |
| 19906 | |
| 19907 | * If batch_id is set, it is expanded for each address, and only those |
| 19908 | addresses with the same expanded value are batched. This allows you to |
| 19909 | specify customized batching conditions. Failure of the expansion for any |
| 19910 | reason, including forced failure, disables batching, but it does not stop |
| 19911 | the delivery from taking place. |
| 19912 | |
| 19913 | * Batched addresses must also have the same errors address (where to send |
| 19914 | delivery errors), the same header additions and removals, the same user and |
| 19915 | group for the transport, and if a host list is present, the first host must |
| 19916 | be the same. |
| 19917 | |
| 19918 | In the case of the appendfile and pipe transports, batching applies both when |
| 19919 | the file or pipe command is specified in the transport, and when it is |
| 19920 | specified by a redirect router, but all the batched addresses must of course be |
| 19921 | routed to the same file or pipe command. These two transports have an option |
| 19922 | called use_bsmtp, which causes them to deliver the message in "batched SMTP" |
| 19923 | format, with the envelope represented as SMTP commands. The check_string and |
| 19924 | escape_string options are forced to the values |
| 19925 | |
| 19926 | check_string = "." |
| 19927 | escape_string = ".." |
| 19928 | |
| 19929 | when batched SMTP is in use. A full description of the batch SMTP mechanism is |
| 19930 | given in section 48.10. The lmtp transport does not have a use_bsmtp option, |
| 19931 | because it always delivers using the SMTP protocol. |
| 19932 | |
| 19933 | If the generic envelope_to_add option is set for a batching transport, the |
| 19934 | Envelope-to: header that is added to the message contains all the addresses |
| 19935 | that are being processed together. If you are using a batching appendfile |
| 19936 | transport without use_bsmtp, the only way to preserve the recipient addresses |
| 19937 | is to set the envelope_to_add option. |
| 19938 | |
| 19939 | If you are using a pipe transport without BSMTP, and setting the transport's |
| 19940 | command option, you can include $pipe_addresses as part of the command. This is |
| 19941 | not a true variable; it is a bit of magic that causes each of the recipient |
| 19942 | addresses to be inserted into the command as a separate argument. This provides |
| 19943 | a way of accessing all the addresses that are being delivered in the batch. |
| 19944 | Note: This is not possible for pipe commands that are specified by a redirect |
| 19945 | router. |
| 19946 | |
| 19947 | |
| 19948 | |
| 19949 | =============================================================================== |
| 19950 | 26. THE APPENDFILE TRANSPORT |
| 19951 | |
| 19952 | The appendfile transport delivers a message by appending it to an existing |
| 19953 | file, or by creating an entirely new file in a specified directory. Single |
| 19954 | files to which messages are appended can be in the traditional Unix mailbox |
| 19955 | format, or optionally in the MBX format supported by the Pine MUA and |
| 19956 | University of Washington IMAP daemon, inter alia. When each message is being |
| 19957 | delivered as a separate file, "maildir" format can optionally be used to give |
| 19958 | added protection against failures that happen part-way through the delivery. A |
| 19959 | third form of separate-file delivery known as "mailstore" is also supported. |
| 19960 | For all file formats, Exim attempts to create as many levels of directory as |
| 19961 | necessary, provided that create_directory is set. |
| 19962 | |
| 19963 | The code for the optional formats is not included in the Exim binary by |
| 19964 | default. It is necessary to set SUPPORT_MBX, SUPPORT_MAILDIR and/or |
| 19965 | SUPPORT_MAILSTORE in Local/Makefile to have the appropriate code included. |
| 19966 | |
| 19967 | Exim recognizes system quota errors, and generates an appropriate message. Exim |
| 19968 | also supports its own quota control within the transport, for use when the |
| 19969 | system facility is unavailable or cannot be used for some reason. |
| 19970 | |
| 19971 | If there is an error while appending to a file (for example, quota exceeded or |
| 19972 | partition filled), Exim attempts to reset the file's length and last |
| 19973 | modification time back to what they were before. If there is an error while |
| 19974 | creating an entirely new file, the new file is removed. |
| 19975 | |
| 19976 | Before appending to a file, a number of security checks are made, and the file |
| 19977 | is locked. A detailed description is given below, after the list of private |
| 19978 | options. |
| 19979 | |
| 19980 | The appendfile transport is most commonly used for local deliveries to users' |
| 19981 | mailboxes. However, it can also be used as a pseudo-remote transport for |
| 19982 | putting messages into files for remote delivery by some means other than Exim. |
| 19983 | "Batch SMTP" format is often used in this case (see the use_bsmtp option). |
| 19984 | |
| 19985 | |
| 19986 | 26.1 The file and directory options |
| 19987 | ----------------------------------- |
| 19988 | |
| 19989 | The file option specifies a single file, to which the message is appended; the |
| 19990 | directory option specifies a directory, in which a new file containing the |
| 19991 | message is created. Only one of these two options can be set, and for normal |
| 19992 | deliveries to mailboxes, one of them must be set. |
| 19993 | |
| 19994 | However, appendfile is also used for delivering messages to files or |
| 19995 | directories whose names (or parts of names) are obtained from alias, |
| 19996 | forwarding, or filtering operations (for example, a save command in a user's |
| 19997 | Exim filter). When such a transport is running, $local_part contains the local |
| 19998 | part that was aliased or forwarded, and $address_file contains the name (or |
| 19999 | partial name) of the file or directory generated by the redirection operation. |
| 20000 | There are two cases: |
| 20001 | |
| 20002 | * If neither file nor directory is set, the redirection operation must |
| 20003 | specify an absolute path (one that begins with "/"). This is the most |
| 20004 | common case when users with local accounts use filtering to sort mail into |
| 20005 | different folders. See for example, the address_file transport in the |
| 20006 | default configuration. If the path ends with a slash, it is assumed to be |
| 20007 | the name of a directory. A delivery to a directory can also be forced by |
| 20008 | setting maildir_format or mailstore_format. |
| 20009 | |
| 20010 | * If file or directory is set for a delivery from a redirection, it is used |
| 20011 | to determine the file or directory name for the delivery. Normally, the |
| 20012 | contents of $address_file are used in some way in the string expansion. |
| 20013 | |
| 20014 | As an example of the second case, consider an environment where users do not |
| 20015 | have home directories. They may be permitted to use Exim filter commands of the |
| 20016 | form: |
| 20017 | |
| 20018 | save folder23 |
| 20019 | |
| 20020 | or Sieve filter commands of the form: |
| 20021 | |
| 20022 | require "fileinto"; |
| 20023 | fileinto "folder23"; |
| 20024 | |
| 20025 | In this situation, the expansion of file or directory in the transport must |
| 20026 | transform the relative path into an appropriate absolute file name. In the case |
| 20027 | of Sieve filters, the name inbox must be handled. It is the name that is used |
| 20028 | as a result of a "keep" action in the filter. This example shows one way of |
| 20029 | handling this requirement: |
| 20030 | |
| 20031 | file = ${if eq{$address_file}{inbox} \ |
| 20032 | {/var/mail/$local_part} \ |
| 20033 | {${if eq{${substr_0_1:$address_file}}{/} \ |
| 20034 | {$address_file} \ |
| 20035 | {$home/mail/$address_file} \ |
| 20036 | }} \ |
| 20037 | } |
| 20038 | |
| 20039 | With this setting of file, inbox refers to the standard mailbox location, |
| 20040 | absolute paths are used without change, and other folders are in the mail |
| 20041 | directory within the home directory. |
| 20042 | |
| 20043 | Note 1: While processing an Exim filter, a relative path such as folder23 is |
| 20044 | turned into an absolute path if a home directory is known to the router. In |
| 20045 | particular, this is the case if check_local_user is set. If you want to prevent |
| 20046 | this happening at routing time, you can set router_home_directory empty. This |
| 20047 | forces the router to pass the relative path to the transport. |
| 20048 | |
| 20049 | Note 2: An absolute path in $address_file is not treated specially; the file or |
| 20050 | directory option is still used if it is set. |
| 20051 | |
| 20052 | |
| 20053 | 26.2 Private options for appendfile |
| 20054 | ----------------------------------- |
| 20055 | |
| 20056 | +-------------------------------------------------------+ |
| 20057 | |allow_fifo|Use: appendfile|Type: boolean|Default: false| |
| 20058 | +-------------------------------------------------------+ |
| 20059 | |
| 20060 | Setting this option permits delivery to named pipes (FIFOs) as well as to |
| 20061 | regular files. If no process is reading the named pipe at delivery time, the |
| 20062 | delivery is deferred. |
| 20063 | |
| 20064 | +----------------------------------------------------------+ |
| 20065 | |allow_symlink|Use: appendfile|Type: boolean|Default: false| |
| 20066 | +----------------------------------------------------------+ |
| 20067 | |
| 20068 | By default, appendfile will not deliver if the path name for the file is that |
| 20069 | of a symbolic link. Setting this option relaxes that constraint, but there are |
| 20070 | security issues involved in the use of symbolic links. Be sure you know what |
| 20071 | you are doing if you set this. Details of exactly what this option affects are |
| 20072 | included in the discussion which follows this list of options. |
| 20073 | |
| 20074 | +-----------------------------------------------------+ |
| 20075 | |batch_id|Use: appendfile|Type: string*|Default: unset| |
| 20076 | +-----------------------------------------------------+ |
| 20077 | |
| 20078 | See the description of local delivery batching in chapter 25. However, batching |
| 20079 | is automatically disabled for appendfile deliveries that happen as a result of |
| 20080 | forwarding or aliasing or other redirection directly to a file. |
| 20081 | |
| 20082 | +--------------------------------------------------+ |
| 20083 | |batch_max|Use: appendfile|Type: integer|Default: 1| |
| 20084 | +--------------------------------------------------+ |
| 20085 | |
| 20086 | See the description of local delivery batching in chapter 25. |
| 20087 | |
| 20088 | +--------------------------------------------------------+ |
| 20089 | |check_group|Use: appendfile|Type: boolean|Default: false| |
| 20090 | +--------------------------------------------------------+ |
| 20091 | |
| 20092 | When this option is set, the group owner of the file defined by the file option |
| 20093 | is checked to see that it is the same as the group under which the delivery |
| 20094 | process is running. The default setting is false because the default file mode |
| 20095 | is 0600, which means that the group is irrelevant. |
| 20096 | |
| 20097 | +-------------------------------------------------------+ |
| 20098 | |check_owner|Use: appendfile|Type: boolean|Default: true| |
| 20099 | +-------------------------------------------------------+ |
| 20100 | |
| 20101 | When this option is set, the owner of the file defined by the file option is |
| 20102 | checked to ensure that it is the same as the user under which the delivery |
| 20103 | process is running. |
| 20104 | |
| 20105 | +------------------------------------------------------------+ |
| 20106 | |check_string|Use: appendfile|Type: string|Default: see below| |
| 20107 | +------------------------------------------------------------+ |
| 20108 | |
| 20109 | As appendfile writes the message, the start of each line is tested for matching |
| 20110 | check_string, and if it does, the initial matching characters are replaced by |
| 20111 | the contents of escape_string. The value of check_string is a literal string, |
| 20112 | not a regular expression, and the case of any letters it contains is |
| 20113 | significant. |
| 20114 | |
| 20115 | If use_bsmtp is set the values of check_string and escape_string are forced to |
| 20116 | "." and ".." respectively, and any settings in the configuration are ignored. |
| 20117 | Otherwise, they default to "From " and ">From " when the file option is set, |
| 20118 | and unset when any of the directory, maildir, or mailstore options are set. |
| 20119 | |
| 20120 | The default settings, along with message_prefix and message_suffix, are |
| 20121 | suitable for traditional "BSD" mailboxes, where a line beginning with "From " |
| 20122 | indicates the start of a new message. All four options need changing if another |
| 20123 | format is used. For example, to deliver to mailboxes in MMDF format: |
| 20124 | |
| 20125 | check_string = "\1\1\1\1\n" |
| 20126 | escape_string = "\1\1\1\1 \n" |
| 20127 | message_prefix = "\1\1\1\1\n" |
| 20128 | message_suffix = "\1\1\1\1\n" |
| 20129 | |
| 20130 | +------------------------------------------------------------+ |
| 20131 | |create_directory|Use: appendfile|Type: boolean|Default: true| |
| 20132 | +------------------------------------------------------------+ |
| 20133 | |
| 20134 | When this option is true, Exim attempts to create any missing superior |
| 20135 | directories for the file that it is about to write. A created directory's mode |
| 20136 | is given by the directory_mode option. |
| 20137 | |
| 20138 | The group ownership of a newly created directory is highly dependent on the |
| 20139 | operating system (and possibly the file system) that is being used. For |
| 20140 | example, in Solaris, if the parent directory has the setgid bit set, its group |
| 20141 | is propagated to the child; if not, the currently set group is used. However, |
| 20142 | in FreeBSD, the parent's group is always used. |
| 20143 | |
| 20144 | +----------------------------------------------------------+ |
| 20145 | |create_file|Use: appendfile|Type: string|Default: anywhere| |
| 20146 | +----------------------------------------------------------+ |
| 20147 | |
| 20148 | This option constrains the location of files and directories that are created |
| 20149 | by this transport. It applies to files defined by the file option and |
| 20150 | directories defined by the directory option. In the case of maildir delivery, |
| 20151 | it applies to the top level directory, not the maildir directories beneath. |
| 20152 | |
| 20153 | The option must be set to one of the words "anywhere", "inhome", or |
| 20154 | "belowhome". In the second and third cases, a home directory must have been set |
| 20155 | for the transport. This option is not useful when an explicit file name is |
| 20156 | given for normal mailbox deliveries. It is intended for the case when file |
| 20157 | names are generated from users' .forward files. These are usually handled by an |
| 20158 | appendfile transport called address_file. See also file_must_exist. |
| 20159 | |
| 20160 | +------------------------------------------------------+ |
| 20161 | |directory|Use: appendfile|Type: string*|Default: unset| |
| 20162 | +------------------------------------------------------+ |
| 20163 | |
| 20164 | This option is mutually exclusive with the file option, but one of file or |
| 20165 | directory must be set, unless the delivery is the direct result of a |
| 20166 | redirection (see section 26.1). |
| 20167 | |
| 20168 | When directory is set, the string is expanded, and the message is delivered |
| 20169 | into a new file or files in or below the given directory, instead of being |
| 20170 | appended to a single mailbox file. A number of different formats are provided |
| 20171 | (see maildir_format and mailstore_format), and see section 26.4 for further |
| 20172 | details of this form of delivery. |
| 20173 | |
| 20174 | +---------------------------------------------------------------+ |
| 20175 | |directory_file|Use: appendfile|Type: string*|Default: see below| |
| 20176 | +---------------------------------------------------------------+ |
| 20177 | |
| 20178 | When directory is set, but neither maildir_format nor mailstore_format is set, |
| 20179 | appendfile delivers each message into a file whose name is obtained by |
| 20180 | expanding this string. The default value is: |
| 20181 | |
| 20182 | q${base62:$tod_epoch}-$inode |
| 20183 | |
| 20184 | This generates a unique name from the current time, in base 62 form, and the |
| 20185 | inode of the file. The variable $inode is available only when expanding this |
| 20186 | option. |
| 20187 | |
| 20188 | +----------------------------------------------------------------+ |
| 20189 | |directory_mode|Use: appendfile|Type: octal integer|Default: 0700| |
| 20190 | +----------------------------------------------------------------+ |
| 20191 | |
| 20192 | If appendfile creates any directories as a result of the create_directory |
| 20193 | option, their mode is specified by this option. |
| 20194 | |
| 20195 | +-------------------------------------------------------------------+ |
| 20196 | |escape_string|Use: appendfile|Type: string|Default: see description| |
| 20197 | +-------------------------------------------------------------------+ |
| 20198 | |
| 20199 | See check_string above. |
| 20200 | |
| 20201 | +-------------------------------------------------+ |
| 20202 | |file|Use: appendfile|Type: string*|Default: unset| |
| 20203 | +-------------------------------------------------+ |
| 20204 | |
| 20205 | This option is mutually exclusive with the directory option, but one of file or |
| 20206 | directory must be set, unless the delivery is the direct result of a |
| 20207 | redirection (see section 26.1). The file option specifies a single file, to |
| 20208 | which the message is appended. One or more of use_fcntl_lock, use_flock_lock, |
| 20209 | or use_lockfile must be set with file. |
| 20210 | |
| 20211 | If you are using more than one host to deliver over NFS into the same |
| 20212 | mailboxes, you should always use lock files. |
| 20213 | |
| 20214 | The string value is expanded for each delivery, and must yield an absolute |
| 20215 | path. The most common settings of this option are variations on one of these |
| 20216 | examples: |
| 20217 | |
| 20218 | file = /var/spool/mail/$local_part |
| 20219 | file = /home/$local_part/inbox |
| 20220 | file = $home/inbox |
| 20221 | |
| 20222 | In the first example, all deliveries are done into the same directory. If Exim |
| 20223 | is configured to use lock files (see use_lockfile below) it must be able to |
| 20224 | create a file in the directory, so the "sticky" bit must be turned on for |
| 20225 | deliveries to be possible, or alternatively the group option can be used to run |
| 20226 | the delivery under a group id which has write access to the directory. |
| 20227 | |
| 20228 | +-------------------------------------------------------+ |
| 20229 | |file_format|Use: appendfile|Type: string|Default: unset| |
| 20230 | +-------------------------------------------------------+ |
| 20231 | |
| 20232 | This option requests the transport to check the format of an existing file |
| 20233 | before adding to it. The check consists of matching a specific string at the |
| 20234 | start of the file. The value of the option consists of an even number of |
| 20235 | colon-separated strings. The first of each pair is the test string, and the |
| 20236 | second is the name of a transport. If the transport associated with a matched |
| 20237 | string is not the current transport, control is passed over to the other |
| 20238 | transport. For example, suppose the standard local_delivery transport has this |
| 20239 | added to it: |
| 20240 | |
| 20241 | file_format = "From : local_delivery :\ |
| 20242 | \1\1\1\1\n : local_mmdf_delivery" |
| 20243 | |
| 20244 | Mailboxes that begin with "From" are still handled by this transport, but if a |
| 20245 | mailbox begins with four binary ones followed by a newline, control is passed |
| 20246 | to a transport called local_mmdf_delivery, which presumably is configured to do |
| 20247 | the delivery in MMDF format. If a mailbox does not exist or is empty, it is |
| 20248 | assumed to match the current transport. If the start of a mailbox doesn't match |
| 20249 | any string, or if the transport named for a given string is not defined, |
| 20250 | delivery is deferred. |
| 20251 | |
| 20252 | +------------------------------------------------------------+ |
| 20253 | |file_must_exist|Use: appendfile|Type: boolean|Default: false| |
| 20254 | +------------------------------------------------------------+ |
| 20255 | |
| 20256 | If this option is true, the file specified by the file option must exist. A |
| 20257 | temporary error occurs if it does not, causing delivery to be deferred. If this |
| 20258 | option is false, the file is created if it does not exist. |
| 20259 | |
| 20260 | +---------------------------------------------------------+ |
| 20261 | |lock_fcntl_timeout|Use: appendfile|Type: time|Default: 0s| |
| 20262 | +---------------------------------------------------------+ |
| 20263 | |
| 20264 | By default, the appendfile transport uses non-blocking calls to fcntl() when |
| 20265 | locking an open mailbox file. If the call fails, the delivery process sleeps |
| 20266 | for lock_interval and tries again, up to lock_retries times. Non-blocking calls |
| 20267 | are used so that the file is not kept open during the wait for the lock; the |
| 20268 | reason for this is to make it as safe as possible for deliveries over NFS in |
| 20269 | the case when processes might be accessing an NFS mailbox without using a lock |
| 20270 | file. This should not be done, but misunderstandings and hence |
| 20271 | misconfigurations are not unknown. |
| 20272 | |
| 20273 | On a busy system, however, the performance of a non-blocking lock approach is |
| 20274 | not as good as using a blocking lock with a timeout. In this case, the waiting |
| 20275 | is done inside the system call, and Exim's delivery process acquires the lock |
| 20276 | and can proceed as soon as the previous lock holder releases it. |
| 20277 | |
| 20278 | If lock_fcntl_timeout is set to a non-zero time, blocking locks, with that |
| 20279 | timeout, are used. There may still be some retrying: the maximum number of |
| 20280 | retries is |
| 20281 | |
| 20282 | (lock_retries * lock_interval) / lock_fcntl_timeout |
| 20283 | |
| 20284 | rounded up to the next whole number. In other words, the total time during |
| 20285 | which appendfile is trying to get a lock is roughly the same, unless |
| 20286 | lock_fcntl_timeout is set very large. |
| 20287 | |
| 20288 | You should consider setting this option if you are getting a lot of delayed |
| 20289 | local deliveries because of errors of the form |
| 20290 | |
| 20291 | failed to lock mailbox /some/file (fcntl) |
| 20292 | |
| 20293 | +---------------------------------------------------------+ |
| 20294 | |lock_flock_timeout|Use: appendfile|Type: time|Default: 0s| |
| 20295 | +---------------------------------------------------------+ |
| 20296 | |
| 20297 | This timeout applies to file locking when using flock() (see use_flock); the |
| 20298 | timeout operates in a similar manner to lock_fcntl_timeout. |
| 20299 | |
| 20300 | +----------------------------------------------------+ |
| 20301 | |lock_interval|Use: appendfile|Type: time|Default: 3s| |
| 20302 | +----------------------------------------------------+ |
| 20303 | |
| 20304 | This specifies the time to wait between attempts to lock the file. See below |
| 20305 | for details of locking. |
| 20306 | |
| 20307 | +------------------------------------------------------+ |
| 20308 | |lock_retries|Use: appendfile|Type: integer|Default: 10| |
| 20309 | +------------------------------------------------------+ |
| 20310 | |
| 20311 | This specifies the maximum number of attempts to lock the file. A value of zero |
| 20312 | is treated as 1. See below for details of locking. |
| 20313 | |
| 20314 | +---------------------------------------------------------------+ |
| 20315 | |lockfile_mode|Use: appendfile|Type: octal integer|Default: 0600| |
| 20316 | +---------------------------------------------------------------+ |
| 20317 | |
| 20318 | This specifies the mode of the created lock file, when a lock file is being |
| 20319 | used (see use_lockfile and use_mbx_lock). |
| 20320 | |
| 20321 | +--------------------------------------------------------+ |
| 20322 | |lockfile_timeout|Use: appendfile|Type: time|Default: 30m| |
| 20323 | +--------------------------------------------------------+ |
| 20324 | |
| 20325 | When a lock file is being used (see use_lockfile), if a lock file already |
| 20326 | exists and is older than this value, it is assumed to have been left behind by |
| 20327 | accident, and Exim attempts to remove it. |
| 20328 | |
| 20329 | +--------------------------------------------------------------+ |
| 20330 | |mailbox_filecount|Use: appendfile|Type: string*|Default: unset| |
| 20331 | +--------------------------------------------------------------+ |
| 20332 | |
| 20333 | If this option is set, it is expanded, and the result is taken as the current |
| 20334 | number of files in the mailbox. It must be a decimal number, optionally |
| 20335 | followed by K or M. This provides a way of obtaining this information from an |
| 20336 | external source that maintains the data. |
| 20337 | |
| 20338 | +---------------------------------------------------------+ |
| 20339 | |mailbox_size|Use: appendfile|Type: string*|Default: unset| |
| 20340 | +---------------------------------------------------------+ |
| 20341 | |
| 20342 | If this option is set, it is expanded, and the result is taken as the current |
| 20343 | size the mailbox. It must be a decimal number, optionally followed by K or M. |
| 20344 | This provides a way of obtaining this information from an external source that |
| 20345 | maintains the data. This is likely to be helpful for maildir deliveries where |
| 20346 | it is computationally expensive to compute the size of a mailbox. |
| 20347 | |
| 20348 | +-----------------------------------------------------------+ |
| 20349 | |maildir_format|Use: appendfile|Type: boolean|Default: false| |
| 20350 | +-----------------------------------------------------------+ |
| 20351 | |
| 20352 | If this option is set with the directory option, the delivery is into a new |
| 20353 | file, in the "maildir" format that is used by other mail software. When the |
| 20354 | transport is activated directly from a redirect router (for example, the |
| 20355 | address_file transport in the default configuration), setting maildir_format |
| 20356 | causes the path received from the router to be treated as a directory, whether |
| 20357 | or not it ends with "/". This option is available only if SUPPORT_MAILDIR is |
| 20358 | present in Local/Makefile. See section 26.5 below for further details. |
| 20359 | |
| 20360 | +-----------------------------------------------------------------------------+ |
| 20361 | |maildir_quota_directory_regex|Use: appendfile|Type: string|Default: See below| |
| 20362 | +-----------------------------------------------------------------------------+ |
| 20363 | |
| 20364 | This option is relevant only when maildir_use_size_file is set. It defines a |
| 20365 | regular expression for specifying directories, relative to the quota directory |
| 20366 | (see quota_directory), that should be included in the quota calculation. The |
| 20367 | default value is: |
| 20368 | |
| 20369 | maildir_quota_directory_regex = ^(?:cur|new|\..*)$ |
| 20370 | |
| 20371 | This includes the cur and new directories, and any maildir++ folders |
| 20372 | (directories whose names begin with a dot). If you want to exclude the Trash |
| 20373 | folder from the count (as some sites do), you need to change this setting to |
| 20374 | |
| 20375 | maildir_quota_directory_regex = ^(?:cur|new|\.(?!Trash).*)$ |
| 20376 | |
| 20377 | This uses a negative lookahead in the regular expression to exclude the |
| 20378 | directory whose name is .Trash. When a directory is excluded from quota |
| 20379 | calculations, quota processing is bypassed for any messages that are delivered |
| 20380 | directly into that directory. |
| 20381 | |
| 20382 | +---------------------------------------------------------+ |
| 20383 | |maildir_retries|Use: appendfile|Type: integer|Default: 10| |
| 20384 | +---------------------------------------------------------+ |
| 20385 | |
| 20386 | This option specifies the number of times to retry when writing a file in |
| 20387 | "maildir" format. See section 26.5 below. |
| 20388 | |
| 20389 | +--------------------------------------------------------+ |
| 20390 | |maildir_tag|Use: appendfile|Type: string*|Default: unset| |
| 20391 | +--------------------------------------------------------+ |
| 20392 | |
| 20393 | This option applies only to deliveries in maildir format, and is described in |
| 20394 | section 26.5 below. |
| 20395 | |
| 20396 | +-------------------------------------------------------------------+ |
| 20397 | |maildir_use_size_file|Use: appendfile*|Type: boolean|Default: false| |
| 20398 | +-------------------------------------------------------------------+ |
| 20399 | |
| 20400 | The result of string expansion for this option must be a valid boolean value. |
| 20401 | If it is true, it enables support for maildirsize files. Exim creates a |
| 20402 | maildirsize file in a maildir if one does not exist, taking the quota from the |
| 20403 | quota option of the transport. If quota is unset, the value is zero. See |
| 20404 | maildir_quota_directory_regex above and section 26.5 below for further details. |
| 20405 | |
| 20406 | +----------------------------------------------------------------------+ |
| 20407 | |maildirfolder_create_regex|Use: appendfile|Type: string|Default: unset| |
| 20408 | +----------------------------------------------------------------------+ |
| 20409 | |
| 20410 | The value of this option is a regular expression. If it is unset, it has no |
| 20411 | effect. Otherwise, before a maildir delivery takes place, the pattern is |
| 20412 | matched against the name of the maildir directory, that is, the directory |
| 20413 | containing the new and tmp subdirectories that will be used for the delivery. |
| 20414 | If there is a match, Exim checks for the existence of a file called |
| 20415 | maildirfolder in the directory, and creates it if it does not exist. See |
| 20416 | section 26.5 for more details. |
| 20417 | |
| 20418 | +-------------------------------------------------------------+ |
| 20419 | |mailstore_format|Use: appendfile|Type: boolean|Default: false| |
| 20420 | +-------------------------------------------------------------+ |
| 20421 | |
| 20422 | If this option is set with the directory option, the delivery is into two new |
| 20423 | files in "mailstore" format. The option is available only if SUPPORT_MAILSTORE |
| 20424 | is present in Local/Makefile. See section 26.4 below for further details. |
| 20425 | |
| 20426 | +-------------------------------------------------------------+ |
| 20427 | |mailstore_prefix|Use: appendfile|Type: string*|Default: unset| |
| 20428 | +-------------------------------------------------------------+ |
| 20429 | |
| 20430 | This option applies only to deliveries in mailstore format, and is described in |
| 20431 | section 26.4 below. |
| 20432 | |
| 20433 | +-------------------------------------------------------------+ |
| 20434 | |mailstore_suffix|Use: appendfile|Type: string*|Default: unset| |
| 20435 | +-------------------------------------------------------------+ |
| 20436 | |
| 20437 | This option applies only to deliveries in mailstore format, and is described in |
| 20438 | section 26.4 below. |
| 20439 | |
| 20440 | +-------------------------------------------------------+ |
| 20441 | |mbx_format|Use: appendfile|Type: boolean|Default: false| |
| 20442 | +-------------------------------------------------------+ |
| 20443 | |
| 20444 | This option is available only if Exim has been compiled with SUPPORT_MBX set in |
| 20445 | Local/Makefile. If mbx_format is set with the file option, the message is |
| 20446 | appended to the mailbox file in MBX format instead of traditional Unix format. |
| 20447 | This format is supported by Pine4 and its associated IMAP and POP daemons, by |
| 20448 | means of the c-client library that they all use. |
| 20449 | |
| 20450 | Note: The message_prefix and message_suffix options are not automatically |
| 20451 | changed by the use of mbx_format. They should normally be set empty when using |
| 20452 | MBX format, so this option almost always appears in this combination: |
| 20453 | |
| 20454 | mbx_format = true |
| 20455 | message_prefix = |
| 20456 | message_suffix = |
| 20457 | |
| 20458 | If none of the locking options are mentioned in the configuration, use_mbx_lock |
| 20459 | is assumed and the other locking options default to false. It is possible to |
| 20460 | specify the other kinds of locking with mbx_format, but use_fcntl_lock and |
| 20461 | use_mbx_lock are mutually exclusive. MBX locking interworks with c-client, |
| 20462 | providing for shared access to the mailbox. It should not be used if any |
| 20463 | program that does not use this form of locking is going to access the mailbox, |
| 20464 | nor should it be used if the mailbox file is NFS mounted, because it works only |
| 20465 | when the mailbox is accessed from a single host. |
| 20466 | |
| 20467 | If you set use_fcntl_lock with an MBX-format mailbox, you cannot use the |
| 20468 | standard version of c-client, because as long as it has a mailbox open (this |
| 20469 | means for the whole of a Pine or IMAP session), Exim will not be able to append |
| 20470 | messages to it. |
| 20471 | |
| 20472 | +---------------------------------------------------------------+ |
| 20473 | |message_prefix|Use: appendfile|Type: string*|Default: see below| |
| 20474 | +---------------------------------------------------------------+ |
| 20475 | |
| 20476 | The string specified here is expanded and output at the start of every message. |
| 20477 | The default is unset unless file is specified and use_bsmtp is not set, in |
| 20478 | which case it is: |
| 20479 | |
| 20480 | message_prefix = "From ${if def:return_path{$return_path}\ |
| 20481 | {MAILER-DAEMON}} $tod_bsdinbox\n" |
| 20482 | |
| 20483 | Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\ |
| 20484 | n" in message_prefix. |
| 20485 | |
| 20486 | +---------------------------------------------------------------+ |
| 20487 | |message_suffix|Use: appendfile|Type: string*|Default: see below| |
| 20488 | +---------------------------------------------------------------+ |
| 20489 | |
| 20490 | The string specified here is expanded and output at the end of every message. |
| 20491 | The default is unset unless file is specified and use_bsmtp is not set, in |
| 20492 | which case it is a single newline character. The suffix can be suppressed by |
| 20493 | setting |
| 20494 | |
| 20495 | message_suffix = |
| 20496 | |
| 20497 | Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\ |
| 20498 | n" in message_suffix. |
| 20499 | |
| 20500 | +------------------------------------------------------+ |
| 20501 | |mode|Use: appendfile|Type: octal integer|Default: 0600| |
| 20502 | +------------------------------------------------------+ |
| 20503 | |
| 20504 | If the output file is created, it is given this mode. If it already exists and |
| 20505 | has wider permissions, they are reduced to this mode. If it has narrower |
| 20506 | permissions, an error occurs unless mode_fail_narrower is false. However, if |
| 20507 | the delivery is the result of a save command in a filter file specifying a |
| 20508 | particular mode, the mode of the output file is always forced to take that |
| 20509 | value, and this option is ignored. |
| 20510 | |
| 20511 | +--------------------------------------------------------------+ |
| 20512 | |mode_fail_narrower|Use: appendfile|Type: boolean|Default: true| |
| 20513 | +--------------------------------------------------------------+ |
| 20514 | |
| 20515 | This option applies in the case when an existing mailbox file has a narrower |
| 20516 | mode than that specified by the mode option. If mode_fail_narrower is true, the |
| 20517 | delivery is deferred ("mailbox has the wrong mode"); otherwise Exim continues |
| 20518 | with the delivery attempt, using the existing mode of the file. |
| 20519 | |
| 20520 | +----------------------------------------------------------+ |
| 20521 | |notify_comsat|Use: appendfile|Type: boolean|Default: false| |
| 20522 | +----------------------------------------------------------+ |
| 20523 | |
| 20524 | If this option is true, the comsat daemon is notified after every successful |
| 20525 | delivery to a user mailbox. This is the daemon that notifies logged on users |
| 20526 | about incoming mail. |
| 20527 | |
| 20528 | +--------------------------------------------------+ |
| 20529 | |quota|Use: appendfile|Type: string*|Default: unset| |
| 20530 | +--------------------------------------------------+ |
| 20531 | |
| 20532 | This option imposes a limit on the size of the file to which Exim is appending, |
| 20533 | or to the total space used in the directory tree when the directory option is |
| 20534 | set. In the latter case, computation of the space used is expensive, because |
| 20535 | all the files in the directory (and any sub-directories) have to be |
| 20536 | individually inspected and their sizes summed. (See quota_size_regex and |
| 20537 | maildir_use_size_file for ways to avoid this in environments where users have |
| 20538 | no shell access to their mailboxes). |
| 20539 | |
| 20540 | As there is no interlock against two simultaneous deliveries into a multi-file |
| 20541 | mailbox, it is possible for the quota to be overrun in this case. For |
| 20542 | single-file mailboxes, of course, an interlock is a necessity. |
| 20543 | |
| 20544 | A file's size is taken as its used value. Because of blocking effects, this may |
| 20545 | be a lot less than the actual amount of disk space allocated to the file. If |
| 20546 | the sizes of a number of files are being added up, the rounding effect can |
| 20547 | become quite noticeable, especially on systems that have large block sizes. |
| 20548 | Nevertheless, it seems best to stick to the used figure, because this is the |
| 20549 | obvious value which users understand most easily. |
| 20550 | |
| 20551 | The value of the option is expanded, and must then be a numerical value |
| 20552 | (decimal point allowed), optionally followed by one of the letters K, M, or G, |
| 20553 | for kilobytes, megabytes, or gigabytes. If Exim is running on a system with |
| 20554 | large file support (Linux and FreeBSD have this), mailboxes larger than 2G can |
| 20555 | be handled. |
| 20556 | |
| 20557 | Note: A value of zero is interpreted as "no quota". |
| 20558 | |
| 20559 | The expansion happens while Exim is running as root, before it changes uid for |
| 20560 | the delivery. This means that files that are inaccessible to the end user can |
| 20561 | be used to hold quota values that are looked up in the expansion. When delivery |
| 20562 | fails because this quota is exceeded, the handling of the error is as for |
| 20563 | system quota failures. |
| 20564 | |
| 20565 | By default, Exim's quota checking mimics system quotas, and restricts the |
| 20566 | mailbox to the specified maximum size, though the value is not accurate to the |
| 20567 | last byte, owing to separator lines and additional headers that may get added |
| 20568 | during message delivery. When a mailbox is nearly full, large messages may get |
| 20569 | refused even though small ones are accepted, because the size of the current |
| 20570 | message is added to the quota when the check is made. This behaviour can be |
| 20571 | changed by setting quota_is_inclusive false. When this is done, the check for |
| 20572 | exceeding the quota does not include the current message. Thus, deliveries |
| 20573 | continue until the quota has been exceeded; thereafter, no further messages are |
| 20574 | delivered. See also quota_warn_threshold. |
| 20575 | |
| 20576 | +------------------------------------------------------------+ |
| 20577 | |quota_directory|Use: appendfile|Type: string*|Default: unset| |
| 20578 | +------------------------------------------------------------+ |
| 20579 | |
| 20580 | This option defines the directory to check for quota purposes when delivering |
| 20581 | into individual files. The default is the delivery directory, or, if a file |
| 20582 | called maildirfolder exists in a maildir directory, the parent of the delivery |
| 20583 | directory. |
| 20584 | |
| 20585 | +--------------------------------------------------------+ |
| 20586 | |quota_filecount|Use: appendfile|Type: string*|Default: 0| |
| 20587 | +--------------------------------------------------------+ |
| 20588 | |
| 20589 | This option applies when the directory option is set. It limits the total |
| 20590 | number of files in the directory (compare the inode limit in system quotas). It |
| 20591 | can only be used if quota is also set. The value is expanded; an expansion |
| 20592 | failure causes delivery to be deferred. A value of zero is interpreted as "no |
| 20593 | quota". |
| 20594 | |
| 20595 | +--------------------------------------------------------------+ |
| 20596 | |quota_is_inclusive|Use: appendfile|Type: boolean|Default: true| |
| 20597 | +--------------------------------------------------------------+ |
| 20598 | |
| 20599 | See quota above. |
| 20600 | |
| 20601 | +------------------------------------------------------------+ |
| 20602 | |quota_size_regex|Use: appendfile|Type: string|Default: unset| |
| 20603 | +------------------------------------------------------------+ |
| 20604 | |
| 20605 | This option applies when one of the delivery modes that writes a separate file |
| 20606 | for each message is being used. When Exim wants to find the size of one of |
| 20607 | these files in order to test the quota, it first checks quota_size_regex. If |
| 20608 | this is set to a regular expression that matches the file name, and it captures |
| 20609 | one string, that string is interpreted as a representation of the file's size. |
| 20610 | The value of quota_size_regex is not expanded. |
| 20611 | |
| 20612 | This feature is useful only when users have no shell access to their mailboxes |
| 20613 | - otherwise they could defeat the quota simply by renaming the files. This |
| 20614 | facility can be used with maildir deliveries, by setting maildir_tag to add the |
| 20615 | file length to the file name. For example: |
| 20616 | |
| 20617 | maildir_tag = ,S=$message_size |
| 20618 | quota_size_regex = ,S=(\d+) |
| 20619 | |
| 20620 | An alternative to $message_size is $message_linecount, which contains the |
| 20621 | number of lines in the message. |
| 20622 | |
| 20623 | The regular expression should not assume that the length is at the end of the |
| 20624 | file name (even though maildir_tag puts it there) because maildir MUAs |
| 20625 | sometimes add other information onto the ends of message file names. |
| 20626 | |
| 20627 | Section 26.7 contains further information. |
| 20628 | |
| 20629 | +-------------------------------------------------------------------+ |
| 20630 | |quota_warn_message|Use: appendfile|Type: string*|Default: see below| |
| 20631 | +-------------------------------------------------------------------+ |
| 20632 | |
| 20633 | See below for the use of this option. If it is not set when |
| 20634 | quota_warn_threshold is set, it defaults to |
| 20635 | |
| 20636 | quota_warn_message = "\ |
| 20637 | To: $local_part@$domain\n\ |
| 20638 | Subject: Your mailbox\n\n\ |
| 20639 | This message is automatically created \ |
| 20640 | by mail delivery software.\n\n\ |
| 20641 | The size of your mailbox has exceeded \ |
| 20642 | a warning threshold that is\n\ |
| 20643 | set by the system administrator.\n" |
| 20644 | |
| 20645 | +-------------------------------------------------------------+ |
| 20646 | |quota_warn_threshold|Use: appendfile|Type: string*|Default: 0| |
| 20647 | +-------------------------------------------------------------+ |
| 20648 | |
| 20649 | This option is expanded in the same way as quota (see above). If the resulting |
| 20650 | value is greater than zero, and delivery of the message causes the size of the |
| 20651 | file or total space in the directory tree to cross the given threshold, a |
| 20652 | warning message is sent. If quota is also set, the threshold may be specified |
| 20653 | as a percentage of it by following the value with a percent sign. For example: |
| 20654 | |
| 20655 | quota = 10M |
| 20656 | quota_warn_threshold = 75% |
| 20657 | |
| 20658 | If quota is not set, a setting of quota_warn_threshold that ends with a percent |
| 20659 | sign is ignored. |
| 20660 | |
| 20661 | The warning message itself is specified by the quota_warn_message option, and |
| 20662 | it must start with a To: header line containing the recipient(s) of the warning |
| 20663 | message. These do not necessarily have to include the recipient(s) of the |
| 20664 | original message. A Subject: line should also normally be supplied. You can |
| 20665 | include any other header lines that you want. If you do not include a From: |
| 20666 | line, the default is: |
| 20667 | |
| 20668 | From: Mail Delivery System <mailer-daemon@$qualify_domain_sender> |
| 20669 | |
| 20670 | If you supply a Reply-To: line, it overrides the global errors_reply_to option. |
| 20671 | |
| 20672 | The quota option does not have to be set in order to use this option; they are |
| 20673 | independent of one another except when the threshold is specified as a |
| 20674 | percentage. |
| 20675 | |
| 20676 | +------------------------------------------------------+ |
| 20677 | |use_bsmtp|Use: appendfile|Type: boolean|Default: false| |
| 20678 | +------------------------------------------------------+ |
| 20679 | |
| 20680 | If this option is set true, appendfile writes messages in "batch SMTP" format, |
| 20681 | with the envelope sender and recipient(s) included as SMTP commands. If you |
| 20682 | want to include a leading HELO command with such messages, you can do so by |
| 20683 | setting the message_prefix option. See section 48.10 for details of batch SMTP. |
| 20684 | |
| 20685 | +-----------------------------------------------------+ |
| 20686 | |use_crlf|Use: appendfile|Type: boolean|Default: false| |
| 20687 | +-----------------------------------------------------+ |
| 20688 | |
| 20689 | This option causes lines to be terminated with the two-character CRLF sequence |
| 20690 | (carriage return, linefeed) instead of just a linefeed character. In the case |
| 20691 | of batched SMTP, the byte sequence written to the file is then an exact image |
| 20692 | of what would be sent down a real SMTP connection. |
| 20693 | |
| 20694 | Note: The contents of the message_prefix and message_suffix options (which are |
| 20695 | used to supply the traditional "From " and blank line separators in |
| 20696 | Berkeley-style mailboxes) are written verbatim, so must contain their own |
| 20697 | carriage return characters if these are needed. In cases where these options |
| 20698 | have non-empty defaults, the values end with a single linefeed, so they must be |
| 20699 | changed to end with "\r\n" if use_crlf is set. |
| 20700 | |
| 20701 | +---------------------------------------------------------------+ |
| 20702 | |use_fcntl_lock|Use: appendfile|Type: boolean|Default: see below| |
| 20703 | +---------------------------------------------------------------+ |
| 20704 | |
| 20705 | This option controls the use of the fcntl() function to lock a file for |
| 20706 | exclusive use when a message is being appended. It is set by default unless |
| 20707 | use_flock_lock is set. Otherwise, it should be turned off only if you know that |
| 20708 | all your MUAs use lock file locking. When both use_fcntl_lock and |
| 20709 | use_flock_lock are unset, use_lockfile must be set. |
| 20710 | |
| 20711 | +-----------------------------------------------------------+ |
| 20712 | |use_flock_lock|Use: appendfile|Type: boolean|Default: false| |
| 20713 | +-----------------------------------------------------------+ |
| 20714 | |
| 20715 | This option is provided to support the use of flock() for file locking, for the |
| 20716 | few situations where it is needed. Most modern operating systems support fcntl |
| 20717 | () and lockf() locking, and these two functions interwork with each other. Exim |
| 20718 | uses fcntl() locking by default. |
| 20719 | |
| 20720 | This option is required only if you are using an operating system where flock() |
| 20721 | is used by programs that access mailboxes (typically MUAs), and where flock() |
| 20722 | does not correctly interwork with fcntl(). You can use both fcntl() and flock() |
| 20723 | locking simultaneously if you want. |
| 20724 | |
| 20725 | Not all operating systems provide flock(). Some versions of Solaris do not have |
| 20726 | it (and some, I think, provide a not quite right version built on top of lockf |
| 20727 | ()). If the OS does not have flock(), Exim will be built without the ability to |
| 20728 | use it, and any attempt to do so will cause a configuration error. |
| 20729 | |
| 20730 | Warning: flock() locks do not work on NFS files (unless flock() is just being |
| 20731 | mapped onto fcntl() by the OS). |
| 20732 | |
| 20733 | +-------------------------------------------------------------+ |
| 20734 | |use_lockfile|Use: appendfile|Type: boolean|Default: see below| |
| 20735 | +-------------------------------------------------------------+ |
| 20736 | |
| 20737 | If this option is turned off, Exim does not attempt to create a lock file when |
| 20738 | appending to a mailbox file. In this situation, the only locking is by fcntl(). |
| 20739 | You should only turn use_lockfile off if you are absolutely sure that every MUA |
| 20740 | that is ever going to look at your users' mailboxes uses fcntl() rather than a |
| 20741 | lock file, and even then only when you are not delivering over NFS from more |
| 20742 | than one host. |
| 20743 | |
| 20744 | In order to append to an NFS file safely from more than one host, it is |
| 20745 | necessary to take out a lock before opening the file, and the lock file |
| 20746 | achieves this. Otherwise, even with fcntl() locking, there is a risk of file |
| 20747 | corruption. |
| 20748 | |
| 20749 | The use_lockfile option is set by default unless use_mbx_lock is set. It is not |
| 20750 | possible to turn both use_lockfile and use_fcntl_lock off, except when |
| 20751 | mbx_format is set. |
| 20752 | |
| 20753 | +-------------------------------------------------------------+ |
| 20754 | |use_mbx_lock|Use: appendfile|Type: boolean|Default: see below| |
| 20755 | +-------------------------------------------------------------+ |
| 20756 | |
| 20757 | This option is available only if Exim has been compiled with SUPPORT_MBX set in |
| 20758 | Local/Makefile. Setting the option specifies that special MBX locking rules be |
| 20759 | used. It is set by default if mbx_format is set and none of the locking options |
| 20760 | are mentioned in the configuration. The locking rules are the same as are used |
| 20761 | by the c-client library that underlies Pine and the IMAP4 and POP daemons that |
| 20762 | come with it (see the discussion below). The rules allow for shared access to |
| 20763 | the mailbox. However, this kind of locking does not work when the mailbox is |
| 20764 | NFS mounted. |
| 20765 | |
| 20766 | You can set use_mbx_lock with either (or both) of use_fcntl_lock and |
| 20767 | use_flock_lock to control what kind of locking is used in implementing the MBX |
| 20768 | locking rules. The default is to use fcntl() if use_mbx_lock is set without |
| 20769 | use_fcntl_lock or use_flock_lock. |
| 20770 | |
| 20771 | |
| 20772 | 26.3 Operational details for appending |
| 20773 | -------------------------------------- |
| 20774 | |
| 20775 | Before appending to a file, the following preparations are made: |
| 20776 | |
| 20777 | * If the name of the file is /dev/null, no action is taken, and a success |
| 20778 | return is given. |
| 20779 | |
| 20780 | * If any directories on the file's path are missing, Exim creates them if the |
| 20781 | create_directory option is set. A created directory's mode is given by the |
| 20782 | directory_mode option. |
| 20783 | |
| 20784 | * If file_format is set, the format of an existing file is checked. If this |
| 20785 | indicates that a different transport should be used, control is passed to |
| 20786 | that transport. |
| 20787 | |
| 20788 | * If use_lockfile is set, a lock file is built in a way that will work |
| 20789 | reliably over NFS, as follows: |
| 20790 | |
| 20791 | 1. Create a "hitching post" file whose name is that of the lock file with |
| 20792 | the current time, primary host name, and process id added, by opening |
| 20793 | for writing as a new file. If this fails with an access error, delivery |
| 20794 | is deferred. |
| 20795 | |
| 20796 | 2. Close the hitching post file, and hard link it to the lock file name. |
| 20797 | |
| 20798 | 3. If the call to link() succeeds, creation of the lock file has |
| 20799 | succeeded. Unlink the hitching post name. |
| 20800 | |
| 20801 | 4. Otherwise, use stat() to get information about the hitching post file, |
| 20802 | and then unlink hitching post name. If the number of links is exactly |
| 20803 | two, creation of the lock file succeeded but something (for example, an |
| 20804 | NFS server crash and restart) caused this fact not to be communicated |
| 20805 | to the link() call. |
| 20806 | |
| 20807 | 5. If creation of the lock file failed, wait for lock_interval and try |
| 20808 | again, up to lock_retries times. However, since any program that writes |
| 20809 | to a mailbox should complete its task very quickly, it is reasonable to |
| 20810 | time out old lock files that are normally the result of user agent and |
| 20811 | system crashes. If an existing lock file is older than lockfile_timeout |
| 20812 | Exim attempts to unlink it before trying again. |
| 20813 | |
| 20814 | * A call is made to lstat() to discover whether the main file exists, and if |
| 20815 | so, what its characteristics are. If lstat() fails for any reason other |
| 20816 | than non-existence, delivery is deferred. |
| 20817 | |
| 20818 | * If the file does exist and is a symbolic link, delivery is deferred, unless |
| 20819 | the allow_symlink option is set, in which case the ownership of the link is |
| 20820 | checked, and then stat() is called to find out about the real file, which |
| 20821 | is then subjected to the checks below. The check on the top-level link |
| 20822 | ownership prevents one user creating a link for another's mailbox in a |
| 20823 | sticky directory, though allowing symbolic links in this case is definitely |
| 20824 | not a good idea. If there is a chain of symbolic links, the intermediate |
| 20825 | ones are not checked. |
| 20826 | |
| 20827 | * If the file already exists but is not a regular file, or if the file's |
| 20828 | owner and group (if the group is being checked - see check_group above) are |
| 20829 | different from the user and group under which the delivery is running, |
| 20830 | delivery is deferred. |
| 20831 | |
| 20832 | * If the file's permissions are more generous than specified, they are |
| 20833 | reduced. If they are insufficient, delivery is deferred, unless |
| 20834 | mode_fail_narrower is set false, in which case the delivery is tried using |
| 20835 | the existing permissions. |
| 20836 | |
| 20837 | * The file's inode number is saved, and the file is then opened for |
| 20838 | appending. If this fails because the file has vanished, appendfile behaves |
| 20839 | as if it hadn't existed (see below). For any other failures, delivery is |
| 20840 | deferred. |
| 20841 | |
| 20842 | * If the file is opened successfully, check that the inode number hasn't |
| 20843 | changed, that it is still a regular file, and that the owner and |
| 20844 | permissions have not changed. If anything is wrong, defer delivery and |
| 20845 | freeze the message. |
| 20846 | |
| 20847 | * If the file did not exist originally, defer delivery if the file_must_exist |
| 20848 | option is set. Otherwise, check that the file is being created in a |
| 20849 | permitted directory if the create_file option is set (deferring on |
| 20850 | failure), and then open for writing as a new file, with the O_EXCL and |
| 20851 | O_CREAT options, except when dealing with a symbolic link (the |
| 20852 | allow_symlink option must be set). In this case, which can happen if the |
| 20853 | link points to a non-existent file, the file is opened for writing using |
| 20854 | O_CREAT but not O_EXCL, because that prevents link following. |
| 20855 | |
| 20856 | * If opening fails because the file exists, obey the tests given above for |
| 20857 | existing files. However, to avoid looping in a situation where the file is |
| 20858 | being continuously created and destroyed, the exists/not-exists loop is |
| 20859 | broken after 10 repetitions, and the message is then frozen. |
| 20860 | |
| 20861 | * If opening fails with any other error, defer delivery. |
| 20862 | |
| 20863 | * Once the file is open, unless both use_fcntl_lock and use_flock_lock are |
| 20864 | false, it is locked using fcntl() or flock() or both. If use_mbx_lock is |
| 20865 | false, an exclusive lock is requested in each case. However, if |
| 20866 | use_mbx_lock is true, Exim takes out a shared lock on the open file, and an |
| 20867 | exclusive lock on the file whose name is |
| 20868 | |
| 20869 | /tmp/.<device-number>.<inode-number> |
| 20870 | |
| 20871 | using the device and inode numbers of the open mailbox file, in accordance |
| 20872 | with the MBX locking rules. This file is created with a mode that is |
| 20873 | specified by the lockfile_mode option. |
| 20874 | |
| 20875 | If Exim fails to lock the file, there are two possible courses of action, |
| 20876 | depending on the value of the locking timeout. This is obtained from |
| 20877 | lock_fcntl_timeout or lock_flock_timeout, as appropriate. |
| 20878 | |
| 20879 | If the timeout value is zero, the file is closed, Exim waits for |
| 20880 | lock_interval, and then goes back and re-opens the file as above and tries |
| 20881 | to lock it again. This happens up to lock_retries times, after which the |
| 20882 | delivery is deferred. |
| 20883 | |
| 20884 | If the timeout has a value greater than zero, blocking calls to fcntl() or |
| 20885 | flock() are used (with the given timeout), so there has already been some |
| 20886 | waiting involved by the time locking fails. Nevertheless, Exim does not |
| 20887 | give up immediately. It retries up to |
| 20888 | |
| 20889 | (lock_retries * lock_interval) / <timeout> |
| 20890 | |
| 20891 | times (rounded up). |
| 20892 | |
| 20893 | At the end of delivery, Exim closes the file (which releases the fcntl() and/or |
| 20894 | flock() locks) and then deletes the lock file if one was created. |
| 20895 | |
| 20896 | |
| 20897 | 26.4 Operational details for delivery to a new file |
| 20898 | --------------------------------------------------- |
| 20899 | |
| 20900 | When the directory option is set instead of file, each message is delivered |
| 20901 | into a newly-created file or set of files. When appendfile is activated |
| 20902 | directly from a redirect router, neither file nor directory is normally set, |
| 20903 | because the path for delivery is supplied by the router. (See for example, the |
| 20904 | address_file transport in the default configuration.) In this case, delivery is |
| 20905 | to a new file if either the path name ends in "/", or the maildir_format or |
| 20906 | mailstore_format option is set. |
| 20907 | |
| 20908 | No locking is required while writing the message to a new file, so the various |
| 20909 | locking options of the transport are ignored. The "From" line that by default |
| 20910 | separates messages in a single file is not normally needed, nor is the escaping |
| 20911 | of message lines that start with "From", and there is no need to ensure a |
| 20912 | newline at the end of each message. Consequently, the default values for |
| 20913 | check_string, message_prefix, and message_suffix are all unset when any of |
| 20914 | directory, maildir_format, or mailstore_format is set. |
| 20915 | |
| 20916 | If Exim is required to check a quota setting, it adds up the sizes of all the |
| 20917 | files in the delivery directory by default. However, you can specify a |
| 20918 | different directory by setting quota_directory. Also, for maildir deliveries |
| 20919 | (see below) the maildirfolder convention is honoured. |
| 20920 | |
| 20921 | There are three different ways in which delivery to individual files can be |
| 20922 | done, controlled by the settings of the maildir_format and mailstore_format |
| 20923 | options. Note that code to support maildir or mailstore formats is not included |
| 20924 | in the binary unless SUPPORT_MAILDIR or SUPPORT_MAILSTORE, respectively, is set |
| 20925 | in Local/Makefile. |
| 20926 | |
| 20927 | In all three cases an attempt is made to create the directory and any necessary |
| 20928 | sub-directories if they do not exist, provided that the create_directory option |
| 20929 | is set (the default). The location of a created directory can be constrained by |
| 20930 | setting create_file. A created directory's mode is given by the directory_mode |
| 20931 | option. If creation fails, or if the create_directory option is not set when |
| 20932 | creation is required, delivery is deferred. |
| 20933 | |
| 20934 | |
| 20935 | 26.5 Maildir delivery |
| 20936 | --------------------- |
| 20937 | |
| 20938 | If the maildir_format option is true, Exim delivers each message by writing it |
| 20939 | to a file whose name is tmp/<stime>.H<mtime>P<pid>.<host> in the directory that |
| 20940 | is defined by the directory option (the "delivery directory"). If the delivery |
| 20941 | is successful, the file is renamed into the new subdirectory. |
| 20942 | |
| 20943 | In the file name, <stime> is the current time of day in seconds, and <mtime> is |
| 20944 | the microsecond fraction of the time. After a maildir delivery, Exim checks |
| 20945 | that the time-of-day clock has moved on by at least one microsecond before |
| 20946 | terminating the delivery process. This guarantees uniqueness for the file name. |
| 20947 | However, as a precaution, Exim calls stat() for the file before opening it. If |
| 20948 | any response other than ENOENT (does not exist) is given, Exim waits 2 seconds |
| 20949 | and tries again, up to maildir_retries times. |
| 20950 | |
| 20951 | Before Exim carries out a maildir delivery, it ensures that subdirectories |
| 20952 | called new, cur, and tmp exist in the delivery directory. If they do not exist, |
| 20953 | Exim tries to create them and any superior directories in their path, subject |
| 20954 | to the create_directory and create_file options. If the |
| 20955 | maildirfolder_create_regex option is set, and the regular expression it |
| 20956 | contains matches the delivery directory, Exim also ensures that a file called |
| 20957 | maildirfolder exists in the delivery directory. If a missing directory or |
| 20958 | maildirfolder file cannot be created, delivery is deferred. |
| 20959 | |
| 20960 | These features make it possible to use Exim to create all the necessary files |
| 20961 | and directories in a maildir mailbox, including subdirectories for maildir++ |
| 20962 | folders. Consider this example: |
| 20963 | |
| 20964 | maildir_format = true |
| 20965 | directory = /var/mail/$local_part\ |
| 20966 | ${if eq{$local_part_suffix}{}{}\ |
| 20967 | {/.${substr_1:$local_part_suffix}}} |
| 20968 | maildirfolder_create_regex = /\.[^/]+$ |
| 20969 | |
| 20970 | If $local_part_suffix is empty (there was no suffix for the local part), |
| 20971 | delivery is into a toplevel maildir with a name like /var/mail/pimbo (for the |
| 20972 | user called pimbo). The pattern in maildirfolder_create_regex does not match |
| 20973 | this name, so Exim will not look for or create the file /var/mail/pimbo/ |
| 20974 | maildirfolder, though it will create /var/mail/pimbo/{cur,new,tmp} if |
| 20975 | necessary. |
| 20976 | |
| 20977 | However, if $local_part_suffix contains "-eximusers" (for example), delivery is |
| 20978 | into the maildir++ folder /var/mail/pimbo/.eximusers, which does match |
| 20979 | maildirfolder_create_regex. In this case, Exim will create /var/mail/pimbo |
| 20980 | /.eximusers/maildirfolder as well as the three maildir directories /var/mail/ |
| 20981 | pimbo/.eximusers/{cur,new,tmp}. |
| 20982 | |
| 20983 | Warning: Take care when setting maildirfolder_create_regex that it does not |
| 20984 | inadvertently match the toplevel maildir directory, because a maildirfolder |
| 20985 | file at top level would completely break quota calculations. |
| 20986 | |
| 20987 | If Exim is required to check a quota setting before a maildir delivery, and |
| 20988 | quota_directory is not set, it looks for a file called maildirfolder in the |
| 20989 | maildir directory (alongside new, cur, tmp). If this exists, Exim assumes the |
| 20990 | directory is a maildir++ folder directory, which is one level down from the |
| 20991 | user's top level mailbox directory. This causes it to start at the parent |
| 20992 | directory instead of the current directory when calculating the amount of space |
| 20993 | used. |
| 20994 | |
| 20995 | One problem with delivering into a multi-file mailbox is that it is |
| 20996 | computationally expensive to compute the size of the mailbox for quota |
| 20997 | checking. Various approaches have been taken to reduce the amount of work |
| 20998 | needed. The next two sections describe two of them. A third alternative is to |
| 20999 | use some external process for maintaining the size data, and use the expansion |
| 21000 | of the mailbox_size option as a way of importing it into Exim. |
| 21001 | |
| 21002 | |
| 21003 | 26.6 Using tags to record message sizes |
| 21004 | --------------------------------------- |
| 21005 | |
| 21006 | If maildir_tag is set, the string is expanded for each delivery. When the |
| 21007 | maildir file is renamed into the new sub-directory, the tag is added to its |
| 21008 | name. However, if adding the tag takes the length of the name to the point |
| 21009 | where the test stat() call fails with ENAMETOOLONG, the tag is dropped and the |
| 21010 | maildir file is created with no tag. |
| 21011 | |
| 21012 | Tags can be used to encode the size of files in their names; see |
| 21013 | quota_size_regex above for an example. The expansion of maildir_tag happens |
| 21014 | after the message has been written. The value of the $message_size variable is |
| 21015 | set to the number of bytes actually written. If the expansion is forced to |
| 21016 | fail, the tag is ignored, but a non-forced failure causes delivery to be |
| 21017 | deferred. The expanded tag may contain any printing characters except "/". |
| 21018 | Non-printing characters in the string are ignored; if the resulting string is |
| 21019 | empty, it is ignored. If it starts with an alphanumeric character, a leading |
| 21020 | colon is inserted; this default has not proven to be the path that popular |
| 21021 | maildir implementations have chosen (but changing it in Exim would break |
| 21022 | backwards compatibility). |
| 21023 | |
| 21024 | For one common implementation, you might set: |
| 21025 | |
| 21026 | maildir_tag = ,S=${message_size} |
| 21027 | |
| 21028 | but you should check the documentation of the other software to be sure. |
| 21029 | |
| 21030 | It is advisable to also set quota_size_regex when setting maildir_tag as this |
| 21031 | allows Exim to extract the size from your tag, instead of having to stat() each |
| 21032 | message file. |
| 21033 | |
| 21034 | |
| 21035 | 26.7 Using a maildirsize file |
| 21036 | ----------------------------- |
| 21037 | |
| 21038 | If maildir_use_size_file is true, Exim implements the maildir++ rules for |
| 21039 | storing quota and message size information in a file called maildirsize within |
| 21040 | the toplevel maildir directory. If this file does not exist, Exim creates it, |
| 21041 | setting the quota from the quota option of the transport. If the maildir |
| 21042 | directory itself does not exist, it is created before any attempt to write a |
| 21043 | maildirsize file. |
| 21044 | |
| 21045 | The maildirsize file is used to hold information about the sizes of messages in |
| 21046 | the maildir, thus speeding up quota calculations. The quota value in the file |
| 21047 | is just a cache; if the quota is changed in the transport, the new value |
| 21048 | overrides the cached value when the next message is delivered. The cache is |
| 21049 | maintained for the benefit of other programs that access the maildir and need |
| 21050 | to know the quota. |
| 21051 | |
| 21052 | If the quota option in the transport is unset or zero, the maildirsize file is |
| 21053 | maintained (with a zero quota setting), but no quota is imposed. |
| 21054 | |
| 21055 | A regular expression is available for controlling which directories in the |
| 21056 | maildir participate in quota calculations when a maildirsizefile is in use. See |
| 21057 | the description of the maildir_quota_directory_regex option above for details. |
| 21058 | |
| 21059 | |
| 21060 | 26.8 Mailstore delivery |
| 21061 | ----------------------- |
| 21062 | |
| 21063 | If the mailstore_format option is true, each message is written as two files in |
| 21064 | the given directory. A unique base name is constructed from the message id and |
| 21065 | the current delivery process, and the files that are written use this base name |
| 21066 | plus the suffixes .env and .msg. The .env file contains the message's envelope, |
| 21067 | and the .msg file contains the message itself. The base name is placed in the |
| 21068 | variable $mailstore_basename. |
| 21069 | |
| 21070 | During delivery, the envelope is first written to a file with the suffix .tmp. |
| 21071 | The .msg file is then written, and when it is complete, the .tmp file is |
| 21072 | renamed as the .env file. Programs that access messages in mailstore format |
| 21073 | should wait for the presence of both a .msg and a .env file before accessing |
| 21074 | either of them. An alternative approach is to wait for the absence of a .tmp |
| 21075 | file. |
| 21076 | |
| 21077 | The envelope file starts with any text defined by the mailstore_prefix option, |
| 21078 | expanded and terminated by a newline if there isn't one. Then follows the |
| 21079 | sender address on one line, then all the recipient addresses, one per line. |
| 21080 | There can be more than one recipient only if the batch_max option is set |
| 21081 | greater than one. Finally, mailstore_suffix is expanded and the result appended |
| 21082 | to the file, followed by a newline if it does not end with one. |
| 21083 | |
| 21084 | If expansion of mailstore_prefix or mailstore_suffix ends with a forced |
| 21085 | failure, it is ignored. Other expansion errors are treated as serious |
| 21086 | configuration errors, and delivery is deferred. The variable |
| 21087 | $mailstore_basename is available for use during these expansions. |
| 21088 | |
| 21089 | |
| 21090 | 26.9 Non-special new file delivery |
| 21091 | ---------------------------------- |
| 21092 | |
| 21093 | If neither maildir_format nor mailstore_format is set, a single new file is |
| 21094 | created directly in the named directory. For example, when delivering messages |
| 21095 | into files in batched SMTP format for later delivery to some host (see section |
| 21096 | 48.10), a setting such as |
| 21097 | |
| 21098 | directory = /var/bsmtp/$host |
| 21099 | |
| 21100 | might be used. A message is written to a file with a temporary name, which is |
| 21101 | then renamed when the delivery is complete. The final name is obtained by |
| 21102 | expanding the contents of the directory_file option. |
| 21103 | |
| 21104 | |
| 21105 | |
| 21106 | =============================================================================== |
| 21107 | 27. THE AUTOREPLY TRANSPORT |
| 21108 | |
| 21109 | The autoreply transport is not a true transport in that it does not cause the |
| 21110 | message to be transmitted. Instead, it generates a new mail message as an |
| 21111 | automatic reply to the incoming message. References: and Auto-Submitted: header |
| 21112 | lines are included. These are constructed according to the rules in RFCs 2822 |
| 21113 | and 3834, respectively. |
| 21114 | |
| 21115 | If the router that passes the message to this transport does not have the |
| 21116 | unseen option set, the original message (for the current recipient) is not |
| 21117 | delivered anywhere. However, when the unseen option is set on the router that |
| 21118 | passes the message to this transport, routing of the address continues, so |
| 21119 | another router can set up a normal message delivery. |
| 21120 | |
| 21121 | The autoreply transport is usually run as the result of mail filtering, a |
| 21122 | "vacation" message being the standard example. However, it can also be run |
| 21123 | directly from a router like any other transport. To reduce the possibility of |
| 21124 | message cascades, messages created by the autoreply transport always have empty |
| 21125 | envelope sender addresses, like bounce messages. |
| 21126 | |
| 21127 | The parameters of the message to be sent can be specified in the configuration |
| 21128 | by options described below. However, these are used only when the address |
| 21129 | passed to the transport does not contain its own reply information. When the |
| 21130 | transport is run as a consequence of a mail or vacation command in a filter |
| 21131 | file, the parameters of the message are supplied by the filter, and passed with |
| 21132 | the address. The transport's options that define the message are then ignored |
| 21133 | (so they are not usually set in this case). The message is specified entirely |
| 21134 | by the filter or by the transport; it is never built from a mixture of options. |
| 21135 | However, the file_optional, mode, and return_message options apply in all |
| 21136 | cases. |
| 21137 | |
| 21138 | Autoreply is implemented as a local transport. When used as a result of a |
| 21139 | command in a user's filter file, autoreply normally runs under the uid and gid |
| 21140 | of the user, and with appropriate current and home directories (see chapter 23 |
| 21141 | ). |
| 21142 | |
| 21143 | There is a subtle difference between routing a message to a pipe transport that |
| 21144 | generates some text to be returned to the sender, and routing it to an |
| 21145 | autoreply transport. This difference is noticeable only if more than one |
| 21146 | address from the same message is so handled. In the case of a pipe, the |
| 21147 | separate outputs from the different addresses are gathered up and returned to |
| 21148 | the sender in a single message, whereas if autoreply is used, a separate |
| 21149 | message is generated for each address that is passed to it. |
| 21150 | |
| 21151 | Non-printing characters are not permitted in the header lines generated for the |
| 21152 | message that autoreply creates, with the exception of newlines that are |
| 21153 | immediately followed by white space. If any non-printing characters are found, |
| 21154 | the transport defers. Whether characters with the top bit set count as printing |
| 21155 | characters or not is controlled by the print_topbitchars global option. |
| 21156 | |
| 21157 | If any of the generic options for manipulating headers (for example, |
| 21158 | headers_add) are set on an autoreply transport, they apply to the copy of the |
| 21159 | original message that is included in the generated message when return_message |
| 21160 | is set. They do not apply to the generated message itself. |
| 21161 | |
| 21162 | If the autoreply transport receives return code 2 from Exim when it submits the |
| 21163 | message, indicating that there were no recipients, it does not treat this as an |
| 21164 | error. This means that autoreplies sent to $sender_address when this is empty |
| 21165 | (because the incoming message is a bounce message) do not cause problems. They |
| 21166 | are just discarded. |
| 21167 | |
| 21168 | |
| 21169 | 27.1 Private options for autoreply |
| 21170 | ---------------------------------- |
| 21171 | |
| 21172 | +-----------------------------------------------+ |
| 21173 | |bcc|Use: autoreply|Type: string*|Default: unset| |
| 21174 | +-----------------------------------------------+ |
| 21175 | |
| 21176 | This specifies the addresses that are to receive "blind carbon copies" of the |
| 21177 | message when the message is specified by the transport. |
| 21178 | |
| 21179 | +----------------------------------------------+ |
| 21180 | |cc|Use: autoreply|Type: string*|Default: unset| |
| 21181 | +----------------------------------------------+ |
| 21182 | |
| 21183 | This specifies recipients of the message and the contents of the Cc: header |
| 21184 | when the message is specified by the transport. |
| 21185 | |
| 21186 | +------------------------------------------------+ |
| 21187 | |file|Use: autoreply|Type: string*|Default: unset| |
| 21188 | +------------------------------------------------+ |
| 21189 | |
| 21190 | The contents of the file are sent as the body of the message when the message |
| 21191 | is specified by the transport. If both file and text are set, the text string |
| 21192 | comes first. |
| 21193 | |
| 21194 | +-------------------------------------------------------+ |
| 21195 | |file_expand|Use: autoreply|Type: boolean|Default: false| |
| 21196 | +-------------------------------------------------------+ |
| 21197 | |
| 21198 | If this is set, the contents of the file named by the file option are subjected |
| 21199 | to string expansion as they are added to the message. |
| 21200 | |
| 21201 | +---------------------------------------------------------+ |
| 21202 | |file_optional|Use: autoreply|Type: boolean|Default: false| |
| 21203 | +---------------------------------------------------------+ |
| 21204 | |
| 21205 | If this option is true, no error is generated if the file named by the file |
| 21206 | option or passed with the address does not exist or cannot be read. |
| 21207 | |
| 21208 | +------------------------------------------------+ |
| 21209 | |from|Use: autoreply|Type: string*|Default: unset| |
| 21210 | +------------------------------------------------+ |
| 21211 | |
| 21212 | This specifies the contents of the From: header when the message is specified |
| 21213 | by the transport. |
| 21214 | |
| 21215 | +---------------------------------------------------+ |
| 21216 | |headers|Use: autoreply|Type: string*|Default: unset| |
| 21217 | +---------------------------------------------------+ |
| 21218 | |
| 21219 | This specifies additional RFC 2822 headers that are to be added to the message |
| 21220 | when the message is specified by the transport. Several can be given by using " |
| 21221 | \n" to separate them. There is no check on the format. |
| 21222 | |
| 21223 | +-----------------------------------------------+ |
| 21224 | |log|Use: autoreply|Type: string*|Default: unset| |
| 21225 | +-----------------------------------------------+ |
| 21226 | |
| 21227 | This option names a file in which a record of every message sent is logged when |
| 21228 | the message is specified by the transport. |
| 21229 | |
| 21230 | +-----------------------------------------------------+ |
| 21231 | |mode|Use: autoreply|Type: octal integer|Default: 0600| |
| 21232 | +-----------------------------------------------------+ |
| 21233 | |
| 21234 | If either the log file or the "once" file has to be created, this mode is used. |
| 21235 | |
| 21236 | +------------------------------------------------------------+ |
| 21237 | |never_mail|Use: autoreply|Type: address list*|Default: unset| |
| 21238 | +------------------------------------------------------------+ |
| 21239 | |
| 21240 | If any run of the transport creates a message with a recipient that matches any |
| 21241 | item in the list, that recipient is quietly discarded. If all recipients are |
| 21242 | discarded, no message is created. This applies both when the recipients are |
| 21243 | generated by a filter and when they are specified in the transport. |
| 21244 | |
| 21245 | +------------------------------------------------+ |
| 21246 | |once|Use: autoreply|Type: string*|Default: unset| |
| 21247 | +------------------------------------------------+ |
| 21248 | |
| 21249 | This option names a file or DBM database in which a record of each To: |
| 21250 | recipient is kept when the message is specified by the transport. Note: This |
| 21251 | does not apply to Cc: or Bcc: recipients. |
| 21252 | |
| 21253 | If once is unset, or is set to an empty string, the message is always sent. By |
| 21254 | default, if once is set to a non-empty file name, the message is not sent if a |
| 21255 | potential recipient is already listed in the database. However, if the |
| 21256 | once_repeat option specifies a time greater than zero, the message is sent if |
| 21257 | that much time has elapsed since a message was last sent to this recipient. A |
| 21258 | setting of zero time for once_repeat (the default) prevents a message from |
| 21259 | being sent a second time - in this case, zero means infinity. |
| 21260 | |
| 21261 | If once_file_size is zero, a DBM database is used to remember recipients, and |
| 21262 | it is allowed to grow as large as necessary. If once_file_size is set greater |
| 21263 | than zero, it changes the way Exim implements the once option. Instead of using |
| 21264 | a DBM file to record every recipient it sends to, it uses a regular file, whose |
| 21265 | size will never get larger than the given value. |
| 21266 | |
| 21267 | In the file, Exim keeps a linear list of recipient addresses and the times at |
| 21268 | which they were sent messages. If the file is full when a new address needs to |
| 21269 | be added, the oldest address is dropped. If once_repeat is not set, this means |
| 21270 | that a given recipient may receive multiple messages, but at unpredictable |
| 21271 | intervals that depend on the rate of turnover of addresses in the file. If |
| 21272 | once_repeat is set, it specifies a maximum time between repeats. |
| 21273 | |
| 21274 | +------------------------------------------------------+ |
| 21275 | |once_file_size|Use: autoreply|Type: integer|Default: 0| |
| 21276 | +------------------------------------------------------+ |
| 21277 | |
| 21278 | See once above. |
| 21279 | |
| 21280 | +--------------------------------------------------+ |
| 21281 | |once_repeat|Use: autoreply|Type: time*|Default: 0s| |
| 21282 | +--------------------------------------------------+ |
| 21283 | |
| 21284 | See once above. After expansion, the value of this option must be a valid time |
| 21285 | value. |
| 21286 | |
| 21287 | +----------------------------------------------------+ |
| 21288 | |reply_to|Use: autoreply|Type: string*|Default: unset| |
| 21289 | +----------------------------------------------------+ |
| 21290 | |
| 21291 | This specifies the contents of the Reply-To: header when the message is |
| 21292 | specified by the transport. |
| 21293 | |
| 21294 | +----------------------------------------------------------+ |
| 21295 | |return_message|Use: autoreply|Type: boolean|Default: false| |
| 21296 | +----------------------------------------------------------+ |
| 21297 | |
| 21298 | If this is set, a copy of the original message is returned with the new |
| 21299 | message, subject to the maximum size set in the return_size_limit global |
| 21300 | configuration option. |
| 21301 | |
| 21302 | +---------------------------------------------------+ |
| 21303 | |subject|Use: autoreply|Type: string*|Default: unset| |
| 21304 | +---------------------------------------------------+ |
| 21305 | |
| 21306 | This specifies the contents of the Subject: header when the message is |
| 21307 | specified by the transport. It is tempting to quote the original subject in |
| 21308 | automatic responses. For example: |
| 21309 | |
| 21310 | subject = Re: $h_subject: |
| 21311 | |
| 21312 | There is a danger in doing this, however. It may allow a third party to |
| 21313 | subscribe your users to an opt-in mailing list, provided that the list accepts |
| 21314 | bounce messages as subscription confirmations. Well-managed lists require a |
| 21315 | non-bounce message to confirm a subscription, so the danger is relatively |
| 21316 | small. |
| 21317 | |
| 21318 | +------------------------------------------------+ |
| 21319 | |text|Use: autoreply|Type: string*|Default: unset| |
| 21320 | +------------------------------------------------+ |
| 21321 | |
| 21322 | This specifies a single string to be used as the body of the message when the |
| 21323 | message is specified by the transport. If both text and file are set, the text |
| 21324 | comes first. |
| 21325 | |
| 21326 | +----------------------------------------------+ |
| 21327 | |to|Use: autoreply|Type: string*|Default: unset| |
| 21328 | +----------------------------------------------+ |
| 21329 | |
| 21330 | This specifies recipients of the message and the contents of the To: header |
| 21331 | when the message is specified by the transport. |
| 21332 | |
| 21333 | |
| 21334 | |
| 21335 | =============================================================================== |
| 21336 | 28. THE LMTP TRANSPORT |
| 21337 | |
| 21338 | The lmtp transport runs the LMTP protocol (RFC 2033) over a pipe to a specified |
| 21339 | command or by interacting with a Unix domain socket. This transport is |
| 21340 | something of a cross between the pipe and smtp transports. Exim also has |
| 21341 | support for using LMTP over TCP/IP; this is implemented as an option for the |
| 21342 | smtp transport. Because LMTP is expected to be of minority interest, the |
| 21343 | default build-time configure in src/EDITME has it commented out. You need to |
| 21344 | ensure that |
| 21345 | |
| 21346 | TRANSPORT_LMTP=yes |
| 21347 | |
| 21348 | is present in your Local/Makefile in order to have the lmtp transport included |
| 21349 | in the Exim binary. The private options of the lmtp transport are as follows: |
| 21350 | |
| 21351 | +-----------------------------------------------+ |
| 21352 | |batch_id|Use: lmtp|Type: string*|Default: unset| |
| 21353 | +-----------------------------------------------+ |
| 21354 | |
| 21355 | See the description of local delivery batching in chapter 25. |
| 21356 | |
| 21357 | +--------------------------------------------+ |
| 21358 | |batch_max|Use: lmtp|Type: integer|Default: 1| |
| 21359 | +--------------------------------------------+ |
| 21360 | |
| 21361 | This limits the number of addresses that can be handled in a single delivery. |
| 21362 | Most LMTP servers can handle several addresses at once, so it is normally a |
| 21363 | good idea to increase this value. See the description of local delivery |
| 21364 | batching in chapter 25. |
| 21365 | |
| 21366 | +----------------------------------------------+ |
| 21367 | |command|Use: lmtp|Type: string*|Default: unset| |
| 21368 | +----------------------------------------------+ |
| 21369 | |
| 21370 | This option must be set if socket is not set. The string is a command which is |
| 21371 | run in a separate process. It is split up into a command name and list of |
| 21372 | arguments, each of which is separately expanded (so expansion cannot change the |
| 21373 | number of arguments). The command is run directly, not via a shell. The message |
| 21374 | is passed to the new process using the standard input and output to operate the |
| 21375 | LMTP protocol. |
| 21376 | |
| 21377 | +---------------------------------------------------+ |
| 21378 | |ignore_quota|Use: lmtp|Type: boolean|Default: false| |
| 21379 | +---------------------------------------------------+ |
| 21380 | |
| 21381 | If this option is set true, the string "IGNOREQUOTA" is added to RCPT commands, |
| 21382 | provided that the LMTP server has advertised support for IGNOREQUOTA in its |
| 21383 | response to the LHLO command. |
| 21384 | |
| 21385 | +---------------------------------------------+ |
| 21386 | |socket|Use: lmtp|Type: string*|Default: unset| |
| 21387 | +---------------------------------------------+ |
| 21388 | |
| 21389 | This option must be set if command is not set. The result of expansion must be |
| 21390 | the name of a Unix domain socket. The transport connects to the socket and |
| 21391 | delivers the message to it using the LMTP protocol. |
| 21392 | |
| 21393 | +----------------------------------------+ |
| 21394 | |timeout|Use: lmtp|Type: time|Default: 5m| |
| 21395 | +----------------------------------------+ |
| 21396 | |
| 21397 | The transport is aborted if the created process or Unix domain socket does not |
| 21398 | respond to LMTP commands or message input within this timeout. Delivery is |
| 21399 | deferred, and will be tried again later. Here is an example of a typical LMTP |
| 21400 | transport: |
| 21401 | |
| 21402 | lmtp: |
| 21403 | driver = lmtp |
| 21404 | command = /some/local/lmtp/delivery/program |
| 21405 | batch_max = 20 |
| 21406 | user = exim |
| 21407 | |
| 21408 | This delivers up to 20 addresses at a time, in a mixture of domains if |
| 21409 | necessary, running as the user exim. |
| 21410 | |
| 21411 | |
| 21412 | |
| 21413 | =============================================================================== |
| 21414 | 29. THE PIPE TRANSPORT |
| 21415 | |
| 21416 | The pipe transport is used to deliver messages via a pipe to a command running |
| 21417 | in another process. One example is the use of pipe as a pseudo-remote transport |
| 21418 | for passing messages to some other delivery mechanism (such as UUCP). Another |
| 21419 | is the use by individual users to automatically process their incoming |
| 21420 | messages. The pipe transport can be used in one of the following ways: |
| 21421 | |
| 21422 | * A router routes one address to a transport in the normal way, and the |
| 21423 | transport is configured as a pipe transport. In this case, $local_part |
| 21424 | contains the local part of the address (as usual), and the command that is |
| 21425 | run is specified by the command option on the transport. |
| 21426 | |
| 21427 | * If the batch_max option is set greater than 1 (the default is 1), the |
| 21428 | transport can handle more than one address in a single run. In this case, |
| 21429 | when more than one address is routed to the transport, $local_part is not |
| 21430 | set (because it is not unique). However, the pseudo-variable |
| 21431 | $pipe_addresses (described in section 29.3 below) contains all the |
| 21432 | addresses that are routed to the transport. |
| 21433 | |
| 21434 | * A router redirects an address directly to a pipe command (for example, from |
| 21435 | an alias or forward file). In this case, $address_pipe contains the text of |
| 21436 | the pipe command, and the command option on the transport is ignored unless |
| 21437 | force_command is set. If only one address is being transported (batch_max |
| 21438 | is not greater than one, or only one address was redirected to this pipe |
| 21439 | command), $local_part contains the local part that was redirected. |
| 21440 | |
| 21441 | The pipe transport is a non-interactive delivery method. Exim can also deliver |
| 21442 | messages over pipes using the LMTP interactive protocol. This is implemented by |
| 21443 | the lmtp transport. |
| 21444 | |
| 21445 | In the case when pipe is run as a consequence of an entry in a local user's |
| 21446 | .forward file, the command runs under the uid and gid of that user. In other |
| 21447 | cases, the uid and gid have to be specified explicitly, either on the transport |
| 21448 | or on the router that handles the address. Current and "home" directories are |
| 21449 | also controllable. See chapter 23 for details of the local delivery environment |
| 21450 | and chapter 25 for a discussion of local delivery batching. |
| 21451 | |
| 21452 | |
| 21453 | 29.1 Concurrent delivery |
| 21454 | ------------------------ |
| 21455 | |
| 21456 | If two messages arrive at almost the same time, and both are routed to a pipe |
| 21457 | delivery, the two pipe transports may be run concurrently. You must ensure that |
| 21458 | any pipe commands you set up are robust against this happening. If the commands |
| 21459 | write to a file, the exim_lock utility might be of use. Alternatively the |
| 21460 | max_parallel option could be used with a value of "1" to enforce serialization. |
| 21461 | |
| 21462 | |
| 21463 | 29.2 Returned status and data |
| 21464 | ----------------------------- |
| 21465 | |
| 21466 | If the command exits with a non-zero return code, the delivery is deemed to |
| 21467 | have failed, unless either the ignore_status option is set (in which case the |
| 21468 | return code is treated as zero), or the return code is one of those listed in |
| 21469 | the temp_errors option, which are interpreted as meaning "try again later". In |
| 21470 | this case, delivery is deferred. Details of a permanent failure are logged, but |
| 21471 | are not included in the bounce message, which merely contains "local delivery |
| 21472 | failed". |
| 21473 | |
| 21474 | If the command exits on a signal and the freeze_signal option is set then the |
| 21475 | message will be frozen in the queue. If that option is not set, a bounce will |
| 21476 | be sent as normal. |
| 21477 | |
| 21478 | If the return code is greater than 128 and the command being run is a shell |
| 21479 | script, it normally means that the script was terminated by a signal whose |
| 21480 | value is the return code minus 128. The freeze_signal option does not apply in |
| 21481 | this case. |
| 21482 | |
| 21483 | If Exim is unable to run the command (that is, if execve() fails), the return |
| 21484 | code is set to 127. This is the value that a shell returns if it is asked to |
| 21485 | run a non-existent command. The wording for the log line suggests that a |
| 21486 | non-existent command may be the problem. |
| 21487 | |
| 21488 | The return_output option can affect the result of a pipe delivery. If it is set |
| 21489 | and the command produces any output on its standard output or standard error |
| 21490 | streams, the command is considered to have failed, even if it gave a zero |
| 21491 | return code or if ignore_status is set. The output from the command is included |
| 21492 | as part of the bounce message. The return_fail_output option is similar, except |
| 21493 | that output is returned only when the command exits with a failure return code, |
| 21494 | that is, a value other than zero or a code that matches temp_errors. |
| 21495 | |
| 21496 | |
| 21497 | 29.3 How the command is run |
| 21498 | --------------------------- |
| 21499 | |
| 21500 | The command line is (by default) broken down into a command name and arguments |
| 21501 | by the pipe transport itself. The allow_commands and restrict_to_path options |
| 21502 | can be used to restrict the commands that may be run. |
| 21503 | |
| 21504 | Unquoted arguments are delimited by white space. If an argument appears in |
| 21505 | double quotes, backslash is interpreted as an escape character in the usual |
| 21506 | way. If an argument appears in single quotes, no escaping is done. |
| 21507 | |
| 21508 | String expansion is applied to the command line except when it comes from a |
| 21509 | traditional .forward file (commands from a filter file are expanded). The |
| 21510 | expansion is applied to each argument in turn rather than to the whole line. |
| 21511 | For this reason, any string expansion item that contains white space must be |
| 21512 | quoted so as to be contained within a single argument. A setting such as |
| 21513 | |
| 21514 | command = /some/path ${if eq{$local_part}{postmaster}{xx}{yy}} |
| 21515 | |
| 21516 | will not work, because the expansion item gets split between several arguments. |
| 21517 | You have to write |
| 21518 | |
| 21519 | command = /some/path "${if eq{$local_part}{postmaster}{xx}{yy}}" |
| 21520 | |
| 21521 | to ensure that it is all in one argument. The expansion is done in this way, |
| 21522 | argument by argument, so that the number of arguments cannot be changed as a |
| 21523 | result of expansion, and quotes or backslashes in inserted variables do not |
| 21524 | interact with external quoting. However, this leads to problems if you want to |
| 21525 | generate multiple arguments (or the command name plus arguments) from a single |
| 21526 | expansion. In this situation, the simplest solution is to use a shell. For |
| 21527 | example: |
| 21528 | |
| 21529 | command = /bin/sh -c ${lookup{$local_part}lsearch{/some/file}} |
| 21530 | |
| 21531 | Special handling takes place when an argument consists of precisely the text |
| 21532 | "$pipe_addresses". This is not a general expansion variable; the only place |
| 21533 | this string is recognized is when it appears as an argument for a pipe or |
| 21534 | transport filter command. It causes each address that is being handled to be |
| 21535 | inserted in the argument list at that point as a separate argument. This avoids |
| 21536 | any problems with spaces or shell metacharacters, and is of use when a pipe |
| 21537 | transport is handling groups of addresses in a batch. |
| 21538 | |
| 21539 | If force_command is enabled on the transport, Special handling takes place for |
| 21540 | an argument that consists of precisely the text "$address_pipe". It is handled |
| 21541 | similarly to $pipe_addresses above. It is expanded and each argument is |
| 21542 | inserted in the argument list at that point as a separate argument. The |
| 21543 | "$address_pipe" item does not need to be the only item in the argument; in |
| 21544 | fact, if it were then force_command should behave as a no-op. Rather, it should |
| 21545 | be used to adjust the command run while preserving the argument vector |
| 21546 | separation. |
| 21547 | |
| 21548 | After splitting up into arguments and expansion, the resulting command is run |
| 21549 | in a subprocess directly from the transport, not under a shell. The message |
| 21550 | that is being delivered is supplied on the standard input, and the standard |
| 21551 | output and standard error are both connected to a single pipe that is read by |
| 21552 | Exim. The max_output option controls how much output the command may produce, |
| 21553 | and the return_output and return_fail_output options control what is done with |
| 21554 | it. |
| 21555 | |
| 21556 | Not running the command under a shell (by default) lessens the security risks |
| 21557 | in cases when a command from a user's filter file is built out of data that was |
| 21558 | taken from an incoming message. If a shell is required, it can of course be |
| 21559 | explicitly specified as the command to be run. However, there are circumstances |
| 21560 | where existing commands (for example, in .forward files) expect to be run under |
| 21561 | a shell and cannot easily be modified. To allow for these cases, there is an |
| 21562 | option called use_shell, which changes the way the pipe transport works. |
| 21563 | Instead of breaking up the command line as just described, it expands it as a |
| 21564 | single string and passes the result to /bin/sh. The restrict_to_path option and |
| 21565 | the $pipe_addresses facility cannot be used with use_shell, and the whole |
| 21566 | mechanism is inherently less secure. |
| 21567 | |
| 21568 | |
| 21569 | 29.4 Environment variables |
| 21570 | -------------------------- |
| 21571 | |
| 21572 | The environment variables listed below are set up when the command is invoked. |
| 21573 | This list is a compromise for maximum compatibility with other MTAs. Note that |
| 21574 | the environment option can be used to add additional variables to this |
| 21575 | environment. The environment for the pipe transport is not subject to the |
| 21576 | add_environment and keep_environment main config options. |
| 21577 | |
| 21578 | DOMAIN the domain of the address |
| 21579 | HOME the home directory, if set |
| 21580 | HOST the host name when called from a router (see below) |
| 21581 | LOCAL_PART see below |
| 21582 | LOCAL_PART_PREFIX see below |
| 21583 | LOCAL_PART_SUFFIX see below |
| 21584 | LOGNAME see below |
| 21585 | MESSAGE_ID Exim's local ID for the message |
| 21586 | PATH as specified by the path option below |
| 21587 | QUALIFY_DOMAIN the sender qualification domain |
| 21588 | RECIPIENT the complete recipient address |
| 21589 | SENDER the sender of the message (empty if a bounce) |
| 21590 | SHELL /bin/sh |
| 21591 | TZ the value of the timezone option, if set |
| 21592 | USER see below |
| 21593 | |
| 21594 | When a pipe transport is called directly from (for example) an accept router, |
| 21595 | LOCAL_PART is set to the local part of the address. When it is called as a |
| 21596 | result of a forward or alias expansion, LOCAL_PART is set to the local part of |
| 21597 | the address that was expanded. In both cases, any affixes are removed from the |
| 21598 | local part, and made available in LOCAL_PART_PREFIX and LOCAL_PART_SUFFIX, |
| 21599 | respectively. LOGNAME and USER are set to the same value as LOCAL_PART for |
| 21600 | compatibility with other MTAs. |
| 21601 | |
| 21602 | HOST is set only when a pipe transport is called from a router that associates |
| 21603 | hosts with an address, typically when using pipe as a pseudo-remote transport. |
| 21604 | HOST is set to the first host name specified by the router. |
| 21605 | |
| 21606 | If the transport's generic home_directory option is set, its value is used for |
| 21607 | the HOME environment variable. Otherwise, a home directory may be set by the |
| 21608 | router's transport_home_directory option, which defaults to the user's home |
| 21609 | directory if check_local_user is set. |
| 21610 | |
| 21611 | |
| 21612 | 29.5 Private options for pipe |
| 21613 | ----------------------------- |
| 21614 | |
| 21615 | +----------------------------------------------------------+ |
| 21616 | |allow_commands|Use: pipe|Type: string list*|Default: unset| |
| 21617 | +----------------------------------------------------------+ |
| 21618 | |
| 21619 | The string is expanded, and is then interpreted as a colon-separated list of |
| 21620 | permitted commands. If restrict_to_path is not set, the only commands permitted |
| 21621 | are those in the allow_commands list. They need not be absolute paths; the path |
| 21622 | option is still used for relative paths. If restrict_to_path is set with |
| 21623 | allow_commands, the command must either be in the allow_commands list, or a |
| 21624 | name without any slashes that is found on the path. In other words, if neither |
| 21625 | allow_commands nor restrict_to_path is set, there is no restriction on the |
| 21626 | command, but otherwise only commands that are permitted by one or the other are |
| 21627 | allowed. For example, if |
| 21628 | |
| 21629 | allow_commands = /usr/bin/vacation |
| 21630 | |
| 21631 | and restrict_to_path is not set, the only permitted command is /usr/bin/ |
| 21632 | vacation. The allow_commands option may not be set if use_shell is set. |
| 21633 | |
| 21634 | +-----------------------------------------------+ |
| 21635 | |batch_id|Use: pipe|Type: string*|Default: unset| |
| 21636 | +-----------------------------------------------+ |
| 21637 | |
| 21638 | See the description of local delivery batching in chapter 25. |
| 21639 | |
| 21640 | +--------------------------------------------+ |
| 21641 | |batch_max|Use: pipe|Type: integer|Default: 1| |
| 21642 | +--------------------------------------------+ |
| 21643 | |
| 21644 | This limits the number of addresses that can be handled in a single delivery. |
| 21645 | See the description of local delivery batching in chapter 25. |
| 21646 | |
| 21647 | +--------------------------------------------------+ |
| 21648 | |check_string|Use: pipe|Type: string|Default: unset| |
| 21649 | +--------------------------------------------------+ |
| 21650 | |
| 21651 | As pipe writes the message, the start of each line is tested for matching |
| 21652 | check_string, and if it does, the initial matching characters are replaced by |
| 21653 | the contents of escape_string, provided both are set. The value of check_string |
| 21654 | is a literal string, not a regular expression, and the case of any letters it |
| 21655 | contains is significant. When use_bsmtp is set, the contents of check_string |
| 21656 | and escape_string are forced to values that implement the SMTP escaping |
| 21657 | protocol. Any settings made in the configuration file are ignored. |
| 21658 | |
| 21659 | +----------------------------------------------+ |
| 21660 | |command|Use: pipe|Type: string*|Default: unset| |
| 21661 | +----------------------------------------------+ |
| 21662 | |
| 21663 | This option need not be set when pipe is being used to deliver to pipes |
| 21664 | obtained directly from address redirections. In other cases, the option must be |
| 21665 | set, to provide a command to be run. It need not yield an absolute path (see |
| 21666 | the path option below). The command is split up into separate arguments by |
| 21667 | Exim, and each argument is separately expanded, as described in section 29.3 |
| 21668 | above. |
| 21669 | |
| 21670 | +--------------------------------------------------+ |
| 21671 | |environment|Use: pipe|Type: string*|Default: unset| |
| 21672 | +--------------------------------------------------+ |
| 21673 | |
| 21674 | This option is used to add additional variables to the environment in which the |
| 21675 | command runs (see section 29.4 for the default list). Its value is a string |
| 21676 | which is expanded, and then interpreted as a colon-separated list of |
| 21677 | environment settings of the form <name>=<value>. |
| 21678 | |
| 21679 | +---------------------------------------------------+ |
| 21680 | |escape_string|Use: pipe|Type: string|Default: unset| |
| 21681 | +---------------------------------------------------+ |
| 21682 | |
| 21683 | See check_string above. |
| 21684 | |
| 21685 | +-------------------------------------------------------+ |
| 21686 | |freeze_exec_fail|Use: pipe|Type: boolean|Default: false| |
| 21687 | +-------------------------------------------------------+ |
| 21688 | |
| 21689 | Failure to exec the command in a pipe transport is by default treated like any |
| 21690 | other failure while running the command. However, if freeze_exec_fail is set, |
| 21691 | failure to exec is treated specially, and causes the message to be frozen, |
| 21692 | whatever the setting of ignore_status. |
| 21693 | |
| 21694 | +----------------------------------------------------+ |
| 21695 | |freeze_signal|Use: pipe|Type: boolean|Default: false| |
| 21696 | +----------------------------------------------------+ |
| 21697 | |
| 21698 | Normally if the process run by a command in a pipe transport exits on a signal, |
| 21699 | a bounce message is sent. If freeze_signal is set, the message will be frozen |
| 21700 | in Exim's queue instead. |
| 21701 | |
| 21702 | +----------------------------------------------------+ |
| 21703 | |force_command|Use: pipe|Type: boolean|Default: false| |
| 21704 | +----------------------------------------------------+ |
| 21705 | |
| 21706 | Normally when a router redirects an address directly to a pipe command the |
| 21707 | command option on the transport is ignored. If force_command is set, the |
| 21708 | command option will used. This is especially useful for forcing a wrapper or |
| 21709 | additional argument to be added to the command. For example: |
| 21710 | |
| 21711 | command = /usr/bin/remote_exec myhost -- $address_pipe |
| 21712 | force_command |
| 21713 | |
| 21714 | Note that $address_pipe is handled specially in command when force_command is |
| 21715 | set, expanding out to the original argument vector as separate items, similarly |
| 21716 | to a Unix shell ""$@"" construct. |
| 21717 | |
| 21718 | +----------------------------------------------------+ |
| 21719 | |ignore_status|Use: pipe|Type: boolean|Default: false| |
| 21720 | +----------------------------------------------------+ |
| 21721 | |
| 21722 | If this option is true, the status returned by the subprocess that is set up to |
| 21723 | run the command is ignored, and Exim behaves as if zero had been returned. |
| 21724 | Otherwise, a non-zero status or termination by signal causes an error return |
| 21725 | from the transport unless the status value is one of those listed in |
| 21726 | temp_errors; these cause the delivery to be deferred and tried again later. |
| 21727 | |
| 21728 | Note: This option does not apply to timeouts, which do not return a status. See |
| 21729 | the timeout_defer option for how timeouts are handled. |
| 21730 | |
| 21731 | +-------------------------------------------------------+ |
| 21732 | |log_defer_output|Use: pipe|Type: boolean|Default: false| |
| 21733 | +-------------------------------------------------------+ |
| 21734 | |
| 21735 | If this option is set, and the status returned by the command is one of the |
| 21736 | codes listed in temp_errors (that is, delivery was deferred), and any output |
| 21737 | was produced on stdout or stderr, the first line of it is written to the main |
| 21738 | log. |
| 21739 | |
| 21740 | +------------------------------------------------------+ |
| 21741 | |log_fail_output|Use: pipe|Type: boolean|Default: false| |
| 21742 | +------------------------------------------------------+ |
| 21743 | |
| 21744 | If this option is set, and the command returns any output on stdout or stderr, |
| 21745 | and also ends with a return code that is neither zero nor one of the return |
| 21746 | codes listed in temp_errors (that is, the delivery failed), the first line of |
| 21747 | output is written to the main log. This option and log_output are mutually |
| 21748 | exclusive. Only one of them may be set. |
| 21749 | |
| 21750 | +-------------------------------------------------+ |
| 21751 | |log_output|Use: pipe|Type: boolean|Default: false| |
| 21752 | +-------------------------------------------------+ |
| 21753 | |
| 21754 | If this option is set and the command returns any output on stdout or stderr, |
| 21755 | the first line of output is written to the main log, whatever the return code. |
| 21756 | This option and log_fail_output are mutually exclusive. Only one of them may be |
| 21757 | set. |
| 21758 | |
| 21759 | +-----------------------------------------------+ |
| 21760 | |max_output|Use: pipe|Type: integer|Default: 20K| |
| 21761 | +-----------------------------------------------+ |
| 21762 | |
| 21763 | This specifies the maximum amount of output that the command may produce on its |
| 21764 | standard output and standard error file combined. If the limit is exceeded, the |
| 21765 | process running the command is killed. This is intended as a safety measure to |
| 21766 | catch runaway processes. The limit is applied independently of the settings of |
| 21767 | the options that control what is done with such output (for example, |
| 21768 | return_output). Because of buffering effects, the amount of output may exceed |
| 21769 | the limit by a small amount before Exim notices. |
| 21770 | |
| 21771 | +---------------------------------------------------------+ |
| 21772 | |message_prefix|Use: pipe|Type: string*|Default: see below| |
| 21773 | +---------------------------------------------------------+ |
| 21774 | |
| 21775 | The string specified here is expanded and output at the start of every message. |
| 21776 | The default is unset if use_bsmtp is set. Otherwise it is |
| 21777 | |
| 21778 | message_prefix = \ |
| 21779 | From ${if def:return_path{$return_path}{MAILER-DAEMON}}\ |
| 21780 | ${tod_bsdinbox}\n |
| 21781 | |
| 21782 | This is required by the commonly used /usr/bin/vacation program. However, it |
| 21783 | must not be present if delivery is to the Cyrus IMAP server, or to the tmail |
| 21784 | local delivery agent. The prefix can be suppressed by setting |
| 21785 | |
| 21786 | message_prefix = |
| 21787 | |
| 21788 | Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\ |
| 21789 | n" in message_prefix. |
| 21790 | |
| 21791 | +---------------------------------------------------------+ |
| 21792 | |message_suffix|Use: pipe|Type: string*|Default: see below| |
| 21793 | +---------------------------------------------------------+ |
| 21794 | |
| 21795 | The string specified here is expanded and output at the end of every message. |
| 21796 | The default is unset if use_bsmtp is set. Otherwise it is a single newline. The |
| 21797 | suffix can be suppressed by setting |
| 21798 | |
| 21799 | message_suffix = |
| 21800 | |
| 21801 | Note: If you set use_crlf true, you must change any occurrences of "\n" to "\r\ |
| 21802 | n" in message_suffix. |
| 21803 | |
| 21804 | +---------------------------------------------------+ |
| 21805 | |path|Use: pipe|Type: string*|Default: /bin:/usr/bin| |
| 21806 | +---------------------------------------------------+ |
| 21807 | |
| 21808 | This option is expanded and |
| 21809 | |
| 21810 | specifies the string that is set up in the PATH environment variable of the |
| 21811 | subprocess. If the command option does not yield an absolute path name, the |
| 21812 | command is sought in the PATH directories, in the usual way. Warning: This does |
| 21813 | not apply to a command specified as a transport filter. |
| 21814 | |
| 21815 | +------------------------------------------------------+ |
| 21816 | |permit_coredump|Use: pipe|Type: boolean|Default: false| |
| 21817 | +------------------------------------------------------+ |
| 21818 | |
| 21819 | Normally Exim inhibits core-dumps during delivery. If you have a need to get a |
| 21820 | core-dump of a pipe command, enable this command. This enables core-dumps |
| 21821 | during delivery and affects both the Exim binary and the pipe command run. It |
| 21822 | is recommended that this option remain off unless and until you have a need for |
| 21823 | it and that this only be enabled when needed, as the risk of excessive resource |
| 21824 | consumption can be quite high. Note also that Exim is typically installed as a |
| 21825 | setuid binary and most operating systems will inhibit coredumps of these by |
| 21826 | default, so further OS-specific action may be required. |
| 21827 | |
| 21828 | +------------------------------------------------------+ |
| 21829 | |pipe_as_creator|Use: pipe|Type: boolean|Default: false| |
| 21830 | +------------------------------------------------------+ |
| 21831 | |
| 21832 | If the generic user option is not set and this option is true, the delivery |
| 21833 | process is run under the uid that was in force when Exim was originally called |
| 21834 | to accept the message. If the group id is not otherwise set (via the generic |
| 21835 | group option), the gid that was in force when Exim was originally called to |
| 21836 | accept the message is used. |
| 21837 | |
| 21838 | +-------------------------------------------------------+ |
| 21839 | |restrict_to_path|Use: pipe|Type: boolean|Default: false| |
| 21840 | +-------------------------------------------------------+ |
| 21841 | |
| 21842 | When this option is set, any command name not listed in allow_commands must |
| 21843 | contain no slashes. The command is searched for only in the directories listed |
| 21844 | in the path option. This option is intended for use in the case when a pipe |
| 21845 | command has been generated from a user's .forward file. This is usually handled |
| 21846 | by a pipe transport called address_pipe. |
| 21847 | |
| 21848 | +---------------------------------------------------------+ |
| 21849 | |return_fail_output|Use: pipe|Type: boolean|Default: false| |
| 21850 | +---------------------------------------------------------+ |
| 21851 | |
| 21852 | If this option is true, and the command produced any output and ended with a |
| 21853 | return code other than zero or one of the codes listed in temp_errors (that is, |
| 21854 | the delivery failed), the output is returned in the bounce message. However, if |
| 21855 | the message has a null sender (that is, it is itself a bounce message), output |
| 21856 | from the command is discarded. This option and return_output are mutually |
| 21857 | exclusive. Only one of them may be set. |
| 21858 | |
| 21859 | +----------------------------------------------------+ |
| 21860 | |return_output|Use: pipe|Type: boolean|Default: false| |
| 21861 | +----------------------------------------------------+ |
| 21862 | |
| 21863 | If this option is true, and the command produced any output, the delivery is |
| 21864 | deemed to have failed whatever the return code from the command, and the output |
| 21865 | is returned in the bounce message. Otherwise, the output is just discarded. |
| 21866 | However, if the message has a null sender (that is, it is a bounce message), |
| 21867 | output from the command is always discarded, whatever the setting of this |
| 21868 | option. This option and return_fail_output are mutually exclusive. Only one of |
| 21869 | them may be set. |
| 21870 | |
| 21871 | +----------------------------------------------------------+ |
| 21872 | |temp_errors|Use: pipe|Type: string list|Default: see below| |
| 21873 | +----------------------------------------------------------+ |
| 21874 | |
| 21875 | This option contains either a colon-separated list of numbers, or a single |
| 21876 | asterisk. If ignore_status is false and return_output is not set, and the |
| 21877 | command exits with a non-zero return code, the failure is treated as temporary |
| 21878 | and the delivery is deferred if the return code matches one of the numbers, or |
| 21879 | if the setting is a single asterisk. Otherwise, non-zero return codes are |
| 21880 | treated as permanent errors. The default setting contains the codes defined by |
| 21881 | EX_TEMPFAIL and EX_CANTCREAT in sysexits.h. If Exim is compiled on a system |
| 21882 | that does not define these macros, it assumes values of 75 and 73, |
| 21883 | respectively. |
| 21884 | |
| 21885 | +----------------------------------------+ |
| 21886 | |timeout|Use: pipe|Type: time|Default: 1h| |
| 21887 | +----------------------------------------+ |
| 21888 | |
| 21889 | If the command fails to complete within this time, it is killed. This normally |
| 21890 | causes the delivery to fail (but see timeout_defer). A zero time interval |
| 21891 | specifies no timeout. In order to ensure that any subprocesses created by the |
| 21892 | command are also killed, Exim makes the initial process a process group leader, |
| 21893 | and kills the whole process group on a timeout. However, this can be defeated |
| 21894 | if one of the processes starts a new process group. |
| 21895 | |
| 21896 | +----------------------------------------------------+ |
| 21897 | |timeout_defer|Use: pipe|Type: boolean|Default: false| |
| 21898 | +----------------------------------------------------+ |
| 21899 | |
| 21900 | A timeout in a pipe transport, either in the command that the transport runs, |
| 21901 | or in a transport filter that is associated with it, is by default treated as a |
| 21902 | hard error, and the delivery fails. However, if timeout_defer is set true, both |
| 21903 | kinds of timeout become temporary errors, causing the delivery to be deferred. |
| 21904 | |
| 21905 | +------------------------------------------------+ |
| 21906 | |umask|Use: pipe|Type: octal integer|Default: 022| |
| 21907 | +------------------------------------------------+ |
| 21908 | |
| 21909 | This specifies the umask setting for the subprocess that runs the command. |
| 21910 | |
| 21911 | +------------------------------------------------+ |
| 21912 | |use_bsmtp|Use: pipe|Type: boolean|Default: false| |
| 21913 | +------------------------------------------------+ |
| 21914 | |
| 21915 | If this option is set true, the pipe transport writes messages in "batch SMTP" |
| 21916 | format, with the envelope sender and recipient(s) included as SMTP commands. If |
| 21917 | you want to include a leading HELO command with such messages, you can do so by |
| 21918 | setting the message_prefix option. See section 48.10 for details of batch SMTP. |
| 21919 | |
| 21920 | +---------------------------------------------------------+ |
| 21921 | |use_classresources|Use: pipe|Type: boolean|Default: false| |
| 21922 | +---------------------------------------------------------+ |
| 21923 | |
| 21924 | This option is available only when Exim is running on FreeBSD, NetBSD, or BSD/ |
| 21925 | OS. If it is set true, the setclassresources() function is used to set resource |
| 21926 | limits when a pipe transport is run to perform a delivery. The limits for the |
| 21927 | uid under which the pipe is to run are obtained from the login class database. |
| 21928 | |
| 21929 | +-----------------------------------------------+ |
| 21930 | |use_crlf|Use: pipe|Type: boolean|Default: false| |
| 21931 | +-----------------------------------------------+ |
| 21932 | |
| 21933 | This option causes lines to be terminated with the two-character CRLF sequence |
| 21934 | (carriage return, linefeed) instead of just a linefeed character. In the case |
| 21935 | of batched SMTP, the byte sequence written to the pipe is then an exact image |
| 21936 | of what would be sent down a real SMTP connection. |
| 21937 | |
| 21938 | The contents of the message_prefix and message_suffix options are written |
| 21939 | verbatim, so must contain their own carriage return characters if these are |
| 21940 | needed. When use_bsmtp is not set, the default values for both message_prefix |
| 21941 | and message_suffix end with a single linefeed, so their values must be changed |
| 21942 | to end with "\r\n" if use_crlf is set. |
| 21943 | |
| 21944 | +------------------------------------------------+ |
| 21945 | |use_shell|Use: pipe|Type: boolean|Default: false| |
| 21946 | +------------------------------------------------+ |
| 21947 | |
| 21948 | If this option is set, it causes the command to be passed to /bin/sh instead of |
| 21949 | being run directly from the transport, as described in section 29.3. This is |
| 21950 | less secure, but is needed in some situations where the command is expected to |
| 21951 | be run under a shell and cannot easily be modified. The allow_commands and |
| 21952 | restrict_to_path options, and the "$pipe_addresses" facility are incompatible |
| 21953 | with use_shell. The command is expanded as a single string, and handed to /bin/ |
| 21954 | sh as data for its -c option. |
| 21955 | |
| 21956 | |
| 21957 | 29.6 Using an external local delivery agent |
| 21958 | ------------------------------------------- |
| 21959 | |
| 21960 | The pipe transport can be used to pass all messages that require local delivery |
| 21961 | to a separate local delivery agent such as procmail. When doing this, care must |
| 21962 | be taken to ensure that the pipe is run under an appropriate uid and gid. In |
| 21963 | some configurations one wants this to be a uid that is trusted by the delivery |
| 21964 | agent to supply the correct sender of the message. It may be necessary to |
| 21965 | recompile or reconfigure the delivery agent so that it trusts an appropriate |
| 21966 | user. The following is an example transport and router configuration for |
| 21967 | procmail: |
| 21968 | |
| 21969 | # transport |
| 21970 | procmail_pipe: |
| 21971 | driver = pipe |
| 21972 | command = /usr/local/bin/procmail -d $local_part |
| 21973 | return_path_add |
| 21974 | delivery_date_add |
| 21975 | envelope_to_add |
| 21976 | check_string = "From " |
| 21977 | escape_string = ">From " |
| 21978 | umask = 077 |
| 21979 | user = $local_part |
| 21980 | group = mail |
| 21981 | |
| 21982 | # router |
| 21983 | procmail: |
| 21984 | driver = accept |
| 21985 | check_local_user |
| 21986 | transport = procmail_pipe |
| 21987 | |
| 21988 | In this example, the pipe is run as the local user, but with the group set to |
| 21989 | mail. An alternative is to run the pipe as a specific user such as mail or exim |
| 21990 | , but in this case you must arrange for procmail to trust that user to supply a |
| 21991 | correct sender address. If you do not specify either a group or a user option, |
| 21992 | the pipe command is run as the local user. The home directory is the user's |
| 21993 | home directory by default. |
| 21994 | |
| 21995 | Note: The command that the pipe transport runs does not begin with |
| 21996 | |
| 21997 | IFS=" " |
| 21998 | |
| 21999 | as shown in some procmail documentation, because Exim does not by default use a |
| 22000 | shell to run pipe commands. |
| 22001 | |
| 22002 | The next example shows a transport and a router for a system where local |
| 22003 | deliveries are handled by the Cyrus IMAP server. |
| 22004 | |
| 22005 | # transport |
| 22006 | local_delivery_cyrus: |
| 22007 | driver = pipe |
| 22008 | command = /usr/cyrus/bin/deliver \ |
| 22009 | -m ${substr_1:$local_part_suffix} -- $local_part |
| 22010 | user = cyrus |
| 22011 | group = mail |
| 22012 | return_output |
| 22013 | log_output |
| 22014 | message_prefix = |
| 22015 | message_suffix = |
| 22016 | |
| 22017 | # router |
| 22018 | local_user_cyrus: |
| 22019 | driver = accept |
| 22020 | check_local_user |
| 22021 | local_part_suffix = .* |
| 22022 | transport = local_delivery_cyrus |
| 22023 | |
| 22024 | Note the unsetting of message_prefix and message_suffix, and the use of |
| 22025 | return_output to cause any text written by Cyrus to be returned to the sender. |
| 22026 | |
| 22027 | |
| 22028 | |
| 22029 | =============================================================================== |
| 22030 | 30. THE SMTP TRANSPORT |
| 22031 | |
| 22032 | The smtp transport delivers messages over TCP/IP connections using the SMTP or |
| 22033 | LMTP protocol. The list of hosts to try can either be taken from the address |
| 22034 | that is being processed (having been set up by the router), or specified |
| 22035 | explicitly for the transport. Timeout and retry processing (see chapter 32) is |
| 22036 | applied to each IP address independently. |
| 22037 | |
| 22038 | |
| 22039 | 30.1 Multiple messages on a single connection |
| 22040 | --------------------------------------------- |
| 22041 | |
| 22042 | The sending of multiple messages over a single TCP/IP connection can arise in |
| 22043 | two ways: |
| 22044 | |
| 22045 | * If a message contains more than max_rcpt (see below) addresses that are |
| 22046 | routed to the same host, more than one copy of the message has to be sent |
| 22047 | to that host. In this situation, multiple copies may be sent in a single |
| 22048 | run of the smtp transport over a single TCP/IP connection. (What Exim |
| 22049 | actually does when it has too many addresses to send in one message also |
| 22050 | depends on the value of the global remote_max_parallel option. Details are |
| 22051 | given in section 48.1.) |
| 22052 | |
| 22053 | * When a message has been successfully delivered over a TCP/IP connection, |
| 22054 | Exim looks in its hints database to see if there are any other messages |
| 22055 | awaiting a connection to the same host. If there are, a new delivery |
| 22056 | process is started for one of them, and the current TCP/IP connection is |
| 22057 | passed on to it. The new process may in turn send multiple copies and |
| 22058 | possibly create yet another process. |
| 22059 | |
| 22060 | For each copy sent over the same TCP/IP connection, a sequence counter is |
| 22061 | incremented, and if it ever gets to the value of connection_max_messages, no |
| 22062 | further messages are sent over that connection. |
| 22063 | |
| 22064 | |
| 22065 | 30.2 Use of the $host and $host_address variables |
| 22066 | ------------------------------------------------- |
| 22067 | |
| 22068 | At the start of a run of the smtp transport, the values of $host and |
| 22069 | $host_address are the name and IP address of the first host on the host list |
| 22070 | passed by the router. However, when the transport is about to connect to a |
| 22071 | specific host, and while it is connected to that host, $host and $host_address |
| 22072 | are set to the values for that host. These are the values that are in force |
| 22073 | when the helo_data, hosts_try_auth, interface, serialize_hosts, and the various |
| 22074 | TLS options are expanded. |
| 22075 | |
| 22076 | |
| 22077 | 30.3 Use of $tls_cipher and $tls_peerdn |
| 22078 | --------------------------------------- |
| 22079 | |
| 22080 | At the start of a run of the smtp transport, the values of $tls_bits, |
| 22081 | $tls_cipher, $tls_peerdn and $tls_sni are the values that were set when the |
| 22082 | message was received. These are the values that are used for options that are |
| 22083 | expanded before any SMTP connections are made. Just before each connection is |
| 22084 | made, these four variables are emptied. If TLS is subsequently started, they |
| 22085 | are set to the appropriate values for the outgoing connection, and these are |
| 22086 | the values that are in force when any authenticators are run and when the |
| 22087 | authenticated_sender option is expanded. |
| 22088 | |
| 22089 | These variables are deprecated in favour of $tls_in_cipher et. al. and will be |
| 22090 | removed in a future release. |
| 22091 | |
| 22092 | |
| 22093 | 30.4 Private options for smtp |
| 22094 | ----------------------------- |
| 22095 | |
| 22096 | The private options of the smtp transport are as follows: |
| 22097 | |
| 22098 | +------------------------------------------------------------------+ |
| 22099 | |address_retry_include_sender|Use: smtp|Type: boolean|Default: true| |
| 22100 | +------------------------------------------------------------------+ |
| 22101 | |
| 22102 | When an address is delayed because of a 4xx response to a RCPT command, it is |
| 22103 | the combination of sender and recipient that is delayed in subsequent queue |
| 22104 | runs until the retry time is reached. You can delay the recipient without |
| 22105 | reference to the sender (which is what earlier versions of Exim did), by |
| 22106 | setting address_retry_include_sender false. However, this can lead to problems |
| 22107 | with servers that regularly issue 4xx responses to RCPT commands. |
| 22108 | |
| 22109 | +------------------------------------------------------+ |
| 22110 | |allow_localhost|Use: smtp|Type: boolean|Default: false| |
| 22111 | +------------------------------------------------------+ |
| 22112 | |
| 22113 | When a host specified in hosts or fallback_hosts (see below) turns out to be |
| 22114 | the local host, or is listed in hosts_treat_as_local, delivery is deferred by |
| 22115 | default. However, if allow_localhost is set, Exim goes on to do the delivery |
| 22116 | anyway. This should be used only in special cases when the configuration |
| 22117 | ensures that no looping will result (for example, a differently configured Exim |
| 22118 | is listening on the port to which the message is sent). |
| 22119 | |
| 22120 | +-----------------------------------------------------------+ |
| 22121 | |authenticated_sender|Use: smtp|Type: string*|Default: unset| |
| 22122 | +-----------------------------------------------------------+ |
| 22123 | |
| 22124 | When Exim has authenticated as a client, or if authenticated_sender_force is |
| 22125 | true, this option sets a value for the AUTH= item on outgoing MAIL commands, |
| 22126 | overriding any existing authenticated sender value. If the string expansion is |
| 22127 | forced to fail, the option is ignored. Other expansion failures cause delivery |
| 22128 | to be deferred. If the result of expansion is an empty string, that is also |
| 22129 | ignored. |
| 22130 | |
| 22131 | The expansion happens after the outgoing connection has been made and TLS |
| 22132 | started, if required. This means that the $host, $host_address, $tls_out_cipher |
| 22133 | , and $tls_out_peerdn variables are set according to the particular connection. |
| 22134 | |
| 22135 | If the SMTP session is not authenticated, the expansion of authenticated_sender |
| 22136 | still happens (and can cause the delivery to be deferred if it fails), but no |
| 22137 | AUTH= item is added to MAIL commands unless authenticated_sender_force is true. |
| 22138 | |
| 22139 | This option allows you to use the smtp transport in LMTP mode to deliver mail |
| 22140 | to Cyrus IMAP and provide the proper local part as the "authenticated sender", |
| 22141 | via a setting such as: |
| 22142 | |
| 22143 | authenticated_sender = $local_part |
| 22144 | |
| 22145 | This removes the need for IMAP subfolders to be assigned special ACLs to allow |
| 22146 | direct delivery to those subfolders. |
| 22147 | |
| 22148 | Because of expected uses such as that just described for Cyrus (when no domain |
| 22149 | is involved), there is no checking on the syntax of the provided value. |
| 22150 | |
| 22151 | +-----------------------------------------------------------------+ |
| 22152 | |authenticated_sender_force|Use: smtp|Type: boolean|Default: false| |
| 22153 | +-----------------------------------------------------------------+ |
| 22154 | |
| 22155 | If this option is set true, the authenticated_sender option's value is used for |
| 22156 | the AUTH= item on outgoing MAIL commands, even if Exim has not authenticated as |
| 22157 | a client. |
| 22158 | |
| 22159 | +------------------------------------------------+ |
| 22160 | |command_timeout|Use: smtp|Type: time|Default: 5m| |
| 22161 | +------------------------------------------------+ |
| 22162 | |
| 22163 | This sets a timeout for receiving a response to an SMTP command that has been |
| 22164 | sent out. It is also used when waiting for the initial banner line from the |
| 22165 | remote host. Its value must not be zero. |
| 22166 | |
| 22167 | +------------------------------------------------+ |
| 22168 | |connect_timeout|Use: smtp|Type: time|Default: 5m| |
| 22169 | +------------------------------------------------+ |
| 22170 | |
| 22171 | This sets a timeout for the connect() function, which sets up a TCP/IP call to |
| 22172 | a remote host. A setting of zero allows the system timeout (typically several |
| 22173 | minutes) to act. To have any effect, the value of this option must be less than |
| 22174 | the system timeout. However, it has been observed that on some systems there is |
| 22175 | no system timeout, which is why the default value for this option is 5 minutes, |
| 22176 | a value recommended by RFC 1123. |
| 22177 | |
| 22178 | +------------------------------------------------------------+ |
| 22179 | |connection_max_messages|Use: smtp|Type: integer|Default: 500| |
| 22180 | +------------------------------------------------------------+ |
| 22181 | |
| 22182 | This controls the maximum number of separate message deliveries that are sent |
| 22183 | over a single TCP/IP connection. If the value is zero, there is no limit. For |
| 22184 | testing purposes, this value can be overridden by the -oB command line option. |
| 22185 | |
| 22186 | +---------------------------------------------+ |
| 22187 | |data_timeout|Use: smtp|Type: time|Default: 5m| |
| 22188 | +---------------------------------------------+ |
| 22189 | |
| 22190 | This sets a timeout for the transmission of each block in the data portion of |
| 22191 | the message. As a result, the overall timeout for a message depends on the size |
| 22192 | of the message. Its value must not be zero. See also final_timeout. |
| 22193 | |
| 22194 | +--------------------------------------------------+ |
| 22195 | |dkim_domain|Use: smtp|Type: string*|Default: unset| |
| 22196 | +--------------------------------------------------+ |
| 22197 | |
| 22198 | +----------------------------------------------------+ |
| 22199 | |dkim_selector|Use: smtp|Type: string*|Default: unset| |
| 22200 | +----------------------------------------------------+ |
| 22201 | |
| 22202 | +-------------------------------------------------------+ |
| 22203 | |dkim_private_key|Use: smtp|Type: string*|Default: unset| |
| 22204 | +-------------------------------------------------------+ |
| 22205 | |
| 22206 | +-------------------------------------------------+ |
| 22207 | |dkim_canon|Use: smtp|Type: string*|Default: unset| |
| 22208 | +-------------------------------------------------+ |
| 22209 | |
| 22210 | +--------------------------------------------------+ |
| 22211 | |dkim_strict|Use: smtp|Type: string*|Default: unset| |
| 22212 | +--------------------------------------------------+ |
| 22213 | |
| 22214 | +--------------------------------------------------------+ |
| 22215 | |dkim_sign_headers|Use: smtp|Type: string*|Default: unset| |
| 22216 | +--------------------------------------------------------+ |
| 22217 | |
| 22218 | DKIM signing options. For details see section 57.1. |
| 22219 | |
| 22220 | +--------------------------------------------------------+ |
| 22221 | |delay_after_cutoff|Use: smtp|Type: boolean|Default: true| |
| 22222 | +--------------------------------------------------------+ |
| 22223 | |
| 22224 | This option controls what happens when all remote IP addresses for a given |
| 22225 | domain have been inaccessible for so long that they have passed their retry |
| 22226 | cutoff times. |
| 22227 | |
| 22228 | In the default state, if the next retry time has not been reached for any of |
| 22229 | them, the address is bounced without trying any deliveries. In other words, |
| 22230 | Exim delays retrying an IP address after the final cutoff time until a new |
| 22231 | retry time is reached, and can therefore bounce an address without ever trying |
| 22232 | a delivery, when machines have been down for a long time. Some people are |
| 22233 | unhappy at this prospect, so... |
| 22234 | |
| 22235 | If delay_after_cutoff is set false, Exim behaves differently. If all IP |
| 22236 | addresses are past their final cutoff time, Exim tries to deliver to those IP |
| 22237 | addresses that have not been tried since the message arrived. If there are |
| 22238 | none, of if they all fail, the address is bounced. In other words, it does not |
| 22239 | delay when a new message arrives, but immediately tries those expired IP |
| 22240 | addresses that haven't been tried since the message arrived. If there is a |
| 22241 | continuous stream of messages for the dead hosts, unsetting delay_after_cutoff |
| 22242 | means that there will be many more attempts to deliver to them. |
| 22243 | |
| 22244 | +--------------------------------------------------------+ |
| 22245 | |dns_qualify_single|Use: smtp|Type: boolean|Default: true| |
| 22246 | +--------------------------------------------------------+ |
| 22247 | |
| 22248 | If the hosts or fallback_hosts option is being used, and the gethostbyname |
| 22249 | option is false, the RES_DEFNAMES resolver option is set. See the |
| 22250 | qualify_single option in chapter 17 for more details. |
| 22251 | |
| 22252 | +---------------------------------------------------------+ |
| 22253 | |dns_search_parents|Use: smtp|Type: boolean|Default: false| |
| 22254 | +---------------------------------------------------------+ |
| 22255 | |
| 22256 | If the hosts or fallback_hosts option is being used, and the gethostbyname |
| 22257 | option is false, the RES_DNSRCH resolver option is set. See the search_parents |
| 22258 | option in chapter 17 for more details. |
| 22259 | |
| 22260 | +------------------------------------------------------------------+ |
| 22261 | |dnssec_request_domains|Use: smtp|Type: domain list*|Default: unset| |
| 22262 | +------------------------------------------------------------------+ |
| 22263 | |
| 22264 | DNS lookups for domains matching dnssec_request_domains will be done with the |
| 22265 | dnssec request bit set. This applies to all of the SRV, MX, AAAA, A lookup |
| 22266 | sequence. |
| 22267 | |
| 22268 | +------------------------------------------------------------------+ |
| 22269 | |dnssec_require_domains|Use: smtp|Type: domain list*|Default: unset| |
| 22270 | +------------------------------------------------------------------+ |
| 22271 | |
| 22272 | DNS lookups for domains matching dnssec_require_domains will be done with the |
| 22273 | dnssec request bit set. Any returns not having the Authenticated Data bit (AD |
| 22274 | bit) set will be ignored and logged as a host-lookup failure. This applies to |
| 22275 | all of the SRV, MX, AAAA, A lookup sequence. |
| 22276 | |
| 22277 | +-------------------------------------------+ |
| 22278 | |dscp|Use: smtp|Type: string*|Default: unset| |
| 22279 | +-------------------------------------------+ |
| 22280 | |
| 22281 | This option causes the DSCP value associated with a socket to be set to one of |
| 22282 | a number of fixed strings or to numeric value. The -bI:dscp option may be used |
| 22283 | to ask Exim which names it knows of. Common values include "throughput", |
| 22284 | "mincost", and on newer systems "ef", "af41", etc. Numeric values may be in the |
| 22285 | range 0 to 0x3F. |
| 22286 | |
| 22287 | The outbound packets from Exim will be marked with this value in the header |
| 22288 | (for IPv4, the TOS field; for IPv6, the TCLASS field); there is no guarantee |
| 22289 | that these values will have any effect, not be stripped by networking |
| 22290 | equipment, or do much of anything without cooperation with your Network |
| 22291 | Engineer and those of all network operators between the source and destination. |
| 22292 | |
| 22293 | +---------------------------------------------------------+ |
| 22294 | |fallback_hosts|Use: smtp|Type: string list|Default: unset| |
| 22295 | +---------------------------------------------------------+ |
| 22296 | |
| 22297 | String expansion is not applied to this option. The argument must be a |
| 22298 | colon-separated list of host names or IP addresses, optionally also including |
| 22299 | port numbers, though the separator can be changed, as described in section 6.20 |
| 22300 | . Each individual item in the list is the same as an item in a route_list |
| 22301 | setting for the manualroute router, as described in section 20.5. |
| 22302 | |
| 22303 | Fallback hosts can also be specified on routers, which associate them with the |
| 22304 | addresses they process. As for the hosts option without hosts_override, |
| 22305 | fallback_hosts specified on the transport is used only if the address does not |
| 22306 | have its own associated fallback host list. Unlike hosts, a setting of |
| 22307 | fallback_hosts on an address is not overridden by hosts_override. However, |
| 22308 | hosts_randomize does apply to fallback host lists. |
| 22309 | |
| 22310 | If Exim is unable to deliver to any of the hosts for a particular address, and |
| 22311 | the errors are not permanent rejections, the address is put on a separate |
| 22312 | transport queue with its host list replaced by the fallback hosts, unless the |
| 22313 | address was routed via MX records and the current host was in the original MX |
| 22314 | list. In that situation, the fallback host list is not used. |
| 22315 | |
| 22316 | Once normal deliveries are complete, the fallback queue is delivered by |
| 22317 | re-running the same transports with the new host lists. If several failing |
| 22318 | addresses have the same fallback hosts (and max_rcpt permits it), a single copy |
| 22319 | of the message is sent. |
| 22320 | |
| 22321 | The resolution of the host names on the fallback list is controlled by the |
| 22322 | gethostbyname option, as for the hosts option. Fallback hosts apply both to |
| 22323 | cases when the host list comes with the address and when it is taken from hosts |
| 22324 | . This option provides a "use a smart host only if delivery fails" facility. |
| 22325 | |
| 22326 | +-----------------------------------------------+ |
| 22327 | |final_timeout|Use: smtp|Type: time|Default: 10m| |
| 22328 | +-----------------------------------------------+ |
| 22329 | |
| 22330 | This is the timeout that applies while waiting for the response to the final |
| 22331 | line containing just "." that terminates a message. Its value must not be zero. |
| 22332 | |
| 22333 | +----------------------------------------------------+ |
| 22334 | |gethostbyname|Use: smtp|Type: boolean|Default: false| |
| 22335 | +----------------------------------------------------+ |
| 22336 | |
| 22337 | If this option is true when the hosts and/or fallback_hosts options are being |
| 22338 | used, names are looked up using gethostbyname() (or getipnodebyname() when |
| 22339 | available) instead of using the DNS. Of course, that function may in fact use |
| 22340 | the DNS, but it may also consult other sources of information such as /etc/ |
| 22341 | hosts. |
| 22342 | |
| 22343 | +---------------------------------------------------------+ |
| 22344 | |gnutls_compat_mode|Use: smtp|Type: boolean|Default: unset| |
| 22345 | +---------------------------------------------------------+ |
| 22346 | |
| 22347 | This option controls whether GnuTLS is used in compatibility mode in an Exim |
| 22348 | server. This reduces security slightly, but improves interworking with older |
| 22349 | implementations of TLS. |
| 22350 | |
| 22351 | +----------------------------------------------------+ |
| 22352 | |helo_data|Use: smtp|Type: string*|Default: see below| |
| 22353 | +----------------------------------------------------+ |
| 22354 | |
| 22355 | The value of this option is expanded after a connection to a another host has |
| 22356 | been set up. The result is used as the argument for the EHLO, HELO, or LHLO |
| 22357 | command that starts the outgoing SMTP or LMTP session. The default value of the |
| 22358 | option is: |
| 22359 | |
| 22360 | $primary_hostname |
| 22361 | |
| 22362 | During the expansion, the variables $host and $host_address are set to the |
| 22363 | identity of the remote host, and the variables $sending_ip_address and |
| 22364 | $sending_port are set to the local IP address and port number that are being |
| 22365 | used. These variables can be used to generate different values for different |
| 22366 | servers or different local IP addresses. For example, if you want the string |
| 22367 | that is used for helo_data to be obtained by a DNS lookup of the outgoing |
| 22368 | interface address, you could use this: |
| 22369 | |
| 22370 | helo_data = ${lookup dnsdb{ptr=$sending_ip_address}{$value}\ |
| 22371 | {$primary_hostname}} |
| 22372 | |
| 22373 | The use of helo_data applies both to sending messages and when doing callouts. |
| 22374 | |
| 22375 | +-------------------------------------------------+ |
| 22376 | |hosts|Use: smtp|Type: string list*|Default: unset| |
| 22377 | +-------------------------------------------------+ |
| 22378 | |
| 22379 | Hosts are associated with an address by a router such as dnslookup, which finds |
| 22380 | the hosts by looking up the address domain in the DNS, or by manualroute, which |
| 22381 | has lists of hosts in its configuration. However, email addresses can be passed |
| 22382 | to the smtp transport by any router, and not all of them can provide an |
| 22383 | associated list of hosts. |
| 22384 | |
| 22385 | The hosts option specifies a list of hosts to be used if the address being |
| 22386 | processed does not have any hosts associated with it. The hosts specified by |
| 22387 | hosts are also used, whether or not the address has its own hosts, if |
| 22388 | hosts_override is set. |
| 22389 | |
| 22390 | The string is first expanded, before being interpreted as a colon-separated |
| 22391 | list of host names or IP addresses, possibly including port numbers. The |
| 22392 | separator may be changed to something other than colon, as described in section |
| 22393 | 6.20. Each individual item in the list is the same as an item in a route_list |
| 22394 | setting for the manualroute router, as described in section 20.5. However, note |
| 22395 | that the "/MX" facility of the manualroute router is not available here. |
| 22396 | |
| 22397 | If the expansion fails, delivery is deferred. Unless the failure was caused by |
| 22398 | the inability to complete a lookup, the error is logged to the panic log as |
| 22399 | well as the main log. Host names are looked up either by searching directly for |
| 22400 | address records in the DNS or by calling gethostbyname() (or getipnodebyname() |
| 22401 | when available), depending on the setting of the gethostbyname option. When |
| 22402 | Exim is compiled with IPv6 support, if a host that is looked up in the DNS has |
| 22403 | both IPv4 and IPv6 addresses, both types of address are used. |
| 22404 | |
| 22405 | During delivery, the hosts are tried in order, subject to their retry status, |
| 22406 | unless hosts_randomize is set. |
| 22407 | |
| 22408 | +-----------------------------------------------------------+ |
| 22409 | |hosts_avoid_esmtp|Use: smtp|Type: host list*|Default: unset| |
| 22410 | +-----------------------------------------------------------+ |
| 22411 | |
| 22412 | This option is for use with broken hosts that announce ESMTP facilities (for |
| 22413 | example, PIPELINING) and then fail to implement them properly. When a host |
| 22414 | matches hosts_avoid_esmtp, Exim sends HELO rather than EHLO at the start of the |
| 22415 | SMTP session. This means that it cannot use any of the ESMTP facilities such as |
| 22416 | AUTH, PIPELINING, SIZE, and STARTTLS. |
| 22417 | |
| 22418 | +----------------------------------------------------------------+ |
| 22419 | |hosts_avoid_pipelining|Use: smtp|Type: host list*|Default: unset| |
| 22420 | +----------------------------------------------------------------+ |
| 22421 | |
| 22422 | Exim will not use the SMTP PIPELINING extension when delivering to any host |
| 22423 | that matches this list, even if the server host advertises PIPELINING support. |
| 22424 | |
| 22425 | +---------------------------------------------------------+ |
| 22426 | |hosts_avoid_tls|Use: smtp|Type: host list*|Default: unset| |
| 22427 | +---------------------------------------------------------+ |
| 22428 | |
| 22429 | Exim will not try to start a TLS session when delivering to any host that |
| 22430 | matches this list. See chapter 42 for details of TLS. |
| 22431 | |
| 22432 | +----------------------------------------------------------------+ |
| 22433 | |hosts_verify_avoid_tls|Use: smtp|Type: host list*|Default: unset| |
| 22434 | +----------------------------------------------------------------+ |
| 22435 | |
| 22436 | Exim will not try to start a TLS session for a verify callout, or when |
| 22437 | delivering in cutthrough mode, to any host that matches this list. |
| 22438 | |
| 22439 | +------------------------------------------------+ |
| 22440 | |hosts_max_try|Use: smtp|Type: integer|Default: 5| |
| 22441 | +------------------------------------------------+ |
| 22442 | |
| 22443 | This option limits the number of IP addresses that are tried for any one |
| 22444 | delivery in cases where there are temporary delivery errors. Section 30.5 |
| 22445 | describes in detail how the value of this option is used. |
| 22446 | |
| 22447 | +-----------------------------------------------------------+ |
| 22448 | |hosts_max_try_hardlimit|Use: smtp|Type: integer|Default: 50| |
| 22449 | +-----------------------------------------------------------+ |
| 22450 | |
| 22451 | This is an additional check on the maximum number of IP addresses that Exim |
| 22452 | tries for any one delivery. Section 30.5 describes its use and why it exists. |
| 22453 | |
| 22454 | +----------------------------------------------------------+ |
| 22455 | |hosts_nopass_tls|Use: smtp|Type: host list*|Default: unset| |
| 22456 | +----------------------------------------------------------+ |
| 22457 | |
| 22458 | For any host that matches this list, a connection on which a TLS session has |
| 22459 | been started will not be passed to a new delivery process for sending another |
| 22460 | message on the same connection. See section 42.11 for an explanation of when |
| 22461 | this might be needed. |
| 22462 | |
| 22463 | +-----------------------------------------------------+ |
| 22464 | |hosts_override|Use: smtp|Type: boolean|Default: false| |
| 22465 | +-----------------------------------------------------+ |
| 22466 | |
| 22467 | If this option is set and the hosts option is also set, any hosts that are |
| 22468 | attached to the address are ignored, and instead the hosts specified by the |
| 22469 | hosts option are always used. This option does not apply to fallback_hosts. |
| 22470 | |
| 22471 | +------------------------------------------------------+ |
| 22472 | |hosts_randomize|Use: smtp|Type: boolean|Default: false| |
| 22473 | +------------------------------------------------------+ |
| 22474 | |
| 22475 | If this option is set, and either the list of hosts is taken from the hosts or |
| 22476 | the fallback_hosts option, or the hosts supplied by the router were not |
| 22477 | obtained from MX records (this includes fallback hosts from the router), and |
| 22478 | were not randomized by the router, the order of trying the hosts is randomized |
| 22479 | each time the transport runs. Randomizing the order of a host list can be used |
| 22480 | to do crude load sharing. |
| 22481 | |
| 22482 | When hosts_randomize is true, a host list may be split into groups whose order |
| 22483 | is separately randomized. This makes it possible to set up MX-like behaviour. |
| 22484 | The boundaries between groups are indicated by an item that is just "+" in the |
| 22485 | host list. For example: |
| 22486 | |
| 22487 | hosts = host1:host2:host3:+:host4:host5 |
| 22488 | |
| 22489 | The order of the first three hosts and the order of the last two hosts is |
| 22490 | randomized for each use, but the first three always end up before the last two. |
| 22491 | If hosts_randomize is not set, a "+" item in the list is ignored. |
| 22492 | |
| 22493 | +------------------------------------------------------------+ |
| 22494 | |hosts_require_auth|Use: smtp|Type: host list*|Default: unset| |
| 22495 | +------------------------------------------------------------+ |
| 22496 | |
| 22497 | This option provides a list of servers for which authentication must succeed |
| 22498 | before Exim will try to transfer a message. If authentication fails for servers |
| 22499 | which are not in this list, Exim tries to send unauthenticated. If |
| 22500 | authentication fails for one of these servers, delivery is deferred. This |
| 22501 | temporary error is detectable in the retry rules, so it can be turned into a |
| 22502 | hard failure if required. See also hosts_try_auth, and chapter 33 for details |
| 22503 | of authentication. |
| 22504 | |
| 22505 | +--------------------------------------------------------+ |
| 22506 | |hosts_request_ocsp|Use: smtp|Type: host list*|Default: *| |
| 22507 | +--------------------------------------------------------+ |
| 22508 | |
| 22509 | Exim will request a Certificate Status on a TLS session for any host that |
| 22510 | matches this list. tls_verify_certificates should also be set for the |
| 22511 | transport. |
| 22512 | |
| 22513 | +------------------------------------------------------------+ |
| 22514 | |hosts_require_ocsp|Use: smtp|Type: host list*|Default: unset| |
| 22515 | +------------------------------------------------------------+ |
| 22516 | |
| 22517 | Exim will request, and check for a valid Certificate Status being given, on a |
| 22518 | TLS session for any host that matches this list. tls_verify_certificates should |
| 22519 | also be set for the transport. |
| 22520 | |
| 22521 | +-----------------------------------------------------------+ |
| 22522 | |hosts_require_tls|Use: smtp|Type: host list*|Default: unset| |
| 22523 | +-----------------------------------------------------------+ |
| 22524 | |
| 22525 | Exim will insist on using a TLS session when delivering to any host that |
| 22526 | matches this list. See chapter 42 for details of TLS. Note: This option affects |
| 22527 | outgoing mail only. To insist on TLS for incoming messages, use an appropriate |
| 22528 | ACL. |
| 22529 | |
| 22530 | +--------------------------------------------------------+ |
| 22531 | |hosts_try_auth|Use: smtp|Type: host list*|Default: unset| |
| 22532 | +--------------------------------------------------------+ |
| 22533 | |
| 22534 | This option provides a list of servers to which, provided they announce |
| 22535 | authentication support, Exim will attempt to authenticate as a client when it |
| 22536 | connects. If authentication fails, Exim will try to transfer the message |
| 22537 | unauthenticated. See also hosts_require_auth, and chapter 33 for details of |
| 22538 | authentication. |
| 22539 | |
| 22540 | +--------------------------------------------------------+ |
| 22541 | |hosts_try_chunking|Use: smtp|Type: host list*|Default: *| |
| 22542 | +--------------------------------------------------------+ |
| 22543 | |
| 22544 | This option provides a list of servers to which, provided they announce |
| 22545 | CHUNKING support, Exim will attempt to use BDAT commands rather than DATA. BDAT |
| 22546 | will not be used in conjunction with a transport filter. |
| 22547 | |
| 22548 | +-------------------------------------------------------------+ |
| 22549 | |hosts_try_fastopen|Use: smtp|Type: host list!!|Default: unset| |
| 22550 | +-------------------------------------------------------------+ |
| 22551 | |
| 22552 | This option provides a list of servers to which, provided the facility is |
| 22553 | supported by this system, Exim will attempt to perform a TCP Fast Open. No data |
| 22554 | is sent on the SYN segment but, if the remote server also supports the |
| 22555 | facility, it can send its SMTP banner immediately after the SYN,ACK segment. |
| 22556 | This can save up to one round-trip time. |
| 22557 | |
| 22558 | The facility is only active for previously-contacted servers, as the initiator |
| 22559 | must present a cookie in the SYN segment. |
| 22560 | |
| 22561 | On (at least some) current Linux distributions the facility must be enabled in |
| 22562 | the kernel by the sysadmin before the support is usable. |
| 22563 | |
| 22564 | +----------------------------------------------------+ |
| 22565 | |hosts_try_prdr|Use: smtp|Type: host list*|Default: *| |
| 22566 | +----------------------------------------------------+ |
| 22567 | |
| 22568 | This option provides a list of servers to which, provided they announce PRDR |
| 22569 | support, Exim will attempt to negotiate PRDR for multi-recipient messages. The |
| 22570 | option can usually be left as default. |
| 22571 | |
| 22572 | +-----------------------------------------------------+ |
| 22573 | |interface|Use: smtp|Type: string list*|Default: unset| |
| 22574 | +-----------------------------------------------------+ |
| 22575 | |
| 22576 | This option specifies which interface to bind to when making an outgoing SMTP |
| 22577 | call. The value is an IP address, not an interface name such as "eth0". Do not |
| 22578 | confuse this with the interface address that was used when a message was |
| 22579 | received, which is in $received_ip_address, formerly known as |
| 22580 | $interface_address. The name was changed to minimize confusion with the |
| 22581 | outgoing interface address. There is no variable that contains an outgoing |
| 22582 | interface address because, unless it is set by this option, its value is |
| 22583 | unknown. |
| 22584 | |
| 22585 | During the expansion of the interface option the variables $host and |
| 22586 | $host_address refer to the host to which a connection is about to be made |
| 22587 | during the expansion of the string. Forced expansion failure, or an empty |
| 22588 | string result causes the option to be ignored. Otherwise, after expansion, the |
| 22589 | string must be a list of IP addresses, colon-separated by default, but the |
| 22590 | separator can be changed in the usual way. For example: |
| 22591 | |
| 22592 | interface = <; 192.168.123.123 ; 3ffe:ffff:836f::fe86:a061 |
| 22593 | |
| 22594 | The first interface of the correct type (IPv4 or IPv6) is used for the outgoing |
| 22595 | connection. If none of them are the correct type, the option is ignored. If |
| 22596 | interface is not set, or is ignored, the system's IP functions choose which |
| 22597 | interface to use if the host has more than one. |
| 22598 | |
| 22599 | +-----------------------------------------------+ |
| 22600 | |keepalive|Use: smtp|Type: boolean|Default: true| |
| 22601 | +-----------------------------------------------+ |
| 22602 | |
| 22603 | This option controls the setting of SO_KEEPALIVE on outgoing TCP/IP socket |
| 22604 | connections. When set, it causes the kernel to probe idle connections |
| 22605 | periodically, by sending packets with "old" sequence numbers. The other end of |
| 22606 | the connection should send a acknowledgment if the connection is still okay or |
| 22607 | a reset if the connection has been aborted. The reason for doing this is that |
| 22608 | it has the beneficial effect of freeing up certain types of connection that can |
| 22609 | get stuck when the remote host is disconnected without tidying up the TCP/IP |
| 22610 | call properly. The keepalive mechanism takes several hours to detect |
| 22611 | unreachable hosts. |
| 22612 | |
| 22613 | +--------------------------------------------------------+ |
| 22614 | |lmtp_ignore_quota|Use: smtp|Type: boolean|Default: false| |
| 22615 | +--------------------------------------------------------+ |
| 22616 | |
| 22617 | If this option is set true when the protocol option is set to "lmtp", the |
| 22618 | string "IGNOREQUOTA" is added to RCPT commands, provided that the LMTP server |
| 22619 | has advertised support for IGNOREQUOTA in its response to the LHLO command. |
| 22620 | |
| 22621 | +---------------------------------------------+ |
| 22622 | |max_rcpt|Use: smtp|Type: integer|Default: 100| |
| 22623 | +---------------------------------------------+ |
| 22624 | |
| 22625 | This option limits the number of RCPT commands that are sent in a single SMTP |
| 22626 | message transaction. Each set of addresses is treated independently, and so can |
| 22627 | cause parallel connections to the same host if remote_max_parallel permits |
| 22628 | this. |
| 22629 | |
| 22630 | +---------------------------------------------------+ |
| 22631 | |multi_domain|Use: smtp|Type: boolean*|Default: true| |
| 22632 | +---------------------------------------------------+ |
| 22633 | |
| 22634 | When this option is set, the smtp transport can handle a number of addresses |
| 22635 | containing a mixture of different domains provided they all resolve to the same |
| 22636 | list of hosts. Turning the option off restricts the transport to handling only |
| 22637 | one domain at a time. This is useful if you want to use $domain in an expansion |
| 22638 | for the transport, because it is set only when there is a single domain |
| 22639 | involved in a remote delivery. |
| 22640 | |
| 22641 | It is expanded per-address and can depend on any of $address_data, $domain_data |
| 22642 | , $local_part_data, $host, $host_address and $host_port. |
| 22643 | |
| 22644 | +-----------------------------------------------+ |
| 22645 | |port|Use: smtp|Type: string*|Default: see below| |
| 22646 | +-----------------------------------------------+ |
| 22647 | |
| 22648 | This option specifies the TCP/IP port on the server to which Exim connects. |
| 22649 | Note: Do not confuse this with the port that was used when a message was |
| 22650 | received, which is in $received_port, formerly known as $interface_port. The |
| 22651 | name was changed to minimize confusion with the outgoing port. There is no |
| 22652 | variable that contains an outgoing port. |
| 22653 | |
| 22654 | If the value of this option begins with a digit it is taken as a port number; |
| 22655 | otherwise it is looked up using getservbyname(). The default value is normally |
| 22656 | "smtp", but if protocol is set to "lmtp", the default is "lmtp". If the |
| 22657 | expansion fails, or if a port number cannot be found, delivery is deferred. |
| 22658 | |
| 22659 | +---------------------------------------------+ |
| 22660 | |protocol|Use: smtp|Type: string|Default: smtp| |
| 22661 | +---------------------------------------------+ |
| 22662 | |
| 22663 | If this option is set to "lmtp" instead of "smtp", the default value for the |
| 22664 | port option changes to "lmtp", and the transport operates the LMTP protocol |
| 22665 | (RFC 2033) instead of SMTP. This protocol is sometimes used for local |
| 22666 | deliveries into closed message stores. Exim also has support for running LMTP |
| 22667 | over a pipe to a local process - see chapter 28. |
| 22668 | |
| 22669 | If this option is set to "smtps", the default value for the port option changes |
| 22670 | to "smtps", and the transport initiates TLS immediately after connecting, as an |
| 22671 | outbound SSL-on-connect, instead of using STARTTLS to upgrade. The Internet |
| 22672 | standards bodies strongly discourage use of this mode. |
| 22673 | |
| 22674 | +---------------------------------------------------------------+ |
| 22675 | |retry_include_ip_address|Use: smtp|Type: boolean*|Default: true| |
| 22676 | +---------------------------------------------------------------+ |
| 22677 | |
| 22678 | Exim normally includes both the host name and the IP address in the key it |
| 22679 | constructs for indexing retry data after a temporary delivery failure. This |
| 22680 | means that when one of several IP addresses for a host is failing, it gets |
| 22681 | tried periodically (controlled by the retry rules), but use of the other IP |
| 22682 | addresses is not affected. |
| 22683 | |
| 22684 | However, in some dialup environments hosts are assigned a different IP address |
| 22685 | each time they connect. In this situation the use of the IP address as part of |
| 22686 | the retry key leads to undesirable behaviour. Setting this option false causes |
| 22687 | Exim to use only the host name. Since it is expanded it can be made to depend |
| 22688 | on the host or domain. |
| 22689 | |
| 22690 | +---------------------------------------------------------+ |
| 22691 | |serialize_hosts|Use: smtp|Type: host list*|Default: unset| |
| 22692 | +---------------------------------------------------------+ |
| 22693 | |
| 22694 | Because Exim operates in a distributed manner, if several messages for the same |
| 22695 | host arrive at around the same time, more than one simultaneous connection to |
| 22696 | the remote host can occur. This is not usually a problem except when there is a |
| 22697 | slow link between the hosts. In that situation it may be helpful to restrict |
| 22698 | Exim to one connection at a time. This can be done by setting serialize_hosts |
| 22699 | to match the relevant hosts. |
| 22700 | |
| 22701 | Exim implements serialization by means of a hints database in which a record is |
| 22702 | written whenever a process connects to one of the restricted hosts. The record |
| 22703 | is deleted when the connection is completed. Obviously there is scope for |
| 22704 | records to get left lying around if there is a system or program crash. To |
| 22705 | guard against this, Exim ignores any records that are more than six hours old. |
| 22706 | |
| 22707 | If you set up this kind of serialization, you should also arrange to delete the |
| 22708 | relevant hints database whenever your system reboots. The names of the files |
| 22709 | start with misc and they are kept in the spool/db directory. There may be one |
| 22710 | or two files, depending on the type of DBM in use. The same files are used for |
| 22711 | ETRN serialization. |
| 22712 | |
| 22713 | See also the max_parallel generic transport option. |
| 22714 | |
| 22715 | +---------------------------------------------------+ |
| 22716 | |size_addition|Use: smtp|Type: integer|Default: 1024| |
| 22717 | +---------------------------------------------------+ |
| 22718 | |
| 22719 | If a remote SMTP server indicates that it supports the SIZE option of the MAIL |
| 22720 | command, Exim uses this to pass over the message size at the start of an SMTP |
| 22721 | transaction. It adds the value of size_addition to the value it sends, to allow |
| 22722 | for headers and other text that may be added during delivery by configuration |
| 22723 | options or in a transport filter. It may be necessary to increase this if a lot |
| 22724 | of text is added to messages. |
| 22725 | |
| 22726 | Alternatively, if the value of size_addition is set negative, it disables the |
| 22727 | use of the SIZE option altogether. |
| 22728 | |
| 22729 | +--------------------------------------------------+ |
| 22730 | |socks_proxy|Use: smtp|Type: string*|Default: unset| |
| 22731 | +--------------------------------------------------+ |
| 22732 | |
| 22733 | This option enables use of SOCKS proxies for connections made by the transport. |
| 22734 | For details see section 58.2. |
| 22735 | |
| 22736 | +------------------------------------------------------+ |
| 22737 | |tls_certificate|Use: smtp|Type: string*|Default: unset| |
| 22738 | +------------------------------------------------------+ |
| 22739 | |
| 22740 | The value of this option must be the absolute path to a file which contains the |
| 22741 | client's certificate, for possible use when sending a message over an encrypted |
| 22742 | connection. The values of $host and $host_address are set to the name and |
| 22743 | address of the server during the expansion. See chapter 42 for details of TLS. |
| 22744 | |
| 22745 | Note: This option must be set if you want Exim to be able to use a TLS |
| 22746 | certificate when sending messages as a client. The global option of the same |
| 22747 | name specifies the certificate for Exim as a server; it is not automatically |
| 22748 | assumed that the same certificate should be used when Exim is operating as a |
| 22749 | client. |
| 22750 | |
| 22751 | +----------------------------------------------+ |
| 22752 | |tls_crl|Use: smtp|Type: string*|Default: unset| |
| 22753 | +----------------------------------------------+ |
| 22754 | |
| 22755 | This option specifies a certificate revocation list. The expanded value must be |
| 22756 | the name of a file that contains a CRL in PEM format. |
| 22757 | |
| 22758 | +-----------------------------------------------------+ |
| 22759 | |tls_dh_min_bits|Use: smtp|Type: integer|Default: 1024| |
| 22760 | +-----------------------------------------------------+ |
| 22761 | |
| 22762 | When establishing a TLS session, if a ciphersuite which uses Diffie-Hellman key |
| 22763 | agreement is negotiated, the server will provide a large prime number for use. |
| 22764 | This option establishes the minimum acceptable size of that number. If the |
| 22765 | parameter offered by the server is too small, then the TLS handshake will fail. |
| 22766 | |
| 22767 | Only supported when using GnuTLS. |
| 22768 | |
| 22769 | +-----------------------------------------------------+ |
| 22770 | |tls_privatekey|Use: smtp|Type: string*|Default: unset| |
| 22771 | +-----------------------------------------------------+ |
| 22772 | |
| 22773 | The value of this option must be the absolute path to a file which contains the |
| 22774 | client's private key. This is used when sending a message over an encrypted |
| 22775 | connection using a client certificate. The values of $host and $host_address |
| 22776 | are set to the name and address of the server during the expansion. If this |
| 22777 | option is unset, or the expansion is forced to fail, or the result is an empty |
| 22778 | string, the private key is assumed to be in the same file as the certificate. |
| 22779 | See chapter 42 for details of TLS. |
| 22780 | |
| 22781 | +----------------------------------------------------------+ |
| 22782 | |tls_require_ciphers|Use: smtp|Type: string*|Default: unset| |
| 22783 | +----------------------------------------------------------+ |
| 22784 | |
| 22785 | The value of this option must be a list of permitted cipher suites, for use |
| 22786 | when setting up an outgoing encrypted connection. (There is a global option of |
| 22787 | the same name for controlling incoming connections.) The values of $host and |
| 22788 | $host_address are set to the name and address of the server during the |
| 22789 | expansion. See chapter 42 for details of TLS; note that this option is used in |
| 22790 | different ways by OpenSSL and GnuTLS (see sections 42.4 and 42.5). For GnuTLS, |
| 22791 | the order of the ciphers is a preference order. |
| 22792 | |
| 22793 | +----------------------------------------------+ |
| 22794 | |tls_sni|Use: smtp|Type: string*|Default: unset| |
| 22795 | +----------------------------------------------+ |
| 22796 | |
| 22797 | If this option is set then it sets the $tls_out_sni variable and causes any TLS |
| 22798 | session to pass this value as the Server Name Indication extension to the |
| 22799 | remote side, which can be used by the remote side to select an appropriate |
| 22800 | certificate and private key for the session. |
| 22801 | |
| 22802 | See 42.10 for more information. |
| 22803 | |
| 22804 | Note that for OpenSSL, this feature requires a build of OpenSSL that supports |
| 22805 | TLS extensions. |
| 22806 | |
| 22807 | +-----------------------------------------------------------+ |
| 22808 | |tls_tempfail_tryclear|Use: smtp|Type: boolean|Default: true| |
| 22809 | +-----------------------------------------------------------+ |
| 22810 | |
| 22811 | When the server host is not in hosts_require_tls, and there is a problem in |
| 22812 | setting up a TLS session, this option determines whether or not Exim should try |
| 22813 | to deliver the message unencrypted. If it is set false, delivery to the current |
| 22814 | host is deferred; if there are other hosts, they are tried. If this option is |
| 22815 | set true, Exim attempts to deliver unencrypted after a 4xx response to |
| 22816 | STARTTLS. Also, if STARTTLS is accepted, but the subsequent TLS negotiation |
| 22817 | fails, Exim closes the current connection (because it is in an unknown state), |
| 22818 | opens a new one to the same host, and then tries the delivery in clear. |
| 22819 | |
| 22820 | +----------------------------------------------------------+ |
| 22821 | |tls_try_verify_hosts|Use: smtp|Type: host list*|Default: *| |
| 22822 | +----------------------------------------------------------+ |
| 22823 | |
| 22824 | This option gives a list of hosts for which, on encrypted connections, |
| 22825 | certificate verification will be tried but need not succeed. The |
| 22826 | tls_verify_certificates option must also be set. Note that unless the host is |
| 22827 | in this list TLS connections will be denied to hosts using self-signed |
| 22828 | certificates when tls_verify_certificates is matched. The |
| 22829 | $tls_out_certificate_verified variable is set when certificate verification |
| 22830 | succeeds. |
| 22831 | |
| 22832 | +---------------------------------------------------------------+ |
| 22833 | |tls_verify_cert_hostnames|Use: smtp|Type: host list*|Default: *| |
| 22834 | +---------------------------------------------------------------+ |
| 22835 | |
| 22836 | This option give a list of hosts for which, while verifying the server |
| 22837 | certificate, checks will be included on the host name (note that this will |
| 22838 | generally be the result of a DNS MX lookup) versus Subject and |
| 22839 | Subject-Alternate-Name fields. Wildcard names are permitted limited to being |
| 22840 | the initial component of a 3-or-more component FQDN. |
| 22841 | |
| 22842 | There is no equivalent checking on client certificates. |
| 22843 | |
| 22844 | +---------------------------------------------------------------+ |
| 22845 | |tls_verify_certificates|Use: smtp|Type: string*|Default: system| |
| 22846 | +---------------------------------------------------------------+ |
| 22847 | |
| 22848 | The value of this option must be either the word "system" or the absolute path |
| 22849 | to a file or directory containing permitted certificates for servers, for use |
| 22850 | when setting up an encrypted connection. |
| 22851 | |
| 22852 | The "system" value for the option will use a location compiled into the SSL |
| 22853 | library. This is not available for GnuTLS versions preceding 3.0.20; a value of |
| 22854 | "system" is taken as empty and an explicit location must be specified. |
| 22855 | |
| 22856 | The use of a directory for the option value is not available for GnuTLS |
| 22857 | versions preceding 3.3.6 and a single file must be used. |
| 22858 | |
| 22859 | With OpenSSL the certificates specified explicitly either by file or directory |
| 22860 | are added to those given by the system default location. |
| 22861 | |
| 22862 | The values of $host and $host_address are set to the name and address of the |
| 22863 | server during the expansion of this option. See chapter 42 for details of TLS. |
| 22864 | |
| 22865 | For back-compatibility, if neither tls_verify_hosts nor tls_try_verify_hosts |
| 22866 | are set (a single-colon empty list counts as being set) and certificate |
| 22867 | verification fails the TLS connection is closed. |
| 22868 | |
| 22869 | +----------------------------------------------------------+ |
| 22870 | |tls_verify_hosts|Use: smtp|Type: host list*|Default: unset| |
| 22871 | +----------------------------------------------------------+ |
| 22872 | |
| 22873 | This option gives a list of hosts for which, on encrypted connections, |
| 22874 | certificate verification must succeed. The tls_verify_certificates option must |
| 22875 | also be set. If both this option and tls_try_verify_hosts are unset operation |
| 22876 | is as if this option selected all hosts. |
| 22877 | |
| 22878 | |
| 22879 | 30.5 How the limits for the number of hosts to try are used |
| 22880 | ----------------------------------------------------------- |
| 22881 | |
| 22882 | There are two options that are concerned with the number of hosts that are |
| 22883 | tried when an SMTP delivery takes place. They are hosts_max_try and |
| 22884 | hosts_max_try_hardlimit. |
| 22885 | |
| 22886 | The hosts_max_try option limits the number of hosts that are tried for a single |
| 22887 | delivery. However, despite the term "host" in its name, the option actually |
| 22888 | applies to each IP address independently. In other words, a multihomed host is |
| 22889 | treated as several independent hosts, just as it is for retrying. |
| 22890 | |
| 22891 | Many of the larger ISPs have multiple MX records which often point to |
| 22892 | multihomed hosts. As a result, a list of a dozen or more IP addresses may be |
| 22893 | created as a result of routing one of these domains. |
| 22894 | |
| 22895 | Trying every single IP address on such a long list does not seem sensible; if |
| 22896 | several at the top of the list fail, it is reasonable to assume there is some |
| 22897 | problem that is likely to affect all of them. Roughly speaking, the value of |
| 22898 | hosts_max_try is the maximum number that are tried before deferring the |
| 22899 | delivery. However, the logic cannot be quite that simple. |
| 22900 | |
| 22901 | Firstly, IP addresses that are skipped because their retry times have not |
| 22902 | arrived do not count, and in addition, addresses that are past their retry |
| 22903 | limits are also not counted, even when they are tried. This means that when |
| 22904 | some IP addresses are past their retry limits, more than the value of |
| 22905 | hosts_max_retry may be tried. The reason for this behaviour is to ensure that |
| 22906 | all IP addresses are considered before timing out an email address (but see |
| 22907 | below for an exception). |
| 22908 | |
| 22909 | Secondly, when the hosts_max_try limit is reached, Exim looks down the host |
| 22910 | list to see if there is a subsequent host with a different (higher valued) MX. |
| 22911 | If there is, that host is considered next, and the current IP address is used |
| 22912 | but not counted. This behaviour helps in the case of a domain with a retry rule |
| 22913 | that hardly ever delays any hosts, as is now explained: |
| 22914 | |
| 22915 | Consider the case of a long list of hosts with one MX value, and a few with a |
| 22916 | higher MX value. If hosts_max_try is small (the default is 5) only a few hosts |
| 22917 | at the top of the list are tried at first. With the default retry rule, which |
| 22918 | specifies increasing retry times, the higher MX hosts are eventually tried when |
| 22919 | those at the top of the list are skipped because they have not reached their |
| 22920 | retry times. |
| 22921 | |
| 22922 | However, it is common practice to put a fixed short retry time on domains for |
| 22923 | large ISPs, on the grounds that their servers are rarely down for very long. |
| 22924 | Unfortunately, these are exactly the domains that tend to resolve to long lists |
| 22925 | of hosts. The short retry time means that the lowest MX hosts are tried every |
| 22926 | time. The attempts may be in a different order because of random sorting, but |
| 22927 | without the special MX check, the higher MX hosts would never be tried until |
| 22928 | all the lower MX hosts had timed out (which might be several days), because |
| 22929 | there are always some lower MX hosts that have reached their retry times. With |
| 22930 | the special check, Exim considers at least one IP address from each MX value at |
| 22931 | every delivery attempt, even if the hosts_max_try limit has already been |
| 22932 | reached. |
| 22933 | |
| 22934 | The above logic means that hosts_max_try is not a hard limit, and in |
| 22935 | particular, Exim normally eventually tries all the IP addresses before timing |
| 22936 | out an email address. When hosts_max_try was implemented, this seemed a |
| 22937 | reasonable thing to do. Recently, however, some lunatic DNS configurations have |
| 22938 | been set up with hundreds of IP addresses for some domains. It can take a very |
| 22939 | long time indeed for an address to time out in these cases. |
| 22940 | |
| 22941 | The hosts_max_try_hardlimit option was added to help with this problem. Exim |
| 22942 | never tries more than this number of IP addresses; if it hits this limit and |
| 22943 | they are all timed out, the email address is bounced, even though not all |
| 22944 | possible IP addresses have been tried. |
| 22945 | |
| 22946 | |
| 22947 | |
| 22948 | =============================================================================== |
| 22949 | 31. ADDRESS REWRITING |
| 22950 | |
| 22951 | There are some circumstances in which Exim automatically rewrites domains in |
| 22952 | addresses. The two most common are when an address is given without a domain |
| 22953 | (referred to as an "unqualified address") or when an address contains an |
| 22954 | abbreviated domain that is expanded by DNS lookup. |
| 22955 | |
| 22956 | Unqualified envelope addresses are accepted only for locally submitted |
| 22957 | messages, or for messages that are received from hosts matching |
| 22958 | sender_unqualified_hosts or recipient_unqualified_hosts, as appropriate. |
| 22959 | Unqualified addresses in header lines are qualified if they are in locally |
| 22960 | submitted messages, or messages from hosts that are permitted to send |
| 22961 | unqualified envelope addresses. Otherwise, unqualified addresses in header |
| 22962 | lines are neither qualified nor rewritten. |
| 22963 | |
| 22964 | One situation in which Exim does not automatically rewrite a domain is when it |
| 22965 | is the name of a CNAME record in the DNS. The older RFCs suggest that such a |
| 22966 | domain should be rewritten using the "canonical" name, and some MTAs do this. |
| 22967 | The new RFCs do not contain this suggestion. |
| 22968 | |
| 22969 | |
| 22970 | 31.1 Explicitly configured address rewriting |
| 22971 | -------------------------------------------- |
| 22972 | |
| 22973 | This chapter describes the rewriting rules that can be used in the main rewrite |
| 22974 | section of the configuration file, and also in the generic headers_rewrite |
| 22975 | option that can be set on any transport. |
| 22976 | |
| 22977 | Some people believe that configured address rewriting is a Mortal Sin. Others |
| 22978 | believe that life is not possible without it. Exim provides the facility; you |
| 22979 | do not have to use it. |
| 22980 | |
| 22981 | The main rewriting rules that appear in the "rewrite" section of the |
| 22982 | configuration file are applied to addresses in incoming messages, both envelope |
| 22983 | addresses and addresses in header lines. Each rule specifies the types of |
| 22984 | address to which it applies. |
| 22985 | |
| 22986 | Whether or not addresses in header lines are rewritten depends on the origin of |
| 22987 | the headers and the type of rewriting. Global rewriting, that is, rewriting |
| 22988 | rules from the rewrite section of the configuration file, is applied only to |
| 22989 | those headers that were received with the message. Header lines that are added |
| 22990 | by ACLs or by a system filter or by individual routers or transports (which are |
| 22991 | specific to individual recipient addresses) are not rewritten by the global |
| 22992 | rules. |
| 22993 | |
| 22994 | Rewriting at transport time, by means of the headers_rewrite option, applies |
| 22995 | all headers except those added by routers and transports. That is, as well as |
| 22996 | the headers that were received with the message, it also applies to headers |
| 22997 | that were added by an ACL or a system filter. |
| 22998 | |
| 22999 | In general, rewriting addresses from your own system or domain has some |
| 23000 | legitimacy. Rewriting other addresses should be done only with great care and |
| 23001 | in special circumstances. The author of Exim believes that rewriting should be |
| 23002 | used sparingly, and mainly for "regularizing" addresses in your own domains. |
| 23003 | Although it can sometimes be used as a routing tool, this is very strongly |
| 23004 | discouraged. |
| 23005 | |
| 23006 | There are two commonly encountered circumstances where rewriting is used, as |
| 23007 | illustrated by these examples: |
| 23008 | |
| 23009 | * The company whose domain is hitch.fict.example has a number of hosts that |
| 23010 | exchange mail with each other behind a firewall, but there is only a single |
| 23011 | gateway to the outer world. The gateway rewrites *.hitch.fict.example as |
| 23012 | hitch.fict.example when sending mail off-site. |
| 23013 | |
| 23014 | * A host rewrites the local parts of its own users so that, for example, |
| 23015 | fp42@hitch.fict.example becomes Ford.Prefect@hitch.fict.example. |
| 23016 | |
| 23017 | |
| 23018 | 31.2 When does rewriting happen? |
| 23019 | -------------------------------- |
| 23020 | |
| 23021 | Configured address rewriting can take place at several different stages of a |
| 23022 | message's processing. |
| 23023 | |
| 23024 | At the start of an ACL for MAIL, the sender address may have been rewritten by |
| 23025 | a special SMTP-time rewrite rule (see section 31.9), but no ordinary rewrite |
| 23026 | rules have yet been applied. If, however, the sender address is verified in the |
| 23027 | ACL, it is rewritten before verification, and remains rewritten thereafter. The |
| 23028 | subsequent value of $sender_address is the rewritten address. This also applies |
| 23029 | if sender verification happens in a RCPT ACL. Otherwise, when the sender |
| 23030 | address is not verified, it is rewritten as soon as a message's header lines |
| 23031 | have been received. |
| 23032 | |
| 23033 | Similarly, at the start of an ACL for RCPT, the current recipient's address may |
| 23034 | have been rewritten by a special SMTP-time rewrite rule, but no ordinary |
| 23035 | rewrite rules have yet been applied to it. However, the behaviour is different |
| 23036 | from the sender address when a recipient is verified. The address is rewritten |
| 23037 | for the verification, but the rewriting is not remembered at this stage. The |
| 23038 | value of $local_part and $domain after verification are always the same as they |
| 23039 | were before (that is, they contain the unrewritten - except for SMTP-time |
| 23040 | rewriting - address). |
| 23041 | |
| 23042 | As soon as a message's header lines have been received, all the envelope |
| 23043 | recipient addresses are permanently rewritten, and rewriting is also applied to |
| 23044 | the addresses in the header lines (if configured). This happens before adding |
| 23045 | any header lines that were specified in MAIL or RCPT ACLs, and before the DATA |
| 23046 | ACL and local_scan() functions are run. |
| 23047 | |
| 23048 | When an address is being routed, either for delivery or for verification, |
| 23049 | rewriting is applied immediately to child addresses that are generated by |
| 23050 | redirection, unless no_rewrite is set on the router. |
| 23051 | |
| 23052 | At transport time, additional rewriting of addresses in header lines can be |
| 23053 | specified by setting the generic headers_rewrite option on a transport. This |
| 23054 | option contains rules that are identical in form to those in the rewrite |
| 23055 | section of the configuration file. They are applied to the original message |
| 23056 | header lines and any that were added by ACLs or a system filter. They are not |
| 23057 | applied to header lines that are added by routers or the transport. |
| 23058 | |
| 23059 | The outgoing envelope sender can be rewritten by means of the return_path |
| 23060 | transport option. However, it is not possible to rewrite envelope recipients at |
| 23061 | transport time. |
| 23062 | |
| 23063 | |
| 23064 | 31.3 Testing the rewriting rules that apply on input |
| 23065 | ---------------------------------------------------- |
| 23066 | |
| 23067 | Exim's input rewriting configuration appears in a part of the run time |
| 23068 | configuration file headed by "begin rewrite". It can be tested by the -brw |
| 23069 | command line option. This takes an address (which can be a full RFC 2822 |
| 23070 | address) as its argument. The output is a list of how the address would be |
| 23071 | transformed by the rewriting rules for each of the different places it might |
| 23072 | appear in an incoming message, that is, for each different header and for the |
| 23073 | envelope sender and recipient fields. For example, |
| 23074 | |
| 23075 | exim -brw ph10@exim.workshop.example |
| 23076 | |
| 23077 | might produce the output |
| 23078 | |
| 23079 | sender: Philip.Hazel@exim.workshop.example |
| 23080 | from: Philip.Hazel@exim.workshop.example |
| 23081 | to: ph10@exim.workshop.example |
| 23082 | cc: ph10@exim.workshop.example |
| 23083 | bcc: ph10@exim.workshop.example |
| 23084 | reply-to: Philip.Hazel@exim.workshop.example |
| 23085 | env-from: Philip.Hazel@exim.workshop.example |
| 23086 | env-to: ph10@exim.workshop.example |
| 23087 | |
| 23088 | which shows that rewriting has been set up for that address when used in any of |
| 23089 | the source fields, but not when it appears as a recipient address. At the |
| 23090 | present time, there is no equivalent way of testing rewriting rules that are |
| 23091 | set for a particular transport. |
| 23092 | |
| 23093 | |
| 23094 | 31.4 Rewriting rules |
| 23095 | -------------------- |
| 23096 | |
| 23097 | The rewrite section of the configuration file consists of lines of rewriting |
| 23098 | rules in the form |
| 23099 | |
| 23100 | <source pattern> <replacement> <flags> |
| 23101 | |
| 23102 | Rewriting rules that are specified for the headers_rewrite generic transport |
| 23103 | option are given as a colon-separated list. Each item in the list takes the |
| 23104 | same form as a line in the main rewriting configuration (except that any colons |
| 23105 | must be doubled, of course). |
| 23106 | |
| 23107 | The formats of source patterns and replacement strings are described below. |
| 23108 | Each is terminated by white space, unless enclosed in double quotes, in which |
| 23109 | case normal quoting conventions apply inside the quotes. The flags are single |
| 23110 | characters which may appear in any order. Spaces and tabs between them are |
| 23111 | ignored. |
| 23112 | |
| 23113 | For each address that could potentially be rewritten, the rules are scanned in |
| 23114 | order, and replacements for the address from earlier rules can themselves be |
| 23115 | replaced by later rules (but see the "q" and "R" flags). |
| 23116 | |
| 23117 | The order in which addresses are rewritten is undefined, may change between |
| 23118 | releases, and must not be relied on, with one exception: when a message is |
| 23119 | received, the envelope sender is always rewritten first, before any header |
| 23120 | lines are rewritten. For example, the replacement string for a rewrite of an |
| 23121 | address in To: must not assume that the message's address in From: has (or has |
| 23122 | not) already been rewritten. However, a rewrite of From: may assume that the |
| 23123 | envelope sender has already been rewritten. |
| 23124 | |
| 23125 | The variables $local_part and $domain can be used in the replacement string to |
| 23126 | refer to the address that is being rewritten. Note that lookup-driven rewriting |
| 23127 | can be done by a rule of the form |
| 23128 | |
| 23129 | *@* ${lookup ... |
| 23130 | |
| 23131 | where the lookup key uses $1 and $2 or $local_part and $domain to refer to the |
| 23132 | address that is being rewritten. |
| 23133 | |
| 23134 | |
| 23135 | 31.5 Rewriting patterns |
| 23136 | ----------------------- |
| 23137 | |
| 23138 | The source pattern in a rewriting rule is any item which may appear in an |
| 23139 | address list (see section 10.19). It is in fact processed as a single-item |
| 23140 | address list, which means that it is expanded before being tested against the |
| 23141 | address. As always, if you use a regular expression as a pattern, you must take |
| 23142 | care to escape dollar and backslash characters, or use the "\N" facility to |
| 23143 | suppress string expansion within the regular expression. |
| 23144 | |
| 23145 | Domains in patterns should be given in lower case. Local parts in patterns are |
| 23146 | case-sensitive. If you want to do case-insensitive matching of local parts, you |
| 23147 | can use a regular expression that starts with "^(?i)". |
| 23148 | |
| 23149 | After matching, the numerical variables $1, $2, etc. may be set, depending on |
| 23150 | the type of match which occurred. These can be used in the replacement string |
| 23151 | to insert portions of the incoming address. $0 always refers to the complete |
| 23152 | incoming address. When a regular expression is used, the numerical variables |
| 23153 | are set from its capturing subexpressions. For other types of pattern they are |
| 23154 | set as follows: |
| 23155 | |
| 23156 | * If a local part or domain starts with an asterisk, the numerical variables |
| 23157 | refer to the character strings matched by asterisks, with $1 associated |
| 23158 | with the first asterisk, and $2 with the second, if present. For example, |
| 23159 | if the pattern |
| 23160 | |
| 23161 | *queen@*.fict.example |
| 23162 | |
| 23163 | is matched against the address hearts-queen@wonderland.fict.example then |
| 23164 | |
| 23165 | $0 = hearts-queen@wonderland.fict.example |
| 23166 | $1 = hearts- |
| 23167 | $2 = wonderland |
| 23168 | |
| 23169 | Note that if the local part does not start with an asterisk, but the domain |
| 23170 | does, it is $1 that contains the wild part of the domain. |
| 23171 | |
| 23172 | * If the domain part of the pattern is a partial lookup, the wild and fixed |
| 23173 | parts of the domain are placed in the next available numerical variables. |
| 23174 | Suppose, for example, that the address foo@bar.baz.example is processed by |
| 23175 | a rewriting rule of the form |
| 23176 | |
| 23177 | *@partial-dbm;/some/dbm/file <replacement string> |
| 23178 | |
| 23179 | and the key in the file that matches the domain is "*.baz.example". Then |
| 23180 | |
| 23181 | $1 = foo |
| 23182 | $2 = bar |
| 23183 | $3 = baz.example |
| 23184 | |
| 23185 | If the address foo@baz.example is looked up, this matches the same wildcard |
| 23186 | file entry, and in this case $2 is set to the empty string, but $3 is still |
| 23187 | set to baz.example. If a non-wild key is matched in a partial lookup, $2 is |
| 23188 | again set to the empty string and $3 is set to the whole domain. For |
| 23189 | non-partial domain lookups, no numerical variables are set. |
| 23190 | |
| 23191 | |
| 23192 | 31.6 Rewriting replacements |
| 23193 | --------------------------- |
| 23194 | |
| 23195 | If the replacement string for a rule is a single asterisk, addresses that match |
| 23196 | the pattern and the flags are not rewritten, and no subsequent rewriting rules |
| 23197 | are scanned. For example, |
| 23198 | |
| 23199 | hatta@lookingglass.fict.example * f |
| 23200 | |
| 23201 | specifies that hatta@lookingglass.fict.example is never to be rewritten in |
| 23202 | From: headers. |
| 23203 | |
| 23204 | If the replacement string is not a single asterisk, it is expanded, and must |
| 23205 | yield a fully qualified address. Within the expansion, the variables |
| 23206 | $local_part and $domain refer to the address that is being rewritten. Any |
| 23207 | letters they contain retain their original case - they are not lower cased. The |
| 23208 | numerical variables are set up according to the type of pattern that matched |
| 23209 | the address, as described above. If the expansion is forced to fail by the |
| 23210 | presence of "fail" in a conditional or lookup item, rewriting by the current |
| 23211 | rule is abandoned, but subsequent rules may take effect. Any other expansion |
| 23212 | failure causes the entire rewriting operation to be abandoned, and an entry |
| 23213 | written to the panic log. |
| 23214 | |
| 23215 | |
| 23216 | 31.7 Rewriting flags |
| 23217 | -------------------- |
| 23218 | |
| 23219 | There are three different kinds of flag that may appear on rewriting rules: |
| 23220 | |
| 23221 | * Flags that specify which headers and envelope addresses to rewrite: E, F, |
| 23222 | T, b, c, f, h, r, s, t. |
| 23223 | |
| 23224 | * A flag that specifies rewriting at SMTP time: S. |
| 23225 | |
| 23226 | * Flags that control the rewriting process: Q, q, R, w. |
| 23227 | |
| 23228 | For rules that are part of the headers_rewrite generic transport option, E, F, |
| 23229 | T, and S are not permitted. |
| 23230 | |
| 23231 | |
| 23232 | 31.8 Flags specifying which headers and envelope addresses to rewrite |
| 23233 | --------------------------------------------------------------------- |
| 23234 | |
| 23235 | If none of the following flag letters, nor the "S" flag (see section 31.9) are |
| 23236 | present, a main rewriting rule applies to all headers and to both the sender |
| 23237 | and recipient fields of the envelope, whereas a transport-time rewriting rule |
| 23238 | just applies to all headers. Otherwise, the rewriting rule is skipped unless |
| 23239 | the relevant addresses are being processed. |
| 23240 | |
| 23241 | E rewrite all envelope fields |
| 23242 | F rewrite the envelope From field |
| 23243 | T rewrite the envelope To field |
| 23244 | b rewrite the Bcc: header |
| 23245 | c rewrite the Cc: header |
| 23246 | f rewrite the From: header |
| 23247 | h rewrite all headers |
| 23248 | r rewrite the Reply-To: header |
| 23249 | s rewrite the Sender: header |
| 23250 | t rewrite the To: header |
| 23251 | |
| 23252 | "All headers" means all of the headers listed above that can be selected |
| 23253 | individually, plus their Resent- versions. It does not include other headers |
| 23254 | such as Subject: etc. |
| 23255 | |
| 23256 | You should be particularly careful about rewriting Sender: headers, and |
| 23257 | restrict this to special known cases in your own domains. |
| 23258 | |
| 23259 | |
| 23260 | 31.9 The SMTP-time rewriting flag |
| 23261 | --------------------------------- |
| 23262 | |
| 23263 | The rewrite flag "S" specifies a rewrite of incoming envelope addresses at SMTP |
| 23264 | time, as soon as an address is received in a MAIL or RCPT command, and before |
| 23265 | any other processing; even before syntax checking. The pattern is required to |
| 23266 | be a regular expression, and it is matched against the whole of the data for |
| 23267 | the command, including any surrounding angle brackets. |
| 23268 | |
| 23269 | This form of rewrite rule allows for the handling of addresses that are not |
| 23270 | compliant with RFCs 2821 and 2822 (for example, "bang paths" in batched SMTP |
| 23271 | input). Because the input is not required to be a syntactically valid address, |
| 23272 | the variables $local_part and $domain are not available during the expansion of |
| 23273 | the replacement string. The result of rewriting replaces the original address |
| 23274 | in the MAIL or RCPT command. |
| 23275 | |
| 23276 | |
| 23277 | 31.10 Flags controlling the rewriting process |
| 23278 | --------------------------------------------- |
| 23279 | |
| 23280 | There are four flags which control the way the rewriting process works. These |
| 23281 | take effect only when a rule is invoked, that is, when the address is of the |
| 23282 | correct type (matches the flags) and matches the pattern: |
| 23283 | |
| 23284 | * If the "Q" flag is set on a rule, the rewritten address is permitted to be |
| 23285 | an unqualified local part. It is qualified with qualify_recipient. In the |
| 23286 | absence of "Q" the rewritten address must always include a domain. |
| 23287 | |
| 23288 | * If the "q" flag is set on a rule, no further rewriting rules are |
| 23289 | considered, even if no rewriting actually takes place because of a "fail" |
| 23290 | in the expansion. The "q" flag is not effective if the address is of the |
| 23291 | wrong type (does not match the flags) or does not match the pattern. |
| 23292 | |
| 23293 | * The "R" flag causes a successful rewriting rule to be re-applied to the new |
| 23294 | address, up to ten times. It can be combined with the "q" flag, to stop |
| 23295 | rewriting once it fails to match (after at least one successful rewrite). |
| 23296 | |
| 23297 | * When an address in a header is rewritten, the rewriting normally applies |
| 23298 | only to the working part of the address, with any comments and RFC 2822 |
| 23299 | "phrase" left unchanged. For example, rewriting might change |
| 23300 | |
| 23301 | From: Ford Prefect <fp42@restaurant.hitch.fict.example> |
| 23302 | |
| 23303 | into |
| 23304 | |
| 23305 | From: Ford Prefect <prefectf@hitch.fict.example> |
| 23306 | |
| 23307 | Sometimes there is a need to replace the whole address item, and this can |
| 23308 | be done by adding the flag letter "w" to a rule. If this is set on a rule |
| 23309 | that causes an address in a header line to be rewritten, the entire address |
| 23310 | is replaced, not just the working part. The replacement must be a complete |
| 23311 | RFC 2822 address, including the angle brackets if necessary. If text |
| 23312 | outside angle brackets contains a character whose value is greater than 126 |
| 23313 | or less than 32 (except for tab), the text is encoded according to RFC |
| 23314 | 2047. The character set is taken from headers_charset, which gets its |
| 23315 | default at build time. |
| 23316 | |
| 23317 | When the "w" flag is set on a rule that causes an envelope address to be |
| 23318 | rewritten, all but the working part of the replacement address is |
| 23319 | discarded. |
| 23320 | |
| 23321 | |
| 23322 | 31.11 Rewriting examples |
| 23323 | ------------------------ |
| 23324 | |
| 23325 | Here is an example of the two common rewriting paradigms: |
| 23326 | |
| 23327 | *@*.hitch.fict.example $1@hitch.fict.example |
| 23328 | *@hitch.fict.example ${lookup{$1}dbm{/etc/realnames}\ |
| 23329 | {$value}fail}@hitch.fict.example bctfrF |
| 23330 | |
| 23331 | Note the use of "fail" in the lookup expansion in the second rule, forcing the |
| 23332 | string expansion to fail if the lookup does not succeed. In this context it has |
| 23333 | the effect of leaving the original address unchanged, but Exim goes on to |
| 23334 | consider subsequent rewriting rules, if any, because the "q" flag is not |
| 23335 | present in that rule. An alternative to "fail" would be to supply $1 |
| 23336 | explicitly, which would cause the rewritten address to be the same as before, |
| 23337 | at the cost of a small bit of processing. Not supplying either of these is an |
| 23338 | error, since the rewritten address would then contain no local part. |
| 23339 | |
| 23340 | The first example above replaces the domain with a superior, more general |
| 23341 | domain. This may not be desirable for certain local parts. If the rule |
| 23342 | |
| 23343 | root@*.hitch.fict.example * |
| 23344 | |
| 23345 | were inserted before the first rule, rewriting would be suppressed for the |
| 23346 | local part root at any domain ending in hitch.fict.example. |
| 23347 | |
| 23348 | Rewriting can be made conditional on a number of tests, by making use of ${if |
| 23349 | in the expansion item. For example, to apply a rewriting rule only to messages |
| 23350 | that originate outside the local host: |
| 23351 | |
| 23352 | *@*.hitch.fict.example "${if !eq {$sender_host_address}{}\ |
| 23353 | {$1@hitch.fict.example}fail}" |
| 23354 | |
| 23355 | The replacement string is quoted in this example because it contains white |
| 23356 | space. |
| 23357 | |
| 23358 | Exim does not handle addresses in the form of "bang paths". If it sees such an |
| 23359 | address it treats it as an unqualified local part which it qualifies with the |
| 23360 | local qualification domain (if the source of the message is local or if the |
| 23361 | remote host is permitted to send unqualified addresses). Rewriting can |
| 23362 | sometimes be used to handle simple bang paths with a fixed number of |
| 23363 | components. For example, the rule |
| 23364 | |
| 23365 | \N^([^!]+)!(.*)@your.domain.example$\N $2@$1 |
| 23366 | |
| 23367 | rewrites a two-component bang path host.name!user as the domain address |
| 23368 | user@host.name. However, there is a security implication in using this as a |
| 23369 | global rewriting rule for envelope addresses. It can provide a backdoor method |
| 23370 | for using your system as a relay, because the incoming addresses appear to be |
| 23371 | local. If the bang path addresses are received via SMTP, it is safer to use the |
| 23372 | "S" flag to rewrite them as they are received, so that relay checking can be |
| 23373 | done on the rewritten addresses. |
| 23374 | |
| 23375 | |
| 23376 | |
| 23377 | =============================================================================== |
| 23378 | 32. RETRY CONFIGURATION |
| 23379 | |
| 23380 | The "retry" section of the runtime configuration file contains a list of retry |
| 23381 | rules that control how often Exim tries to deliver messages that cannot be |
| 23382 | delivered at the first attempt. If there are no retry rules (the section is |
| 23383 | empty or not present), there are no retries. In this situation, temporary |
| 23384 | errors are treated as permanent. The default configuration contains a single, |
| 23385 | general-purpose retry rule (see section 7.5). The -brt command line option can |
| 23386 | be used to test which retry rule will be used for a given address, domain and |
| 23387 | error. |
| 23388 | |
| 23389 | The most common cause of retries is temporary failure to deliver to a remote |
| 23390 | host because the host is down, or inaccessible because of a network problem. |
| 23391 | Exim's retry processing in this case is applied on a per-host (strictly, per IP |
| 23392 | address) basis, not on a per-message basis. Thus, if one message has recently |
| 23393 | been delayed, delivery of a new message to the same host is not immediately |
| 23394 | tried, but waits for the host's retry time to arrive. If the retry_defer log |
| 23395 | selector is set, the message "retry time not reached" is written to the main |
| 23396 | log whenever a delivery is skipped for this reason. Section 48.2 contains more |
| 23397 | details of the handling of errors during remote deliveries. |
| 23398 | |
| 23399 | Retry processing applies to routing as well as to delivering, except as covered |
| 23400 | in the next paragraph. The retry rules do not distinguish between these |
| 23401 | actions. It is not possible, for example, to specify different behaviour for |
| 23402 | failures to route the domain snark.fict.example and failures to deliver to the |
| 23403 | host snark.fict.example. I didn't think anyone would ever need this added |
| 23404 | complication, so did not implement it. However, although they share the same |
| 23405 | retry rule, the actual retry times for routing and transporting a given domain |
| 23406 | are maintained independently. |
| 23407 | |
| 23408 | When a delivery is not part of a queue run (typically an immediate delivery on |
| 23409 | receipt of a message), the routers are always run, and local deliveries are |
| 23410 | always attempted, even if retry times are set for them. This makes for better |
| 23411 | behaviour if one particular message is causing problems (for example, causing |
| 23412 | quota overflow, or provoking an error in a filter file). If such a delivery |
| 23413 | suffers a temporary failure, the retry data is updated as normal, and |
| 23414 | subsequent delivery attempts from queue runs occur only when the retry time for |
| 23415 | the local address is reached. |
| 23416 | |
| 23417 | |
| 23418 | 32.1 Changing retry rules |
| 23419 | ------------------------- |
| 23420 | |
| 23421 | If you change the retry rules in your configuration, you should consider |
| 23422 | whether or not to delete the retry data that is stored in Exim's spool area in |
| 23423 | files with names like db/retry. Deleting any of Exim's hints files is always |
| 23424 | safe; that is why they are called "hints". |
| 23425 | |
| 23426 | The hints retry data contains suggested retry times based on the previous |
| 23427 | rules. In the case of a long-running problem with a remote host, it might |
| 23428 | record the fact that the host has timed out. If your new rules increase the |
| 23429 | timeout time for such a host, you should definitely remove the old retry data |
| 23430 | and let Exim recreate it, based on the new rules. Otherwise Exim might bounce |
| 23431 | messages that it should now be retaining. |
| 23432 | |
| 23433 | |
| 23434 | 32.2 Format of retry rules |
| 23435 | -------------------------- |
| 23436 | |
| 23437 | Each retry rule occupies one line and consists of three or four parts, |
| 23438 | separated by white space: a pattern, an error name, an optional list of sender |
| 23439 | addresses, and a list of retry parameters. The pattern and sender lists must be |
| 23440 | enclosed in double quotes if they contain white space. The rules are searched |
| 23441 | in order until one is found where the pattern, error name, and sender list (if |
| 23442 | present) match the failing host or address, the error that occurred, and the |
| 23443 | message's sender, respectively. |
| 23444 | |
| 23445 | The pattern is any single item that may appear in an address list (see section |
| 23446 | 10.19). It is in fact processed as a one-item address list, which means that it |
| 23447 | is expanded before being tested against the address that has been delayed. A |
| 23448 | negated address list item is permitted. Address list processing treats a plain |
| 23449 | domain name as if it were preceded by "*@", which makes it possible for many |
| 23450 | retry rules to start with just a domain. For example, |
| 23451 | |
| 23452 | lookingglass.fict.example * F,24h,30m; |
| 23453 | |
| 23454 | provides a rule for any address in the lookingglass.fict.example domain, |
| 23455 | whereas |
| 23456 | |
| 23457 | alice@lookingglass.fict.example * F,24h,30m; |
| 23458 | |
| 23459 | applies only to temporary failures involving the local part alice. In practice, |
| 23460 | almost all rules start with a domain name pattern without a local part. |
| 23461 | |
| 23462 | Warning: If you use a regular expression in a retry rule pattern, it must match |
| 23463 | a complete address, not just a domain, because that is how regular expressions |
| 23464 | work in address lists. |
| 23465 | |
| 23466 | ^\Nxyz\d+\.abc\.example$\N * G,1h,10m,2 Wrong |
| 23467 | ^\N[^@]+@xyz\d+\.abc\.example$\N * G,1h,10m,2 Right |
| 23468 | |
| 23469 | |
| 23470 | 32.3 Choosing which retry rule to use for address errors |
| 23471 | -------------------------------------------------------- |
| 23472 | |
| 23473 | When Exim is looking for a retry rule after a routing attempt has failed (for |
| 23474 | example, after a DNS timeout), each line in the retry configuration is tested |
| 23475 | against the complete address only if retry_use_local_part is set for the |
| 23476 | router. Otherwise, only the domain is used, except when matching against a |
| 23477 | regular expression, when the local part of the address is replaced with "*". A |
| 23478 | domain on its own can match a domain pattern, or a pattern that starts with |
| 23479 | "*@". By default, retry_use_local_part is true for routers where |
| 23480 | check_local_user is true, and false for other routers. |
| 23481 | |
| 23482 | Similarly, when Exim is looking for a retry rule after a local delivery has |
| 23483 | failed (for example, after a mailbox full error), each line in the retry |
| 23484 | configuration is tested against the complete address only if |
| 23485 | retry_use_local_part is set for the transport (it defaults true for all local |
| 23486 | transports). |
| 23487 | |
| 23488 | However, when Exim is looking for a retry rule after a remote delivery attempt |
| 23489 | suffers an address error (a 4xx SMTP response for a recipient address), the |
| 23490 | whole address is always used as the key when searching the retry rules. The |
| 23491 | rule that is found is used to create a retry time for the combination of the |
| 23492 | failing address and the message's sender. It is the combination of sender and |
| 23493 | recipient that is delayed in subsequent queue runs until its retry time is |
| 23494 | reached. You can delay the recipient without regard to the sender by setting |
| 23495 | address_retry_include_sender false in the smtp transport but this can lead to |
| 23496 | problems with servers that regularly issue 4xx responses to RCPT commands. |
| 23497 | |
| 23498 | |
| 23499 | 32.4 Choosing which retry rule to use for host and message errors |
| 23500 | ----------------------------------------------------------------- |
| 23501 | |
| 23502 | For a temporary error that is not related to an individual address (for |
| 23503 | example, a connection timeout), each line in the retry configuration is checked |
| 23504 | twice. First, the name of the remote host is used as a domain name (preceded by |
| 23505 | "*@" when matching a regular expression). If this does not match the line, the |
| 23506 | domain from the email address is tried in a similar fashion. For example, |
| 23507 | suppose the MX records for a.b.c.example are |
| 23508 | |
| 23509 | a.b.c.example MX 5 x.y.z.example |
| 23510 | MX 6 p.q.r.example |
| 23511 | MX 7 m.n.o.example |
| 23512 | |
| 23513 | and the retry rules are |
| 23514 | |
| 23515 | p.q.r.example * F,24h,30m; |
| 23516 | a.b.c.example * F,4d,45m; |
| 23517 | |
| 23518 | and a delivery to the host x.y.z.example suffers a connection failure. The |
| 23519 | first rule matches neither the host nor the domain, so Exim looks at the second |
| 23520 | rule. This does not match the host, but it does match the domain, so it is used |
| 23521 | to calculate the retry time for the host x.y.z.example. Meanwhile, Exim tries |
| 23522 | to deliver to p.q.r.example. If this also suffers a host error, the first retry |
| 23523 | rule is used, because it matches the host. |
| 23524 | |
| 23525 | In other words, temporary failures to deliver to host p.q.r.example use the |
| 23526 | first rule to determine retry times, but for all the other hosts for the domain |
| 23527 | a.b.c.example, the second rule is used. The second rule is also used if routing |
| 23528 | to a.b.c.example suffers a temporary failure. |
| 23529 | |
| 23530 | Note: The host name is used when matching the patterns, not its IP address. |
| 23531 | However, if a message is routed directly to an IP address without the use of a |
| 23532 | host name, for example, if a manualroute router contains a setting such as: |
| 23533 | |
| 23534 | route_list = *.a.example 192.168.34.23 |
| 23535 | |
| 23536 | then the "host name" that is used when searching for a retry rule is the |
| 23537 | textual form of the IP address. |
| 23538 | |
| 23539 | |
| 23540 | 32.5 Retry rules for specific errors |
| 23541 | ------------------------------------ |
| 23542 | |
| 23543 | The second field in a retry rule is the name of a particular error, or an |
| 23544 | asterisk, which matches any error. The errors that can be tested for are: |
| 23545 | |
| 23546 | auth_failed |
| 23547 | |
| 23548 | Authentication failed when trying to send to a host in the |
| 23549 | hosts_require_auth list in an smtp transport. |
| 23550 | |
| 23551 | data_4xx |
| 23552 | |
| 23553 | A 4xx error was received for an outgoing DATA command, either immediately |
| 23554 | after the command, or after sending the message's data. |
| 23555 | |
| 23556 | mail_4xx |
| 23557 | |
| 23558 | A 4xx error was received for an outgoing MAIL command. |
| 23559 | |
| 23560 | rcpt_4xx |
| 23561 | |
| 23562 | A 4xx error was received for an outgoing RCPT command. |
| 23563 | |
| 23564 | For the three 4xx errors, either the first or both of the x's can be given as |
| 23565 | specific digits, for example: "mail_45x" or "rcpt_436". For example, to |
| 23566 | recognize 452 errors given to RCPT commands for addresses in a certain domain, |
| 23567 | and have retries every ten minutes with a one-hour timeout, you could set up a |
| 23568 | retry rule of this form: |
| 23569 | |
| 23570 | the.domain.name rcpt_452 F,1h,10m |
| 23571 | |
| 23572 | These errors apply to both outgoing SMTP (the smtp transport) and outgoing LMTP |
| 23573 | (either the lmtp transport, or the smtp transport in LMTP mode). |
| 23574 | |
| 23575 | lost_connection |
| 23576 | |
| 23577 | A server unexpectedly closed the SMTP connection. There may, of course, |
| 23578 | legitimate reasons for this (host died, network died), but if it repeats a |
| 23579 | lot for the same host, it indicates something odd. |
| 23580 | |
| 23581 | lookup |
| 23582 | |
| 23583 | A DNS lookup for a host failed. Note that a dnslookup router will need to |
| 23584 | have matched its fail_defer_domains option for this retry type to be |
| 23585 | usable. Also note that a manualroute router will probably need its |
| 23586 | host_find_failed option set to defer. |
| 23587 | |
| 23588 | refused_MX |
| 23589 | |
| 23590 | A connection to a host obtained from an MX record was refused. |
| 23591 | |
| 23592 | refused_A |
| 23593 | |
| 23594 | A connection to a host not obtained from an MX record was refused. |
| 23595 | |
| 23596 | refused |
| 23597 | |
| 23598 | A connection was refused. |
| 23599 | |
| 23600 | timeout_connect_MX |
| 23601 | |
| 23602 | A connection attempt to a host obtained from an MX record timed out. |
| 23603 | |
| 23604 | timeout_connect_A |
| 23605 | |
| 23606 | A connection attempt to a host not obtained from an MX record timed out. |
| 23607 | |
| 23608 | timeout_connect |
| 23609 | |
| 23610 | A connection attempt timed out. |
| 23611 | |
| 23612 | timeout_MX |
| 23613 | |
| 23614 | There was a timeout while connecting or during an SMTP session with a host |
| 23615 | obtained from an MX record. |
| 23616 | |
| 23617 | timeout_A |
| 23618 | |
| 23619 | There was a timeout while connecting or during an SMTP session with a host |
| 23620 | not obtained from an MX record. |
| 23621 | |
| 23622 | timeout |
| 23623 | |
| 23624 | There was a timeout while connecting or during an SMTP session. |
| 23625 | |
| 23626 | tls_required |
| 23627 | |
| 23628 | The server was required to use TLS (it matched hosts_require_tls in the |
| 23629 | smtp transport), but either did not offer TLS, or it responded with 4xx to |
| 23630 | STARTTLS, or there was a problem setting up the TLS connection. |
| 23631 | |
| 23632 | quota |
| 23633 | |
| 23634 | A mailbox quota was exceeded in a local delivery by the appendfile |
| 23635 | transport. |
| 23636 | |
| 23637 | quota_<time> |
| 23638 | |
| 23639 | A mailbox quota was exceeded in a local delivery by the appendfile |
| 23640 | transport, and the mailbox has not been accessed for <time>. For example, |
| 23641 | quota_4d applies to a quota error when the mailbox has not been accessed |
| 23642 | for four days. |
| 23643 | |
| 23644 | The idea of quota_<time> is to make it possible to have shorter timeouts when |
| 23645 | the mailbox is full and is not being read by its owner. Ideally, it should be |
| 23646 | based on the last time that the user accessed the mailbox. However, it is not |
| 23647 | always possible to determine this. Exim uses the following heuristic rules: |
| 23648 | |
| 23649 | * If the mailbox is a single file, the time of last access (the "atime") is |
| 23650 | used. As no new messages are being delivered (because the mailbox is over |
| 23651 | quota), Exim does not access the file, so this is the time of last user |
| 23652 | access. |
| 23653 | |
| 23654 | * For a maildir delivery, the time of last modification of the new |
| 23655 | subdirectory is used. As the mailbox is over quota, no new files are |
| 23656 | created in the new subdirectory, because no new messages are being |
| 23657 | delivered. Any change to the new subdirectory is therefore assumed to be |
| 23658 | the result of an MUA moving a new message to the cur directory when it is |
| 23659 | first read. The time that is used is therefore the last time that the user |
| 23660 | read a new message. |
| 23661 | |
| 23662 | * For other kinds of multi-file mailbox, the time of last access cannot be |
| 23663 | obtained, so a retry rule that uses this type of error field is never |
| 23664 | matched. |
| 23665 | |
| 23666 | The quota errors apply both to system-enforced quotas and to Exim's own quota |
| 23667 | mechanism in the appendfile transport. The quota error also applies when a |
| 23668 | local delivery is deferred because a partition is full (the ENOSPC error). |
| 23669 | |
| 23670 | |
| 23671 | 32.6 Retry rules for specified senders |
| 23672 | -------------------------------------- |
| 23673 | |
| 23674 | You can specify retry rules that apply only when the failing message has a |
| 23675 | specific sender. In particular, this can be used to define retry rules that |
| 23676 | apply only to bounce messages. The third item in a retry rule can be of this |
| 23677 | form: |
| 23678 | |
| 23679 | senders=<address list> |
| 23680 | |
| 23681 | The retry timings themselves are then the fourth item. For example: |
| 23682 | |
| 23683 | * rcpt_4xx senders=: F,1h,30m |
| 23684 | |
| 23685 | matches recipient 4xx errors for bounce messages sent to any address at any |
| 23686 | host. If the address list contains white space, it must be enclosed in quotes. |
| 23687 | For example: |
| 23688 | |
| 23689 | a.domain rcpt_452 senders="xb.dom : yc.dom" G,8h,10m,1.5 |
| 23690 | |
| 23691 | Warning: This facility can be unhelpful if it is used for host errors (which do |
| 23692 | not depend on the recipient). The reason is that the sender is used only to |
| 23693 | match the retry rule. Once the rule has been found for a host error, its |
| 23694 | contents are used to set a retry time for the host, and this will apply to all |
| 23695 | messages, not just those with specific senders. |
| 23696 | |
| 23697 | When testing retry rules using -brt, you can supply a sender using the -f |
| 23698 | command line option, like this: |
| 23699 | |
| 23700 | exim -f "" -brt user@dom.ain |
| 23701 | |
| 23702 | If you do not set -f with -brt, a retry rule that contains a senders list is |
| 23703 | never matched. |
| 23704 | |
| 23705 | |
| 23706 | 32.7 Retry parameters |
| 23707 | --------------------- |
| 23708 | |
| 23709 | The third (or fourth, if a senders list is present) field in a retry rule is a |
| 23710 | sequence of retry parameter sets, separated by semicolons. Each set consists of |
| 23711 | |
| 23712 | <letter>,<cutoff time>,<arguments> |
| 23713 | |
| 23714 | The letter identifies the algorithm for computing a new retry time; the cutoff |
| 23715 | time is the time beyond which this algorithm no longer applies, and the |
| 23716 | arguments vary the algorithm's action. The cutoff time is measured from the |
| 23717 | time that the first failure for the domain (combined with the local part if |
| 23718 | relevant) was detected, not from the time the message was received. |
| 23719 | |
| 23720 | The available algorithms are: |
| 23721 | |
| 23722 | * F: retry at fixed intervals. There is a single time parameter specifying |
| 23723 | the interval. |
| 23724 | |
| 23725 | * G: retry at geometrically increasing intervals. The first argument |
| 23726 | specifies a starting value for the interval, and the second a multiplier, |
| 23727 | which is used to increase the size of the interval at each retry. |
| 23728 | |
| 23729 | * H: retry at randomized intervals. The arguments are as for G. For each |
| 23730 | retry, the previous interval is multiplied by the factor in order to get a |
| 23731 | maximum for the next interval. The minimum interval is the first argument |
| 23732 | of the parameter, and an actual interval is chosen randomly between them. |
| 23733 | Such a rule has been found to be helpful in cluster configurations when all |
| 23734 | the members of the cluster restart at once, and may therefore synchronize |
| 23735 | their queue processing times. |
| 23736 | |
| 23737 | When computing the next retry time, the algorithm definitions are scanned in |
| 23738 | order until one whose cutoff time has not yet passed is reached. This is then |
| 23739 | used to compute a new retry time that is later than the current time. In the |
| 23740 | case of fixed interval retries, this simply means adding the interval to the |
| 23741 | current time. For geometrically increasing intervals, retry intervals are |
| 23742 | computed from the rule's parameters until one that is greater than the previous |
| 23743 | interval is found. The main configuration variable retry_interval_max limits |
| 23744 | the maximum interval between retries. It cannot be set greater than "24h", |
| 23745 | which is its default value. |
| 23746 | |
| 23747 | A single remote domain may have a number of hosts associated with it, and each |
| 23748 | host may have more than one IP address. Retry algorithms are selected on the |
| 23749 | basis of the domain name, but are applied to each IP address independently. If, |
| 23750 | for example, a host has two IP addresses and one is unusable, Exim will |
| 23751 | generate retry times for it and will not try to use it until its next retry |
| 23752 | time comes. Thus the good IP address is likely to be tried first most of the |
| 23753 | time. |
| 23754 | |
| 23755 | Retry times are hints rather than promises. Exim does not make any attempt to |
| 23756 | run deliveries exactly at the computed times. Instead, a queue runner process |
| 23757 | starts delivery processes for delayed messages periodically, and these attempt |
| 23758 | new deliveries only for those addresses that have passed their next retry time. |
| 23759 | If a new message arrives for a deferred address, an immediate delivery attempt |
| 23760 | occurs only if the address has passed its retry time. In the absence of new |
| 23761 | messages, the minimum time between retries is the interval between queue runner |
| 23762 | processes. There is not much point in setting retry times of five minutes if |
| 23763 | your queue runners happen only once an hour, unless there are a significant |
| 23764 | number of incoming messages (which might be the case on a system that is |
| 23765 | sending everything to a smart host, for example). |
| 23766 | |
| 23767 | The data in the retry hints database can be inspected by using the exim_dumpdb |
| 23768 | or exim_fixdb utility programs (see chapter 53). The latter utility can also be |
| 23769 | used to change the data. The exinext utility script can be used to find out |
| 23770 | what the next retry times are for the hosts associated with a particular mail |
| 23771 | domain, and also for local deliveries that have been deferred. |
| 23772 | |
| 23773 | |
| 23774 | 32.8 Retry rule examples |
| 23775 | ------------------------ |
| 23776 | |
| 23777 | Here are some example retry rules: |
| 23778 | |
| 23779 | alice@wonderland.fict.example quota_5d F,7d,3h |
| 23780 | wonderland.fict.example quota_5d |
| 23781 | wonderland.fict.example * F,1h,15m; G,2d,1h,2; |
| 23782 | lookingglass.fict.example * F,24h,30m; |
| 23783 | * refused_A F,2h,20m; |
| 23784 | * * F,2h,15m; G,16h,1h,1.5; F,5d,8h |
| 23785 | |
| 23786 | The first rule sets up special handling for mail to |
| 23787 | alice@wonderland.fict.example when there is an over-quota error and the mailbox |
| 23788 | has not been read for at least 5 days. Retries continue every three hours for 7 |
| 23789 | days. The second rule handles over-quota errors for all other local parts at |
| 23790 | wonderland.fict.example; the absence of a local part has the same effect as |
| 23791 | supplying "*@". As no retry algorithms are supplied, messages that fail are |
| 23792 | bounced immediately if the mailbox has not been read for at least 5 days. |
| 23793 | |
| 23794 | The third rule handles all other errors at wonderland.fict.example; retries |
| 23795 | happen every 15 minutes for an hour, then with geometrically increasing |
| 23796 | intervals until two days have passed since a delivery first failed. After the |
| 23797 | first hour there is a delay of one hour, then two hours, then four hours, and |
| 23798 | so on (this is a rather extreme example). |
| 23799 | |
| 23800 | The fourth rule controls retries for the domain lookingglass.fict.example. They |
| 23801 | happen every 30 minutes for 24 hours only. The remaining two rules handle all |
| 23802 | other domains, with special action for connection refusal from hosts that were |
| 23803 | not obtained from an MX record. |
| 23804 | |
| 23805 | The final rule in a retry configuration should always have asterisks in the |
| 23806 | first two fields so as to provide a general catch-all for any addresses that do |
| 23807 | not have their own special handling. This example tries every 15 minutes for 2 |
| 23808 | hours, then with intervals starting at one hour and increasing by a factor of |
| 23809 | 1.5 up to 16 hours, then every 8 hours up to 5 days. |
| 23810 | |
| 23811 | |
| 23812 | 32.9 Timeout of retry data |
| 23813 | -------------------------- |
| 23814 | |
| 23815 | Exim timestamps the data that it writes to its retry hints database. When it |
| 23816 | consults the data during a delivery it ignores any that is older than the value |
| 23817 | set in retry_data_expire (default 7 days). If, for example, a host hasn't been |
| 23818 | tried for 7 days, Exim will try to deliver to it immediately a message arrives, |
| 23819 | and if that fails, it will calculate a retry time as if it were failing for the |
| 23820 | first time. |
| 23821 | |
| 23822 | This improves the behaviour for messages routed to rarely-used hosts such as MX |
| 23823 | backups. If such a host was down at one time, and happens to be down again when |
| 23824 | Exim tries a month later, using the old retry data would imply that it had been |
| 23825 | down all the time, which is not a justified assumption. |
| 23826 | |
| 23827 | If a host really is permanently dead, this behaviour causes a burst of retries |
| 23828 | every now and again, but only if messages routed to it are rare. If there is a |
| 23829 | message at least once every 7 days the retry data never expires. |
| 23830 | |
| 23831 | |
| 23832 | 32.10 Long-term failures |
| 23833 | ------------------------ |
| 23834 | |
| 23835 | Special processing happens when an email address has been failing for so long |
| 23836 | that the cutoff time for the last algorithm is reached. For example, using the |
| 23837 | default retry rule: |
| 23838 | |
| 23839 | * * F,2h,15m; G,16h,1h,1.5; F,4d,6h |
| 23840 | |
| 23841 | the cutoff time is four days. Reaching the retry cutoff is independent of how |
| 23842 | long any specific message has been failing; it is the length of continuous |
| 23843 | failure for the recipient address that counts. |
| 23844 | |
| 23845 | When the cutoff time is reached for a local delivery, or for all the IP |
| 23846 | addresses associated with a remote delivery, a subsequent delivery failure |
| 23847 | causes Exim to give up on the address, and a bounce message is generated. In |
| 23848 | order to cater for new messages that use the failing address, a next retry time |
| 23849 | is still computed from the final algorithm, and is used as follows: |
| 23850 | |
| 23851 | For local deliveries, one delivery attempt is always made for any subsequent |
| 23852 | messages. If this delivery fails, the address fails immediately. The |
| 23853 | post-cutoff retry time is not used. |
| 23854 | |
| 23855 | If the delivery is remote, there are two possibilities, controlled by the |
| 23856 | delay_after_cutoff option of the smtp transport. The option is true by default. |
| 23857 | Until the post-cutoff retry time for one of the IP addresses is reached, the |
| 23858 | failing email address is bounced immediately, without a delivery attempt taking |
| 23859 | place. After that time, one new delivery attempt is made to those IP addresses |
| 23860 | that are past their retry times, and if that still fails, the address is |
| 23861 | bounced and new retry times are computed. |
| 23862 | |
| 23863 | In other words, when all the hosts for a given email address have been failing |
| 23864 | for a long time, Exim bounces rather then defers until one of the hosts' retry |
| 23865 | times is reached. Then it tries once, and bounces if that attempt fails. This |
| 23866 | behaviour ensures that few resources are wasted in repeatedly trying to deliver |
| 23867 | to a broken destination, but if the host does recover, Exim will eventually |
| 23868 | notice. |
| 23869 | |
| 23870 | If delay_after_cutoff is set false, Exim behaves differently. If all IP |
| 23871 | addresses are past their final cutoff time, Exim tries to deliver to those IP |
| 23872 | addresses that have not been tried since the message arrived. If there are no |
| 23873 | suitable IP addresses, or if they all fail, the address is bounced. In other |
| 23874 | words, it does not delay when a new message arrives, but tries the expired |
| 23875 | addresses immediately, unless they have been tried since the message arrived. |
| 23876 | If there is a continuous stream of messages for the failing domains, setting |
| 23877 | delay_after_cutoff false means that there will be many more attempts to deliver |
| 23878 | to permanently failing IP addresses than when delay_after_cutoff is true. |
| 23879 | |
| 23880 | |
| 23881 | 32.11 Deliveries that work intermittently |
| 23882 | ----------------------------------------- |
| 23883 | |
| 23884 | Some additional logic is needed to cope with cases where a host is |
| 23885 | intermittently available, or when a message has some attribute that prevents |
| 23886 | its delivery when others to the same address get through. In this situation, |
| 23887 | because some messages are successfully delivered, the "retry clock" for the |
| 23888 | host or address keeps getting reset by the successful deliveries, and so |
| 23889 | failing messages remain on the queue for ever because the cutoff time is never |
| 23890 | reached. |
| 23891 | |
| 23892 | Two exceptional actions are applied to prevent this happening. The first |
| 23893 | applies to errors that are related to a message rather than a remote host. |
| 23894 | Section 48.2 has a discussion of the different kinds of error; examples of |
| 23895 | message-related errors are 4xx responses to MAIL or DATA commands, and quota |
| 23896 | failures. For this type of error, if a message's arrival time is earlier than |
| 23897 | the "first failed" time for the error, the earlier time is used when scanning |
| 23898 | the retry rules to decide when to try next and when to time out the address. |
| 23899 | |
| 23900 | The exceptional second action applies in all cases. If a message has been on |
| 23901 | the queue for longer than the cutoff time of any applicable retry rule for a |
| 23902 | given address, a delivery is attempted for that address, even if it is not yet |
| 23903 | time, and if this delivery fails, the address is timed out. A new retry time is |
| 23904 | not computed in this case, so that other messages for the same address are |
| 23905 | considered immediately. |
| 23906 | |
| 23907 | |
| 23908 | |
| 23909 | =============================================================================== |
| 23910 | 33. SMTP AUTHENTICATION |
| 23911 | |
| 23912 | The "authenticators" section of Exim's run time configuration is concerned with |
| 23913 | SMTP authentication. This facility is an extension to the SMTP protocol, |
| 23914 | described in RFC 2554, which allows a client SMTP host to authenticate itself |
| 23915 | to a server. This is a common way for a server to recognize clients that are |
| 23916 | permitted to use it as a relay. SMTP authentication is not of relevance to the |
| 23917 | transfer of mail between servers that have no managerial connection with each |
| 23918 | other. |
| 23919 | |
| 23920 | Very briefly, the way SMTP authentication works is as follows: |
| 23921 | |
| 23922 | * The server advertises a number of authentication mechanisms in response to |
| 23923 | the client's EHLO command. |
| 23924 | |
| 23925 | * The client issues an AUTH command, naming a specific mechanism. The command |
| 23926 | may, optionally, contain some authentication data. |
| 23927 | |
| 23928 | * The server may issue one or more challenges, to which the client must send |
| 23929 | appropriate responses. In simple authentication mechanisms, the challenges |
| 23930 | are just prompts for user names and passwords. The server does not have to |
| 23931 | issue any challenges - in some mechanisms the relevant data may all be |
| 23932 | transmitted with the AUTH command. |
| 23933 | |
| 23934 | * The server either accepts or denies authentication. |
| 23935 | |
| 23936 | * If authentication succeeds, the client may optionally make use of the AUTH |
| 23937 | option on the MAIL command to pass an authenticated sender in subsequent |
| 23938 | mail transactions. Authentication lasts for the remainder of the SMTP |
| 23939 | connection. |
| 23940 | |
| 23941 | * If authentication fails, the client may give up, or it may try a different |
| 23942 | authentication mechanism, or it may try transferring mail over the |
| 23943 | unauthenticated connection. |
| 23944 | |
| 23945 | If you are setting up a client, and want to know which authentication |
| 23946 | mechanisms the server supports, you can use Telnet to connect to port 25 (the |
| 23947 | SMTP port) on the server, and issue an EHLO command. The response to this |
| 23948 | includes the list of supported mechanisms. For example: |
| 23949 | |
| 23950 | $ telnet server.example 25 |
| 23951 | Trying 192.168.34.25... |
| 23952 | Connected to server.example. |
| 23953 | Escape character is '^]'. |
| 23954 | 220 server.example ESMTP Exim 4.20 ... |
| 23955 | ehlo client.example |
| 23956 | 250-server.example Hello client.example [10.8.4.5] |
| 23957 | 250-SIZE 52428800 |
| 23958 | 250-PIPELINING |
| 23959 | 250-AUTH PLAIN |
| 23960 | 250 HELP |
| 23961 | |
| 23962 | The second-last line of this example output shows that the server supports |
| 23963 | authentication using the PLAIN mechanism. In Exim, the different authentication |
| 23964 | mechanisms are configured by specifying authenticator drivers. Like the routers |
| 23965 | and transports, which authenticators are included in the binary is controlled |
| 23966 | by build-time definitions. The following are currently available, included by |
| 23967 | setting |
| 23968 | |
| 23969 | AUTH_CRAM_MD5=yes |
| 23970 | AUTH_CYRUS_SASL=yes |
| 23971 | AUTH_DOVECOT=yes |
| 23972 | AUTH_GSASL=yes |
| 23973 | AUTH_HEIMDAL_GSSAPI=yes |
| 23974 | AUTH_PLAINTEXT=yes |
| 23975 | AUTH_SPA=yes |
| 23976 | AUTH_TLS=yes |
| 23977 | |
| 23978 | in Local/Makefile, respectively. The first of these supports the CRAM-MD5 |
| 23979 | authentication mechanism (RFC 2195), and the second provides an interface to |
| 23980 | the Cyrus SASL authentication library. The third is an interface to Dovecot's |
| 23981 | authentication system, delegating the work via a socket interface. The fourth |
| 23982 | provides an interface to the GNU SASL authentication library, which provides |
| 23983 | mechanisms but typically not data sources. The fifth provides direct access to |
| 23984 | Heimdal GSSAPI, geared for Kerberos, but supporting setting a server keytab. |
| 23985 | The sixth can be configured to support the PLAIN authentication mechanism (RFC |
| 23986 | 2595) or the LOGIN mechanism, which is not formally documented, but used by |
| 23987 | several MUAs. The seventh authenticator supports Microsoft's Secure Password |
| 23988 | Authentication mechanism. The eighth is an Exim authenticator but not an SMTP |
| 23989 | one; instead it can use information from a TLS negotiation. |
| 23990 | |
| 23991 | The authenticators are configured using the same syntax as other drivers (see |
| 23992 | section 6.23). If no authenticators are required, no authentication section |
| 23993 | need be present in the configuration file. Each authenticator can in principle |
| 23994 | have both server and client functions. When Exim is receiving SMTP mail, it is |
| 23995 | acting as a server; when it is sending out messages over SMTP, it is acting as |
| 23996 | a client. Authenticator configuration options are provided for use in both |
| 23997 | these circumstances. |
| 23998 | |
| 23999 | To make it clear which options apply to which situation, the prefixes server_ |
| 24000 | and client_ are used on option names that are specific to either the server or |
| 24001 | the client function, respectively. Server and client functions are disabled if |
| 24002 | none of their options are set. If an authenticator is to be used for both |
| 24003 | server and client functions, a single definition, using both sets of options, |
| 24004 | is required. For example: |
| 24005 | |
| 24006 | cram: |
| 24007 | driver = cram_md5 |
| 24008 | public_name = CRAM-MD5 |
| 24009 | server_secret = ${if eq{$auth1}{ph10}{secret1}fail} |
| 24010 | client_name = ph10 |
| 24011 | client_secret = secret2 |
| 24012 | |
| 24013 | The server_ option is used when Exim is acting as a server, and the client_ |
| 24014 | options when it is acting as a client. |
| 24015 | |
| 24016 | Descriptions of the individual authenticators are given in subsequent chapters. |
| 24017 | The remainder of this chapter covers the generic options for the |
| 24018 | authenticators, followed by general discussion of the way authentication works |
| 24019 | in Exim. |
| 24020 | |
| 24021 | Beware: the meaning of $auth1, $auth2, ... varies on a per-driver and |
| 24022 | per-mechanism basis. Please read carefully to determine which variables hold |
| 24023 | account labels such as usercodes and which hold passwords or other |
| 24024 | authenticating data. |
| 24025 | |
| 24026 | Note that some mechanisms support two different identifiers for accounts: the |
| 24027 | authentication id and the authorization id. The contractions authn and authz |
| 24028 | are commonly encountered. The American spelling is standard here. Conceptually, |
| 24029 | authentication data such as passwords are tied to the identifier used to |
| 24030 | authenticate; servers may have rules to permit one user to act as a second |
| 24031 | user, so that after login the session is treated as though that second user had |
| 24032 | logged in. That second user is the authorization id. A robust configuration |
| 24033 | might confirm that the authz field is empty or matches the authn field. Often |
| 24034 | this is just ignored. The authn can be considered as verified data, the authz |
| 24035 | as an unverified request which the server might choose to honour. |
| 24036 | |
| 24037 | A realm is a text string, typically a domain name, presented by a server to a |
| 24038 | client to help it select an account and credentials to use. In some mechanisms, |
| 24039 | the client and server provably agree on the realm, but clients typically can |
| 24040 | not treat the realm as secure data to be blindly trusted. |
| 24041 | |
| 24042 | |
| 24043 | 33.1 Generic options for authenticators |
| 24044 | --------------------------------------- |
| 24045 | |
| 24046 | +-----------------------------------------------------------------+ |
| 24047 | |client_condition|Use: authenticators|Type: string*|Default: unset| |
| 24048 | +-----------------------------------------------------------------+ |
| 24049 | |
| 24050 | When Exim is authenticating as a client, it skips any authenticator whose |
| 24051 | client_condition expansion yields "0", "no", or "false". This can be used, for |
| 24052 | example, to skip plain text authenticators when the connection is not encrypted |
| 24053 | by a setting such as: |
| 24054 | |
| 24055 | client_condition = ${if !eq{$tls_out_cipher}{}} |
| 24056 | |
| 24057 | +--------------------------------------------------------------+ |
| 24058 | |client_set_id|Use: authenticators|Type: string*|Default: unset| |
| 24059 | +--------------------------------------------------------------+ |
| 24060 | |
| 24061 | When client authentication succeeds, this condition is expanded; the result is |
| 24062 | used in the log lines for outbound messages. Typically it will be the user name |
| 24063 | used for authentication. |
| 24064 | |
| 24065 | +------------------------------------------------------+ |
| 24066 | |driver|Use: authenticators|Type: string|Default: unset| |
| 24067 | +------------------------------------------------------+ |
| 24068 | |
| 24069 | This option must always be set. It specifies which of the available |
| 24070 | authenticators is to be used. |
| 24071 | |
| 24072 | +-----------------------------------------------------------+ |
| 24073 | |public_name|Use: authenticators|Type: string|Default: unset| |
| 24074 | +-----------------------------------------------------------+ |
| 24075 | |
| 24076 | This option specifies the name of the authentication mechanism that the driver |
| 24077 | implements, and by which it is known to the outside world. These names should |
| 24078 | contain only upper case letters, digits, underscores, and hyphens (RFC 2222), |
| 24079 | but Exim in fact matches them caselessly. If public_name is not set, it |
| 24080 | defaults to the driver's instance name. |
| 24081 | |
| 24082 | +---------------------------------------------------------------------------+ |
| 24083 | |server_advertise_condition|Use: authenticators|Type: string*|Default: unset| |
| 24084 | +---------------------------------------------------------------------------+ |
| 24085 | |
| 24086 | When a server is about to advertise an authentication mechanism, the condition |
| 24087 | is expanded. If it yields the empty string, "0", "no", or "false", the |
| 24088 | mechanism is not advertised. If the expansion fails, the mechanism is not |
| 24089 | advertised. If the failure was not forced, and was not caused by a lookup |
| 24090 | defer, the incident is logged. See section 33.3 below for further discussion. |
| 24091 | |
| 24092 | +-----------------------------------------------------------------+ |
| 24093 | |server_condition|Use: authenticators|Type: string*|Default: unset| |
| 24094 | +-----------------------------------------------------------------+ |
| 24095 | |
| 24096 | This option must be set for a plaintext server authenticator, where it is used |
| 24097 | directly to control authentication. See section 34.2 for details. |
| 24098 | |
| 24099 | For the gsasl authenticator, this option is required for various mechanisms; |
| 24100 | see chapter 38 for details. |
| 24101 | |
| 24102 | For the other authenticators, server_condition can be used as an additional |
| 24103 | authentication or authorization mechanism that is applied after the other |
| 24104 | authenticator conditions succeed. If it is set, it is expanded when the |
| 24105 | authenticator would otherwise return a success code. If the expansion is forced |
| 24106 | to fail, authentication fails. Any other expansion failure causes a temporary |
| 24107 | error code to be returned. If the result of a successful expansion is an empty |
| 24108 | string, "0", "no", or "false", authentication fails. If the result of the |
| 24109 | expansion is "1", "yes", or "true", authentication succeeds. For any other |
| 24110 | result, a temporary error code is returned, with the expanded string as the |
| 24111 | error text. |
| 24112 | |
| 24113 | +-------------------------------------------------------------------+ |
| 24114 | |server_debug_print|Use: authenticators|Type: string*|Default: unset| |
| 24115 | +-------------------------------------------------------------------+ |
| 24116 | |
| 24117 | If this option is set and authentication debugging is enabled (see the -d |
| 24118 | command line option), the string is expanded and included in the debugging |
| 24119 | output when the authenticator is run as a server. This can help with checking |
| 24120 | out the values of variables. If expansion of the string fails, the error |
| 24121 | message is written to the debugging output, and Exim carries on processing. |
| 24122 | |
| 24123 | +--------------------------------------------------------------+ |
| 24124 | |server_set_id|Use: authenticators|Type: string*|Default: unset| |
| 24125 | +--------------------------------------------------------------+ |
| 24126 | |
| 24127 | When an Exim server successfully authenticates a client, this string is |
| 24128 | expanded using data from the authentication, and preserved for any incoming |
| 24129 | messages in the variable $authenticated_id. It is also included in the log |
| 24130 | lines for incoming messages. For example, a user/password authenticator |
| 24131 | configuration might preserve the user name that was used to authenticate, and |
| 24132 | refer to it subsequently during delivery of the message. If expansion fails, |
| 24133 | the option is ignored. |
| 24134 | |
| 24135 | +---------------------------------------------------------------------------+ |
| 24136 | |server_mail_auth_condition|Use: authenticators|Type: string*|Default: unset| |
| 24137 | +---------------------------------------------------------------------------+ |
| 24138 | |
| 24139 | This option allows a server to discard authenticated sender addresses supplied |
| 24140 | as part of MAIL commands in SMTP connections that are authenticated by the |
| 24141 | driver on which server_mail_auth_condition is set. The option is not used as |
| 24142 | part of the authentication process; instead its (unexpanded) value is |
| 24143 | remembered for later use. How it is used is described in the following section. |
| 24144 | |
| 24145 | |
| 24146 | 33.2 The AUTH parameter on MAIL commands |
| 24147 | ---------------------------------------- |
| 24148 | |
| 24149 | When a client supplied an AUTH= item on a MAIL command, Exim applies the |
| 24150 | following checks before accepting it as the authenticated sender of the |
| 24151 | message: |
| 24152 | |
| 24153 | * If the connection is not using extended SMTP (that is, HELO was used rather |
| 24154 | than EHLO), the use of AUTH= is a syntax error. |
| 24155 | |
| 24156 | * If the value of the AUTH= parameter is "<>", it is ignored. |
| 24157 | |
| 24158 | * If acl_smtp_mailauth is defined, the ACL it specifies is run. While it is |
| 24159 | running, the value of $authenticated_sender is set to the value obtained |
| 24160 | from the AUTH= parameter. If the ACL does not yield "accept", the value of |
| 24161 | $authenticated_sender is deleted. The acl_smtp_mailauth ACL may not return |
| 24162 | "drop" or "discard". If it defers, a temporary error code (451) is given |
| 24163 | for the MAIL command. |
| 24164 | |
| 24165 | * If acl_smtp_mailauth is not defined, the value of the AUTH= parameter is |
| 24166 | accepted and placed in $authenticated_sender only if the client has |
| 24167 | authenticated. |
| 24168 | |
| 24169 | * If the AUTH= value was accepted by either of the two previous rules, and |
| 24170 | the client has authenticated, and the authenticator has a setting for the |
| 24171 | server_mail_auth_condition, the condition is checked at this point. The |
| 24172 | valued that was saved from the authenticator is expanded. If the expansion |
| 24173 | fails, or yields an empty string, "0", "no", or "false", the value of |
| 24174 | $authenticated_sender is deleted. If the expansion yields any other value, |
| 24175 | the value of $authenticated_sender is retained and passed on with the |
| 24176 | message. |
| 24177 | |
| 24178 | When $authenticated_sender is set for a message, it is passed on to other hosts |
| 24179 | to which Exim authenticates as a client. Do not confuse this value with |
| 24180 | $authenticated_id, which is a string obtained from the authentication process, |
| 24181 | and which is not usually a complete email address. |
| 24182 | |
| 24183 | Whenever an AUTH= value is ignored, the incident is logged. The ACL for MAIL, |
| 24184 | if defined, is run after AUTH= is accepted or ignored. It can therefore make |
| 24185 | use of $authenticated_sender. The converse is not true: the value of |
| 24186 | $sender_address is not yet set up when the acl_smtp_mailauth ACL is run. |
| 24187 | |
| 24188 | |
| 24189 | 33.3 Authentication on an Exim server |
| 24190 | ------------------------------------- |
| 24191 | |
| 24192 | When Exim receives an EHLO command, it advertises the public names of those |
| 24193 | authenticators that are configured as servers, subject to the following |
| 24194 | conditions: |
| 24195 | |
| 24196 | * The client host must match auth_advertise_hosts (default *). |
| 24197 | |
| 24198 | * It the server_advertise_condition option is set, its expansion must not |
| 24199 | yield the empty string, "0", "no", or "false". |
| 24200 | |
| 24201 | The order in which the authenticators are defined controls the order in which |
| 24202 | the mechanisms are advertised. |
| 24203 | |
| 24204 | Some mail clients (for example, some versions of Netscape) require the user to |
| 24205 | provide a name and password for authentication whenever AUTH is advertised, |
| 24206 | even though authentication may not in fact be needed (for example, Exim may be |
| 24207 | set up to allow unconditional relaying from the client by an IP address check). |
| 24208 | You can make such clients more friendly by not advertising AUTH to them. For |
| 24209 | example, if clients on the 10.9.8.0/24 network are permitted (by the ACL that |
| 24210 | runs for RCPT) to relay without authentication, you should set |
| 24211 | |
| 24212 | auth_advertise_hosts = ! 10.9.8.0/24 |
| 24213 | |
| 24214 | so that no authentication mechanisms are advertised to them. |
| 24215 | |
| 24216 | The server_advertise_condition controls the advertisement of individual |
| 24217 | authentication mechanisms. For example, it can be used to restrict the |
| 24218 | advertisement of a particular mechanism to encrypted connections, by a setting |
| 24219 | such as: |
| 24220 | |
| 24221 | server_advertise_condition = ${if eq{$tls_in_cipher}{}{no}{yes}} |
| 24222 | |
| 24223 | If the session is encrypted, $tls_in_cipher is not empty, and so the expansion |
| 24224 | yields "yes", which allows the advertisement to happen. |
| 24225 | |
| 24226 | When an Exim server receives an AUTH command from a client, it rejects it |
| 24227 | immediately if AUTH was not advertised in response to an earlier EHLO command. |
| 24228 | This is the case if |
| 24229 | |
| 24230 | * The client host does not match auth_advertise_hosts; or |
| 24231 | |
| 24232 | * No authenticators are configured with server options; or |
| 24233 | |
| 24234 | * Expansion of server_advertise_condition blocked the advertising of all the |
| 24235 | server authenticators. |
| 24236 | |
| 24237 | Otherwise, Exim runs the ACL specified by acl_smtp_auth in order to decide |
| 24238 | whether to accept the command. If acl_smtp_auth is not set, AUTH is accepted |
| 24239 | from any client host. |
| 24240 | |
| 24241 | If AUTH is not rejected by the ACL, Exim searches its configuration for a |
| 24242 | server authentication mechanism that was advertised in response to EHLO and |
| 24243 | that matches the one named in the AUTH command. If it finds one, it runs the |
| 24244 | appropriate authentication protocol, and authentication either succeeds or |
| 24245 | fails. If there is no matching advertised mechanism, the AUTH command is |
| 24246 | rejected with a 504 error. |
| 24247 | |
| 24248 | When a message is received from an authenticated host, the value of |
| 24249 | $received_protocol is set to "esmtpa" or "esmtpsa" instead of "esmtp" or |
| 24250 | "esmtps", and $sender_host_authenticated contains the name (not the public |
| 24251 | name) of the authenticator driver that successfully authenticated the client |
| 24252 | from which the message was received. This variable is empty if there was no |
| 24253 | successful authentication. |
| 24254 | |
| 24255 | |
| 24256 | 33.4 Testing server authentication |
| 24257 | ---------------------------------- |
| 24258 | |
| 24259 | Exim's -bh option can be useful for testing server authentication |
| 24260 | configurations. The data for the AUTH command has to be sent using base64 |
| 24261 | encoding. A quick way to produce such data for testing is the following Perl |
| 24262 | script: |
| 24263 | |
| 24264 | use MIME::Base64; |
| 24265 | printf ("%s", encode_base64(eval "\"$ARGV[0]\"")); |
| 24266 | |
| 24267 | This interprets its argument as a Perl string, and then encodes it. The |
| 24268 | interpretation as a Perl string allows binary zeros, which are required for |
| 24269 | some kinds of authentication, to be included in the data. For example, a |
| 24270 | command line to run this script on such data might be |
| 24271 | |
| 24272 | encode '\0user\0password' |
| 24273 | |
| 24274 | Note the use of single quotes to prevent the shell interpreting the |
| 24275 | backslashes, so that they can be interpreted by Perl to specify characters |
| 24276 | whose code value is zero. |
| 24277 | |
| 24278 | Warning 1: If either of the user or password strings starts with an octal |
| 24279 | digit, you must use three zeros instead of one after the leading backslash. If |
| 24280 | you do not, the octal digit that starts your string will be incorrectly |
| 24281 | interpreted as part of the code for the first character. |
| 24282 | |
| 24283 | Warning 2: If there are characters in the strings that Perl interprets |
| 24284 | specially, you must use a Perl escape to prevent them being misinterpreted. For |
| 24285 | example, a command such as |
| 24286 | |
| 24287 | encode '\0user@domain.com\0pas$$word' |
| 24288 | |
| 24289 | gives an incorrect answer because of the unescaped "@" and "$" characters. |
| 24290 | |
| 24291 | If you have the mimencode command installed, another way to do produce |
| 24292 | base64-encoded strings is to run the command |
| 24293 | |
| 24294 | echo -e -n `\0user\0password' | mimencode |
| 24295 | |
| 24296 | The -e option of echo enables the interpretation of backslash escapes in the |
| 24297 | argument, and the -n option specifies no newline at the end of its output. |
| 24298 | However, not all versions of echo recognize these options, so you should check |
| 24299 | your version before relying on this suggestion. |
| 24300 | |
| 24301 | |
| 24302 | 33.5 Authentication by an Exim client |
| 24303 | ------------------------------------- |
| 24304 | |
| 24305 | The smtp transport has two options called hosts_require_auth and hosts_try_auth |
| 24306 | . When the smtp transport connects to a server that announces support for |
| 24307 | authentication, and the host matches an entry in either of these options, Exim |
| 24308 | (as a client) tries to authenticate as follows: |
| 24309 | |
| 24310 | * For each authenticator that is configured as a client, in the order in |
| 24311 | which they are defined in the configuration, it searches the authentication |
| 24312 | mechanisms announced by the server for one whose name matches the public |
| 24313 | name of the authenticator. |
| 24314 | |
| 24315 | * When it finds one that matches, it runs the authenticator's client code. |
| 24316 | The variables $host and $host_address are available for any string |
| 24317 | expansions that the client might do. They are set to the server's name and |
| 24318 | IP address. If any expansion is forced to fail, the authentication attempt |
| 24319 | is abandoned, and Exim moves on to the next authenticator. Otherwise an |
| 24320 | expansion failure causes delivery to be deferred. |
| 24321 | |
| 24322 | * If the result of the authentication attempt is a temporary error or a |
| 24323 | timeout, Exim abandons trying to send the message to the host for the |
| 24324 | moment. It will try again later. If there are any backup hosts available, |
| 24325 | they are tried in the usual way. |
| 24326 | |
| 24327 | * If the response to authentication is a permanent error (5xx code), Exim |
| 24328 | carries on searching the list of authenticators and tries another one if |
| 24329 | possible. If all authentication attempts give permanent errors, or if there |
| 24330 | are no attempts because no mechanisms match (or option expansions force |
| 24331 | failure), what happens depends on whether the host matches |
| 24332 | hosts_require_auth or hosts_try_auth. In the first case, a temporary error |
| 24333 | is generated, and delivery is deferred. The error can be detected in the |
| 24334 | retry rules, and thereby turned into a permanent error if you wish. In the |
| 24335 | second case, Exim tries to deliver the message unauthenticated. |
| 24336 | |
| 24337 | Note that the hostlist test for whether to do authentication can be confused if |
| 24338 | name-IP lookups change between the time the peer is decided on and the |
| 24339 | transport running. For example, with a manualroute router given a host name, |
| 24340 | and DNS "round-robin" use by that name: if the local resolver cache times out |
| 24341 | between the router and the transport running, the transport may get an IP for |
| 24342 | the name for its authentication check which does not match the connection peer |
| 24343 | IP. No authentication will then be done, despite the names being identical. |
| 24344 | |
| 24345 | For such cases use a separate transport which always authenticates. |
| 24346 | |
| 24347 | When Exim has authenticated itself to a remote server, it adds the AUTH |
| 24348 | parameter to the MAIL commands it sends, if it has an authenticated sender for |
| 24349 | the message. If the message came from a remote host, the authenticated sender |
| 24350 | is the one that was receiving on an incoming MAIL command, provided that the |
| 24351 | incoming connection was authenticated and the server_mail_auth condition |
| 24352 | allowed the authenticated sender to be retained. If a local process calls Exim |
| 24353 | to send a message, the sender address that is built from the login name and |
| 24354 | qualify_domain is treated as authenticated. However, if the |
| 24355 | authenticated_sender option is set on the smtp transport, it overrides the |
| 24356 | authenticated sender that was received with the message. |
| 24357 | |
| 24358 | |
| 24359 | |
| 24360 | =============================================================================== |
| 24361 | 34. THE PLAINTEXT AUTHENTICATOR |
| 24362 | |
| 24363 | The plaintext authenticator can be configured to support the PLAIN and LOGIN |
| 24364 | authentication mechanisms, both of which transfer authentication data as plain |
| 24365 | (unencrypted) text (though base64 encoded). The use of plain text is a security |
| 24366 | risk; you are strongly advised to insist on the use of SMTP encryption (see |
| 24367 | chapter 42) if you use the PLAIN or LOGIN mechanisms. If you do use unencrypted |
| 24368 | plain text, you should not use the same passwords for SMTP connections as you |
| 24369 | do for login accounts. |
| 24370 | |
| 24371 | |
| 24372 | 34.1 Plaintext options |
| 24373 | ---------------------- |
| 24374 | |
| 24375 | When configured as a server, plaintext uses the following options: |
| 24376 | |
| 24377 | +-----------------------------------------------------------------+ |
| 24378 | |server_condition|Use: authenticators|Type: string*|Default: unset| |
| 24379 | +-----------------------------------------------------------------+ |
| 24380 | |
| 24381 | This is actually a global authentication option, but it must be set in order to |
| 24382 | configure the plaintext driver as a server. Its use is described below. |
| 24383 | |
| 24384 | +----------------------------------------------------------+ |
| 24385 | |server_prompts|Use: plaintext|Type: string*|Default: unset| |
| 24386 | +----------------------------------------------------------+ |
| 24387 | |
| 24388 | The contents of this option, after expansion, must be a colon-separated list of |
| 24389 | prompt strings. If expansion fails, a temporary authentication rejection is |
| 24390 | given. |
| 24391 | |
| 24392 | |
| 24393 | 34.2 Using plaintext in a server |
| 24394 | -------------------------------- |
| 24395 | |
| 24396 | When running as a server, plaintext performs the authentication test by |
| 24397 | expanding a string. The data sent by the client with the AUTH command, or in |
| 24398 | response to subsequent prompts, is base64 encoded, and so may contain any byte |
| 24399 | values when decoded. If any data is supplied with the command, it is treated as |
| 24400 | a list of strings, separated by NULs (binary zeros), the first three of which |
| 24401 | are placed in the expansion variables $auth1, $auth2, and $auth3 (neither LOGIN |
| 24402 | nor PLAIN uses more than three strings). |
| 24403 | |
| 24404 | For compatibility with previous releases of Exim, the values are also placed in |
| 24405 | the expansion variables $1, $2, and $3. However, the use of these variables for |
| 24406 | this purpose is now deprecated, as it can lead to confusion in string |
| 24407 | expansions that also use them for other things. |
| 24408 | |
| 24409 | If there are more strings in server_prompts than the number of strings supplied |
| 24410 | with the AUTH command, the remaining prompts are used to obtain more data. Each |
| 24411 | response from the client may be a list of NUL-separated strings. |
| 24412 | |
| 24413 | Once a sufficient number of data strings have been received, server_condition |
| 24414 | is expanded. If the expansion is forced to fail, authentication fails. Any |
| 24415 | other expansion failure causes a temporary error code to be returned. If the |
| 24416 | result of a successful expansion is an empty string, "0", "no", or "false", |
| 24417 | authentication fails. If the result of the expansion is "1", "yes", or "true", |
| 24418 | authentication succeeds and the generic server_set_id option is expanded and |
| 24419 | saved in $authenticated_id. For any other result, a temporary error code is |
| 24420 | returned, with the expanded string as the error text |
| 24421 | |
| 24422 | Warning: If you use a lookup in the expansion to find the user's password, be |
| 24423 | sure to make the authentication fail if the user is unknown. There are good and |
| 24424 | bad examples at the end of the next section. |
| 24425 | |
| 24426 | |
| 24427 | 34.3 The PLAIN authentication mechanism |
| 24428 | --------------------------------------- |
| 24429 | |
| 24430 | The PLAIN authentication mechanism (RFC 2595) specifies that three strings be |
| 24431 | sent as one item of data (that is, one combined string containing two NUL |
| 24432 | separators). The data is sent either as part of the AUTH command, or |
| 24433 | subsequently in response to an empty prompt from the server. |
| 24434 | |
| 24435 | The second and third strings are a user name and a corresponding password. |
| 24436 | Using a single fixed user name and password as an example, this could be |
| 24437 | configured as follows: |
| 24438 | |
| 24439 | fixed_plain: |
| 24440 | driver = plaintext |
| 24441 | public_name = PLAIN |
| 24442 | server_prompts = : |
| 24443 | server_condition = \ |
| 24444 | ${if and {{eq{$auth2}{username}}{eq{$auth3}{mysecret}}}} |
| 24445 | server_set_id = $auth2 |
| 24446 | |
| 24447 | Note that the default result strings from if ("true" or an empty string) are |
| 24448 | exactly what we want here, so they need not be specified. Obviously, if the |
| 24449 | password contains expansion-significant characters such as dollar, backslash, |
| 24450 | or closing brace, they have to be escaped. |
| 24451 | |
| 24452 | The server_prompts setting specifies a single, empty prompt (empty items at the |
| 24453 | end of a string list are ignored). If all the data comes as part of the AUTH |
| 24454 | command, as is commonly the case, the prompt is not used. This authenticator is |
| 24455 | advertised in the response to EHLO as |
| 24456 | |
| 24457 | 250-AUTH PLAIN |
| 24458 | |
| 24459 | and a client host can authenticate itself by sending the command |
| 24460 | |
| 24461 | AUTH PLAIN AHVzZXJuYW1lAG15c2VjcmV0 |
| 24462 | |
| 24463 | As this contains three strings (more than the number of prompts), no further |
| 24464 | data is required from the client. Alternatively, the client may just send |
| 24465 | |
| 24466 | AUTH PLAIN |
| 24467 | |
| 24468 | to initiate authentication, in which case the server replies with an empty |
| 24469 | prompt. The client must respond with the combined data string. |
| 24470 | |
| 24471 | The data string is base64 encoded, as required by the RFC. This example, when |
| 24472 | decoded, is <NUL>"username"<NUL>"mysecret", where <NUL> represents a zero byte. |
| 24473 | This is split up into three strings, the first of which is empty. The |
| 24474 | server_condition option in the authenticator checks that the second two are |
| 24475 | "username" and "mysecret" respectively. |
| 24476 | |
| 24477 | Having just one fixed user name and password, as in this example, is not very |
| 24478 | realistic, though for a small organization with only a handful of |
| 24479 | authenticating clients it could make sense. |
| 24480 | |
| 24481 | A more sophisticated instance of this authenticator could use the user name in |
| 24482 | $auth2 to look up a password in a file or database, and maybe do an encrypted |
| 24483 | comparison (see crypteq in chapter 11). Here is a example of this approach, |
| 24484 | where the passwords are looked up in a DBM file. Warning: This is an incorrect |
| 24485 | example: |
| 24486 | |
| 24487 | server_condition = \ |
| 24488 | ${if eq{$auth3}{${lookup{$auth2}dbm{/etc/authpwd}}}} |
| 24489 | |
| 24490 | The expansion uses the user name ($auth2) as the key to look up a password, |
| 24491 | which it then compares to the supplied password ($auth3). Why is this example |
| 24492 | incorrect? It works fine for existing users, but consider what happens if a |
| 24493 | non-existent user name is given. The lookup fails, but as no success/failure |
| 24494 | strings are given for the lookup, it yields an empty string. Thus, to defeat |
| 24495 | the authentication, all a client has to do is to supply a non-existent user |
| 24496 | name and an empty password. The correct way of writing this test is: |
| 24497 | |
| 24498 | server_condition = ${lookup{$auth2}dbm{/etc/authpwd}\ |
| 24499 | {${if eq{$value}{$auth3}}} {false}} |
| 24500 | |
| 24501 | In this case, if the lookup succeeds, the result is checked; if the lookup |
| 24502 | fails, "false" is returned and authentication fails. If crypteq is being used |
| 24503 | instead of eq, the first example is in fact safe, because crypteq always fails |
| 24504 | if its second argument is empty. However, the second way of writing the test |
| 24505 | makes the logic clearer. |
| 24506 | |
| 24507 | |
| 24508 | 34.4 The LOGIN authentication mechanism |
| 24509 | --------------------------------------- |
| 24510 | |
| 24511 | The LOGIN authentication mechanism is not documented in any RFC, but is in use |
| 24512 | in a number of programs. No data is sent with the AUTH command. Instead, a user |
| 24513 | name and password are supplied separately, in response to prompts. The |
| 24514 | plaintext authenticator can be configured to support this as in this example: |
| 24515 | |
| 24516 | fixed_login: |
| 24517 | driver = plaintext |
| 24518 | public_name = LOGIN |
| 24519 | server_prompts = User Name : Password |
| 24520 | server_condition = \ |
| 24521 | ${if and {{eq{$auth1}{username}}{eq{$auth2}{mysecret}}}} |
| 24522 | server_set_id = $auth1 |
| 24523 | |
| 24524 | Because of the way plaintext operates, this authenticator accepts data supplied |
| 24525 | with the AUTH command (in contravention of the specification of LOGIN), but if |
| 24526 | the client does not supply it (as is the case for LOGIN clients), the prompt |
| 24527 | strings are used to obtain two data items. |
| 24528 | |
| 24529 | Some clients are very particular about the precise text of the prompts. For |
| 24530 | example, Outlook Express is reported to recognize only "Username:" and |
| 24531 | "Password:". Here is an example of a LOGIN authenticator that uses those |
| 24532 | strings. It uses the ldapauth expansion condition to check the user name and |
| 24533 | password by binding to an LDAP server: |
| 24534 | |
| 24535 | login: |
| 24536 | driver = plaintext |
| 24537 | public_name = LOGIN |
| 24538 | server_prompts = Username:: : Password:: |
| 24539 | server_condition = ${if and{{ \ |
| 24540 | !eq{}{$auth1} }{ \ |
| 24541 | ldapauth{\ |
| 24542 | user="uid=${quote_ldap_dn:$auth1},ou=people,o=example.org" \ |
| 24543 | pass=${quote:$auth2} \ |
| 24544 | ldap://ldap.example.org/} }} } |
| 24545 | server_set_id = uid=$auth1,ou=people,o=example.org |
| 24546 | |
| 24547 | We have to check that the username is not empty before using it, because LDAP |
| 24548 | does not permit empty DN components. We must also use the quote_ldap_dn |
| 24549 | operator to correctly quote the DN for authentication. However, the basic quote |
| 24550 | operator, rather than any of the LDAP quoting operators, is the correct one to |
| 24551 | use for the password, because quoting is needed only to make the password |
| 24552 | conform to the Exim syntax. At the LDAP level, the password is an uninterpreted |
| 24553 | string. |
| 24554 | |
| 24555 | |
| 24556 | 34.5 Support for different kinds of authentication |
| 24557 | -------------------------------------------------- |
| 24558 | |
| 24559 | A number of string expansion features are provided for the purpose of |
| 24560 | interfacing to different ways of user authentication. These include checking |
| 24561 | traditionally encrypted passwords from /etc/passwd (or equivalent), PAM, |
| 24562 | Radius, ldapauth, pwcheck, and saslauthd. For details see section 11.7. |
| 24563 | |
| 24564 | |
| 24565 | 34.6 Using plaintext in a client |
| 24566 | -------------------------------- |
| 24567 | |
| 24568 | The plaintext authenticator has two client options: |
| 24569 | |
| 24570 | +------------------------------------------------------------------------+ |
| 24571 | |client_ignore_invalid_base64|Use: plaintext|Type: boolean|Default: false| |
| 24572 | +------------------------------------------------------------------------+ |
| 24573 | |
| 24574 | If the client receives a server prompt that is not a valid base64 string, |
| 24575 | authentication is abandoned by default. However, if this option is set true, |
| 24576 | the error in the challenge is ignored and the client sends the response as |
| 24577 | usual. |
| 24578 | |
| 24579 | +-------------------------------------------------------+ |
| 24580 | |client_send|Use: plaintext|Type: string*|Default: unset| |
| 24581 | +-------------------------------------------------------+ |
| 24582 | |
| 24583 | The string is a colon-separated list of authentication data strings. Each |
| 24584 | string is independently expanded before being sent to the server. The first |
| 24585 | string is sent with the AUTH command; any more strings are sent in response to |
| 24586 | prompts from the server. Before each string is expanded, the value of the most |
| 24587 | recent prompt is placed in the next $auth<n> variable, starting with $auth1 for |
| 24588 | the first prompt. Up to three prompts are stored in this way. Thus, the prompt |
| 24589 | that is received in response to sending the first string (with the AUTH |
| 24590 | command) can be used in the expansion of the second string, and so on. If an |
| 24591 | invalid base64 string is received when client_ignore_invalid_base64 is set, an |
| 24592 | empty string is put in the $auth<n> variable. |
| 24593 | |
| 24594 | Note: You cannot use expansion to create multiple strings, because splitting |
| 24595 | takes priority and happens first. |
| 24596 | |
| 24597 | Because the PLAIN authentication mechanism requires NUL (binary zero) bytes in |
| 24598 | the data, further processing is applied to each string before it is sent. If |
| 24599 | there are any single circumflex characters in the string, they are converted to |
| 24600 | NULs. Should an actual circumflex be required as data, it must be doubled in |
| 24601 | the string. |
| 24602 | |
| 24603 | This is an example of a client configuration that implements the PLAIN |
| 24604 | authentication mechanism with a fixed user name and password: |
| 24605 | |
| 24606 | fixed_plain: |
| 24607 | driver = plaintext |
| 24608 | public_name = PLAIN |
| 24609 | client_send = ^username^mysecret |
| 24610 | |
| 24611 | The lack of colons means that the entire text is sent with the AUTH command, |
| 24612 | with the circumflex characters converted to NULs. A similar example that uses |
| 24613 | the LOGIN mechanism is: |
| 24614 | |
| 24615 | fixed_login: |
| 24616 | driver = plaintext |
| 24617 | public_name = LOGIN |
| 24618 | client_send = : username : mysecret |
| 24619 | |
| 24620 | The initial colon means that the first string is empty, so no data is sent with |
| 24621 | the AUTH command itself. The remaining strings are sent in response to prompts. |
| 24622 | |
| 24623 | |
| 24624 | |
| 24625 | =============================================================================== |
| 24626 | 35. THE CRAM_MD5 AUTHENTICATOR |
| 24627 | |
| 24628 | The CRAM-MD5 authentication mechanism is described in RFC 2195. The server |
| 24629 | sends a challenge string to the client, and the response consists of a user |
| 24630 | name and the CRAM-MD5 digest of the challenge string combined with a secret |
| 24631 | string (password) which is known to both server and client. Thus, the secret is |
| 24632 | not sent over the network as plain text, which makes this authenticator more |
| 24633 | secure than plaintext. However, the downside is that the secret has to be |
| 24634 | available in plain text at either end. |
| 24635 | |
| 24636 | |
| 24637 | 35.1 Using cram_md5 as a server |
| 24638 | ------------------------------- |
| 24639 | |
| 24640 | This authenticator has one server option, which must be set to configure the |
| 24641 | authenticator as a server: |
| 24642 | |
| 24643 | +--------------------------------------------------------+ |
| 24644 | |server_secret|Use: cram_md5|Type: string*|Default: unset| |
| 24645 | +--------------------------------------------------------+ |
| 24646 | |
| 24647 | When the server receives the client's response, the user name is placed in the |
| 24648 | expansion variable $auth1, and server_secret is expanded to obtain the password |
| 24649 | for that user. The server then computes the CRAM-MD5 digest that the client |
| 24650 | should have sent, and checks that it received the correct string. If the |
| 24651 | expansion of server_secret is forced to fail, authentication fails. If the |
| 24652 | expansion fails for some other reason, a temporary error code is returned to |
| 24653 | the client. |
| 24654 | |
| 24655 | For compatibility with previous releases of Exim, the user name is also placed |
| 24656 | in $1. However, the use of this variables for this purpose is now deprecated, |
| 24657 | as it can lead to confusion in string expansions that also use numeric |
| 24658 | variables for other things. |
| 24659 | |
| 24660 | For example, the following authenticator checks that the user name given by the |
| 24661 | client is "ph10", and if so, uses "secret" as the password. For any other user |
| 24662 | name, authentication fails. |
| 24663 | |
| 24664 | fixed_cram: |
| 24665 | driver = cram_md5 |
| 24666 | public_name = CRAM-MD5 |
| 24667 | server_secret = ${if eq{$auth1}{ph10}{secret}fail} |
| 24668 | server_set_id = $auth1 |
| 24669 | |
| 24670 | If authentication succeeds, the setting of server_set_id preserves the user |
| 24671 | name in $authenticated_id. A more typical configuration might look up the |
| 24672 | secret string in a file, using the user name as the key. For example: |
| 24673 | |
| 24674 | lookup_cram: |
| 24675 | driver = cram_md5 |
| 24676 | public_name = CRAM-MD5 |
| 24677 | server_secret = ${lookup{$auth1}lsearch{/etc/authpwd}\ |
| 24678 | {$value}fail} |
| 24679 | server_set_id = $auth1 |
| 24680 | |
| 24681 | Note that this expansion explicitly forces failure if the lookup fails because |
| 24682 | $auth1 contains an unknown user name. |
| 24683 | |
| 24684 | As another example, if you wish to re-use a Cyrus SASL sasldb2 file without |
| 24685 | using the relevant libraries, you need to know the realm to specify in the |
| 24686 | lookup and then ask for the "userPassword" attribute for that user in that |
| 24687 | realm, with: |
| 24688 | |
| 24689 | cyrusless_crammd5: |
| 24690 | driver = cram_md5 |
| 24691 | public_name = CRAM-MD5 |
| 24692 | server_secret = ${lookup{$auth1:mail.example.org:userPassword}\ |
| 24693 | dbmjz{/etc/sasldb2}{$value}fail} |
| 24694 | server_set_id = $auth1 |
| 24695 | |
| 24696 | |
| 24697 | 35.2 Using cram_md5 as a client |
| 24698 | ------------------------------- |
| 24699 | |
| 24700 | When used as a client, the cram_md5 authenticator has two options: |
| 24701 | |
| 24702 | +----------------------------------------------------------------------+ |
| 24703 | |client_name|Use: cram_md5|Type: string*|Default: the primary host name| |
| 24704 | +----------------------------------------------------------------------+ |
| 24705 | |
| 24706 | This string is expanded, and the result used as the user name data when |
| 24707 | computing the response to the server's challenge. |
| 24708 | |
| 24709 | +--------------------------------------------------------+ |
| 24710 | |client_secret|Use: cram_md5|Type: string*|Default: unset| |
| 24711 | +--------------------------------------------------------+ |
| 24712 | |
| 24713 | This option must be set for the authenticator to work as a client. Its value is |
| 24714 | expanded and the result used as the secret string when computing the response. |
| 24715 | |
| 24716 | Different user names and secrets can be used for different servers by referring |
| 24717 | to $host or $host_address in the options. Forced failure of either expansion |
| 24718 | string is treated as an indication that this authenticator is not prepared to |
| 24719 | handle this case. Exim moves on to the next configured client authenticator. |
| 24720 | Any other expansion failure causes Exim to give up trying to send the message |
| 24721 | to the current server. |
| 24722 | |
| 24723 | A simple example configuration of a cram_md5 authenticator, using fixed |
| 24724 | strings, is: |
| 24725 | |
| 24726 | fixed_cram: |
| 24727 | driver = cram_md5 |
| 24728 | public_name = CRAM-MD5 |
| 24729 | client_name = ph10 |
| 24730 | client_secret = secret |
| 24731 | |
| 24732 | |
| 24733 | |
| 24734 | =============================================================================== |
| 24735 | 36. THE CYRUS_SASL AUTHENTICATOR |
| 24736 | |
| 24737 | The code for this authenticator was provided by Matthew Byng-Maddick of A L |
| 24738 | Digital Ltd (http://www.aldigital.co.uk). |
| 24739 | |
| 24740 | The cyrus_sasl authenticator provides server support for the Cyrus SASL library |
| 24741 | implementation of the RFC 2222 ("Simple Authentication and Security Layer"). |
| 24742 | This library supports a number of authentication mechanisms, including PLAIN |
| 24743 | and LOGIN, but also several others that Exim does not support directly. In |
| 24744 | particular, there is support for Kerberos authentication. |
| 24745 | |
| 24746 | The cyrus_sasl authenticator provides a gatewaying mechanism directly to the |
| 24747 | Cyrus interface, so if your Cyrus library can do, for example, CRAM-MD5, then |
| 24748 | so can the cyrus_sasl authenticator. By default it uses the public name of the |
| 24749 | driver to determine which mechanism to support. |
| 24750 | |
| 24751 | Where access to some kind of secret file is required, for example in GSSAPI or |
| 24752 | CRAM-MD5, it is worth noting that the authenticator runs as the Exim user, and |
| 24753 | that the Cyrus SASL library has no way of escalating privileges by default. You |
| 24754 | may also find you need to set environment variables, depending on the driver |
| 24755 | you are using. |
| 24756 | |
| 24757 | The application name provided by Exim is "exim", so various SASL options may be |
| 24758 | set in exim.conf in your SASL directory. If you are using GSSAPI for Kerberos, |
| 24759 | note that because of limitations in the GSSAPI interface, changing the server |
| 24760 | keytab might need to be communicated down to the Kerberos layer independently. |
| 24761 | The mechanism for doing so is dependent upon the Kerberos implementation. |
| 24762 | |
| 24763 | For example, for older releases of Heimdal, the environment variable |
| 24764 | KRB5_KTNAME may be set to point to an alternative keytab file. Exim will pass |
| 24765 | this variable through from its own inherited environment when started as root |
| 24766 | or the Exim user. The keytab file needs to be readable by the Exim user. With |
| 24767 | newer releases of Heimdal, a setuid Exim may cause Heimdal to discard the |
| 24768 | environment variable. In practice, for those releases, the Cyrus authenticator |
| 24769 | is not a suitable interface for GSSAPI (Kerberos) support. Instead, consider |
| 24770 | the heimdal_gssapi authenticator, described in chapter 39 |
| 24771 | |
| 24772 | |
| 24773 | 36.1 Using cyrus_sasl as a server |
| 24774 | --------------------------------- |
| 24775 | |
| 24776 | The cyrus_sasl authenticator has four private options. It puts the username (on |
| 24777 | a successful authentication) into $auth1. For compatibility with previous |
| 24778 | releases of Exim, the username is also placed in $1. However, the use of this |
| 24779 | variable for this purpose is now deprecated, as it can lead to confusion in |
| 24780 | string expansions that also use numeric variables for other things. |
| 24781 | |
| 24782 | +----------------------------------------------------------------+ |
| 24783 | |server_hostname|Use: cyrus_sasl|Type: string*|Default: see below| |
| 24784 | +----------------------------------------------------------------+ |
| 24785 | |
| 24786 | This option selects the hostname that is used when communicating with the |
| 24787 | library. The default value is "$primary_hostname". It is up to the underlying |
| 24788 | SASL plug-in what it does with this data. |
| 24789 | |
| 24790 | +-----------------------------------------------------------+ |
| 24791 | |server_mech|Use: cyrus_sasl|Type: string|Default: see below| |
| 24792 | +-----------------------------------------------------------+ |
| 24793 | |
| 24794 | This option selects the authentication mechanism this driver should use. The |
| 24795 | default is the value of the generic public_name option. This option allows you |
| 24796 | to use a different underlying mechanism from the advertised name. For example: |
| 24797 | |
| 24798 | sasl: |
| 24799 | driver = cyrus_sasl |
| 24800 | public_name = X-ANYTHING |
| 24801 | server_mech = CRAM-MD5 |
| 24802 | server_set_id = $auth1 |
| 24803 | |
| 24804 | +---------------------------------------------------------+ |
| 24805 | |server_realm|Use: cyrus_sasl|Type: string*|Default: unset| |
| 24806 | +---------------------------------------------------------+ |
| 24807 | |
| 24808 | This specifies the SASL realm that the server claims to be in. |
| 24809 | |
| 24810 | +-----------------------------------------------------------+ |
| 24811 | |server_service|Use: cyrus_sasl|Type: string|Default: "smtp"| |
| 24812 | +-----------------------------------------------------------+ |
| 24813 | |
| 24814 | This is the SASL service that the server claims to implement. |
| 24815 | |
| 24816 | For straightforward cases, you do not need to set any of the authenticator's |
| 24817 | private options. All you need to do is to specify an appropriate mechanism as |
| 24818 | the public name. Thus, if you have a SASL library that supports CRAM-MD5 and |
| 24819 | PLAIN, you could have two authenticators as follows: |
| 24820 | |
| 24821 | sasl_cram_md5: |
| 24822 | driver = cyrus_sasl |
| 24823 | public_name = CRAM-MD5 |
| 24824 | server_set_id = $auth1 |
| 24825 | |
| 24826 | sasl_plain: |
| 24827 | driver = cyrus_sasl |
| 24828 | public_name = PLAIN |
| 24829 | server_set_id = $auth2 |
| 24830 | |
| 24831 | Cyrus SASL does implement the LOGIN authentication method, even though it is |
| 24832 | not a standard method. It is disabled by default in the source distribution, |
| 24833 | but it is present in many binary distributions. |
| 24834 | |
| 24835 | |
| 24836 | |
| 24837 | =============================================================================== |
| 24838 | 37. THE DOVECOT AUTHENTICATOR |
| 24839 | |
| 24840 | This authenticator is an interface to the authentication facility of the |
| 24841 | Dovecot POP/IMAP server, which can support a number of authentication methods. |
| 24842 | Note that Dovecot must be configured to use auth-client not auth-userdb. If you |
| 24843 | are using Dovecot to authenticate POP/IMAP clients, it might be helpful to use |
| 24844 | the same mechanisms for SMTP authentication. This is a server authenticator |
| 24845 | only. There is only one option: |
| 24846 | |
| 24847 | +------------------------------------------------------+ |
| 24848 | |server_socket|Use: dovecot|Type: string|Default: unset| |
| 24849 | +------------------------------------------------------+ |
| 24850 | |
| 24851 | This option must specify the socket that is the interface to Dovecot |
| 24852 | authentication. The public_name option must specify an authentication mechanism |
| 24853 | that Dovecot is configured to support. You can have several authenticators for |
| 24854 | different mechanisms. For example: |
| 24855 | |
| 24856 | dovecot_plain: |
| 24857 | driver = dovecot |
| 24858 | public_name = PLAIN |
| 24859 | server_socket = /var/run/dovecot/auth-client |
| 24860 | server_set_id = $auth1 |
| 24861 | |
| 24862 | dovecot_ntlm: |
| 24863 | driver = dovecot |
| 24864 | public_name = NTLM |
| 24865 | server_socket = /var/run/dovecot/auth-client |
| 24866 | server_set_id = $auth1 |
| 24867 | |
| 24868 | If the SMTP connection is encrypted, or if $sender_host_address is equal to |
| 24869 | $received_ip_address (that is, the connection is local), the "secured" option |
| 24870 | is passed in the Dovecot authentication command. If, for a TLS connection, a |
| 24871 | client certificate has been verified, the "valid-client-cert" option is passed. |
| 24872 | When authentication succeeds, the identity of the user who authenticated is |
| 24873 | placed in $auth1. |
| 24874 | |
| 24875 | |
| 24876 | |
| 24877 | =============================================================================== |
| 24878 | 38. THE GSASL AUTHENTICATOR |
| 24879 | |
| 24880 | The gsasl authenticator provides server integration for the GNU SASL library |
| 24881 | and the mechanisms it provides. This is new as of the 4.80 release and there |
| 24882 | are a few areas where the library does not let Exim smoothly scale to handle |
| 24883 | future authentication mechanisms, so no guarantee can be made that any |
| 24884 | particular new authentication mechanism will be supported without code changes |
| 24885 | in Exim. |
| 24886 | |
| 24887 | +-------------------------------------------------------------+ |
| 24888 | |server_channelbinding|Use: gsasl|Type: boolean|Default: false| |
| 24889 | +-------------------------------------------------------------+ |
| 24890 | |
| 24891 | Some authentication mechanisms are able to use external context at both ends of |
| 24892 | the session to bind the authentication to that context, and fail the |
| 24893 | authentication process if that context differs. Specifically, some TLS |
| 24894 | ciphersuites can provide identifying information about the cryptographic |
| 24895 | context. |
| 24896 | |
| 24897 | This means that certificate identity and verification becomes a non-issue, as a |
| 24898 | man-in-the-middle attack will cause the correct client and server to see |
| 24899 | different identifiers and authentication will fail. |
| 24900 | |
| 24901 | This is currently only supported when using the GnuTLS library. This is only |
| 24902 | usable by mechanisms which support "channel binding"; at time of writing, |
| 24903 | that's the SCRAM family. |
| 24904 | |
| 24905 | This defaults off to ensure smooth upgrade across Exim releases, in case this |
| 24906 | option causes some clients to start failing. Some future release of Exim may |
| 24907 | switch the default to be true. |
| 24908 | |
| 24909 | +-----------------------------------------------------------+ |
| 24910 | |server_hostname|Use: gsasl|Type: string*|Default: see below| |
| 24911 | +-----------------------------------------------------------+ |
| 24912 | |
| 24913 | This option selects the hostname that is used when communicating with the |
| 24914 | library. The default value is "$primary_hostname". Some mechanisms will use |
| 24915 | this data. |
| 24916 | |
| 24917 | +------------------------------------------------------+ |
| 24918 | |server_mech|Use: gsasl|Type: string|Default: see below| |
| 24919 | +------------------------------------------------------+ |
| 24920 | |
| 24921 | This option selects the authentication mechanism this driver should use. The |
| 24922 | default is the value of the generic public_name option. This option allows you |
| 24923 | to use a different underlying mechanism from the advertised name. For example: |
| 24924 | |
| 24925 | sasl: |
| 24926 | driver = gsasl |
| 24927 | public_name = X-ANYTHING |
| 24928 | server_mech = CRAM-MD5 |
| 24929 | server_set_id = $auth1 |
| 24930 | |
| 24931 | +-------------------------------------------------------+ |
| 24932 | |server_password|Use: gsasl|Type: string*|Default: unset| |
| 24933 | +-------------------------------------------------------+ |
| 24934 | |
| 24935 | Various mechanisms need access to the cleartext password on the server, so that |
| 24936 | proof-of-possession can be demonstrated on the wire, without sending the |
| 24937 | password itself. |
| 24938 | |
| 24939 | The data available for lookup varies per mechanism. In all cases, $auth1 is set |
| 24940 | to the authentication id. The $auth2 variable will always be the authorization |
| 24941 | id (authz) if available, else the empty string. The $auth3 variable will always |
| 24942 | be the realm if available, else the empty string. |
| 24943 | |
| 24944 | A forced failure will cause authentication to defer. |
| 24945 | |
| 24946 | If using this option, it may make sense to set the server_condition option to |
| 24947 | be simply "true". |
| 24948 | |
| 24949 | +----------------------------------------------------+ |
| 24950 | |server_realm|Use: gsasl|Type: string*|Default: unset| |
| 24951 | +----------------------------------------------------+ |
| 24952 | |
| 24953 | This specifies the SASL realm that the server claims to be in. Some mechanisms |
| 24954 | will use this data. |
| 24955 | |
| 24956 | +---------------------------------------------------------+ |
| 24957 | |server_scram_iter|Use: gsasl|Type: string*|Default: unset| |
| 24958 | +---------------------------------------------------------+ |
| 24959 | |
| 24960 | This option provides data for the SCRAM family of mechanisms. $auth1 is not |
| 24961 | available at evaluation time. (This may change, as we receive feedback on use) |
| 24962 | |
| 24963 | +---------------------------------------------------------+ |
| 24964 | |server_scram_salt|Use: gsasl|Type: string*|Default: unset| |
| 24965 | +---------------------------------------------------------+ |
| 24966 | |
| 24967 | This option provides data for the SCRAM family of mechanisms. $auth1 is not |
| 24968 | available at evaluation time. (This may change, as we receive feedback on use) |
| 24969 | |
| 24970 | +------------------------------------------------------+ |
| 24971 | |server_service|Use: gsasl|Type: string|Default: "smtp"| |
| 24972 | +------------------------------------------------------+ |
| 24973 | |
| 24974 | This is the SASL service that the server claims to implement. Some mechanisms |
| 24975 | will use this data. |
| 24976 | |
| 24977 | |
| 24978 | 38.1 gsasl auth variables |
| 24979 | ------------------------- |
| 24980 | |
| 24981 | These may be set when evaluating specific options, as detailed above. They will |
| 24982 | also be set when evaluating server_condition. |
| 24983 | |
| 24984 | Unless otherwise stated below, the gsasl integration will use the following |
| 24985 | meanings for these variables: |
| 24986 | |
| 24987 | * $auth1: the authentication id |
| 24988 | |
| 24989 | * $auth2: the authorization id |
| 24990 | |
| 24991 | * $auth3: the realm |
| 24992 | |
| 24993 | On a per-mechanism basis: |
| 24994 | |
| 24995 | * EXTERNAL: only $auth1 is set, to the possibly empty authorization id; the |
| 24996 | server_condition option must be present. |
| 24997 | |
| 24998 | * ANONYMOUS: only $auth1 is set, to the possibly empty anonymous token; the |
| 24999 | server_condition option must be present. |
| 25000 | |
| 25001 | * GSSAPI: $auth1 will be set to the GSSAPI Display Name; $auth2 will be set |
| 25002 | to the authorization id, the server_condition option must be present. |
| 25003 | |
| 25004 | An anonymous token is something passed along as an unauthenticated identifier; |
| 25005 | this is analogous to FTP anonymous authentication passing an email address, or |
| 25006 | software-identifier@, as the "password". |
| 25007 | |
| 25008 | An example showing the password having the realm specified in the callback and |
| 25009 | demonstrating a Cyrus SASL to GSASL migration approach is: |
| 25010 | |
| 25011 | gsasl_cyrusless_crammd5: |
| 25012 | driver = gsasl |
| 25013 | public_name = CRAM-MD5 |
| 25014 | server_realm = imap.example.org |
| 25015 | server_password = ${lookup{$auth1:$auth3:userPassword}\ |
| 25016 | dbmjz{/etc/sasldb2}{$value}fail} |
| 25017 | server_set_id = ${quote:$auth1} |
| 25018 | server_condition = yes |
| 25019 | |
| 25020 | |
| 25021 | |
| 25022 | =============================================================================== |
| 25023 | 39. THE HEIMDAL_GSSAPI AUTHENTICATOR |
| 25024 | |
| 25025 | The heimdal_gssapi authenticator provides server integration for the Heimdal |
| 25026 | GSSAPI/Kerberos library, permitting Exim to set a keytab pathname reliably. |
| 25027 | |
| 25028 | +--------------------------------------------------------------------+ |
| 25029 | |server_hostname|Use: heimdal_gssapi|Type: string*|Default: see below| |
| 25030 | +--------------------------------------------------------------------+ |
| 25031 | |
| 25032 | This option selects the hostname that is used, with server_service, for |
| 25033 | constructing the GSS server name, as a GSS_C_NT_HOSTBASED_SERVICE identifier. |
| 25034 | The default value is "$primary_hostname". |
| 25035 | |
| 25036 | +--------------------------------------------------------------+ |
| 25037 | |server_keytab|Use: heimdal_gssapi|Type: string*|Default: unset| |
| 25038 | +--------------------------------------------------------------+ |
| 25039 | |
| 25040 | If set, then Heimdal will not use the system default keytab (typically /etc/ |
| 25041 | krb5.keytab) but instead the pathname given in this option. The value should be |
| 25042 | a pathname, with no "file:" prefix. |
| 25043 | |
| 25044 | +--------------------------------------------------------------+ |
| 25045 | |server_service|Use: heimdal_gssapi|Type: string*|Default: smtp| |
| 25046 | +--------------------------------------------------------------+ |
| 25047 | |
| 25048 | This option specifies the service identifier used, in conjunction with |
| 25049 | server_hostname, for building the identifier for finding credentials from the |
| 25050 | keytab. |
| 25051 | |
| 25052 | |
| 25053 | 39.1 heimdal_gssapi auth variables |
| 25054 | ---------------------------------- |
| 25055 | |
| 25056 | Beware that these variables will typically include a realm, thus will appear to |
| 25057 | be roughly like an email address already. The authzid in $auth2 is not |
| 25058 | verified, so a malicious client can set it to anything. |
| 25059 | |
| 25060 | The $auth1 field should be safely trustable as a value from the Key |
| 25061 | Distribution Center. Note that these are not quite email addresses. Each |
| 25062 | identifier is for a role, and so the left-hand-side may include a role suffix. |
| 25063 | For instance, "joe/admin@EXAMPLE.ORG". |
| 25064 | |
| 25065 | * $auth1: the authentication id, set to the GSS Display Name. |
| 25066 | |
| 25067 | * $auth2: the authorization id, sent within SASL encapsulation after |
| 25068 | authentication. If that was empty, this will also be set to the GSS Display |
| 25069 | Name. |
| 25070 | |
| 25071 | |
| 25072 | |
| 25073 | =============================================================================== |
| 25074 | 40. THE SPA AUTHENTICATOR |
| 25075 | |
| 25076 | The spa authenticator provides client support for Microsoft's Secure Password |
| 25077 | Authentication mechanism, which is also sometimes known as NTLM (NT LanMan). |
| 25078 | The code for client side of this authenticator was contributed by Marc |
| 25079 | Prud'hommeaux, and much of it is taken from the Samba project (http:// |
| 25080 | www.samba.org). The code for the server side was subsequently contributed by |
| 25081 | Tom Kistner. The mechanism works as follows: |
| 25082 | |
| 25083 | * After the AUTH command has been accepted, the client sends an SPA |
| 25084 | authentication request based on the user name and optional domain. |
| 25085 | |
| 25086 | * The server sends back a challenge. |
| 25087 | |
| 25088 | * The client builds a challenge response which makes use of the user's |
| 25089 | password and sends it to the server, which then accepts or rejects it. |
| 25090 | |
| 25091 | Encryption is used to protect the password in transit. |
| 25092 | |
| 25093 | |
| 25094 | 40.1 Using spa as a server |
| 25095 | -------------------------- |
| 25096 | |
| 25097 | The spa authenticator has just one server option: |
| 25098 | |
| 25099 | +-----------------------------------------------------+ |
| 25100 | |server_password|Use: spa|Type: string*|Default: unset| |
| 25101 | +-----------------------------------------------------+ |
| 25102 | |
| 25103 | This option is expanded, and the result must be the cleartext password for the |
| 25104 | authenticating user, whose name is at this point in $auth1. For compatibility |
| 25105 | with previous releases of Exim, the user name is also placed in $1. However, |
| 25106 | the use of this variable for this purpose is now deprecated, as it can lead to |
| 25107 | confusion in string expansions that also use numeric variables for other |
| 25108 | things. For example: |
| 25109 | |
| 25110 | spa: |
| 25111 | driver = spa |
| 25112 | public_name = NTLM |
| 25113 | server_password = \ |
| 25114 | ${lookup{$auth1}lsearch{/etc/exim/spa_clearpass}{$value}fail} |
| 25115 | |
| 25116 | If the expansion is forced to fail, authentication fails. Any other expansion |
| 25117 | failure causes a temporary error code to be returned. |
| 25118 | |
| 25119 | |
| 25120 | 40.2 Using spa as a client |
| 25121 | -------------------------- |
| 25122 | |
| 25123 | The spa authenticator has the following client options: |
| 25124 | |
| 25125 | +---------------------------------------------------+ |
| 25126 | |client_domain|Use: spa|Type: string*|Default: unset| |
| 25127 | +---------------------------------------------------+ |
| 25128 | |
| 25129 | This option specifies an optional domain for the authentication. |
| 25130 | |
| 25131 | +-----------------------------------------------------+ |
| 25132 | |client_password|Use: spa|Type: string*|Default: unset| |
| 25133 | +-----------------------------------------------------+ |
| 25134 | |
| 25135 | This option specifies the user's password, and must be set. |
| 25136 | |
| 25137 | +-----------------------------------------------------+ |
| 25138 | |client_username|Use: spa|Type: string*|Default: unset| |
| 25139 | +-----------------------------------------------------+ |
| 25140 | |
| 25141 | This option specifies the user name, and must be set. Here is an example of a |
| 25142 | configuration of this authenticator for use with the mail servers at msn.com: |
| 25143 | |
| 25144 | msn: |
| 25145 | driver = spa |
| 25146 | public_name = MSN |
| 25147 | client_username = msn/msn_username |
| 25148 | client_password = msn_plaintext_password |
| 25149 | client_domain = DOMAIN_OR_UNSET |
| 25150 | |
| 25151 | |
| 25152 | |
| 25153 | =============================================================================== |
| 25154 | 41. THE TLS AUTHENTICATOR |
| 25155 | |
| 25156 | The tls authenticator provides server support for authentication based on |
| 25157 | client certificates. |
| 25158 | |
| 25159 | It is not an SMTP authentication mechanism and is not advertised by the server |
| 25160 | as part of the SMTP EHLO response. It is an Exim authenticator in the sense |
| 25161 | that it affects the protocol element of the log line, can be tested for by the |
| 25162 | authenticated ACL condition, and can set the $authenticated_id variable. |
| 25163 | |
| 25164 | The client must present a verifiable certificate, for which it must have been |
| 25165 | requested via the tls_verify_hosts or tls_try_verify_hosts main options (see 42 |
| 25166 | ). |
| 25167 | |
| 25168 | If an authenticator of this type is configured it is run before any SMTP-level |
| 25169 | communication is done, and can authenticate the connection. If it does, SMTP |
| 25170 | authentication is not offered. |
| 25171 | |
| 25172 | A maximum of one authenticator of this type may be present. |
| 25173 | |
| 25174 | The tls authenticator has three server options: |
| 25175 | |
| 25176 | +---------------------------------------------------+ |
| 25177 | |server_param1|Use: tls|Type: string*|Default: unset| |
| 25178 | +---------------------------------------------------+ |
| 25179 | |
| 25180 | This option is expanded after the TLS negotiation and the result is placed in |
| 25181 | $auth1. If the expansion is forced to fail, authentication fails. Any other |
| 25182 | expansion failure causes a temporary error code to be returned. |
| 25183 | |
| 25184 | +---------------------------------------------------+ |
| 25185 | |server_param2|Use: tls|Type: string*|Default: unset| |
| 25186 | +---------------------------------------------------+ |
| 25187 | |
| 25188 | +---------------------------------------------------+ |
| 25189 | |server_param3|Use: tls|Type: string*|Default: unset| |
| 25190 | +---------------------------------------------------+ |
| 25191 | |
| 25192 | As above, for $auth2 and $auth3. |
| 25193 | |
| 25194 | server_param1 may also be spelled server_param. |
| 25195 | |
| 25196 | Example: |
| 25197 | |
| 25198 | tls: |
| 25199 | driver = tls |
| 25200 | server_param1 = ${certextract {subj_altname,mail,>:} \ |
| 25201 | {$tls_in_peercert}} |
| 25202 | server_condition = ${if forany {$auth1} \ |
| 25203 | {!= {0} \ |
| 25204 | {${lookup ldap{ldap:///\ |
| 25205 | mailname=${quote_ldap_dn:${lc:$item}},\ |
| 25206 | ou=users,LDAP_DC?mailid} {$value}{0} \ |
| 25207 | } } } } |
| 25208 | server_set_id = ${if = {1}{${listcount:$auth1}} {$auth1}{}} |
| 25209 | |
| 25210 | This accepts a client certificate that is verifiable against any of your |
| 25211 | configured trust-anchors (which usually means the full set of public CAs) and |
| 25212 | which has a SAN with a good account name. Note that the client cert is on the |
| 25213 | wire in-clear, including the SAN, whereas a plaintext SMTP AUTH done inside TLS |
| 25214 | is not. |
| 25215 | |
| 25216 | Note that because authentication is traditionally an SMTP operation, the |
| 25217 | authenticated ACL condition cannot be used in a connect- or helo-ACL. |
| 25218 | |
| 25219 | |
| 25220 | |
| 25221 | =============================================================================== |
| 25222 | 42. ENCRYPTED SMTP CONNECTIONS USING TLS/SSL |
| 25223 | |
| 25224 | Support for TLS (Transport Layer Security), formerly known as SSL (Secure |
| 25225 | Sockets Layer), is implemented by making use of the OpenSSL library or the |
| 25226 | GnuTLS library (Exim requires GnuTLS release 1.0 or later). There is no |
| 25227 | cryptographic code in the Exim distribution itself for implementing TLS. In |
| 25228 | order to use this feature you must install OpenSSL or GnuTLS, and then build a |
| 25229 | version of Exim that includes TLS support (see section 4.7). You also need to |
| 25230 | understand the basic concepts of encryption at a managerial level, and in |
| 25231 | particular, the way that public keys, private keys, and certificates are used. |
| 25232 | |
| 25233 | RFC 3207 defines how SMTP connections can make use of encryption. Once a |
| 25234 | connection is established, the client issues a STARTTLS command. If the server |
| 25235 | accepts this, the client and the server negotiate an encryption mechanism. If |
| 25236 | the negotiation succeeds, the data that subsequently passes between them is |
| 25237 | encrypted. |
| 25238 | |
| 25239 | Exim's ACLs can detect whether the current SMTP session is encrypted or not, |
| 25240 | and if so, what cipher suite is in use, whether the client supplied a |
| 25241 | certificate, and whether or not that certificate was verified. This makes it |
| 25242 | possible for an Exim server to deny or accept certain commands based on the |
| 25243 | encryption state. |
| 25244 | |
| 25245 | Warning: Certain types of firewall and certain anti-virus products can disrupt |
| 25246 | TLS connections. You need to turn off SMTP scanning for these products in order |
| 25247 | to get TLS to work. |
| 25248 | |
| 25249 | |
| 25250 | 42.1 Support for the legacy "ssmtp" (aka "smtps") protocol |
| 25251 | ---------------------------------------------------------- |
| 25252 | |
| 25253 | Early implementations of encrypted SMTP used a different TCP port from normal |
| 25254 | SMTP, and expected an encryption negotiation to start immediately, instead of |
| 25255 | waiting for a STARTTLS command from the client using the standard SMTP port. |
| 25256 | The protocol was called "ssmtp" or "smtps", and port 465 was allocated for this |
| 25257 | purpose. |
| 25258 | |
| 25259 | This approach was abandoned when encrypted SMTP was standardized, but there are |
| 25260 | still some legacy clients that use it. Exim supports these clients by means of |
| 25261 | the tls_on_connect_ports global option. Its value must be a list of port |
| 25262 | numbers; the most common use is expected to be: |
| 25263 | |
| 25264 | tls_on_connect_ports = 465 |
| 25265 | |
| 25266 | The port numbers specified by this option apply to all SMTP connections, both |
| 25267 | via the daemon and via inetd. You still need to specify all the ports that the |
| 25268 | daemon uses (by setting daemon_smtp_ports or local_interfaces or the -oX |
| 25269 | command line option) because tls_on_connect_ports does not add an extra port - |
| 25270 | rather, it specifies different behaviour on a port that is defined elsewhere. |
| 25271 | |
| 25272 | There is also a -tls-on-connect command line option. This overrides |
| 25273 | tls_on_connect_ports; it forces the legacy behaviour for all ports. |
| 25274 | |
| 25275 | |
| 25276 | 42.2 OpenSSL vs GnuTLS |
| 25277 | ---------------------- |
| 25278 | |
| 25279 | The first TLS support in Exim was implemented using OpenSSL. Support for GnuTLS |
| 25280 | followed later, when the first versions of GnuTLS were released. To build Exim |
| 25281 | to use GnuTLS, you need to set |
| 25282 | |
| 25283 | USE_GNUTLS=yes |
| 25284 | |
| 25285 | in Local/Makefile, in addition to |
| 25286 | |
| 25287 | SUPPORT_TLS=yes |
| 25288 | |
| 25289 | You must also set TLS_LIBS and TLS_INCLUDE appropriately, so that the include |
| 25290 | files and libraries for GnuTLS can be found. |
| 25291 | |
| 25292 | There are some differences in usage when using GnuTLS instead of OpenSSL: |
| 25293 | |
| 25294 | * The tls_verify_certificates option cannot be the path of a directory for |
| 25295 | GnuTLS versions before 3.3.6 (for later versions, or OpenSSL, it can be |
| 25296 | either). |
| 25297 | |
| 25298 | * The default value for tls_dhparam differs for historical reasons. |
| 25299 | |
| 25300 | * Distinguished Name (DN) strings reported by the OpenSSL library use a slash |
| 25301 | for separating fields; GnuTLS uses commas, in accordance with RFC 2253. |
| 25302 | This affects the value of the $tls_in_peerdn and $tls_out_peerdn variables. |
| 25303 | |
| 25304 | * OpenSSL identifies cipher suites using hyphens as separators, for example: |
| 25305 | DES-CBC3-SHA. GnuTLS historically used underscores, for example: |
| 25306 | RSA_ARCFOUR_SHA. What is more, OpenSSL complains if underscores are present |
| 25307 | in a cipher list. To make life simpler, Exim changes underscores to hyphens |
| 25308 | for OpenSSL and passes the string unchanged to GnuTLS (expecting the |
| 25309 | library to handle its own older variants) when processing lists of cipher |
| 25310 | suites in the tls_require_ciphers options (the global option and the smtp |
| 25311 | transport option). |
| 25312 | |
| 25313 | * The tls_require_ciphers options operate differently, as described in the |
| 25314 | sections 42.4 and 42.5. |
| 25315 | |
| 25316 | * The tls_dh_min_bits SMTP transport option is only honoured by GnuTLS. When |
| 25317 | using OpenSSL, this option is ignored. (If an API is found to let OpenSSL |
| 25318 | be configured in this way, let the Exim Maintainers know and we'll likely |
| 25319 | use it). |
| 25320 | |
| 25321 | * Some other recently added features may only be available in one or the |
| 25322 | other. This should be documented with the feature. If the documentation |
| 25323 | does not explicitly state that the feature is infeasible in the other TLS |
| 25324 | implementation, then patches are welcome. |
| 25325 | |
| 25326 | |
| 25327 | 42.3 GnuTLS parameter computation |
| 25328 | --------------------------------- |
| 25329 | |
| 25330 | This section only applies if tls_dhparam is set to "historic" or to an explicit |
| 25331 | path; if the latter, then the text about generation still applies, but not the |
| 25332 | chosen filename. By default, as of Exim 4.80 a hard-coded D-H prime is used. |
| 25333 | See the documentation of tls_dhparam for more information. |
| 25334 | |
| 25335 | GnuTLS uses D-H parameters that may take a substantial amount of time to |
| 25336 | compute. It is unreasonable to re-compute them for every TLS session. |
| 25337 | Therefore, Exim keeps this data in a file in its spool directory, called |
| 25338 | gnutls-params-NNNN for some value of NNNN, corresponding to the number of bits |
| 25339 | requested. The file is owned by the Exim user and is readable only by its |
| 25340 | owner. Every Exim process that start up GnuTLS reads the D-H parameters from |
| 25341 | this file. If the file does not exist, the first Exim process that needs it |
| 25342 | computes the data and writes it to a temporary file which is renamed once it is |
| 25343 | complete. It does not matter if several Exim processes do this simultaneously |
| 25344 | (apart from wasting a few resources). Once a file is in place, new Exim |
| 25345 | processes immediately start using it. |
| 25346 | |
| 25347 | For maximum security, the parameters that are stored in this file should be |
| 25348 | recalculated periodically, the frequency depending on your paranoia level. If |
| 25349 | you are avoiding using the fixed D-H primes published in RFCs, then you are |
| 25350 | concerned about some advanced attacks and will wish to do this; if you do not |
| 25351 | regenerate then you might as well stick to the standard primes. |
| 25352 | |
| 25353 | Arranging this is easy in principle; just delete the file when you want new |
| 25354 | values to be computed. However, there may be a problem. The calculation of new |
| 25355 | parameters needs random numbers, and these are obtained from /dev/random. If |
| 25356 | the system is not very active, /dev/random may delay returning data until |
| 25357 | enough randomness (entropy) is available. This may cause Exim to hang for a |
| 25358 | substantial amount of time, causing timeouts on incoming connections. |
| 25359 | |
| 25360 | The solution is to generate the parameters externally to Exim. They are stored |
| 25361 | in gnutls-params-N in PEM format, which means that they can be generated |
| 25362 | externally using the certtool command that is part of GnuTLS. |
| 25363 | |
| 25364 | To replace the parameters with new ones, instead of deleting the file and |
| 25365 | letting Exim re-create it, you can generate new parameters using certtool and, |
| 25366 | when this has been done, replace Exim's cache file by renaming. The relevant |
| 25367 | commands are something like this: |
| 25368 | |
| 25369 | # ls |
| 25370 | [ look for file; assume gnutls-params-2236 is the most recent ] |
| 25371 | # rm -f new-params |
| 25372 | # touch new-params |
| 25373 | # chown exim:exim new-params |
| 25374 | # chmod 0600 new-params |
| 25375 | # certtool --generate-dh-params --bits 2236 >>new-params |
| 25376 | # openssl dhparam -noout -text -in new-params | head |
| 25377 | [ check the first line, make sure it's not more than 2236; |
| 25378 | if it is, then go back to the start ("rm") and repeat |
| 25379 | until the size generated is at most the size requested ] |
| 25380 | # chmod 0400 new-params |
| 25381 | # mv new-params gnutls-params-2236 |
| 25382 | |
| 25383 | If Exim never has to generate the parameters itself, the possibility of |
| 25384 | stalling is removed. |
| 25385 | |
| 25386 | The filename changed in Exim 4.80, to gain the -bits suffix. The value which |
| 25387 | Exim will choose depends upon the version of GnuTLS in use. For older GnuTLS, |
| 25388 | the value remains hard-coded in Exim as 1024. As of GnuTLS 2.12.x, there is a |
| 25389 | way for Exim to ask for the "normal" number of bits for D-H public-key usage, |
| 25390 | and Exim does so. This attempt to remove Exim from TLS policy decisions failed, |
| 25391 | as GnuTLS 2.12 returns a value higher than the current hard-coded limit of the |
| 25392 | NSS library. Thus Exim gains the tls_dh_max_bits global option, which applies |
| 25393 | to all D-H usage, client or server. If the value returned by GnuTLS is greater |
| 25394 | than tls_dh_max_bits then the value will be clamped down to tls_dh_max_bits. |
| 25395 | The default value has been set at the current NSS limit, which is still much |
| 25396 | higher than Exim historically used. |
| 25397 | |
| 25398 | The filename and bits used will change as the GnuTLS maintainers change the |
| 25399 | value for their parameter "GNUTLS_SEC_PARAM_NORMAL", as clamped by |
| 25400 | tls_dh_max_bits. At the time of writing (mid 2012), GnuTLS 2.12 recommends 2432 |
| 25401 | bits, while NSS is limited to 2236 bits. |
| 25402 | |
| 25403 | In fact, the requested value will be *lower* than tls_dh_max_bits, to increase |
| 25404 | the chance of the generated prime actually being within acceptable bounds, as |
| 25405 | GnuTLS has been observed to overshoot. Note the check step in the procedure |
| 25406 | above. There is no sane procedure available to Exim to double-check the size of |
| 25407 | the generated prime, so it might still be too large. |
| 25408 | |
| 25409 | |
| 25410 | 42.4 Requiring specific ciphers in OpenSSL |
| 25411 | ------------------------------------------ |
| 25412 | |
| 25413 | There is a function in the OpenSSL library that can be passed a list of cipher |
| 25414 | suites before the cipher negotiation takes place. This specifies which ciphers |
| 25415 | are acceptable. The list is colon separated and may contain names like |
| 25416 | DES-CBC3-SHA. Exim passes the expanded value of tls_require_ciphers directly to |
| 25417 | this function call. Many systems will install the OpenSSL manual-pages, so you |
| 25418 | may have ciphers(1) available to you. The following quotation from the OpenSSL |
| 25419 | documentation specifies what forms of item are allowed in the cipher string: |
| 25420 | |
| 25421 | * It can consist of a single cipher suite such as RC4-SHA. |
| 25422 | |
| 25423 | * It can represent a list of cipher suites containing a certain algorithm, or |
| 25424 | cipher suites of a certain type. For example SHA1 represents all ciphers |
| 25425 | suites using the digest algorithm SHA1 and SSLv3 represents all SSL v3 |
| 25426 | algorithms. |
| 25427 | |
| 25428 | * Lists of cipher suites can be combined in a single cipher string using the |
| 25429 | + character. This is used as a logical and operation. For example SHA1+DES |
| 25430 | represents all cipher suites containing the SHA1 and the DES algorithms. |
| 25431 | |
| 25432 | Each cipher string can be optionally preceded by one of the characters "!", "-" |
| 25433 | or "+". |
| 25434 | |
| 25435 | * If "!" is used, the ciphers are permanently deleted from the list. The |
| 25436 | ciphers deleted can never reappear in the list even if they are explicitly |
| 25437 | stated. |
| 25438 | |
| 25439 | * If "-" is used, the ciphers are deleted from the list, but some or all of |
| 25440 | the ciphers can be added again by later options. |
| 25441 | |
| 25442 | * If "+" is used, the ciphers are moved to the end of the list. This option |
| 25443 | does not add any new ciphers; it just moves matching existing ones. |
| 25444 | |
| 25445 | If none of these characters is present, the string is interpreted as a list of |
| 25446 | ciphers to be appended to the current preference list. If the list includes any |
| 25447 | ciphers already present they will be ignored: that is, they will not be moved |
| 25448 | to the end of the list. |
| 25449 | |
| 25450 | The OpenSSL ciphers(1) command may be used to test the results of a given |
| 25451 | string: |
| 25452 | |
| 25453 | # note single-quotes to get ! past any shell history expansion |
| 25454 | $ openssl ciphers 'HIGH:!MD5:!SHA1' |
| 25455 | |
| 25456 | This example will let the library defaults be permitted on the MX port, where |
| 25457 | there's probably no identity verification anyway, but ups the ante on the |
| 25458 | submission ports where the administrator might have some influence on the |
| 25459 | choice of clients used: |
| 25460 | |
| 25461 | # OpenSSL variant; see man ciphers(1) |
| 25462 | tls_require_ciphers = ${if =={$received_port}{25}\ |
| 25463 | {DEFAULT}\ |
| 25464 | {HIGH:!MD5:!SHA1}} |
| 25465 | |
| 25466 | |
| 25467 | 42.5 Requiring specific ciphers or other parameters in GnuTLS |
| 25468 | ------------------------------------------------------------- |
| 25469 | |
| 25470 | The GnuTLS library allows the caller to provide a "priority string", documented |
| 25471 | as part of the gnutls_priority_init function. This is very similar to the |
| 25472 | ciphersuite specification in OpenSSL. |
| 25473 | |
| 25474 | The tls_require_ciphers option is treated as the GnuTLS priority string and |
| 25475 | controls both protocols and ciphers. |
| 25476 | |
| 25477 | The tls_require_ciphers option is available both as an global option, |
| 25478 | controlling how Exim behaves as a server, and also as an option of the smtp |
| 25479 | transport, controlling how Exim behaves as a client. In both cases the value is |
| 25480 | string expanded. The resulting string is not an Exim list and the string is |
| 25481 | given to the GnuTLS library, so that Exim does not need to be aware of future |
| 25482 | feature enhancements of GnuTLS. |
| 25483 | |
| 25484 | Documentation of the strings accepted may be found in the GnuTLS manual, under |
| 25485 | "Priority strings". This is online as http://www.gnutls.org/manual/html_node/ |
| 25486 | Priority-Strings.html, but beware that this relates to GnuTLS 3, which may be |
| 25487 | newer than the version installed on your system. If you are using GnuTLS 3, |
| 25488 | then the example code http://www.gnutls.org/manual/gnutls.html# |
| 25489 | Listing-the-ciphersuites-in-a-priority-string on that site can be used to test |
| 25490 | a given string. |
| 25491 | |
| 25492 | For example: |
| 25493 | |
| 25494 | # Disable older versions of protocols |
| 25495 | tls_require_ciphers = NORMAL:%LATEST_RECORD_VERSION:-VERS-SSL3.0 |
| 25496 | |
| 25497 | Prior to Exim 4.80, an older API of GnuTLS was used, and Exim supported three |
| 25498 | additional options, "gnutls_require_kx", "gnutls_require_mac" and " |
| 25499 | gnutls_require_protocols". tls_require_ciphers was an Exim list. |
| 25500 | |
| 25501 | This example will let the library defaults be permitted on the MX port, where |
| 25502 | there's probably no identity verification anyway, and lowers security further |
| 25503 | by increasing compatibility; but this ups the ante on the submission ports |
| 25504 | where the administrator might have some influence on the choice of clients |
| 25505 | used: |
| 25506 | |
| 25507 | # GnuTLS variant |
| 25508 | tls_require_ciphers = ${if =={$received_port}{25}\ |
| 25509 | {NORMAL:%COMPAT}\ |
| 25510 | {SECURE128}} |
| 25511 | |
| 25512 | |
| 25513 | 42.6 Configuring an Exim server to use TLS |
| 25514 | ------------------------------------------ |
| 25515 | |
| 25516 | When Exim has been built with TLS support, it advertises the availability of |
| 25517 | the STARTTLS command to client hosts that match tls_advertise_hosts, but not to |
| 25518 | any others. The default value of this option is unset, which means that |
| 25519 | STARTTLS is not advertised at all. This default is chosen because you need to |
| 25520 | set some other options in order to make TLS available, and also it is sensible |
| 25521 | for systems that want to use TLS only as a client. |
| 25522 | |
| 25523 | If a client issues a STARTTLS command and there is some configuration problem |
| 25524 | in the server, the command is rejected with a 454 error. If the client persists |
| 25525 | in trying to issue SMTP commands, all except QUIT are rejected with the error |
| 25526 | |
| 25527 | 554 Security failure |
| 25528 | |
| 25529 | If a STARTTLS command is issued within an existing TLS session, it is rejected |
| 25530 | with a 554 error code. |
| 25531 | |
| 25532 | To enable TLS operations on a server, the tls_advertise_hosts option must be |
| 25533 | set to match some hosts. The default is * which matches all hosts. |
| 25534 | |
| 25535 | If this is all you do, TLS encryption will be enabled but not authentication - |
| 25536 | meaning that the peer has no assurance it is actually you he is talking to. You |
| 25537 | gain protection from a passive sniffer listening on the wire but not from |
| 25538 | someone able to intercept the communication. |
| 25539 | |
| 25540 | Further protection requires some further configuration at the server end. |
| 25541 | |
| 25542 | It is rumoured that all existing clients that support TLS/SSL use RSA |
| 25543 | encryption. To make this work you need to set, in the server, |
| 25544 | |
| 25545 | tls_certificate = /some/file/name |
| 25546 | tls_privatekey = /some/file/name |
| 25547 | |
| 25548 | These options are, in fact, expanded strings, so you can make them depend on |
| 25549 | the identity of the client that is connected if you wish. The first file |
| 25550 | contains the server's X509 certificate, and the second contains the private key |
| 25551 | that goes with it. These files need to be PEM format and readable by the Exim |
| 25552 | user, and must always be given as full path names. The key must not be |
| 25553 | password-protected. They can be the same file if both the certificate and the |
| 25554 | key are contained within it. If tls_privatekey is not set, or if its expansion |
| 25555 | is forced to fail or results in an empty string, this is assumed to be the |
| 25556 | case. The certificate file may also contain intermediate certificates that need |
| 25557 | to be sent to the client to enable it to authenticate the server's certificate. |
| 25558 | |
| 25559 | If you do not understand about certificates and keys, please try to find a |
| 25560 | source of this background information, which is not Exim-specific. (There are a |
| 25561 | few comments below in section 42.12.) |
| 25562 | |
| 25563 | Note: These options do not apply when Exim is operating as a client - they |
| 25564 | apply only in the case of a server. If you need to use a certificate in an Exim |
| 25565 | client, you must set the options of the same names in an smtp transport. |
| 25566 | |
| 25567 | With just these options, an Exim server will be able to use TLS. It does not |
| 25568 | require the client to have a certificate (but see below for how to insist on |
| 25569 | this). There is one other option that may be needed in other situations. If |
| 25570 | |
| 25571 | tls_dhparam = /some/file/name |
| 25572 | |
| 25573 | is set, the SSL library is initialized for the use of Diffie-Hellman ciphers |
| 25574 | with the parameters contained in the file. Set this to "none" to disable use of |
| 25575 | DH entirely, by making no prime available: |
| 25576 | |
| 25577 | tls_dhparam = none |
| 25578 | |
| 25579 | This may also be set to a string identifying a standard prime to be used for |
| 25580 | DH; if it is set to "default" or, for OpenSSL, is unset, then the prime used is |
| 25581 | "ike23". There are a few standard primes available, see the documentation for |
| 25582 | tls_dhparam for the complete list. |
| 25583 | |
| 25584 | See the command |
| 25585 | |
| 25586 | openssl dhparam |
| 25587 | |
| 25588 | for a way of generating file data. |
| 25589 | |
| 25590 | The strings supplied for these three options are expanded every time a client |
| 25591 | host connects. It is therefore possible to use different certificates and keys |
| 25592 | for different hosts, if you so wish, by making use of the client's IP address |
| 25593 | in $sender_host_address to control the expansion. If a string expansion is |
| 25594 | forced to fail, Exim behaves as if the option is not set. |
| 25595 | |
| 25596 | The variable $tls_in_cipher is set to the cipher suite that was negotiated for |
| 25597 | an incoming TLS connection. It is included in the Received: header of an |
| 25598 | incoming message (by default - you can, of course, change this), and it is also |
| 25599 | included in the log line that records a message's arrival, keyed by "X=", |
| 25600 | unless the tls_cipher log selector is turned off. The encrypted condition can |
| 25601 | be used to test for specific cipher suites in ACLs. |
| 25602 | |
| 25603 | Once TLS has been established, the ACLs that run for subsequent SMTP commands |
| 25604 | can check the name of the cipher suite and vary their actions accordingly. The |
| 25605 | cipher suite names vary, depending on which TLS library is being used. For |
| 25606 | example, OpenSSL uses the name DES-CBC3-SHA for the cipher suite which in other |
| 25607 | contexts is known as TLS_RSA_WITH_3DES_EDE_CBC_SHA. Check the OpenSSL or GnuTLS |
| 25608 | documentation for more details. |
| 25609 | |
| 25610 | For outgoing SMTP deliveries, $tls_out_cipher is used and logged (again |
| 25611 | depending on the tls_cipher log selector). |
| 25612 | |
| 25613 | |
| 25614 | 42.7 Requesting and verifying client certificates |
| 25615 | ------------------------------------------------- |
| 25616 | |
| 25617 | If you want an Exim server to request a certificate when negotiating a TLS |
| 25618 | session with a client, you must set either tls_verify_hosts or |
| 25619 | tls_try_verify_hosts. You can, of course, set either of them to * to apply to |
| 25620 | all TLS connections. For any host that matches one of these options, Exim |
| 25621 | requests a certificate as part of the setup of the TLS session. The contents of |
| 25622 | the certificate are verified by comparing it with a list of expected |
| 25623 | certificates. These may be the system default set (depending on library |
| 25624 | version), an explicit file or, depending on library version, a directory, |
| 25625 | identified by tls_verify_certificates. |
| 25626 | |
| 25627 | A file can contain multiple certificates, concatenated end to end. If a |
| 25628 | directory is used (OpenSSL only), each certificate must be in a separate file, |
| 25629 | with a name (or a symbolic link) of the form <hash>.0, where <hash> is a hash |
| 25630 | value constructed from the certificate. You can compute the relevant hash by |
| 25631 | running the command |
| 25632 | |
| 25633 | openssl x509 -hash -noout -in /cert/file |
| 25634 | |
| 25635 | where /cert/file contains a single certificate. |
| 25636 | |
| 25637 | The difference between tls_verify_hosts and tls_try_verify_hosts is what |
| 25638 | happens if the client does not supply a certificate, or if the certificate does |
| 25639 | not match any of the certificates in the collection named by |
| 25640 | tls_verify_certificates. If the client matches tls_verify_hosts, the attempt to |
| 25641 | set up a TLS session is aborted, and the incoming connection is dropped. If the |
| 25642 | client matches tls_try_verify_hosts, the (encrypted) SMTP session continues. |
| 25643 | ACLs that run for subsequent SMTP commands can detect the fact that no |
| 25644 | certificate was verified, and vary their actions accordingly. For example, you |
| 25645 | can insist on a certificate before accepting a message for relaying, but not |
| 25646 | when the message is destined for local delivery. |
| 25647 | |
| 25648 | When a client supplies a certificate (whether it verifies or not), the value of |
| 25649 | the Distinguished Name of the certificate is made available in the variable |
| 25650 | $tls_in_peerdn during subsequent processing of the message. |
| 25651 | |
| 25652 | Because it is often a long text string, it is not included in the log line or |
| 25653 | Received: header by default. You can arrange for it to be logged, keyed by "DN= |
| 25654 | ", by setting the tls_peerdn log selector, and you can use received_header_text |
| 25655 | to change the Received: header. When no certificate is supplied, $tls_in_peerdn |
| 25656 | is empty. |
| 25657 | |
| 25658 | |
| 25659 | 42.8 Revoked certificates |
| 25660 | ------------------------- |
| 25661 | |
| 25662 | Certificate issuing authorities issue Certificate Revocation Lists (CRLs) when |
| 25663 | certificates are revoked. If you have such a list, you can pass it to an Exim |
| 25664 | server using the global option called tls_crl and to an Exim client using an |
| 25665 | identically named option for the smtp transport. In each case, the value of the |
| 25666 | option is expanded and must then be the name of a file that contains a CRL in |
| 25667 | PEM format. The downside is that clients have to periodically re-download a |
| 25668 | potentially huge file from every certificate authority they know of. |
| 25669 | |
| 25670 | The way with most moving parts at query time is Online Certificate Status |
| 25671 | Protocol (OCSP), where the client verifies the certificate against an OCSP |
| 25672 | server run by the CA. This lets the CA track all usage of the certs. It |
| 25673 | requires running software with access to the private key of the CA, to sign the |
| 25674 | responses to the OCSP queries. OCSP is based on HTTP and can be proxied |
| 25675 | accordingly. |
| 25676 | |
| 25677 | The only widespread OCSP server implementation (known to this writer) comes as |
| 25678 | part of OpenSSL and aborts on an invalid request, such as connecting to the |
| 25679 | port and then disconnecting. This requires re-entering the passphrase each time |
| 25680 | some random client does this. |
| 25681 | |
| 25682 | The third way is OCSP Stapling; in this, the server using a certificate issued |
| 25683 | by the CA periodically requests an OCSP proof of validity from the OCSP server, |
| 25684 | then serves it up inline as part of the TLS negotiation. This approach adds no |
| 25685 | extra round trips, does not let the CA track users, scales well with number of |
| 25686 | certs issued by the CA and is resilient to temporary OCSP server failures, as |
| 25687 | long as the server starts retrying to fetch an OCSP proof some time before its |
| 25688 | current proof expires. The downside is that it requires server support. |
| 25689 | |
| 25690 | Unless Exim is built with the support disabled, or with GnuTLS earlier than |
| 25691 | version 3.3.16 / 3.4.8 support for OCSP stapling is included. |
| 25692 | |
| 25693 | There is a global option called tls_ocsp_file. The file specified therein is |
| 25694 | expected to be in DER format, and contain an OCSP proof. Exim will serve it as |
| 25695 | part of the TLS handshake. This option will be re-expanded for SNI, if the |
| 25696 | tls_certificate option contains "tls_in_sni", as per other TLS options. |
| 25697 | |
| 25698 | Exim does not at this time implement any support for fetching a new OCSP proof. |
| 25699 | The burden is on the administrator to handle this, outside of Exim. The file |
| 25700 | specified should be replaced atomically, so that the contents are always valid. |
| 25701 | Exim will expand the tls_ocsp_file option on each connection, so a new file |
| 25702 | will be handled transparently on the next connection. |
| 25703 | |
| 25704 | When built with OpenSSL Exim will check for a valid next update timestamp in |
| 25705 | the OCSP proof; if not present, or if the proof has expired, it will be |
| 25706 | ignored. |
| 25707 | |
| 25708 | For the client to be able to verify the stapled OCSP the server must also |
| 25709 | supply, in its stapled information, any intermediate certificates for the chain |
| 25710 | leading to the OCSP proof from the signer of the server certificate. There may |
| 25711 | be zero or one such. These intermediate certificates should be added to the |
| 25712 | server OCSP stapling file named by tls_ocsp_file. |
| 25713 | |
| 25714 | Note that the proof only covers the terminal server certificate, not any of the |
| 25715 | chain from CA to it. |
| 25716 | |
| 25717 | There is no current way to staple a proof for a client certificate. |
| 25718 | |
| 25719 | A helper script "ocsp_fetch.pl" for fetching a proof from a CA |
| 25720 | OCSP server is supplied. The server URL may be included in the |
| 25721 | server certificate, if the CA is helpful. |
| 25722 | |
| 25723 | One failure mode seen was the OCSP Signer cert expiring before the end |
| 25724 | of validity of the OCSP proof. The checking done by Exim/OpenSSL |
| 25725 | noted this as invalid overall, but the re-fetch script did not. |
| 25726 | |
| 25727 | |
| 25728 | 42.9 Configuring an Exim client to use TLS |
| 25729 | ------------------------------------------ |
| 25730 | |
| 25731 | The tls_cipher and tls_peerdn log selectors apply to outgoing SMTP deliveries |
| 25732 | as well as to incoming, the latter one causing logging of the server |
| 25733 | certificate's DN. The remaining client configuration for TLS is all within the |
| 25734 | smtp transport. |
| 25735 | |
| 25736 | It is not necessary to set any options to have TLS work in the smtp transport. |
| 25737 | If Exim is built with TLS support, and TLS is advertised by a server, the smtp |
| 25738 | transport always tries to start a TLS session. However, this can be prevented |
| 25739 | by setting hosts_avoid_tls (an option of the transport) to a list of server |
| 25740 | hosts for which TLS should not be used. |
| 25741 | |
| 25742 | If you do not want Exim to attempt to send messages unencrypted when an attempt |
| 25743 | to set up an encrypted connection fails in any way, you can set |
| 25744 | hosts_require_tls to a list of hosts for which encryption is mandatory. For |
| 25745 | those hosts, delivery is always deferred if an encrypted connection cannot be |
| 25746 | set up. If there are any other hosts for the address, they are tried in the |
| 25747 | usual way. |
| 25748 | |
| 25749 | When the server host is not in hosts_require_tls, Exim may try to deliver the |
| 25750 | message unencrypted. It always does this if the response to STARTTLS is a 5xx |
| 25751 | code. For a temporary error code, or for a failure to negotiate a TLS session |
| 25752 | after a success response code, what happens is controlled by the |
| 25753 | tls_tempfail_tryclear option of the smtp transport. If it is false, delivery to |
| 25754 | this host is deferred, and other hosts (if available) are tried. If it is true, |
| 25755 | Exim attempts to deliver unencrypted after a 4xx response to STARTTLS, and if |
| 25756 | STARTTLS is accepted, but the subsequent TLS negotiation fails, Exim closes the |
| 25757 | current connection (because it is in an unknown state), opens a new one to the |
| 25758 | same host, and then tries the delivery unencrypted. |
| 25759 | |
| 25760 | The tls_certificate and tls_privatekey options of the smtp transport provide |
| 25761 | the client with a certificate, which is passed to the server if it requests it. |
| 25762 | If the server is Exim, it will request a certificate only if tls_verify_hosts |
| 25763 | or tls_try_verify_hosts matches the client. |
| 25764 | |
| 25765 | If the tls_verify_certificates option is set on the smtp transport, it |
| 25766 | specifies a collection of expected server certificates. These may be the system |
| 25767 | default set (depending on library version), a file or, depending on library |
| 25768 | version, a directory, must name a file or, for OpenSSL only (not GnuTLS), a |
| 25769 | directory. The client verifies the server's certificate against this |
| 25770 | collection, taking into account any revoked certificates that are in the list |
| 25771 | defined by tls_crl. Failure to verify fails the TLS connection unless either of |
| 25772 | the tls_verify_hosts or tls_try_verify_hosts options are set. |
| 25773 | |
| 25774 | The tls_verify_hosts and tls_try_verify_hosts options restrict certificate |
| 25775 | verification to the listed servers. Verification either must or need not |
| 25776 | succeed respectively. |
| 25777 | |
| 25778 | The smtp transport has two OCSP-related options: hosts_require_ocsp; a |
| 25779 | host-list for which a Certificate Status is requested and required for the |
| 25780 | connection to proceed. The default value is empty. hosts_request_ocsp; a |
| 25781 | host-list for which (additionally) a Certificate Status is requested (but not |
| 25782 | necessarily verified). The default value is "*" meaning that requests are made |
| 25783 | unless configured otherwise. |
| 25784 | |
| 25785 | The host(s) should also be in hosts_require_tls, and tls_verify_certificates |
| 25786 | configured for the transport, for OCSP to be relevant. |
| 25787 | |
| 25788 | If tls_require_ciphers is set on the smtp transport, it must contain a list of |
| 25789 | permitted cipher suites. If either of these checks fails, delivery to the |
| 25790 | current host is abandoned, and the smtp transport tries to deliver to |
| 25791 | alternative hosts, if any. |
| 25792 | |
| 25793 | Note: These options must be set in the smtp transport for Exim to use TLS when |
| 25794 | it is operating as a client. Exim does not assume that a server certificate |
| 25795 | (set by the global options of the same name) should also be used when operating |
| 25796 | as a client. |
| 25797 | |
| 25798 | All the TLS options in the smtp transport are expanded before use, with $host |
| 25799 | and $host_address containing the name and address of the server to which the |
| 25800 | client is connected. Forced failure of an expansion causes Exim to behave as if |
| 25801 | the relevant option were unset. |
| 25802 | |
| 25803 | Before an SMTP connection is established, the $tls_out_bits, $tls_out_cipher, |
| 25804 | $tls_out_peerdn and $tls_out_sni variables are emptied. (Until the first |
| 25805 | connection, they contain the values that were set when the message was |
| 25806 | received.) If STARTTLS is subsequently successfully obeyed, these variables are |
| 25807 | set to the relevant values for the outgoing connection. |
| 25808 | |
| 25809 | |
| 25810 | 42.10 Use of TLS Server Name Indication |
| 25811 | --------------------------------------- |
| 25812 | |
| 25813 | With TLS1.0 or above, there is an extension mechanism by which extra |
| 25814 | information can be included at various points in the protocol. One of these |
| 25815 | extensions, documented in RFC 6066 (and before that RFC 4366) is "Server Name |
| 25816 | Indication", commonly "SNI". This extension is sent by the client in the |
| 25817 | initial handshake, so that the server can examine the servername within and |
| 25818 | possibly choose to use different certificates and keys (and more) for this |
| 25819 | session. |
| 25820 | |
| 25821 | This is analogous to HTTP's "Host:" header, and is the main mechanism by which |
| 25822 | HTTPS-enabled web-sites can be virtual-hosted, many sites to one IP address. |
| 25823 | |
| 25824 | With SMTP to MX, there are the same problems here as in choosing the identity |
| 25825 | against which to validate a certificate: you can't rely on insecure DNS to |
| 25826 | provide the identity which you then cryptographically verify. So this will be |
| 25827 | of limited use in that environment. |
| 25828 | |
| 25829 | With SMTP to Submission, there is a well-defined hostname which clients are |
| 25830 | connecting to and can validate certificates against. Thus clients can choose to |
| 25831 | include this information in the TLS negotiation. If this becomes wide-spread, |
| 25832 | then hosters can choose to present different certificates to different clients. |
| 25833 | Or even negotiate different cipher suites. |
| 25834 | |
| 25835 | The tls_sni option on an SMTP transport is an expanded string; the result, if |
| 25836 | not empty, will be sent on a TLS session as part of the handshake. There's |
| 25837 | nothing more to it. Choosing a sensible value not derived insecurely is the |
| 25838 | only point of caution. The $tls_out_sni variable will be set to this string for |
| 25839 | the lifetime of the client connection (including during authentication). |
| 25840 | |
| 25841 | Except during SMTP client sessions, if $tls_in_sni is set then it is a string |
| 25842 | received from a client. It can be logged with the log_selector item "+tls_sni". |
| 25843 | |
| 25844 | If the string "tls_in_sni" appears in the main section's tls_certificate option |
| 25845 | (prior to expansion) then the following options will be re-expanded during TLS |
| 25846 | session handshake, to permit alternative values to be chosen: |
| 25847 | |
| 25848 | * tls_certificate |
| 25849 | |
| 25850 | * tls_crl |
| 25851 | |
| 25852 | * tls_privatekey |
| 25853 | |
| 25854 | * tls_verify_certificates |
| 25855 | |
| 25856 | * tls_ocsp_file |
| 25857 | |
| 25858 | Great care should be taken to deal with matters of case, various injection |
| 25859 | attacks in the string ("../" or SQL), and ensuring that a valid filename can |
| 25860 | always be referenced; it is important to remember that $tls_in_sni is arbitrary |
| 25861 | unverified data provided prior to authentication. Further, the initial |
| 25862 | certificate is loaded before SNI is arrived, so an expansion for |
| 25863 | tls_certificate must have a default which is used when $tls_in_sni is empty. |
| 25864 | |
| 25865 | The Exim developers are proceeding cautiously and so far no other TLS options |
| 25866 | are re-expanded. |
| 25867 | |
| 25868 | When Exim is built against OpenSSL, OpenSSL must have been built with support |
| 25869 | for TLS Extensions. This holds true for OpenSSL 1.0.0+ and 0.9.8+ with |
| 25870 | enable-tlsext in EXTRACONFIGURE. If you invoke openssl s_client -h and see |
| 25871 | "-servername" in the output, then OpenSSL has support. |
| 25872 | |
| 25873 | When Exim is built against GnuTLS, SNI support is available as of GnuTLS |
| 25874 | 0.5.10. (Its presence predates the current API which Exim uses, so if Exim |
| 25875 | built, then you have SNI support). |
| 25876 | |
| 25877 | |
| 25878 | 42.11 Multiple messages on the same encrypted TCP/IP connection |
| 25879 | --------------------------------------------------------------- |
| 25880 | |
| 25881 | Exim sends multiple messages down the same TCP/IP connection by starting up an |
| 25882 | entirely new delivery process for each message, passing the socket from one |
| 25883 | process to the next. This implementation does not fit well with the use of TLS, |
| 25884 | because there is quite a lot of state information associated with a TLS |
| 25885 | connection, not just a socket identification. Passing all the state information |
| 25886 | to a new process is not feasible. Consequently, Exim shuts down an existing TLS |
| 25887 | session before passing the socket to a new process. The new process may then |
| 25888 | try to start a new TLS session, and if successful, may try to re-authenticate |
| 25889 | if AUTH is in use, before sending the next message. |
| 25890 | |
| 25891 | The RFC is not clear as to whether or not an SMTP session continues in clear |
| 25892 | after TLS has been shut down, or whether TLS may be restarted again later, as |
| 25893 | just described. However, if the server is Exim, this shutdown and |
| 25894 | reinitialization works. It is not known which (if any) other servers operate |
| 25895 | successfully if the client closes a TLS session and continues with unencrypted |
| 25896 | SMTP, but there are certainly some that do not work. For such servers, Exim |
| 25897 | should not pass the socket to another process, because the failure of the |
| 25898 | subsequent attempt to use it would cause Exim to record a temporary host error, |
| 25899 | and delay other deliveries to that host. |
| 25900 | |
| 25901 | To test for this case, Exim sends an EHLO command to the server after closing |
| 25902 | down the TLS session. If this fails in any way, the connection is closed |
| 25903 | instead of being passed to a new delivery process, but no retry information is |
| 25904 | recorded. |
| 25905 | |
| 25906 | There is also a manual override; you can set hosts_nopass_tls on the smtp |
| 25907 | transport to match those hosts for which Exim should not pass connections to |
| 25908 | new processes if TLS has been used. |
| 25909 | |
| 25910 | |
| 25911 | 42.12 Certificates and all that |
| 25912 | ------------------------------- |
| 25913 | |
| 25914 | In order to understand fully how TLS works, you need to know about |
| 25915 | certificates, certificate signing, and certificate authorities. This is not the |
| 25916 | place to give a tutorial, especially as I do not know very much about it |
| 25917 | myself. Some helpful introduction can be found in the FAQ for the SSL addition |
| 25918 | to Apache, currently at |
| 25919 | |
| 25920 | http://www.modssl.org/docs/2.7/ssl_faq.html#ToC24 |
| 25921 | |
| 25922 | Other parts of the modssl documentation are also helpful, and have links to |
| 25923 | further files. Eric Rescorla's book, SSL and TLS, published by Addison-Wesley |
| 25924 | (ISBN 0-201-61598-3), contains both introductory and more in-depth |
| 25925 | descriptions. Some sample programs taken from the book are available from |
| 25926 | |
| 25927 | http://www.rtfm.com/openssl-examples/ |
| 25928 | |
| 25929 | |
| 25930 | 42.13 Certificate chains |
| 25931 | ------------------------ |
| 25932 | |
| 25933 | The file named by tls_certificate may contain more than one certificate. This |
| 25934 | is useful in the case where the certificate that is being sent is validated by |
| 25935 | an intermediate certificate which the other end does not have. Multiple |
| 25936 | certificates must be in the correct order in the file. First the host's |
| 25937 | certificate itself, then the first intermediate certificate to validate the |
| 25938 | issuer of the host certificate, then the next intermediate certificate to |
| 25939 | validate the issuer of the first intermediate certificate, and so on, until |
| 25940 | finally (optionally) the root certificate. The root certificate must already be |
| 25941 | trusted by the recipient for validation to succeed, of course, but if it's not |
| 25942 | preinstalled, sending the root certificate along with the rest makes it |
| 25943 | available for the user to install if the receiving end is a client MUA that can |
| 25944 | interact with a user. |
| 25945 | |
| 25946 | Note that certificates using MD5 are unlikely to work on today's Internet; even |
| 25947 | if your libraries allow loading them for use in Exim when acting as a server, |
| 25948 | increasingly clients will not accept such certificates. The error diagnostics |
| 25949 | in such a case can be frustratingly vague. |
| 25950 | |
| 25951 | |
| 25952 | 42.14 Self-signed certificates |
| 25953 | ------------------------------ |
| 25954 | |
| 25955 | You can create a self-signed certificate using the req command provided with |
| 25956 | OpenSSL, like this: |
| 25957 | |
| 25958 | openssl req -x509 -newkey rsa:1024 -keyout file1 -out file2 \ |
| 25959 | -days 9999 -nodes |
| 25960 | |
| 25961 | file1 and file2 can be the same file; the key and the certificate are delimited |
| 25962 | and so can be identified independently. The -days option specifies a period for |
| 25963 | which the certificate is valid. The -nodes option is important: if you do not |
| 25964 | set it, the key is encrypted with a passphrase that you are prompted for, and |
| 25965 | any use that is made of the key causes more prompting for the passphrase. This |
| 25966 | is not helpful if you are going to use this certificate and key in an MTA, |
| 25967 | where prompting is not possible. |
| 25968 | |
| 25969 | NB: we are now past the point where 9999 days takes us past the 32-bit Unix |
| 25970 | epoch. If your system uses unsigned time_t (most do) and is 32-bit, then the |
| 25971 | above command might produce a date in the past. Think carefully about the |
| 25972 | lifetime of the systems you're deploying, and either reduce the duration of the |
| 25973 | certificate or reconsider your platform deployment. (At time of writing, |
| 25974 | reducing the duration is the most likely choice, but the inexorable progression |
| 25975 | of time takes us steadily towards an era where this will not be a sensible |
| 25976 | resolution). |
| 25977 | |
| 25978 | A self-signed certificate made in this way is sufficient for testing, and may |
| 25979 | be adequate for all your requirements if you are mainly interested in |
| 25980 | encrypting transfers, and not in secure identification. |
| 25981 | |
| 25982 | However, many clients require that the certificate presented by the server be a |
| 25983 | user (also called "leaf" or "site") certificate, and not a self-signed |
| 25984 | certificate. In this situation, the self-signed certificate described above |
| 25985 | must be installed on the client host as a trusted root certification authority |
| 25986 | (CA), and the certificate used by Exim must be a user certificate signed with |
| 25987 | that self-signed certificate. |
| 25988 | |
| 25989 | For information on creating self-signed CA certificates and using them to sign |
| 25990 | user certificates, see the General implementation overview chapter of the |
| 25991 | Open-source PKI book, available online at http://ospkibook.sourceforge.net/. |
| 25992 | |
| 25993 | |
| 25994 | |
| 25995 | =============================================================================== |
| 25996 | 43. ACCESS CONTROL LISTS |
| 25997 | |
| 25998 | Access Control Lists (ACLs) are defined in a separate section of the run time |
| 25999 | configuration file, headed by "begin acl". Each ACL definition starts with a |
| 26000 | name, terminated by a colon. Here is a complete ACL section that contains just |
| 26001 | one very small ACL: |
| 26002 | |
| 26003 | begin acl |
| 26004 | small_acl: |
| 26005 | accept hosts = one.host.only |
| 26006 | |
| 26007 | You can have as many lists as you like in the ACL section, and the order in |
| 26008 | which they appear does not matter. The lists are self-terminating. |
| 26009 | |
| 26010 | The majority of ACLs are used to control Exim's behaviour when it receives |
| 26011 | certain SMTP commands. This applies both to incoming TCP/IP connections, and |
| 26012 | when a local process submits a message using SMTP by specifying the -bs option. |
| 26013 | The most common use is for controlling which recipients are accepted in |
| 26014 | incoming messages. In addition, you can define an ACL that is used to check |
| 26015 | local non-SMTP messages. The default configuration file contains an example of |
| 26016 | a realistic ACL for checking RCPT commands. This is discussed in chapter 7. |
| 26017 | |
| 26018 | |
| 26019 | 43.1 Testing ACLs |
| 26020 | ----------------- |
| 26021 | |
| 26022 | The -bh command line option provides a way of testing your ACL configuration |
| 26023 | locally by running a fake SMTP session with which you interact. |
| 26024 | |
| 26025 | |
| 26026 | 43.2 Specifying when ACLs are used |
| 26027 | ---------------------------------- |
| 26028 | |
| 26029 | In order to cause an ACL to be used, you have to name it in one of the relevant |
| 26030 | options in the main part of the configuration. These options are: |
| 26031 | |
| 26032 | acl_not_smtp ACL for non-SMTP messages |
| 26033 | acl_not_smtp_mime ACL for non-SMTP MIME parts |
| 26034 | acl_not_smtp_start ACL at start of non-SMTP message |
| 26035 | acl_smtp_auth ACL for AUTH |
| 26036 | acl_smtp_connect ACL for start of SMTP connection |
| 26037 | acl_smtp_data ACL after DATA is complete |
| 26038 | acl_smtp_data_prdr ACL for each recipient, after DATA is complete |
| 26039 | acl_smtp_dkim ACL for each DKIM signer |
| 26040 | acl_smtp_etrn ACL for ETRN |
| 26041 | acl_smtp_expn ACL for EXPN |
| 26042 | acl_smtp_helo ACL for HELO or EHLO |
| 26043 | acl_smtp_mail ACL for MAIL |
| 26044 | acl_smtp_mailauth ACL for the AUTH parameter of MAIL |
| 26045 | acl_smtp_mime ACL for content-scanning MIME parts |
| 26046 | acl_smtp_notquit ACL for non-QUIT terminations |
| 26047 | acl_smtp_predata ACL at start of DATA command |
| 26048 | acl_smtp_quit ACL for QUIT |
| 26049 | acl_smtp_rcpt ACL for RCPT |
| 26050 | acl_smtp_starttls ACL for STARTTLS |
| 26051 | acl_smtp_vrfy ACL for VRFY |
| 26052 | |
| 26053 | For example, if you set |
| 26054 | |
| 26055 | acl_smtp_rcpt = small_acl |
| 26056 | |
| 26057 | the little ACL defined above is used whenever Exim receives a RCPT command in |
| 26058 | an SMTP dialogue. The majority of policy tests on incoming messages can be done |
| 26059 | when RCPT commands arrive. A rejection of RCPT should cause the sending MTA to |
| 26060 | give up on the recipient address contained in the RCPT command, whereas |
| 26061 | rejection at other times may cause the client MTA to keep on trying to deliver |
| 26062 | the message. It is therefore recommended that you do as much testing as |
| 26063 | possible at RCPT time. |
| 26064 | |
| 26065 | |
| 26066 | 43.3 The non-SMTP ACLs |
| 26067 | ---------------------- |
| 26068 | |
| 26069 | The non-SMTP ACLs apply to all non-interactive incoming messages, that is, they |
| 26070 | apply to batched SMTP as well as to non-SMTP messages. (Batched SMTP is not |
| 26071 | really SMTP.) Many of the ACL conditions (for example, host tests, and tests on |
| 26072 | the state of the SMTP connection such as encryption and authentication) are not |
| 26073 | relevant and are forbidden in these ACLs. However, the sender and recipients |
| 26074 | are known, so the senders and sender_domains conditions and the $sender_address |
| 26075 | and $recipients variables can be used. Variables such as $authenticated_sender |
| 26076 | are also available. You can specify added header lines in any of these ACLs. |
| 26077 | |
| 26078 | The acl_not_smtp_start ACL is run right at the start of receiving a non-SMTP |
| 26079 | message, before any of the message has been read. (This is the analogue of the |
| 26080 | acl_smtp_predata ACL for SMTP input.) In the case of batched SMTP input, it |
| 26081 | runs after the DATA command has been reached. The result of this ACL is |
| 26082 | ignored; it cannot be used to reject a message. If you really need to, you |
| 26083 | could set a value in an ACL variable here and reject based on that in the |
| 26084 | acl_not_smtp ACL. However, this ACL can be used to set controls, and in |
| 26085 | particular, it can be used to set |
| 26086 | |
| 26087 | control = suppress_local_fixups |
| 26088 | |
| 26089 | This cannot be used in the other non-SMTP ACLs because by the time they are |
| 26090 | run, it is too late. |
| 26091 | |
| 26092 | The acl_not_smtp_mime ACL is available only when Exim is compiled with the |
| 26093 | content-scanning extension. For details, see chapter 44. |
| 26094 | |
| 26095 | The acl_not_smtp ACL is run just before the local_scan() function. Any kind of |
| 26096 | rejection is treated as permanent, because there is no way of sending a |
| 26097 | temporary error for these kinds of message. |
| 26098 | |
| 26099 | |
| 26100 | 43.4 The SMTP connect ACL |
| 26101 | ------------------------- |
| 26102 | |
| 26103 | The ACL test specified by acl_smtp_connect happens at the start of an SMTP |
| 26104 | session, after the test specified by host_reject_connection (which is now an |
| 26105 | anomaly) and any TCP Wrappers testing (if configured). If the connection is |
| 26106 | accepted by an accept verb that has a message modifier, the contents of the |
| 26107 | message override the banner message that is otherwise specified by the |
| 26108 | smtp_banner option. |
| 26109 | |
| 26110 | |
| 26111 | 43.5 The EHLO/HELO ACL |
| 26112 | ---------------------- |
| 26113 | |
| 26114 | The ACL test specified by acl_smtp_helo happens when the client issues an EHLO |
| 26115 | or HELO command, after the tests specified by helo_accept_junk_hosts, |
| 26116 | helo_allow_chars, helo_verify_hosts, and helo_try_verify_hosts. Note that a |
| 26117 | client may issue more than one EHLO or HELO command in an SMTP session, and |
| 26118 | indeed is required to issue a new EHLO or HELO after successfully setting up |
| 26119 | encryption following a STARTTLS command. |
| 26120 | |
| 26121 | Note also that a deny neither forces the client to go away nor means that mail |
| 26122 | will be refused on the connection. Consider checking for $sender_helo_name |
| 26123 | being defined in a MAIL or RCPT ACL to do that. |
| 26124 | |
| 26125 | If the command is accepted by an accept verb that has a message modifier, the |
| 26126 | message may not contain more than one line (it will be truncated at the first |
| 26127 | newline and a panic logged if it does). Such a message cannot affect the EHLO |
| 26128 | options that are listed on the second and subsequent lines of an EHLO response. |
| 26129 | |
| 26130 | |
| 26131 | 43.6 The DATA ACLs |
| 26132 | ------------------ |
| 26133 | |
| 26134 | Two ACLs are associated with the DATA command, because it is two-stage command, |
| 26135 | with two responses being sent to the client. When the DATA command is received, |
| 26136 | the ACL defined by acl_smtp_predata is obeyed. This gives you control after all |
| 26137 | the RCPT commands, but before the message itself is received. It offers the |
| 26138 | opportunity to give a negative response to the DATA command before the data is |
| 26139 | transmitted. Header lines added by MAIL or RCPT ACLs are not visible at this |
| 26140 | time, but any that are defined here are visible when the acl_smtp_data ACL is |
| 26141 | run. |
| 26142 | |
| 26143 | You cannot test the contents of the message, for example, to verify addresses |
| 26144 | in the headers, at RCPT time or when the DATA command is received. Such tests |
| 26145 | have to appear in the ACL that is run after the message itself has been |
| 26146 | received, before the final response to the DATA command is sent. This is the |
| 26147 | ACL specified by acl_smtp_data, which is the second ACL that is associated with |
| 26148 | the DATA command. |
| 26149 | |
| 26150 | If CHUNKING was advertised and a BDAT command sequence is received, the |
| 26151 | acl_smtp_predata ACL is not run. The acl_smtp_data is run after the last BDAT |
| 26152 | command and all of the data specified is received. |
| 26153 | |
| 26154 | For both of these ACLs, it is not possible to reject individual recipients. An |
| 26155 | error response rejects the entire message. Unfortunately, it is known that some |
| 26156 | MTAs do not treat hard (5xx) responses to the DATA command (either before or |
| 26157 | after the data) correctly - they keep the message on their queues and try again |
| 26158 | later, but that is their problem, though it does waste some of your resources. |
| 26159 | |
| 26160 | The acl_smtp_data ACL is run after the acl_smtp_data_prdr, the acl_smtp_dkim |
| 26161 | and the acl_smtp_mime ACLs. |
| 26162 | |
| 26163 | |
| 26164 | 43.7 The SMTP DKIM ACL |
| 26165 | ---------------------- |
| 26166 | |
| 26167 | The acl_smtp_dkim ACL is available only when Exim is compiled with DKIM support |
| 26168 | enabled (which is the default). |
| 26169 | |
| 26170 | The ACL test specified by acl_smtp_dkim happens after a message has been |
| 26171 | received, and is executed for each DKIM signature found in a message. If not |
| 26172 | otherwise specified, the default action is to accept. |
| 26173 | |
| 26174 | This ACL is evaluated before acl_smtp_mime and acl_smtp_data. |
| 26175 | |
| 26176 | For details on the operation of DKIM, see chapter 57. |
| 26177 | |
| 26178 | |
| 26179 | 43.8 The SMTP MIME ACL |
| 26180 | ---------------------- |
| 26181 | |
| 26182 | The acl_smtp_mime option is available only when Exim is compiled with the |
| 26183 | content-scanning extension. For details, see chapter 44. |
| 26184 | |
| 26185 | This ACL is evaluated after acl_smtp_dkim but before acl_smtp_data. |
| 26186 | |
| 26187 | |
| 26188 | 43.9 The SMTP PRDR ACL |
| 26189 | ---------------------- |
| 26190 | |
| 26191 | The acl_smtp_data_prdr ACL is available only when Exim is compiled with PRDR |
| 26192 | support enabled (which is the default). It becomes active only when the PRDR |
| 26193 | feature is negotiated between client and server for a message, and more than |
| 26194 | one recipient has been accepted. |
| 26195 | |
| 26196 | The ACL test specified by acl_smtp_data_prdr happens after a message has been |
| 26197 | received, and is executed once for each recipient of the message with |
| 26198 | $local_part and $domain valid. The test may accept, defer or deny for |
| 26199 | individual recipients. The acl_smtp_data will still be called after this ACL |
| 26200 | and can reject the message overall, even if this ACL has accepted it for some |
| 26201 | or all recipients. |
| 26202 | |
| 26203 | PRDR may be used to support per-user content filtering. Without it one must |
| 26204 | defer any recipient after the first that has a different content-filter |
| 26205 | configuration. With PRDR, the RCPT-time check for this can be disabled when the |
| 26206 | variable $prdr_requested is "yes". Any required difference in behaviour of the |
| 26207 | main DATA-time ACL should however depend on the PRDR-time ACL having run, as |
| 26208 | Exim will avoid doing so in some situations (e.g. single-recipient mails). |
| 26209 | |
| 26210 | See also the prdr_enable global option and the hosts_try_prdr smtp transport |
| 26211 | option. |
| 26212 | |
| 26213 | This ACL is evaluated after acl_smtp_dkim but before acl_smtp_data. If the ACL |
| 26214 | is not defined, processing completes as if the feature was not requested by the |
| 26215 | client. |
| 26216 | |
| 26217 | |
| 26218 | 43.10 The QUIT ACL |
| 26219 | ------------------ |
| 26220 | |
| 26221 | The ACL for the SMTP QUIT command is anomalous, in that the outcome of the ACL |
| 26222 | does not affect the response code to QUIT, which is always 221. Thus, the ACL |
| 26223 | does not in fact control any access. For this reason, it may only accept or |
| 26224 | warn as its final result. |
| 26225 | |
| 26226 | This ACL can be used for tasks such as custom logging at the end of an SMTP |
| 26227 | session. For example, you can use ACL variables in other ACLs to count |
| 26228 | messages, recipients, etc., and log the totals at QUIT time using one or more |
| 26229 | logwrite modifiers on a warn verb. |
| 26230 | |
| 26231 | Warning: Only the $acl_cx variables can be used for this, because the $acl_mx |
| 26232 | variables are reset at the end of each incoming message. |
| 26233 | |
| 26234 | You do not need to have a final accept, but if you do, you can use a message |
| 26235 | modifier to specify custom text that is sent as part of the 221 response to |
| 26236 | QUIT. |
| 26237 | |
| 26238 | This ACL is run only for a "normal" QUIT. For certain kinds of disastrous |
| 26239 | failure (for example, failure to open a log file, or when Exim is bombing out |
| 26240 | because it has detected an unrecoverable error), all SMTP commands from the |
| 26241 | client are given temporary error responses until QUIT is received or the |
| 26242 | connection is closed. In these special cases, the QUIT ACL does not run. |
| 26243 | |
| 26244 | |
| 26245 | 43.11 The not-QUIT ACL |
| 26246 | ---------------------- |
| 26247 | |
| 26248 | The not-QUIT ACL, specified by acl_smtp_notquit, is run in most cases when an |
| 26249 | SMTP session ends without sending QUIT. However, when Exim itself is in bad |
| 26250 | trouble, such as being unable to write to its log files, this ACL is not run, |
| 26251 | because it might try to do things (such as write to log files) that make the |
| 26252 | situation even worse. |
| 26253 | |
| 26254 | Like the QUIT ACL, this ACL is provided to make it possible to do customized |
| 26255 | logging or to gather statistics, and its outcome is ignored. The delay modifier |
| 26256 | is forbidden in this ACL, and the only permitted verbs are accept and warn. |
| 26257 | |
| 26258 | When the not-QUIT ACL is running, the variable $smtp_notquit_reason is set to a |
| 26259 | string that indicates the reason for the termination of the SMTP connection. |
| 26260 | The possible values are: |
| 26261 | |
| 26262 | "acl-drop" Another ACL issued a drop command |
| 26263 | "bad-commands" Too many unknown or non-mail commands |
| 26264 | "command-timeout" Timeout while reading SMTP commands |
| 26265 | "connection-lost" The SMTP connection has been lost |
| 26266 | "data-timeout" Timeout while reading message data |
| 26267 | "local-scan-error" The local_scan() function crashed |
| 26268 | "local-scan-timeout" The local_scan() function timed out |
| 26269 | "signal-exit" SIGTERM or SIGINT |
| 26270 | "synchronization-error" SMTP synchronization error |
| 26271 | "tls-failed" TLS failed to start |
| 26272 | |
| 26273 | In most cases when an SMTP connection is closed without having received QUIT, |
| 26274 | Exim sends an SMTP response message before actually closing the connection. |
| 26275 | With the exception of the "acl-drop" case, the default message can be |
| 26276 | overridden by the message modifier in the not-QUIT ACL. In the case of a drop |
| 26277 | verb in another ACL, it is the message from the other ACL that is used. |
| 26278 | |
| 26279 | |
| 26280 | 43.12 Finding an ACL to use |
| 26281 | --------------------------- |
| 26282 | |
| 26283 | The value of an acl_smtp_xxx option is expanded before use, so you can use |
| 26284 | different ACLs in different circumstances. For example, |
| 26285 | |
| 26286 | acl_smtp_rcpt = ${if ={25}{$interface_port} \ |
| 26287 | {acl_check_rcpt} {acl_check_rcpt_submit} } |
| 26288 | |
| 26289 | In the default configuration file there are some example settings for providing |
| 26290 | an RFC 4409 message submission service on port 587 and a non-standard "smtps" |
| 26291 | service on port 465. You can use a string expansion like this to choose an ACL |
| 26292 | for MUAs on these ports which is more appropriate for this purpose than the |
| 26293 | default ACL on port 25. |
| 26294 | |
| 26295 | The expanded string does not have to be the name of an ACL in the configuration |
| 26296 | file; there are other possibilities. Having expanded the string, Exim searches |
| 26297 | for an ACL as follows: |
| 26298 | |
| 26299 | * If the string begins with a slash, Exim uses it as a file name, and reads |
| 26300 | its contents as an ACL. The lines are processed in the same way as lines in |
| 26301 | the Exim configuration file. In particular, continuation lines are |
| 26302 | supported, blank lines are ignored, as are lines whose first non-whitespace |
| 26303 | character is "#". If the file does not exist or cannot be read, an error |
| 26304 | occurs (typically causing a temporary failure of whatever caused the ACL to |
| 26305 | be run). For example: |
| 26306 | |
| 26307 | acl_smtp_data = /etc/acls/\ |
| 26308 | ${lookup{$sender_host_address}lsearch\ |
| 26309 | {/etc/acllist}{$value}{default}} |
| 26310 | |
| 26311 | This looks up an ACL file to use on the basis of the host's IP address, |
| 26312 | falling back to a default if the lookup fails. If an ACL is successfully |
| 26313 | read from a file, it is retained in memory for the duration of the Exim |
| 26314 | process, so that it can be re-used without having to re-read the file. |
| 26315 | |
| 26316 | * If the string does not start with a slash, and does not contain any spaces, |
| 26317 | Exim searches the ACL section of the configuration for an ACL whose name |
| 26318 | matches the string. |
| 26319 | |
| 26320 | * If no named ACL is found, or if the string contains spaces, Exim parses the |
| 26321 | string as an inline ACL. This can save typing in cases where you just want |
| 26322 | to have something like |
| 26323 | |
| 26324 | acl_smtp_vrfy = accept |
| 26325 | |
| 26326 | in order to allow free use of the VRFY command. Such a string may contain |
| 26327 | newlines; it is processed in the same way as an ACL that is read from a |
| 26328 | file. |
| 26329 | |
| 26330 | |
| 26331 | 43.13 ACL return codes |
| 26332 | ---------------------- |
| 26333 | |
| 26334 | Except for the QUIT ACL, which does not affect the SMTP return code (see |
| 26335 | section 43.10 above), the result of running an ACL is either "accept" or |
| 26336 | "deny", or, if some test cannot be completed (for example, if a database is |
| 26337 | down), "defer". These results cause 2xx, 5xx, and 4xx return codes, |
| 26338 | respectively, to be used in the SMTP dialogue. A fourth return, "error", occurs |
| 26339 | when there is an error such as invalid syntax in the ACL. This also causes a 4 |
| 26340 | xx return code. |
| 26341 | |
| 26342 | For the non-SMTP ACL, "defer" and "error" are treated in the same way as |
| 26343 | "deny", because there is no mechanism for passing temporary errors to the |
| 26344 | submitters of non-SMTP messages. |
| 26345 | |
| 26346 | ACLs that are relevant to message reception may also return "discard". This has |
| 26347 | the effect of "accept", but causes either the entire message or an individual |
| 26348 | recipient address to be discarded. In other words, it is a blackholing |
| 26349 | facility. Use it with care. |
| 26350 | |
| 26351 | If the ACL for MAIL returns "discard", all recipients are discarded, and no ACL |
| 26352 | is run for subsequent RCPT commands. The effect of "discard" in a RCPT ACL is |
| 26353 | to discard just the one recipient address. If there are no recipients left when |
| 26354 | the message's data is received, the DATA ACL is not run. A "discard" return |
| 26355 | from the DATA or the non-SMTP ACL discards all the remaining recipients. The |
| 26356 | "discard" return is not permitted for the acl_smtp_predata ACL. |
| 26357 | |
| 26358 | If the ACL for VRFY returns "accept", a recipient verify (without callout) is |
| 26359 | done on the address and the result determines the SMTP response. |
| 26360 | |
| 26361 | The local_scan() function is always run, even if there are no remaining |
| 26362 | recipients; it may create new recipients. |
| 26363 | |
| 26364 | |
| 26365 | 43.14 Unset ACL options |
| 26366 | ----------------------- |
| 26367 | |
| 26368 | The default actions when any of the acl_xxx options are unset are not all the |
| 26369 | same. Note: These defaults apply only when the relevant ACL is not defined at |
| 26370 | all. For any defined ACL, the default action when control reaches the end of |
| 26371 | the ACL statements is "deny". |
| 26372 | |
| 26373 | For acl_smtp_quit and acl_not_smtp_start there is no default because these two |
| 26374 | are ACLs that are used only for their side effects. They cannot be used to |
| 26375 | accept or reject anything. |
| 26376 | |
| 26377 | For acl_not_smtp, acl_smtp_auth, acl_smtp_connect, acl_smtp_data, acl_smtp_helo |
| 26378 | , acl_smtp_mail, acl_smtp_mailauth, acl_smtp_mime, acl_smtp_predata, and |
| 26379 | acl_smtp_starttls, the action when the ACL is not defined is "accept". |
| 26380 | |
| 26381 | For the others (acl_smtp_etrn, acl_smtp_expn, acl_smtp_rcpt, and acl_smtp_vrfy |
| 26382 | ), the action when the ACL is not defined is "deny". This means that |
| 26383 | acl_smtp_rcpt must be defined in order to receive any messages over an SMTP |
| 26384 | connection. For an example, see the ACL in the default configuration file. |
| 26385 | |
| 26386 | |
| 26387 | 43.15 Data for message ACLs |
| 26388 | --------------------------- |
| 26389 | |
| 26390 | When a MAIL or RCPT ACL, or either of the DATA ACLs, is running, the variables |
| 26391 | that contain information about the host and the message's sender (for example, |
| 26392 | $sender_host_address and $sender_address) are set, and can be used in ACL |
| 26393 | statements. In the case of RCPT (but not MAIL or DATA), $domain and $local_part |
| 26394 | are set from the argument address. The entire SMTP command is available in |
| 26395 | $smtp_command. |
| 26396 | |
| 26397 | When an ACL for the AUTH parameter of MAIL is running, the variables that |
| 26398 | contain information about the host are set, but $sender_address is not yet set. |
| 26399 | Section 33.2 contains a discussion of this parameter and how it is used. |
| 26400 | |
| 26401 | The $message_size variable is set to the value of the SIZE parameter on the |
| 26402 | MAIL command at MAIL, RCPT and pre-data time, or to -1 if that parameter is not |
| 26403 | given. The value is updated to the true message size by the time the final DATA |
| 26404 | ACL is run (after the message data has been received). |
| 26405 | |
| 26406 | The $rcpt_count variable increases by one for each RCPT command received. The |
| 26407 | $recipients_count variable increases by one each time a RCPT command is |
| 26408 | accepted, so while an ACL for RCPT is being processed, it contains the number |
| 26409 | of previously accepted recipients. At DATA time (for both the DATA ACLs), |
| 26410 | $rcpt_count contains the total number of RCPT commands, and $recipients_count |
| 26411 | contains the total number of accepted recipients. |
| 26412 | |
| 26413 | |
| 26414 | 43.16 Data for non-message ACLs |
| 26415 | ------------------------------- |
| 26416 | |
| 26417 | When an ACL is being run for AUTH, EHLO, ETRN, EXPN, HELO, STARTTLS, or VRFY, |
| 26418 | the remainder of the SMTP command line is placed in $smtp_command_argument, and |
| 26419 | the entire SMTP command is available in $smtp_command. These variables can be |
| 26420 | tested using a condition condition. For example, here is an ACL for use with |
| 26421 | AUTH, which insists that either the session is encrypted, or the CRAM-MD5 |
| 26422 | authentication method is used. In other words, it does not permit |
| 26423 | authentication methods that use cleartext passwords on unencrypted connections. |
| 26424 | |
| 26425 | acl_check_auth: |
| 26426 | accept encrypted = * |
| 26427 | accept condition = ${if eq{${uc:$smtp_command_argument}}\ |
| 26428 | {CRAM-MD5}} |
| 26429 | deny message = TLS encryption or CRAM-MD5 required |
| 26430 | |
| 26431 | (Another way of applying this restriction is to arrange for the authenticators |
| 26432 | that use cleartext passwords not to be advertised when the connection is not |
| 26433 | encrypted. You can use the generic server_advertise_condition authenticator |
| 26434 | option to do this.) |
| 26435 | |
| 26436 | |
| 26437 | 43.17 Format of an ACL |
| 26438 | ---------------------- |
| 26439 | |
| 26440 | An individual ACL consists of a number of statements. Each statement starts |
| 26441 | with a verb, optionally followed by a number of conditions and "modifiers". |
| 26442 | Modifiers can change the way the verb operates, define error and log messages, |
| 26443 | set variables, insert delays, and vary the processing of accepted messages. |
| 26444 | |
| 26445 | If all the conditions are met, the verb is obeyed. The same condition may be |
| 26446 | used (with different arguments) more than once in the same statement. This |
| 26447 | provides a means of specifying an "and" conjunction between conditions. For |
| 26448 | example: |
| 26449 | |
| 26450 | deny dnslists = list1.example |
| 26451 | dnslists = list2.example |
| 26452 | |
| 26453 | If there are no conditions, the verb is always obeyed. Exim stops evaluating |
| 26454 | the conditions and modifiers when it reaches a condition that fails. What |
| 26455 | happens then depends on the verb (and in one case, on a special modifier). Not |
| 26456 | all the conditions make sense at every testing point. For example, you cannot |
| 26457 | test a sender address in the ACL that is run for a VRFY command. |
| 26458 | |
| 26459 | |
| 26460 | 43.18 ACL verbs |
| 26461 | --------------- |
| 26462 | |
| 26463 | The ACL verbs are as follows: |
| 26464 | |
| 26465 | * accept: If all the conditions are met, the ACL returns "accept". If any of |
| 26466 | the conditions are not met, what happens depends on whether endpass appears |
| 26467 | among the conditions (for syntax see below). If the failing condition is |
| 26468 | before endpass, control is passed to the next ACL statement; if it is after |
| 26469 | endpass, the ACL returns "deny". Consider this statement, used to check a |
| 26470 | RCPT command: |
| 26471 | |
| 26472 | accept domains = +local_domains |
| 26473 | endpass |
| 26474 | verify = recipient |
| 26475 | |
| 26476 | If the recipient domain does not match the domains condition, control |
| 26477 | passes to the next statement. If it does match, the recipient is verified, |
| 26478 | and the command is accepted if verification succeeds. However, if |
| 26479 | verification fails, the ACL yields "deny", because the failing condition is |
| 26480 | after endpass. |
| 26481 | |
| 26482 | The endpass feature has turned out to be confusing to many people, so its |
| 26483 | use is not recommended nowadays. It is always possible to rewrite an ACL so |
| 26484 | that endpass is not needed, and it is no longer used in the default |
| 26485 | configuration. |
| 26486 | |
| 26487 | If a message modifier appears on an accept statement, its action depends on |
| 26488 | whether or not endpass is present. In the absence of endpass (when an |
| 26489 | accept verb either accepts or passes control to the next statement), |
| 26490 | message can be used to vary the message that is sent when an SMTP command |
| 26491 | is accepted. For example, in a RCPT ACL you could have: |
| 26492 | |
| 26493 | accept <some conditions> |
| 26494 | message = OK, I will allow you through today |
| 26495 | |
| 26496 | You can specify an SMTP response code, optionally followed by an "extended |
| 26497 | response code" at the start of the message, but the first digit must be the |
| 26498 | same as would be sent by default, which is 2 for an accept verb. |
| 26499 | |
| 26500 | If endpass is present in an accept statement, message specifies an error |
| 26501 | message that is used when access is denied. This behaviour is retained for |
| 26502 | backward compatibility, but current "best practice" is to avoid the use of |
| 26503 | endpass. |
| 26504 | |
| 26505 | * defer: If all the conditions are true, the ACL returns "defer" which, in an |
| 26506 | SMTP session, causes a 4xx response to be given. For a non-SMTP ACL, defer |
| 26507 | is the same as deny, because there is no way of sending a temporary error. |
| 26508 | For a RCPT command, defer is much the same as using a redirect router and |
| 26509 | ":defer:" while verifying, but the defer verb can be used in any ACL, and |
| 26510 | even for a recipient it might be a simpler approach. |
| 26511 | |
| 26512 | * deny: If all the conditions are met, the ACL returns "deny". If any of the |
| 26513 | conditions are not met, control is passed to the next ACL statement. For |
| 26514 | example, |
| 26515 | |
| 26516 | deny dnslists = blackholes.mail-abuse.org |
| 26517 | |
| 26518 | rejects commands from hosts that are on a DNS black list. |
| 26519 | |
| 26520 | * discard: This verb behaves like accept, except that it returns "discard" |
| 26521 | from the ACL instead of "accept". It is permitted only on ACLs that are |
| 26522 | concerned with receiving messages. When all the conditions are true, the |
| 26523 | sending entity receives a "success" response. However, discard causes |
| 26524 | recipients to be discarded. If it is used in an ACL for RCPT, just the one |
| 26525 | recipient is discarded; if used for MAIL, DATA or in the non-SMTP ACL, all |
| 26526 | the message's recipients are discarded. Recipients that are discarded |
| 26527 | before DATA do not appear in the log line when the received_recipients log |
| 26528 | selector is set. |
| 26529 | |
| 26530 | If the log_message modifier is set when discard operates, its contents are |
| 26531 | added to the line that is automatically written to the log. The message |
| 26532 | modifier operates exactly as it does for accept. |
| 26533 | |
| 26534 | * drop: This verb behaves like deny, except that an SMTP connection is |
| 26535 | forcibly closed after the 5xx error message has been sent. For example: |
| 26536 | |
| 26537 | drop message = I don't take more than 20 RCPTs |
| 26538 | condition = ${if > {$rcpt_count}{20}} |
| 26539 | |
| 26540 | There is no difference between deny and drop for the connect-time ACL. The |
| 26541 | connection is always dropped after sending a 550 response. |
| 26542 | |
| 26543 | * require: If all the conditions are met, control is passed to the next ACL |
| 26544 | statement. If any of the conditions are not met, the ACL returns "deny". |
| 26545 | For example, when checking a RCPT command, |
| 26546 | |
| 26547 | require message = Sender did not verify |
| 26548 | verify = sender |
| 26549 | |
| 26550 | passes control to subsequent statements only if the message's sender can be |
| 26551 | verified. Otherwise, it rejects the command. Note the positioning of the |
| 26552 | message modifier, before the verify condition. The reason for this is |
| 26553 | discussed in section 43.20. |
| 26554 | |
| 26555 | * warn: If all the conditions are true, a line specified by the log_message |
| 26556 | modifier is written to Exim's main log. Control always passes to the next |
| 26557 | ACL statement. If any condition is false, the log line is not written. If |
| 26558 | an identical log line is requested several times in the same message, only |
| 26559 | one copy is actually written to the log. If you want to force duplicates to |
| 26560 | be written, use the logwrite modifier instead. |
| 26561 | |
| 26562 | If log_message is not present, a warn verb just checks its conditions and |
| 26563 | obeys any "immediate" modifiers (such as control, set, logwrite, add_header |
| 26564 | , and remove_header) that appear before the first failing condition. There |
| 26565 | is more about adding header lines in section 43.24. |
| 26566 | |
| 26567 | If any condition on a warn statement cannot be completed (that is, there is |
| 26568 | some sort of defer), the log line specified by log_message is not written. |
| 26569 | This does not include the case of a forced failure from a lookup, which is |
| 26570 | considered to be a successful completion. After a defer, no further |
| 26571 | conditions or modifiers in the warn statement are processed. The incident |
| 26572 | is logged, and the ACL continues to be processed, from the next statement |
| 26573 | onwards. |
| 26574 | |
| 26575 | When one of the warn conditions is an address verification that fails, the |
| 26576 | text of the verification failure message is in $acl_verify_message. If you |
| 26577 | want this logged, you must set it up explicitly. For example: |
| 26578 | |
| 26579 | warn !verify = sender |
| 26580 | log_message = sender verify failed: $acl_verify_message |
| 26581 | |
| 26582 | At the end of each ACL there is an implicit unconditional deny. |
| 26583 | |
| 26584 | As you can see from the examples above, the conditions and modifiers are |
| 26585 | written one to a line, with the first one on the same line as the verb, and |
| 26586 | subsequent ones on following lines. If you have a very long condition, you can |
| 26587 | continue it onto several physical lines by the usual backslash continuation |
| 26588 | mechanism. It is conventional to align the conditions vertically. |
| 26589 | |
| 26590 | |
| 26591 | 43.19 ACL variables |
| 26592 | ------------------- |
| 26593 | |
| 26594 | There are some special variables that can be set during ACL processing. They |
| 26595 | can be used to pass information between different ACLs, different invocations |
| 26596 | of the same ACL in the same SMTP connection, and between ACLs and the routers, |
| 26597 | transports, and filters that are used to deliver a message. The names of these |
| 26598 | variables must begin with $acl_c or $acl_m, followed either by a digit or an |
| 26599 | underscore, but the remainder of the name can be any sequence of alphanumeric |
| 26600 | characters and underscores that you choose. There is no limit on the number of |
| 26601 | ACL variables. The two sets act as follows: |
| 26602 | |
| 26603 | * The values of those variables whose names begin with $acl_c persist |
| 26604 | throughout an SMTP connection. They are never reset. Thus, a value that is |
| 26605 | set while receiving one message is still available when receiving the next |
| 26606 | message on the same SMTP connection. |
| 26607 | |
| 26608 | * The values of those variables whose names begin with $acl_m persist only |
| 26609 | while a message is being received. They are reset afterwards. They are also |
| 26610 | reset by MAIL, RSET, EHLO, HELO, and after starting up a TLS session. |
| 26611 | |
| 26612 | When a message is accepted, the current values of all the ACL variables are |
| 26613 | preserved with the message and are subsequently made available at delivery |
| 26614 | time. The ACL variables are set by a modifier called set. For example: |
| 26615 | |
| 26616 | accept hosts = whatever |
| 26617 | set acl_m4 = some value |
| 26618 | accept authenticated = * |
| 26619 | set acl_c_auth = yes |
| 26620 | |
| 26621 | Note: A leading dollar sign is not used when naming a variable that is to be |
| 26622 | set. If you want to set a variable without taking any action, you can use a |
| 26623 | warn verb without any other modifiers or conditions. |
| 26624 | |
| 26625 | What happens if a syntactically valid but undefined ACL variable is referenced |
| 26626 | depends on the setting of the strict_acl_vars option. If it is false (the |
| 26627 | default), an empty string is substituted; if it is true, an error is generated. |
| 26628 | |
| 26629 | Versions of Exim before 4.64 have a limited set of numbered variables, but |
| 26630 | their names are compatible, so there is no problem with upgrading. |
| 26631 | |
| 26632 | |
| 26633 | 43.20 Condition and modifier processing |
| 26634 | --------------------------------------- |
| 26635 | |
| 26636 | An exclamation mark preceding a condition negates its result. For example: |
| 26637 | |
| 26638 | deny domains = *.dom.example |
| 26639 | !verify = recipient |
| 26640 | |
| 26641 | causes the ACL to return "deny" if the recipient domain ends in dom.example and |
| 26642 | the recipient address cannot be verified. Sometimes negation can be used on the |
| 26643 | right-hand side of a condition. For example, these two statements are |
| 26644 | equivalent: |
| 26645 | |
| 26646 | deny hosts = !192.168.3.4 |
| 26647 | deny !hosts = 192.168.3.4 |
| 26648 | |
| 26649 | However, for many conditions (verify being a good example), only left-hand side |
| 26650 | negation of the whole condition is possible. |
| 26651 | |
| 26652 | The arguments of conditions and modifiers are expanded. A forced failure of an |
| 26653 | expansion causes a condition to be ignored, that is, it behaves as if the |
| 26654 | condition is true. Consider these two statements: |
| 26655 | |
| 26656 | accept senders = ${lookup{$host_name}lsearch\ |
| 26657 | {/some/file}{$value}fail} |
| 26658 | accept senders = ${lookup{$host_name}lsearch\ |
| 26659 | {/some/file}{$value}{}} |
| 26660 | |
| 26661 | Each attempts to look up a list of acceptable senders. If the lookup succeeds, |
| 26662 | the returned list is searched, but if the lookup fails the behaviour is |
| 26663 | different in the two cases. The fail in the first statement causes the |
| 26664 | condition to be ignored, leaving no further conditions. The accept verb |
| 26665 | therefore succeeds. The second statement, however, generates an empty list when |
| 26666 | the lookup fails. No sender can match an empty list, so the condition fails, |
| 26667 | and therefore the accept also fails. |
| 26668 | |
| 26669 | ACL modifiers appear mixed in with conditions in ACL statements. Some of them |
| 26670 | specify actions that are taken as the conditions for a statement are checked; |
| 26671 | others specify text for messages that are used when access is denied or a |
| 26672 | warning is generated. The control modifier affects the way an incoming message |
| 26673 | is handled. |
| 26674 | |
| 26675 | The positioning of the modifiers in an ACL statement is important, because the |
| 26676 | processing of a verb ceases as soon as its outcome is known. Only those |
| 26677 | modifiers that have already been encountered will take effect. For example, |
| 26678 | consider this use of the message modifier: |
| 26679 | |
| 26680 | require message = Can't verify sender |
| 26681 | verify = sender |
| 26682 | message = Can't verify recipient |
| 26683 | verify = recipient |
| 26684 | message = This message cannot be used |
| 26685 | |
| 26686 | If sender verification fails, Exim knows that the result of the statement is |
| 26687 | "deny", so it goes no further. The first message modifier has been seen, so its |
| 26688 | text is used as the error message. If sender verification succeeds, but |
| 26689 | recipient verification fails, the second message is used. If recipient |
| 26690 | verification succeeds, the third message becomes "current", but is never used |
| 26691 | because there are no more conditions to cause failure. |
| 26692 | |
| 26693 | For the deny verb, on the other hand, it is always the last message modifier |
| 26694 | that is used, because all the conditions must be true for rejection to happen. |
| 26695 | Specifying more than one message modifier does not make sense, and the message |
| 26696 | can even be specified after all the conditions. For example: |
| 26697 | |
| 26698 | deny hosts = ... |
| 26699 | !senders = *@my.domain.example |
| 26700 | message = Invalid sender from client host |
| 26701 | |
| 26702 | The "deny" result does not happen until the end of the statement is reached, by |
| 26703 | which time Exim has set up the message. |
| 26704 | |
| 26705 | |
| 26706 | 43.21 ACL modifiers |
| 26707 | ------------------- |
| 26708 | |
| 26709 | The ACL modifiers are as follows: |
| 26710 | |
| 26711 | add_header = <text> |
| 26712 | |
| 26713 | This modifier specifies one or more header lines that are to be added to an |
| 26714 | incoming message, assuming, of course, that the message is ultimately |
| 26715 | accepted. For details, see section 43.24. |
| 26716 | |
| 26717 | continue = <text> |
| 26718 | |
| 26719 | This modifier does nothing of itself, and processing of the ACL always |
| 26720 | continues with the next condition or modifier. The value of continue is in |
| 26721 | the side effects of expanding its argument. Typically this could be used to |
| 26722 | update a database. It is really just a syntactic tidiness, to avoid having |
| 26723 | to write rather ugly lines like this: |
| 26724 | |
| 26725 | condition = ${if eq{0}{<some expansion>}{true}{true}} |
| 26726 | |
| 26727 | Instead, all you need is |
| 26728 | |
| 26729 | continue = <some expansion> |
| 26730 | |
| 26731 | control = <text> |
| 26732 | |
| 26733 | This modifier affects the subsequent processing of the SMTP connection or |
| 26734 | of an incoming message that is accepted. The effect of the first type of |
| 26735 | control lasts for the duration of the connection, whereas the effect of the |
| 26736 | second type lasts only until the current message has been received. The |
| 26737 | message-specific controls always apply to the whole message, not to |
| 26738 | individual recipients, even if the control modifier appears in a RCPT ACL. |
| 26739 | |
| 26740 | As there are now quite a few controls that can be applied, they are |
| 26741 | described separately in section 43.22. The control modifier can be used in |
| 26742 | several different ways. For example: |
| 26743 | |
| 26744 | + It can be at the end of an accept statement: |
| 26745 | |
| 26746 | accept ...some conditions |
| 26747 | control = queue_only |
| 26748 | |
| 26749 | In this case, the control is applied when this statement yields |
| 26750 | "accept", in other words, when the conditions are all true. |
| 26751 | |
| 26752 | + It can be in the middle of an accept statement: |
| 26753 | |
| 26754 | accept ...some conditions... |
| 26755 | control = queue_only |
| 26756 | ...some more conditions... |
| 26757 | |
| 26758 | If the first set of conditions are true, the control is applied, even |
| 26759 | if the statement does not accept because one of the second set of |
| 26760 | conditions is false. In this case, some subsequent statement must yield |
| 26761 | "accept" for the control to be relevant. |
| 26762 | |
| 26763 | + It can be used with warn to apply the control, leaving the decision |
| 26764 | about accepting or denying to a subsequent verb. For example: |
| 26765 | |
| 26766 | warn ...some conditions... |
| 26767 | control = freeze |
| 26768 | accept ... |
| 26769 | |
| 26770 | This example of warn does not contain message, log_message, or logwrite |
| 26771 | , so it does not add anything to the message and does not write a log |
| 26772 | entry. |
| 26773 | |
| 26774 | + If you want to apply a control unconditionally, you can use it with a |
| 26775 | require verb. For example: |
| 26776 | |
| 26777 | require control = no_multiline_responses |
| 26778 | |
| 26779 | delay = <time> |
| 26780 | |
| 26781 | This modifier may appear in any ACL except notquit. It causes Exim to wait |
| 26782 | for the time interval before proceeding. However, when testing Exim using |
| 26783 | the -bh option, the delay is not actually imposed (an appropriate message |
| 26784 | is output instead). The time is given in the usual Exim notation, and the |
| 26785 | delay happens as soon as the modifier is processed. In an SMTP session, |
| 26786 | pending output is flushed before the delay is imposed. |
| 26787 | |
| 26788 | Like control, delay can be used with accept or deny, for example: |
| 26789 | |
| 26790 | deny ...some conditions... |
| 26791 | delay = 30s |
| 26792 | |
| 26793 | The delay happens if all the conditions are true, before the statement |
| 26794 | returns "deny". Compare this with: |
| 26795 | |
| 26796 | deny delay = 30s |
| 26797 | ...some conditions... |
| 26798 | |
| 26799 | which waits for 30s before processing the conditions. The delay modifier |
| 26800 | can also be used with warn and together with control: |
| 26801 | |
| 26802 | warn ...some conditions... |
| 26803 | delay = 2m |
| 26804 | control = freeze |
| 26805 | accept ... |
| 26806 | |
| 26807 | If delay is encountered when the SMTP PIPELINING extension is in use, |
| 26808 | responses to several commands are no longer buffered and sent in one packet |
| 26809 | (as they would normally be) because all output is flushed before imposing |
| 26810 | the delay. This optimization is disabled so that a number of small delays |
| 26811 | do not appear to the client as one large aggregated delay that might |
| 26812 | provoke an unwanted timeout. You can, however, disable output flushing for |
| 26813 | delay by using a control modifier to set no_delay_flush. |
| 26814 | |
| 26815 | endpass |
| 26816 | |
| 26817 | This modifier, which has no argument, is recognized only in accept and |
| 26818 | discard statements. It marks the boundary between the conditions whose |
| 26819 | failure causes control to pass to the next statement, and the conditions |
| 26820 | whose failure causes the ACL to return "deny". This concept has proved to |
| 26821 | be confusing to some people, so the use of endpass is no longer recommended |
| 26822 | as "best practice". See the description of accept above for more details. |
| 26823 | |
| 26824 | log_message = <text> |
| 26825 | |
| 26826 | This modifier sets up a message that is used as part of the log message if |
| 26827 | the ACL denies access or a warn statement's conditions are true. For |
| 26828 | example: |
| 26829 | |
| 26830 | require log_message = wrong cipher suite $tls_in_cipher |
| 26831 | encrypted = DES-CBC3-SHA |
| 26832 | |
| 26833 | log_message is also used when recipients are discarded by discard. For |
| 26834 | example: |
| 26835 | |
| 26836 | discard <some conditions> |
| 26837 | log_message = Discarded $local_part@$domain because... |
| 26838 | |
| 26839 | When access is denied, log_message adds to any underlying error message |
| 26840 | that may exist because of a condition failure. For example, while verifying |
| 26841 | a recipient address, a :fail: redirection might have already set up a |
| 26842 | message. |
| 26843 | |
| 26844 | The message may be defined before the conditions to which it applies, |
| 26845 | because the string expansion does not happen until Exim decides that access |
| 26846 | is to be denied. This means that any variables that are set by the |
| 26847 | condition are available for inclusion in the message. For example, the |
| 26848 | $dnslist_<xxx> variables are set after a DNS black list lookup succeeds. If |
| 26849 | the expansion of log_message fails, or if the result is an empty string, |
| 26850 | the modifier is ignored. |
| 26851 | |
| 26852 | If you want to use a warn statement to log the result of an address |
| 26853 | verification, you can use $acl_verify_message to include the verification |
| 26854 | error message. |
| 26855 | |
| 26856 | If log_message is used with a warn statement, "Warning:" is added to the |
| 26857 | start of the logged message. If the same warning log message is requested |
| 26858 | more than once while receiving a single email message, only one copy is |
| 26859 | actually logged. If you want to log multiple copies, use logwrite instead |
| 26860 | of log_message. In the absence of log_message and logwrite, nothing is |
| 26861 | logged for a successful warn statement. |
| 26862 | |
| 26863 | If log_message is not present and there is no underlying error message (for |
| 26864 | example, from the failure of address verification), but message is present, |
| 26865 | the message text is used for logging rejections. However, if any text for |
| 26866 | logging contains newlines, only the first line is logged. In the absence of |
| 26867 | both log_message and message, a default built-in message is used for |
| 26868 | logging rejections. |
| 26869 | |
| 26870 | log_reject_target = <log name list> |
| 26871 | |
| 26872 | This modifier makes it possible to specify which logs are used for messages |
| 26873 | about ACL rejections. Its argument is a colon-separated list of words that |
| 26874 | can be "main", "reject", or "panic". The default is "main:reject". The list |
| 26875 | may be empty, in which case a rejection is not logged at all. For example, |
| 26876 | this ACL fragment writes no logging information when access is denied: |
| 26877 | |
| 26878 | deny <some conditions> |
| 26879 | log_reject_target = |
| 26880 | |
| 26881 | This modifier can be used in SMTP and non-SMTP ACLs. It applies to both |
| 26882 | permanent and temporary rejections. Its effect lasts for the rest of the |
| 26883 | current ACL. |
| 26884 | |
| 26885 | logwrite = <text> |
| 26886 | |
| 26887 | This modifier writes a message to a log file as soon as it is encountered |
| 26888 | when processing an ACL. (Compare log_message, which, except in the case of |
| 26889 | warn and discard, is used only if the ACL statement denies access.) The |
| 26890 | logwrite modifier can be used to log special incidents in ACLs. For |
| 26891 | example: |
| 26892 | |
| 26893 | accept <some special conditions> |
| 26894 | control = freeze |
| 26895 | logwrite = froze message because ... |
| 26896 | |
| 26897 | By default, the message is written to the main log. However, it may begin |
| 26898 | with a colon, followed by a comma-separated list of log names, and then |
| 26899 | another colon, to specify exactly which logs are to be written. For |
| 26900 | example: |
| 26901 | |
| 26902 | logwrite = :main,reject: text for main and reject logs |
| 26903 | logwrite = :panic: text for panic log only |
| 26904 | |
| 26905 | message = <text> |
| 26906 | |
| 26907 | This modifier sets up a text string that is expanded and used as a response |
| 26908 | message when an ACL statement terminates the ACL with an "accept", "deny", |
| 26909 | or "defer" response. (In the case of the accept and discard verbs, there is |
| 26910 | some complication if endpass is involved; see the description of accept for |
| 26911 | details.) |
| 26912 | |
| 26913 | The expansion of the message happens at the time Exim decides that the ACL |
| 26914 | is to end, not at the time it processes message. If the expansion fails, or |
| 26915 | generates an empty string, the modifier is ignored. Here is an example |
| 26916 | where message must be specified first, because the ACL ends with a |
| 26917 | rejection if the hosts condition fails: |
| 26918 | |
| 26919 | require message = Host not recognized |
| 26920 | hosts = 10.0.0.0/8 |
| 26921 | |
| 26922 | (Once a condition has failed, no further conditions or modifiers are |
| 26923 | processed.) |
| 26924 | |
| 26925 | For ACLs that are triggered by SMTP commands, the message is returned as |
| 26926 | part of the SMTP response. The use of message with accept (or discard) is |
| 26927 | meaningful only for SMTP, as no message is returned when a non-SMTP message |
| 26928 | is accepted. In the case of the connect ACL, accepting with a message |
| 26929 | modifier overrides the value of smtp_banner. For the EHLO/HELO ACL, a |
| 26930 | customized accept message may not contain more than one line (otherwise it |
| 26931 | will be truncated at the first newline and a panic logged), and it cannot |
| 26932 | affect the EHLO options. |
| 26933 | |
| 26934 | When SMTP is involved, the message may begin with an overriding response |
| 26935 | code, consisting of three digits optionally followed by an "extended |
| 26936 | response code" of the form n.n.n, each code being followed by a space. For |
| 26937 | example: |
| 26938 | |
| 26939 | deny message = 599 1.2.3 Host not welcome |
| 26940 | hosts = 192.168.34.0/24 |
| 26941 | |
| 26942 | The first digit of the supplied response code must be the same as would be |
| 26943 | sent by default. A panic occurs if it is not. Exim uses a 550 code when it |
| 26944 | denies access, but for the predata ACL, note that the default success code |
| 26945 | is 354, not 2xx. |
| 26946 | |
| 26947 | Notwithstanding the previous paragraph, for the QUIT ACL, unlike the |
| 26948 | others, the message modifier cannot override the 221 response code. |
| 26949 | |
| 26950 | The text in a message modifier is literal; any quotes are taken as |
| 26951 | literals, but because the string is expanded, backslash escapes are |
| 26952 | processed anyway. If the message contains newlines, this gives rise to a |
| 26953 | multi-line SMTP response. |
| 26954 | |
| 26955 | For ACLs that are called by an acl = ACL condition, the message is stored |
| 26956 | in $acl_verify_message, from which the calling ACL may use it. |
| 26957 | |
| 26958 | If message is used on a statement that verifies an address, the message |
| 26959 | specified overrides any message that is generated by the verification |
| 26960 | process. However, the original message is available in the variable |
| 26961 | $acl_verify_message, so you can incorporate it into your message if you |
| 26962 | wish. In particular, if you want the text from :fail: items in redirect |
| 26963 | routers to be passed back as part of the SMTP response, you should either |
| 26964 | not use a message modifier, or make use of $acl_verify_message. |
| 26965 | |
| 26966 | For compatibility with previous releases of Exim, a message modifier that |
| 26967 | is used with a warn verb behaves in a similar way to the add_header |
| 26968 | modifier, but this usage is now deprecated. However, message acts only when |
| 26969 | all the conditions are true, wherever it appears in an ACL command, whereas |
| 26970 | add_header acts as soon as it is encountered. If message is used with warn |
| 26971 | in an ACL that is not concerned with receiving a message, it has no effect. |
| 26972 | |
| 26973 | queue = <text> |
| 26974 | |
| 26975 | This modifier specifies the use of a named queue for spool files for the |
| 26976 | message. It can only be used before the message is received (i.e. not in |
| 26977 | the DATA ACL). This could be used, for example, for known high-volume burst |
| 26978 | sources of traffic, or for quarantine of messages. Separate queue-runner |
| 26979 | processes will be needed for named queues. If the text after expansion is |
| 26980 | empty, the default queue is used. |
| 26981 | |
| 26982 | remove_header = <text> |
| 26983 | |
| 26984 | This modifier specifies one or more header names in a colon-separated list |
| 26985 | that are to be removed from an incoming message, assuming, of course, that |
| 26986 | the message is ultimately accepted. For details, see section 43.25. |
| 26987 | |
| 26988 | set <acl_name> = <value> |
| 26989 | |
| 26990 | This modifier puts a value into one of the ACL variables (see section 43.19 |
| 26991 | ). |
| 26992 | |
| 26993 | udpsend = <parameters> |
| 26994 | |
| 26995 | This modifier sends a UDP packet, for purposes such as statistics |
| 26996 | collection or behaviour monitoring. The parameters are expanded, and the |
| 26997 | result of the expansion must be a colon-separated list consisting of a |
| 26998 | destination server, port number, and the packet contents. The server can be |
| 26999 | specified as a host name or IPv4 or IPv6 address. The separator can be |
| 27000 | changed with the usual angle bracket syntax. For example, you might want to |
| 27001 | collect information on which hosts connect when: |
| 27002 | |
| 27003 | udpsend = <; 2001:dB8::dead:beef ; 1234 ;\ |
| 27004 | $tod_zulu $sender_host_address |
| 27005 | |
| 27006 | |
| 27007 | 43.22 Use of the control modifier |
| 27008 | --------------------------------- |
| 27009 | |
| 27010 | The control modifier supports the following settings: |
| 27011 | |
| 27012 | control = allow_auth_unadvertised |
| 27013 | |
| 27014 | This modifier allows a client host to use the SMTP AUTH command even when |
| 27015 | it has not been advertised in response to EHLO. Furthermore, because there |
| 27016 | are apparently some really broken clients that do this, Exim will accept |
| 27017 | AUTH after HELO (rather than EHLO) when this control is set. It should be |
| 27018 | used only if you really need it, and you should limit its use to those |
| 27019 | broken clients that do not work without it. For example: |
| 27020 | |
| 27021 | warn hosts = 192.168.34.25 |
| 27022 | control = allow_auth_unadvertised |
| 27023 | |
| 27024 | Normally, when an Exim server receives an AUTH command, it checks the name |
| 27025 | of the authentication mechanism that is given in the command to ensure that |
| 27026 | it matches an advertised mechanism. When this control is set, the check |
| 27027 | that a mechanism has been advertised is bypassed. Any configured mechanism |
| 27028 | can be used by the client. This control is permitted only in the connection |
| 27029 | and HELO ACLs. |
| 27030 | |
| 27031 | control = caseful_local_part, control = caselower_local_part |
| 27032 | |
| 27033 | These two controls are permitted only in the ACL specified by acl_smtp_rcpt |
| 27034 | (that is, during RCPT processing). By default, the contents of $local_part |
| 27035 | are lower cased before ACL processing. If "caseful_local_part" is |
| 27036 | specified, any uppercase letters in the original local part are restored in |
| 27037 | $local_part for the rest of the ACL, or until a control that sets |
| 27038 | "caselower_local_part" is encountered. |
| 27039 | |
| 27040 | These controls affect only the current recipient. Moreover, they apply only |
| 27041 | to local part handling that takes place directly in the ACL (for example, |
| 27042 | as a key in lookups). If a test to verify the recipient is obeyed, the |
| 27043 | case-related handling of the local part during the verification is |
| 27044 | controlled by the router configuration (see the caseful_local_part generic |
| 27045 | router option). |
| 27046 | |
| 27047 | This facility could be used, for example, to add a spam score to local |
| 27048 | parts containing upper case letters. For example, using $acl_m4 to |
| 27049 | accumulate the spam score: |
| 27050 | |
| 27051 | warn control = caseful_local_part |
| 27052 | set acl_m4 = ${eval:\ |
| 27053 | $acl_m4 + \ |
| 27054 | ${if match{$local_part}{[A-Z]}{1}{0}}\ |
| 27055 | } |
| 27056 | control = caselower_local_part |
| 27057 | |
| 27058 | Notice that we put back the lower cased version afterwards, assuming that |
| 27059 | is what is wanted for subsequent tests. |
| 27060 | |
| 27061 | control = cutthrough_delivery/<options> |
| 27062 | |
| 27063 | This option requests delivery be attempted while the item is being |
| 27064 | received. |
| 27065 | |
| 27066 | The option is usable in the RCPT ACL. If enabled for a message received via |
| 27067 | smtp and routed to an smtp transport, and only one transport, interface, |
| 27068 | destination host and port combination is used for all recipients of the |
| 27069 | message, then the delivery connection is made while the receiving |
| 27070 | connection is open and data is copied from one to the other. |
| 27071 | |
| 27072 | An attempt to set this option for any recipient but the first for a mail |
| 27073 | will be quietly ignored. If a recipient-verify callout (with use_sender) |
| 27074 | connection is subsequently requested in the same ACL it is held open and |
| 27075 | used for any subsequent recipients and the data, otherwise one is made |
| 27076 | after the initial RCPT ACL completes. |
| 27077 | |
| 27078 | Note that routers are used in verify mode, and cannot depend on content of |
| 27079 | received headers. Note also that headers cannot be modified by any of the |
| 27080 | post-data ACLs (DATA, MIME and DKIM). Headers may be modified by routers |
| 27081 | (subject to the above) and transports. |
| 27082 | |
| 27083 | All the usual ACLs are called; if one results in the message being |
| 27084 | rejected, all effort spent in delivery (including the costs on the ultimate |
| 27085 | destination) will be wasted. Note that in the case of data-time ACLs this |
| 27086 | includes the entire message body. |
| 27087 | |
| 27088 | Cutthrough delivery is not supported via transport-filters or when DKIM |
| 27089 | signing of outgoing messages is done, because it sends data to the ultimate |
| 27090 | destination before the entire message has been received from the source. It |
| 27091 | is not supported for messages received with the SMTP PRDR |
| 27092 | |
| 27093 | or CHUNKING |
| 27094 | |
| 27095 | options in use. |
| 27096 | |
| 27097 | Should the ultimate destination system positively accept or reject the |
| 27098 | mail, a corresponding indication is given to the source system and nothing |
| 27099 | is queued. If the item is successfully delivered in cutthrough mode the |
| 27100 | delivery log lines are tagged with ">>" rather than "=>" and appear before |
| 27101 | the acceptance "<=" line. |
| 27102 | |
| 27103 | If there is a temporary error the item is queued for later delivery in the |
| 27104 | usual fashion. This behaviour can be adjusted by appending the option defer |
| 27105 | =<value> to the control; the default value is "spool" and the alternate |
| 27106 | value "pass" copies an SMTP defer response from the target back to the |
| 27107 | initiator and does not queue the message. Note that this is independent of |
| 27108 | any recipient verify conditions in the ACL. |
| 27109 | |
| 27110 | Delivery in this mode avoids the generation of a bounce mail to a (possibly |
| 27111 | faked) sender when the destination system is doing content-scan based |
| 27112 | rejection. |
| 27113 | |
| 27114 | control = debug/<options> |
| 27115 | |
| 27116 | This control turns on debug logging, almost as though Exim had been invoked |
| 27117 | with "-d", with the output going to a new logfile, by default called |
| 27118 | debuglog. The filename can be adjusted with the tag option, which may |
| 27119 | access any variables already defined. The logging may be adjusted with the |
| 27120 | opts option, which takes the same values as the "-d" command-line option. |
| 27121 | Logging may be stopped, and the file removed, with the kill option. Some |
| 27122 | examples (which depend on variables that don't exist in all contexts): |
| 27123 | |
| 27124 | control = debug |
| 27125 | control = debug/tag=.$sender_host_address |
| 27126 | control = debug/opts=+expand+acl |
| 27127 | control = debug/tag=.$message_exim_id/opts=+expand |
| 27128 | control = debug/kill |
| 27129 | |
| 27130 | control = dkim_disable_verify |
| 27131 | |
| 27132 | This control turns off DKIM verification processing entirely. For details |
| 27133 | on the operation and configuration of DKIM, see chapter 57. |
| 27134 | |
| 27135 | control = dscp/<value> |
| 27136 | |
| 27137 | This option causes the DSCP value associated with the socket for the |
| 27138 | inbound connection to be adjusted to a given value, given as one of a |
| 27139 | number of fixed strings or to numeric value. The -bI:dscp option may be |
| 27140 | used to ask Exim which names it knows of. Common values include |
| 27141 | "throughput", "mincost", and on newer systems "ef", "af41", etc. Numeric |
| 27142 | values may be in the range 0 to 0x3F. |
| 27143 | |
| 27144 | The outbound packets from Exim will be marked with this value in the header |
| 27145 | (for IPv4, the TOS field; for IPv6, the TCLASS field); there is no |
| 27146 | guarantee that these values will have any effect, not be stripped by |
| 27147 | networking equipment, or do much of anything without cooperation with your |
| 27148 | Network Engineer and those of all network operators between the source and |
| 27149 | destination. |
| 27150 | |
| 27151 | control = enforce_sync, control = no_enforce_sync |
| 27152 | |
| 27153 | These controls make it possible to be selective about when SMTP |
| 27154 | synchronization is enforced. The global option smtp_enforce_sync specifies |
| 27155 | the initial state of the switch (it is true by default). See the |
| 27156 | description of this option in chapter 14 for details of SMTP |
| 27157 | synchronization checking. |
| 27158 | |
| 27159 | The effect of these two controls lasts for the remainder of the SMTP |
| 27160 | connection. They can appear in any ACL except the one for the non-SMTP |
| 27161 | messages. The most straightforward place to put them is in the ACL defined |
| 27162 | by acl_smtp_connect, which is run at the start of an incoming SMTP |
| 27163 | connection, before the first synchronization check. The expected use is to |
| 27164 | turn off the synchronization checks for badly-behaved hosts that you |
| 27165 | nevertheless need to work with. |
| 27166 | |
| 27167 | control = fakedefer/<message> |
| 27168 | |
| 27169 | This control works in exactly the same way as fakereject (described below) |
| 27170 | except that it causes an SMTP 450 response after the message data instead |
| 27171 | of a 550 response. You must take care when using fakedefer because it |
| 27172 | causes the messages to be duplicated when the sender retries. Therefore, |
| 27173 | you should not use fakedefer if the message is to be delivered normally. |
| 27174 | |
| 27175 | control = fakereject/<message> |
| 27176 | |
| 27177 | This control is permitted only for the MAIL, RCPT, and DATA ACLs, in other |
| 27178 | words, only when an SMTP message is being received. If Exim accepts the |
| 27179 | message, instead the final 250 response, a 550 rejection message is sent. |
| 27180 | However, Exim proceeds to deliver the message as normal. The control |
| 27181 | applies only to the current message, not to any subsequent ones that may be |
| 27182 | received in the same SMTP connection. |
| 27183 | |
| 27184 | The text for the 550 response is taken from the control modifier. If no |
| 27185 | message is supplied, the following is used: |
| 27186 | |
| 27187 | 550-Your message has been rejected but is being |
| 27188 | 550-kept for evaluation. |
| 27189 | 550-If it was a legitimate message, it may still be |
| 27190 | 550 delivered to the target recipient(s). |
| 27191 | |
| 27192 | This facility should be used with extreme caution. |
| 27193 | |
| 27194 | control = freeze |
| 27195 | |
| 27196 | This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, |
| 27197 | in other words, only when a message is being received. If the message is |
| 27198 | accepted, it is placed on Exim's queue and frozen. The control applies only |
| 27199 | to the current message, not to any subsequent ones that may be received in |
| 27200 | the same SMTP connection. |
| 27201 | |
| 27202 | This modifier can optionally be followed by "/no_tell". If the global |
| 27203 | option freeze_tell is set, it is ignored for the current message (that is, |
| 27204 | nobody is told about the freezing), provided all the control=freeze |
| 27205 | modifiers that are obeyed for the current message have the "/no_tell" |
| 27206 | option. |
| 27207 | |
| 27208 | control = no_delay_flush |
| 27209 | |
| 27210 | Exim normally flushes SMTP output before implementing a delay in an ACL, to |
| 27211 | avoid unexpected timeouts in clients when the SMTP PIPELINING extension is |
| 27212 | in use. This control, as long as it is encountered before the delay |
| 27213 | modifier, disables such output flushing. |
| 27214 | |
| 27215 | control = no_callout_flush |
| 27216 | |
| 27217 | Exim normally flushes SMTP output before performing a callout in an ACL, to |
| 27218 | avoid unexpected timeouts in clients when the SMTP PIPELINING extension is |
| 27219 | in use. This control, as long as it is encountered before the verify |
| 27220 | condition that causes the callout, disables such output flushing. |
| 27221 | |
| 27222 | control = no_mbox_unspool |
| 27223 | |
| 27224 | This control is available when Exim is compiled with the content scanning |
| 27225 | extension. Content scanning may require a copy of the current message, or |
| 27226 | parts of it, to be written in "mbox format" to a spool file, for passing to |
| 27227 | a virus or spam scanner. Normally, such copies are deleted when they are no |
| 27228 | longer needed. If this control is set, the copies are not deleted. The |
| 27229 | control applies only to the current message, not to any subsequent ones |
| 27230 | that may be received in the same SMTP connection. It is provided for |
| 27231 | debugging purposes and is unlikely to be useful in production. |
| 27232 | |
| 27233 | control = no_multiline_responses |
| 27234 | |
| 27235 | This control is permitted for any ACL except the one for non-SMTP messages. |
| 27236 | It seems that there are broken clients in use that cannot handle multiline |
| 27237 | SMTP responses, despite the fact that RFC 821 defined them over 20 years |
| 27238 | ago. |
| 27239 | |
| 27240 | If this control is set, multiline SMTP responses from ACL rejections are |
| 27241 | suppressed. One way of doing this would have been to put out these |
| 27242 | responses as one long line. However, RFC 2821 specifies a maximum of 512 |
| 27243 | bytes per response ("use multiline responses for more" it says - ha!), and |
| 27244 | some of the responses might get close to that. So this facility, which is |
| 27245 | after all only a sop to broken clients, is implemented by doing two very |
| 27246 | easy things: |
| 27247 | |
| 27248 | + Extra information that is normally output as part of a rejection caused |
| 27249 | by sender verification failure is omitted. Only the final line |
| 27250 | (typically "sender verification failed") is sent. |
| 27251 | |
| 27252 | + If a message modifier supplies a multiline response, only the first |
| 27253 | line is output. |
| 27254 | |
| 27255 | The setting of the switch can, of course, be made conditional on the |
| 27256 | calling host. Its effect lasts until the end of the SMTP connection. |
| 27257 | |
| 27258 | control = no_pipelining |
| 27259 | |
| 27260 | This control turns off the advertising of the PIPELINING extension to SMTP |
| 27261 | in the current session. To be useful, it must be obeyed before Exim sends |
| 27262 | its response to an EHLO command. Therefore, it should normally appear in an |
| 27263 | ACL controlled by acl_smtp_connect or acl_smtp_helo. See also |
| 27264 | pipelining_advertise_hosts. |
| 27265 | |
| 27266 | control = queue_only |
| 27267 | |
| 27268 | This control is permitted only for the MAIL, RCPT, DATA, and non-SMTP ACLs, |
| 27269 | in other words, only when a message is being received. If the message is |
| 27270 | accepted, it is placed on Exim's queue and left there for delivery by a |
| 27271 | subsequent queue runner. No immediate delivery process is started. In other |
| 27272 | words, it has the effect as the queue_only global option. However, the |
| 27273 | control applies only to the current message, not to any subsequent ones |
| 27274 | that may be received in the same SMTP connection. |
| 27275 | |
| 27276 | control = submission/<options> |
| 27277 | |
| 27278 | This control is permitted only for the MAIL, RCPT, and start of data ACLs |
| 27279 | (the latter is the one defined by acl_smtp_predata). Setting it tells Exim |
| 27280 | that the current message is a submission from a local MUA. In this case, |
| 27281 | Exim operates in "submission mode", and applies certain fixups to the |
| 27282 | message if necessary. For example, it adds a Date: header line if one is |
| 27283 | not present. This control is not permitted in the acl_smtp_data ACL, |
| 27284 | because that is too late (the message has already been created). |
| 27285 | |
| 27286 | Chapter 47 describes the processing that Exim applies to messages. Section |
| 27287 | 47.1 covers the processing that happens in submission mode; the available |
| 27288 | options for this control are described there. The control applies only to |
| 27289 | the current message, not to any subsequent ones that may be received in the |
| 27290 | same SMTP connection. |
| 27291 | |
| 27292 | control = suppress_local_fixups |
| 27293 | |
| 27294 | This control applies to locally submitted (non TCP/IP) messages, and is the |
| 27295 | complement of "control = submission". It disables the fixups that are |
| 27296 | normally applied to locally-submitted messages. Specifically: |
| 27297 | |
| 27298 | + Any Sender: header line is left alone (in this respect, it is a dynamic |
| 27299 | version of local_sender_retain). |
| 27300 | |
| 27301 | + No Message-ID:, From:, or Date: header lines are added. |
| 27302 | |
| 27303 | + There is no check that From: corresponds to the actual sender. |
| 27304 | |
| 27305 | This control may be useful when a remotely-originated message is accepted, |
| 27306 | passed to some scanning program, and then re-submitted for delivery. It can |
| 27307 | be used only in the acl_smtp_mail, acl_smtp_rcpt, acl_smtp_predata, and |
| 27308 | acl_not_smtp_start ACLs, because it has to be set before the message's data |
| 27309 | is read. |
| 27310 | |
| 27311 | Note: This control applies only to the current message, not to any others |
| 27312 | that are being submitted at the same time using -bs or -bS. |
| 27313 | |
| 27314 | control = utf8_downconvert |
| 27315 | |
| 27316 | This control enables conversion of UTF-8 in message addresses to a-label |
| 27317 | form. For details see section 59.1. |
| 27318 | |
| 27319 | |
| 27320 | 43.23 Summary of message fixup control |
| 27321 | -------------------------------------- |
| 27322 | |
| 27323 | All four possibilities for message fixups can be specified: |
| 27324 | |
| 27325 | * Locally submitted, fixups applied: the default. |
| 27326 | |
| 27327 | * Locally submitted, no fixups applied: use "control = |
| 27328 | suppress_local_fixups". |
| 27329 | |
| 27330 | * Remotely submitted, no fixups applied: the default. |
| 27331 | |
| 27332 | * Remotely submitted, fixups applied: use "control = submission". |
| 27333 | |
| 27334 | |
| 27335 | 43.24 Adding header lines in ACLs |
| 27336 | --------------------------------- |
| 27337 | |
| 27338 | The add_header modifier can be used to add one or more extra header lines to an |
| 27339 | incoming message, as in this example: |
| 27340 | |
| 27341 | warn dnslists = sbl.spamhaus.org : \ |
| 27342 | dialup.mail-abuse.org |
| 27343 | add_header = X-blacklisted-at: $dnslist_domain |
| 27344 | |
| 27345 | The add_header modifier is permitted in the MAIL, RCPT, PREDATA, DATA, MIME, |
| 27346 | DKIM, and non-SMTP ACLs (in other words, those that are concerned with |
| 27347 | receiving a message). The message must ultimately be accepted for add_header to |
| 27348 | have any significant effect. You can use add_header with any ACL verb, |
| 27349 | including deny (though this is potentially useful only in a RCPT ACL). |
| 27350 | |
| 27351 | Headers will not be added to the message if the modifier is used in DATA, MIME |
| 27352 | or DKIM ACLs for a message delivered by cutthrough routing. |
| 27353 | |
| 27354 | Leading and trailing newlines are removed from the data for the add_header |
| 27355 | modifier; if it then contains one or more newlines that are not followed by a |
| 27356 | space or a tab, it is assumed to contain multiple header lines. Each one is |
| 27357 | checked for valid syntax; "X-ACL-Warn:" is added to the front of any line that |
| 27358 | is not a valid header line. |
| 27359 | |
| 27360 | Added header lines are accumulated during the MAIL, RCPT, and predata ACLs. |
| 27361 | They are added to the message before processing the DATA and MIME ACLs. |
| 27362 | However, if an identical header line is requested more than once, only one copy |
| 27363 | is actually added to the message. Further header lines may be accumulated |
| 27364 | during the DATA and MIME ACLs, after which they are added to the message, again |
| 27365 | with duplicates suppressed. Thus, it is possible to add two identical header |
| 27366 | lines to an SMTP message, but only if one is added before DATA and one after. |
| 27367 | In the case of non-SMTP messages, new headers are accumulated during the |
| 27368 | non-SMTP ACLs, and are added to the message after all the ACLs have run. If a |
| 27369 | message is rejected after DATA or by the non-SMTP ACL, all added header lines |
| 27370 | are included in the entry that is written to the reject log. |
| 27371 | |
| 27372 | Header lines are not visible in string expansions of message headers until they |
| 27373 | are added to the message. It follows that header lines defined in the MAIL, |
| 27374 | RCPT, and predata ACLs are not visible until the DATA ACL and MIME ACLs are |
| 27375 | run. Similarly, header lines that are added by the DATA or MIME ACLs are not |
| 27376 | visible in those ACLs. Because of this restriction, you cannot use header lines |
| 27377 | as a way of passing data between (for example) the MAIL and RCPT ACLs. If you |
| 27378 | want to do this, you can use ACL variables, as described in section 43.19. |
| 27379 | |
| 27380 | The list of headers yet to be added is given by the $headers_added variable. |
| 27381 | |
| 27382 | The add_header modifier acts immediately as it is encountered during the |
| 27383 | processing of an ACL. Notice the difference between these two cases: |
| 27384 | |
| 27385 | accept add_header = ADDED: some text |
| 27386 | <some condition> |
| 27387 | |
| 27388 | accept <some condition> |
| 27389 | add_header = ADDED: some text |
| 27390 | |
| 27391 | In the first case, the header line is always added, whether or not the |
| 27392 | condition is true. In the second case, the header line is added only if the |
| 27393 | condition is true. Multiple occurrences of add_header may occur in the same ACL |
| 27394 | statement. All those that are encountered before a condition fails are |
| 27395 | honoured. |
| 27396 | |
| 27397 | For compatibility with previous versions of Exim, a message modifier for a warn |
| 27398 | verb acts in the same way as add_header, except that it takes effect only if |
| 27399 | all the conditions are true, even if it appears before some of them. |
| 27400 | Furthermore, only the last occurrence of message is honoured. This usage of |
| 27401 | message is now deprecated. If both add_header and message are present on a warn |
| 27402 | verb, both are processed according to their specifications. |
| 27403 | |
| 27404 | By default, new header lines are added to a message at the end of the existing |
| 27405 | header lines. However, you can specify that any particular header line should |
| 27406 | be added right at the start (before all the Received: lines), immediately after |
| 27407 | the first block of Received: lines, or immediately before any line that is not |
| 27408 | a Received: or Resent-something: header. |
| 27409 | |
| 27410 | This is done by specifying ":at_start:", ":after_received:", or |
| 27411 | ":at_start_rfc:" (or, for completeness, ":at_end:") before the text of the |
| 27412 | header line, respectively. (Header text cannot start with a colon, as there has |
| 27413 | to be a header name first.) For example: |
| 27414 | |
| 27415 | warn add_header = \ |
| 27416 | :after_received:X-My-Header: something or other... |
| 27417 | |
| 27418 | If more than one header line is supplied in a single add_header modifier, each |
| 27419 | one is treated independently and can therefore be placed differently. If you |
| 27420 | add more than one line at the start, or after the Received: block, they end up |
| 27421 | in reverse order. |
| 27422 | |
| 27423 | Warning: This facility currently applies only to header lines that are added in |
| 27424 | an ACL. It does NOT work for header lines that are added in a system filter or |
| 27425 | in a router or transport. |
| 27426 | |
| 27427 | |
| 27428 | 43.25 Removing header lines in ACLs |
| 27429 | ----------------------------------- |
| 27430 | |
| 27431 | The remove_header modifier can be used to remove one or more header lines from |
| 27432 | an incoming message, as in this example: |
| 27433 | |
| 27434 | warn message = Remove internal headers |
| 27435 | remove_header = x-route-mail1 : x-route-mail2 |
| 27436 | |
| 27437 | The remove_header modifier is permitted in the MAIL, RCPT, PREDATA, DATA, MIME, |
| 27438 | DKIM, and non-SMTP ACLs (in other words, those that are concerned with |
| 27439 | receiving a message). The message must ultimately be accepted for remove_header |
| 27440 | to have any significant effect. You can use remove_header with any ACL verb, |
| 27441 | including deny, though this is really not useful for any verb that doesn't |
| 27442 | result in a delivered message. |
| 27443 | |
| 27444 | Headers will not be removed from the message if the modifier is used in DATA, |
| 27445 | MIME or DKIM ACLs for a message delivered by cutthrough routing. |
| 27446 | |
| 27447 | More than one header can be removed at the same time by using a colon separated |
| 27448 | list of header names. The header matching is case insensitive. Wildcards are |
| 27449 | not permitted, nor is list expansion performed, so you cannot use hostlists to |
| 27450 | create a list of headers, however both connection and message variable |
| 27451 | expansion are performed ($acl_c_* and $acl_m_*), illustrated in this example: |
| 27452 | |
| 27453 | warn hosts = +internal_hosts |
| 27454 | set acl_c_ihdrs = x-route-mail1 : x-route-mail2 |
| 27455 | warn message = Remove internal headers |
| 27456 | remove_header = $acl_c_ihdrs |
| 27457 | |
| 27458 | Removed header lines are accumulated during the MAIL, RCPT, and predata ACLs. |
| 27459 | They are removed from the message before processing the DATA and MIME ACLs. |
| 27460 | There is no harm in attempting to remove the same header twice nor is removing |
| 27461 | a non-existent header. Further header lines to be removed may be accumulated |
| 27462 | during the DATA and MIME ACLs, after which they are removed from the message, |
| 27463 | if present. In the case of non-SMTP messages, headers to be removed are |
| 27464 | accumulated during the non-SMTP ACLs, and are removed from the message after |
| 27465 | all the ACLs have run. If a message is rejected after DATA or by the non-SMTP |
| 27466 | ACL, there really is no effect because there is no logging of what headers |
| 27467 | would have been removed. |
| 27468 | |
| 27469 | Header lines are not visible in string expansions until the DATA phase when it |
| 27470 | is received. Any header lines removed in the MAIL, RCPT, and predata ACLs are |
| 27471 | not visible in the DATA ACL and MIME ACLs. Similarly, header lines that are |
| 27472 | removed by the DATA or MIME ACLs are still visible in those ACLs. Because of |
| 27473 | this restriction, you cannot use header lines as a way of controlling data |
| 27474 | passed between (for example) the MAIL and RCPT ACLs. If you want to do this, |
| 27475 | you should instead use ACL variables, as described in section 43.19. |
| 27476 | |
| 27477 | The remove_header modifier acts immediately as it is encountered during the |
| 27478 | processing of an ACL. Notice the difference between these two cases: |
| 27479 | |
| 27480 | accept remove_header = X-Internal |
| 27481 | <some condition> |
| 27482 | |
| 27483 | accept <some condition> |
| 27484 | remove_header = X-Internal |
| 27485 | |
| 27486 | In the first case, the header line is always removed, whether or not the |
| 27487 | condition is true. In the second case, the header line is removed only if the |
| 27488 | condition is true. Multiple occurrences of remove_header may occur in the same |
| 27489 | ACL statement. All those that are encountered before a condition fails are |
| 27490 | honoured. |
| 27491 | |
| 27492 | Warning: This facility currently applies only to header lines that are present |
| 27493 | during ACL processing. It does NOT remove header lines that are added in a |
| 27494 | system filter or in a router or transport. |
| 27495 | |
| 27496 | |
| 27497 | 43.26 ACL conditions |
| 27498 | -------------------- |
| 27499 | |
| 27500 | Some of the conditions listed in this section are available only when Exim is |
| 27501 | compiled with the content-scanning extension. They are included here briefly |
| 27502 | for completeness. More detailed descriptions can be found in the discussion on |
| 27503 | content scanning in chapter 44. |
| 27504 | |
| 27505 | Not all conditions are relevant in all circumstances. For example, testing |
| 27506 | senders and recipients does not make sense in an ACL that is being run as the |
| 27507 | result of the arrival of an ETRN command, and checks on message headers can be |
| 27508 | done only in the ACLs specified by acl_smtp_data and acl_not_smtp. You can use |
| 27509 | the same condition (with different parameters) more than once in the same ACL |
| 27510 | statement. This provides a way of specifying an "and" conjunction. The |
| 27511 | conditions are as follows: |
| 27512 | |
| 27513 | acl = <name of acl or ACL string or file name > |
| 27514 | |
| 27515 | The possible values of the argument are the same as for the acl_smtp_xxx |
| 27516 | options. The named or inline ACL is run. If it returns "accept" the |
| 27517 | condition is true; if it returns "deny" the condition is false. If it |
| 27518 | returns "defer", the current ACL returns "defer" unless the condition is on |
| 27519 | a warn verb. In that case, a "defer" return makes the condition false. This |
| 27520 | means that further processing of the warn verb ceases, but processing of |
| 27521 | the ACL continues. |
| 27522 | |
| 27523 | If the argument is a named ACL, up to nine space-separated optional values |
| 27524 | can be appended; they appear within the called ACL in $acl_arg1 to |
| 27525 | $acl_arg9, and $acl_narg is set to the count of values. Previous values of |
| 27526 | these variables are restored after the call returns. The name and values |
| 27527 | are expanded separately. Note that spaces in complex expansions which are |
| 27528 | used as arguments will act as argument separators. |
| 27529 | |
| 27530 | If the nested acl returns "drop" and the outer condition denies access, the |
| 27531 | connection is dropped. If it returns "discard", the verb must be accept or |
| 27532 | discard, and the action is taken immediately - no further conditions are |
| 27533 | tested. |
| 27534 | |
| 27535 | ACLs may be nested up to 20 deep; the limit exists purely to catch runaway |
| 27536 | loops. This condition allows you to use different ACLs in different |
| 27537 | circumstances. For example, different ACLs can be used to handle RCPT |
| 27538 | commands for different local users or different local domains. |
| 27539 | |
| 27540 | authenticated = <string list> |
| 27541 | |
| 27542 | If the SMTP connection is not authenticated, the condition is false. |
| 27543 | Otherwise, the name of the authenticator is tested against the list. To |
| 27544 | test for authentication by any authenticator, you can set |
| 27545 | |
| 27546 | authenticated = * |
| 27547 | |
| 27548 | condition = <string> |
| 27549 | |
| 27550 | This feature allows you to make up custom conditions. If the result of |
| 27551 | expanding the string is an empty string, the number zero, or one of the |
| 27552 | strings "no" or "false", the condition is false. If the result is any |
| 27553 | non-zero number, or one of the strings "yes" or "true", the condition is |
| 27554 | true. For any other value, some error is assumed to have occurred, and the |
| 27555 | ACL returns "defer". However, if the expansion is forced to fail, the |
| 27556 | condition is ignored. The effect is to treat it as true, whether it is |
| 27557 | positive or negative. |
| 27558 | |
| 27559 | decode = <location> |
| 27560 | |
| 27561 | This condition is available only when Exim is compiled with the |
| 27562 | content-scanning extension, and it is allowed only in the ACL defined by |
| 27563 | acl_smtp_mime. It causes the current MIME part to be decoded into a file. |
| 27564 | If all goes well, the condition is true. It is false only if there are |
| 27565 | problems such as a syntax error or a memory shortage. For more details, see |
| 27566 | chapter 44. |
| 27567 | |
| 27568 | dnslists = <list of domain names and other data> |
| 27569 | |
| 27570 | This condition checks for entries in DNS black lists. These are also known |
| 27571 | as "RBL lists", after the original Realtime Blackhole List, but note that |
| 27572 | the use of the lists at mail-abuse.org now carries a charge. There are too |
| 27573 | many different variants of this condition to describe briefly here. See |
| 27574 | sections 43.27-43.37 for details. |
| 27575 | |
| 27576 | domains = <domain list> |
| 27577 | |
| 27578 | This condition is relevant only after a RCPT command. It checks that the |
| 27579 | domain of the recipient address is in the domain list. If percent-hack |
| 27580 | processing is enabled, it is done before this test is done. If the check |
| 27581 | succeeds with a lookup, the result of the lookup is placed in $domain_data |
| 27582 | until the next domains test. |
| 27583 | |
| 27584 | Note carefully (because many people seem to fall foul of this): you cannot |
| 27585 | use domains in a DATA ACL. |
| 27586 | |
| 27587 | encrypted = <string list> |
| 27588 | |
| 27589 | If the SMTP connection is not encrypted, the condition is false. Otherwise, |
| 27590 | the name of the cipher suite in use is tested against the list. To test for |
| 27591 | encryption without testing for any specific cipher suite(s), set |
| 27592 | |
| 27593 | encrypted = * |
| 27594 | |
| 27595 | hosts = <host list> |
| 27596 | |
| 27597 | This condition tests that the calling host matches the host list. If you |
| 27598 | have name lookups or wildcarded host names and IP addresses in the same |
| 27599 | host list, you should normally put the IP addresses first. For example, you |
| 27600 | could have: |
| 27601 | |
| 27602 | accept hosts = 10.9.8.7 : dbm;/etc/friendly/hosts |
| 27603 | |
| 27604 | The lookup in this example uses the host name for its key. This is implied |
| 27605 | by the lookup type "dbm". (For a host address lookup you would use |
| 27606 | "net-dbm" and it wouldn't matter which way round you had these two items.) |
| 27607 | |
| 27608 | The reason for the problem with host names lies in the left-to-right way |
| 27609 | that Exim processes lists. It can test IP addresses without doing any DNS |
| 27610 | lookups, but when it reaches an item that requires a host name, it fails if |
| 27611 | it cannot find a host name to compare with the pattern. If the above list |
| 27612 | is given in the opposite order, the accept statement fails for a host whose |
| 27613 | name cannot be found, even if its IP address is 10.9.8.7. |
| 27614 | |
| 27615 | If you really do want to do the name check first, and still recognize the |
| 27616 | IP address even if the name lookup fails, you can rewrite the ACL like |
| 27617 | this: |
| 27618 | |
| 27619 | accept hosts = dbm;/etc/friendly/hosts |
| 27620 | accept hosts = 10.9.8.7 |
| 27621 | |
| 27622 | The default action on failing to find the host name is to assume that the |
| 27623 | host is not in the list, so the first accept statement fails. The second |
| 27624 | statement can then check the IP address. |
| 27625 | |
| 27626 | If a hosts condition is satisfied by means of a lookup, the result of the |
| 27627 | lookup is made available in the $host_data variable. This allows you, for |
| 27628 | example, to set up a statement like this: |
| 27629 | |
| 27630 | deny hosts = net-lsearch;/some/file |
| 27631 | message = $host_data |
| 27632 | |
| 27633 | which gives a custom error message for each denied host. |
| 27634 | |
| 27635 | local_parts = <local part list> |
| 27636 | |
| 27637 | This condition is relevant only after a RCPT command. It checks that the |
| 27638 | local part of the recipient address is in the list. If percent-hack |
| 27639 | processing is enabled, it is done before this test. If the check succeeds |
| 27640 | with a lookup, the result of the lookup is placed in $local_part_data, |
| 27641 | which remains set until the next local_parts test. |
| 27642 | |
| 27643 | malware = <option> |
| 27644 | |
| 27645 | This condition is available only when Exim is compiled with the |
| 27646 | content-scanning extension. It causes the incoming message to be scanned |
| 27647 | for viruses. For details, see chapter 44. |
| 27648 | |
| 27649 | mime_regex = <list of regular expressions> |
| 27650 | |
| 27651 | This condition is available only when Exim is compiled with the |
| 27652 | content-scanning extension, and it is allowed only in the ACL defined by |
| 27653 | acl_smtp_mime. It causes the current MIME part to be scanned for a match |
| 27654 | with any of the regular expressions. For details, see chapter 44. |
| 27655 | |
| 27656 | ratelimit = <parameters> |
| 27657 | |
| 27658 | This condition can be used to limit the rate at which a user or host |
| 27659 | submits messages. Details are given in section 43.38. |
| 27660 | |
| 27661 | recipients = <address list> |
| 27662 | |
| 27663 | This condition is relevant only after a RCPT command. It checks the entire |
| 27664 | recipient address against a list of recipients. |
| 27665 | |
| 27666 | regex = <list of regular expressions> |
| 27667 | |
| 27668 | This condition is available only when Exim is compiled with the |
| 27669 | content-scanning extension, and is available only in the DATA, MIME, and |
| 27670 | non-SMTP ACLs. It causes the incoming message to be scanned for a match |
| 27671 | with any of the regular expressions. For details, see chapter 44. |
| 27672 | |
| 27673 | sender_domains = <domain list> |
| 27674 | |
| 27675 | This condition tests the domain of the sender of the message against the |
| 27676 | given domain list. Note: The domain of the sender address is in |
| 27677 | $sender_address_domain. It is not put in $domain during the testing of this |
| 27678 | condition. This is an exception to the general rule for testing domain |
| 27679 | lists. It is done this way so that, if this condition is used in an ACL for |
| 27680 | a RCPT command, the recipient's domain (which is in $domain) can be used to |
| 27681 | influence the sender checking. |
| 27682 | |
| 27683 | Warning: It is a bad idea to use this condition on its own as a control on |
| 27684 | relaying, because sender addresses are easily, and commonly, forged. |
| 27685 | |
| 27686 | senders = <address list> |
| 27687 | |
| 27688 | This condition tests the sender of the message against the given list. To |
| 27689 | test for a bounce message, which has an empty sender, set |
| 27690 | |
| 27691 | senders = : |
| 27692 | |
| 27693 | Warning: It is a bad idea to use this condition on its own as a control on |
| 27694 | relaying, because sender addresses are easily, and commonly, forged. |
| 27695 | |
| 27696 | spam = <username> |
| 27697 | |
| 27698 | This condition is available only when Exim is compiled with the |
| 27699 | content-scanning extension. It causes the incoming message to be scanned by |
| 27700 | SpamAssassin. For details, see chapter 44. |
| 27701 | |
| 27702 | verify = certificate |
| 27703 | |
| 27704 | This condition is true in an SMTP session if the session is encrypted, and |
| 27705 | a certificate was received from the client, and the certificate was |
| 27706 | verified. The server requests a certificate only if the client matches |
| 27707 | tls_verify_hosts or tls_try_verify_hosts (see chapter 42). |
| 27708 | |
| 27709 | verify = csa |
| 27710 | |
| 27711 | This condition checks whether the sending host (the client) is authorized |
| 27712 | to send email. Details of how this works are given in section 43.50. |
| 27713 | |
| 27714 | verify = header_names_ascii |
| 27715 | |
| 27716 | This condition is relevant only in an ACL that is run after a message has |
| 27717 | been received, that is, in an ACL specified by acl_smtp_data or |
| 27718 | acl_not_smtp. It checks all header names (not the content) to make sure |
| 27719 | there are no non-ASCII characters, also excluding control characters. The |
| 27720 | allowable characters are decimal ASCII values 33 through 126. |
| 27721 | |
| 27722 | Exim itself will handle headers with non-ASCII characters, but it can cause |
| 27723 | problems for downstream applications, so this option will allow their |
| 27724 | detection and rejection in the DATA ACL's. |
| 27725 | |
| 27726 | verify = header_sender/<options> |
| 27727 | |
| 27728 | This condition is relevant only in an ACL that is run after a message has |
| 27729 | been received, that is, in an ACL specified by acl_smtp_data or |
| 27730 | acl_not_smtp. It checks that there is a verifiable address in at least one |
| 27731 | of the Sender:, Reply-To:, or From: header lines. Such an address is |
| 27732 | loosely thought of as a "sender" address (hence the name of the test). |
| 27733 | However, an address that appears in one of these headers need not be an |
| 27734 | address that accepts bounce messages; only sender addresses in envelopes |
| 27735 | are required to accept bounces. Therefore, if you use the callout option on |
| 27736 | this check, you might want to arrange for a non-empty address in the MAIL |
| 27737 | command. |
| 27738 | |
| 27739 | Details of address verification and the options are given later, starting |
| 27740 | at section 43.44 (callouts are described in section 43.45). You can combine |
| 27741 | this condition with the senders condition to restrict it to bounce messages |
| 27742 | only: |
| 27743 | |
| 27744 | deny senders = : |
| 27745 | message = A valid sender header is required for bounces |
| 27746 | !verify = header_sender |
| 27747 | |
| 27748 | verify = header_syntax |
| 27749 | |
| 27750 | This condition is relevant only in an ACL that is run after a message has |
| 27751 | been received, that is, in an ACL specified by acl_smtp_data or |
| 27752 | acl_not_smtp. It checks the syntax of all header lines that can contain |
| 27753 | lists of addresses (Sender:, From:, Reply-To:, To:, Cc:, and Bcc:), |
| 27754 | returning true if there are no problems. Unqualified addresses (local parts |
| 27755 | without domains) are permitted only in locally generated messages and from |
| 27756 | hosts that match sender_unqualified_hosts or recipient_unqualified_hosts, |
| 27757 | as appropriate. |
| 27758 | |
| 27759 | Note that this condition is a syntax check only. However, a common spamming |
| 27760 | ploy used to be to send syntactically invalid headers such as |
| 27761 | |
| 27762 | To: @ |
| 27763 | |
| 27764 | and this condition can be used to reject such messages, though they are not |
| 27765 | as common as they used to be. |
| 27766 | |
| 27767 | verify = helo |
| 27768 | |
| 27769 | This condition is true if a HELO or EHLO command has been received from the |
| 27770 | client host, and its contents have been verified. If there has been no |
| 27771 | previous attempt to verify the HELO/EHLO contents, it is carried out when |
| 27772 | this condition is encountered. See the description of the helo_verify_hosts |
| 27773 | and helo_try_verify_hosts options for details of how to request |
| 27774 | verification independently of this condition. |
| 27775 | |
| 27776 | For SMTP input that does not come over TCP/IP (the -bs command line |
| 27777 | option), this condition is always true. |
| 27778 | |
| 27779 | verify = not_blind |
| 27780 | |
| 27781 | This condition checks that there are no blind (bcc) recipients in the |
| 27782 | message. Every envelope recipient must appear either in a To: header line |
| 27783 | or in a Cc: header line for this condition to be true. Local parts are |
| 27784 | checked case-sensitively; domains are checked case-insensitively. If |
| 27785 | Resent-To: or Resent-Cc: header lines exist, they are also checked. This |
| 27786 | condition can be used only in a DATA or non-SMTP ACL. |
| 27787 | |
| 27788 | There are, of course, many legitimate messages that make use of blind (bcc) |
| 27789 | recipients. This check should not be used on its own for blocking messages. |
| 27790 | |
| 27791 | verify = recipient/<options> |
| 27792 | |
| 27793 | This condition is relevant only after a RCPT command. It verifies the |
| 27794 | current recipient. Details of address verification are given later, |
| 27795 | starting at section 43.44. After a recipient has been verified, the value |
| 27796 | of $address_data is the last value that was set while routing the address. |
| 27797 | This applies even if the verification fails. When an address that is being |
| 27798 | verified is redirected to a single address, verification continues with the |
| 27799 | new address, and in that case, the subsequent value of $address_data is the |
| 27800 | value for the child address. |
| 27801 | |
| 27802 | verify = reverse_host_lookup/<options> |
| 27803 | |
| 27804 | This condition ensures that a verified host name has been looked up from |
| 27805 | the IP address of the client host. (This may have happened already if the |
| 27806 | host name was needed for checking a host list, or if the host matched |
| 27807 | host_lookup.) Verification ensures that the host name obtained from a |
| 27808 | reverse DNS lookup, or one of its aliases, does, when it is itself looked |
| 27809 | up in the DNS, yield the original IP address. |
| 27810 | |
| 27811 | There is one possible option, "defer_ok". If this is present and a DNS |
| 27812 | operation returns a temporary error, the verify condition succeeds. |
| 27813 | |
| 27814 | If this condition is used for a locally generated message (that is, when |
| 27815 | there is no client host involved), it always succeeds. |
| 27816 | |
| 27817 | verify = sender/<options> |
| 27818 | |
| 27819 | This condition is relevant only after a MAIL or RCPT command, or after a |
| 27820 | message has been received (the acl_smtp_data or acl_not_smtp ACLs). If the |
| 27821 | message's sender is empty (that is, this is a bounce message), the |
| 27822 | condition is true. Otherwise, the sender address is verified. |
| 27823 | |
| 27824 | If there is data in the $address_data variable at the end of routing, its |
| 27825 | value is placed in $sender_address_data at the end of verification. This |
| 27826 | value can be used in subsequent conditions and modifiers in the same ACL |
| 27827 | statement. It does not persist after the end of the current statement. If |
| 27828 | you want to preserve the value for longer, you can save it in an ACL |
| 27829 | variable. |
| 27830 | |
| 27831 | Details of verification are given later, starting at section 43.44. Exim |
| 27832 | caches the result of sender verification, to avoid doing it more than once |
| 27833 | per message. |
| 27834 | |
| 27835 | verify = sender=<address>/<options> |
| 27836 | |
| 27837 | This is a variation of the previous option, in which a modified address is |
| 27838 | verified as a sender. |
| 27839 | |
| 27840 | Note that '/' is legal in local-parts; if the address may have such (eg. is |
| 27841 | generated from the received message) they must be protected from the |
| 27842 | options parsing by doubling: |
| 27843 | |
| 27844 | verify = sender=${sg{${address:$h_sender:}}{/}{//}} |
| 27845 | |
| 27846 | |
| 27847 | 43.27 Using DNS lists |
| 27848 | --------------------- |
| 27849 | |
| 27850 | In its simplest form, the dnslists condition tests whether the calling host is |
| 27851 | on at least one of a number of DNS lists by looking up the inverted IP address |
| 27852 | in one or more DNS domains. (Note that DNS list domains are not mail domains, |
| 27853 | so the "+" syntax for named lists doesn't work - it is used for special options |
| 27854 | instead.) For example, if the calling host's IP address is 192.168.62.43, and |
| 27855 | the ACL statement is |
| 27856 | |
| 27857 | deny dnslists = blackholes.mail-abuse.org : \ |
| 27858 | dialups.mail-abuse.org |
| 27859 | |
| 27860 | the following records are looked up: |
| 27861 | |
| 27862 | 43.62.168.192.blackholes.mail-abuse.org |
| 27863 | 43.62.168.192.dialups.mail-abuse.org |
| 27864 | |
| 27865 | As soon as Exim finds an existing DNS record, processing of the list stops. |
| 27866 | Thus, multiple entries on the list provide an "or" conjunction. If you want to |
| 27867 | test that a host is on more than one list (an "and" conjunction), you can use |
| 27868 | two separate conditions: |
| 27869 | |
| 27870 | deny dnslists = blackholes.mail-abuse.org |
| 27871 | dnslists = dialups.mail-abuse.org |
| 27872 | |
| 27873 | If a DNS lookup times out or otherwise fails to give a decisive answer, Exim |
| 27874 | behaves as if the host does not match the list item, that is, as if the DNS |
| 27875 | record does not exist. If there are further items in the DNS list, they are |
| 27876 | processed. |
| 27877 | |
| 27878 | This is usually the required action when dnslists is used with deny (which is |
| 27879 | the most common usage), because it prevents a DNS failure from blocking mail. |
| 27880 | However, you can change this behaviour by putting one of the following special |
| 27881 | items in the list: |
| 27882 | |
| 27883 | +include_unknown behave as if the item is on the list |
| 27884 | +exclude_unknown behave as if the item is not on the list (default) |
| 27885 | +defer_unknown give a temporary error |
| 27886 | |
| 27887 | Each of these applies to any subsequent items on the list. For example: |
| 27888 | |
| 27889 | deny dnslists = +defer_unknown : foo.bar.example |
| 27890 | |
| 27891 | Testing the list of domains stops as soon as a match is found. If you want to |
| 27892 | warn for one list and block for another, you can use two different statements: |
| 27893 | |
| 27894 | deny dnslists = blackholes.mail-abuse.org |
| 27895 | warn message = X-Warn: sending host is on dialups list |
| 27896 | dnslists = dialups.mail-abuse.org |
| 27897 | |
| 27898 | DNS list lookups are cached by Exim for the duration of the SMTP session (but |
| 27899 | limited by the DNS return TTL value), so a lookup based on the IP address is |
| 27900 | done at most once for any incoming connection (assuming long-enough TTL). Exim |
| 27901 | does not share information between multiple incoming connections (but your |
| 27902 | local name server cache should be active). |
| 27903 | |
| 27904 | |
| 27905 | 43.28 Specifying the IP address for a DNS list lookup |
| 27906 | ----------------------------------------------------- |
| 27907 | |
| 27908 | By default, the IP address that is used in a DNS list lookup is the IP address |
| 27909 | of the calling host. However, you can specify another IP address by listing it |
| 27910 | after the domain name, introduced by a slash. For example: |
| 27911 | |
| 27912 | deny dnslists = black.list.tld/192.168.1.2 |
| 27913 | |
| 27914 | This feature is not very helpful with explicit IP addresses; it is intended for |
| 27915 | use with IP addresses that are looked up, for example, the IP addresses of the |
| 27916 | MX hosts or nameservers of an email sender address. For an example, see section |
| 27917 | 43.30 below. |
| 27918 | |
| 27919 | |
| 27920 | 43.29 DNS lists keyed on domain names |
| 27921 | ------------------------------------- |
| 27922 | |
| 27923 | There are some lists that are keyed on domain names rather than inverted IP |
| 27924 | addresses (see for example the domain based zones link at http:// |
| 27925 | www.rfc-ignorant.org/). No reversing of components is used with these lists. |
| 27926 | You can change the name that is looked up in a DNS list by listing it after the |
| 27927 | domain name, introduced by a slash. For example, |
| 27928 | |
| 27929 | deny message = Sender's domain is listed at $dnslist_domain |
| 27930 | dnslists = dsn.rfc-ignorant.org/$sender_address_domain |
| 27931 | |
| 27932 | This particular example is useful only in ACLs that are obeyed after the RCPT |
| 27933 | or DATA commands, when a sender address is available. If (for example) the |
| 27934 | message's sender is user@tld.example the name that is looked up by this example |
| 27935 | is |
| 27936 | |
| 27937 | tld.example.dsn.rfc-ignorant.org |
| 27938 | |
| 27939 | A single dnslists condition can contain entries for both names and IP |
| 27940 | addresses. For example: |
| 27941 | |
| 27942 | deny dnslists = sbl.spamhaus.org : \ |
| 27943 | dsn.rfc-ignorant.org/$sender_address_domain |
| 27944 | |
| 27945 | The first item checks the sending host's IP address; the second checks a domain |
| 27946 | name. The whole condition is true if either of the DNS lookups succeeds. |
| 27947 | |
| 27948 | |
| 27949 | 43.30 Multiple explicit keys for a DNS list |
| 27950 | ------------------------------------------- |
| 27951 | |
| 27952 | The syntax described above for looking up explicitly-defined values (either |
| 27953 | names or IP addresses) in a DNS blacklist is a simplification. After the domain |
| 27954 | name for the DNS list, what follows the slash can in fact be a list of items. |
| 27955 | As with all lists in Exim, the default separator is a colon. However, because |
| 27956 | this is a sublist within the list of DNS blacklist domains, it is necessary |
| 27957 | either to double the separators like this: |
| 27958 | |
| 27959 | dnslists = black.list.tld/name.1::name.2 |
| 27960 | |
| 27961 | or to change the separator character, like this: |
| 27962 | |
| 27963 | dnslists = black.list.tld/<;name.1;name.2 |
| 27964 | |
| 27965 | If an item in the list is an IP address, it is inverted before the DNS |
| 27966 | blacklist domain is appended. If it is not an IP address, no inversion occurs. |
| 27967 | Consider this condition: |
| 27968 | |
| 27969 | dnslists = black.list.tld/<;192.168.1.2;a.domain |
| 27970 | |
| 27971 | The DNS lookups that occur are: |
| 27972 | |
| 27973 | 2.1.168.192.black.list.tld |
| 27974 | a.domain.black.list.tld |
| 27975 | |
| 27976 | Once a DNS record has been found (that matches a specific IP return address, if |
| 27977 | specified - see section 43.33), no further lookups are done. If there is a |
| 27978 | temporary DNS error, the rest of the sublist of domains or IP addresses is |
| 27979 | tried. A temporary error for the whole dnslists item occurs only if no other |
| 27980 | DNS lookup in this sublist succeeds. In other words, a successful lookup for |
| 27981 | any of the items in the sublist overrides a temporary error for a previous |
| 27982 | item. |
| 27983 | |
| 27984 | The ability to supply a list of items after the slash is in some sense just a |
| 27985 | syntactic convenience. These two examples have the same effect: |
| 27986 | |
| 27987 | dnslists = black.list.tld/a.domain : black.list.tld/b.domain |
| 27988 | dnslists = black.list.tld/a.domain::b.domain |
| 27989 | |
| 27990 | However, when the data for the list is obtained from a lookup, the second form |
| 27991 | is usually much more convenient. Consider this example: |
| 27992 | |
| 27993 | deny message = The mail servers for the domain \ |
| 27994 | $sender_address_domain \ |
| 27995 | are listed at $dnslist_domain ($dnslist_value); \ |
| 27996 | see $dnslist_text. |
| 27997 | dnslists = sbl.spamhaus.org/<|${lookup dnsdb {>|a=<|\ |
| 27998 | ${lookup dnsdb {>|mxh=\ |
| 27999 | $sender_address_domain} }} } |
| 28000 | |
| 28001 | Note the use of ">|" in the dnsdb lookup to specify the separator for multiple |
| 28002 | DNS records. The inner dnsdb lookup produces a list of MX hosts and the outer |
| 28003 | dnsdb lookup finds the IP addresses for these hosts. The result of expanding |
| 28004 | the condition might be something like this: |
| 28005 | |
| 28006 | dnslists = sbl.spamhaus.org/<|192.168.2.3|192.168.5.6|... |
| 28007 | |
| 28008 | Thus, this example checks whether or not the IP addresses of the sender |
| 28009 | domain's mail servers are on the Spamhaus black list. |
| 28010 | |
| 28011 | The key that was used for a successful DNS list lookup is put into the variable |
| 28012 | $dnslist_matched (see section 43.32). |
| 28013 | |
| 28014 | |
| 28015 | 43.31 Data returned by DNS lists |
| 28016 | -------------------------------- |
| 28017 | |
| 28018 | DNS lists are constructed using address records in the DNS. The original RBL |
| 28019 | just used the address 127.0.0.1 on the right hand side of each record, but the |
| 28020 | RBL+ list and some other lists use a number of values with different meanings. |
| 28021 | The values used on the RBL+ list are: |
| 28022 | |
| 28023 | 127.1.0.1 RBL |
| 28024 | 127.1.0.2 DUL |
| 28025 | 127.1.0.3 DUL and RBL |
| 28026 | 127.1.0.4 RSS |
| 28027 | 127.1.0.5 RSS and RBL |
| 28028 | 127.1.0.6 RSS and DUL |
| 28029 | 127.1.0.7 RSS and DUL and RBL |
| 28030 | |
| 28031 | Section 43.33 below describes how you can distinguish between different values. |
| 28032 | Some DNS lists may return more than one address record; see section 43.35 for |
| 28033 | details of how they are checked. |
| 28034 | |
| 28035 | |
| 28036 | 43.32 Variables set from DNS lists |
| 28037 | ---------------------------------- |
| 28038 | |
| 28039 | When an entry is found in a DNS list, the variable $dnslist_domain contains the |
| 28040 | name of the overall domain that matched (for example, "spamhaus.example"), |
| 28041 | $dnslist_matched contains the key within that domain (for example, |
| 28042 | "192.168.5.3"), and $dnslist_value contains the data from the DNS record. When |
| 28043 | the key is an IP address, it is not reversed in $dnslist_matched (though it is, |
| 28044 | of course, in the actual lookup). In simple cases, for example: |
| 28045 | |
| 28046 | deny dnslists = spamhaus.example |
| 28047 | |
| 28048 | the key is also available in another variable (in this case, |
| 28049 | $sender_host_address). In more complicated cases, however, this is not true. |
| 28050 | For example, using a data lookup (as described in section 43.30) might generate |
| 28051 | a dnslists lookup like this: |
| 28052 | |
| 28053 | deny dnslists = spamhaus.example/<|192.168.1.2|192.168.6.7|... |
| 28054 | |
| 28055 | If this condition succeeds, the value in $dnslist_matched might be |
| 28056 | "192.168.6.7" (for example). |
| 28057 | |
| 28058 | If more than one address record is returned by the DNS lookup, all the IP |
| 28059 | addresses are included in $dnslist_value, separated by commas and spaces. The |
| 28060 | variable $dnslist_text contains the contents of any associated TXT record. For |
| 28061 | lists such as RBL+ the TXT record for a merged entry is often not very |
| 28062 | meaningful. See section 43.36 for a way of obtaining more information. |
| 28063 | |
| 28064 | You can use the DNS list variables in message or log_message modifiers - |
| 28065 | although these appear before the condition in the ACL, they are not expanded |
| 28066 | until after it has failed. For example: |
| 28067 | |
| 28068 | deny hosts = !+local_networks |
| 28069 | message = $sender_host_address is listed \ |
| 28070 | at $dnslist_domain |
| 28071 | dnslists = rbl-plus.mail-abuse.example |
| 28072 | |
| 28073 | |
| 28074 | 43.33 Additional matching conditions for DNS lists |
| 28075 | -------------------------------------------------- |
| 28076 | |
| 28077 | You can add an equals sign and an IP address after a dnslists domain name in |
| 28078 | order to restrict its action to DNS records with a matching right hand side. |
| 28079 | For example, |
| 28080 | |
| 28081 | deny dnslists = rblplus.mail-abuse.org=127.0.0.2 |
| 28082 | |
| 28083 | rejects only those hosts that yield 127.0.0.2. Without this additional data, |
| 28084 | any address record is considered to be a match. For the moment, we assume that |
| 28085 | the DNS lookup returns just one record. Section 43.35 describes how multiple |
| 28086 | records are handled. |
| 28087 | |
| 28088 | More than one IP address may be given for checking, using a comma as a |
| 28089 | separator. These are alternatives - if any one of them matches, the dnslists |
| 28090 | condition is true. For example: |
| 28091 | |
| 28092 | deny dnslists = a.b.c=127.0.0.2,127.0.0.3 |
| 28093 | |
| 28094 | If you want to specify a constraining address list and also specify names or IP |
| 28095 | addresses to be looked up, the constraining address list must be specified |
| 28096 | first. For example: |
| 28097 | |
| 28098 | deny dnslists = dsn.rfc-ignorant.org\ |
| 28099 | =127.0.0.2/$sender_address_domain |
| 28100 | |
| 28101 | If the character "&" is used instead of "=", the comparison for each listed IP |
| 28102 | address is done by a bitwise "and" instead of by an equality test. In other |
| 28103 | words, the listed addresses are used as bit masks. The comparison is true if |
| 28104 | all the bits in the mask are present in the address that is being tested. For |
| 28105 | example: |
| 28106 | |
| 28107 | dnslists = a.b.c&0.0.0.3 |
| 28108 | |
| 28109 | matches if the address is x.x.x.3, x.x.x.7, x.x.x.11, etc. If you want to test |
| 28110 | whether one bit or another bit is present (as opposed to both being present), |
| 28111 | you must use multiple values. For example: |
| 28112 | |
| 28113 | dnslists = a.b.c&0.0.0.1,0.0.0.2 |
| 28114 | |
| 28115 | matches if the final component of the address is an odd number or two times an |
| 28116 | odd number. |
| 28117 | |
| 28118 | |
| 28119 | 43.34 Negated DNS matching conditions |
| 28120 | ------------------------------------- |
| 28121 | |
| 28122 | You can supply a negative list of IP addresses as part of a dnslists condition. |
| 28123 | Whereas |
| 28124 | |
| 28125 | deny dnslists = a.b.c=127.0.0.2,127.0.0.3 |
| 28126 | |
| 28127 | means "deny if the host is in the black list at the domain a.b.c and the IP |
| 28128 | address yielded by the list is either 127.0.0.2 or 127.0.0.3", |
| 28129 | |
| 28130 | deny dnslists = a.b.c!=127.0.0.2,127.0.0.3 |
| 28131 | |
| 28132 | means "deny if the host is in the black list at the domain a.b.c and the IP |
| 28133 | address yielded by the list is not 127.0.0.2 and not 127.0.0.3". In other |
| 28134 | words, the result of the test is inverted if an exclamation mark appears before |
| 28135 | the "=" (or the "&") sign. |
| 28136 | |
| 28137 | Note: This kind of negation is not the same as negation in a domain, host, or |
| 28138 | address list (which is why the syntax is different). |
| 28139 | |
| 28140 | If you are using just one list, the negation syntax does not gain you much. The |
| 28141 | previous example is precisely equivalent to |
| 28142 | |
| 28143 | deny dnslists = a.b.c |
| 28144 | !dnslists = a.b.c=127.0.0.2,127.0.0.3 |
| 28145 | |
| 28146 | However, if you are using multiple lists, the negation syntax is clearer. |
| 28147 | Consider this example: |
| 28148 | |
| 28149 | deny dnslists = sbl.spamhaus.org : \ |
| 28150 | list.dsbl.org : \ |
| 28151 | dnsbl.njabl.org!=127.0.0.3 : \ |
| 28152 | relays.ordb.org |
| 28153 | |
| 28154 | Using only positive lists, this would have to be: |
| 28155 | |
| 28156 | deny dnslists = sbl.spamhaus.org : \ |
| 28157 | list.dsbl.org |
| 28158 | deny dnslists = dnsbl.njabl.org |
| 28159 | !dnslists = dnsbl.njabl.org=127.0.0.3 |
| 28160 | deny dnslists = relays.ordb.org |
| 28161 | |
| 28162 | which is less clear, and harder to maintain. |
| 28163 | |
| 28164 | |
| 28165 | 43.35 Handling multiple DNS records from a DNS list |
| 28166 | --------------------------------------------------- |
| 28167 | |
| 28168 | A DNS lookup for a dnslists condition may return more than one DNS record, |
| 28169 | thereby providing more than one IP address. When an item in a dnslists list is |
| 28170 | followed by "=" or "&" and a list of IP addresses, in order to restrict the |
| 28171 | match to specific results from the DNS lookup, there are two ways in which the |
| 28172 | checking can be handled. For example, consider the condition: |
| 28173 | |
| 28174 | dnslists = a.b.c=127.0.0.1 |
| 28175 | |
| 28176 | What happens if the DNS lookup for the incoming IP address yields both |
| 28177 | 127.0.0.1 and 127.0.0.2 by means of two separate DNS records? Is the condition |
| 28178 | true because at least one given value was found, or is it false because at |
| 28179 | least one of the found values was not listed? And how does this affect negated |
| 28180 | conditions? Both possibilities are provided for with the help of additional |
| 28181 | separators "==" and "=&". |
| 28182 | |
| 28183 | * If "=" or "&" is used, the condition is true if any one of the looked up IP |
| 28184 | addresses matches one of the listed addresses. For the example above, the |
| 28185 | condition is true because 127.0.0.1 matches. |
| 28186 | |
| 28187 | * If "==" or "=&" is used, the condition is true only if every one of the |
| 28188 | looked up IP addresses matches one of the listed addresses. If the |
| 28189 | condition is changed to: |
| 28190 | |
| 28191 | dnslists = a.b.c==127.0.0.1 |
| 28192 | |
| 28193 | and the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is |
| 28194 | false because 127.0.0.2 is not listed. You would need to have: |
| 28195 | |
| 28196 | dnslists = a.b.c==127.0.0.1,127.0.0.2 |
| 28197 | |
| 28198 | for the condition to be true. |
| 28199 | |
| 28200 | When "!" is used to negate IP address matching, it inverts the result, giving |
| 28201 | the precise opposite of the behaviour above. Thus: |
| 28202 | |
| 28203 | * If "!=" or "!&" is used, the condition is true if none of the looked up IP |
| 28204 | addresses matches one of the listed addresses. Consider: |
| 28205 | |
| 28206 | dnslists = a.b.c!&0.0.0.1 |
| 28207 | |
| 28208 | If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is |
| 28209 | false because 127.0.0.1 matches. |
| 28210 | |
| 28211 | * If "!==" or "!=&" is used, the condition is true if there is at least one |
| 28212 | looked up IP address that does not match. Consider: |
| 28213 | |
| 28214 | dnslists = a.b.c!=&0.0.0.1 |
| 28215 | |
| 28216 | If the DNS lookup yields both 127.0.0.1 and 127.0.0.2, the condition is |
| 28217 | true, because 127.0.0.2 does not match. You would need to have: |
| 28218 | |
| 28219 | dnslists = a.b.c!=&0.0.0.1,0.0.0.2 |
| 28220 | |
| 28221 | for the condition to be false. |
| 28222 | |
| 28223 | When the DNS lookup yields only a single IP address, there is no difference |
| 28224 | between "=" and "==" and between "&" and "=&". |
| 28225 | |
| 28226 | |
| 28227 | 43.36 Detailed information from merged DNS lists |
| 28228 | ------------------------------------------------ |
| 28229 | |
| 28230 | When the facility for restricting the matching IP values in a DNS list is used, |
| 28231 | the text from the TXT record that is set in $dnslist_text may not reflect the |
| 28232 | true reason for rejection. This happens when lists are merged and the IP |
| 28233 | address in the A record is used to distinguish them; unfortunately there is |
| 28234 | only one TXT record. One way round this is not to use merged lists, but that |
| 28235 | can be inefficient because it requires multiple DNS lookups where one would do |
| 28236 | in the vast majority of cases when the host of interest is not on any of the |
| 28237 | lists. |
| 28238 | |
| 28239 | A less inefficient way of solving this problem is available. If two domain |
| 28240 | names, comma-separated, are given, the second is used first to do an initial |
| 28241 | check, making use of any IP value restrictions that are set. If there is a |
| 28242 | match, the first domain is used, without any IP value restrictions, to get the |
| 28243 | TXT record. As a byproduct of this, there is also a check that the IP being |
| 28244 | tested is indeed on the first list. The first domain is the one that is put in |
| 28245 | $dnslist_domain. For example: |
| 28246 | |
| 28247 | reject message = \ |
| 28248 | rejected because $sender_host_address is blacklisted \ |
| 28249 | at $dnslist_domain\n$dnslist_text |
| 28250 | dnslists = \ |
| 28251 | sbl.spamhaus.org,sbl-xbl.spamhaus.org=127.0.0.2 : \ |
| 28252 | dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10 |
| 28253 | |
| 28254 | For the first blacklist item, this starts by doing a lookup in |
| 28255 | sbl-xbl.spamhaus.org and testing for a 127.0.0.2 return. If there is a match, |
| 28256 | it then looks in sbl.spamhaus.org, without checking the return value, and as |
| 28257 | long as something is found, it looks for the corresponding TXT record. If there |
| 28258 | is no match in sbl-xbl.spamhaus.org, nothing more is done. The second blacklist |
| 28259 | item is processed similarly. |
| 28260 | |
| 28261 | If you are interested in more than one merged list, the same list must be given |
| 28262 | several times, but because the results of the DNS lookups are cached, the DNS |
| 28263 | calls themselves are not repeated. For example: |
| 28264 | |
| 28265 | reject dnslists = \ |
| 28266 | http.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.2 : \ |
| 28267 | socks.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.3 : \ |
| 28268 | misc.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.4 : \ |
| 28269 | dul.dnsbl.sorbs.net,dnsbl.sorbs.net=127.0.0.10 |
| 28270 | |
| 28271 | In this case there is one lookup in dnsbl.sorbs.net, and if none of the IP |
| 28272 | values matches (or if no record is found), this is the only lookup that is |
| 28273 | done. Only if there is a match is one of the more specific lists consulted. |
| 28274 | |
| 28275 | |
| 28276 | 43.37 DNS lists and IPv6 |
| 28277 | ------------------------ |
| 28278 | |
| 28279 | If Exim is asked to do a dnslist lookup for an IPv6 address, it inverts it |
| 28280 | nibble by nibble. For example, if the calling host's IP address is |
| 28281 | 3ffe:ffff:836f:0a00:000a:0800:200a:c031, Exim might look up |
| 28282 | |
| 28283 | 1.3.0.c.a.0.0.2.0.0.8.0.a.0.0.0.0.0.a.0.f.6.3.8. |
| 28284 | f.f.f.f.e.f.f.3.blackholes.mail-abuse.org |
| 28285 | |
| 28286 | (split over two lines here to fit on the page). Unfortunately, some of the DNS |
| 28287 | lists contain wildcard records, intended for IPv4, that interact badly with |
| 28288 | IPv6. For example, the DNS entry |
| 28289 | |
| 28290 | *.3.some.list.example. A 127.0.0.1 |
| 28291 | |
| 28292 | is probably intended to put the entire 3.0.0.0/8 IPv4 network on the list. |
| 28293 | Unfortunately, it also matches the entire 3::/4 IPv6 network. |
| 28294 | |
| 28295 | You can exclude IPv6 addresses from DNS lookups by making use of a suitable |
| 28296 | condition condition, as in this example: |
| 28297 | |
| 28298 | deny condition = ${if isip4{$sender_host_address}} |
| 28299 | dnslists = some.list.example |
| 28300 | |
| 28301 | If an explicit key is being used for a DNS lookup and it may be an IPv6 address |
| 28302 | you should specify alternate list separators for both the outer (DNS list name) |
| 28303 | list and inner (lookup keys) list: |
| 28304 | |
| 28305 | dnslists = <; dnsbl.example.com/<|$acl_m_addrslist |
| 28306 | |
| 28307 | |
| 28308 | 43.38 Rate limiting incoming messages |
| 28309 | ------------------------------------- |
| 28310 | |
| 28311 | The ratelimit ACL condition can be used to measure and control the rate at |
| 28312 | which clients can send email. This is more powerful than the smtp_ratelimit_* |
| 28313 | options, because those options control the rate of commands in a single SMTP |
| 28314 | session only, whereas the ratelimit condition works across all connections |
| 28315 | (concurrent and sequential) from the same client host. The syntax of the |
| 28316 | ratelimit condition is: |
| 28317 | |
| 28318 | ratelimit = <m> / <p> / <options> / <key> |
| 28319 | |
| 28320 | If the average client sending rate is less than m messages per time period p |
| 28321 | then the condition is false; otherwise it is true. |
| 28322 | |
| 28323 | As a side-effect, the ratelimit condition sets the expansion variable |
| 28324 | $sender_rate to the client's computed rate, $sender_rate_limit to the |
| 28325 | configured value of m, and $sender_rate_period to the configured value of p. |
| 28326 | |
| 28327 | The parameter p is the smoothing time constant, in the form of an Exim time |
| 28328 | interval, for example, "8h" for eight hours. A larger time constant means that |
| 28329 | it takes Exim longer to forget a client's past behaviour. The parameter m is |
| 28330 | the maximum number of messages that a client is permitted to send in each time |
| 28331 | interval. It also specifies the number of messages permitted in a fast burst. |
| 28332 | By increasing both m and p but keeping m/p constant, you can allow a client to |
| 28333 | send more messages in a burst without changing its long-term sending rate |
| 28334 | limit. Conversely, if m and p are both small, messages must be sent at an even |
| 28335 | rate. |
| 28336 | |
| 28337 | There is a script in util/ratelimit.pl which extracts sending rates from log |
| 28338 | files, to assist with choosing appropriate settings for m and p when deploying |
| 28339 | the ratelimit ACL condition. The script prints usage instructions when it is |
| 28340 | run with no arguments. |
| 28341 | |
| 28342 | The key is used to look up the data for calculating the client's average |
| 28343 | sending rate. This data is stored in Exim's spool directory, alongside the |
| 28344 | retry and other hints databases. The default key is $sender_host_address, which |
| 28345 | means Exim computes the sending rate of each client host IP address. By |
| 28346 | changing the key you can change how Exim identifies clients for the purpose of |
| 28347 | ratelimiting. For example, to limit the sending rate of each authenticated |
| 28348 | user, independent of the computer they are sending from, set the key to |
| 28349 | $authenticated_id. You must ensure that the lookup key is meaningful; for |
| 28350 | example, $authenticated_id is only meaningful if the client has authenticated |
| 28351 | (which you can check with the authenticated ACL condition). |
| 28352 | |
| 28353 | The lookup key does not have to identify clients: If you want to limit the rate |
| 28354 | at which a recipient receives messages, you can use the key |
| 28355 | "$local_part@$domain" with the per_rcpt option (see below) in a RCPT ACL. |
| 28356 | |
| 28357 | Each ratelimit condition can have up to four options. A per_* option specifies |
| 28358 | what Exim measures the rate of, for example messages or recipients or bytes. |
| 28359 | You can adjust the measurement using the unique= and/or count= options. You can |
| 28360 | also control when Exim updates the recorded rate using a strict, leaky, or |
| 28361 | readonly option. The options are separated by a slash, like the other |
| 28362 | parameters. They may appear in any order. |
| 28363 | |
| 28364 | Internally, Exim appends the smoothing constant p onto the lookup key with any |
| 28365 | options that alter the meaning of the stored data. The limit m is not stored, |
| 28366 | so you can alter the configured maximum rate and Exim will still remember |
| 28367 | clients' past behaviour. If you change the per_* mode or add or remove the |
| 28368 | unique= option, the lookup key changes so Exim will forget past behaviour. The |
| 28369 | lookup key is not affected by changes to the update mode and the count= option. |
| 28370 | |
| 28371 | |
| 28372 | 43.39 Ratelimit options for what is being measured |
| 28373 | -------------------------------------------------- |
| 28374 | |
| 28375 | The per_conn option limits the client's connection rate. It is not normally |
| 28376 | used in the acl_not_smtp, acl_not_smtp_mime, or acl_not_smtp_start ACLs. |
| 28377 | |
| 28378 | The per_mail option limits the client's rate of sending messages. This is the |
| 28379 | default if none of the per_* options is specified. It can be used in |
| 28380 | acl_smtp_mail, acl_smtp_rcpt, acl_smtp_predata, acl_smtp_mime, acl_smtp_data, |
| 28381 | or acl_not_smtp. |
| 28382 | |
| 28383 | The per_byte option limits the sender's email bandwidth. It can be used in the |
| 28384 | same ACLs as the per_mail option, though it is best to use this option in the |
| 28385 | acl_smtp_mime, acl_smtp_data or acl_not_smtp ACLs; if it is used in an earlier |
| 28386 | ACL, Exim relies on the SIZE parameter given by the client in its MAIL command, |
| 28387 | which may be inaccurate or completely missing. You can follow the limit m in |
| 28388 | the configuration with K, M, or G to specify limits in kilobytes, megabytes, or |
| 28389 | gigabytes, respectively. |
| 28390 | |
| 28391 | The per_rcpt option causes Exim to limit the rate at which recipients are |
| 28392 | accepted. It can be used in the acl_smtp_rcpt, acl_smtp_predata, acl_smtp_mime, |
| 28393 | acl_smtp_data, or acl_smtp_rcpt ACLs. In acl_smtp_rcpt the rate is updated one |
| 28394 | recipient at a time; in the other ACLs the rate is updated with the total |
| 28395 | (accepted) recipient count in one go. Note that in either case the rate |
| 28396 | limiting engine will see a message with many recipients as a large high-speed |
| 28397 | burst. |
| 28398 | |
| 28399 | The per_addr option is like the per_rcpt option, except it counts the number of |
| 28400 | different recipients that the client has sent messages to in the last time |
| 28401 | period. That is, if the client repeatedly sends messages to the same recipient, |
| 28402 | its measured rate is not increased. This option can only be used in |
| 28403 | acl_smtp_rcpt. |
| 28404 | |
| 28405 | The per_cmd option causes Exim to recompute the rate every time the condition |
| 28406 | is processed. This can be used to limit the rate of any SMTP command. If it is |
| 28407 | used in multiple ACLs it can limit the aggregate rate of multiple different |
| 28408 | commands. |
| 28409 | |
| 28410 | The count= option can be used to alter how much Exim adds to the client's |
| 28411 | measured rate. For example, the per_byte option is equivalent to "per_mail/ |
| 28412 | count=$message_size". If there is no count= option, Exim increases the measured |
| 28413 | rate by one (except for the per_rcpt option in ACLs other than acl_smtp_rcpt). |
| 28414 | The count does not have to be an integer. |
| 28415 | |
| 28416 | The unique= option is described in section 43.42 below. |
| 28417 | |
| 28418 | |
| 28419 | 43.40 Ratelimit update modes |
| 28420 | ---------------------------- |
| 28421 | |
| 28422 | You can specify one of three options with the ratelimit condition to control |
| 28423 | when its database is updated. This section describes the readonly mode, and the |
| 28424 | next section describes the strict and leaky modes. |
| 28425 | |
| 28426 | If the ratelimit condition is used in readonly mode, Exim looks up a |
| 28427 | previously-computed rate to check against the limit. |
| 28428 | |
| 28429 | For example, you can test the client's sending rate and deny it access (when it |
| 28430 | is too fast) in the connect ACL. If the client passes this check then it can go |
| 28431 | on to send a message, in which case its recorded rate will be updated in the |
| 28432 | MAIL ACL. Subsequent connections from the same client will check this new rate. |
| 28433 | |
| 28434 | acl_check_connect: |
| 28435 | deny ratelimit = 100 / 5m / readonly |
| 28436 | log_message = RATE CHECK: $sender_rate/$sender_rate_period \ |
| 28437 | (max $sender_rate_limit) |
| 28438 | # ... |
| 28439 | acl_check_mail: |
| 28440 | warn ratelimit = 100 / 5m / strict |
| 28441 | log_message = RATE UPDATE: $sender_rate/$sender_rate_period \ |
| 28442 | (max $sender_rate_limit) |
| 28443 | |
| 28444 | If Exim encounters multiple ratelimit conditions with the same key when |
| 28445 | processing a message then it may increase the client's measured rate more than |
| 28446 | it should. For example, this will happen if you check the per_rcpt option in |
| 28447 | both acl_smtp_rcpt and acl_smtp_data. However it's OK to check the same |
| 28448 | ratelimit condition multiple times in the same ACL. You can avoid any multiple |
| 28449 | update problems by using the readonly option on later ratelimit checks. |
| 28450 | |
| 28451 | The per_* options described above do not make sense in some ACLs. If you use a |
| 28452 | per_* option in an ACL where it is not normally permitted then the update mode |
| 28453 | defaults to readonly and you cannot specify the strict or leaky modes. In other |
| 28454 | ACLs the default update mode is leaky (see the next section) so you must |
| 28455 | specify the readonly option explicitly. |
| 28456 | |
| 28457 | |
| 28458 | 43.41 Ratelimit options for handling fast clients |
| 28459 | ------------------------------------------------- |
| 28460 | |
| 28461 | If a client's average rate is greater than the maximum, the rate limiting |
| 28462 | engine can react in two possible ways, depending on the presence of the strict |
| 28463 | or leaky update modes. This is independent of the other counter-measures (such |
| 28464 | as rejecting the message) that may be specified by the rest of the ACL. |
| 28465 | |
| 28466 | The leaky (default) option means that the client's recorded rate is not updated |
| 28467 | if it is above the limit. The effect of this is that Exim measures the client's |
| 28468 | average rate of successfully sent email, which cannot be greater than the |
| 28469 | maximum allowed. If the client is over the limit it may suffer some |
| 28470 | counter-measures (as specified in the ACL), but it will still be able to send |
| 28471 | email at the configured maximum rate, whatever the rate of its attempts. This |
| 28472 | is generally the better choice if you have clients that retry automatically. |
| 28473 | For example, it does not prevent a sender with an over-aggressive retry rate |
| 28474 | from getting any email through. |
| 28475 | |
| 28476 | The strict option means that the client's recorded rate is always updated. The |
| 28477 | effect of this is that Exim measures the client's average rate of attempts to |
| 28478 | send email, which can be much higher than the maximum it is actually allowed. |
| 28479 | If the client is over the limit it may be subjected to counter-measures by the |
| 28480 | ACL. It must slow down and allow sufficient time to pass that its computed rate |
| 28481 | falls below the maximum before it can send email again. The time (the number of |
| 28482 | smoothing periods) it must wait and not attempt to send mail can be calculated |
| 28483 | with this formula: |
| 28484 | |
| 28485 | ln(peakrate/maxrate) |
| 28486 | |
| 28487 | |
| 28488 | 43.42 Limiting the rate of different events |
| 28489 | ------------------------------------------- |
| 28490 | |
| 28491 | The ratelimit unique= option controls a mechanism for counting the rate of |
| 28492 | different events. For example, the per_addr option uses this mechanism to count |
| 28493 | the number of different recipients that the client has sent messages to in the |
| 28494 | last time period; it is equivalent to "per_rcpt/unique=$local_part@$domain". |
| 28495 | You could use this feature to measure the rate that a client uses different |
| 28496 | sender addresses with the options "per_mail/unique=$sender_address". |
| 28497 | |
| 28498 | For each ratelimit key Exim stores the set of unique= values that it has seen |
| 28499 | for that key. The whole set is thrown away when it is older than the rate |
| 28500 | smoothing period p, so each different event is counted at most once per period. |
| 28501 | In the leaky update mode, an event that causes the client to go over the limit |
| 28502 | is not added to the set, in the same way that the client's recorded rate is not |
| 28503 | updated in the same situation. |
| 28504 | |
| 28505 | When you combine the unique= and readonly options, the specific unique= value |
| 28506 | is ignored, and Exim just retrieves the client's stored rate. |
| 28507 | |
| 28508 | The unique= mechanism needs more space in the ratelimit database than the other |
| 28509 | ratelimit options in order to store the event set. The number of unique values |
| 28510 | is potentially as large as the rate limit, so the extra space required |
| 28511 | increases with larger limits. |
| 28512 | |
| 28513 | The uniqueification is not perfect: there is a small probability that Exim will |
| 28514 | think a new event has happened before. If the sender's rate is less than the |
| 28515 | limit, Exim should be more than 99.9% correct. However in strict mode the |
| 28516 | measured rate can go above the limit, in which case Exim may under-count events |
| 28517 | by a significant margin. Fortunately, if the rate is high enough (2.7 times the |
| 28518 | limit) that the false positive rate goes above 9%, then Exim will throw away |
| 28519 | the over-full event set before the measured rate falls below the limit. |
| 28520 | Therefore the only harm should be that exceptionally high sending rates are |
| 28521 | logged incorrectly; any countermeasures you configure will be as effective as |
| 28522 | intended. |
| 28523 | |
| 28524 | |
| 28525 | 43.43 Using rate limiting |
| 28526 | ------------------------- |
| 28527 | |
| 28528 | Exim's other ACL facilities are used to define what counter-measures are taken |
| 28529 | when the rate limit is exceeded. This might be anything from logging a warning |
| 28530 | (for example, while measuring existing sending rates in order to define |
| 28531 | policy), through time delays to slow down fast senders, up to rejecting the |
| 28532 | message. For example: |
| 28533 | |
| 28534 | # Log all senders' rates |
| 28535 | warn ratelimit = 0 / 1h / strict |
| 28536 | log_message = Sender rate $sender_rate / $sender_rate_period |
| 28537 | |
| 28538 | # Slow down fast senders; note the need to truncate $sender_rate |
| 28539 | # at the decimal point. |
| 28540 | warn ratelimit = 100 / 1h / per_rcpt / strict |
| 28541 | delay = ${eval: ${sg{$sender_rate}{[.].*}{}} - \ |
| 28542 | $sender_rate_limit }s |
| 28543 | |
| 28544 | # Keep authenticated users under control |
| 28545 | deny authenticated = * |
| 28546 | ratelimit = 100 / 1d / strict / $authenticated_id |
| 28547 | |
| 28548 | # System-wide rate limit |
| 28549 | defer message = Sorry, too busy. Try again later. |
| 28550 | ratelimit = 10 / 1s / $primary_hostname |
| 28551 | |
| 28552 | # Restrict incoming rate from each host, with a default |
| 28553 | # set using a macro and special cases looked up in a table. |
| 28554 | defer message = Sender rate exceeds $sender_rate_limit \ |
| 28555 | messages per $sender_rate_period |
| 28556 | ratelimit = ${lookup {$sender_host_address} \ |
| 28557 | cdb {DB/ratelimits.cdb} \ |
| 28558 | {$value} {RATELIMIT} } |
| 28559 | |
| 28560 | Warning: If you have a busy server with a lot of ratelimit tests, especially |
| 28561 | with the per_rcpt option, you may suffer from a performance bottleneck caused |
| 28562 | by locking on the ratelimit hints database. Apart from making your ACLs less |
| 28563 | complicated, you can reduce the problem by using a RAM disk for Exim's hints |
| 28564 | directory (usually /var/spool/exim/db/). However this means that Exim will lose |
| 28565 | its hints data after a reboot (including retry hints, the callout cache, and |
| 28566 | ratelimit data). |
| 28567 | |
| 28568 | |
| 28569 | 43.44 Address verification |
| 28570 | -------------------------- |
| 28571 | |
| 28572 | Several of the verify conditions described in section 43.26 cause addresses to |
| 28573 | be verified. Section 43.48 discusses the reporting of sender verification |
| 28574 | failures. The verification conditions can be followed by options that modify |
| 28575 | the verification process. The options are separated from the keyword and from |
| 28576 | each other by slashes, and some of them contain parameters. For example: |
| 28577 | |
| 28578 | verify = sender/callout |
| 28579 | verify = recipient/defer_ok/callout=10s,defer_ok |
| 28580 | |
| 28581 | The first stage of address verification, which always happens, is to run the |
| 28582 | address through the routers, in "verify mode". Routers can detect the |
| 28583 | difference between verification and routing for delivery, and their actions can |
| 28584 | be varied by a number of generic options such as verify and verify_only (see |
| 28585 | chapter 15). If routing fails, verification fails. The available options are as |
| 28586 | follows: |
| 28587 | |
| 28588 | * If the callout option is specified, successful routing to one or more |
| 28589 | remote hosts is followed by a "callout" to those hosts as an additional |
| 28590 | check. Callouts and their sub-options are discussed in the next section. |
| 28591 | |
| 28592 | * If there is a defer error while doing verification routing, the ACL |
| 28593 | normally returns "defer". However, if you include defer_ok in the options, |
| 28594 | the condition is forced to be true instead. Note that this is a main |
| 28595 | verification option as well as a suboption for callouts. |
| 28596 | |
| 28597 | * The no_details option is covered in section 43.48, which discusses the |
| 28598 | reporting of sender address verification failures. |
| 28599 | |
| 28600 | * The success_on_redirect option causes verification always to succeed |
| 28601 | immediately after a successful redirection. By default, if a redirection |
| 28602 | generates just one address, that address is also verified. See further |
| 28603 | discussion in section 43.49. |
| 28604 | |
| 28605 | After an address verification failure, $acl_verify_message contains the error |
| 28606 | message that is associated with the failure. It can be preserved by coding like |
| 28607 | this: |
| 28608 | |
| 28609 | warn !verify = sender |
| 28610 | set acl_m0 = $acl_verify_message |
| 28611 | |
| 28612 | If you are writing your own custom rejection message or log message when |
| 28613 | denying access, you can use this variable to include information about the |
| 28614 | verification failure. |
| 28615 | |
| 28616 | In addition, $sender_verify_failure or $recipient_verify_failure (as |
| 28617 | appropriate) contains one of the following words: |
| 28618 | |
| 28619 | * qualify: The address was unqualified (no domain), and the message was |
| 28620 | neither local nor came from an exempted host. |
| 28621 | |
| 28622 | * route: Routing failed. |
| 28623 | |
| 28624 | * mail: Routing succeeded, and a callout was attempted; rejection occurred at |
| 28625 | or before the MAIL command (that is, on initial connection, HELO, or MAIL). |
| 28626 | |
| 28627 | * recipient: The RCPT command in a callout was rejected. |
| 28628 | |
| 28629 | * postmaster: The postmaster check in a callout was rejected. |
| 28630 | |
| 28631 | The main use of these variables is expected to be to distinguish between |
| 28632 | rejections of MAIL and rejections of RCPT in callouts. |
| 28633 | |
| 28634 | |
| 28635 | 43.45 Callout verification |
| 28636 | -------------------------- |
| 28637 | |
| 28638 | For non-local addresses, routing verifies the domain, but is unable to do any |
| 28639 | checking of the local part. There are situations where some means of verifying |
| 28640 | the local part is desirable. One way this can be done is to make an SMTP |
| 28641 | callback to a delivery host for the sender address or a callforward to a |
| 28642 | subsequent host for a recipient address, to see if the host accepts the |
| 28643 | address. We use the term callout to cover both cases. Note that for a sender |
| 28644 | address, the callback is not to the client host that is trying to deliver the |
| 28645 | message, but to one of the hosts that accepts incoming mail for the sender's |
| 28646 | domain. |
| 28647 | |
| 28648 | Exim does not do callouts by default. If you want them to happen, you must |
| 28649 | request them by setting appropriate options on the verify condition, as |
| 28650 | described below. This facility should be used with care, because it can add a |
| 28651 | lot of resource usage to the cost of verifying an address. However, Exim does |
| 28652 | cache the results of callouts, which helps to reduce the cost. Details of |
| 28653 | caching are in section 43.47. |
| 28654 | |
| 28655 | Recipient callouts are usually used only between hosts that are controlled by |
| 28656 | the same administration. For example, a corporate gateway host could use |
| 28657 | callouts to check for valid recipients on an internal mailserver. A successful |
| 28658 | callout does not guarantee that a real delivery to the address would succeed; |
| 28659 | on the other hand, a failing callout does guarantee that a delivery would fail. |
| 28660 | |
| 28661 | If the callout option is present on a condition that verifies an address, a |
| 28662 | second stage of verification occurs if the address is successfully routed to |
| 28663 | one or more remote hosts. The usual case is routing by a dnslookup or a |
| 28664 | manualroute router, where the router specifies the hosts. However, if a router |
| 28665 | that does not set up hosts routes to an smtp transport with a hosts setting, |
| 28666 | the transport's hosts are used. If an smtp transport has hosts_override set, |
| 28667 | its hosts are always used, whether or not the router supplies a host list. |
| 28668 | Callouts are only supported on smtp transports. |
| 28669 | |
| 28670 | The port that is used is taken from the transport, if it is specified and is a |
| 28671 | remote transport. (For routers that do verification only, no transport need be |
| 28672 | specified.) Otherwise, the default SMTP port is used. If a remote transport |
| 28673 | specifies an outgoing interface, this is used; otherwise the interface is not |
| 28674 | specified. Likewise, the text that is used for the HELO command is taken from |
| 28675 | the transport's helo_data option; if there is no transport, the value of |
| 28676 | $smtp_active_hostname is used. |
| 28677 | |
| 28678 | For a sender callout check, Exim makes SMTP connections to the remote hosts, to |
| 28679 | test whether a bounce message could be delivered to the sender address. The |
| 28680 | following SMTP commands are sent: |
| 28681 | |
| 28682 | HELO <local host name> |
| 28683 | MAIL FROM:<> |
| 28684 | RCPT TO:<the address to be tested> |
| 28685 | QUIT |
| 28686 | |
| 28687 | LHLO is used instead of HELO if the transport's protocol option is set to |
| 28688 | "lmtp". |
| 28689 | |
| 28690 | The callout may use EHLO, AUTH and/or STARTTLS given appropriate option |
| 28691 | settings. |
| 28692 | |
| 28693 | A recipient callout check is similar. By default, it also uses an empty address |
| 28694 | for the sender. This default is chosen because most hosts do not make use of |
| 28695 | the sender address when verifying a recipient. Using the same address means |
| 28696 | that a single cache entry can be used for each recipient. Some sites, however, |
| 28697 | do make use of the sender address when verifying. These are catered for by the |
| 28698 | use_sender and use_postmaster options, described in the next section. |
| 28699 | |
| 28700 | If the response to the RCPT command is a 2xx code, the verification succeeds. |
| 28701 | If it is 5xx, the verification fails. For any other condition, Exim tries the |
| 28702 | next host, if any. If there is a problem with all the remote hosts, the ACL |
| 28703 | yields "defer", unless the defer_ok parameter of the callout option is given, |
| 28704 | in which case the condition is forced to succeed. |
| 28705 | |
| 28706 | A callout may take a little time. For this reason, Exim normally flushes SMTP |
| 28707 | output before performing a callout in an ACL, to avoid unexpected timeouts in |
| 28708 | clients when the SMTP PIPELINING extension is in use. The flushing can be |
| 28709 | disabled by using a control modifier to set no_callout_flush. |
| 28710 | |
| 28711 | |
| 28712 | 43.46 Additional parameters for callouts |
| 28713 | ---------------------------------------- |
| 28714 | |
| 28715 | The callout option can be followed by an equals sign and a number of optional |
| 28716 | parameters, separated by commas. For example: |
| 28717 | |
| 28718 | verify = recipient/callout=10s,defer_ok |
| 28719 | |
| 28720 | The old syntax, which had callout_defer_ok and check_postmaster as separate |
| 28721 | verify options, is retained for backwards compatibility, but is now deprecated. |
| 28722 | The additional parameters for callout are as follows: |
| 28723 | |
| 28724 | <a time interval> |
| 28725 | |
| 28726 | This specifies the timeout that applies for the callout attempt to each |
| 28727 | host. For example: |
| 28728 | |
| 28729 | verify = sender/callout=5s |
| 28730 | |
| 28731 | The default is 30 seconds. The timeout is used for each response from the |
| 28732 | remote host. It is also used for the initial connection, unless overridden |
| 28733 | by the connect parameter. |
| 28734 | |
| 28735 | connect = <time interval> |
| 28736 | |
| 28737 | This parameter makes it possible to set a different (usually smaller) |
| 28738 | timeout for making the SMTP connection. For example: |
| 28739 | |
| 28740 | verify = sender/callout=5s,connect=1s |
| 28741 | |
| 28742 | If not specified, this timeout defaults to the general timeout value. |
| 28743 | |
| 28744 | defer_ok |
| 28745 | |
| 28746 | When this parameter is present, failure to contact any host, or any other |
| 28747 | kind of temporary error, is treated as success by the ACL. However, the |
| 28748 | cache is not updated in this circumstance. |
| 28749 | |
| 28750 | fullpostmaster |
| 28751 | |
| 28752 | This operates like the postmaster option (see below), but if the check for |
| 28753 | postmaster@domain fails, it tries just postmaster, without a domain, in |
| 28754 | accordance with the specification in RFC 2821. The RFC states that the |
| 28755 | unqualified address postmaster should be accepted. |
| 28756 | |
| 28757 | mailfrom = <email address> |
| 28758 | |
| 28759 | When verifying addresses in header lines using the header_sender |
| 28760 | verification option, Exim behaves by default as if the addresses are |
| 28761 | envelope sender addresses from a message. Callout verification therefore |
| 28762 | tests to see whether a bounce message could be delivered, by using an empty |
| 28763 | address in the MAIL command. However, it is arguable that these addresses |
| 28764 | might never be used as envelope senders, and could therefore justifiably |
| 28765 | reject bounce messages (empty senders). The mailfrom callout parameter |
| 28766 | allows you to specify what address to use in the MAIL command. For example: |
| 28767 | |
| 28768 | require verify = header_sender/callout=mailfrom=abcd@x.y.z |
| 28769 | |
| 28770 | This parameter is available only for the header_sender verification option. |
| 28771 | |
| 28772 | maxwait = <time interval> |
| 28773 | |
| 28774 | This parameter sets an overall timeout for performing a callout |
| 28775 | verification. For example: |
| 28776 | |
| 28777 | verify = sender/callout=5s,maxwait=30s |
| 28778 | |
| 28779 | This timeout defaults to four times the callout timeout for individual SMTP |
| 28780 | commands. The overall timeout applies when there is more than one host that |
| 28781 | can be tried. The timeout is checked before trying the next host. This |
| 28782 | prevents very long delays if there are a large number of hosts and all are |
| 28783 | timing out (for example, when network connections are timing out). |
| 28784 | |
| 28785 | no_cache |
| 28786 | |
| 28787 | When this parameter is given, the callout cache is neither read nor |
| 28788 | updated. |
| 28789 | |
| 28790 | postmaster |
| 28791 | |
| 28792 | When this parameter is set, a successful callout check is followed by a |
| 28793 | similar check for the local part postmaster at the same domain. If this |
| 28794 | address is rejected, the callout fails (but see fullpostmaster above). The |
| 28795 | result of the postmaster check is recorded in a cache record; if it is a |
| 28796 | failure, this is used to fail subsequent callouts for the domain without a |
| 28797 | connection being made, until the cache record expires. |
| 28798 | |
| 28799 | postmaster_mailfrom = <email address> |
| 28800 | |
| 28801 | The postmaster check uses an empty sender in the MAIL command by default. |
| 28802 | You can use this parameter to do a postmaster check using a different |
| 28803 | address. For example: |
| 28804 | |
| 28805 | require verify = sender/callout=postmaster_mailfrom=abc@x.y.z |
| 28806 | |
| 28807 | If both postmaster and postmaster_mailfrom are present, the rightmost one |
| 28808 | overrides. The postmaster parameter is equivalent to this example: |
| 28809 | |
| 28810 | require verify = sender/callout=postmaster_mailfrom= |
| 28811 | |
| 28812 | Warning: The caching arrangements for postmaster checking do not take |
| 28813 | account of the sender address. It is assumed that either the empty address |
| 28814 | or a fixed non-empty address will be used. All that Exim remembers is that |
| 28815 | the postmaster check for the domain succeeded or failed. |
| 28816 | |
| 28817 | random |
| 28818 | |
| 28819 | When this parameter is set, before doing the normal callout check, Exim |
| 28820 | does a check for a "random" local part at the same domain. The local part |
| 28821 | is not really random - it is defined by the expansion of the option |
| 28822 | callout_random_local_part, which defaults to |
| 28823 | |
| 28824 | $primary_hostname-$tod_epoch-testing |
| 28825 | |
| 28826 | The idea here is to try to determine whether the remote host accepts all |
| 28827 | local parts without checking. If it does, there is no point in doing |
| 28828 | callouts for specific local parts. If the "random" check succeeds, the |
| 28829 | result is saved in a cache record, and used to force the current and |
| 28830 | subsequent callout checks to succeed without a connection being made, until |
| 28831 | the cache record expires. |
| 28832 | |
| 28833 | use_postmaster |
| 28834 | |
| 28835 | This parameter applies to recipient callouts only. For example: |
| 28836 | |
| 28837 | deny !verify = recipient/callout=use_postmaster |
| 28838 | |
| 28839 | It causes a non-empty postmaster address to be used in the MAIL command |
| 28840 | when performing the callout for the recipient, and also for a "random" |
| 28841 | check if that is configured. The local part of the address is "postmaster" |
| 28842 | and the domain is the contents of $qualify_domain. |
| 28843 | |
| 28844 | use_sender |
| 28845 | |
| 28846 | This option applies to recipient callouts only. For example: |
| 28847 | |
| 28848 | require verify = recipient/callout=use_sender |
| 28849 | |
| 28850 | It causes the message's actual sender address to be used in the MAIL |
| 28851 | command when performing the callout, instead of an empty address. There is |
| 28852 | no need to use this option unless you know that the called hosts make use |
| 28853 | of the sender when checking recipients. If used indiscriminately, it |
| 28854 | reduces the usefulness of callout caching. |
| 28855 | |
| 28856 | If you use any of the parameters that set a non-empty sender for the MAIL |
| 28857 | command (mailfrom, postmaster_mailfrom, use_postmaster, or use_sender), you |
| 28858 | should think about possible loops. Recipient checking is usually done between |
| 28859 | two hosts that are under the same management, and the host that receives the |
| 28860 | callouts is not normally configured to do callouts itself. Therefore, it is |
| 28861 | normally safe to use use_postmaster or use_sender in these circumstances. |
| 28862 | |
| 28863 | However, if you use a non-empty sender address for a callout to an arbitrary |
| 28864 | host, there is the likelihood that the remote host will itself initiate a |
| 28865 | callout check back to your host. As it is checking what appears to be a message |
| 28866 | sender, it is likely to use an empty address in MAIL, thus avoiding a callout |
| 28867 | loop. However, to be on the safe side it would be best to set up your own ACLs |
| 28868 | so that they do not do sender verification checks when the recipient is the |
| 28869 | address you use for header sender or postmaster callout checking. |
| 28870 | |
| 28871 | Another issue to think about when using non-empty senders for callouts is |
| 28872 | caching. When you set mailfrom or use_sender, the cache record is keyed by the |
| 28873 | sender/recipient combination; thus, for any given recipient, many more actual |
| 28874 | callouts are performed than when an empty sender or postmaster is used. |
| 28875 | |
| 28876 | |
| 28877 | 43.47 Callout caching |
| 28878 | --------------------- |
| 28879 | |
| 28880 | Exim caches the results of callouts in order to reduce the amount of resources |
| 28881 | used, unless you specify the no_cache parameter with the callout option. A |
| 28882 | hints database called "callout" is used for the cache. Two different record |
| 28883 | types are used: one records the result of a callout check for a specific |
| 28884 | address, and the other records information that applies to the entire domain |
| 28885 | (for example, that it accepts the local part postmaster). |
| 28886 | |
| 28887 | When an original callout fails, a detailed SMTP error message is given about |
| 28888 | the failure. However, for subsequent failures use the cache data, this message |
| 28889 | is not available. |
| 28890 | |
| 28891 | The expiry times for negative and positive address cache records are |
| 28892 | independent, and can be set by the global options callout_negative_expire |
| 28893 | (default 2h) and callout_positive_expire (default 24h), respectively. |
| 28894 | |
| 28895 | If a host gives a negative response to an SMTP connection, or rejects any |
| 28896 | commands up to and including |
| 28897 | |
| 28898 | MAIL FROM:<> |
| 28899 | |
| 28900 | (but not including the MAIL command with a non-empty address), any callout |
| 28901 | attempt is bound to fail. Exim remembers such failures in a domain cache |
| 28902 | record, which it uses to fail callouts for the domain without making new |
| 28903 | connections, until the domain record times out. There are two separate expiry |
| 28904 | times for domain cache records: callout_domain_negative_expire (default 3h) and |
| 28905 | callout_domain_positive_expire (default 7d). |
| 28906 | |
| 28907 | Domain records expire when the negative expiry time is reached if callouts |
| 28908 | cannot be made for the domain, or if the postmaster check failed. Otherwise, |
| 28909 | they expire when the positive expiry time is reached. This ensures that, for |
| 28910 | example, a host that stops accepting "random" local parts will eventually be |
| 28911 | noticed. |
| 28912 | |
| 28913 | The callout caching mechanism is based on the domain of the address that is |
| 28914 | being tested. If the domain routes to several hosts, it is assumed that their |
| 28915 | behaviour will be the same. |
| 28916 | |
| 28917 | |
| 28918 | 43.48 Sender address verification reporting |
| 28919 | ------------------------------------------- |
| 28920 | |
| 28921 | See section 43.44 for a general discussion of verification. When sender |
| 28922 | verification fails in an ACL, the details of the failure are given as |
| 28923 | additional output lines before the 550 response to the relevant SMTP command |
| 28924 | (RCPT or DATA). For example, if sender callout is in use, you might see: |
| 28925 | |
| 28926 | MAIL FROM:<xyz@abc.example> |
| 28927 | 250 OK |
| 28928 | RCPT TO:<pqr@def.example> |
| 28929 | 550-Verification failed for <xyz@abc.example> |
| 28930 | 550-Called: 192.168.34.43 |
| 28931 | 550-Sent: RCPT TO:<xyz@abc.example> |
| 28932 | 550-Response: 550 Unknown local part xyz in <xyz@abc.example> |
| 28933 | 550 Sender verification failed |
| 28934 | |
| 28935 | If more than one RCPT command fails in the same way, the details are given only |
| 28936 | for the first of them. However, some administrators do not want to send out |
| 28937 | this much information. You can suppress the details by adding "/no_details" to |
| 28938 | the ACL statement that requests sender verification. For example: |
| 28939 | |
| 28940 | verify = sender/no_details |
| 28941 | |
| 28942 | |
| 28943 | 43.49 Redirection while verifying |
| 28944 | --------------------------------- |
| 28945 | |
| 28946 | A dilemma arises when a local address is redirected by aliasing or forwarding |
| 28947 | during verification: should the generated addresses themselves be verified, or |
| 28948 | should the successful expansion of the original address be enough to verify it? |
| 28949 | By default, Exim takes the following pragmatic approach: |
| 28950 | |
| 28951 | * When an incoming address is redirected to just one child address, |
| 28952 | verification continues with the child address, and if that fails to verify, |
| 28953 | the original verification also fails. |
| 28954 | |
| 28955 | * When an incoming address is redirected to more than one child address, |
| 28956 | verification does not continue. A success result is returned. |
| 28957 | |
| 28958 | This seems the most reasonable behaviour for the common use of aliasing as a |
| 28959 | way of redirecting different local parts to the same mailbox. It means, for |
| 28960 | example, that a pair of alias entries of the form |
| 28961 | |
| 28962 | A.Wol: aw123 |
| 28963 | aw123: :fail: Gone away, no forwarding address |
| 28964 | |
| 28965 | work as expected, with both local parts causing verification failure. When a |
| 28966 | redirection generates more than one address, the behaviour is more like a |
| 28967 | mailing list, where the existence of the alias itself is sufficient for |
| 28968 | verification to succeed. |
| 28969 | |
| 28970 | It is possible, however, to change the default behaviour so that all successful |
| 28971 | redirections count as successful verifications, however many new addresses are |
| 28972 | generated. This is specified by the success_on_redirect verification option. |
| 28973 | For example: |
| 28974 | |
| 28975 | require verify = recipient/success_on_redirect/callout=10s |
| 28976 | |
| 28977 | In this example, verification succeeds if a router generates a new address, and |
| 28978 | the callout does not occur, because no address was routed to a remote host. |
| 28979 | |
| 28980 | When verification is being tested via the -bv option, the treatment of |
| 28981 | redirections is as just described, unless the -v or any debugging option is |
| 28982 | also specified. In that case, full verification is done for every generated |
| 28983 | address and a report is output for each of them. |
| 28984 | |
| 28985 | |
| 28986 | 43.50 Client SMTP authorization (CSA) |
| 28987 | ------------------------------------- |
| 28988 | |
| 28989 | Client SMTP Authorization is a system that allows a site to advertise which |
| 28990 | machines are and are not permitted to send email. This is done by placing |
| 28991 | special SRV records in the DNS; these are looked up using the client's HELO |
| 28992 | domain. At the time of writing, CSA is still an Internet Draft. Client SMTP |
| 28993 | Authorization checks in Exim are performed by the ACL condition: |
| 28994 | |
| 28995 | verify = csa |
| 28996 | |
| 28997 | This fails if the client is not authorized. If there is a DNS problem, or if no |
| 28998 | valid CSA SRV record is found, or if the client is authorized, the condition |
| 28999 | succeeds. These three cases can be distinguished using the expansion variable |
| 29000 | $csa_status, which can take one of the values "fail", "defer", "unknown", or |
| 29001 | "ok". The condition does not itself defer because that would be likely to cause |
| 29002 | problems for legitimate email. |
| 29003 | |
| 29004 | The error messages produced by the CSA code include slightly more detail. If |
| 29005 | $csa_status is "defer", this may be because of problems looking up the CSA SRV |
| 29006 | record, or problems looking up the CSA target address record. There are four |
| 29007 | reasons for $csa_status being "fail": |
| 29008 | |
| 29009 | * The client's host name is explicitly not authorized. |
| 29010 | |
| 29011 | * The client's IP address does not match any of the CSA target IP addresses. |
| 29012 | |
| 29013 | * The client's host name is authorized but it has no valid target IP |
| 29014 | addresses (for example, the target's addresses are IPv6 and the client is |
| 29015 | using IPv4). |
| 29016 | |
| 29017 | * The client's host name has no CSA SRV record but a parent domain has |
| 29018 | asserted that all subdomains must be explicitly authorized. |
| 29019 | |
| 29020 | The csa verification condition can take an argument which is the domain to use |
| 29021 | for the DNS query. The default is: |
| 29022 | |
| 29023 | verify = csa/$sender_helo_name |
| 29024 | |
| 29025 | This implementation includes an extension to CSA. If the query domain is an |
| 29026 | address literal such as [192.0.2.95], or if it is a bare IP address, Exim |
| 29027 | searches for CSA SRV records in the reverse DNS as if the HELO domain was (for |
| 29028 | example) 95.2.0.192.in-addr.arpa. Therefore it is meaningful to say: |
| 29029 | |
| 29030 | verify = csa/$sender_host_address |
| 29031 | |
| 29032 | In fact, this is the check that Exim performs if the client does not say HELO. |
| 29033 | This extension can be turned off by setting the main configuration option |
| 29034 | dns_csa_use_reverse to be false. |
| 29035 | |
| 29036 | If a CSA SRV record is not found for the domain itself, a search is performed |
| 29037 | through its parent domains for a record which might be making assertions about |
| 29038 | subdomains. The maximum depth of this search is limited using the main |
| 29039 | configuration option dns_csa_search_limit, which is 5 by default. Exim does not |
| 29040 | look for CSA SRV records in a top level domain, so the default settings handle |
| 29041 | HELO domains as long as seven (hostname.five.four.three.two.one.com). This |
| 29042 | encompasses the vast majority of legitimate HELO domains. |
| 29043 | |
| 29044 | The dnsdb lookup also has support for CSA. Although dnsdb also supports direct |
| 29045 | SRV lookups, this is not sufficient because of the extra parent domain search |
| 29046 | behaviour of CSA, and (as with PTR lookups) dnsdb also turns IP addresses into |
| 29047 | lookups in the reverse DNS space. The result of a successful lookup such as: |
| 29048 | |
| 29049 | ${lookup dnsdb {csa=$sender_helo_name}} |
| 29050 | |
| 29051 | has two space-separated fields: an authorization code and a target host name. |
| 29052 | The authorization code can be "Y" for yes, "N" for no, "X" for explicit |
| 29053 | authorization required but absent, or "?" for unknown. |
| 29054 | |
| 29055 | |
| 29056 | 43.51 Bounce address tag validation |
| 29057 | ----------------------------------- |
| 29058 | |
| 29059 | Bounce address tag validation (BATV) is a scheme whereby the envelope senders |
| 29060 | of outgoing messages have a cryptographic, timestamped "tag" added to them. |
| 29061 | Genuine incoming bounce messages should therefore always be addressed to |
| 29062 | recipients that have a valid tag. This scheme is a way of detecting unwanted |
| 29063 | bounce messages caused by sender address forgeries (often called "collateral |
| 29064 | spam"), because the recipients of such messages do not include valid tags. |
| 29065 | |
| 29066 | There are two expansion items to help with the implementation of the BATV |
| 29067 | "prvs" (private signature) scheme in an Exim configuration. This scheme signs |
| 29068 | the original envelope sender address by using a simple key to add a hash of the |
| 29069 | address and some time-based randomizing information. The prvs expansion item |
| 29070 | creates a signed address, and the prvscheck expansion item checks one. The |
| 29071 | syntax of these expansion items is described in section 11.5. |
| 29072 | |
| 29073 | As an example, suppose the secret per-address keys are stored in an MySQL |
| 29074 | database. A query to look up the key for an address could be defined as a macro |
| 29075 | like this: |
| 29076 | |
| 29077 | PRVSCHECK_SQL = ${lookup mysql{SELECT secret FROM batv_prvs \ |
| 29078 | WHERE sender='${quote_mysql:$prvscheck_address}'\ |
| 29079 | }{$value}} |
| 29080 | |
| 29081 | Suppose also that the senders who make use of BATV are defined by an address |
| 29082 | list called batv_senders. Then, in the ACL for RCPT commands, you could use |
| 29083 | this: |
| 29084 | |
| 29085 | # Bounces: drop unsigned addresses for BATV senders |
| 29086 | deny message = This address does not send an unsigned reverse path |
| 29087 | senders = : |
| 29088 | recipients = +batv_senders |
| 29089 | |
| 29090 | # Bounces: In case of prvs-signed address, check signature. |
| 29091 | deny message = Invalid reverse path signature. |
| 29092 | senders = : |
| 29093 | condition = ${prvscheck {$local_part@$domain}\ |
| 29094 | {PRVSCHECK_SQL}{1}} |
| 29095 | !condition = $prvscheck_result |
| 29096 | |
| 29097 | The first statement rejects recipients for bounce messages that are addressed |
| 29098 | to plain BATV sender addresses, because it is known that BATV senders do not |
| 29099 | send out messages with plain sender addresses. The second statement rejects |
| 29100 | recipients that are prvs-signed, but with invalid signatures (either because |
| 29101 | the key is wrong, or the signature has timed out). |
| 29102 | |
| 29103 | A non-prvs-signed address is not rejected by the second statement, because the |
| 29104 | prvscheck expansion yields an empty string if its first argument is not a |
| 29105 | prvs-signed address, thus causing the condition condition to be false. If the |
| 29106 | first argument is a syntactically valid prvs-signed address, the yield is the |
| 29107 | third string (in this case "1"), whether or not the cryptographic and timeout |
| 29108 | checks succeed. The $prvscheck_result variable contains the result of the |
| 29109 | checks (empty for failure, "1" for success). |
| 29110 | |
| 29111 | There is one more issue you must consider when implementing prvs-signing: you |
| 29112 | have to ensure that the routers accept prvs-signed addresses and deliver them |
| 29113 | correctly. The easiest way to handle this is to use a redirect router to remove |
| 29114 | the signature with a configuration along these lines: |
| 29115 | |
| 29116 | batv_redirect: |
| 29117 | driver = redirect |
| 29118 | data = ${prvscheck {$local_part@$domain}{PRVSCHECK_SQL}} |
| 29119 | |
| 29120 | This works because, if the third argument of prvscheck is empty, the result of |
| 29121 | the expansion of a prvs-signed address is the decoded value of the original |
| 29122 | address. This router should probably be the first of your routers that handles |
| 29123 | local addresses. |
| 29124 | |
| 29125 | To create BATV-signed addresses in the first place, a transport of this form |
| 29126 | can be used: |
| 29127 | |
| 29128 | external_smtp_batv: |
| 29129 | driver = smtp |
| 29130 | return_path = ${prvs {$return_path} \ |
| 29131 | {${lookup mysql{SELECT \ |
| 29132 | secret FROM batv_prvs WHERE \ |
| 29133 | sender='${quote_mysql:$sender_address}'} \ |
| 29134 | {$value}fail}}} |
| 29135 | |
| 29136 | If no key can be found for the existing return path, no signing takes place. |
| 29137 | |
| 29138 | |
| 29139 | 43.52 Using an ACL to control relaying |
| 29140 | -------------------------------------- |
| 29141 | |
| 29142 | An MTA is said to relay a message if it receives it from some host and delivers |
| 29143 | it directly to another host as a result of a remote address contained within |
| 29144 | it. Redirecting a local address via an alias or forward file and then passing |
| 29145 | the message on to another host is not relaying, but a redirection as a result |
| 29146 | of the "percent hack" is. |
| 29147 | |
| 29148 | Two kinds of relaying exist, which are termed "incoming" and "outgoing". A host |
| 29149 | which is acting as a gateway or an MX backup is concerned with incoming |
| 29150 | relaying from arbitrary hosts to a specific set of domains. On the other hand, |
| 29151 | a host which is acting as a smart host for a number of clients is concerned |
| 29152 | with outgoing relaying from those clients to the Internet at large. Often the |
| 29153 | same host is fulfilling both functions, but in principle these two kinds of |
| 29154 | relaying are entirely independent. What is not wanted is the transmission of |
| 29155 | mail from arbitrary remote hosts through your system to arbitrary domains. |
| 29156 | |
| 29157 | You can implement relay control by means of suitable statements in the ACL that |
| 29158 | runs for each RCPT command. For convenience, it is often easiest to use Exim's |
| 29159 | named list facility to define the domains and hosts involved. For example, |
| 29160 | suppose you want to do the following: |
| 29161 | |
| 29162 | * Deliver a number of domains to mailboxes on the local host (or process them |
| 29163 | locally in some other way). Let's say these are my.dom1.example and |
| 29164 | my.dom2.example. |
| 29165 | |
| 29166 | * Relay mail for a number of other domains for which you are the secondary |
| 29167 | MX. These might be friend1.example and friend2.example. |
| 29168 | |
| 29169 | * Relay mail from the hosts on your local LAN, to whatever domains are |
| 29170 | involved. Suppose your LAN is 192.168.45.0/24. |
| 29171 | |
| 29172 | In the main part of the configuration, you put the following definitions: |
| 29173 | |
| 29174 | domainlist local_domains = my.dom1.example : my.dom2.example |
| 29175 | domainlist relay_to_domains = friend1.example : friend2.example |
| 29176 | hostlist relay_from_hosts = 192.168.45.0/24 |
| 29177 | |
| 29178 | Now you can use these definitions in the ACL that is run for every RCPT |
| 29179 | command: |
| 29180 | |
| 29181 | acl_check_rcpt: |
| 29182 | accept domains = +local_domains : +relay_to_domains |
| 29183 | accept hosts = +relay_from_hosts |
| 29184 | |
| 29185 | The first statement accepts any RCPT command that contains an address in the |
| 29186 | local or relay domains. For any other domain, control passes to the second |
| 29187 | statement, which accepts the command only if it comes from one of the relay |
| 29188 | hosts. In practice, you will probably want to make your ACL more sophisticated |
| 29189 | than this, for example, by including sender and recipient verification. The |
| 29190 | default configuration includes a more comprehensive example, which is described |
| 29191 | in chapter 7. |
| 29192 | |
| 29193 | |
| 29194 | 43.53 Checking a relay configuration |
| 29195 | ------------------------------------ |
| 29196 | |
| 29197 | You can check the relay characteristics of your configuration in the same way |
| 29198 | that you can test any ACL behaviour for an incoming SMTP connection, by using |
| 29199 | the -bh option to run a fake SMTP session with which you interact. |
| 29200 | |
| 29201 | |
| 29202 | |
| 29203 | =============================================================================== |
| 29204 | 44. CONTENT SCANNING AT ACL TIME |
| 29205 | |
| 29206 | The extension of Exim to include content scanning at ACL time, formerly known |
| 29207 | as "exiscan", was originally implemented as a patch by Tom Kistner. The code |
| 29208 | was integrated into the main source for Exim release 4.50, and Tom continues to |
| 29209 | maintain it. Most of the wording of this chapter is taken from Tom's |
| 29210 | specification. |
| 29211 | |
| 29212 | It is also possible to scan the content of messages at other times. The |
| 29213 | local_scan() function (see chapter 45) allows for content scanning after all |
| 29214 | the ACLs have run. A transport filter can be used to scan messages at delivery |
| 29215 | time (see the transport_filter option, described in chapter 24). |
| 29216 | |
| 29217 | If you want to include the ACL-time content-scanning features when you compile |
| 29218 | Exim, you need to arrange for WITH_CONTENT_SCAN to be defined in your Local/ |
| 29219 | Makefile. When you do that, the Exim binary is built with: |
| 29220 | |
| 29221 | * Two additional ACLs (acl_smtp_mime and acl_not_smtp_mime) that are run for |
| 29222 | all MIME parts for SMTP and non-SMTP messages, respectively. |
| 29223 | |
| 29224 | * Additional ACL conditions and modifiers: decode, malware, mime_regex, regex |
| 29225 | , and spam. These can be used in the ACL that is run at the end of message |
| 29226 | reception (the acl_smtp_data ACL). |
| 29227 | |
| 29228 | * An additional control feature ("no_mbox_unspool") that saves spooled copies |
| 29229 | of messages, or parts of messages, for debugging purposes. |
| 29230 | |
| 29231 | * Additional expansion variables that are set in the new ACL and by the new |
| 29232 | conditions. |
| 29233 | |
| 29234 | * Two new main configuration options: av_scanner and spamd_address. |
| 29235 | |
| 29236 | Content-scanning is continually evolving, and new features are still being |
| 29237 | added. While such features are still unstable and liable to incompatible |
| 29238 | changes, they are made available in Exim by setting options whose names begin |
| 29239 | EXPERIMENTAL_ in Local/Makefile. Such features are not documented in this |
| 29240 | manual. You can find out about them by reading the file called doc/ |
| 29241 | experimental.txt. |
| 29242 | |
| 29243 | All the content-scanning facilities work on a MBOX copy of the message that is |
| 29244 | temporarily created in a file called: |
| 29245 | |
| 29246 | <spool_directory>/scan/<message_id>/<message_id>.eml |
| 29247 | |
| 29248 | The .eml extension is a friendly hint to virus scanners that they can expect an |
| 29249 | MBOX-like structure inside that file. The file is created when the first |
| 29250 | content scanning facility is called. Subsequent calls to content scanning |
| 29251 | conditions open the same file again. The directory is recursively removed when |
| 29252 | the acl_smtp_data ACL has finished running, unless |
| 29253 | |
| 29254 | control = no_mbox_unspool |
| 29255 | |
| 29256 | has been encountered. When the MIME ACL decodes files, they are put into the |
| 29257 | same directory by default. |
| 29258 | |
| 29259 | |
| 29260 | 44.1 Scanning for viruses |
| 29261 | ------------------------- |
| 29262 | |
| 29263 | The malware ACL condition lets you connect virus scanner software to Exim. It |
| 29264 | supports a "generic" interface to scanners called via the shell, and |
| 29265 | specialized interfaces for "daemon" type virus scanners, which are resident in |
| 29266 | memory and thus are much faster. |
| 29267 | |
| 29268 | A timeout of 2 minutes is applied to a scanner call (by default); if it expires |
| 29269 | then a defer action is taken. |
| 29270 | |
| 29271 | You can set the av_scanner option in the main part of the configuration to |
| 29272 | specify which scanner to use, together with any additional options that are |
| 29273 | needed. The basic syntax is as follows: |
| 29274 | |
| 29275 | av_scanner = <scanner-type>:<option1>:<option2>:[...] |
| 29276 | |
| 29277 | If you do not set av_scanner, it defaults to |
| 29278 | |
| 29279 | av_scanner = sophie:/var/run/sophie |
| 29280 | |
| 29281 | If the value of av_scanner starts with a dollar character, it is expanded |
| 29282 | before use. The usual list-parsing of the content (see 6.20) applies. The |
| 29283 | following scanner types are supported in this release: |
| 29284 | |
| 29285 | avast |
| 29286 | |
| 29287 | This is the scanner daemon of Avast. It has been tested with Avast Core |
| 29288 | Security (currently at version 1.1.7). You can get a trial version at http: |
| 29289 | //www.avast.com or for Linux at http://www.avast.com/linux-server-antivirus |
| 29290 | . This scanner type takes one option, which can be either a full path to a |
| 29291 | UNIX socket, or host and port specifiers separated by white space. The host |
| 29292 | may be a name or an IP address; the port is either a single number or a |
| 29293 | pair of numbers with a dash between. Any further options are given, on |
| 29294 | separate lines, to the daemon as options before the main scan command. For |
| 29295 | example: |
| 29296 | |
| 29297 | av_scanner = avast:/var/run/avast/scan.sock:FLAGS -fullfiles:SENSITIVITY -pup |
| 29298 | av_scanner = avast:192.168.2.22 5036 |
| 29299 | |
| 29300 | If you omit the argument, the default path /var/run/avast/scan.sock is |
| 29301 | used. If you use a remote host, you need to make Exim's spool directory |
| 29302 | available to it, as the scanner is passed a file path, not file contents. |
| 29303 | For information about available commands and their options you may use |
| 29304 | |
| 29305 | $ socat UNIX:/var/run/avast/scan.sock STDIO: |
| 29306 | FLAGS |
| 29307 | SENSITIVITY |
| 29308 | PACK |
| 29309 | |
| 29310 | aveserver |
| 29311 | |
| 29312 | This is the scanner daemon of Kaspersky Version 5. You can get a trial |
| 29313 | version at http://www.kaspersky.com. This scanner type takes one option, |
| 29314 | which is the path to the daemon's UNIX socket. The default is shown in this |
| 29315 | example: |
| 29316 | |
| 29317 | av_scanner = aveserver:/var/run/aveserver |
| 29318 | |
| 29319 | clamd |
| 29320 | |
| 29321 | This daemon-type scanner is GPL and free. You can get it at http:// |
| 29322 | www.clamav.net/. Some older versions of clamd do not seem to unpack MIME |
| 29323 | containers, so it used to be recommended to unpack MIME attachments in the |
| 29324 | MIME ACL. This is no longer believed to be necessary. |
| 29325 | |
| 29326 | The options are a list of server specifiers, which may be a UNIX socket |
| 29327 | specification, a TCP socket specification, or a (global) option. |
| 29328 | |
| 29329 | A socket specification consists of a space-separated list. For a Unix |
| 29330 | socket the first element is a full path for the socket, for a TCP socket |
| 29331 | the first element is the IP address and the second a port number, Any |
| 29332 | further elements are per-server (non-global) options. These per-server |
| 29333 | options are supported: |
| 29334 | |
| 29335 | retry=<timespec> Retry on connect fail |
| 29336 | |
| 29337 | The "retry" option specifies a time after which a single retry for a failed |
| 29338 | connect is made. The default is to not retry. |
| 29339 | |
| 29340 | If a Unix socket file is specified, only one server is supported. |
| 29341 | |
| 29342 | Examples: |
| 29343 | |
| 29344 | av_scanner = clamd:/opt/clamd/socket |
| 29345 | av_scanner = clamd:192.0.2.3 1234 |
| 29346 | av_scanner = clamd:192.0.2.3 1234:local |
| 29347 | av_scanner = clamd:192.0.2.3 1234 retry=10s |
| 29348 | av_scanner = clamd:192.0.2.3 1234 : 192.0.2.4 1234 |
| 29349 | |
| 29350 | If the value of av_scanner points to a UNIX socket file or contains the |
| 29351 | "local" option, then the ClamAV interface will pass a filename containing |
| 29352 | the data to be scanned, which will should normally result in less I/O |
| 29353 | happening and be more efficient. Normally in the TCP case, the data is |
| 29354 | streamed to ClamAV as Exim does not assume that there is a common |
| 29355 | filesystem with the remote host. There is an option WITH_OLD_CLAMAV_STREAM |
| 29356 | in src/EDITME available, should you be running a version of ClamAV prior to |
| 29357 | 0.95. |
| 29358 | |
| 29359 | The final example shows that multiple TCP targets can be specified. Exim |
| 29360 | will randomly use one for each incoming email (i.e. it load balances them). |
| 29361 | Note that only TCP targets may be used if specifying a list of scanners; a |
| 29362 | UNIX socket cannot be mixed in with TCP targets. If one of the servers |
| 29363 | becomes unavailable, Exim will try the remaining one(s) until it finds one |
| 29364 | that works. When a clamd server becomes unreachable, Exim will log a |
| 29365 | message. Exim does not keep track of scanner state between multiple |
| 29366 | messages, and the scanner selection is random, so the message will get |
| 29367 | logged in the mainlog for each email that the down scanner gets chosen |
| 29368 | first (message wrapped to be readable): |
| 29369 | |
| 29370 | 2013-10-09 14:30:39 1VTumd-0000Y8-BQ malware acl condition: |
| 29371 | clamd: connection to localhost, port 3310 failed |
| 29372 | (Connection refused) |
| 29373 | |
| 29374 | If the option is unset, the default is /tmp/clamd. Thanks to David Saez for |
| 29375 | contributing the code for this scanner. |
| 29376 | |
| 29377 | cmdline |
| 29378 | |
| 29379 | This is the keyword for the generic command line scanner interface. It can |
| 29380 | be used to attach virus scanners that are invoked from the shell. This |
| 29381 | scanner type takes 3 mandatory options: |
| 29382 | |
| 29383 | 1. The full path and name of the scanner binary, with all command line |
| 29384 | options, and a placeholder ("%s") for the directory to scan. |
| 29385 | |
| 29386 | 2. A regular expression to match against the STDOUT and STDERR output of |
| 29387 | the virus scanner. If the expression matches, a virus was found. You |
| 29388 | must make absolutely sure that this expression matches on "virus |
| 29389 | found". This is called the "trigger" expression. |
| 29390 | |
| 29391 | 3. Another regular expression, containing exactly one pair of parentheses, |
| 29392 | to match the name of the virus found in the scanners output. This is |
| 29393 | called the "name" expression. |
| 29394 | |
| 29395 | For example, Sophos Sweep reports a virus on a line like this: |
| 29396 | |
| 29397 | Virus 'W32/Magistr-B' found in file ./those.bat |
| 29398 | |
| 29399 | For the trigger expression, we can match the phrase "found in file". For |
| 29400 | the name expression, we want to extract the W32/Magistr-B string, so we can |
| 29401 | match for the single quotes left and right of it. Altogether, this makes |
| 29402 | the configuration setting: |
| 29403 | |
| 29404 | av_scanner = cmdline:\ |
| 29405 | /path/to/sweep -ss -all -rec -archive %s:\ |
| 29406 | found in file:'(.+)' |
| 29407 | |
| 29408 | drweb |
| 29409 | |
| 29410 | The DrWeb daemon scanner (http://www.sald.com/) interface takes one option, |
| 29411 | either a full path to a UNIX socket, or host and port specifiers separated |
| 29412 | by white space. The host may be a name or an IP address; the port is either |
| 29413 | a single number or a pair of numbers with a dash between. For example: |
| 29414 | |
| 29415 | av_scanner = drweb:/var/run/drwebd.sock |
| 29416 | av_scanner = drweb:192.168.2.20 31337 |
| 29417 | |
| 29418 | If you omit the argument, the default path /usr/local/drweb/run/drwebd.sock |
| 29419 | is used. Thanks to Alex Miller for contributing the code for this scanner. |
| 29420 | |
| 29421 | f-protd |
| 29422 | |
| 29423 | The f-protd scanner is accessed via HTTP over TCP. One argument is taken, |
| 29424 | being a space-separated hostname and port number (or port-range). For |
| 29425 | example: |
| 29426 | |
| 29427 | av_scanner = f-protd:localhost 10200-10204 |
| 29428 | |
| 29429 | If you omit the argument, the default values show above are used. |
| 29430 | |
| 29431 | fsecure |
| 29432 | |
| 29433 | The F-Secure daemon scanner (http://www.f-secure.com) takes one argument |
| 29434 | which is the path to a UNIX socket. For example: |
| 29435 | |
| 29436 | av_scanner = fsecure:/path/to/.fsav |
| 29437 | |
| 29438 | If no argument is given, the default is /var/run/.fsav. Thanks to Johan |
| 29439 | Thelmen for contributing the code for this scanner. |
| 29440 | |
| 29441 | kavdaemon |
| 29442 | |
| 29443 | This is the scanner daemon of Kaspersky Version 4. This version of the |
| 29444 | Kaspersky scanner is outdated. Please upgrade (see aveserver above). This |
| 29445 | scanner type takes one option, which is the path to the daemon's UNIX |
| 29446 | socket. For example: |
| 29447 | |
| 29448 | av_scanner = kavdaemon:/opt/AVP/AvpCtl |
| 29449 | |
| 29450 | The default path is /var/run/AvpCtl. |
| 29451 | |
| 29452 | mksd |
| 29453 | |
| 29454 | This is a daemon type scanner that is aimed mainly at Polish users, though |
| 29455 | some parts of documentation are now available in English. You can get it at |
| 29456 | http://linux.mks.com.pl/. The only option for this scanner type is the |
| 29457 | maximum number of processes used simultaneously to scan the attachments, |
| 29458 | provided that mksd has been run with at least the same number of child |
| 29459 | processes. For example: |
| 29460 | |
| 29461 | av_scanner = mksd:2 |
| 29462 | |
| 29463 | You can safely omit this option (the default value is 1). |
| 29464 | |
| 29465 | sock |
| 29466 | |
| 29467 | This is a general-purpose way of talking to simple scanner daemons running |
| 29468 | on the local machine. There are four options: an address (which may be an |
| 29469 | IP address and port, or the path of a Unix socket), a commandline to send |
| 29470 | (may include a single %s which will be replaced with the path to the mail |
| 29471 | file to be scanned), an RE to trigger on from the returned data, an RE to |
| 29472 | extract malware_name from the returned data. For example: |
| 29473 | |
| 29474 | av_scanner = sock:127.0.0.1 6001:%s:(SPAM|VIRUS):(.*)\$ |
| 29475 | |
| 29476 | Default for the socket specifier is /tmp/malware.sock. Default for the |
| 29477 | commandline is %s\n. Both regular-expressions are required. |
| 29478 | |
| 29479 | sophie |
| 29480 | |
| 29481 | Sophie is a daemon that uses Sophos' libsavi library to scan for viruses. |
| 29482 | You can get Sophie at http://www.clanfield.info/sophie/. The only option |
| 29483 | for this scanner type is the path to the UNIX socket that Sophie uses for |
| 29484 | client communication. For example: |
| 29485 | |
| 29486 | av_scanner = sophie:/tmp/sophie |
| 29487 | |
| 29488 | The default path is /var/run/sophie, so if you are using this, you can omit |
| 29489 | the option. |
| 29490 | |
| 29491 | When av_scanner is correctly set, you can use the malware condition in the DATA |
| 29492 | ACL. Note: You cannot use the malware condition in the MIME ACL. |
| 29493 | |
| 29494 | The av_scanner option is expanded each time malware is called. This makes it |
| 29495 | possible to use different scanners. See further below for an example. The |
| 29496 | malware condition caches its results, so when you use it multiple times for the |
| 29497 | same message, the actual scanning process is only carried out once. However, |
| 29498 | using expandable items in av_scanner disables this caching, in which case each |
| 29499 | use of the malware condition causes a new scan of the message. |
| 29500 | |
| 29501 | The malware condition takes a right-hand argument that is expanded before use |
| 29502 | and taken as a list, slash-separated by default. The first element can then be |
| 29503 | one of |
| 29504 | |
| 29505 | * "true", "*", or "1", in which case the message is scanned for viruses. The |
| 29506 | condition succeeds if a virus was found, and fail otherwise. This is the |
| 29507 | recommended usage. |
| 29508 | |
| 29509 | * "false" or "0" or an empty string, in which case no scanning is done and |
| 29510 | the condition fails immediately. |
| 29511 | |
| 29512 | * A regular expression, in which case the message is scanned for viruses. The |
| 29513 | condition succeeds if a virus is found and its name matches the regular |
| 29514 | expression. This allows you to take special actions on certain types of |
| 29515 | virus. Note that "/" characters in the RE must be doubled due to the |
| 29516 | list-processing, unless the separator is changed (in the usual way). |
| 29517 | |
| 29518 | You can append a "defer_ok" element to the malware argument list to accept |
| 29519 | messages even if there is a problem with the virus scanner. Otherwise, such a |
| 29520 | problem causes the ACL to defer. |
| 29521 | |
| 29522 | You can append a "tmo=<val>" element to the malware argument list to specify a |
| 29523 | non-default timeout. The default is two minutes. For example: |
| 29524 | |
| 29525 | malware = * / defer_ok / tmo=10s |
| 29526 | |
| 29527 | A timeout causes the ACL to defer. |
| 29528 | |
| 29529 | When a connection is made to the scanner the expansion variable |
| 29530 | $callout_address is set to record the actual address used. |
| 29531 | |
| 29532 | When a virus is found, the condition sets up an expansion variable called |
| 29533 | $malware_name that contains the name of the virus. You can use it in a message |
| 29534 | modifier that specifies the error returned to the sender, and/or in logging |
| 29535 | data. |
| 29536 | |
| 29537 | Beware the interaction of Exim's message_size_limit with any size limits |
| 29538 | imposed by your anti-virus scanner. |
| 29539 | |
| 29540 | Here is a very simple scanning example: |
| 29541 | |
| 29542 | deny message = This message contains malware ($malware_name) |
| 29543 | malware = * |
| 29544 | |
| 29545 | The next example accepts messages when there is a problem with the scanner: |
| 29546 | |
| 29547 | deny message = This message contains malware ($malware_name) |
| 29548 | malware = */defer_ok |
| 29549 | |
| 29550 | The next example shows how to use an ACL variable to scan with both sophie and |
| 29551 | aveserver. It assumes you have set: |
| 29552 | |
| 29553 | av_scanner = $acl_m0 |
| 29554 | |
| 29555 | in the main Exim configuration. |
| 29556 | |
| 29557 | deny message = This message contains malware ($malware_name) |
| 29558 | set acl_m0 = sophie |
| 29559 | malware = * |
| 29560 | |
| 29561 | deny message = This message contains malware ($malware_name) |
| 29562 | set acl_m0 = aveserver |
| 29563 | malware = * |
| 29564 | |
| 29565 | |
| 29566 | 44.2 Scanning with SpamAssassin and Rspamd |
| 29567 | ------------------------------------------ |
| 29568 | |
| 29569 | The spam ACL condition calls SpamAssassin's spamd daemon to get a spam score |
| 29570 | and a report for the message. Support is also provided for Rspamd. |
| 29571 | |
| 29572 | For more information about installation and configuration of SpamAssassin or |
| 29573 | Rspamd refer to their respective websites at http://spamassassin.apache.org and |
| 29574 | http://www.rspamd.com |
| 29575 | |
| 29576 | SpamAssassin can be installed with CPAN by running: |
| 29577 | |
| 29578 | perl -MCPAN -e 'install Mail::SpamAssassin' |
| 29579 | |
| 29580 | SpamAssassin has its own set of configuration files. Please review its |
| 29581 | documentation to see how you can tweak it. The default installation should work |
| 29582 | nicely, however. |
| 29583 | |
| 29584 | By default, SpamAssassin listens on 127.0.0.1, TCP port 783 and if you intend |
| 29585 | to use an instance running on the local host you do not need to set |
| 29586 | spamd_address. If you intend to use another host or port for SpamAssassin, you |
| 29587 | must set the spamd_address option in the global part of the Exim configuration |
| 29588 | as follows (example): |
| 29589 | |
| 29590 | spamd_address = 192.168.99.45 387 |
| 29591 | |
| 29592 | The SpamAssassin protocol relies on a TCP half-close from the client. If your |
| 29593 | SpamAssassin client side is running a Linux system with an iptables firewall, |
| 29594 | consider setting net.netfilter.nf_conntrack_tcp_timeout_close_wait to at least |
| 29595 | the timeout, Exim uses when waiting for a response from the SpamAssassin server |
| 29596 | (currently defaulting to 120s). With a lower value the Linux connection |
| 29597 | tracking may consider your half-closed connection as dead too soon. |
| 29598 | |
| 29599 | To use Rspamd (which by default listens on all local addresses on TCP port |
| 29600 | 11333) you should add variant=rspamd after the address/port pair, for example: |
| 29601 | |
| 29602 | spamd_address = 127.0.0.1 11333 variant=rspamd |
| 29603 | |
| 29604 | As of version 2.60, SpamAssassin also supports communication over UNIX sockets. |
| 29605 | If you want to us these, supply spamd_address with an absolute file name |
| 29606 | instead of an address/port pair: |
| 29607 | |
| 29608 | spamd_address = /var/run/spamd_socket |
| 29609 | |
| 29610 | You can have multiple spamd servers to improve scalability. These can reside on |
| 29611 | other hardware reachable over the network. To specify multiple spamd servers, |
| 29612 | put multiple address/port pairs in the spamd_address option, separated with |
| 29613 | colons (the separator can be changed in the usual way): |
| 29614 | |
| 29615 | spamd_address = 192.168.2.10 783 : \ |
| 29616 | 192.168.2.11 783 : \ |
| 29617 | 192.168.2.12 783 |
| 29618 | |
| 29619 | Up to 32 spamd servers are supported. When a server fails to respond to the |
| 29620 | connection attempt, all other servers are tried until one succeeds. If no |
| 29621 | server responds, the spam condition defers. |
| 29622 | |
| 29623 | Unix and TCP socket specifications may be mixed in any order. Each element of |
| 29624 | the list is a list itself, space-separated by default and changeable in the |
| 29625 | usual way; take care to not double the separator. |
| 29626 | |
| 29627 | For TCP socket specifications a host name or IP (v4 or v6, but subject to |
| 29628 | list-separator quoting rules) address can be used, and the port can be one or a |
| 29629 | dash-separated pair. In the latter case, the range is tried in strict order. |
| 29630 | |
| 29631 | Elements after the first for Unix sockets, or second for TCP socket, are |
| 29632 | options. The supported options are: |
| 29633 | |
| 29634 | pri=<priority> Selection priority |
| 29635 | weight=<value> Selection bias |
| 29636 | time=<start>-<end> Use only between these times of day |
| 29637 | retry=<timespec> Retry on connect fail |
| 29638 | tmo=<timespec> Connection time limit |
| 29639 | variant=rspamd Use Rspamd rather than SpamAssassin protocol |
| 29640 | |
| 29641 | The "pri" option specifies a priority for the server within the list, higher |
| 29642 | values being tried first. The default priority is 1. |
| 29643 | |
| 29644 | The "weight" option specifies a selection bias. Within a priority set servers |
| 29645 | are queried in a random fashion, weighted by this value. The default value for |
| 29646 | selection bias is 1. |
| 29647 | |
| 29648 | Time specifications for the "time" option are <hour>.<minute>.<second> in the |
| 29649 | local time zone; each element being one or more digits. Either the seconds or |
| 29650 | both minutes and seconds, plus the leading "." characters, may be omitted and |
| 29651 | will be taken as zero. |
| 29652 | |
| 29653 | Timeout specifications for the "retry" and "tmo" options are the usual Exim |
| 29654 | time interval standard, e.g. "20s" or "1m". |
| 29655 | |
| 29656 | The "tmo" option specifies an overall timeout for communication. The default |
| 29657 | value is two minutes. |
| 29658 | |
| 29659 | The "retry" option specifies a time after which a single retry for a failed |
| 29660 | connect is made. The default is to not retry. |
| 29661 | |
| 29662 | The spamd_address variable is expanded before use if it starts with a dollar |
| 29663 | sign. In this case, the expansion may return a string that is used as the list |
| 29664 | so that multiple spamd servers can be the result of an expansion. |
| 29665 | |
| 29666 | When a connection is made to the server the expansion variable $callout_address |
| 29667 | is set to record the actual address used. |
| 29668 | |
| 29669 | |
| 29670 | 44.3 Calling SpamAssassin from an Exim ACL |
| 29671 | ------------------------------------------ |
| 29672 | |
| 29673 | Here is a simple example of the use of the spam condition in a DATA ACL: |
| 29674 | |
| 29675 | deny message = This message was classified as SPAM |
| 29676 | spam = joe |
| 29677 | |
| 29678 | The right-hand side of the spam condition specifies a name. This is relevant if |
| 29679 | you have set up multiple SpamAssassin profiles. If you do not want to scan |
| 29680 | using a specific profile, but rather use the SpamAssassin system-wide default |
| 29681 | profile, you can scan for an unknown name, or simply use "nobody". Rspamd does |
| 29682 | not use this setting. However, you must put something on the right-hand side. |
| 29683 | |
| 29684 | The name allows you to use per-domain or per-user antispam profiles in |
| 29685 | principle, but this is not straightforward in practice, because a message may |
| 29686 | have multiple recipients, not necessarily all in the same domain. Because the |
| 29687 | spam condition has to be called from a DATA-time ACL in order to be able to |
| 29688 | read the contents of the message, the variables $local_part and $domain are not |
| 29689 | set. Careful enforcement of single-recipient messages (e.g. by responding with |
| 29690 | defer in the recipient ACL for all recipients after the first), or the use of |
| 29691 | PRDR, are needed to use this feature. |
| 29692 | |
| 29693 | The right-hand side of the spam condition is expanded before being used, so you |
| 29694 | can put lookups or conditions there. When the right-hand side evaluates to "0" |
| 29695 | or "false", no scanning is done and the condition fails immediately. |
| 29696 | |
| 29697 | Scanning with SpamAssassin uses a lot of resources. If you scan every message, |
| 29698 | large ones may cause significant performance degradation. As most spam messages |
| 29699 | are quite small, it is recommended that you do not scan the big ones. For |
| 29700 | example: |
| 29701 | |
| 29702 | deny message = This message was classified as SPAM |
| 29703 | condition = ${if < {$message_size}{10K}} |
| 29704 | spam = nobody |
| 29705 | |
| 29706 | The spam condition returns true if the threshold specified in the user's |
| 29707 | SpamAssassin profile has been matched or exceeded. If you want to use the spam |
| 29708 | condition for its side effects (see the variables below), you can make it |
| 29709 | always return "true" by appending ":true" to the username. |
| 29710 | |
| 29711 | When the spam condition is run, it sets up a number of expansion variables. |
| 29712 | Except for $spam_report, these variables are saved with the received message so |
| 29713 | are available for use at delivery time. |
| 29714 | |
| 29715 | $spam_score |
| 29716 | |
| 29717 | The spam score of the message, for example "3.4" or "30.5". This is useful |
| 29718 | for inclusion in log or reject messages. |
| 29719 | |
| 29720 | $spam_score_int |
| 29721 | |
| 29722 | The spam score of the message, multiplied by ten, as an integer value. For |
| 29723 | example "34" or "305". It may appear to disagree with $spam_score because |
| 29724 | $spam_score is rounded and $spam_score_int is truncated. The integer value |
| 29725 | is useful for numeric comparisons in conditions. |
| 29726 | |
| 29727 | $spam_bar |
| 29728 | |
| 29729 | A string consisting of a number of "+" or "-" characters, representing the |
| 29730 | integer part of the spam score value. A spam score of 4.4 would have a |
| 29731 | $spam_bar value of "++++". This is useful for inclusion in warning headers, |
| 29732 | since MUAs can match on such strings. The maximum length of the spam bar is |
| 29733 | 50 characters. |
| 29734 | |
| 29735 | $spam_report |
| 29736 | |
| 29737 | A multiline text table, containing the full SpamAssassin report for the |
| 29738 | message. Useful for inclusion in headers or reject messages. This variable |
| 29739 | is only usable in a DATA-time ACL. Beware that SpamAssassin may return |
| 29740 | non-ASCII characters, especially when running in country-specific locales, |
| 29741 | which are not legal unencoded in headers. |
| 29742 | |
| 29743 | $spam_action |
| 29744 | |
| 29745 | For SpamAssassin either 'reject' or 'no action' depending on the spam score |
| 29746 | versus threshold. For Rspamd, the recommended action. |
| 29747 | |
| 29748 | The spam condition caches its results unless expansion in spamd_address was |
| 29749 | used. If you call it again with the same user name, it does not scan again, but |
| 29750 | rather returns the same values as before. |
| 29751 | |
| 29752 | The spam condition returns DEFER if there is any error while running the |
| 29753 | message through SpamAssassin or if the expansion of spamd_address failed. If |
| 29754 | you want to treat DEFER as FAIL (to pass on to the next ACL statement block), |
| 29755 | append "/defer_ok" to the right-hand side of the spam condition, like this: |
| 29756 | |
| 29757 | deny message = This message was classified as SPAM |
| 29758 | spam = joe/defer_ok |
| 29759 | |
| 29760 | This causes messages to be accepted even if there is a problem with spamd. |
| 29761 | |
| 29762 | Here is a longer, commented example of the use of the spam condition: |
| 29763 | |
| 29764 | # put headers in all messages (no matter if spam or not) |
| 29765 | warn spam = nobody:true |
| 29766 | add_header = X-Spam-Score: $spam_score ($spam_bar) |
| 29767 | add_header = X-Spam-Report: $spam_report |
| 29768 | |
| 29769 | # add second subject line with *SPAM* marker when message |
| 29770 | # is over threshold |
| 29771 | warn spam = nobody |
| 29772 | add_header = Subject: *SPAM* $h_Subject: |
| 29773 | |
| 29774 | # reject spam at high scores (> 12) |
| 29775 | deny message = This message scored $spam_score spam points. |
| 29776 | spam = nobody:true |
| 29777 | condition = ${if >{$spam_score_int}{120}{1}{0}} |
| 29778 | |
| 29779 | |
| 29780 | 44.4 Scanning MIME parts |
| 29781 | ------------------------ |
| 29782 | |
| 29783 | The acl_smtp_mime global option specifies an ACL that is called once for each |
| 29784 | MIME part of an SMTP message, including multipart types, in the sequence of |
| 29785 | their position in the message. Similarly, the acl_not_smtp_mime option |
| 29786 | specifies an ACL that is used for the MIME parts of non-SMTP messages. These |
| 29787 | options may both refer to the same ACL if you want the same processing in both |
| 29788 | cases. |
| 29789 | |
| 29790 | These ACLs are called (possibly many times) just before the acl_smtp_data ACL |
| 29791 | in the case of an SMTP message, or just before the acl_not_smtp ACL in the case |
| 29792 | of a non-SMTP message. However, a MIME ACL is called only if the message |
| 29793 | contains a Content-Type: header line. When a call to a MIME ACL does not yield |
| 29794 | "accept", ACL processing is aborted and the appropriate result code is sent to |
| 29795 | the client. In the case of an SMTP message, the acl_smtp_data ACL is not called |
| 29796 | when this happens. |
| 29797 | |
| 29798 | You cannot use the malware or spam conditions in a MIME ACL; these can only be |
| 29799 | used in the DATA or non-SMTP ACLs. However, you can use the regex condition to |
| 29800 | match against the raw MIME part. You can also use the mime_regex condition to |
| 29801 | match against the decoded MIME part (see section 44.5). |
| 29802 | |
| 29803 | At the start of a MIME ACL, a number of variables are set from the header |
| 29804 | information for the relevant MIME part. These are described below. The contents |
| 29805 | of the MIME part are not by default decoded into a disk file except for MIME |
| 29806 | parts whose content-type is "message/rfc822". If you want to decode a MIME part |
| 29807 | into a disk file, you can use the decode condition. The general syntax is: |
| 29808 | |
| 29809 | decode = [/<path>/]<filename> |
| 29810 | |
| 29811 | The right hand side is expanded before use. After expansion, the value can be: |
| 29812 | |
| 29813 | 1. "0" or "false", in which case no decoding is done. |
| 29814 | |
| 29815 | 2. The string "default". In that case, the file is put in the temporary |
| 29816 | "default" directory <spool_directory>/scan/<message_id>/ with a sequential |
| 29817 | file name consisting of the message id and a sequence number. The full path |
| 29818 | and name is available in $mime_decoded_filename after decoding. |
| 29819 | |
| 29820 | 3. A full path name starting with a slash. If the full name is an existing |
| 29821 | directory, it is used as a replacement for the default directory. The |
| 29822 | filename is then sequentially assigned. If the path does not exist, it is |
| 29823 | used as the full path and file name. |
| 29824 | |
| 29825 | 4. If the string does not start with a slash, it is used as the filename, and |
| 29826 | the default path is then used. |
| 29827 | |
| 29828 | The decode condition normally succeeds. It is only false for syntax errors or |
| 29829 | unusual circumstances such as memory shortages. You can easily decode a file |
| 29830 | with its original, proposed filename using |
| 29831 | |
| 29832 | decode = $mime_filename |
| 29833 | |
| 29834 | However, you should keep in mind that $mime_filename might contain anything. If |
| 29835 | you place files outside of the default path, they are not automatically |
| 29836 | unlinked. |
| 29837 | |
| 29838 | For RFC822 attachments (these are messages attached to messages, with a |
| 29839 | content-type of "message/rfc822"), the ACL is called again in the same manner |
| 29840 | as for the primary message, only that the $mime_is_rfc822 expansion variable is |
| 29841 | set (see below). Attached messages are always decoded to disk before being |
| 29842 | checked, and the files are unlinked once the check is done. |
| 29843 | |
| 29844 | The MIME ACL supports the regex and mime_regex conditions. These can be used to |
| 29845 | match regular expressions against raw and decoded MIME parts, respectively. |
| 29846 | They are described in section 44.5. |
| 29847 | |
| 29848 | The following list describes all expansion variables that are available in the |
| 29849 | MIME ACL: |
| 29850 | |
| 29851 | $mime_boundary |
| 29852 | |
| 29853 | If the current part is a multipart (see $mime_is_multipart) below, it |
| 29854 | should have a boundary string, which is stored in this variable. If the |
| 29855 | current part has no boundary parameter in the Content-Type: header, this |
| 29856 | variable contains the empty string. |
| 29857 | |
| 29858 | $mime_charset |
| 29859 | |
| 29860 | This variable contains the character set identifier, if one was found in |
| 29861 | the Content-Type: header. Examples for charset identifiers are: |
| 29862 | |
| 29863 | us-ascii |
| 29864 | gb2312 (Chinese) |
| 29865 | iso-8859-1 |
| 29866 | |
| 29867 | Please note that this value is not normalized, so you should do matches |
| 29868 | case-insensitively. |
| 29869 | |
| 29870 | $mime_content_description |
| 29871 | |
| 29872 | This variable contains the normalized content of the Content-Description: |
| 29873 | header. It can contain a human-readable description of the parts content. |
| 29874 | Some implementations repeat the filename for attachments here, but they are |
| 29875 | usually only used for display purposes. |
| 29876 | |
| 29877 | $mime_content_disposition |
| 29878 | |
| 29879 | This variable contains the normalized content of the Content-Disposition: |
| 29880 | header. You can expect strings like "attachment" or "inline" here. |
| 29881 | |
| 29882 | $mime_content_id |
| 29883 | |
| 29884 | This variable contains the normalized content of the Content-ID: header. |
| 29885 | This is a unique ID that can be used to reference a part from another part. |
| 29886 | |
| 29887 | $mime_content_size |
| 29888 | |
| 29889 | This variable is set only after the decode modifier (see above) has been |
| 29890 | successfully run. It contains the size of the decoded part in kilobytes. |
| 29891 | The size is always rounded up to full kilobytes, so only a completely empty |
| 29892 | part has a $mime_content_size of zero. |
| 29893 | |
| 29894 | $mime_content_transfer_encoding |
| 29895 | |
| 29896 | This variable contains the normalized content of the |
| 29897 | Content-transfer-encoding: header. This is a symbolic name for an encoding |
| 29898 | type. Typical values are "base64" and "quoted-printable". |
| 29899 | |
| 29900 | $mime_content_type |
| 29901 | |
| 29902 | If the MIME part has a Content-Type: header, this variable contains its |
| 29903 | value, lowercased, and without any options (like "name" or "charset"). Here |
| 29904 | are some examples of popular MIME types, as they may appear in this |
| 29905 | variable: |
| 29906 | |
| 29907 | text/plain |
| 29908 | text/html |
| 29909 | application/octet-stream |
| 29910 | image/jpeg |
| 29911 | audio/midi |
| 29912 | |
| 29913 | If the MIME part has no Content-Type: header, this variable contains the |
| 29914 | empty string. |
| 29915 | |
| 29916 | $mime_decoded_filename |
| 29917 | |
| 29918 | This variable is set only after the decode modifier (see above) has been |
| 29919 | successfully run. It contains the full path and file name of the file |
| 29920 | containing the decoded data. |
| 29921 | |
| 29922 | $mime_filename |
| 29923 | |
| 29924 | This is perhaps the most important of the MIME variables. It contains a |
| 29925 | proposed filename for an attachment, if one was found in either the |
| 29926 | Content-Type: or Content-Disposition: headers. The filename will be RFC2047 |
| 29927 | or RFC2231 decoded, but no additional sanity checks are done. If no |
| 29928 | filename was found, this variable contains the empty string. |
| 29929 | |
| 29930 | $mime_is_coverletter |
| 29931 | |
| 29932 | This variable attempts to differentiate the "cover letter" of an e-mail |
| 29933 | from attached data. It can be used to clamp down on flashy or unnecessarily |
| 29934 | encoded content in the cover letter, while not restricting attachments at |
| 29935 | all. |
| 29936 | |
| 29937 | The variable contains 1 (true) for a MIME part believed to be part of the |
| 29938 | cover letter, and 0 (false) for an attachment. At present, the algorithm is |
| 29939 | as follows: |
| 29940 | |
| 29941 | 1. The outermost MIME part of a message is always a cover letter. |
| 29942 | |
| 29943 | 2. If a multipart/alternative or multipart/related MIME part is a cover |
| 29944 | letter, so are all MIME subparts within that multipart. |
| 29945 | |
| 29946 | 3. If any other multipart is a cover letter, the first subpart is a cover |
| 29947 | letter, and the rest are attachments. |
| 29948 | |
| 29949 | 4. All parts contained within an attachment multipart are attachments. |
| 29950 | |
| 29951 | As an example, the following will ban "HTML mail" (including that sent with |
| 29952 | alternative plain text), while allowing HTML files to be attached. HTML |
| 29953 | coverletter mail attached to non-HMTL coverletter mail will also be |
| 29954 | allowed: |
| 29955 | |
| 29956 | deny message = HTML mail is not accepted here |
| 29957 | !condition = $mime_is_rfc822 |
| 29958 | condition = $mime_is_coverletter |
| 29959 | condition = ${if eq{$mime_content_type}{text/html}{1}{0}} |
| 29960 | |
| 29961 | $mime_is_multipart |
| 29962 | |
| 29963 | This variable has the value 1 (true) when the current part has the main |
| 29964 | type "multipart", for example "multipart/alternative" or "multipart/mixed". |
| 29965 | Since multipart entities only serve as containers for other parts, you may |
| 29966 | not want to carry out specific actions on them. |
| 29967 | |
| 29968 | $mime_is_rfc822 |
| 29969 | |
| 29970 | This variable has the value 1 (true) if the current part is not a part of |
| 29971 | the checked message itself, but part of an attached message. Attached |
| 29972 | message decoding is fully recursive. |
| 29973 | |
| 29974 | $mime_part_count |
| 29975 | |
| 29976 | This variable is a counter that is raised for each processed MIME part. It |
| 29977 | starts at zero for the very first part (which is usually a multipart). The |
| 29978 | counter is per-message, so it is reset when processing RFC822 attachments |
| 29979 | (see $mime_is_rfc822). The counter stays set after acl_smtp_mime is |
| 29980 | complete, so you can use it in the DATA ACL to determine the number of MIME |
| 29981 | parts of a message. For non-MIME messages, this variable contains the value |
| 29982 | -1. |
| 29983 | |
| 29984 | |
| 29985 | 44.5 Scanning with regular expressions |
| 29986 | -------------------------------------- |
| 29987 | |
| 29988 | You can specify your own custom regular expression matches on the full body of |
| 29989 | the message, or on individual MIME parts. |
| 29990 | |
| 29991 | The regex condition takes one or more regular expressions as arguments and |
| 29992 | matches them against the full message (when called in the DATA ACL) or a raw |
| 29993 | MIME part (when called in the MIME ACL). The regex condition matches linewise, |
| 29994 | with a maximum line length of 32K characters. That means you cannot have |
| 29995 | multiline matches with the regex condition. |
| 29996 | |
| 29997 | The mime_regex condition can be called only in the MIME ACL. It matches up to |
| 29998 | 32K of decoded content (the whole content at once, not linewise). If the part |
| 29999 | has not been decoded with the decode modifier earlier in the ACL, it is decoded |
| 30000 | automatically when mime_regex is executed (using default path and filename |
| 30001 | values). If the decoded data is larger than 32K, only the first 32K characters |
| 30002 | are checked. |
| 30003 | |
| 30004 | The regular expressions are passed as a colon-separated list. To include a |
| 30005 | literal colon, you must double it. Since the whole right-hand side string is |
| 30006 | expanded before being used, you must also escape dollar signs and backslashes |
| 30007 | with more backslashes, or use the "\N" facility to disable expansion. Here is a |
| 30008 | simple example that contains two regular expressions: |
| 30009 | |
| 30010 | deny message = contains blacklisted regex ($regex_match_string) |
| 30011 | regex = [Mm]ortgage : URGENT BUSINESS PROPOSAL |
| 30012 | |
| 30013 | The conditions returns true if any one of the regular expressions matches. The |
| 30014 | $regex_match_string expansion variable is then set up and contains the matching |
| 30015 | regular expression. The expansion variables $regex1 $regex2 etc are set to any |
| 30016 | substrings captured by the regular expression. |
| 30017 | |
| 30018 | Warning: With large messages, these conditions can be fairly CPU-intensive. |
| 30019 | |
| 30020 | |
| 30021 | |
| 30022 | =============================================================================== |
| 30023 | 45. ADDING A LOCAL SCAN FUNCTION TO EXIM |
| 30024 | |
| 30025 | In these days of email worms, viruses, and ever-increasing spam, some sites |
| 30026 | want to apply a lot of checking to messages before accepting them. |
| 30027 | |
| 30028 | The content scanning extension (chapter 44) has facilities for passing messages |
| 30029 | to external virus and spam scanning software. You can also do a certain amount |
| 30030 | in Exim itself through string expansions and the condition condition in the ACL |
| 30031 | that runs after the SMTP DATA command or the ACL for non-SMTP messages (see |
| 30032 | chapter 43), but this has its limitations. |
| 30033 | |
| 30034 | To allow for further customization to a site's own requirements, there is the |
| 30035 | possibility of linking Exim with a private message scanning function, written |
| 30036 | in C. If you want to run code that is written in something other than C, you |
| 30037 | can of course use a little C stub to call it. |
| 30038 | |
| 30039 | The local scan function is run once for every incoming message, at the point |
| 30040 | when Exim is just about to accept the message. It can therefore be used to |
| 30041 | control non-SMTP messages from local processes as well as messages arriving via |
| 30042 | SMTP. |
| 30043 | |
| 30044 | Exim applies a timeout to calls of the local scan function, and there is an |
| 30045 | option called local_scan_timeout for setting it. The default is 5 minutes. Zero |
| 30046 | means "no timeout". Exim also sets up signal handlers for SIGSEGV, SIGILL, |
| 30047 | SIGFPE, and SIGBUS before calling the local scan function, so that the most |
| 30048 | common types of crash are caught. If the timeout is exceeded or one of those |
| 30049 | signals is caught, the incoming message is rejected with a temporary error if |
| 30050 | it is an SMTP message. For a non-SMTP message, the message is dropped and Exim |
| 30051 | ends with a non-zero code. The incident is logged on the main and reject logs. |
| 30052 | |
| 30053 | |
| 30054 | 45.1 Building Exim to use a local scan function |
| 30055 | ----------------------------------------------- |
| 30056 | |
| 30057 | To make use of the local scan function feature, you must tell Exim where your |
| 30058 | function is before building Exim, by setting LOCAL_SCAN_SOURCE in your Local/ |
| 30059 | Makefile. A recommended place to put it is in the Local directory, so you might |
| 30060 | set |
| 30061 | |
| 30062 | LOCAL_SCAN_SOURCE=Local/local_scan.c |
| 30063 | |
| 30064 | for example. The function must be called local_scan(). It is called by Exim |
| 30065 | after it has received a message, when the success return code is about to be |
| 30066 | sent. This is after all the ACLs have been run. The return code from your |
| 30067 | function controls whether the message is actually accepted or not. There is a |
| 30068 | commented template function (that just accepts the message) in the file _src/ |
| 30069 | local_scan.c_. |
| 30070 | |
| 30071 | If you want to make use of Exim's run time configuration file to set options |
| 30072 | for your local_scan() function, you must also set |
| 30073 | |
| 30074 | LOCAL_SCAN_HAS_OPTIONS=yes |
| 30075 | |
| 30076 | in Local/Makefile (see section 45.3 below). |
| 30077 | |
| 30078 | |
| 30079 | 45.2 API for local_scan() |
| 30080 | ------------------------- |
| 30081 | |
| 30082 | You must include this line near the start of your code: |
| 30083 | |
| 30084 | #include "local_scan.h" |
| 30085 | |
| 30086 | This header file defines a number of variables and other values, and the |
| 30087 | prototype for the function itself. Exim is coded to use unsigned char values |
| 30088 | almost exclusively, and one of the things this header defines is a shorthand |
| 30089 | for "unsigned char" called "uschar". It also contains the following macro |
| 30090 | definitions, to simplify casting character strings and pointers to character |
| 30091 | strings: |
| 30092 | |
| 30093 | #define CS (char *) |
| 30094 | #define CCS (const char *) |
| 30095 | #define CSS (char **) |
| 30096 | #define US (unsigned char *) |
| 30097 | #define CUS (const unsigned char *) |
| 30098 | #define USS (unsigned char **) |
| 30099 | |
| 30100 | The function prototype for local_scan() is: |
| 30101 | |
| 30102 | extern int local_scan(int fd, uschar **return_text); |
| 30103 | |
| 30104 | The arguments are as follows: |
| 30105 | |
| 30106 | * fd is a file descriptor for the file that contains the body of the message |
| 30107 | (the -D file). The file is open for reading and writing, but updating it is |
| 30108 | not recommended. Warning: You must not close this file descriptor. |
| 30109 | |
| 30110 | The descriptor is positioned at character 19 of the file, which is the |
| 30111 | first character of the body itself, because the first 19 characters are the |
| 30112 | message id followed by "-D" and a newline. If you rewind the file, you |
| 30113 | should use the macro SPOOL_DATA_START_OFFSET to reset to the start of the |
| 30114 | data, just in case this changes in some future version. |
| 30115 | |
| 30116 | * return_text is an address which you can use to return a pointer to a text |
| 30117 | string at the end of the function. The value it points to on entry is NULL. |
| 30118 | |
| 30119 | The function must return an int value which is one of the following macros: |
| 30120 | |
| 30121 | "LOCAL_SCAN_ACCEPT" |
| 30122 | |
| 30123 | The message is accepted. If you pass back a string of text, it is saved |
| 30124 | with the message, and made available in the variable $local_scan_data. No |
| 30125 | newlines are permitted (if there are any, they are turned into spaces) and |
| 30126 | the maximum length of text is 1000 characters. |
| 30127 | |
| 30128 | "LOCAL_SCAN_ACCEPT_FREEZE" |
| 30129 | |
| 30130 | This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is |
| 30131 | queued without immediate delivery, and is frozen. |
| 30132 | |
| 30133 | "LOCAL_SCAN_ACCEPT_QUEUE" |
| 30134 | |
| 30135 | This behaves as LOCAL_SCAN_ACCEPT, except that the accepted message is |
| 30136 | queued without immediate delivery. |
| 30137 | |
| 30138 | "LOCAL_SCAN_REJECT" |
| 30139 | |
| 30140 | The message is rejected; the returned text is used as an error message |
| 30141 | which is passed back to the sender and which is also logged. Newlines are |
| 30142 | permitted - they cause a multiline response for SMTP rejections, but are |
| 30143 | converted to "\n" in log lines. If no message is given, "Administrative |
| 30144 | prohibition" is used. |
| 30145 | |
| 30146 | "LOCAL_SCAN_TEMPREJECT" |
| 30147 | |
| 30148 | The message is temporarily rejected; the returned text is used as an error |
| 30149 | message as for LOCAL_SCAN_REJECT. If no message is given, "Temporary local |
| 30150 | problem" is used. |
| 30151 | |
| 30152 | "LOCAL_SCAN_REJECT_NOLOGHDR" |
| 30153 | |
| 30154 | This behaves as LOCAL_SCAN_REJECT, except that the header of the rejected |
| 30155 | message is not written to the reject log. It has the effect of unsetting |
| 30156 | the rejected_header log selector for just this rejection. If |
| 30157 | rejected_header is already unset (see the discussion of the log_selection |
| 30158 | option in section 52.15), this code is the same as LOCAL_SCAN_REJECT. |
| 30159 | |
| 30160 | "LOCAL_SCAN_TEMPREJECT_NOLOGHDR" |
| 30161 | |
| 30162 | This code is a variation of LOCAL_SCAN_TEMPREJECT in the same way that |
| 30163 | LOCAL_SCAN_REJECT_NOLOGHDR is a variation of LOCAL_SCAN_REJECT. |
| 30164 | |
| 30165 | If the message is not being received by interactive SMTP, rejections are |
| 30166 | reported by writing to stderr or by sending an email, as configured by the -oe |
| 30167 | command line options. |
| 30168 | |
| 30169 | |
| 30170 | 45.3 Configuration options for local_scan() |
| 30171 | ------------------------------------------- |
| 30172 | |
| 30173 | It is possible to have option settings in the main configuration file that set |
| 30174 | values in static variables in the local_scan() module. If you want to do this, |
| 30175 | you must have the line |
| 30176 | |
| 30177 | LOCAL_SCAN_HAS_OPTIONS=yes |
| 30178 | |
| 30179 | in your Local/Makefile when you build Exim. (This line is in OS/ |
| 30180 | Makefile-Default, commented out). Then, in the local_scan() source file, you |
| 30181 | must define static variables to hold the option values, and a table to define |
| 30182 | them. |
| 30183 | |
| 30184 | The table must be a vector called local_scan_options, of type "optionlist". |
| 30185 | Each entry is a triplet, consisting of a name, an option type, and a pointer to |
| 30186 | the variable that holds the value. The entries must appear in alphabetical |
| 30187 | order. Following local_scan_options you must also define a variable called |
| 30188 | local_scan_options_count that contains the number of entries in the table. Here |
| 30189 | is a short example, showing two kinds of option: |
| 30190 | |
| 30191 | static int my_integer_option = 42; |
| 30192 | static uschar *my_string_option = US"a default string"; |
| 30193 | |
| 30194 | optionlist local_scan_options[] = { |
| 30195 | { "my_integer", opt_int, &my_integer_option }, |
| 30196 | { "my_string", opt_stringptr, &my_string_option } |
| 30197 | }; |
| 30198 | |
| 30199 | int local_scan_options_count = |
| 30200 | sizeof(local_scan_options)/sizeof(optionlist); |
| 30201 | |
| 30202 | The values of the variables can now be changed from Exim's runtime |
| 30203 | configuration file by including a local scan section as in this example: |
| 30204 | |
| 30205 | begin local_scan |
| 30206 | my_integer = 99 |
| 30207 | my_string = some string of text... |
| 30208 | |
| 30209 | The available types of option data are as follows: |
| 30210 | |
| 30211 | opt_bool |
| 30212 | |
| 30213 | This specifies a boolean (true/false) option. The address should point to a |
| 30214 | variable of type "BOOL", which will be set to TRUE or FALSE, which are |
| 30215 | macros that are defined as "1" and "0", respectively. If you want to detect |
| 30216 | whether such a variable has been set at all, you can initialize it to |
| 30217 | TRUE_UNSET. (BOOL variables are integers underneath, so can hold more than |
| 30218 | two values.) |
| 30219 | |
| 30220 | opt_fixed |
| 30221 | |
| 30222 | This specifies a fixed point number, such as is used for load averages. The |
| 30223 | address should point to a variable of type "int". The value is stored |
| 30224 | multiplied by 1000, so, for example, 1.4142 is truncated and stored as |
| 30225 | 1414. |
| 30226 | |
| 30227 | opt_int |
| 30228 | |
| 30229 | This specifies an integer; the address should point to a variable of type |
| 30230 | "int". The value may be specified in any of the integer formats accepted by |
| 30231 | Exim. |
| 30232 | |
| 30233 | opt_mkint |
| 30234 | |
| 30235 | This is the same as opt_int, except that when such a value is output in a |
| 30236 | -bP listing, if it is an exact number of kilobytes or megabytes, it is |
| 30237 | printed with the suffix K or M. |
| 30238 | |
| 30239 | opt_octint |
| 30240 | |
| 30241 | This also specifies an integer, but the value is always interpreted as an |
| 30242 | octal integer, whether or not it starts with the digit zero, and it is |
| 30243 | always output in octal. |
| 30244 | |
| 30245 | opt_stringptr |
| 30246 | |
| 30247 | This specifies a string value; the address must be a pointer to a variable |
| 30248 | that points to a string (for example, of type "uschar *"). |
| 30249 | |
| 30250 | opt_time |
| 30251 | |
| 30252 | This specifies a time interval value. The address must point to a variable |
| 30253 | of type "int". The value that is placed there is a number of seconds. |
| 30254 | |
| 30255 | If the -bP command line option is followed by "local_scan", Exim prints out the |
| 30256 | values of all the local_scan() options. |
| 30257 | |
| 30258 | |
| 30259 | 45.4 Available Exim variables |
| 30260 | ----------------------------- |
| 30261 | |
| 30262 | The header local_scan.h gives you access to a number of C variables. These are |
| 30263 | the only ones that are guaranteed to be maintained from release to release. |
| 30264 | Note, however, that you can obtain the value of any Exim expansion variable, |
| 30265 | including $recipients, by calling expand_string(). The exported C variables are |
| 30266 | as follows: |
| 30267 | |
| 30268 | int body_linecount |
| 30269 | |
| 30270 | This variable contains the number of lines in the message's body. |
| 30271 | |
| 30272 | int body_zerocount |
| 30273 | |
| 30274 | This variable contains the number of binary zero bytes in the message's |
| 30275 | body. |
| 30276 | |
| 30277 | unsigned int debug_selector |
| 30278 | |
| 30279 | This variable is set to zero when no debugging is taking place. Otherwise, |
| 30280 | it is a bitmap of debugging selectors. Two bits are identified for use in |
| 30281 | local_scan(); they are defined as macros: |
| 30282 | |
| 30283 | + The "D_v" bit is set when -v was present on the command line. This is a |
| 30284 | testing option that is not privileged - any caller may set it. All the |
| 30285 | other selector bits can be set only by admin users. |
| 30286 | |
| 30287 | + The "D_local_scan" bit is provided for use by local_scan(); it is set |
| 30288 | by the "+local_scan" debug selector. It is not included in the default |
| 30289 | set of debugging bits. |
| 30290 | |
| 30291 | Thus, to write to the debugging output only when "+local_scan" has been |
| 30292 | selected, you should use code like this: |
| 30293 | |
| 30294 | if ((debug_selector & D_local_scan) != 0) |
| 30295 | debug_printf("xxx", ...); |
| 30296 | |
| 30297 | uschar *expand_string_message |
| 30298 | |
| 30299 | After a failing call to expand_string() (returned value NULL), the variable |
| 30300 | expand_string_message contains the error message, zero-terminated. |
| 30301 | |
| 30302 | header_line *header_list |
| 30303 | |
| 30304 | A pointer to a chain of header lines. The header_line structure is |
| 30305 | discussed below. |
| 30306 | |
| 30307 | header_line *header_last |
| 30308 | |
| 30309 | A pointer to the last of the header lines. |
| 30310 | |
| 30311 | uschar *headers_charset |
| 30312 | |
| 30313 | The value of the headers_charset configuration option. |
| 30314 | |
| 30315 | BOOL host_checking |
| 30316 | |
| 30317 | This variable is TRUE during a host checking session that is initiated by |
| 30318 | the -bh command line option. |
| 30319 | |
| 30320 | uschar *interface_address |
| 30321 | |
| 30322 | The IP address of the interface that received the message, as a string. |
| 30323 | This is NULL for locally submitted messages. |
| 30324 | |
| 30325 | int interface_port |
| 30326 | |
| 30327 | The port on which this message was received. When testing with the -bh |
| 30328 | command line option, the value of this variable is -1 unless a port has |
| 30329 | been specified via the -oMi option. |
| 30330 | |
| 30331 | uschar *message_id |
| 30332 | |
| 30333 | This variable contains Exim's message id for the incoming message (the |
| 30334 | value of $message_exim_id) as a zero-terminated string. |
| 30335 | |
| 30336 | uschar *received_protocol |
| 30337 | |
| 30338 | The name of the protocol by which the message was received. |
| 30339 | |
| 30340 | int recipients_count |
| 30341 | |
| 30342 | The number of accepted recipients. |
| 30343 | |
| 30344 | recipient_item *recipients_list |
| 30345 | |
| 30346 | The list of accepted recipients, held in a vector of length |
| 30347 | recipients_count. The recipient_item structure is discussed below. You can |
| 30348 | add additional recipients by calling receive_add_recipient() (see below). |
| 30349 | You can delete recipients by removing them from the vector and adjusting |
| 30350 | the value in recipients_count. In particular, by setting recipients_count |
| 30351 | to zero you remove all recipients. If you then return the value |
| 30352 | "LOCAL_SCAN_ACCEPT", the message is accepted, but immediately blackholed. |
| 30353 | To replace the recipients, you can set recipients_count to zero and then |
| 30354 | call receive_add_recipient() as often as needed. |
| 30355 | |
| 30356 | uschar *sender_address |
| 30357 | |
| 30358 | The envelope sender address. For bounce messages this is the empty string. |
| 30359 | |
| 30360 | uschar *sender_host_address |
| 30361 | |
| 30362 | The IP address of the sending host, as a string. This is NULL for |
| 30363 | locally-submitted messages. |
| 30364 | |
| 30365 | uschar *sender_host_authenticated |
| 30366 | |
| 30367 | The name of the authentication mechanism that was used, or NULL if the |
| 30368 | message was not received over an authenticated SMTP connection. |
| 30369 | |
| 30370 | uschar *sender_host_name |
| 30371 | |
| 30372 | The name of the sending host, if known. |
| 30373 | |
| 30374 | int sender_host_port |
| 30375 | |
| 30376 | The port on the sending host. |
| 30377 | |
| 30378 | BOOL smtp_input |
| 30379 | |
| 30380 | This variable is TRUE for all SMTP input, including BSMTP. |
| 30381 | |
| 30382 | BOOL smtp_batched_input |
| 30383 | |
| 30384 | This variable is TRUE for BSMTP input. |
| 30385 | |
| 30386 | int store_pool |
| 30387 | |
| 30388 | The contents of this variable control which pool of memory is used for new |
| 30389 | requests. See section 45.8 for details. |
| 30390 | |
| 30391 | |
| 30392 | 45.5 Structure of header lines |
| 30393 | ------------------------------ |
| 30394 | |
| 30395 | The header_line structure contains the members listed below. You can add |
| 30396 | additional header lines by calling the header_add() function (see below). You |
| 30397 | can cause header lines to be ignored (deleted) by setting their type to *. |
| 30398 | |
| 30399 | struct header_line *next |
| 30400 | |
| 30401 | A pointer to the next header line, or NULL for the last line. |
| 30402 | |
| 30403 | int type |
| 30404 | |
| 30405 | A code identifying certain headers that Exim recognizes. The codes are |
| 30406 | printing characters, and are documented in chapter 56 of this manual. |
| 30407 | Notice in particular that any header line whose type is * is not |
| 30408 | transmitted with the message. This flagging is used for header lines that |
| 30409 | have been rewritten, or are to be removed (for example, Envelope-sender: |
| 30410 | header lines.) Effectively, * means "deleted". |
| 30411 | |
| 30412 | int slen |
| 30413 | |
| 30414 | The number of characters in the header line, including the terminating and |
| 30415 | any internal newlines. |
| 30416 | |
| 30417 | uschar *text |
| 30418 | |
| 30419 | A pointer to the text of the header. It always ends with a newline, |
| 30420 | followed by a zero byte. Internal newlines are preserved. |
| 30421 | |
| 30422 | |
| 30423 | 45.6 Structure of recipient items |
| 30424 | --------------------------------- |
| 30425 | |
| 30426 | The recipient_item structure contains these members: |
| 30427 | |
| 30428 | uschar *address |
| 30429 | |
| 30430 | This is a pointer to the recipient address as it was received. |
| 30431 | |
| 30432 | int pno |
| 30433 | |
| 30434 | This is used in later Exim processing when top level addresses are created |
| 30435 | by the one_time option. It is not relevant at the time local_scan() is run |
| 30436 | and must always contain -1 at this stage. |
| 30437 | |
| 30438 | uschar *errors_to |
| 30439 | |
| 30440 | If this value is not NULL, bounce messages caused by failing to deliver to |
| 30441 | the recipient are sent to the address it contains. In other words, it |
| 30442 | overrides the envelope sender for this one recipient. (Compare the |
| 30443 | errors_to generic router option.) If a local_scan() function sets an |
| 30444 | errors_to field to an unqualified address, Exim qualifies it using the |
| 30445 | domain from qualify_recipient. When local_scan() is called, the errors_to |
| 30446 | field is NULL for all recipients. |
| 30447 | |
| 30448 | |
| 30449 | 45.7 Available Exim functions |
| 30450 | ----------------------------- |
| 30451 | |
| 30452 | The header local_scan.h gives you access to a number of Exim functions. These |
| 30453 | are the only ones that are guaranteed to be maintained from release to release: |
| 30454 | |
| 30455 | pid_t child_open |
| 30456 | (uschar **argv, uschar **envp, int newumask, int *infdptr, int *outfdptr, |
| 30457 | BOOL make_leader) |
| 30458 | |
| 30459 | This function creates a child process that runs the command specified by |
| 30460 | argv. The environment for the process is specified by envp, which can be |
| 30461 | NULL if no environment variables are to be passed. A new umask is supplied |
| 30462 | for the process in newumask. |
| 30463 | |
| 30464 | Pipes to the standard input and output of the new process are set up and |
| 30465 | returned to the caller via the infdptr and outfdptr arguments. The standard |
| 30466 | error is cloned to the standard output. If there are any file descriptors |
| 30467 | "in the way" in the new process, they are closed. If the final argument is |
| 30468 | TRUE, the new process is made into a process group leader. |
| 30469 | |
| 30470 | The function returns the pid of the new process, or -1 if things go wrong. |
| 30471 | |
| 30472 | int child_close(pid_t pid, int timeout) |
| 30473 | |
| 30474 | This function waits for a child process to terminate, or for a timeout (in |
| 30475 | seconds) to expire. A timeout value of zero means wait as long as it takes. |
| 30476 | The return value is as follows: |
| 30477 | |
| 30478 | + >= 0 |
| 30479 | |
| 30480 | The process terminated by a normal exit and the value is the process |
| 30481 | ending status. |
| 30482 | |
| 30483 | + < 0 and > -256 |
| 30484 | |
| 30485 | The process was terminated by a signal and the value is the negation of |
| 30486 | the signal number. |
| 30487 | |
| 30488 | + -256 |
| 30489 | |
| 30490 | The process timed out. |
| 30491 | |
| 30492 | + -257 |
| 30493 | |
| 30494 | The was some other error in wait(); errno is still set. |
| 30495 | |
| 30496 | pid_t child_open_exim(int *fd) |
| 30497 | |
| 30498 | This function provide you with a means of submitting a new message to Exim. |
| 30499 | (Of course, you can also call /usr/sbin/sendmail yourself if you want, but |
| 30500 | this packages it all up for you.) The function creates a pipe, forks a |
| 30501 | subprocess that is running |
| 30502 | |
| 30503 | exim -t -oem -oi -f <> |
| 30504 | |
| 30505 | and returns to you (via the "int *" argument) a file descriptor for the |
| 30506 | pipe that is connected to the standard input. The yield of the function is |
| 30507 | the PID of the subprocess. You can then write a message to the file |
| 30508 | descriptor, with recipients in To:, Cc:, and/or Bcc: header lines. |
| 30509 | |
| 30510 | When you have finished, call child_close() to wait for the process to |
| 30511 | finish and to collect its ending status. A timeout value of zero is usually |
| 30512 | fine in this circumstance. Unless you have made a mistake with the |
| 30513 | recipient addresses, you should get a return code of zero. |
| 30514 | |
| 30515 | pid_t child_open_exim2(int *fd, uschar *sender, uschar *sender_authentication) |
| 30516 | |
| 30517 | This function is a more sophisticated version of child_open(). The command |
| 30518 | that it runs is: |
| 30519 | |
| 30520 | exim -t -oem -oi -f sender -oMas sender_authentication |
| 30521 | |
| 30522 | The third argument may be NULL, in which case the -oMas option is omitted. |
| 30523 | |
| 30524 | void debug_printf(char *, ...) |
| 30525 | |
| 30526 | This is Exim's debugging function, with arguments as for (printf(). The |
| 30527 | output is written to the standard error stream. If no debugging is |
| 30528 | selected, calls to debug_printf() have no effect. Normally, you should make |
| 30529 | calls conditional on the "local_scan" debug selector by coding like this: |
| 30530 | |
| 30531 | if ((debug_selector & D_local_scan) != 0) |
| 30532 | debug_printf("xxx", ...); |
| 30533 | |
| 30534 | uschar *expand_string(uschar *string) |
| 30535 | |
| 30536 | This is an interface to Exim's string expansion code. The return value is |
| 30537 | the expanded string, or NULL if there was an expansion failure. The C |
| 30538 | variable expand_string_message contains an error message after an expansion |
| 30539 | failure. If expansion does not change the string, the return value is the |
| 30540 | pointer to the input string. Otherwise, the return value points to a new |
| 30541 | block of memory that was obtained by a call to store_get(). See section |
| 30542 | 45.8 below for a discussion of memory handling. |
| 30543 | |
| 30544 | void header_add(int type, char *format, ...) |
| 30545 | |
| 30546 | This function allows you to an add additional header line at the end of the |
| 30547 | existing ones. The first argument is the type, and should normally be a |
| 30548 | space character. The second argument is a format string and any number of |
| 30549 | substitution arguments as for sprintf(). You may include internal newlines |
| 30550 | if you want, and you must ensure that the string ends with a newline. |
| 30551 | |
| 30552 | void header_add_at_position |
| 30553 | (BOOL after, uschar *name, BOOL topnot, int type, char *format, ...) |
| 30554 | |
| 30555 | This function adds a new header line at a specified point in the header |
| 30556 | chain. The header itself is specified as for header_add(). |
| 30557 | |
| 30558 | If name is NULL, the new header is added at the end of the chain if after |
| 30559 | is true, or at the start if after is false. If name is not NULL, the header |
| 30560 | lines are searched for the first non-deleted header that matches the name. |
| 30561 | If one is found, the new header is added before it if after is false. If |
| 30562 | after is true, the new header is added after the found header and any |
| 30563 | adjacent subsequent ones with the same name (even if marked "deleted"). If |
| 30564 | no matching non-deleted header is found, the topnot option controls where |
| 30565 | the header is added. If it is true, addition is at the top; otherwise at |
| 30566 | the bottom. Thus, to add a header after all the Received: headers, or at |
| 30567 | the top if there are no Received: headers, you could use |
| 30568 | |
| 30569 | header_add_at_position(TRUE, US"Received", TRUE, |
| 30570 | ' ', "X-xxx: ..."); |
| 30571 | |
| 30572 | Normally, there is always at least one non-deleted Received: header, but |
| 30573 | there may not be if received_header_text expands to an empty string. |
| 30574 | |
| 30575 | void header_remove(int occurrence, uschar *name) |
| 30576 | |
| 30577 | This function removes header lines. If occurrence is zero or negative, all |
| 30578 | occurrences of the header are removed. If occurrence is greater than zero, |
| 30579 | that particular instance of the header is removed. If no header(s) can be |
| 30580 | found that match the specification, the function does nothing. |
| 30581 | |
| 30582 | BOOL header_testname(header_line *hdr, uschar *name, int length, BOOL notdel) |
| 30583 | |
| 30584 | This function tests whether the given header has the given name. It is not |
| 30585 | just a string comparison, because white space is permitted between the name |
| 30586 | and the colon. If the notdel argument is true, a false return is forced for |
| 30587 | all "deleted" headers; otherwise they are not treated specially. For |
| 30588 | example: |
| 30589 | |
| 30590 | if (header_testname(h, US"X-Spam", 6, TRUE)) ... |
| 30591 | |
| 30592 | uschar *lss_b64encode(uschar *cleartext, int length) |
| 30593 | |
| 30594 | This function base64-encodes a string, which is passed by address and |
| 30595 | length. The text may contain bytes of any value, including zero. The result |
| 30596 | is passed back in dynamic memory that is obtained by calling store_get(). |
| 30597 | It is zero-terminated. |
| 30598 | |
| 30599 | int lss_b64decode(uschar *codetext, uschar **cleartext) |
| 30600 | |
| 30601 | This function decodes a base64-encoded string. Its arguments are a |
| 30602 | zero-terminated base64-encoded string and the address of a variable that is |
| 30603 | set to point to the result, which is in dynamic memory. The length of the |
| 30604 | decoded string is the yield of the function. If the input is invalid base64 |
| 30605 | data, the yield is -1. A zero byte is added to the end of the output string |
| 30606 | to make it easy to interpret as a C string (assuming it contains no zeros |
| 30607 | of its own). The added zero byte is not included in the returned count. |
| 30608 | |
| 30609 | int lss_match_domain(uschar *domain, uschar *list) |
| 30610 | |
| 30611 | This function checks for a match in a domain list. Domains are always |
| 30612 | matched caselessly. The return value is one of the following: |
| 30613 | |
| 30614 | OK match succeeded |
| 30615 | FAIL match failed |
| 30616 | DEFER match deferred |
| 30617 | |
| 30618 | DEFER is usually caused by some kind of lookup defer, such as the inability |
| 30619 | to contact a database. |
| 30620 | |
| 30621 | int lss_match_local_part(uschar *localpart, uschar *list, BOOL caseless) |
| 30622 | |
| 30623 | This function checks for a match in a local part list. The third argument |
| 30624 | controls case-sensitivity. The return values are as for lss_match_domain(). |
| 30625 | |
| 30626 | int lss_match_address(uschar *address, uschar *list, BOOL caseless) |
| 30627 | |
| 30628 | This function checks for a match in an address list. The third argument |
| 30629 | controls the case-sensitivity of the local part match. The domain is always |
| 30630 | matched caselessly. The return values are as for lss_match_domain(). |
| 30631 | |
| 30632 | int lss_match_host(uschar *host_name, uschar *host_address, uschar *list) |
| 30633 | |
| 30634 | This function checks for a match in a host list. The most common usage is |
| 30635 | expected to be |
| 30636 | |
| 30637 | lss_match_host(sender_host_name, sender_host_address, ...) |
| 30638 | |
| 30639 | An empty address field matches an empty item in the host list. If the host |
| 30640 | name is NULL, the name corresponding to $sender_host_address is |
| 30641 | automatically looked up if a host name is required to match an item in the |
| 30642 | list. The return values are as for lss_match_domain(), but in addition, |
| 30643 | lss_match_host() returns ERROR in the case when it had to look up a host |
| 30644 | name, but the lookup failed. |
| 30645 | |
| 30646 | void log_write(unsigned int selector, int which, char *format, ...) |
| 30647 | |
| 30648 | This function writes to Exim's log files. The first argument should be zero |
| 30649 | (it is concerned with log_selector). The second argument can be "LOG_MAIN" |
| 30650 | or "LOG_REJECT" or "LOG_PANIC" or the inclusive "or" of any combination of |
| 30651 | them. It specifies to which log or logs the message is written. The |
| 30652 | remaining arguments are a format and relevant insertion arguments. The |
| 30653 | string should not contain any newlines, not even at the end. |
| 30654 | |
| 30655 | void receive_add_recipient(uschar *address, int pno) |
| 30656 | |
| 30657 | This function adds an additional recipient to the message. The first |
| 30658 | argument is the recipient address. If it is unqualified (has no domain), it |
| 30659 | is qualified with the qualify_recipient domain. The second argument must |
| 30660 | always be -1. |
| 30661 | |
| 30662 | This function does not allow you to specify a private errors_to address (as |
| 30663 | described with the structure of recipient_item above), because it pre-dates |
| 30664 | the addition of that field to the structure. However, it is easy to add |
| 30665 | such a value afterwards. For example: |
| 30666 | |
| 30667 | receive_add_recipient(US"monitor@mydom.example", -1); |
| 30668 | recipients_list[recipients_count-1].errors_to = |
| 30669 | US"postmaster@mydom.example"; |
| 30670 | |
| 30671 | BOOL receive_remove_recipient(uschar *recipient) |
| 30672 | |
| 30673 | This is a convenience function to remove a named recipient from the list of |
| 30674 | recipients. It returns true if a recipient was removed, and false if no |
| 30675 | matching recipient could be found. The argument must be a complete email |
| 30676 | address. |
| 30677 | |
| 30678 | uschar rfc2047_decode |
| 30679 | (uschar *string, BOOL lencheck, uschar *target, int zeroval, int *lenptr, |
| 30680 | uschar **error) |
| 30681 | |
| 30682 | This function decodes strings that are encoded according to RFC 2047. |
| 30683 | Typically these are the contents of header lines. First, each "encoded |
| 30684 | word" is decoded from the Q or B encoding into a byte-string. Then, if |
| 30685 | provided with the name of a charset encoding, and if the iconv() function |
| 30686 | is available, an attempt is made to translate the result to the named |
| 30687 | character set. If this fails, the binary string is returned with an error |
| 30688 | message. |
| 30689 | |
| 30690 | The first argument is the string to be decoded. If lencheck is TRUE, the |
| 30691 | maximum MIME word length is enforced. The third argument is the target |
| 30692 | encoding, or NULL if no translation is wanted. |
| 30693 | |
| 30694 | If a binary zero is encountered in the decoded string, it is replaced by |
| 30695 | the contents of the zeroval argument. For use with Exim headers, the value |
| 30696 | must not be 0 because header lines are handled as zero-terminated strings. |
| 30697 | |
| 30698 | The function returns the result of processing the string, zero-terminated; |
| 30699 | if lenptr is not NULL, the length of the result is set in the variable to |
| 30700 | which it points. When zeroval is 0, lenptr should not be NULL. |
| 30701 | |
| 30702 | If an error is encountered, the function returns NULL and uses the error |
| 30703 | argument to return an error message. The variable pointed to by error is |
| 30704 | set to NULL if there is no error; it may be set non-NULL even when the |
| 30705 | function returns a non-NULL value if decoding was successful, but there was |
| 30706 | a problem with translation. |
| 30707 | |
| 30708 | int smtp_fflush(void) |
| 30709 | |
| 30710 | This function is used in conjunction with smtp_printf(), as described |
| 30711 | below. |
| 30712 | |
| 30713 | void smtp_printf(char *, ...) |
| 30714 | |
| 30715 | The arguments of this function are like printf(); it writes to the SMTP |
| 30716 | output stream. You should use this function only when there is an SMTP |
| 30717 | output stream, that is, when the incoming message is being received via |
| 30718 | interactive SMTP. This is the case when smtp_input is TRUE and |
| 30719 | smtp_batched_input is FALSE. If you want to test for an incoming message |
| 30720 | from another host (as opposed to a local process that used the -bs command |
| 30721 | line option), you can test the value of sender_host_address, which is |
| 30722 | non-NULL when a remote host is involved. |
| 30723 | |
| 30724 | If an SMTP TLS connection is established, smtp_printf() uses the TLS output |
| 30725 | function, so it can be used for all forms of SMTP connection. |
| 30726 | |
| 30727 | Strings that are written by smtp_printf() from within local_scan() must |
| 30728 | start with an appropriate response code: 550 if you are going to return |
| 30729 | LOCAL_SCAN_REJECT, 451 if you are going to return LOCAL_SCAN_TEMPREJECT, |
| 30730 | and 250 otherwise. Because you are writing the initial lines of a |
| 30731 | multi-line response, the code must be followed by a hyphen to indicate that |
| 30732 | the line is not the final response line. You must also ensure that the |
| 30733 | lines you write terminate with CRLF. For example: |
| 30734 | |
| 30735 | smtp_printf("550-this is some extra info\r\n"); |
| 30736 | return LOCAL_SCAN_REJECT; |
| 30737 | |
| 30738 | Note that you can also create multi-line responses by including newlines in |
| 30739 | the data returned via the return_text argument. The added value of using |
| 30740 | smtp_printf() is that, for instance, you could introduce delays between |
| 30741 | multiple output lines. |
| 30742 | |
| 30743 | The smtp_printf() function does not return any error indication, because it |
| 30744 | does not automatically flush pending output, and therefore does not test |
| 30745 | the state of the stream. (In the main code of Exim, flushing and error |
| 30746 | detection is done when Exim is ready for the next SMTP input command.) If |
| 30747 | you want to flush the output and check for an error (for example, the |
| 30748 | dropping of a TCP/IP connection), you can call smtp_fflush(), which has no |
| 30749 | arguments. It flushes the output stream, and returns a non-zero value if |
| 30750 | there is an error. |
| 30751 | |
| 30752 | void *store_get(int) |
| 30753 | |
| 30754 | This function accesses Exim's internal store (memory) manager. It gets a |
| 30755 | new chunk of memory whose size is given by the argument. Exim bombs out if |
| 30756 | it ever runs out of memory. See the next section for a discussion of memory |
| 30757 | handling. |
| 30758 | |
| 30759 | void *store_get_perm(int) |
| 30760 | |
| 30761 | This function is like store_get(), but it always gets memory from the |
| 30762 | permanent pool. See the next section for a discussion of memory handling. |
| 30763 | |
| 30764 | uschar *string_copy(uschar *string) |
| 30765 | |
| 30766 | See below. |
| 30767 | |
| 30768 | uschar *string_copyn(uschar *string, int length) |
| 30769 | |
| 30770 | See below. |
| 30771 | |
| 30772 | uschar *string_sprintf(char *format, ...) |
| 30773 | |
| 30774 | These three functions create strings using Exim's dynamic memory |
| 30775 | facilities. The first makes a copy of an entire string. The second copies |
| 30776 | up to a maximum number of characters, indicated by the second argument. The |
| 30777 | third uses a format and insertion arguments to create a new string. In each |
| 30778 | case, the result is a pointer to a new string in the current memory pool. |
| 30779 | See the next section for more discussion. |
| 30780 | |
| 30781 | |
| 30782 | 45.8 More about Exim's memory handling |
| 30783 | -------------------------------------- |
| 30784 | |
| 30785 | No function is provided for freeing memory, because that is never needed. The |
| 30786 | dynamic memory that Exim uses when receiving a message is automatically |
| 30787 | recycled if another message is received by the same process (this applies only |
| 30788 | to incoming SMTP connections - other input methods can supply only one message |
| 30789 | at a time). After receiving the last message, a reception process terminates. |
| 30790 | |
| 30791 | Because it is recycled, the normal dynamic memory cannot be used for holding |
| 30792 | data that must be preserved over a number of incoming messages on the same SMTP |
| 30793 | connection. However, Exim in fact uses two pools of dynamic memory; the second |
| 30794 | one is not recycled, and can be used for this purpose. |
| 30795 | |
| 30796 | If you want to allocate memory that remains available for subsequent messages |
| 30797 | in the same SMTP connection, you should set |
| 30798 | |
| 30799 | store_pool = POOL_PERM |
| 30800 | |
| 30801 | before calling the function that does the allocation. There is no need to |
| 30802 | restore the value if you do not need to; however, if you do want to revert to |
| 30803 | the normal pool, you can either restore the previous value of store_pool or set |
| 30804 | it explicitly to POOL_MAIN. |
| 30805 | |
| 30806 | The pool setting applies to all functions that get dynamic memory, including |
| 30807 | expand_string(), store_get(), and the string_xxx() functions. There is also a |
| 30808 | convenience function called store_get_perm() that gets a block of memory from |
| 30809 | the permanent pool while preserving the value of store_pool. |
| 30810 | |
| 30811 | |
| 30812 | |
| 30813 | =============================================================================== |
| 30814 | 46. SYSTEM-WIDE MESSAGE FILTERING |
| 30815 | |
| 30816 | The previous chapters (on ACLs and the local scan function) describe checks |
| 30817 | that can be applied to messages before they are accepted by a host. There is |
| 30818 | also a mechanism for checking messages once they have been received, but before |
| 30819 | they are delivered. This is called the system filter. |
| 30820 | |
| 30821 | The system filter operates in a similar manner to users' filter files, but it |
| 30822 | is run just once per message (however many recipients the message has). It |
| 30823 | should not normally be used as a substitute for routing, because deliver |
| 30824 | commands in a system router provide new envelope recipient addresses. The |
| 30825 | system filter must be an Exim filter. It cannot be a Sieve filter. |
| 30826 | |
| 30827 | The system filter is run at the start of a delivery attempt, before any routing |
| 30828 | is done. If a message fails to be completely delivered at the first attempt, |
| 30829 | the system filter is run again at the start of every retry. If you want your |
| 30830 | filter to do something only once per message, you can make use of the |
| 30831 | first_delivery condition in an if command in the filter to prevent it happening |
| 30832 | on retries. |
| 30833 | |
| 30834 | Warning: Because the system filter runs just once, variables that are specific |
| 30835 | to individual recipient addresses, such as $local_part and $domain, are not |
| 30836 | set, and the "personal" condition is not meaningful. If you want to run a |
| 30837 | centrally-specified filter for each recipient address independently, you can do |
| 30838 | so by setting up a suitable redirect router, as described in section 46.8 |
| 30839 | below. |
| 30840 | |
| 30841 | |
| 30842 | 46.1 Specifying a system filter |
| 30843 | ------------------------------- |
| 30844 | |
| 30845 | The name of the file that contains the system filter must be specified by |
| 30846 | setting system_filter. If you want the filter to run under a uid and gid other |
| 30847 | than root, you must also set system_filter_user and system_filter_group as |
| 30848 | appropriate. For example: |
| 30849 | |
| 30850 | system_filter = /etc/mail/exim.filter |
| 30851 | system_filter_user = exim |
| 30852 | |
| 30853 | If a system filter generates any deliveries directly to files or pipes (via the |
| 30854 | save or pipe commands), transports to handle these deliveries must be specified |
| 30855 | by setting system_filter_file_transport and system_filter_pipe_transport, |
| 30856 | respectively. Similarly, system_filter_reply_transport must be set to handle |
| 30857 | any messages generated by the reply command. |
| 30858 | |
| 30859 | |
| 30860 | 46.2 Testing a system filter |
| 30861 | ---------------------------- |
| 30862 | |
| 30863 | You can run simple tests of a system filter in the same way as for a user |
| 30864 | filter, but you should use -bF rather than -bf, so that features that are |
| 30865 | permitted only in system filters are recognized. |
| 30866 | |
| 30867 | If you want to test the combined effect of a system filter and a user filter, |
| 30868 | you can use both -bF and -bf on the same command line. |
| 30869 | |
| 30870 | |
| 30871 | 46.3 Contents of a system filter |
| 30872 | -------------------------------- |
| 30873 | |
| 30874 | The language used to specify system filters is the same as for users' filter |
| 30875 | files. It is described in the separate end-user document Exim's interface to |
| 30876 | mail filtering. However, there are some additional features that are available |
| 30877 | only in system filters; these are described in subsequent sections. If they are |
| 30878 | encountered in a user's filter file or when testing with -bf, they cause |
| 30879 | errors. |
| 30880 | |
| 30881 | There are two special conditions which, though available in users' filter |
| 30882 | files, are designed for use in system filters. The condition first_delivery is |
| 30883 | true only for the first attempt at delivering a message, and manually_thawed is |
| 30884 | true only if the message has been frozen, and subsequently thawed by an admin |
| 30885 | user. An explicit forced delivery counts as a manual thaw, but thawing as a |
| 30886 | result of the auto_thaw setting does not. |
| 30887 | |
| 30888 | Warning: If a system filter uses the first_delivery condition to specify an |
| 30889 | "unseen" (non-significant) delivery, and that delivery does not succeed, it |
| 30890 | will not be tried again. If you want Exim to retry an unseen delivery until it |
| 30891 | succeeds, you should arrange to set it up every time the filter runs. |
| 30892 | |
| 30893 | When a system filter finishes running, the values of the variables $n0 - $n9 |
| 30894 | are copied into $sn0 - $sn9 and are thereby made available to users' filter |
| 30895 | files. Thus a system filter can, for example, set up "scores" to which users' |
| 30896 | filter files can refer. |
| 30897 | |
| 30898 | |
| 30899 | 46.4 Additional variable for system filters |
| 30900 | ------------------------------------------- |
| 30901 | |
| 30902 | The expansion variable $recipients, containing a list of all the recipients of |
| 30903 | the message (separated by commas and white space), is available in system |
| 30904 | filters. It is not available in users' filters for privacy reasons. |
| 30905 | |
| 30906 | |
| 30907 | 46.5 Defer, freeze, and fail commands for system filters |
| 30908 | -------------------------------------------------------- |
| 30909 | |
| 30910 | There are three extra commands (defer, freeze and fail) which are always |
| 30911 | available in system filters, but are not normally enabled in users' filters. |
| 30912 | (See the allow_defer, allow_freeze and allow_fail options for the redirect |
| 30913 | router.) These commands can optionally be followed by the word text and a |
| 30914 | string containing an error message, for example: |
| 30915 | |
| 30916 | fail text "this message looks like spam to me" |
| 30917 | |
| 30918 | The keyword text is optional if the next character is a double quote. |
| 30919 | |
| 30920 | The defer command defers delivery of the original recipients of the message. |
| 30921 | The fail command causes all the original recipients to be failed, and a bounce |
| 30922 | message to be created. The freeze command suspends all delivery attempts for |
| 30923 | the original recipients. In all cases, any new deliveries that are specified by |
| 30924 | the filter are attempted as normal after the filter has run. |
| 30925 | |
| 30926 | The freeze command is ignored if the message has been manually unfrozen and not |
| 30927 | manually frozen since. This means that automatic freezing by a system filter |
| 30928 | can be used as a way of checking out suspicious messages. If a message is found |
| 30929 | to be all right, manually unfreezing it allows it to be delivered. |
| 30930 | |
| 30931 | The text given with a fail command is used as part of the bounce message as |
| 30932 | well as being written to the log. If the message is quite long, this can fill |
| 30933 | up a lot of log space when such failures are common. To reduce the size of the |
| 30934 | log message, Exim interprets the text in a special way if it starts with the |
| 30935 | two characters "<<" and contains ">>" later. The text between these two strings |
| 30936 | is written to the log, and the rest of the text is used in the bounce message. |
| 30937 | For example: |
| 30938 | |
| 30939 | fail "<<filter test 1>>Your message is rejected \ |
| 30940 | because it contains attachments that we are \ |
| 30941 | not prepared to receive." |
| 30942 | |
| 30943 | Take great care with the fail command when basing the decision to fail on the |
| 30944 | contents of the message, because the bounce message will of course include the |
| 30945 | contents of the original message and will therefore trigger the fail command |
| 30946 | again (causing a mail loop) unless steps are taken to prevent this. Testing the |
| 30947 | error_message condition is one way to prevent this. You could use, for example |
| 30948 | |
| 30949 | if $message_body contains "this is spam" and not error_message |
| 30950 | then fail text "spam is not wanted here" endif |
| 30951 | |
| 30952 | though of course that might let through unwanted bounce messages. The |
| 30953 | alternative is clever checking of the body and/or headers to detect bounces |
| 30954 | generated by the filter. |
| 30955 | |
| 30956 | The interpretation of a system filter file ceases after a defer, freeze, or |
| 30957 | fail command is obeyed. However, any deliveries that were set up earlier in the |
| 30958 | filter file are honoured, so you can use a sequence such as |
| 30959 | |
| 30960 | mail ... |
| 30961 | freeze |
| 30962 | |
| 30963 | to send a specified message when the system filter is freezing (or deferring or |
| 30964 | failing) a message. The normal deliveries for the message do not, of course, |
| 30965 | take place. |
| 30966 | |
| 30967 | |
| 30968 | 46.6 Adding and removing headers in a system filter |
| 30969 | --------------------------------------------------- |
| 30970 | |
| 30971 | Two filter commands that are available only in system filters are: |
| 30972 | |
| 30973 | headers add <string> |
| 30974 | headers remove <string> |
| 30975 | |
| 30976 | The argument for the headers add is a string that is expanded and then added to |
| 30977 | the end of the message's headers. It is the responsibility of the filter |
| 30978 | maintainer to make sure it conforms to RFC 2822 syntax. Leading white space is |
| 30979 | ignored, and if the string is otherwise empty, or if the expansion is forced to |
| 30980 | fail, the command has no effect. |
| 30981 | |
| 30982 | You can use "\n" within the string, followed by white space, to specify |
| 30983 | continued header lines. More than one header may be added in one command by |
| 30984 | including "\n" within the string without any following white space. For |
| 30985 | example: |
| 30986 | |
| 30987 | headers add "X-header-1: ....\n \ |
| 30988 | continuation of X-header-1 ...\n\ |
| 30989 | X-header-2: ...." |
| 30990 | |
| 30991 | Note that the header line continuation white space after the first newline must |
| 30992 | be placed before the backslash that continues the input string, because white |
| 30993 | space after input continuations is ignored. |
| 30994 | |
| 30995 | The argument for headers remove is a colon-separated list of header names. This |
| 30996 | command applies only to those headers that are stored with the message; those |
| 30997 | that are added at delivery time (such as Envelope-To: and Return-Path:) cannot |
| 30998 | be removed by this means. If there is more than one header with the same name, |
| 30999 | they are all removed. |
| 31000 | |
| 31001 | The headers command in a system filter makes an immediate change to the set of |
| 31002 | header lines that was received with the message (with possible additions from |
| 31003 | ACL processing). Subsequent commands in the system filter operate on the |
| 31004 | modified set, which also forms the basis for subsequent message delivery. |
| 31005 | Unless further modified during routing or transporting, this set of headers is |
| 31006 | used for all recipients of the message. |
| 31007 | |
| 31008 | During routing and transporting, the variables that refer to the contents of |
| 31009 | header lines refer only to those lines that are in this set. Thus, header lines |
| 31010 | that are added by a system filter are visible to users' filter files and to all |
| 31011 | routers and transports. This contrasts with the manipulation of header lines by |
| 31012 | routers and transports, which is not immediate, but which instead is saved up |
| 31013 | until the message is actually being written (see section 47.17). |
| 31014 | |
| 31015 | If the message is not delivered at the first attempt, header lines that were |
| 31016 | added by the system filter are stored with the message, and so are still |
| 31017 | present at the next delivery attempt. Header lines that were removed are still |
| 31018 | present, but marked "deleted" so that they are not transported with the |
| 31019 | message. For this reason, it is usual to make the headers command conditional |
| 31020 | on first_delivery so that the set of header lines is not modified more than |
| 31021 | once. |
| 31022 | |
| 31023 | Because header modification in a system filter acts immediately, you have to |
| 31024 | use an indirect approach if you want to modify the contents of a header line. |
| 31025 | For example: |
| 31026 | |
| 31027 | headers add "Old-Subject: $h_subject:" |
| 31028 | headers remove "Subject" |
| 31029 | headers add "Subject: new subject (was: $h_old-subject:)" |
| 31030 | headers remove "Old-Subject" |
| 31031 | |
| 31032 | |
| 31033 | 46.7 Setting an errors address in a system filter |
| 31034 | ------------------------------------------------- |
| 31035 | |
| 31036 | In a system filter, if a deliver command is followed by |
| 31037 | |
| 31038 | errors_to <some address> |
| 31039 | |
| 31040 | in order to change the envelope sender (and hence the error reporting) for that |
| 31041 | delivery, any address may be specified. (In a user filter, only the current |
| 31042 | user's address can be set.) For example, if some mail is being monitored, you |
| 31043 | might use |
| 31044 | |
| 31045 | unseen deliver monitor@spying.example errors_to root@local.example |
| 31046 | |
| 31047 | to take a copy which would not be sent back to the normal error reporting |
| 31048 | address if its delivery failed. |
| 31049 | |
| 31050 | |
| 31051 | 46.8 Per-address filtering |
| 31052 | -------------------------- |
| 31053 | |
| 31054 | In contrast to the system filter, which is run just once per message for each |
| 31055 | delivery attempt, it is also possible to set up a system-wide filtering |
| 31056 | operation that runs once for each recipient address. In this case, variables |
| 31057 | such as $local_part and $domain can be used, and indeed, the choice of filter |
| 31058 | file could be made dependent on them. This is an example of a router which |
| 31059 | implements such a filter: |
| 31060 | |
| 31061 | central_filter: |
| 31062 | check_local_user |
| 31063 | driver = redirect |
| 31064 | domains = +local_domains |
| 31065 | file = /central/filters/$local_part |
| 31066 | no_verify |
| 31067 | allow_filter |
| 31068 | allow_freeze |
| 31069 | |
| 31070 | The filter is run in a separate process under its own uid. Therefore, either |
| 31071 | check_local_user must be set (as above), in which case the filter is run as the |
| 31072 | local user, or the user option must be used to specify which user to use. If |
| 31073 | both are set, user overrides. |
| 31074 | |
| 31075 | Care should be taken to ensure that none of the commands in the filter file |
| 31076 | specify a significant delivery if the message is to go on to be delivered to |
| 31077 | its intended recipient. The router will not then claim to have dealt with the |
| 31078 | address, so it will be passed on to subsequent routers to be delivered in the |
| 31079 | normal way. |
| 31080 | |
| 31081 | |
| 31082 | |
| 31083 | =============================================================================== |
| 31084 | 47. MESSAGE PROCESSING |
| 31085 | |
| 31086 | Exim performs various transformations on the sender and recipient addresses of |
| 31087 | all messages that it handles, and also on the messages' header lines. Some of |
| 31088 | these are optional and configurable, while others always take place. All of |
| 31089 | this processing, except rewriting as a result of routing, and the addition or |
| 31090 | removal of header lines while delivering, happens when a message is received, |
| 31091 | before it is placed on Exim's queue. |
| 31092 | |
| 31093 | Some of the automatic processing takes place by default only for |
| 31094 | "locally-originated" messages. This adjective is used to describe messages that |
| 31095 | are not received over TCP/IP, but instead are passed to an Exim process on its |
| 31096 | standard input. This includes the interactive "local SMTP" case that is set up |
| 31097 | by the -bs command line option. |
| 31098 | |
| 31099 | Note: Messages received over TCP/IP on the loopback interface (127.0.0.1 or |
| 31100 | ::1) are not considered to be locally-originated. Exim does not treat the |
| 31101 | loopback interface specially in any way. |
| 31102 | |
| 31103 | If you want the loopback interface to be treated specially, you must ensure |
| 31104 | that there are appropriate entries in your ACLs. |
| 31105 | |
| 31106 | |
| 31107 | 47.1 Submission mode for non-local messages |
| 31108 | ------------------------------------------- |
| 31109 | |
| 31110 | Processing that happens automatically for locally-originated messages (unless |
| 31111 | suppress_local_fixups is set) can also be requested for messages that are |
| 31112 | received over TCP/IP. The term "submission mode" is used to describe this |
| 31113 | state. Submission mode is set by the modifier |
| 31114 | |
| 31115 | control = submission |
| 31116 | |
| 31117 | in a MAIL, RCPT, or pre-data ACL for an incoming message (see sections 43.21 |
| 31118 | and 43.22). This makes Exim treat the message as a local submission, and is |
| 31119 | normally used when the source of the message is known to be an MUA running on a |
| 31120 | client host (as opposed to an MTA). For example, to set submission mode for |
| 31121 | messages originating on the IPv4 loopback interface, you could include the |
| 31122 | following in the MAIL ACL: |
| 31123 | |
| 31124 | warn hosts = 127.0.0.1 |
| 31125 | control = submission |
| 31126 | |
| 31127 | There are some options that can be used when setting submission mode. A slash |
| 31128 | is used to separate options. For example: |
| 31129 | |
| 31130 | control = submission/sender_retain |
| 31131 | |
| 31132 | Specifying sender_retain has the effect of setting local_sender_retain true and |
| 31133 | local_from_check false for the current incoming message. The first of these |
| 31134 | allows an existing Sender: header in the message to remain, and the second |
| 31135 | suppresses the check to ensure that From: matches the authenticated sender. |
| 31136 | With this setting, Exim still fixes up messages by adding Date: and Message-ID: |
| 31137 | header lines if they are missing, but makes no attempt to check sender |
| 31138 | authenticity in header lines. |
| 31139 | |
| 31140 | When sender_retain is not set, a submission mode setting may specify a domain |
| 31141 | to be used when generating a From: or Sender: header line. For example: |
| 31142 | |
| 31143 | control = submission/domain=some.domain |
| 31144 | |
| 31145 | The domain may be empty. How this value is used is described in sections 47.11 |
| 31146 | and 47.16. There is also a name option that allows you to specify the user's |
| 31147 | full name for inclusion in a created Sender: or From: header line. For example: |
| 31148 | |
| 31149 | accept authenticated = * |
| 31150 | control = submission/domain=wonderland.example/\ |
| 31151 | name=${lookup {$authenticated_id} \ |
| 31152 | lsearch {/etc/exim/namelist}} |
| 31153 | |
| 31154 | Because the name may contain any characters, including slashes, the name option |
| 31155 | must be given last. The remainder of the string is used as the name. For the |
| 31156 | example above, if /etc/exim/namelist contains: |
| 31157 | |
| 31158 | bigegg: Humpty Dumpty |
| 31159 | |
| 31160 | then when the sender has authenticated as bigegg, the generated Sender: line |
| 31161 | would be: |
| 31162 | |
| 31163 | Sender: Humpty Dumpty <bigegg@wonderland.example> |
| 31164 | |
| 31165 | By default, submission mode forces the return path to the same address as is |
| 31166 | used to create the Sender: header. However, if sender_retain is specified, the |
| 31167 | return path is also left unchanged. |
| 31168 | |
| 31169 | Note: The changes caused by submission mode take effect after the predata ACL. |
| 31170 | This means that any sender checks performed before the fix-ups use the |
| 31171 | untrusted sender address specified by the user, not the trusted sender address |
| 31172 | specified by submission mode. Although this might be slightly unexpected, it |
| 31173 | does mean that you can configure ACL checks to spot that a user is trying to |
| 31174 | spoof another's address. |
| 31175 | |
| 31176 | |
| 31177 | 47.2 Line endings |
| 31178 | ----------------- |
| 31179 | |
| 31180 | RFC 2821 specifies that CRLF (two characters: carriage-return, followed by |
| 31181 | linefeed) is the line ending for messages transmitted over the Internet using |
| 31182 | SMTP over TCP/IP. However, within individual operating systems, different |
| 31183 | conventions are used. For example, Unix-like systems use just LF, but others |
| 31184 | use CRLF or just CR. |
| 31185 | |
| 31186 | Exim was designed for Unix-like systems, and internally, it stores messages |
| 31187 | using the system's convention of a single LF as a line terminator. When |
| 31188 | receiving a message, all line endings are translated to this standard format. |
| 31189 | Originally, it was thought that programs that passed messages directly to an |
| 31190 | MTA within an operating system would use that system's convention. Experience |
| 31191 | has shown that this is not the case; for example, there are Unix applications |
| 31192 | that use CRLF in this circumstance. For this reason, and for compatibility with |
| 31193 | other MTAs, the way Exim handles line endings for all messages is now as |
| 31194 | follows: |
| 31195 | |
| 31196 | * LF not preceded by CR is treated as a line ending. |
| 31197 | |
| 31198 | * CR is treated as a line ending; if it is immediately followed by LF, the LF |
| 31199 | is ignored. |
| 31200 | |
| 31201 | * The sequence "CR, dot, CR" does not terminate an incoming SMTP message, nor |
| 31202 | a local message in the state where a line containing only a dot is a |
| 31203 | terminator. |
| 31204 | |
| 31205 | * If a bare CR is encountered within a header line, an extra space is added |
| 31206 | after the line terminator so as not to end the header line. The reasoning |
| 31207 | behind this is that bare CRs in header lines are most likely either to be |
| 31208 | mistakes, or people trying to play silly games. |
| 31209 | |
| 31210 | * If the first header line received in a message ends with CRLF, a subsequent |
| 31211 | bare LF in a header line is treated in the same way as a bare CR in a |
| 31212 | header line. |
| 31213 | |
| 31214 | |
| 31215 | 47.3 Unqualified addresses |
| 31216 | -------------------------- |
| 31217 | |
| 31218 | By default, Exim expects every envelope address it receives from an external |
| 31219 | host to be fully qualified. Unqualified addresses cause negative responses to |
| 31220 | SMTP commands. However, because SMTP is used as a means of transporting |
| 31221 | messages from MUAs running on personal workstations, there is sometimes a |
| 31222 | requirement to accept unqualified addresses from specific hosts or IP networks. |
| 31223 | |
| 31224 | Exim has two options that separately control which hosts may send unqualified |
| 31225 | sender or recipient addresses in SMTP commands, namely sender_unqualified_hosts |
| 31226 | and recipient_unqualified_hosts. In both cases, if an unqualified address is |
| 31227 | accepted, it is qualified by adding the value of qualify_domain or |
| 31228 | qualify_recipient, as appropriate. |
| 31229 | |
| 31230 | Unqualified addresses in header lines are automatically qualified for messages |
| 31231 | that are locally originated, unless the -bnq option is given on the command |
| 31232 | line. For messages received over SMTP, unqualified addresses in header lines |
| 31233 | are qualified only if unqualified addresses are permitted in SMTP commands. In |
| 31234 | other words, such qualification is also controlled by sender_unqualified_hosts |
| 31235 | and recipient_unqualified_hosts, |
| 31236 | |
| 31237 | |
| 31238 | 47.4 The UUCP From line |
| 31239 | ----------------------- |
| 31240 | |
| 31241 | Messages that have come from UUCP (and some other applications) often begin |
| 31242 | with a line containing the envelope sender and a timestamp, following the word |
| 31243 | "From". Examples of two common formats are: |
| 31244 | |
| 31245 | From a.oakley@berlin.mus Fri Jan 5 12:35 GMT 1996 |
| 31246 | From f.butler@berlin.mus Fri, 7 Jan 97 14:00:00 GMT |
| 31247 | |
| 31248 | This line precedes the RFC 2822 header lines. For compatibility with Sendmail, |
| 31249 | Exim recognizes such lines at the start of messages that are submitted to it |
| 31250 | via the command line (that is, on the standard input). It does not recognize |
| 31251 | such lines in incoming SMTP messages, unless the sending host matches |
| 31252 | ignore_fromline_hosts or the -bs option was used for a local message and |
| 31253 | ignore_fromline_local is set. The recognition is controlled by a regular |
| 31254 | expression that is defined by the uucp_from_pattern option, whose default value |
| 31255 | matches the two common cases shown above and puts the address that follows |
| 31256 | "From" into $1. |
| 31257 | |
| 31258 | When the caller of Exim for a non-SMTP message that contains a "From" line is a |
| 31259 | trusted user, the message's sender address is constructed by expanding the |
| 31260 | contents of uucp_sender_address, whose default value is "$1". This is then |
| 31261 | parsed as an RFC 2822 address. If there is no domain, the local part is |
| 31262 | qualified with qualify_domain unless it is the empty string. However, if the |
| 31263 | command line -f option is used, it overrides the "From" line. |
| 31264 | |
| 31265 | If the caller of Exim is not trusted, the "From" line is recognized, but the |
| 31266 | sender address is not changed. This is also the case for incoming SMTP messages |
| 31267 | that are permitted to contain "From" lines. |
| 31268 | |
| 31269 | Only one "From" line is recognized. If there is more than one, the second is |
| 31270 | treated as a data line that starts the body of the message, as it is not valid |
| 31271 | as a header line. This also happens if a "From" line is present in an incoming |
| 31272 | SMTP message from a source that is not permitted to send them. |
| 31273 | |
| 31274 | |
| 31275 | 47.5 Resent- header lines |
| 31276 | ------------------------- |
| 31277 | |
| 31278 | RFC 2822 makes provision for sets of header lines starting with the string |
| 31279 | "Resent-" to be added to a message when it is resent by the original recipient |
| 31280 | to somebody else. These headers are Resent-Date:, Resent-From:, Resent-Sender:, |
| 31281 | Resent-To:, Resent-Cc:, Resent-Bcc: and Resent-Message-ID:. The RFC says: |
| 31282 | |
| 31283 | Resent fields are strictly informational. They MUST NOT be used in the |
| 31284 | normal processing of replies or other such automatic actions on messages. |
| 31285 | |
| 31286 | This leaves things a bit vague as far as other processing actions such as |
| 31287 | address rewriting are concerned. Exim treats Resent- header lines as follows: |
| 31288 | |
| 31289 | * A Resent-From: line that just contains the login id of the submitting user |
| 31290 | is automatically rewritten in the same way as From: (see below). |
| 31291 | |
| 31292 | * If there's a rewriting rule for a particular header line, it is also |
| 31293 | applied to Resent- header lines of the same type. For example, a rule that |
| 31294 | rewrites From: also rewrites Resent-From:. |
| 31295 | |
| 31296 | * For local messages, if Sender: is removed on input, Resent-Sender: is also |
| 31297 | removed. |
| 31298 | |
| 31299 | * For a locally-submitted message, if there are any Resent- header lines but |
| 31300 | no Resent-Date:, Resent-From:, or Resent-Message-Id:, they are added as |
| 31301 | necessary. It is the contents of Resent-Message-Id: (rather than |
| 31302 | Message-Id:) which are included in log lines in this case. |
| 31303 | |
| 31304 | * The logic for adding Sender: is duplicated for Resent-Sender: when any |
| 31305 | Resent- header lines are present. |
| 31306 | |
| 31307 | |
| 31308 | 47.6 The Auto-Submitted: header line |
| 31309 | ------------------------------------ |
| 31310 | |
| 31311 | Whenever Exim generates an autoreply, a bounce, or a delay warning message, it |
| 31312 | includes the header line: |
| 31313 | |
| 31314 | Auto-Submitted: auto-replied |
| 31315 | |
| 31316 | |
| 31317 | 47.7 The Bcc: header line |
| 31318 | ------------------------- |
| 31319 | |
| 31320 | If Exim is called with the -t option, to take recipient addresses from a |
| 31321 | message's header, it removes any Bcc: header line that may exist (after |
| 31322 | extracting its addresses). If -t is not present on the command line, any |
| 31323 | existing Bcc: is not removed. |
| 31324 | |
| 31325 | |
| 31326 | 47.8 The Date: header line |
| 31327 | -------------------------- |
| 31328 | |
| 31329 | If a locally-generated or submission-mode message has no Date: header line, |
| 31330 | Exim adds one, using the current date and time, unless the |
| 31331 | suppress_local_fixups control has been specified. |
| 31332 | |
| 31333 | |
| 31334 | 47.9 The Delivery-date: header line |
| 31335 | ----------------------------------- |
| 31336 | |
| 31337 | Delivery-date: header lines are not part of the standard RFC 2822 header set. |
| 31338 | Exim can be configured to add them to the final delivery of messages. (See the |
| 31339 | generic delivery_date_add transport option.) They should not be present in |
| 31340 | messages in transit. If the delivery_date_remove configuration option is set |
| 31341 | (the default), Exim removes Delivery-date: header lines from incoming messages. |
| 31342 | |
| 31343 | |
| 31344 | 47.10 The Envelope-to: header line |
| 31345 | ---------------------------------- |
| 31346 | |
| 31347 | Envelope-to: header lines are not part of the standard RFC 2822 header set. |
| 31348 | Exim can be configured to add them to the final delivery of messages. (See the |
| 31349 | generic envelope_to_add transport option.) They should not be present in |
| 31350 | messages in transit. If the envelope_to_remove configuration option is set (the |
| 31351 | default), Exim removes Envelope-to: header lines from incoming messages. |
| 31352 | |
| 31353 | |
| 31354 | 47.11 The From: header line |
| 31355 | --------------------------- |
| 31356 | |
| 31357 | If a submission-mode message does not contain a From: header line, Exim adds |
| 31358 | one if either of the following conditions is true: |
| 31359 | |
| 31360 | * The envelope sender address is not empty (that is, this is not a bounce |
| 31361 | message). The added header line copies the envelope sender address. |
| 31362 | |
| 31363 | * The SMTP session is authenticated and $authenticated_id is not empty. |
| 31364 | |
| 31365 | 1. If no domain is specified by the submission control, the local part is |
| 31366 | $authenticated_id and the domain is $qualify_domain. |
| 31367 | |
| 31368 | 2. If a non-empty domain is specified by the submission control, the local |
| 31369 | part is $authenticated_id, and the domain is the specified domain. |
| 31370 | |
| 31371 | 3. If an empty domain is specified by the submission control, |
| 31372 | $authenticated_id is assumed to be the complete address. |
| 31373 | |
| 31374 | A non-empty envelope sender takes precedence. |
| 31375 | |
| 31376 | If a locally-generated incoming message does not contain a From: header line, |
| 31377 | and the suppress_local_fixups control is not set, Exim adds one containing the |
| 31378 | sender's address. The calling user's login name and full name are used to |
| 31379 | construct the address, as described in section 47.18. They are obtained from |
| 31380 | the password data by calling getpwuid() (but see the unknown_login |
| 31381 | configuration option). The address is qualified with qualify_domain. |
| 31382 | |
| 31383 | For compatibility with Sendmail, if an incoming, non-SMTP message has a From: |
| 31384 | header line containing just the unqualified login name of the calling user, |
| 31385 | this is replaced by an address containing the user's login name and full name |
| 31386 | as described in section 47.18. |
| 31387 | |
| 31388 | |
| 31389 | 47.12 The Message-ID: header line |
| 31390 | --------------------------------- |
| 31391 | |
| 31392 | If a locally-generated or submission-mode incoming message does not contain a |
| 31393 | Message-ID: or Resent-Message-ID: header line, and the suppress_local_fixups |
| 31394 | control is not set, Exim adds a suitable header line to the message. If there |
| 31395 | are any Resent-: headers in the message, it creates Resent-Message-ID:. The id |
| 31396 | is constructed from Exim's internal message id, preceded by the letter E to |
| 31397 | ensure it starts with a letter, and followed by @ and the primary host name. |
| 31398 | Additional information can be included in this header line by setting the |
| 31399 | message_id_header_text and/or message_id_header_domain options. |
| 31400 | |
| 31401 | |
| 31402 | 47.13 The Received: header line |
| 31403 | ------------------------------- |
| 31404 | |
| 31405 | A Received: header line is added at the start of every message. The contents |
| 31406 | are defined by the received_header_text configuration option, and Exim |
| 31407 | automatically adds a semicolon and a timestamp to the configured string. |
| 31408 | |
| 31409 | The Received: header is generated as soon as the message's header lines have |
| 31410 | been received. At this stage, the timestamp in the Received: header line is the |
| 31411 | time that the message started to be received. This is the value that is seen by |
| 31412 | the DATA ACL and by the local_scan() function. |
| 31413 | |
| 31414 | Once a message is accepted, the timestamp in the Received: header line is |
| 31415 | changed to the time of acceptance, which is (apart from a small delay while the |
| 31416 | -H spool file is written) the earliest time at which delivery could start. |
| 31417 | |
| 31418 | |
| 31419 | 47.14 The References: header line |
| 31420 | --------------------------------- |
| 31421 | |
| 31422 | Messages created by the autoreply transport include a References: header line. |
| 31423 | This is constructed according to the rules that are described in section 3.64 |
| 31424 | of RFC 2822 (which states that replies should contain such a header line), and |
| 31425 | section 3.14 of RFC 3834 (which states that automatic responses are not |
| 31426 | different in this respect). However, because some mail processing software does |
| 31427 | not cope well with very long header lines, no more than 12 message IDs are |
| 31428 | copied from the References: header line in the incoming message. If there are |
| 31429 | more than 12, the first one and then the final 11 are copied, before adding the |
| 31430 | message ID of the incoming message. |
| 31431 | |
| 31432 | |
| 31433 | 47.15 The Return-path: header line |
| 31434 | ---------------------------------- |
| 31435 | |
| 31436 | Return-path: header lines are defined as something an MTA may insert when it |
| 31437 | does the final delivery of messages. (See the generic return_path_add transport |
| 31438 | option.) Therefore, they should not be present in messages in transit. If the |
| 31439 | return_path_remove configuration option is set (the default), Exim removes |
| 31440 | Return-path: header lines from incoming messages. |
| 31441 | |
| 31442 | |
| 31443 | 47.16 The Sender: header line |
| 31444 | ----------------------------- |
| 31445 | |
| 31446 | For a locally-originated message from an untrusted user, Exim may remove an |
| 31447 | existing Sender: header line, and it may add a new one. You can modify these |
| 31448 | actions by setting the local_sender_retain option true, the local_from_check |
| 31449 | option false, or by using the suppress_local_fixups control setting. |
| 31450 | |
| 31451 | When a local message is received from an untrusted user and local_from_check is |
| 31452 | true (the default), and the suppress_local_fixups control has not been set, a |
| 31453 | check is made to see if the address given in the From: header line is the |
| 31454 | correct (local) sender of the message. The address that is expected has the |
| 31455 | login name as the local part and the value of qualify_domain as the domain. |
| 31456 | Prefixes and suffixes for the local part can be permitted by setting |
| 31457 | local_from_prefix and local_from_suffix appropriately. If From: does not |
| 31458 | contain the correct sender, a Sender: line is added to the message. |
| 31459 | |
| 31460 | If you set local_from_check false, this checking does not occur. However, the |
| 31461 | removal of an existing Sender: line still happens, unless you also set |
| 31462 | local_sender_retain to be true. It is not possible to set both of these options |
| 31463 | true at the same time. |
| 31464 | |
| 31465 | By default, no processing of Sender: header lines is done for messages received |
| 31466 | over TCP/IP or for messages submitted by trusted users. However, when a message |
| 31467 | is received over TCP/IP in submission mode, and sender_retain is not specified |
| 31468 | on the submission control, the following processing takes place: |
| 31469 | |
| 31470 | First, any existing Sender: lines are removed. Then, if the SMTP session is |
| 31471 | authenticated, and $authenticated_id is not empty, a sender address is created |
| 31472 | as follows: |
| 31473 | |
| 31474 | * If no domain is specified by the submission control, the local part is |
| 31475 | $authenticated_id and the domain is $qualify_domain. |
| 31476 | |
| 31477 | * If a non-empty domain is specified by the submission control, the local |
| 31478 | part is $authenticated_id, and the domain is the specified domain. |
| 31479 | |
| 31480 | * If an empty domain is specified by the submission control, |
| 31481 | $authenticated_id is assumed to be the complete address. |
| 31482 | |
| 31483 | This address is compared with the address in the From: header line. If they are |
| 31484 | different, a Sender: header line containing the created address is added. |
| 31485 | Prefixes and suffixes for the local part in From: can be permitted by setting |
| 31486 | local_from_prefix and local_from_suffix appropriately. |
| 31487 | |
| 31488 | Note: Whenever a Sender: header line is created, the return path for the |
| 31489 | message (the envelope sender address) is changed to be the same address, except |
| 31490 | in the case of submission mode when sender_retain is specified. |
| 31491 | |
| 31492 | |
| 31493 | 47.17 Adding and removing header lines in routers and transports |
| 31494 | ---------------------------------------------------------------- |
| 31495 | |
| 31496 | When a message is delivered, the addition and removal of header lines can be |
| 31497 | specified in a system filter, or on any of the routers and transports that |
| 31498 | process the message. Section 46.6 contains details about modifying headers in a |
| 31499 | system filter. Header lines can also be added in an ACL as a message is |
| 31500 | received (see section 43.24). |
| 31501 | |
| 31502 | In contrast to what happens in a system filter, header modifications that are |
| 31503 | specified on routers and transports apply only to the particular recipient |
| 31504 | addresses that are being processed by those routers and transports. These |
| 31505 | changes do not actually take place until a copy of the message is being |
| 31506 | transported. Therefore, they do not affect the basic set of header lines, and |
| 31507 | they do not affect the values of the variables that refer to header lines. |
| 31508 | |
| 31509 | Note: In particular, this means that any expansions in the configuration of the |
| 31510 | transport cannot refer to the modified header lines, because such expansions |
| 31511 | all occur before the message is actually transported. |
| 31512 | |
| 31513 | For both routers and transports, the argument of a headers_add option must be |
| 31514 | in the form of one or more RFC 2822 header lines, separated by newlines (coded |
| 31515 | as "\n"). For example: |
| 31516 | |
| 31517 | headers_add = X-added-header: added by $primary_hostname\n\ |
| 31518 | X-added-second: another added header line |
| 31519 | |
| 31520 | Exim does not check the syntax of these added header lines. |
| 31521 | |
| 31522 | Multiple headers_add options for a single router or transport can be specified; |
| 31523 | the values will append to a single list of header lines. Each header-line is |
| 31524 | separately expanded. |
| 31525 | |
| 31526 | The argument of a headers_remove option must consist of a colon-separated list |
| 31527 | of header names. This is confusing, because header names themselves are often |
| 31528 | terminated by colons. In this case, the colons are the list separators, not |
| 31529 | part of the names. For example: |
| 31530 | |
| 31531 | headers_remove = return-receipt-to:acknowledge-to |
| 31532 | |
| 31533 | Multiple headers_remove options for a single router or transport can be |
| 31534 | specified; the arguments will append to a single header-names list. Each item |
| 31535 | is separately expanded. Note that colons in complex expansions which are used |
| 31536 | to form all or part of a headers_remove list will act as list separators. |
| 31537 | |
| 31538 | When headers_add or headers_remove is specified on a router, items are expanded |
| 31539 | at routing time, and then associated with all addresses that are accepted by |
| 31540 | that router, and also with any new addresses that it generates. If an address |
| 31541 | passes through several routers as a result of aliasing or forwarding, the |
| 31542 | changes are cumulative. |
| 31543 | |
| 31544 | However, this does not apply to multiple routers that result from the use of |
| 31545 | the unseen option. Any header modifications that were specified by the "unseen" |
| 31546 | router or its predecessors apply only to the "unseen" delivery. |
| 31547 | |
| 31548 | Addresses that end up with different headers_add or headers_remove settings |
| 31549 | cannot be delivered together in a batch, so a transport is always dealing with |
| 31550 | a set of addresses that have the same header-processing requirements. |
| 31551 | |
| 31552 | The transport starts by writing the original set of header lines that arrived |
| 31553 | with the message, possibly modified by the system filter. As it writes out |
| 31554 | these lines, it consults the list of header names that were attached to the |
| 31555 | recipient address(es) by headers_remove options in routers, and it also |
| 31556 | consults the transport's own headers_remove option. Header lines whose names |
| 31557 | are on either of these lists are not written out. If there are multiple |
| 31558 | instances of any listed header, they are all skipped. |
| 31559 | |
| 31560 | After the remaining original header lines have been written, new header lines |
| 31561 | that were specified by routers' headers_add options are written, in the order |
| 31562 | in which they were attached to the address. These are followed by any header |
| 31563 | lines specified by the transport's headers_add option. |
| 31564 | |
| 31565 | This way of handling header line modifications in routers and transports has |
| 31566 | the following consequences: |
| 31567 | |
| 31568 | * The original set of header lines, possibly modified by the system filter, |
| 31569 | remains "visible", in the sense that the $header_xxx variables refer to it, |
| 31570 | at all times. |
| 31571 | |
| 31572 | * Header lines that are added by a router's headers_add option are not |
| 31573 | accessible by means of the $header_xxx expansion syntax in subsequent |
| 31574 | routers or the transport. |
| 31575 | |
| 31576 | * Conversely, header lines that are specified for removal by headers_remove |
| 31577 | in a router remain visible to subsequent routers and the transport. |
| 31578 | |
| 31579 | * Headers added to an address by headers_add in a router cannot be removed by |
| 31580 | a later router or by a transport. |
| 31581 | |
| 31582 | * An added header can refer to the contents of an original header that is to |
| 31583 | be removed, even it has the same name as the added header. For example: |
| 31584 | |
| 31585 | headers_remove = subject |
| 31586 | headers_add = Subject: new subject (was: $h_subject:) |
| 31587 | |
| 31588 | Warning: The headers_add and headers_remove options cannot be used for a |
| 31589 | redirect router that has the one_time option set. |
| 31590 | |
| 31591 | |
| 31592 | 47.18 Constructed addresses |
| 31593 | --------------------------- |
| 31594 | |
| 31595 | When Exim constructs a sender address for a locally-generated message, it uses |
| 31596 | the form |
| 31597 | |
| 31598 | <user name> <login@qualify_domain> |
| 31599 | |
| 31600 | For example: |
| 31601 | |
| 31602 | Zaphod Beeblebrox <zaphod@end.univ.example> |
| 31603 | |
| 31604 | The user name is obtained from the -F command line option if set, or otherwise |
| 31605 | by looking up the calling user by getpwuid() and extracting the "gecos" field |
| 31606 | from the password entry. If the "gecos" field contains an ampersand character, |
| 31607 | this is replaced by the login name with the first letter upper cased, as is |
| 31608 | conventional in a number of operating systems. See the gecos_name option for a |
| 31609 | way to tailor the handling of the "gecos" field. The unknown_username option |
| 31610 | can be used to specify user names in cases when there is no password file |
| 31611 | entry. |
| 31612 | |
| 31613 | In all cases, the user name is made to conform to RFC 2822 by quoting all or |
| 31614 | parts of it if necessary. In addition, if it contains any non-printing |
| 31615 | characters, it is encoded as described in RFC 2047, which defines a way of |
| 31616 | including non-ASCII characters in header lines. The value of the |
| 31617 | headers_charset option specifies the name of the encoding that is used (the |
| 31618 | characters are assumed to be in this encoding). The setting of |
| 31619 | print_topbitchars controls whether characters with the top bit set (that is, |
| 31620 | with codes greater than 127) count as printing characters or not. |
| 31621 | |
| 31622 | |
| 31623 | 47.19 Case of local parts |
| 31624 | ------------------------- |
| 31625 | |
| 31626 | RFC 2822 states that the case of letters in the local parts of addresses cannot |
| 31627 | be assumed to be non-significant. Exim preserves the case of local parts of |
| 31628 | addresses, but by default it uses a lower-cased form when it is routing, |
| 31629 | because on most Unix systems, usernames are in lower case and case-insensitive |
| 31630 | routing is required. However, any particular router can be made to use the |
| 31631 | original case for local parts by setting the caseful_local_part generic router |
| 31632 | option. |
| 31633 | |
| 31634 | If you must have mixed-case user names on your system, the best way to proceed, |
| 31635 | assuming you want case-independent handling of incoming email, is to set up |
| 31636 | your first router to convert incoming local parts in your domains to the |
| 31637 | correct case by means of a file lookup. For example: |
| 31638 | |
| 31639 | correct_case: |
| 31640 | driver = redirect |
| 31641 | domains = +local_domains |
| 31642 | data = ${lookup{$local_part}cdb\ |
| 31643 | {/etc/usercased.cdb}{$value}fail}\ |
| 31644 | @$domain |
| 31645 | |
| 31646 | For this router, the local part is forced to lower case by the default action ( |
| 31647 | caseful_local_part is not set). The lower-cased local part is used to look up a |
| 31648 | new local part in the correct case. If you then set caseful_local_part on any |
| 31649 | subsequent routers which process your domains, they will operate on local parts |
| 31650 | with the correct case in a case-sensitive manner. |
| 31651 | |
| 31652 | |
| 31653 | 47.20 Dots in local parts |
| 31654 | ------------------------- |
| 31655 | |
| 31656 | RFC 2822 forbids empty components in local parts. That is, an unquoted local |
| 31657 | part may not begin or end with a dot, nor have two consecutive dots in the |
| 31658 | middle. However, it seems that many MTAs do not enforce this, so Exim permits |
| 31659 | empty components for compatibility. |
| 31660 | |
| 31661 | |
| 31662 | 47.21 Rewriting addresses |
| 31663 | ------------------------- |
| 31664 | |
| 31665 | Rewriting of sender and recipient addresses, and addresses in headers, can |
| 31666 | happen automatically, or as the result of configuration options, as described |
| 31667 | in chapter 31. The headers that may be affected by this are Bcc:, Cc:, From:, |
| 31668 | Reply-To:, Sender:, and To:. |
| 31669 | |
| 31670 | Automatic rewriting includes qualification, as mentioned above. The other case |
| 31671 | in which it can happen is when an incomplete non-local domain is given. The |
| 31672 | routing process may cause this to be expanded into the full domain name. For |
| 31673 | example, a header such as |
| 31674 | |
| 31675 | To: hare@teaparty |
| 31676 | |
| 31677 | might get rewritten as |
| 31678 | |
| 31679 | To: hare@teaparty.wonderland.fict.example |
| 31680 | |
| 31681 | Rewriting as a result of routing is the one kind of message processing that |
| 31682 | does not happen at input time, as it cannot be done until the address has been |
| 31683 | routed. |
| 31684 | |
| 31685 | Strictly, one should not do any deliveries of a message until all its addresses |
| 31686 | have been routed, in case any of the headers get changed as a result of |
| 31687 | routing. However, doing this in practice would hold up many deliveries for |
| 31688 | unreasonable amounts of time, just because one address could not immediately be |
| 31689 | routed. Exim therefore does not delay other deliveries when routing of one or |
| 31690 | more addresses is deferred. |
| 31691 | |
| 31692 | |
| 31693 | |
| 31694 | =============================================================================== |
| 31695 | 48. SMTP PROCESSING |
| 31696 | |
| 31697 | Exim supports a number of different ways of using the SMTP protocol, and its |
| 31698 | LMTP variant, which is an interactive protocol for transferring messages into a |
| 31699 | closed mail store application. This chapter contains details of how SMTP is |
| 31700 | processed. For incoming mail, the following are available: |
| 31701 | |
| 31702 | * SMTP over TCP/IP (Exim daemon or inetd); |
| 31703 | |
| 31704 | * SMTP over the standard input and output (the -bs option); |
| 31705 | |
| 31706 | * Batched SMTP on the standard input (the -bS option). |
| 31707 | |
| 31708 | For mail delivery, the following are available: |
| 31709 | |
| 31710 | * SMTP over TCP/IP (the smtp transport); |
| 31711 | |
| 31712 | * LMTP over TCP/IP (the smtp transport with the protocol option set to |
| 31713 | "lmtp"); |
| 31714 | |
| 31715 | * LMTP over a pipe to a process running in the local host (the lmtp |
| 31716 | transport); |
| 31717 | |
| 31718 | * Batched SMTP to a file or pipe (the appendfile and pipe transports with the |
| 31719 | use_bsmtp option set). |
| 31720 | |
| 31721 | Batched SMTP is the name for a process in which batches of messages are stored |
| 31722 | in or read from files (or pipes), in a format in which SMTP commands are used |
| 31723 | to contain the envelope information. |
| 31724 | |
| 31725 | |
| 31726 | 48.1 Outgoing SMTP and LMTP over TCP/IP |
| 31727 | --------------------------------------- |
| 31728 | |
| 31729 | Outgoing SMTP and LMTP over TCP/IP is implemented by the smtp transport. The |
| 31730 | protocol option selects which protocol is to be used, but the actual processing |
| 31731 | is the same in both cases. |
| 31732 | |
| 31733 | If, in response to its EHLO command, Exim is told that the SIZE parameter is |
| 31734 | supported, it adds SIZE=<n> to each subsequent MAIL command. The value of <n> |
| 31735 | is the message size plus the value of the size_addition option (default 1024) |
| 31736 | to allow for additions to the message such as per-transport header lines, or |
| 31737 | changes made in a transport filter. If size_addition is set negative, the use |
| 31738 | of SIZE is suppressed. |
| 31739 | |
| 31740 | If the remote server advertises support for PIPELINING, Exim uses the |
| 31741 | pipelining extension to SMTP (RFC 2197) to reduce the number of TCP/IP packets |
| 31742 | required for the transaction. |
| 31743 | |
| 31744 | If the remote server advertises support for the STARTTLS command, and Exim was |
| 31745 | built to support TLS encryption, it tries to start a TLS session unless the |
| 31746 | server matches hosts_avoid_tls. See chapter 42 for more details. Either a match |
| 31747 | in that or hosts_verify_avoid_tls apply when the transport is called for |
| 31748 | verification. |
| 31749 | |
| 31750 | If the remote server advertises support for the AUTH command, Exim scans the |
| 31751 | authenticators configuration for any suitable client settings, as described in |
| 31752 | chapter 33. |
| 31753 | |
| 31754 | Responses from the remote host are supposed to be terminated by CR followed by |
| 31755 | LF. However, there are known to be hosts that do not send CR characters, so in |
| 31756 | order to be able to interwork with such hosts, Exim treats LF on its own as a |
| 31757 | line terminator. |
| 31758 | |
| 31759 | If a message contains a number of different addresses, all those with the same |
| 31760 | characteristics (for example, the same envelope sender) that resolve to the |
| 31761 | same set of hosts, in the same order, are sent in a single SMTP transaction, |
| 31762 | even if they are for different domains, unless there are more than the setting |
| 31763 | of the max_rcpts option in the smtp transport allows, in which case they are |
| 31764 | split into groups containing no more than max_rcpts addresses each. If |
| 31765 | remote_max_parallel is greater than one, such groups may be sent in parallel |
| 31766 | sessions. The order of hosts with identical MX values is not significant when |
| 31767 | checking whether addresses can be batched in this way. |
| 31768 | |
| 31769 | When the smtp transport suffers a temporary failure that is not |
| 31770 | message-related, Exim updates its transport-specific database, which contains |
| 31771 | records indexed by host name that remember which messages are waiting for each |
| 31772 | particular host. It also updates the retry database with new retry times. |
| 31773 | |
| 31774 | Exim's retry hints are based on host name plus IP address, so if one address of |
| 31775 | a multi-homed host is broken, it will soon be skipped most of the time. See the |
| 31776 | next section for more detail about error handling. |
| 31777 | |
| 31778 | When a message is successfully delivered over a TCP/IP SMTP connection, Exim |
| 31779 | looks in the hints database for the transport to see if there are any queued |
| 31780 | messages waiting for the host to which it is connected. If it finds one, it |
| 31781 | creates a new Exim process using the -MC option (which can only be used by a |
| 31782 | process running as root or the Exim user) and passes the TCP/IP socket to it so |
| 31783 | that it can deliver another message using the same socket. The new process does |
| 31784 | only those deliveries that are routed to the connected host, and may in turn |
| 31785 | pass the socket on to a third process, and so on. |
| 31786 | |
| 31787 | The connection_max_messages option of the smtp transport can be used to limit |
| 31788 | the number of messages sent down a single TCP/IP connection. |
| 31789 | |
| 31790 | The second and subsequent messages delivered down an existing connection are |
| 31791 | identified in the main log by the addition of an asterisk after the closing |
| 31792 | square bracket of the IP address. |
| 31793 | |
| 31794 | |
| 31795 | 48.2 Errors in outgoing SMTP |
| 31796 | ---------------------------- |
| 31797 | |
| 31798 | Three different kinds of error are recognized for outgoing SMTP: host errors, |
| 31799 | message errors, and recipient errors. |
| 31800 | |
| 31801 | Host errors |
| 31802 | |
| 31803 | A host error is not associated with a particular message or with a |
| 31804 | particular recipient of a message. The host errors are: |
| 31805 | |
| 31806 | + Connection refused or timed out, |
| 31807 | |
| 31808 | + Any error response code on connection, |
| 31809 | |
| 31810 | + Any error response code to EHLO or HELO, |
| 31811 | |
| 31812 | + Loss of connection at any time, except after ".", |
| 31813 | |
| 31814 | + I/O errors at any time, |
| 31815 | |
| 31816 | + Timeouts during the session, other than in response to MAIL, RCPT or |
| 31817 | the "." at the end of the data. |
| 31818 | |
| 31819 | For a host error, a permanent error response on connection, or in response |
| 31820 | to EHLO, causes all addresses routed to the host to be failed. Any other |
| 31821 | host error causes all addresses to be deferred, and retry data to be |
| 31822 | created for the host. It is not tried again, for any message, until its |
| 31823 | retry time arrives. If the current set of addresses are not all delivered |
| 31824 | in this run (to some alternative host), the message is added to the list of |
| 31825 | those waiting for this host, so if it is still undelivered when a |
| 31826 | subsequent successful delivery is made to the host, it will be sent down |
| 31827 | the same SMTP connection. |
| 31828 | |
| 31829 | Message errors |
| 31830 | |
| 31831 | A message error is associated with a particular message when sent to a |
| 31832 | particular host, but not with a particular recipient of the message. The |
| 31833 | message errors are: |
| 31834 | |
| 31835 | + Any error response code to MAIL, DATA, or the "." that terminates the |
| 31836 | data, |
| 31837 | |
| 31838 | + Timeout after MAIL, |
| 31839 | |
| 31840 | + Timeout or loss of connection after the "." that terminates the data. A |
| 31841 | timeout after the DATA command itself is treated as a host error, as is |
| 31842 | loss of connection at any other time. |
| 31843 | |
| 31844 | For a message error, a permanent error response (5xx) causes all addresses |
| 31845 | to be failed, and a delivery error report to be returned to the sender. A |
| 31846 | temporary error response (4xx), or one of the timeouts, causes all |
| 31847 | addresses to be deferred. Retry data is not created for the host, but |
| 31848 | instead, a retry record for the combination of host plus message id is |
| 31849 | created. The message is not added to the list of those waiting for this |
| 31850 | host. This ensures that the failing message will not be sent to this host |
| 31851 | again until the retry time arrives. However, other messages that are routed |
| 31852 | to the host are not affected, so if it is some property of the message that |
| 31853 | is causing the error, it will not stop the delivery of other mail. |
| 31854 | |
| 31855 | If the remote host specified support for the SIZE parameter in its response |
| 31856 | to EHLO, Exim adds SIZE=nnn to the MAIL command, so an over-large message |
| 31857 | will cause a message error because the error arrives as a response to MAIL. |
| 31858 | |
| 31859 | Recipient errors |
| 31860 | |
| 31861 | A recipient error is associated with a particular recipient of a message. |
| 31862 | The recipient errors are: |
| 31863 | |
| 31864 | + Any error response to RCPT, |
| 31865 | |
| 31866 | + Timeout after RCPT. |
| 31867 | |
| 31868 | For a recipient error, a permanent error response (5xx) causes the |
| 31869 | recipient address to be failed, and a bounce message to be returned to the |
| 31870 | sender. A temporary error response (4xx) or a timeout causes the failing |
| 31871 | address to be deferred, and routing retry data to be created for it. This |
| 31872 | is used to delay processing of the address in subsequent queue runs, until |
| 31873 | its routing retry time arrives. This applies to all messages, but because |
| 31874 | it operates only in queue runs, one attempt will be made to deliver a new |
| 31875 | message to the failing address before the delay starts to operate. This |
| 31876 | ensures that, if the failure is really related to the message rather than |
| 31877 | the recipient ("message too big for this recipient" is a possible example), |
| 31878 | other messages have a chance of getting delivered. If a delivery to the |
| 31879 | address does succeed, the retry information gets cleared, so all stuck |
| 31880 | messages get tried again, and the retry clock is reset. |
| 31881 | |
| 31882 | The message is not added to the list of those waiting for this host. Use of |
| 31883 | the host for other messages is unaffected, and except in the case of a |
| 31884 | timeout, other recipients are processed independently, and may be |
| 31885 | successfully delivered in the current SMTP session. After a timeout it is |
| 31886 | of course impossible to proceed with the session, so all addresses get |
| 31887 | deferred. However, those other than the one that failed do not suffer any |
| 31888 | subsequent retry delays. Therefore, if one recipient is causing trouble, |
| 31889 | the others have a chance of getting through when a subsequent delivery |
| 31890 | attempt occurs before the failing recipient's retry time. |
| 31891 | |
| 31892 | In all cases, if there are other hosts (or IP addresses) available for the |
| 31893 | current set of addresses (for example, from multiple MX records), they are |
| 31894 | tried in this run for any undelivered addresses, subject of course to their own |
| 31895 | retry data. In other words, recipient error retry data does not take effect |
| 31896 | until the next delivery attempt. |
| 31897 | |
| 31898 | Some hosts have been observed to give temporary error responses to every MAIL |
| 31899 | command at certain times ("insufficient space" has been seen). It would be nice |
| 31900 | if such circumstances could be recognized, and defer data for the host itself |
| 31901 | created, but this is not possible within the current Exim design. What actually |
| 31902 | happens is that retry data for every (host, message) combination is created. |
| 31903 | |
| 31904 | The reason that timeouts after MAIL and RCPT are treated specially is that |
| 31905 | these can sometimes arise as a result of the remote host's verification |
| 31906 | procedures. Exim makes this assumption, and treats them as if a temporary error |
| 31907 | response had been received. A timeout after "." is treated specially because it |
| 31908 | is known that some broken implementations fail to recognize the end of the |
| 31909 | message if the last character of the last line is a binary zero. Thus, it is |
| 31910 | helpful to treat this case as a message error. |
| 31911 | |
| 31912 | Timeouts at other times are treated as host errors, assuming a problem with the |
| 31913 | host, or the connection to it. If a timeout after MAIL, RCPT, or "." is really |
| 31914 | a connection problem, the assumption is that at the next try the timeout is |
| 31915 | likely to occur at some other point in the dialogue, causing it then to be |
| 31916 | treated as a host error. |
| 31917 | |
| 31918 | There is experimental evidence that some MTAs drop the connection after the |
| 31919 | terminating "." if they do not like the contents of the message for some |
| 31920 | reason, in contravention of the RFC, which indicates that a 5xx response should |
| 31921 | be given. That is why Exim treats this case as a message rather than a host |
| 31922 | error, in order not to delay other messages to the same host. |
| 31923 | |
| 31924 | |
| 31925 | 48.3 Incoming SMTP messages over TCP/IP |
| 31926 | --------------------------------------- |
| 31927 | |
| 31928 | Incoming SMTP messages can be accepted in one of two ways: by running a |
| 31929 | listening daemon, or by using inetd. In the latter case, the entry in /etc/ |
| 31930 | inetd.conf should be like this: |
| 31931 | |
| 31932 | smtp stream tcp nowait exim /opt/exim/bin/exim in.exim -bs |
| 31933 | |
| 31934 | Exim distinguishes between this case and the case of a locally running user |
| 31935 | agent using the -bs option by checking whether or not the standard input is a |
| 31936 | socket. When it is, either the port must be privileged (less than 1024), or the |
| 31937 | caller must be root or the Exim user. If any other user passes a socket with an |
| 31938 | unprivileged port number, Exim prints a message on the standard error stream |
| 31939 | and exits with an error code. |
| 31940 | |
| 31941 | By default, Exim does not make a log entry when a remote host connects or |
| 31942 | disconnects (either via the daemon or inetd), unless the disconnection is |
| 31943 | unexpected. It can be made to write such log entries by setting the |
| 31944 | smtp_connection log selector. |
| 31945 | |
| 31946 | Commands from the remote host are supposed to be terminated by CR followed by |
| 31947 | LF. However, there are known to be hosts that do not send CR characters. In |
| 31948 | order to be able to interwork with such hosts, Exim treats LF on its own as a |
| 31949 | line terminator. Furthermore, because common code is used for receiving |
| 31950 | messages from all sources, a CR on its own is also interpreted as a line |
| 31951 | terminator. However, the sequence "CR, dot, CR" does not terminate incoming |
| 31952 | SMTP data. |
| 31953 | |
| 31954 | One area that sometimes gives rise to problems concerns the EHLO or HELO |
| 31955 | commands. Some clients send syntactically invalid versions of these commands, |
| 31956 | which Exim rejects by default. (This is nothing to do with verifying the data |
| 31957 | that is sent, so helo_verify_hosts is not relevant.) You can tell Exim not to |
| 31958 | apply a syntax check by setting helo_accept_junk_hosts to match the broken |
| 31959 | hosts that send invalid commands. |
| 31960 | |
| 31961 | The amount of disk space available is checked whenever SIZE is received on a |
| 31962 | MAIL command, independently of whether message_size_limit or check_spool_space |
| 31963 | is configured, unless smtp_check_spool_space is set false. A temporary error is |
| 31964 | given if there is not enough space. If check_spool_space is set, the check is |
| 31965 | for that amount of space plus the value given with SIZE, that is, it checks |
| 31966 | that the addition of the incoming message will not reduce the space below the |
| 31967 | threshold. |
| 31968 | |
| 31969 | When a message is successfully received, Exim includes the local message id in |
| 31970 | its response to the final "." that terminates the data. If the remote host logs |
| 31971 | this text it can help with tracing what has happened to a message. |
| 31972 | |
| 31973 | The Exim daemon can limit the number of simultaneous incoming connections it is |
| 31974 | prepared to handle (see the smtp_accept_max option). It can also limit the |
| 31975 | number of simultaneous incoming connections from a single remote host (see the |
| 31976 | smtp_accept_max_per_host option). Additional connection attempts are rejected |
| 31977 | using the SMTP temporary error code 421. |
| 31978 | |
| 31979 | The Exim daemon does not rely on the SIGCHLD signal to detect when a subprocess |
| 31980 | has finished, as this can get lost at busy times. Instead, it looks for |
| 31981 | completed subprocesses every time it wakes up. Provided there are other things |
| 31982 | happening (new incoming calls, starts of queue runs), completed processes will |
| 31983 | be noticed and tidied away. On very quiet systems you may sometimes see a |
| 31984 | "defunct" Exim process hanging about. This is not a problem; it will be noticed |
| 31985 | when the daemon next wakes up. |
| 31986 | |
| 31987 | When running as a daemon, Exim can reserve some SMTP slots for specific hosts, |
| 31988 | and can also be set up to reject SMTP calls from non-reserved hosts at times of |
| 31989 | high system load - for details see the smtp_accept_reserve, smtp_load_reserve, |
| 31990 | and smtp_reserve_hosts options. The load check applies in both the daemon and |
| 31991 | inetd cases. |
| 31992 | |
| 31993 | Exim normally starts a delivery process for each message received, though this |
| 31994 | can be varied by means of the -odq command line option and the queue_only, |
| 31995 | queue_only_file, and queue_only_load options. The number of simultaneously |
| 31996 | running delivery processes started in this way from SMTP input can be limited |
| 31997 | by the smtp_accept_queue and smtp_accept_queue_per_connection options. When |
| 31998 | either limit is reached, subsequently received messages are just put on the |
| 31999 | input queue without starting a delivery process. |
| 32000 | |
| 32001 | The controls that involve counts of incoming SMTP calls (smtp_accept_max, |
| 32002 | smtp_accept_queue, smtp_accept_reserve) are not available when Exim is started |
| 32003 | up from the inetd daemon, because in that case each connection is handled by an |
| 32004 | entirely independent Exim process. Control by load average is, however, |
| 32005 | available with inetd. |
| 32006 | |
| 32007 | Exim can be configured to verify addresses in incoming SMTP commands as they |
| 32008 | are received. See chapter 43 for details. It can also be configured to rewrite |
| 32009 | addresses at this time - before any syntax checking is done. See section 31.9. |
| 32010 | |
| 32011 | Exim can also be configured to limit the rate at which a client host submits |
| 32012 | MAIL and RCPT commands in a single SMTP session. See the smtp_ratelimit_hosts |
| 32013 | option. |
| 32014 | |
| 32015 | |
| 32016 | 48.4 Unrecognized SMTP commands |
| 32017 | ------------------------------- |
| 32018 | |
| 32019 | If Exim receives more than smtp_max_unknown_commands unrecognized SMTP commands |
| 32020 | during a single SMTP connection, it drops the connection after sending the |
| 32021 | error response to the last command. The default value for |
| 32022 | smtp_max_unknown_commands is 3. This is a defence against some kinds of abuse |
| 32023 | that subvert web servers into making connections to SMTP ports; in these |
| 32024 | circumstances, a number of non-SMTP lines are sent first. |
| 32025 | |
| 32026 | |
| 32027 | 48.5 Syntax and protocol errors in SMTP commands |
| 32028 | ------------------------------------------------ |
| 32029 | |
| 32030 | A syntax error is detected if an SMTP command is recognized, but there is |
| 32031 | something syntactically wrong with its data, for example, a malformed email |
| 32032 | address in a RCPT command. Protocol errors include invalid command sequencing |
| 32033 | such as RCPT before MAIL. If Exim receives more than smtp_max_synprot_errors |
| 32034 | such commands during a single SMTP connection, it drops the connection after |
| 32035 | sending the error response to the last command. The default value for |
| 32036 | smtp_max_synprot_errors is 3. This is a defence against broken clients that |
| 32037 | loop sending bad commands (yes, it has been seen). |
| 32038 | |
| 32039 | |
| 32040 | 48.6 Use of non-mail SMTP commands |
| 32041 | ---------------------------------- |
| 32042 | |
| 32043 | The "non-mail" SMTP commands are those other than MAIL, RCPT, and DATA. Exim |
| 32044 | counts such commands, and drops the connection if there are too many of them in |
| 32045 | a single SMTP session. This action catches some denial-of-service attempts and |
| 32046 | things like repeated failing AUTHs, or a mad client looping sending EHLO. The |
| 32047 | global option smtp_accept_max_nonmail defines what "too many" means. Its |
| 32048 | default value is 10. |
| 32049 | |
| 32050 | When a new message is expected, one occurrence of RSET is not counted. This |
| 32051 | allows a client to send one RSET between messages (this is not necessary, but |
| 32052 | some clients do it). Exim also allows one uncounted occurrence of HELO or EHLO, |
| 32053 | and one occurrence of STARTTLS between messages. After starting up a TLS |
| 32054 | session, another EHLO is expected, and so it too is not counted. |
| 32055 | |
| 32056 | The first occurrence of AUTH in a connection, or immediately following STARTTLS |
| 32057 | is also not counted. Otherwise, all commands other than MAIL, RCPT, DATA, and |
| 32058 | QUIT are counted. |
| 32059 | |
| 32060 | You can control which hosts are subject to the limit set by |
| 32061 | smtp_accept_max_nonmail by setting smtp_accept_max_nonmail_hosts. The default |
| 32062 | value is "*", which makes the limit apply to all hosts. This option means that |
| 32063 | you can exclude any specific badly-behaved hosts that you have to live with. |
| 32064 | |
| 32065 | |
| 32066 | 48.7 The VRFY and EXPN commands |
| 32067 | ------------------------------- |
| 32068 | |
| 32069 | When Exim receives a VRFY or EXPN command on a TCP/IP connection, it runs the |
| 32070 | ACL specified by acl_smtp_vrfy or acl_smtp_expn (as appropriate) in order to |
| 32071 | decide whether the command should be accepted or not. |
| 32072 | |
| 32073 | When no ACL is defined for VRFY, or if it rejects without setting an explicit |
| 32074 | response code, the command is accepted (with a 252 SMTP response code) in order |
| 32075 | to support awkward clients that do a VRFY before every RCPT. When VRFY is |
| 32076 | accepted, it runs exactly the same code as when Exim is called with the -bv |
| 32077 | option, and returns 250/451/550 SMTP response codes. |
| 32078 | |
| 32079 | If no ACL for EXPN is defined, the command is rejected. When EXPN is accepted, |
| 32080 | a single-level expansion of the address is done. EXPN is treated as an "address |
| 32081 | test" (similar to the -bt option) rather than a verification (the -bv option). |
| 32082 | If an unqualified local part is given as the argument to EXPN, it is qualified |
| 32083 | with qualify_domain. Rejections of VRFY and EXPN commands are logged on the |
| 32084 | main and reject logs, and VRFY verification failures are logged on the main log |
| 32085 | for consistency with RCPT failures. |
| 32086 | |
| 32087 | |
| 32088 | 48.8 The ETRN command |
| 32089 | --------------------- |
| 32090 | |
| 32091 | RFC 1985 describes an SMTP command called ETRN that is designed to overcome the |
| 32092 | security problems of the TURN command (which has fallen into disuse). When Exim |
| 32093 | receives an ETRN command on a TCP/IP connection, it runs the ACL specified by |
| 32094 | acl_smtp_etrn in order to decide whether the command should be accepted or not. |
| 32095 | If no ACL is defined, the command is rejected. |
| 32096 | |
| 32097 | The ETRN command is concerned with "releasing" messages that are awaiting |
| 32098 | delivery to certain hosts. As Exim does not organize its message queue by host, |
| 32099 | the only form of ETRN that is supported by default is the one where the text |
| 32100 | starts with the "#" prefix, in which case the remainder of the text is specific |
| 32101 | to the SMTP server. A valid ETRN command causes a run of Exim with the -R |
| 32102 | option to happen, with the remainder of the ETRN text as its argument. For |
| 32103 | example, |
| 32104 | |
| 32105 | ETRN #brigadoon |
| 32106 | |
| 32107 | runs the command |
| 32108 | |
| 32109 | exim -R brigadoon |
| 32110 | |
| 32111 | which causes a delivery attempt on all messages with undelivered addresses |
| 32112 | containing the text "brigadoon". When smtp_etrn_serialize is set (the default), |
| 32113 | Exim prevents the simultaneous execution of more than one queue run for the |
| 32114 | same argument string as a result of an ETRN command. This stops a misbehaving |
| 32115 | client from starting more than one queue runner at once. |
| 32116 | |
| 32117 | Exim implements the serialization by means of a hints database in which a |
| 32118 | record is written whenever a process is started by ETRN, and deleted when the |
| 32119 | process completes. However, Exim does not keep the SMTP session waiting for the |
| 32120 | ETRN process to complete. Once ETRN is accepted, the client is sent a "success" |
| 32121 | return code. Obviously there is scope for hints records to get left lying |
| 32122 | around if there is a system or program crash. To guard against this, Exim |
| 32123 | ignores any records that are more than six hours old. |
| 32124 | |
| 32125 | For more control over what ETRN does, the smtp_etrn_command option can used. |
| 32126 | This specifies a command that is run whenever ETRN is received, whatever the |
| 32127 | form of its argument. For example: |
| 32128 | |
| 32129 | smtp_etrn_command = /etc/etrn_command $domain \ |
| 32130 | $sender_host_address |
| 32131 | |
| 32132 | The string is split up into arguments which are independently expanded. The |
| 32133 | expansion variable $domain is set to the argument of the ETRN command, and no |
| 32134 | syntax checking is done on the contents of this argument. Exim does not wait |
| 32135 | for the command to complete, so its status code is not checked. Exim runs under |
| 32136 | its own uid and gid when receiving incoming SMTP, so it is not possible for it |
| 32137 | to change them before running the command. |
| 32138 | |
| 32139 | |
| 32140 | 48.9 Incoming local SMTP |
| 32141 | ------------------------ |
| 32142 | |
| 32143 | Some user agents use SMTP to pass messages to their local MTA using the |
| 32144 | standard input and output, as opposed to passing the envelope on the command |
| 32145 | line and writing the message to the standard input. This is supported by the |
| 32146 | -bs option. This form of SMTP is handled in the same way as incoming messages |
| 32147 | over TCP/IP (including the use of ACLs), except that the envelope sender given |
| 32148 | in a MAIL command is ignored unless the caller is trusted. In an ACL you can |
| 32149 | detect this form of SMTP input by testing for an empty host identification. It |
| 32150 | is common to have this as the first line in the ACL that runs for RCPT |
| 32151 | commands: |
| 32152 | |
| 32153 | accept hosts = : |
| 32154 | |
| 32155 | This accepts SMTP messages from local processes without doing any other tests. |
| 32156 | |
| 32157 | |
| 32158 | 48.10 Outgoing batched SMTP |
| 32159 | --------------------------- |
| 32160 | |
| 32161 | Both the appendfile and pipe transports can be used for handling batched SMTP. |
| 32162 | Each has an option called use_bsmtp which causes messages to be output in BSMTP |
| 32163 | format. No SMTP responses are possible for this form of delivery. All it is |
| 32164 | doing is using SMTP commands as a way of transmitting the envelope along with |
| 32165 | the message. |
| 32166 | |
| 32167 | The message is written to the file or pipe preceded by the SMTP commands MAIL |
| 32168 | and RCPT, and followed by a line containing a single dot. Lines in the message |
| 32169 | that start with a dot have an extra dot added. The SMTP command HELO is not |
| 32170 | normally used. If it is required, the message_prefix option can be used to |
| 32171 | specify it. |
| 32172 | |
| 32173 | Because appendfile and pipe are both local transports, they accept only one |
| 32174 | recipient address at a time by default. However, you can arrange for them to |
| 32175 | handle several addresses at once by setting the batch_max option. When this is |
| 32176 | done for BSMTP, messages may contain multiple RCPT commands. See chapter 25 for |
| 32177 | more details. |
| 32178 | |
| 32179 | When one or more addresses are routed to a BSMTP transport by a router that |
| 32180 | sets up a host list, the name of the first host on the list is available to the |
| 32181 | transport in the variable $host. Here is an example of such a transport and |
| 32182 | router: |
| 32183 | |
| 32184 | begin routers |
| 32185 | route_append: |
| 32186 | driver = manualroute |
| 32187 | transport = smtp_appendfile |
| 32188 | route_list = domain.example batch.host.example |
| 32189 | |
| 32190 | begin transports |
| 32191 | smtp_appendfile: |
| 32192 | driver = appendfile |
| 32193 | directory = /var/bsmtp/$host |
| 32194 | batch_max = 1000 |
| 32195 | use_bsmtp |
| 32196 | user = exim |
| 32197 | |
| 32198 | This causes messages addressed to domain.example to be written in BSMTP format |
| 32199 | to /var/bsmtp/batch.host.example, with only a single copy of each message |
| 32200 | (unless there are more than 1000 recipients). |
| 32201 | |
| 32202 | |
| 32203 | 48.11 Incoming batched SMTP |
| 32204 | --------------------------- |
| 32205 | |
| 32206 | The -bS command line option causes Exim to accept one or more messages by |
| 32207 | reading SMTP on the standard input, but to generate no responses. If the caller |
| 32208 | is trusted, the senders in the MAIL commands are believed; otherwise the sender |
| 32209 | is always the caller of Exim. Unqualified senders and receivers are not |
| 32210 | rejected (there seems little point) but instead just get qualified. HELO and |
| 32211 | EHLO act as RSET; VRFY, EXPN, ETRN and HELP, act as NOOP; QUIT quits. |
| 32212 | |
| 32213 | Minimal policy checking is done for BSMTP input. Only the non-SMTP ACL is run |
| 32214 | in the same way as for non-SMTP local input. |
| 32215 | |
| 32216 | If an error is detected while reading a message, including a missing "." at the |
| 32217 | end, Exim gives up immediately. It writes details of the error to the standard |
| 32218 | output in a stylized way that the calling program should be able to make some |
| 32219 | use of automatically, for example: |
| 32220 | |
| 32221 | 554 Unexpected end of file |
| 32222 | Transaction started in line 10 |
| 32223 | Error detected in line 14 |
| 32224 | |
| 32225 | It writes a more verbose version, for human consumption, to the standard error |
| 32226 | file, for example: |
| 32227 | |
| 32228 | An error was detected while processing a file of BSMTP input. |
| 32229 | The error message was: |
| 32230 | |
| 32231 | 501 '>' missing at end of address |
| 32232 | |
| 32233 | The SMTP transaction started in line 10. |
| 32234 | The error was detected in line 12. |
| 32235 | The SMTP command at fault was: |
| 32236 | |
| 32237 | rcpt to:<malformed@in.com.plete |
| 32238 | |
| 32239 | 1 previous message was successfully processed. |
| 32240 | The rest of the batch was abandoned. |
| 32241 | |
| 32242 | The return code from Exim is zero only if there were no errors. It is 1 if some |
| 32243 | messages were accepted before an error was detected, and 2 if no messages were |
| 32244 | accepted. |
| 32245 | |
| 32246 | |
| 32247 | |
| 32248 | =============================================================================== |
| 32249 | 49. CUSTOMIZING BOUNCE AND WARNING MESSAGES |
| 32250 | |
| 32251 | When a message fails to be delivered, or remains on the queue for more than a |
| 32252 | configured amount of time, Exim sends a message to the original sender, or to |
| 32253 | an alternative configured address. The text of these messages is built into the |
| 32254 | code of Exim, but it is possible to change it, either by adding a single |
| 32255 | string, or by replacing each of the paragraphs by text supplied in a file. |
| 32256 | |
| 32257 | The From: and To: header lines are automatically generated; you can cause a |
| 32258 | Reply-To: line to be added by setting the errors_reply_to option. Exim also |
| 32259 | adds the line |
| 32260 | |
| 32261 | Auto-Submitted: auto-generated |
| 32262 | |
| 32263 | to all warning and bounce messages, |
| 32264 | |
| 32265 | |
| 32266 | 49.1 Customizing bounce messages |
| 32267 | -------------------------------- |
| 32268 | |
| 32269 | If bounce_message_text is set, its contents are included in the default message |
| 32270 | immediately after "This message was created automatically by mail delivery |
| 32271 | software." The string is not expanded. It is not used if bounce_message_file is |
| 32272 | set. |
| 32273 | |
| 32274 | When bounce_message_file is set, it must point to a template file for |
| 32275 | constructing error messages. The file consists of a series of text items, |
| 32276 | separated by lines consisting of exactly four asterisks. If the file cannot be |
| 32277 | opened, default text is used and a message is written to the main and panic |
| 32278 | logs. If any text item in the file is empty, default text is used for that |
| 32279 | item. |
| 32280 | |
| 32281 | Each item of text that is read from the file is expanded, and there are two |
| 32282 | expansion variables which can be of use here: $bounce_recipient is set to the |
| 32283 | recipient of an error message while it is being created, and |
| 32284 | $bounce_return_size_limit contains the value of the return_size_limit option, |
| 32285 | rounded to a whole number. |
| 32286 | |
| 32287 | The items must appear in the file in the following order: |
| 32288 | |
| 32289 | * The first item is included in the headers, and should include at least a |
| 32290 | Subject: header. Exim does not check the syntax of these headers. |
| 32291 | |
| 32292 | * The second item forms the start of the error message. After it, Exim lists |
| 32293 | the failing addresses with their error messages. |
| 32294 | |
| 32295 | * The third item is used to introduce any text from pipe transports that is |
| 32296 | to be returned to the sender. It is omitted if there is no such text. |
| 32297 | |
| 32298 | * The fourth, fifth and sixth items will be ignored and may be empty. The |
| 32299 | fields exist for back-compatibility |
| 32300 | |
| 32301 | The default state (bounce_message_file unset) is equivalent to the following |
| 32302 | file, in which the sixth item is empty. The Subject: and some other lines have |
| 32303 | been split in order to fit them on the page: |
| 32304 | |
| 32305 | Subject: Mail delivery failed |
| 32306 | ${if eq{$sender_address}{$bounce_recipient} |
| 32307 | {: returning message to sender}} |
| 32308 | **** |
| 32309 | This message was created automatically by mail delivery software. |
| 32310 | |
| 32311 | A message ${if eq{$sender_address}{$bounce_recipient} |
| 32312 | {that you sent }{sent by |
| 32313 | |
| 32314 | <$sender_address> |
| 32315 | |
| 32316 | }}could not be delivered to all of its recipients. |
| 32317 | This is a permanent error. The following address(es) failed: |
| 32318 | **** |
| 32319 | The following text was generated during the delivery attempt(s): |
| 32320 | **** |
| 32321 | ------ This is a copy of the message, including all the headers. |
| 32322 | ------ |
| 32323 | **** |
| 32324 | ------ The body of the message is $message_size characters long; |
| 32325 | only the first |
| 32326 | ------ $bounce_return_size_limit or so are included here. |
| 32327 | **** |
| 32328 | |
| 32329 | |
| 32330 | 49.2 Customizing warning messages |
| 32331 | --------------------------------- |
| 32332 | |
| 32333 | The option warn_message_file can be pointed at a template file for use when |
| 32334 | warnings about message delays are created. In this case there are only three |
| 32335 | text sections: |
| 32336 | |
| 32337 | * The first item is included in the headers, and should include at least a |
| 32338 | Subject: header. Exim does not check the syntax of these headers. |
| 32339 | |
| 32340 | * The second item forms the start of the warning message. After it, Exim |
| 32341 | lists the delayed addresses. |
| 32342 | |
| 32343 | * The third item then ends the message. |
| 32344 | |
| 32345 | The default state is equivalent to the following file, except that some lines |
| 32346 | have been split here, in order to fit them on the page: |
| 32347 | |
| 32348 | Subject: Warning: message $message_exim_id delayed |
| 32349 | $warn_message_delay |
| 32350 | **** |
| 32351 | This message was created automatically by mail delivery software. |
| 32352 | |
| 32353 | A message ${if eq{$sender_address}{$warn_message_recipients} |
| 32354 | {that you sent }{sent by |
| 32355 | |
| 32356 | <$sender_address> |
| 32357 | |
| 32358 | }}has not been delivered to all of its recipients after |
| 32359 | more than $warn_message_delay on the queue on $primary_hostname. |
| 32360 | |
| 32361 | The message identifier is: $message_exim_id |
| 32362 | The subject of the message is: $h_subject |
| 32363 | The date of the message is: $h_date |
| 32364 | |
| 32365 | The following address(es) have not yet been delivered: |
| 32366 | **** |
| 32367 | No action is required on your part. Delivery attempts will |
| 32368 | continue for some time, and this warning may be repeated at |
| 32369 | intervals if the message remains undelivered. Eventually the |
| 32370 | mail delivery software will give up, and when that happens, |
| 32371 | the message will be returned to you. |
| 32372 | |
| 32373 | However, in the default state the subject and date lines are omitted if no |
| 32374 | appropriate headers exist. During the expansion of this file, |
| 32375 | $warn_message_delay is set to the delay time in one of the forms "<n> minutes" |
| 32376 | or "<n> hours", and $warn_message_recipients contains a list of recipients for |
| 32377 | the warning message. There may be more than one if there are multiple addresses |
| 32378 | with different errors_to settings on the routers that handled them. |
| 32379 | |
| 32380 | |
| 32381 | |
| 32382 | =============================================================================== |
| 32383 | 50. SOME COMMON CONFIGURATION SETTINGS |
| 32384 | |
| 32385 | This chapter discusses some configuration settings that seem to be fairly |
| 32386 | common. More examples and discussion can be found in the Exim book. |
| 32387 | |
| 32388 | |
| 32389 | 50.1 Sending mail to a smart host |
| 32390 | --------------------------------- |
| 32391 | |
| 32392 | If you want to send all mail for non-local domains to a "smart host", you |
| 32393 | should replace the default dnslookup router with a router which does the |
| 32394 | routing explicitly: |
| 32395 | |
| 32396 | send_to_smart_host: |
| 32397 | driver = manualroute |
| 32398 | route_list = !+local_domains smart.host.name |
| 32399 | transport = remote_smtp |
| 32400 | |
| 32401 | You can use the smart host's IP address instead of the name if you wish. If you |
| 32402 | are using Exim only to submit messages to a smart host, and not for receiving |
| 32403 | incoming messages, you can arrange for it to do the submission synchronously by |
| 32404 | setting the mua_wrapper option (see chapter 51). |
| 32405 | |
| 32406 | |
| 32407 | 50.2 Using Exim to handle mailing lists |
| 32408 | --------------------------------------- |
| 32409 | |
| 32410 | Exim can be used to run simple mailing lists, but for large and/or complicated |
| 32411 | requirements, the use of additional specialized mailing list software such as |
| 32412 | Majordomo or Mailman is recommended. |
| 32413 | |
| 32414 | The redirect router can be used to handle mailing lists where each list is |
| 32415 | maintained in a separate file, which can therefore be managed by an independent |
| 32416 | manager. The domains router option can be used to run these lists in a separate |
| 32417 | domain from normal mail. For example: |
| 32418 | |
| 32419 | lists: |
| 32420 | driver = redirect |
| 32421 | domains = lists.example |
| 32422 | file = /usr/lists/$local_part |
| 32423 | forbid_pipe |
| 32424 | forbid_file |
| 32425 | errors_to = $local_part-request@lists.example |
| 32426 | no_more |
| 32427 | |
| 32428 | This router is skipped for domains other than lists.example. For addresses in |
| 32429 | that domain, it looks for a file that matches the local part. If there is no |
| 32430 | such file, the router declines, but because no_more is set, no subsequent |
| 32431 | routers are tried, and so the whole delivery fails. |
| 32432 | |
| 32433 | The forbid_pipe and forbid_file options prevent a local part from being |
| 32434 | expanded into a file name or a pipe delivery, which is usually inappropriate in |
| 32435 | a mailing list. |
| 32436 | |
| 32437 | The errors_to option specifies that any delivery errors caused by addresses |
| 32438 | taken from a mailing list are to be sent to the given address rather than the |
| 32439 | original sender of the message. However, before acting on this, Exim verifies |
| 32440 | the error address, and ignores it if verification fails. |
| 32441 | |
| 32442 | For example, using the configuration above, mail sent to dicts@lists.example is |
| 32443 | passed on to those addresses contained in /usr/lists/dicts, with error reports |
| 32444 | directed to dicts-request@lists.example, provided that this address can be |
| 32445 | verified. There could be a file called /usr/lists/dicts-request containing the |
| 32446 | address(es) of this particular list's manager(s), but other approaches, such as |
| 32447 | setting up an earlier router (possibly using the local_part_prefix or |
| 32448 | local_part_suffix options) to handle addresses of the form owner-xxx or xxx- |
| 32449 | request, are also possible. |
| 32450 | |
| 32451 | |
| 32452 | 50.3 Syntax errors in mailing lists |
| 32453 | ----------------------------------- |
| 32454 | |
| 32455 | If an entry in redirection data contains a syntax error, Exim normally defers |
| 32456 | delivery of the original address. That means that a syntax error in a mailing |
| 32457 | list holds up all deliveries to the list. This may not be appropriate when a |
| 32458 | list is being maintained automatically from data supplied by users, and the |
| 32459 | addresses are not rigorously checked. |
| 32460 | |
| 32461 | If the skip_syntax_errors option is set, the redirect router just skips entries |
| 32462 | that fail to parse, noting the incident in the log. If in addition |
| 32463 | syntax_errors_to is set to a verifiable address, a message is sent to it |
| 32464 | whenever a broken address is skipped. It is usually appropriate to set |
| 32465 | syntax_errors_to to the same address as errors_to. |
| 32466 | |
| 32467 | |
| 32468 | 50.4 Re-expansion of mailing lists |
| 32469 | ---------------------------------- |
| 32470 | |
| 32471 | Exim remembers every individual address to which a message has been delivered, |
| 32472 | in order to avoid duplication, but it normally stores only the original |
| 32473 | recipient addresses with a message. If all the deliveries to a mailing list |
| 32474 | cannot be done at the first attempt, the mailing list is re-expanded when the |
| 32475 | delivery is next tried. This means that alterations to the list are taken into |
| 32476 | account at each delivery attempt, so addresses that have been added to the list |
| 32477 | since the message arrived will therefore receive a copy of the message, even |
| 32478 | though it pre-dates their subscription. |
| 32479 | |
| 32480 | If this behaviour is felt to be undesirable, the one_time option can be set on |
| 32481 | the redirect router. If this is done, any addresses generated by the router |
| 32482 | that fail to deliver at the first attempt are added to the message as "top |
| 32483 | level" addresses, and the parent address that generated them is marked |
| 32484 | "delivered". Thus, expansion of the mailing list does not happen again at the |
| 32485 | subsequent delivery attempts. The disadvantage of this is that if any of the |
| 32486 | failing addresses are incorrect, correcting them in the file has no effect on |
| 32487 | pre-existing messages. |
| 32488 | |
| 32489 | The original top-level address is remembered with each of the generated |
| 32490 | addresses, and is output in any log messages. However, any intermediate parent |
| 32491 | addresses are not recorded. This makes a difference to the log only if the |
| 32492 | all_parents selector is set, but for mailing lists there is normally only one |
| 32493 | level of expansion anyway. |
| 32494 | |
| 32495 | |
| 32496 | 50.5 Closed mailing lists |
| 32497 | ------------------------- |
| 32498 | |
| 32499 | The examples so far have assumed open mailing lists, to which anybody may send |
| 32500 | mail. It is also possible to set up closed lists, where mail is accepted from |
| 32501 | specified senders only. This is done by making use of the generic senders |
| 32502 | option to restrict the router that handles the list. |
| 32503 | |
| 32504 | The following example uses the same file as a list of recipients and as a list |
| 32505 | of permitted senders. It requires three routers: |
| 32506 | |
| 32507 | lists_request: |
| 32508 | driver = redirect |
| 32509 | domains = lists.example |
| 32510 | local_part_suffix = -request |
| 32511 | file = /usr/lists/$local_part$local_part_suffix |
| 32512 | no_more |
| 32513 | |
| 32514 | lists_post: |
| 32515 | driver = redirect |
| 32516 | domains = lists.example |
| 32517 | senders = ${if exists {/usr/lists/$local_part}\ |
| 32518 | {lsearch;/usr/lists/$local_part}{*}} |
| 32519 | file = /usr/lists/$local_part |
| 32520 | forbid_pipe |
| 32521 | forbid_file |
| 32522 | errors_to = $local_part-request@lists.example |
| 32523 | no_more |
| 32524 | |
| 32525 | lists_closed: |
| 32526 | driver = redirect |
| 32527 | domains = lists.example |
| 32528 | allow_fail |
| 32529 | data = :fail: $local_part@lists.example is a closed mailing list |
| 32530 | |
| 32531 | All three routers have the same domains setting, so for any other domains, they |
| 32532 | are all skipped. The first router runs only if the local part ends in -request. |
| 32533 | It handles messages to the list manager(s) by means of an open mailing list. |
| 32534 | |
| 32535 | The second router runs only if the senders precondition is satisfied. It checks |
| 32536 | for the existence of a list that corresponds to the local part, and then checks |
| 32537 | that the sender is on the list by means of a linear search. It is necessary to |
| 32538 | check for the existence of the file before trying to search it, because |
| 32539 | otherwise Exim thinks there is a configuration error. If the file does not |
| 32540 | exist, the expansion of senders is *, which matches all senders. This means |
| 32541 | that the router runs, but because there is no list, declines, and no_more |
| 32542 | ensures that no further routers are run. The address fails with an "unrouteable |
| 32543 | address" error. |
| 32544 | |
| 32545 | The third router runs only if the second router is skipped, which happens when |
| 32546 | a mailing list exists, but the sender is not on it. This router forcibly fails |
| 32547 | the address, giving a suitable error message. |
| 32548 | |
| 32549 | |
| 32550 | 50.6 Variable Envelope Return Paths (VERP) |
| 32551 | ------------------------------------------ |
| 32552 | |
| 32553 | Variable Envelope Return Paths - see http://cr.yp.to/proto/verp.txt - are a way |
| 32554 | of helping mailing list administrators discover which subscription address is |
| 32555 | the cause of a particular delivery failure. The idea is to encode the original |
| 32556 | recipient address in the outgoing envelope sender address, so that if the |
| 32557 | message is forwarded by another host and then subsequently bounces, the |
| 32558 | original recipient can be extracted from the recipient address of the bounce. |
| 32559 | |
| 32560 | Envelope sender addresses can be modified by Exim using two different |
| 32561 | facilities: the errors_to option on a router (as shown in previous mailing list |
| 32562 | examples), or the return_path option on a transport. The second of these is |
| 32563 | effective only if the message is successfully delivered to another host; it is |
| 32564 | not used for errors detected on the local host (see the description of |
| 32565 | return_path in chapter 24). Here is an example of the use of return_path to |
| 32566 | implement VERP on an smtp transport: |
| 32567 | |
| 32568 | verp_smtp: |
| 32569 | driver = smtp |
| 32570 | max_rcpt = 1 |
| 32571 | return_path = \ |
| 32572 | ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\ |
| 32573 | {$1-request+$local_part=$domain@your.dom.example}fail} |
| 32574 | |
| 32575 | This has the effect of rewriting the return path (envelope sender) on outgoing |
| 32576 | SMTP messages, if the local part of the original return path ends in |
| 32577 | "-request", and the domain is your.dom.example. The rewriting inserts the local |
| 32578 | part and domain of the recipient into the return path. Suppose, for example, |
| 32579 | that a message whose return path has been set to |
| 32580 | somelist-request@your.dom.example is sent to subscriber@other.dom.example. In |
| 32581 | the transport, the return path is rewritten as |
| 32582 | |
| 32583 | somelist-request+subscriber=other.dom.example@your.dom.example |
| 32584 | |
| 32585 | For this to work, you must tell Exim to send multiple copies of messages that |
| 32586 | have more than one recipient, so that each copy has just one recipient. This is |
| 32587 | achieved by setting max_rcpt to 1. Without this, a single copy of a message |
| 32588 | might be sent to several different recipients in the same domain, in which case |
| 32589 | $local_part is not available in the transport, because it is not unique. |
| 32590 | |
| 32591 | Unless your host is doing nothing but mailing list deliveries, you should |
| 32592 | probably use a separate transport for the VERP deliveries, so as not to use |
| 32593 | extra resources in making one-per-recipient copies for other deliveries. This |
| 32594 | can easily be done by expanding the transport option in the router: |
| 32595 | |
| 32596 | dnslookup: |
| 32597 | driver = dnslookup |
| 32598 | domains = ! +local_domains |
| 32599 | transport = \ |
| 32600 | ${if match {$return_path}{^(.+?)-request@your.dom.example\$}\ |
| 32601 | {verp_smtp}{remote_smtp}} |
| 32602 | no_more |
| 32603 | |
| 32604 | If you want to change the return path using errors_to in a router instead of |
| 32605 | using return_path in the transport, you need to set errors_to on all routers |
| 32606 | that handle mailing list addresses. This will ensure that all delivery errors, |
| 32607 | including those detected on the local host, are sent to the VERP address. |
| 32608 | |
| 32609 | On a host that does no local deliveries and has no manual routing, only the |
| 32610 | dnslookup router needs to be changed. A special transport is not needed for |
| 32611 | SMTP deliveries. Every mailing list recipient has its own return path value, |
| 32612 | and so Exim must hand them to the transport one at a time. Here is an example |
| 32613 | of a dnslookup router that implements VERP: |
| 32614 | |
| 32615 | verp_dnslookup: |
| 32616 | driver = dnslookup |
| 32617 | domains = ! +local_domains |
| 32618 | transport = remote_smtp |
| 32619 | errors_to = \ |
| 32620 | ${if match {$return_path}{^(.+?)-request@your.dom.example\$}} |
| 32621 | {$1-request+$local_part=$domain@your.dom.example}fail} |
| 32622 | no_more |
| 32623 | |
| 32624 | Before you start sending out messages with VERPed return paths, you must also |
| 32625 | configure Exim to accept the bounce messages that come back to those paths. |
| 32626 | Typically this is done by setting a local_part_suffix option for a router, and |
| 32627 | using this to route the messages to wherever you want to handle them. |
| 32628 | |
| 32629 | The overhead incurred in using VERP depends very much on the size of the |
| 32630 | message, the number of recipient addresses that resolve to the same remote |
| 32631 | host, and the speed of the connection over which the message is being sent. If |
| 32632 | a lot of addresses resolve to the same host and the connection is slow, sending |
| 32633 | a separate copy of the message for each address may take substantially longer |
| 32634 | than sending a single copy with many recipients (for which VERP cannot be |
| 32635 | used). |
| 32636 | |
| 32637 | |
| 32638 | 50.7 Virtual domains |
| 32639 | -------------------- |
| 32640 | |
| 32641 | The phrase virtual domain is unfortunately used with two rather different |
| 32642 | meanings: |
| 32643 | |
| 32644 | * A domain for which there are no real mailboxes; all valid local parts are |
| 32645 | aliases for other email addresses. Common examples are organizational |
| 32646 | top-level domains and "vanity" domains. |
| 32647 | |
| 32648 | * One of a number of independent domains that are all handled by the same |
| 32649 | host, with mailboxes on that host, but where the mailbox owners do not |
| 32650 | necessarily have login accounts on that host. |
| 32651 | |
| 32652 | The first usage is probably more common, and does seem more "virtual" than the |
| 32653 | second. This kind of domain can be handled in Exim with a straightforward |
| 32654 | aliasing router. One approach is to create a separate alias file for each |
| 32655 | virtual domain. Exim can test for the existence of the alias file to determine |
| 32656 | whether the domain exists. The dsearch lookup type is useful here, leading to a |
| 32657 | router of this form: |
| 32658 | |
| 32659 | virtual: |
| 32660 | driver = redirect |
| 32661 | domains = dsearch;/etc/mail/virtual |
| 32662 | data = ${lookup{$local_part}lsearch{/etc/mail/virtual/$domain}} |
| 32663 | no_more |
| 32664 | |
| 32665 | The domains option specifies that the router is to be skipped, unless there is |
| 32666 | a file in the /etc/mail/virtual directory whose name is the same as the domain |
| 32667 | that is being processed. When the router runs, it looks up the local part in |
| 32668 | the file to find a new address (or list of addresses). The no_more setting |
| 32669 | ensures that if the lookup fails (leading to data being an empty string), Exim |
| 32670 | gives up on the address without trying any subsequent routers. |
| 32671 | |
| 32672 | This one router can handle all the virtual domains because the alias file names |
| 32673 | follow a fixed pattern. Permissions can be arranged so that appropriate people |
| 32674 | can edit the different alias files. A successful aliasing operation results in |
| 32675 | a new envelope recipient address, which is then routed from scratch. |
| 32676 | |
| 32677 | The other kind of "virtual" domain can also be handled in a straightforward |
| 32678 | way. One approach is to create a file for each domain containing a list of |
| 32679 | valid local parts, and use it in a router like this: |
| 32680 | |
| 32681 | my_domains: |
| 32682 | driver = accept |
| 32683 | domains = dsearch;/etc/mail/domains |
| 32684 | local_parts = lsearch;/etc/mail/domains/$domain |
| 32685 | transport = my_mailboxes |
| 32686 | |
| 32687 | The address is accepted if there is a file for the domain, and the local part |
| 32688 | can be found in the file. The domains option is used to check for the file's |
| 32689 | existence because domains is tested before the local_parts option (see section |
| 32690 | 3.12). You cannot use require_files, because that option is tested after |
| 32691 | local_parts. The transport is as follows: |
| 32692 | |
| 32693 | my_mailboxes: |
| 32694 | driver = appendfile |
| 32695 | file = /var/mail/$domain/$local_part |
| 32696 | user = mail |
| 32697 | |
| 32698 | This uses a directory of mailboxes for each domain. The user setting is |
| 32699 | required, to specify which uid is to be used for writing to the mailboxes. |
| 32700 | |
| 32701 | The configuration shown here is just one example of how you might support this |
| 32702 | requirement. There are many other ways this kind of configuration can be set |
| 32703 | up, for example, by using a database instead of separate files to hold all the |
| 32704 | information about the domains. |
| 32705 | |
| 32706 | |
| 32707 | 50.8 Multiple user mailboxes |
| 32708 | ---------------------------- |
| 32709 | |
| 32710 | Heavy email users often want to operate with multiple mailboxes, into which |
| 32711 | incoming mail is automatically sorted. A popular way of handling this is to |
| 32712 | allow users to use multiple sender addresses, so that replies can easily be |
| 32713 | identified. Users are permitted to add prefixes or suffixes to their local |
| 32714 | parts for this purpose. The wildcard facility of the generic router options |
| 32715 | local_part_prefix and local_part_suffix can be used for this. For example, |
| 32716 | consider this router: |
| 32717 | |
| 32718 | userforward: |
| 32719 | driver = redirect |
| 32720 | check_local_user |
| 32721 | file = $home/.forward |
| 32722 | local_part_suffix = -* |
| 32723 | local_part_suffix_optional |
| 32724 | allow_filter |
| 32725 | |
| 32726 | It runs a user's .forward file for all local parts of the form username-*. |
| 32727 | Within the filter file the user can distinguish different cases by testing the |
| 32728 | variable $local_part_suffix. For example: |
| 32729 | |
| 32730 | if $local_part_suffix contains -special then |
| 32731 | save /home/$local_part/Mail/special |
| 32732 | endif |
| 32733 | |
| 32734 | If the filter file does not exist, or does not deal with such addresses, they |
| 32735 | fall through to subsequent routers, and, assuming no subsequent use of the |
| 32736 | local_part_suffix option is made, they presumably fail. Thus, users have |
| 32737 | control over which suffixes are valid. |
| 32738 | |
| 32739 | Alternatively, a suffix can be used to trigger the use of a different .forward |
| 32740 | file - which is the way a similar facility is implemented in another MTA: |
| 32741 | |
| 32742 | userforward: |
| 32743 | driver = redirect |
| 32744 | check_local_user |
| 32745 | file = $home/.forward$local_part_suffix |
| 32746 | local_part_suffix = -* |
| 32747 | local_part_suffix_optional |
| 32748 | allow_filter |
| 32749 | |
| 32750 | If there is no suffix, .forward is used; if the suffix is -special, for |
| 32751 | example, .forward-special is used. Once again, if the appropriate file does not |
| 32752 | exist, or does not deal with the address, it is passed on to subsequent |
| 32753 | routers, which could, if required, look for an unqualified .forward file to use |
| 32754 | as a default. |
| 32755 | |
| 32756 | |
| 32757 | 50.9 Simplified vacation processing |
| 32758 | ----------------------------------- |
| 32759 | |
| 32760 | The traditional way of running the vacation program is for a user to set up a |
| 32761 | pipe command in a .forward file (see section 22.6 for syntax details). This is |
| 32762 | prone to error by inexperienced users. There are two features of Exim that can |
| 32763 | be used to make this process simpler for users: |
| 32764 | |
| 32765 | * A local part prefix such as "vacation-" can be specified on a router which |
| 32766 | can cause the message to be delivered directly to the vacation program, or |
| 32767 | alternatively can use Exim's autoreply transport. The contents of a user's |
| 32768 | .forward file are then much simpler. For example: |
| 32769 | |
| 32770 | spqr, vacation-spqr |
| 32771 | |
| 32772 | * The require_files generic router option can be used to trigger a vacation |
| 32773 | delivery by checking for the existence of a certain file in the user's home |
| 32774 | directory. The unseen generic option should also be used, to ensure that |
| 32775 | the original delivery also proceeds. In this case, all the user has to do |
| 32776 | is to create a file called, say, .vacation, containing a vacation message. |
| 32777 | |
| 32778 | Another advantage of both these methods is that they both work even when the |
| 32779 | use of arbitrary pipes by users is locked out. |
| 32780 | |
| 32781 | |
| 32782 | 50.10 Taking copies of mail |
| 32783 | --------------------------- |
| 32784 | |
| 32785 | Some installations have policies that require archive copies of all messages to |
| 32786 | be made. A single copy of each message can easily be taken by an appropriate |
| 32787 | command in a system filter, which could, for example, use a different file for |
| 32788 | each day's messages. |
| 32789 | |
| 32790 | There is also a shadow transport mechanism that can be used to take copies of |
| 32791 | messages that are successfully delivered by local transports, one copy per |
| 32792 | delivery. This could be used, inter alia, to implement automatic notification |
| 32793 | of delivery by sites that insist on doing such things. |
| 32794 | |
| 32795 | |
| 32796 | 50.11 Intermittently connected hosts |
| 32797 | ------------------------------------ |
| 32798 | |
| 32799 | It has become quite common (because it is cheaper) for hosts to connect to the |
| 32800 | Internet periodically rather than remain connected all the time. The normal |
| 32801 | arrangement is that mail for such hosts accumulates on a system that is |
| 32802 | permanently connected. |
| 32803 | |
| 32804 | Exim was designed for use on permanently connected hosts, and so it is not |
| 32805 | particularly well-suited to use in an intermittently connected environment. |
| 32806 | Nevertheless there are some features that can be used. |
| 32807 | |
| 32808 | |
| 32809 | 50.12 Exim on the upstream server host |
| 32810 | -------------------------------------- |
| 32811 | |
| 32812 | It is tempting to arrange for incoming mail for the intermittently connected |
| 32813 | host to remain on Exim's queue until the client connects. However, this |
| 32814 | approach does not scale very well. Two different kinds of waiting message are |
| 32815 | being mixed up in the same queue - those that cannot be delivered because of |
| 32816 | some temporary problem, and those that are waiting for their destination host |
| 32817 | to connect. This makes it hard to manage the queue, as well as wasting |
| 32818 | resources, because each queue runner scans the entire queue. |
| 32819 | |
| 32820 | A better approach is to separate off those messages that are waiting for an |
| 32821 | intermittently connected host. This can be done by delivering these messages |
| 32822 | into local files in batch SMTP, "mailstore", or other envelope-preserving |
| 32823 | format, from where they are transmitted by other software when their |
| 32824 | destination connects. This makes it easy to collect all the mail for one host |
| 32825 | in a single directory, and to apply local timeout rules on a per-message basis |
| 32826 | if required. |
| 32827 | |
| 32828 | On a very small scale, leaving the mail on Exim's queue can be made to work. If |
| 32829 | you are doing this, you should configure Exim with a long retry period for the |
| 32830 | intermittent host. For example: |
| 32831 | |
| 32832 | cheshire.wonderland.fict.example * F,5d,24h |
| 32833 | |
| 32834 | This stops a lot of failed delivery attempts from occurring, but Exim remembers |
| 32835 | which messages it has queued up for that host. Once the intermittent host comes |
| 32836 | online, forcing delivery of one message (either by using the -M or -R options, |
| 32837 | or by using the ETRN SMTP command (see section 48.8) causes all the queued up |
| 32838 | messages to be delivered, often down a single SMTP connection. While the host |
| 32839 | remains connected, any new messages get delivered immediately. |
| 32840 | |
| 32841 | If the connecting hosts do not have fixed IP addresses, that is, if a host is |
| 32842 | issued with a different IP address each time it connects, Exim's retry |
| 32843 | mechanisms on the holding host get confused, because the IP address is normally |
| 32844 | used as part of the key string for holding retry information. This can be |
| 32845 | avoided by unsetting retry_include_ip_address on the smtp transport. Since this |
| 32846 | has disadvantages for permanently connected hosts, it is best to arrange a |
| 32847 | separate transport for the intermittently connected ones. |
| 32848 | |
| 32849 | |
| 32850 | 50.13 Exim on the intermittently connected client host |
| 32851 | ------------------------------------------------------ |
| 32852 | |
| 32853 | The value of smtp_accept_queue_per_connection should probably be increased, or |
| 32854 | even set to zero (that is, disabled) on the intermittently connected host, so |
| 32855 | that all incoming messages down a single connection get delivered immediately. |
| 32856 | |
| 32857 | Mail waiting to be sent from an intermittently connected host will probably not |
| 32858 | have been routed, because without a connection DNS lookups are not possible. |
| 32859 | This means that if a normal queue run is done at connection time, each message |
| 32860 | is likely to be sent in a separate SMTP session. This can be avoided by |
| 32861 | starting the queue run with a command line option beginning with -qq instead of |
| 32862 | -q. In this case, the queue is scanned twice. In the first pass, routing is |
| 32863 | done but no deliveries take place. The second pass is a normal queue run; since |
| 32864 | all the messages have been previously routed, those destined for the same host |
| 32865 | are likely to get sent as multiple deliveries in a single SMTP connection. |
| 32866 | |
| 32867 | |
| 32868 | |
| 32869 | =============================================================================== |
| 32870 | 51. USING EXIM AS A NON-QUEUEING CLIENT |
| 32871 | |
| 32872 | On a personal computer, it is a common requirement for all email to be sent to |
| 32873 | a "smart host". There are plenty of MUAs that can be configured to operate that |
| 32874 | way, for all the popular operating systems. However, there are some MUAs for |
| 32875 | Unix-like systems that cannot be so configured: they submit messages using the |
| 32876 | command line interface of /usr/sbin/sendmail. Furthermore, utility programs |
| 32877 | such as cron submit messages this way. |
| 32878 | |
| 32879 | If the personal computer runs continuously, there is no problem, because it can |
| 32880 | run a conventional MTA that handles delivery to the smart host, and deal with |
| 32881 | any delays via its queueing mechanism. However, if the computer does not run |
| 32882 | continuously or runs different operating systems at different times, queueing |
| 32883 | email is not desirable. |
| 32884 | |
| 32885 | There is therefore a requirement for something that can provide the /usr/sbin/ |
| 32886 | sendmail interface but deliver messages to a smart host without any queueing or |
| 32887 | retrying facilities. Furthermore, the delivery to the smart host should be |
| 32888 | synchronous, so that if it fails, the sending MUA is immediately informed. In |
| 32889 | other words, we want something that extends an MUA that submits to a local MTA |
| 32890 | via the command line so that it behaves like one that submits to a remote smart |
| 32891 | host using TCP/SMTP. |
| 32892 | |
| 32893 | There are a number of applications (for example, there is one called ssmtp) |
| 32894 | that do this job. However, people have found them to be lacking in various |
| 32895 | ways. For instance, you might want to allow aliasing and forwarding to be done |
| 32896 | before sending a message to the smart host. |
| 32897 | |
| 32898 | Exim already had the necessary infrastructure for doing this job. Just a few |
| 32899 | tweaks were needed to make it behave as required, though it is somewhat of an |
| 32900 | overkill to use a fully-featured MTA for this purpose. |
| 32901 | |
| 32902 | There is a Boolean global option called mua_wrapper, defaulting false. Setting |
| 32903 | mua_wrapper true causes Exim to run in a special mode where it assumes that it |
| 32904 | is being used to "wrap" a command-line MUA in the manner just described. As |
| 32905 | well as setting mua_wrapper, you also need to provide a compatible router and |
| 32906 | transport configuration. Typically there will be just one router and one |
| 32907 | transport, sending everything to a smart host. |
| 32908 | |
| 32909 | When run in MUA wrapping mode, the behaviour of Exim changes in the following |
| 32910 | ways: |
| 32911 | |
| 32912 | * A daemon cannot be run, nor will Exim accept incoming messages from inetd. |
| 32913 | In other words, the only way to submit messages is via the command line. |
| 32914 | |
| 32915 | * Each message is synchronously delivered as soon as it is received (-odi is |
| 32916 | assumed). All queueing options (queue_only, queue_smtp_domains, control in |
| 32917 | an ACL, etc.) are quietly ignored. The Exim reception process does not |
| 32918 | finish until the delivery attempt is complete. If the delivery is |
| 32919 | successful, a zero return code is given. |
| 32920 | |
| 32921 | * Address redirection is permitted, but the final routing for all addresses |
| 32922 | must be to the same remote transport, and to the same list of hosts. |
| 32923 | Furthermore, the return address (envelope sender) must be the same for all |
| 32924 | recipients, as must any added or deleted header lines. In other words, it |
| 32925 | must be possible to deliver the message in a single SMTP transaction, |
| 32926 | however many recipients there are. |
| 32927 | |
| 32928 | * If these conditions are not met, or if routing any address results in a |
| 32929 | failure or defer status, or if Exim is unable to deliver all the recipients |
| 32930 | successfully to one of the smart hosts, delivery of the entire message |
| 32931 | fails. |
| 32932 | |
| 32933 | * Because no queueing is allowed, all failures are treated as permanent; |
| 32934 | there is no distinction between 4xx and 5xx SMTP response codes from the |
| 32935 | smart host. Furthermore, because only a single yes/no response can be given |
| 32936 | to the caller, it is not possible to deliver to some recipients and not |
| 32937 | others. If there is an error (temporary or permanent) for any recipient, |
| 32938 | all are failed. |
| 32939 | |
| 32940 | * If more than one smart host is listed, Exim will try another host after a |
| 32941 | connection failure or a timeout, in the normal way. However, if this kind |
| 32942 | of failure happens for all the hosts, the delivery fails. |
| 32943 | |
| 32944 | * When delivery fails, an error message is written to the standard error |
| 32945 | stream (as well as to Exim's log), and Exim exits to the caller with a |
| 32946 | return code value 1. The message is expunged from Exim's spool files. No |
| 32947 | bounce messages are ever generated. |
| 32948 | |
| 32949 | * No retry data is maintained, and any retry rules are ignored. |
| 32950 | |
| 32951 | * A number of Exim options are overridden: deliver_drop_privilege is forced |
| 32952 | true, max_rcpt in the smtp transport is forced to "unlimited", |
| 32953 | remote_max_parallel is forced to one, and fallback hosts are ignored. |
| 32954 | |
| 32955 | The overall effect is that Exim makes a single synchronous attempt to deliver |
| 32956 | the message, failing if there is any kind of problem. Because no local |
| 32957 | deliveries are done and no daemon can be run, Exim does not need root |
| 32958 | privilege. It should be possible to run it setuid to exim instead of setuid to |
| 32959 | root. See section 55.3 for a general discussion about the advantages and |
| 32960 | disadvantages of running without root privilege. |
| 32961 | |
| 32962 | |
| 32963 | |
| 32964 | =============================================================================== |
| 32965 | 52. LOG FILES |
| 32966 | |
| 32967 | Exim writes three different logs, referred to as the main log, the reject log, |
| 32968 | and the panic log: |
| 32969 | |
| 32970 | * The main log records the arrival of each message and each delivery in a |
| 32971 | single line in each case. The format is as compact as possible, in an |
| 32972 | attempt to keep down the size of log files. Two-character flag sequences |
| 32973 | make it easy to pick out these lines. A number of other events are recorded |
| 32974 | in the main log. Some of them are optional, in which case the log_selector |
| 32975 | option controls whether they are included or not. A Perl script called |
| 32976 | eximstats, which does simple analysis of main log files, is provided in the |
| 32977 | Exim distribution (see section 53.7). |
| 32978 | |
| 32979 | * The reject log records information from messages that are rejected as a |
| 32980 | result of a configuration option (that is, for policy reasons). The first |
| 32981 | line of each rejection is a copy of the line that is also written to the |
| 32982 | main log. Then, if the message's header has been read at the time the log |
| 32983 | is written, its contents are written to this log. Only the original header |
| 32984 | lines are available; header lines added by ACLs are not logged. You can use |
| 32985 | the reject log to check that your policy controls are working correctly; on |
| 32986 | a busy host this may be easier than scanning the main log for rejection |
| 32987 | messages. You can suppress the writing of the reject log by setting |
| 32988 | write_rejectlog false. |
| 32989 | |
| 32990 | * When certain serious errors occur, Exim writes entries to its panic log. If |
| 32991 | the error is sufficiently disastrous, Exim bombs out afterwards. Panic log |
| 32992 | entries are usually written to the main log as well, but can get lost amid |
| 32993 | the mass of other entries. The panic log should be empty under normal |
| 32994 | circumstances. It is therefore a good idea to check it (or to have a cron |
| 32995 | script check it) regularly, in order to become aware of any problems. When |
| 32996 | Exim cannot open its panic log, it tries as a last resort to write to the |
| 32997 | system log (syslog). This is opened with LOG_PID+LOG_CONS and the facility |
| 32998 | code of LOG_MAIL. The message itself is written at priority LOG_CRIT. |
| 32999 | |
| 33000 | Every log line starts with a timestamp, in the format shown in the following |
| 33001 | example. Note that many of the examples shown in this chapter are line-wrapped. |
| 33002 | In the log file, this would be all on one line: |
| 33003 | |
| 33004 | 2001-09-16 16:09:47 SMTP connection from [127.0.0.1] closed |
| 33005 | by QUIT |
| 33006 | |
| 33007 | By default, the timestamps are in the local timezone. There are two ways of |
| 33008 | changing this: |
| 33009 | |
| 33010 | * You can set the timezone option to a different time zone; in particular, if |
| 33011 | you set |
| 33012 | |
| 33013 | timezone = UTC |
| 33014 | |
| 33015 | the timestamps will be in UTC (aka GMT). |
| 33016 | |
| 33017 | * If you set log_timezone true, the time zone is added to the timestamp, for |
| 33018 | example: |
| 33019 | |
| 33020 | 2003-04-25 11:17:07 +0100 Start queue run: pid=12762 |
| 33021 | |
| 33022 | Exim does not include its process id in log lines by default, but you can |
| 33023 | request that it does so by specifying the "pid" log selector (see section 52.15 |
| 33024 | ). When this is set, the process id is output, in square brackets, immediately |
| 33025 | after the time and date. |
| 33026 | |
| 33027 | |
| 33028 | 52.1 Where the logs are written |
| 33029 | ------------------------------- |
| 33030 | |
| 33031 | The logs may be written to local files, or to syslog, or both. However, it |
| 33032 | should be noted that many syslog implementations use UDP as a transport, and |
| 33033 | are therefore unreliable in the sense that messages are not guaranteed to |
| 33034 | arrive at the loghost, nor is the ordering of messages necessarily maintained. |
| 33035 | It has also been reported that on large log files (tens of megabytes) you may |
| 33036 | need to tweak syslog to prevent it syncing the file with each write - on Linux |
| 33037 | this has been seen to make syslog take 90% plus of CPU time. |
| 33038 | |
| 33039 | The destination for Exim's logs is configured by setting LOG_FILE_PATH in Local |
| 33040 | /Makefile or by setting log_file_path in the run time configuration. This |
| 33041 | latter string is expanded, so it can contain, for example, references to the |
| 33042 | host name: |
| 33043 | |
| 33044 | log_file_path = /var/log/$primary_hostname/exim_%slog |
| 33045 | |
| 33046 | It is generally advisable, however, to set the string in Local/Makefile rather |
| 33047 | than at run time, because then the setting is available right from the start of |
| 33048 | Exim's execution. Otherwise, if there's something it wants to log before it has |
| 33049 | read the configuration file (for example, an error in the configuration file) |
| 33050 | it will not use the path you want, and may not be able to log at all. |
| 33051 | |
| 33052 | The value of LOG_FILE_PATH or log_file_path is a colon-separated list, |
| 33053 | currently limited to at most two items. This is one option where the facility |
| 33054 | for changing a list separator may not be used. The list must always be |
| 33055 | colon-separated. If an item in the list is "syslog" then syslog is used; |
| 33056 | otherwise the item must either be an absolute path, containing "%s" at the |
| 33057 | point where "main", "reject", or "panic" is to be inserted, or be empty, |
| 33058 | implying the use of a default path. |
| 33059 | |
| 33060 | When Exim encounters an empty item in the list, it searches the list defined by |
| 33061 | LOG_FILE_PATH, and uses the first item it finds that is neither empty nor |
| 33062 | "syslog". This means that an empty item in log_file_path can be used to mean |
| 33063 | "use the path specified at build time". It no such item exists, log files are |
| 33064 | written in the log subdirectory of the spool directory. This is equivalent to |
| 33065 | the setting: |
| 33066 | |
| 33067 | log_file_path = $spool_directory/log/%slog |
| 33068 | |
| 33069 | If you do not specify anything at build time or run time, or if you unset the |
| 33070 | option at run time (i.e. "log_file_path = "), that is where the logs are |
| 33071 | written. |
| 33072 | |
| 33073 | A log file path may also contain "%D" or "%M" if datestamped log file names are |
| 33074 | in use - see section 52.3 below. |
| 33075 | |
| 33076 | Here are some examples of possible settings: |
| 33077 | |
| 33078 | LOG_FILE_PATH=syslog syslog only |
| 33079 | LOG_FILE_PATH=:syslog syslog and default path |
| 33080 | LOG_FILE_PATH=syslog : /usr/log/exim_%s syslog and specified path |
| 33081 | LOG_FILE_PATH=/usr/log/exim_%s specified path only |
| 33082 | |
| 33083 | If there are more than two paths in the list, the first is used and a panic |
| 33084 | error is logged. |
| 33085 | |
| 33086 | |
| 33087 | 52.2 Logging to local files that are periodically "cycled" |
| 33088 | ---------------------------------------------------------- |
| 33089 | |
| 33090 | Some operating systems provide centralized and standardized methods for cycling |
| 33091 | log files. For those that do not, a utility script called exicyclog is provided |
| 33092 | (see section 53.6). This renames and compresses the main and reject logs each |
| 33093 | time it is called. The maximum number of old logs to keep can be set. It is |
| 33094 | suggested this script is run as a daily cron job. |
| 33095 | |
| 33096 | An Exim delivery process opens the main log when it first needs to write to it, |
| 33097 | and it keeps the file open in case subsequent entries are required - for |
| 33098 | example, if a number of different deliveries are being done for the same |
| 33099 | message. However, remote SMTP deliveries can take a long time, and this means |
| 33100 | that the file may be kept open long after it is renamed if exicyclog or |
| 33101 | something similar is being used to rename log files on a regular basis. To |
| 33102 | ensure that a switch of log files is noticed as soon as possible, Exim calls |
| 33103 | stat() on the main log's name before reusing an open file, and if the file does |
| 33104 | not exist, or its inode has changed, the old file is closed and Exim tries to |
| 33105 | open the main log from scratch. Thus, an old log file may remain open for quite |
| 33106 | some time, but no Exim processes should write to it once it has been renamed. |
| 33107 | |
| 33108 | |
| 33109 | 52.3 Datestamped log files |
| 33110 | -------------------------- |
| 33111 | |
| 33112 | Instead of cycling the main and reject log files by renaming them periodically, |
| 33113 | some sites like to use files whose names contain a datestamp, for example, |
| 33114 | mainlog-20031225. The datestamp is in the form yyyymmdd or yyyymm. Exim has |
| 33115 | support for this way of working. It is enabled by setting the log_file_path |
| 33116 | option to a path that includes "%D" or "%M" at the point where the datestamp is |
| 33117 | required. For example: |
| 33118 | |
| 33119 | log_file_path = /var/spool/exim/log/%slog-%D |
| 33120 | log_file_path = /var/log/exim-%s-%D.log |
| 33121 | log_file_path = /var/spool/exim/log/%D-%slog |
| 33122 | log_file_path = /var/log/exim/%s.%M |
| 33123 | |
| 33124 | As before, "%s" is replaced by "main" or "reject"; the following are examples |
| 33125 | of names generated by the above examples: |
| 33126 | |
| 33127 | /var/spool/exim/log/mainlog-20021225 |
| 33128 | /var/log/exim-reject-20021225.log |
| 33129 | /var/spool/exim/log/20021225-mainlog |
| 33130 | /var/log/exim/main.200212 |
| 33131 | |
| 33132 | When this form of log file is specified, Exim automatically switches to new |
| 33133 | files at midnight. It does not make any attempt to compress old logs; you will |
| 33134 | need to write your own script if you require this. You should not run exicyclog |
| 33135 | with this form of logging. |
| 33136 | |
| 33137 | The location of the panic log is also determined by log_file_path, but it is |
| 33138 | not datestamped, because rotation of the panic log does not make sense. When |
| 33139 | generating the name of the panic log, "%D" or "%M" are removed from the string. |
| 33140 | In addition, if it immediately follows a slash, a following non-alphanumeric |
| 33141 | character is removed; otherwise a preceding non-alphanumeric character is |
| 33142 | removed. Thus, the four examples above would give these panic log names: |
| 33143 | |
| 33144 | /var/spool/exim/log/paniclog |
| 33145 | /var/log/exim-panic.log |
| 33146 | /var/spool/exim/log/paniclog |
| 33147 | /var/log/exim/panic |
| 33148 | |
| 33149 | |
| 33150 | 52.4 Logging to syslog |
| 33151 | ---------------------- |
| 33152 | |
| 33153 | The use of syslog does not change what Exim logs or the format of its messages, |
| 33154 | except in one respect. If syslog_timestamp is set false, the timestamps on |
| 33155 | Exim's log lines are omitted when these lines are sent to syslog. Apart from |
| 33156 | that, the same strings are written to syslog as to log files. The syslog |
| 33157 | "facility" is set to LOG_MAIL, and the program name to "exim" by default, but |
| 33158 | you can change these by setting the syslog_facility and syslog_processname |
| 33159 | options, respectively. If Exim was compiled with SYSLOG_LOG_PID set in Local/ |
| 33160 | Makefile (this is the default in src/EDITME), then, on systems that permit it |
| 33161 | (all except ULTRIX), the LOG_PID flag is set so that the syslog() call adds the |
| 33162 | pid as well as the time and host name to each line. The three log streams are |
| 33163 | mapped onto syslog priorities as follows: |
| 33164 | |
| 33165 | * mainlog is mapped to LOG_INFO |
| 33166 | |
| 33167 | * rejectlog is mapped to LOG_NOTICE |
| 33168 | |
| 33169 | * paniclog is mapped to LOG_ALERT |
| 33170 | |
| 33171 | Many log lines are written to both mainlog and rejectlog, and some are written |
| 33172 | to both mainlog and paniclog, so there will be duplicates if these are routed |
| 33173 | by syslog to the same place. You can suppress this duplication by setting |
| 33174 | syslog_duplication false. |
| 33175 | |
| 33176 | Exim's log lines can sometimes be very long, and some of its rejectlog entries |
| 33177 | contain multiple lines when headers are included. To cope with both these |
| 33178 | cases, entries written to syslog are split into separate syslog() calls at each |
| 33179 | internal newline, and also after a maximum of 870 data characters. (This allows |
| 33180 | for a total syslog line length of 1024, when additions such as timestamps are |
| 33181 | added.) If you are running a syslog replacement that can handle lines longer |
| 33182 | than the 1024 characters allowed by RFC 3164, you should set |
| 33183 | |
| 33184 | SYSLOG_LONG_LINES=yes |
| 33185 | |
| 33186 | in Local/Makefile before building Exim. That stops Exim from splitting long |
| 33187 | lines, but it still splits at internal newlines in reject log entries. |
| 33188 | |
| 33189 | To make it easy to re-assemble split lines later, each component of a split |
| 33190 | entry starts with a string of the form [<n>/<m>] or [<n>\<m>] where <n> is the |
| 33191 | component number and <m> is the total number of components in the entry. The / |
| 33192 | delimiter is used when the line was split because it was too long; if it was |
| 33193 | split because of an internal newline, the \ delimiter is used. For example, |
| 33194 | supposing the length limit to be 50 instead of 870, the following would be the |
| 33195 | result of a typical rejection message to mainlog (LOG_INFO), each line in |
| 33196 | addition being preceded by the time, host name, and pid as added by syslog: |
| 33197 | |
| 33198 | [1/5] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected from |
| 33199 | [2/5] [127.0.0.1] (ph10): syntax error in 'From' header |
| 33200 | [3/5] when scanning for sender: missing or malformed lo |
| 33201 | [4/5] cal part in "<>" (envelope sender is <ph10@cam.exa |
| 33202 | [5/5] mple>) |
| 33203 | |
| 33204 | The same error might cause the following lines to be written to "rejectlog" |
| 33205 | (LOG_NOTICE): |
| 33206 | |
| 33207 | [1/18] 2002-09-16 16:09:43 16RdAL-0006pc-00 rejected fro |
| 33208 | [2/18] m [127.0.0.1] (ph10): syntax error in 'From' head |
| 33209 | [3/18] er when scanning for sender: missing or malformed |
| 33210 | [4/18] local part in "<>" (envelope sender is <ph10@cam |
| 33211 | [5\18] .example>) |
| 33212 | [6\18] Recipients: ph10@some.domain.cam.example |
| 33213 | [7\18] P Received: from [127.0.0.1] (ident=ph10) |
| 33214 | [8\18] by xxxxx.cam.example with smtp (Exim 4.00) |
| 33215 | [9\18] id 16RdAL-0006pc-00 |
| 33216 | [10/18] for ph10@cam.example; Mon, 16 Sep 2002 16: |
| 33217 | [11\18] 09:43 +0100 |
| 33218 | [12\18] F From: <> |
| 33219 | [13\18] Subject: this is a test header |
| 33220 | [18\18] X-something: this is another header |
| 33221 | [15/18] I Message-Id: <E16RdAL-0006pc-00@xxxxx.cam.examp |
| 33222 | [16\18] le> |
| 33223 | [17\18] B Bcc: |
| 33224 | [18/18] Date: Mon, 16 Sep 2002 16:09:43 +0100 |
| 33225 | |
| 33226 | Log lines that are neither too long nor contain newlines are written to syslog |
| 33227 | without modification. |
| 33228 | |
| 33229 | If only syslog is being used, the Exim monitor is unable to provide a log tail |
| 33230 | display, unless syslog is routing mainlog to a file on the local host and the |
| 33231 | environment variable EXIMON_LOG_FILE_PATH is set to tell the monitor where it |
| 33232 | is. |
| 33233 | |
| 33234 | |
| 33235 | 52.5 Log line flags |
| 33236 | ------------------- |
| 33237 | |
| 33238 | One line is written to the main log for each message received, and for each |
| 33239 | successful, unsuccessful, and delayed delivery. These lines can readily be |
| 33240 | picked out by the distinctive two-character flags that immediately follow the |
| 33241 | timestamp. The flags are: |
| 33242 | |
| 33243 | <= message arrival |
| 33244 | (= message fakereject |
| 33245 | => normal message delivery |
| 33246 | -> additional address in same delivery |
| 33247 | >> cutthrough message delivery |
| 33248 | *> delivery suppressed by -N |
| 33249 | ** delivery failed; address bounced |
| 33250 | == delivery deferred; temporary problem |
| 33251 | |
| 33252 | |
| 33253 | 52.6 Logging message reception |
| 33254 | ------------------------------ |
| 33255 | |
| 33256 | The format of the single-line entry in the main log that is written for every |
| 33257 | message received is shown in the basic example below, which is split over |
| 33258 | several lines in order to fit it on the page: |
| 33259 | |
| 33260 | 2002-10-31 08:57:53 16ZCW1-0005MB-00 <= kryten@dwarf.fict.example |
| 33261 | H=mailer.fict.example [192.168.123.123] U=exim |
| 33262 | P=smtp S=5678 id=<incoming message id> |
| 33263 | |
| 33264 | The address immediately following "<=" is the envelope sender address. A bounce |
| 33265 | message is shown with the sender address "<>", and if it is locally generated, |
| 33266 | this is followed by an item of the form |
| 33267 | |
| 33268 | R=<message id> |
| 33269 | |
| 33270 | which is a reference to the message that caused the bounce to be sent. |
| 33271 | |
| 33272 | For messages from other hosts, the H and U fields identify the remote host and |
| 33273 | record the RFC 1413 identity of the user that sent the message, if one was |
| 33274 | received. The number given in square brackets is the IP address of the sending |
| 33275 | host. If there is a single, unparenthesized host name in the H field, as above, |
| 33276 | it has been verified to correspond to the IP address (see the host_lookup |
| 33277 | option). If the name is in parentheses, it was the name quoted by the remote |
| 33278 | host in the SMTP HELO or EHLO command, and has not been verified. If |
| 33279 | verification yields a different name to that given for HELO or EHLO, the |
| 33280 | verified name appears first, followed by the HELO or EHLO name in parentheses. |
| 33281 | |
| 33282 | Misconfigured hosts (and mail forgers) sometimes put an IP address, with or |
| 33283 | without brackets, in the HELO or EHLO command, leading to entries in the log |
| 33284 | containing text like these examples: |
| 33285 | |
| 33286 | H=(10.21.32.43) [192.168.8.34] |
| 33287 | H=([10.21.32.43]) [192.168.8.34] |
| 33288 | |
| 33289 | This can be confusing. Only the final address in square brackets can be relied |
| 33290 | on. |
| 33291 | |
| 33292 | For locally generated messages (that is, messages not received over TCP/IP), |
| 33293 | the H field is omitted, and the U field contains the login name of the caller |
| 33294 | of Exim. |
| 33295 | |
| 33296 | For all messages, the P field specifies the protocol used to receive the |
| 33297 | message. This is the value that is stored in $received_protocol. In the case of |
| 33298 | incoming SMTP messages, the value indicates whether or not any SMTP extensions |
| 33299 | (ESMTP), encryption, or authentication were used. If the SMTP session was |
| 33300 | encrypted, there is an additional X field that records the cipher suite that |
| 33301 | was used. |
| 33302 | |
| 33303 | The protocol is set to "esmtpsa" or "esmtpa" for messages received from hosts |
| 33304 | that have authenticated themselves using the SMTP AUTH command. The first value |
| 33305 | is used when the SMTP connection was encrypted ("secure"). In this case there |
| 33306 | is an additional item A= followed by the name of the authenticator that was |
| 33307 | used. If an authenticated identification was set up by the authenticator's |
| 33308 | server_set_id option, this is logged too, separated by a colon from the |
| 33309 | authenticator name. |
| 33310 | |
| 33311 | The id field records the existing message id, if present. The size of the |
| 33312 | received message is given by the S field. When the message is delivered, |
| 33313 | headers may be removed or added, so that the size of delivered copies of the |
| 33314 | message may not correspond with this value (and indeed may be different to each |
| 33315 | other). |
| 33316 | |
| 33317 | The log_selector option can be used to request the logging of additional data |
| 33318 | when a message is received. See section 52.15 below. |
| 33319 | |
| 33320 | |
| 33321 | 52.7 Logging deliveries |
| 33322 | ----------------------- |
| 33323 | |
| 33324 | The format of the single-line entry in the main log that is written for every |
| 33325 | delivery is shown in one of the examples below, for local and remote |
| 33326 | deliveries, respectively. Each example has been split into multiple lines in |
| 33327 | order to fit it on the page: |
| 33328 | |
| 33329 | 2002-10-31 08:59:13 16ZCW1-0005MB-00 => marv |
| 33330 | <marv@hitch.fict.example> R=localuser T=local_delivery |
| 33331 | 2002-10-31 09:00:10 16ZCW1-0005MB-00 => |
| 33332 | monk@holistic.fict.example R=dnslookup T=remote_smtp |
| 33333 | H=holistic.fict.example [192.168.234.234] |
| 33334 | |
| 33335 | For ordinary local deliveries, the original address is given in angle brackets |
| 33336 | after the final delivery address, which might be a pipe or a file. If |
| 33337 | intermediate address(es) exist between the original and the final address, the |
| 33338 | last of these is given in parentheses after the final address. The R and T |
| 33339 | fields record the router and transport that were used to process the address. |
| 33340 | |
| 33341 | If SMTP AUTH was used for the delivery there is an additional item A= followed |
| 33342 | by the name of the authenticator that was used. If an authenticated |
| 33343 | identification was set up by the authenticator's client_set_id option, this is |
| 33344 | logged too, separated by a colon from the authenticator name. |
| 33345 | |
| 33346 | If a shadow transport was run after a successful local delivery, the log line |
| 33347 | for the successful delivery has an item added on the end, of the form |
| 33348 | |
| 33349 | ST=<shadow transport name> |
| 33350 | |
| 33351 | If the shadow transport did not succeed, the error message is put in |
| 33352 | parentheses afterwards. |
| 33353 | |
| 33354 | When more than one address is included in a single delivery (for example, two |
| 33355 | SMTP RCPT commands in one transaction) the second and subsequent addresses are |
| 33356 | flagged with "->" instead of "=>". When two or more messages are delivered down |
| 33357 | a single SMTP connection, an asterisk follows the IP address in the log lines |
| 33358 | for the second and subsequent messages. |
| 33359 | |
| 33360 | When delivery is done in cutthrough mode it is flagged with ">>" and the log |
| 33361 | line precedes the reception line, since cutthrough waits for a possible |
| 33362 | rejection from the destination in case it can reject the sourced item. |
| 33363 | |
| 33364 | The generation of a reply message by a filter file gets logged as a "delivery" |
| 33365 | to the addressee, preceded by ">". |
| 33366 | |
| 33367 | The log_selector option can be used to request the logging of additional data |
| 33368 | when a message is delivered. See section 52.15 below. |
| 33369 | |
| 33370 | |
| 33371 | 52.8 Discarded deliveries |
| 33372 | ------------------------- |
| 33373 | |
| 33374 | When a message is discarded as a result of the command "seen finish" being |
| 33375 | obeyed in a filter file which generates no deliveries, a log entry of the form |
| 33376 | |
| 33377 | 2002-12-10 00:50:49 16auJc-0001UB-00 => discarded |
| 33378 | <low.club@bridge.example> R=userforward |
| 33379 | |
| 33380 | is written, to record why no deliveries are logged. When a message is discarded |
| 33381 | because it is aliased to ":blackhole:" the log line is like this: |
| 33382 | |
| 33383 | 1999-03-02 09:44:33 10HmaX-0005vi-00 => :blackhole: |
| 33384 | <hole@nowhere.example> R=blackhole_router |
| 33385 | |
| 33386 | |
| 33387 | 52.9 Deferred deliveries |
| 33388 | ------------------------ |
| 33389 | |
| 33390 | When a delivery is deferred, a line of the following form is logged: |
| 33391 | |
| 33392 | 2002-12-19 16:20:23 16aiQz-0002Q5-00 == marvin@endrest.example |
| 33393 | R=dnslookup T=smtp defer (146): Connection refused |
| 33394 | |
| 33395 | In the case of remote deliveries, the error is the one that was given for the |
| 33396 | last IP address that was tried. Details of individual SMTP failures are also |
| 33397 | written to the log, so the above line would be preceded by something like |
| 33398 | |
| 33399 | 2002-12-19 16:20:23 16aiQz-0002Q5-00 Failed to connect to |
| 33400 | mail1.endrest.example [192.168.239.239]: Connection refused |
| 33401 | |
| 33402 | When a deferred address is skipped because its retry time has not been reached, |
| 33403 | a message is written to the log, but this can be suppressed by setting an |
| 33404 | appropriate value in log_selector. |
| 33405 | |
| 33406 | |
| 33407 | 52.10 Delivery failures |
| 33408 | ----------------------- |
| 33409 | |
| 33410 | If a delivery fails because an address cannot be routed, a line of the |
| 33411 | following form is logged: |
| 33412 | |
| 33413 | 1995-12-19 16:20:23 0tRiQz-0002Q5-00 ** jim@trek99.example |
| 33414 | <jim@trek99.example>: unknown mail domain |
| 33415 | |
| 33416 | If a delivery fails at transport time, the router and transport are shown, and |
| 33417 | the response from the remote host is included, as in this example: |
| 33418 | |
| 33419 | 2002-07-11 07:14:17 17SXDU-000189-00 ** ace400@pb.example |
| 33420 | R=dnslookup T=remote_smtp: SMTP error from remote mailer |
| 33421 | after pipelined RCPT TO:<ace400@pb.example>: host |
| 33422 | pbmail3.py.example [192.168.63.111]: 553 5.3.0 |
| 33423 | <ace400@pb.example>...Addressee unknown |
| 33424 | |
| 33425 | The word "pipelined" indicates that the SMTP PIPELINING extension was being |
| 33426 | used. See hosts_avoid_esmtp in the smtp transport for a way of disabling |
| 33427 | PIPELINING. The log lines for all forms of delivery failure are flagged with |
| 33428 | "**". |
| 33429 | |
| 33430 | |
| 33431 | 52.11 Fake deliveries |
| 33432 | --------------------- |
| 33433 | |
| 33434 | If a delivery does not actually take place because the -N option has been used |
| 33435 | to suppress it, a normal delivery line is written to the log, except that "=>" |
| 33436 | is replaced by "*>". |
| 33437 | |
| 33438 | |
| 33439 | 52.12 Completion |
| 33440 | ---------------- |
| 33441 | |
| 33442 | A line of the form |
| 33443 | |
| 33444 | 2002-10-31 09:00:11 16ZCW1-0005MB-00 Completed |
| 33445 | |
| 33446 | is written to the main log when a message is about to be removed from the spool |
| 33447 | at the end of its processing. |
| 33448 | |
| 33449 | |
| 33450 | 52.13 Summary of Fields in Log Lines |
| 33451 | ------------------------------------ |
| 33452 | |
| 33453 | A summary of the field identifiers that are used in log lines is shown in the |
| 33454 | following table: |
| 33455 | |
| 33456 | A authenticator name (and optional id and sender) |
| 33457 | C SMTP confirmation on delivery |
| 33458 | command list for "no mail in SMTP session" |
| 33459 | CV certificate verification status |
| 33460 | D duration of "no mail in SMTP session" |
| 33461 | DN distinguished name from peer certificate |
| 33462 | DS DNSSEC secured lookups |
| 33463 | DT on => lines: time taken for a delivery |
| 33464 | F sender address (on delivery lines) |
| 33465 | H host name and IP address |
| 33466 | I local interface used |
| 33467 | K CHUNKING extension used |
| 33468 | id message id for incoming message |
| 33469 | P on <= lines: protocol used |
| 33470 | on => and ** lines: return path |
| 33471 | PRDR PRDR extension used |
| 33472 | PRX on <= and => lines: proxy address |
| 33473 | Q alternate queue name |
| 33474 | QT on => lines: time spent on queue so far |
| 33475 | on "Completed" lines: time spent on queue |
| 33476 | R on <= lines: reference for local bounce |
| 33477 | on => >> ** and == lines: router name |
| 33478 | S size of message in bytes |
| 33479 | SNI server name indication from TLS client hello |
| 33480 | ST shadow transport name |
| 33481 | T on <= lines: message subject (topic) |
| 33482 | on => ** and == lines: transport name |
| 33483 | U local user or RFC 1413 identity |
| 33484 | X TLS cipher suite |
| 33485 | |
| 33486 | |
| 33487 | 52.14 Other log entries |
| 33488 | ----------------------- |
| 33489 | |
| 33490 | Various other types of log entry are written from time to time. Most should be |
| 33491 | self-explanatory. Among the more common are: |
| 33492 | |
| 33493 | * retry time not reached An address previously suffered a temporary error |
| 33494 | during routing or local delivery, and the time to retry has not yet |
| 33495 | arrived. This message is not written to an individual message log file |
| 33496 | unless it happens during the first delivery attempt. |
| 33497 | |
| 33498 | * retry time not reached for any host An address previously suffered |
| 33499 | temporary errors during remote delivery, and the retry time has not yet |
| 33500 | arrived for any of the hosts to which it is routed. |
| 33501 | |
| 33502 | * spool file locked An attempt to deliver a message cannot proceed because |
| 33503 | some other Exim process is already working on the message. This can be |
| 33504 | quite common if queue running processes are started at frequent intervals. |
| 33505 | The exiwhat utility script can be used to find out what Exim processes are |
| 33506 | doing. |
| 33507 | |
| 33508 | * error ignored There are several circumstances that give rise to this |
| 33509 | message: |
| 33510 | |
| 33511 | 1. Exim failed to deliver a bounce message whose age was greater than |
| 33512 | ignore_bounce_errors_after. The bounce was discarded. |
| 33513 | |
| 33514 | 2. A filter file set up a delivery using the "noerror" option, and the |
| 33515 | delivery failed. The delivery was discarded. |
| 33516 | |
| 33517 | 3. A delivery set up by a router configured with |
| 33518 | |
| 33519 | errors_to = <> |
| 33520 | |
| 33521 | failed. The delivery was discarded. |
| 33522 | |
| 33523 | |
| 33524 | 52.15 Reducing or increasing what is logged |
| 33525 | ------------------------------------------- |
| 33526 | |
| 33527 | By setting the log_selector global option, you can disable some of Exim's |
| 33528 | default logging, or you can request additional logging. The value of |
| 33529 | log_selector is made up of names preceded by plus or minus characters. For |
| 33530 | example: |
| 33531 | |
| 33532 | log_selector = +arguments -retry_defer |
| 33533 | |
| 33534 | The list of optional log items is in the following table, with the default |
| 33535 | selection marked by asterisks: |
| 33536 | |
| 33537 | 8bitmime received 8BITMIME status |
| 33538 | *acl_warn_skipped skipped warn statement in ACL |
| 33539 | address_rewrite address rewriting |
| 33540 | all_parents all parents in => lines |
| 33541 | arguments command line arguments |
| 33542 | *connection_reject connection rejections |
| 33543 | *delay_delivery immediate delivery delayed |
| 33544 | deliver_time time taken to perform delivery |
| 33545 | delivery_size add S=nnn to => lines |
| 33546 | *dnslist_defer defers of DNS list (aka RBL) lookups |
| 33547 | dnssec DNSSEC secured lookups |
| 33548 | *etrn ETRN commands |
| 33549 | *host_lookup_failed as it says |
| 33550 | ident_timeout timeout for ident connection |
| 33551 | incoming_interface local interface on <= and => lines |
| 33552 | incoming_port remote port on <= lines |
| 33553 | *lost_incoming_connection as it says (includes timeouts) |
| 33554 | outgoing_interface local interface on => lines |
| 33555 | outgoing_port add remote port to => lines |
| 33556 | *queue_run start and end queue runs |
| 33557 | queue_time time on queue for one recipient |
| 33558 | queue_time_overall time on queue for whole message |
| 33559 | pid Exim process id |
| 33560 | proxy proxy address on <= and => lines |
| 33561 | received_recipients recipients on <= lines |
| 33562 | received_sender sender on <= lines |
| 33563 | *rejected_header header contents on reject log |
| 33564 | *retry_defer "retry time not reached" |
| 33565 | return_path_on_delivery put return path on => and ** lines |
| 33566 | sender_on_delivery add sender to => lines |
| 33567 | *sender_verify_fail sender verification failures |
| 33568 | *size_reject rejection because too big |
| 33569 | *skip_delivery delivery skipped in a queue run |
| 33570 | *smtp_confirmation SMTP confirmation on => lines |
| 33571 | smtp_connection incoming SMTP connections |
| 33572 | smtp_incomplete_transaction incomplete SMTP transactions |
| 33573 | smtp_mailauth AUTH argument to MAIL commands |
| 33574 | smtp_no_mail session with no MAIL commands |
| 33575 | smtp_protocol_error SMTP protocol errors |
| 33576 | smtp_syntax_error SMTP syntax errors |
| 33577 | subject contents of Subject: on <= lines |
| 33578 | *tls_certificate_verified certificate verification status |
| 33579 | *tls_cipher TLS cipher suite on <= and => lines |
| 33580 | tls_peerdn TLS peer DN on <= and => lines |
| 33581 | tls_sni TLS SNI on <= lines |
| 33582 | unknown_in_list DNS lookup failed in list match |
| 33583 | |
| 33584 | all all of the above |
| 33585 | |
| 33586 | See also the slow_lookup_log main configuration option, section 14.4 |
| 33587 | |
| 33588 | More details on each of these items follows: |
| 33589 | |
| 33590 | * 8bitmime: This causes Exim to log any 8BITMIME status of received messages, |
| 33591 | which may help in tracking down interoperability issues with ancient MTAs |
| 33592 | that are not 8bit clean. This is added to the "<=" line, tagged with "M8S=" |
| 33593 | and a value of "0", "7" or "8", corresponding to "not given", "7BIT" and |
| 33594 | "8BITMIME" respectively. |
| 33595 | |
| 33596 | * acl_warn_skipped: When an ACL warn statement is skipped because one of its |
| 33597 | conditions cannot be evaluated, a log line to this effect is written if |
| 33598 | this log selector is set. |
| 33599 | |
| 33600 | * address_rewrite: This applies both to global rewrites and per-transport |
| 33601 | rewrites, but not to rewrites in filters run as an unprivileged user |
| 33602 | (because such users cannot access the log). |
| 33603 | |
| 33604 | * all_parents: Normally only the original and final addresses are logged on |
| 33605 | delivery lines; with this selector, intermediate parents are given in |
| 33606 | parentheses between them. |
| 33607 | |
| 33608 | * arguments: This causes Exim to write the arguments with which it was called |
| 33609 | to the main log, preceded by the current working directory. This is a |
| 33610 | debugging feature, added to make it easier to find out how certain MUAs |
| 33611 | call /usr/sbin/sendmail. The logging does not happen if Exim has given up |
| 33612 | root privilege because it was called with the -C or -D options. Arguments |
| 33613 | that are empty or that contain white space are quoted. Non-printing |
| 33614 | characters are shown as escape sequences. This facility cannot log |
| 33615 | unrecognized arguments, because the arguments are checked before the |
| 33616 | configuration file is read. The only way to log such cases is to interpose |
| 33617 | a script such as util/logargs.sh between the caller and Exim. |
| 33618 | |
| 33619 | * connection_reject: A log entry is written whenever an incoming SMTP |
| 33620 | connection is rejected, for whatever reason. |
| 33621 | |
| 33622 | * delay_delivery: A log entry is written whenever a delivery process is not |
| 33623 | started for an incoming message because the load is too high or too many |
| 33624 | messages were received on one connection. Logging does not occur if no |
| 33625 | delivery process is started because queue_only is set or -odq was used. |
| 33626 | |
| 33627 | * deliver_time: For each delivery, the amount of real time it has taken to |
| 33628 | perform the actual delivery is logged as DT=<time>, for example, "DT=1s". |
| 33629 | |
| 33630 | * delivery_size: For each delivery, the size of message delivered is added to |
| 33631 | the "=>" line, tagged with S=. |
| 33632 | |
| 33633 | * dnslist_defer: A log entry is written if an attempt to look up a host in a |
| 33634 | DNS black list suffers a temporary error. |
| 33635 | |
| 33636 | * dnssec: For message acceptance and (attempted) delivery log lines, when dns |
| 33637 | lookups gave secure results a tag of DS is added. For acceptance this |
| 33638 | covers the reverse and forward lookups for host name verification. It does |
| 33639 | not cover helo-name verification. For delivery this covers the SRV, MX, A |
| 33640 | and/or AAAA lookups. |
| 33641 | |
| 33642 | * etrn: Every valid ETRN command that is received is logged, before the ACL |
| 33643 | is run to determine whether or not it is actually accepted. An invalid ETRN |
| 33644 | command, or one received within a message transaction is not logged by this |
| 33645 | selector (see smtp_syntax_error and smtp_protocol_error). |
| 33646 | |
| 33647 | * host_lookup_failed: When a lookup of a host's IP addresses fails to find |
| 33648 | any addresses, or when a lookup of an IP address fails to find a host name, |
| 33649 | a log line is written. This logging does not apply to direct DNS lookups |
| 33650 | when routing email addresses, but it does apply to "byname" lookups. |
| 33651 | |
| 33652 | * ident_timeout: A log line is written whenever an attempt to connect to a |
| 33653 | client's ident port times out. |
| 33654 | |
| 33655 | * incoming_interface: The interface on which a message was received is added |
| 33656 | to the "<=" line as an IP address in square brackets, tagged by I= and |
| 33657 | followed by a colon and the port number. The local interface and port are |
| 33658 | also added to other SMTP log lines, for example "SMTP connection from", to |
| 33659 | rejection lines, and (despite the name) to outgoing "=>" and "->" lines. |
| 33660 | The latter can be disabled by turning off the outgoing_interface option. |
| 33661 | |
| 33662 | * proxy: The internal (closest to the system running Exim) IP address of the |
| 33663 | proxy, tagged by PRX=, on the "<=" line for a message accepted on a proxied |
| 33664 | connection or the "=>" line for a message delivered on a proxied |
| 33665 | connection. See 58.1 for more information. |
| 33666 | |
| 33667 | * incoming_port: The remote port number from which a message was received is |
| 33668 | added to log entries and Received: header lines, following the IP address |
| 33669 | in square brackets, and separated from it by a colon. This is implemented |
| 33670 | by changing the value that is put in the $sender_fullhost and |
| 33671 | $sender_rcvhost variables. Recording the remote port number has become more |
| 33672 | important with the widening use of NAT (see RFC 2505). |
| 33673 | |
| 33674 | * lost_incoming_connection: A log line is written when an incoming SMTP |
| 33675 | connection is unexpectedly dropped. |
| 33676 | |
| 33677 | * outgoing_interface: If incoming_interface is turned on, then the interface |
| 33678 | on which a message was sent is added to delivery lines as an I= tag |
| 33679 | followed by IP address in square brackets. You can disable this by turning |
| 33680 | off the outgoing_interface option. |
| 33681 | |
| 33682 | * outgoing_port: The remote port number is added to delivery log lines (those |
| 33683 | containing => tags) following the IP address. The local port is also added |
| 33684 | if incoming_interface and outgoing_interface are both enabled. This option |
| 33685 | is not included in the default setting, because for most ordinary |
| 33686 | configurations, the remote port number is always 25 (the SMTP port), and |
| 33687 | the local port is a random ephemeral port. |
| 33688 | |
| 33689 | * pid: The current process id is added to every log line, in square brackets, |
| 33690 | immediately after the time and date. |
| 33691 | |
| 33692 | * queue_run: The start and end of every queue run are logged. |
| 33693 | |
| 33694 | * queue_time: The amount of time the message has been in the queue on the |
| 33695 | local host is logged as QT=<time> on delivery ("=>") lines, for example, |
| 33696 | "QT=3m45s". The clock starts when Exim starts to receive the message, so it |
| 33697 | includes reception time as well as the delivery time for the current |
| 33698 | address. This means that it may be longer than the difference between the |
| 33699 | arrival and delivery log line times, because the arrival log line is not |
| 33700 | written until the message has been successfully received. |
| 33701 | |
| 33702 | * queue_time_overall: The amount of time the message has been in the queue on |
| 33703 | the local host is logged as QT=<time> on "Completed" lines, for example, |
| 33704 | "QT=3m45s". The clock starts when Exim starts to receive the message, so it |
| 33705 | includes reception time as well as the total delivery time. |
| 33706 | |
| 33707 | * received_recipients: The recipients of a message are listed in the main log |
| 33708 | as soon as the message is received. The list appears at the end of the log |
| 33709 | line that is written when a message is received, preceded by the word |
| 33710 | "for". The addresses are listed after they have been qualified, but before |
| 33711 | any rewriting has taken place. Recipients that were discarded by an ACL for |
| 33712 | MAIL or RCPT do not appear in the list. |
| 33713 | |
| 33714 | * received_sender: The unrewritten original sender of a message is added to |
| 33715 | the end of the log line that records the message's arrival, after the word |
| 33716 | "from" (before the recipients if received_recipients is also set). |
| 33717 | |
| 33718 | * rejected_header: If a message's header has been received at the time a |
| 33719 | rejection is written to the reject log, the complete header is added to the |
| 33720 | log. Header logging can be turned off individually for messages that are |
| 33721 | rejected by the local_scan() function (see section 45.2). |
| 33722 | |
| 33723 | * retry_defer: A log line is written if a delivery is deferred because a |
| 33724 | retry time has not yet been reached. However, this "retry time not reached" |
| 33725 | message is always omitted from individual message logs after the first |
| 33726 | delivery attempt. |
| 33727 | |
| 33728 | * return_path_on_delivery: The return path that is being transmitted with the |
| 33729 | message is included in delivery and bounce lines, using the tag P=. This is |
| 33730 | omitted if no delivery actually happens, for example, if routing fails, or |
| 33731 | if delivery is to /dev/null or to ":blackhole:". |
| 33732 | |
| 33733 | * sender_on_delivery: The message's sender address is added to every delivery |
| 33734 | and bounce line, tagged by F= (for "from"). This is the original sender |
| 33735 | that was received with the message; it is not necessarily the same as the |
| 33736 | outgoing return path. |
| 33737 | |
| 33738 | * sender_verify_fail: If this selector is unset, the separate log line that |
| 33739 | gives details of a sender verification failure is not written. Log lines |
| 33740 | for the rejection of SMTP commands contain just "sender verify failed", so |
| 33741 | some detail is lost. |
| 33742 | |
| 33743 | * size_reject: A log line is written whenever a message is rejected because |
| 33744 | it is too big. |
| 33745 | |
| 33746 | * skip_delivery: A log line is written whenever a message is skipped during a |
| 33747 | queue run because it is frozen or because another process is already |
| 33748 | delivering it. The message that is written is "spool file is locked". |
| 33749 | |
| 33750 | * smtp_confirmation: The response to the final "." in the SMTP or LMTP |
| 33751 | dialogue for outgoing messages is added to delivery log lines in the form |
| 33752 | "C="<text>. A number of MTAs (including Exim) return an identifying string |
| 33753 | in this response. |
| 33754 | |
| 33755 | * smtp_connection: A log line is written whenever an incoming SMTP connection |
| 33756 | is established or closed, unless the connection is from a host that matches |
| 33757 | hosts_connection_nolog. (In contrast, lost_incoming_connection applies only |
| 33758 | when the closure is unexpected.) This applies to connections from local |
| 33759 | processes that use -bs as well as to TCP/IP connections. If a connection is |
| 33760 | dropped in the middle of a message, a log line is always written, whether |
| 33761 | or not this selector is set, but otherwise nothing is written at the start |
| 33762 | and end of connections unless this selector is enabled. |
| 33763 | |
| 33764 | For TCP/IP connections to an Exim daemon, the current number of connections |
| 33765 | is included in the log message for each new connection, but note that the |
| 33766 | count is reset if the daemon is restarted. Also, because connections are |
| 33767 | closed (and the closure is logged) in subprocesses, the count may not |
| 33768 | include connections that have been closed but whose termination the daemon |
| 33769 | has not yet noticed. Thus, while it is possible to match up the opening and |
| 33770 | closing of connections in the log, the value of the logged counts may not |
| 33771 | be entirely accurate. |
| 33772 | |
| 33773 | * smtp_incomplete_transaction: When a mail transaction is aborted by RSET, |
| 33774 | QUIT, loss of connection, or otherwise, the incident is logged, and the |
| 33775 | message sender plus any accepted recipients are included in the log line. |
| 33776 | This can provide evidence of dictionary attacks. |
| 33777 | |
| 33778 | * smtp_no_mail: A line is written to the main log whenever an accepted SMTP |
| 33779 | connection terminates without having issued a MAIL command. This includes |
| 33780 | both the case when the connection is dropped, and the case when QUIT is |
| 33781 | used. It does not include cases where the connection is rejected right at |
| 33782 | the start (by an ACL, or because there are too many connections, or |
| 33783 | whatever). These cases already have their own log lines. |
| 33784 | |
| 33785 | The log line that is written contains the identity of the client in the |
| 33786 | usual way, followed by D= and a time, which records the duration of the |
| 33787 | connection. If the connection was authenticated, this fact is logged |
| 33788 | exactly as it is for an incoming message, with an A= item. If the |
| 33789 | connection was encrypted, CV=, DN=, and X= items may appear as they do for |
| 33790 | an incoming message, controlled by the same logging options. |
| 33791 | |
| 33792 | Finally, if any SMTP commands were issued during the connection, a C= item |
| 33793 | is added to the line, listing the commands that were used. For example, |
| 33794 | |
| 33795 | C=EHLO,QUIT |
| 33796 | |
| 33797 | shows that the client issued QUIT straight after EHLO. If there were fewer |
| 33798 | than 20 commands, they are all listed. If there were more than 20 commands, |
| 33799 | the last 20 are listed, preceded by "...". However, with the default |
| 33800 | setting of 10 for smtp_accept_max_nonmail, the connection will in any case |
| 33801 | have been aborted before 20 non-mail commands are processed. |
| 33802 | |
| 33803 | * smtp_mailauth: A third subfield with the authenticated sender, |
| 33804 | colon-separated, is appended to the A= item for a message arrival or |
| 33805 | delivery log line, if an AUTH argument to the SMTP MAIL command (see 33.2) |
| 33806 | was accepted or used. |
| 33807 | |
| 33808 | * smtp_protocol_error: A log line is written for every SMTP protocol error |
| 33809 | encountered. Exim does not have perfect detection of all protocol errors |
| 33810 | because of transmission delays and the use of pipelining. If PIPELINING has |
| 33811 | been advertised to a client, an Exim server assumes that the client will |
| 33812 | use it, and therefore it does not count "expected" errors (for example, |
| 33813 | RCPT received after rejecting MAIL) as protocol errors. |
| 33814 | |
| 33815 | * smtp_syntax_error: A log line is written for every SMTP syntax error |
| 33816 | encountered. An unrecognized command is treated as a syntax error. For an |
| 33817 | external connection, the host identity is given; for an internal connection |
| 33818 | using -bs the sender identification (normally the calling user) is given. |
| 33819 | |
| 33820 | * subject: The subject of the message is added to the arrival log line, |
| 33821 | preceded by "T=" (T for "topic", since S is already used for "size"). Any |
| 33822 | MIME "words" in the subject are decoded. The print_topbitchars option |
| 33823 | specifies whether characters with values greater than 127 should be logged |
| 33824 | unchanged, or whether they should be rendered as escape sequences. |
| 33825 | |
| 33826 | * tls_certificate_verified: An extra item is added to <= and => log lines |
| 33827 | when TLS is in use. The item is "CV=yes" if the peer's certificate was |
| 33828 | verified, and "CV=no" if not. |
| 33829 | |
| 33830 | * tls_cipher: When a message is sent or received over an encrypted |
| 33831 | connection, the cipher suite used is added to the log line, preceded by X=. |
| 33832 | |
| 33833 | * tls_peerdn: When a message is sent or received over an encrypted |
| 33834 | connection, and a certificate is supplied by the remote host, the peer DN |
| 33835 | is added to the log line, preceded by DN=. |
| 33836 | |
| 33837 | * tls_sni: When a message is received over an encrypted connection, and the |
| 33838 | remote host provided the Server Name Indication extension, the SNI is added |
| 33839 | to the log line, preceded by SNI=. |
| 33840 | |
| 33841 | * unknown_in_list: This setting causes a log entry to be written when the |
| 33842 | result of a list match is failure because a DNS lookup failed. |
| 33843 | |
| 33844 | |
| 33845 | 52.16 Message log |
| 33846 | ----------------- |
| 33847 | |
| 33848 | In addition to the general log files, Exim writes a log file for each message |
| 33849 | that it handles. The names of these per-message logs are the message ids, and |
| 33850 | they are kept in the msglog sub-directory of the spool directory. Each message |
| 33851 | log contains copies of the log lines that apply to the message. This makes it |
| 33852 | easier to inspect the status of an individual message without having to search |
| 33853 | the main log. A message log is deleted when processing of the message is |
| 33854 | complete, unless preserve_message_logs is set, but this should be used only |
| 33855 | with great care because they can fill up your disk very quickly. |
| 33856 | |
| 33857 | On a heavily loaded system, it may be desirable to disable the use of |
| 33858 | per-message logs, in order to reduce disk I/O. This can be done by setting the |
| 33859 | message_logs option false. |
| 33860 | |
| 33861 | |
| 33862 | |
| 33863 | =============================================================================== |
| 33864 | 53. EXIM UTILITIES |
| 33865 | |
| 33866 | A number of utility scripts and programs are supplied with Exim and are |
| 33867 | described in this chapter. There is also the Exim Monitor, which is covered in |
| 33868 | the next chapter. The utilities described here are: |
| 33869 | |
| 33870 | 53.1 exiwhat list what Exim processes are doing |
| 33871 | 53.2 exiqgrep grep the queue |
| 33872 | 53.3 exiqsumm summarize the queue |
| 33873 | 53.4 exigrep search the main log |
| 33874 | 53.5 exipick select messages on various criteria |
| 33875 | 53.6 exicyclog cycle (rotate) log files |
| 33876 | 53.7 eximstats extract statistics from the log |
| 33877 | 53.8 exim_checkaccess check address acceptance from given IP |
| 33878 | 53.9 exim_dbmbuild build a DBM file |
| 33879 | 53.10 exinext extract retry information |
| 33880 | 53.11 exim_dumpdb dump a hints database |
| 33881 | 53.11 exim_tidydb clean up a hints database |
| 33882 | 53.11 exim_fixdb patch a hints database |
| 33883 | 53.15 exim_lock lock a mailbox file |
| 33884 | |
| 33885 | Another utility that might be of use to sites with many MTAs is Tom Kistner's |
| 33886 | exilog. It provides log visualizations across multiple Exim servers. See http:/ |
| 33887 | /duncanthrax.net/exilog/ for details. |
| 33888 | |
| 33889 | |
| 33890 | 53.1 Finding out what Exim processes are doing (exiwhat) |
| 33891 | -------------------------------------------------------- |
| 33892 | |
| 33893 | On operating systems that can restart a system call after receiving a signal |
| 33894 | (most modern OS), an Exim process responds to the SIGUSR1 signal by writing a |
| 33895 | line describing what it is doing to the file exim-process.info in the Exim |
| 33896 | spool directory. The exiwhat script sends the signal to all Exim processes it |
| 33897 | can find, having first emptied the file. It then waits for one second to allow |
| 33898 | the Exim processes to react before displaying the results. In order to run |
| 33899 | exiwhat successfully you have to have sufficient privilege to send the signal |
| 33900 | to the Exim processes, so it is normally run as root. |
| 33901 | |
| 33902 | Warning: This is not an efficient process. It is intended for occasional use by |
| 33903 | system administrators. It is not sensible, for example, to set up a script that |
| 33904 | sends SIGUSR1 signals to Exim processes at short intervals. |
| 33905 | |
| 33906 | Unfortunately, the ps command that exiwhat uses to find Exim processes varies |
| 33907 | in different operating systems. Not only are different options used, but the |
| 33908 | format of the output is different. For this reason, there are some system |
| 33909 | configuration options that configure exactly how exiwhat works. If it doesn't |
| 33910 | seem to be working for you, check the following compile-time options: |
| 33911 | |
| 33912 | EXIWHAT_PS_CMD the command for running ps |
| 33913 | EXIWHAT_PS_ARG the argument for ps |
| 33914 | EXIWHAT_EGREP_ARG the argument for egrep to select from ps output |
| 33915 | EXIWHAT_KILL_ARG the argument for the kill command |
| 33916 | |
| 33917 | An example of typical output from exiwhat is |
| 33918 | |
| 33919 | 164 daemon: -q1h, listening on port 25 |
| 33920 | 10483 running queue: waiting for 0tAycK-0002ij-00 (10492) |
| 33921 | 10492 delivering 0tAycK-0002ij-00 to mail.ref.example |
| 33922 | [10.19.42.42] (editor@ref.example) |
| 33923 | 10592 handling incoming call from [192.168.243.242] |
| 33924 | 10628 accepting a local non-SMTP message |
| 33925 | |
| 33926 | The first number in the output line is the process number. The third line has |
| 33927 | been split here, in order to fit it on the page. |
| 33928 | |
| 33929 | |
| 33930 | 53.2 Selective queue listing (exiqgrep) |
| 33931 | --------------------------------------- |
| 33932 | |
| 33933 | This utility is a Perl script contributed by Matt Hubbard. It runs |
| 33934 | |
| 33935 | exim -bpu |
| 33936 | |
| 33937 | or (in case -a switch is specified) |
| 33938 | |
| 33939 | exim -bp |
| 33940 | |
| 33941 | The -C option is used to specify an alternate exim.conf which might contain |
| 33942 | alternate exim configuration the queue management might be using. |
| 33943 | |
| 33944 | to obtain a queue listing, and then greps the output to select messages that |
| 33945 | match given criteria. The following selection options are available: |
| 33946 | |
| 33947 | -f <regex> |
| 33948 | |
| 33949 | Match the sender address using a case-insensitive search. The field that is |
| 33950 | tested is enclosed in angle brackets, so you can test for bounce messages |
| 33951 | with |
| 33952 | |
| 33953 | exiqgrep -f '^<>$' |
| 33954 | |
| 33955 | -r <regex> |
| 33956 | |
| 33957 | Match a recipient address using a case-insensitive search. The field that |
| 33958 | is tested is not enclosed in angle brackets. |
| 33959 | |
| 33960 | -s <regex> |
| 33961 | |
| 33962 | Match against the size field. |
| 33963 | |
| 33964 | -y <seconds> |
| 33965 | |
| 33966 | Match messages that are younger than the given time. |
| 33967 | |
| 33968 | -o <seconds> |
| 33969 | |
| 33970 | Match messages that are older than the given time. |
| 33971 | |
| 33972 | -z |
| 33973 | |
| 33974 | Match only frozen messages. |
| 33975 | |
| 33976 | -x |
| 33977 | |
| 33978 | Match only non-frozen messages. |
| 33979 | |
| 33980 | The following options control the format of the output: |
| 33981 | |
| 33982 | -c |
| 33983 | |
| 33984 | Display only the count of matching messages. |
| 33985 | |
| 33986 | -l |
| 33987 | |
| 33988 | Long format - display the full message information as output by Exim. This |
| 33989 | is the default. |
| 33990 | |
| 33991 | -i |
| 33992 | |
| 33993 | Display message ids only. |
| 33994 | |
| 33995 | -b |
| 33996 | |
| 33997 | Brief format - one line per message. |
| 33998 | |
| 33999 | -R |
| 34000 | |
| 34001 | Display messages in reverse order. |
| 34002 | |
| 34003 | -a |
| 34004 | |
| 34005 | Include delivered recipients in queue listing. |
| 34006 | |
| 34007 | There is one more option, -h, which outputs a list of options. |
| 34008 | |
| 34009 | |
| 34010 | 53.3 Summarizing the queue (exiqsumm) |
| 34011 | ------------------------------------- |
| 34012 | |
| 34013 | The exiqsumm utility is a Perl script which reads the output of "exim -bp" and |
| 34014 | produces a summary of the messages on the queue. Thus, you use it by running a |
| 34015 | command such as |
| 34016 | |
| 34017 | exim -bp | exiqsumm |
| 34018 | |
| 34019 | The output consists of one line for each domain that has messages waiting for |
| 34020 | it, as in the following example: |
| 34021 | |
| 34022 | 3 2322 74m 66m msn.com.example |
| 34023 | |
| 34024 | Each line lists the number of pending deliveries for a domain, their total |
| 34025 | volume, and the length of time that the oldest and the newest messages have |
| 34026 | been waiting. Note that the number of pending deliveries is greater than the |
| 34027 | number of messages when messages have more than one recipient. |
| 34028 | |
| 34029 | A summary line is output at the end. By default the output is sorted on the |
| 34030 | domain name, but exiqsumm has the options -a and -c, which cause the output to |
| 34031 | be sorted by oldest message and by count of messages, respectively. There are |
| 34032 | also three options that split the messages for each domain into two or more |
| 34033 | subcounts: -b separates bounce messages, -f separates frozen messages, and -s |
| 34034 | separates messages according to their sender. |
| 34035 | |
| 34036 | The output of exim -bp contains the original addresses in the message, so this |
| 34037 | also applies to the output from exiqsumm. No domains from addresses generated |
| 34038 | by aliasing or forwarding are included (unless the one_time option of the |
| 34039 | redirect router has been used to convert them into "top level" addresses). |
| 34040 | |
| 34041 | |
| 34042 | 53.4 Extracting specific information from the log (exigrep) |
| 34043 | ----------------------------------------------------------- |
| 34044 | |
| 34045 | The exigrep utility is a Perl script that searches one or more main log files |
| 34046 | for entries that match a given pattern. When it finds a match, it extracts all |
| 34047 | the log entries for the relevant message, not just those that match the |
| 34048 | pattern. Thus, exigrep can extract complete log entries for a given message, or |
| 34049 | all mail for a given user, or for a given host, for example. The input files |
| 34050 | can be in Exim log format or syslog format. If a matching log line is not |
| 34051 | associated with a specific message, it is included in exigrep's output without |
| 34052 | any additional lines. The usage is: |
| 34053 | |
| 34054 | exigrep [-t<n>] [-I] [-l] [-M] [-v] <pattern> [<log file>] ... |
| 34055 | |
| 34056 | If no log file names are given on the command line, the standard input is read. |
| 34057 | |
| 34058 | The -t argument specifies a number of seconds. It adds an additional condition |
| 34059 | for message selection. Messages that are complete are shown only if they spent |
| 34060 | more than <n> seconds on the queue. |
| 34061 | |
| 34062 | By default, exigrep does case-insensitive matching. The -I option makes it |
| 34063 | case-sensitive. This may give a performance improvement when searching large |
| 34064 | log files. Without -I, the Perl pattern matches use Perl's "/i" option; with -I |
| 34065 | they do not. In both cases it is possible to change the case sensitivity within |
| 34066 | the pattern by using "(?i)" or "(?-i)". |
| 34067 | |
| 34068 | The -l option means "literal", that is, treat all characters in the pattern as |
| 34069 | standing for themselves. Otherwise the pattern must be a Perl regular |
| 34070 | expression. |
| 34071 | |
| 34072 | The -v option inverts the matching condition. That is, a line is selected if it |
| 34073 | does not match the pattern. |
| 34074 | |
| 34075 | The -M options means "related messages". exigrep will show messages that are |
| 34076 | generated as a result/response to a message that exigrep matched normally. |
| 34077 | |
| 34078 | Example of -M: user_a sends a message to user_b, which generates a bounce back |
| 34079 | to user_b. If exigrep is used to search for "user_a", only the first message |
| 34080 | will be displayed. But if exigrep is used to search for "user_b", the first and |
| 34081 | the second (bounce) message will be displayed. Using -M with exigrep when |
| 34082 | searching for "user_a" will show both messages since the bounce is "related" to |
| 34083 | or a "result" of the first message that was found by the search term. |
| 34084 | |
| 34085 | If the location of a zcat command is known from the definition of ZCAT_COMMAND |
| 34086 | in Local/Makefile, exigrep automatically passes any file whose name ends in |
| 34087 | COMPRESS_SUFFIX through zcat as it searches it. If the ZCAT_COMMAND is not |
| 34088 | executable, exigrep tries to use autodetection of some well known compression |
| 34089 | extensions. |
| 34090 | |
| 34091 | |
| 34092 | 53.5 Selecting messages by various criteria (exipick) |
| 34093 | ----------------------------------------------------- |
| 34094 | |
| 34095 | John Jetmore's exipick utility is included in the Exim distribution. It lists |
| 34096 | messages from the queue according to a variety of criteria. For details of |
| 34097 | exipick's facilities, visit the web page at http://www.exim.org/eximwiki/ |
| 34098 | ToolExipickManPage or run exipick with the --help option. |
| 34099 | |
| 34100 | |
| 34101 | 53.6 Cycling log files (exicyclog) |
| 34102 | ---------------------------------- |
| 34103 | |
| 34104 | The exicyclog script can be used to cycle (rotate) mainlog and rejectlog files. |
| 34105 | This is not necessary if only syslog is being used, or if you are using log |
| 34106 | files with datestamps in their names (see section 52.3). Some operating systems |
| 34107 | have their own standard mechanisms for log cycling, and these can be used |
| 34108 | instead of exicyclog if preferred. There are two command line options for |
| 34109 | exicyclog: |
| 34110 | |
| 34111 | * -k <count> specifies the number of log files to keep, overriding the |
| 34112 | default that is set when Exim is built. The default default is 10. |
| 34113 | |
| 34114 | * -l <path> specifies the log file path, in the same format as Exim's |
| 34115 | log_file_path option (for example, "/var/log/exim_%slog"), again overriding |
| 34116 | the script's default, which is to find the setting from Exim's |
| 34117 | configuration. |
| 34118 | |
| 34119 | Each time exicyclog is run the file names get "shuffled down" by one. If the |
| 34120 | main log file name is mainlog (the default) then when exicyclog is run mainlog |
| 34121 | becomes mainlog.01, the previous mainlog.01 becomes mainlog.02 and so on, up to |
| 34122 | the limit that is set in the script or by the -k option. Log files whose |
| 34123 | numbers exceed the limit are discarded. Reject logs are handled similarly. |
| 34124 | |
| 34125 | If the limit is greater than 99, the script uses 3-digit numbers such as |
| 34126 | mainlog.001, mainlog.002, etc. If you change from a number less than 99 to one |
| 34127 | that is greater, or vice versa, you will have to fix the names of any existing |
| 34128 | log files. |
| 34129 | |
| 34130 | If no mainlog file exists, the script does nothing. Files that "drop off" the |
| 34131 | end are deleted. All files with numbers greater than 01 are compressed, using a |
| 34132 | compression command which is configured by the COMPRESS_COMMAND setting in |
| 34133 | Local/Makefile. It is usual to run exicyclog daily from a root crontab entry of |
| 34134 | the form |
| 34135 | |
| 34136 | 1 0 * * * su exim -c /usr/exim/bin/exicyclog |
| 34137 | |
| 34138 | assuming you have used the name "exim" for the Exim user. You can run exicyclog |
| 34139 | as root if you wish, but there is no need. |
| 34140 | |
| 34141 | |
| 34142 | 53.7 Mail statistics (eximstats) |
| 34143 | -------------------------------- |
| 34144 | |
| 34145 | A Perl script called eximstats is provided for extracting statistical |
| 34146 | information from log files. The output is either plain text, or HTML. Exim log |
| 34147 | files are also supported by the Lire system produced by the LogReport |
| 34148 | Foundation http://www.logreport.org. |
| 34149 | |
| 34150 | The eximstats script has been hacked about quite a bit over time. The latest |
| 34151 | version is the result of some extensive revision by Steve Campbell. A lot of |
| 34152 | information is given by default, but there are options for suppressing various |
| 34153 | parts of it. Following any options, the arguments to the script are a list of |
| 34154 | files, which should be main log files. For example: |
| 34155 | |
| 34156 | eximstats -nr /var/spool/exim/log/mainlog.01 |
| 34157 | |
| 34158 | By default, eximstats extracts information about the number and volume of |
| 34159 | messages received from or delivered to various hosts. The information is sorted |
| 34160 | both by message count and by volume, and the top fifty hosts in each category |
| 34161 | are listed on the standard output. Similar information, based on email |
| 34162 | addresses or domains instead of hosts can be requested by means of various |
| 34163 | options. For messages delivered and received locally, similar statistics are |
| 34164 | also produced per user. |
| 34165 | |
| 34166 | The output also includes total counts and statistics about delivery errors, and |
| 34167 | histograms showing the number of messages received and deliveries made in each |
| 34168 | hour of the day. A delivery with more than one address in its envelope (for |
| 34169 | example, an SMTP transaction with more than one RCPT command) is counted as a |
| 34170 | single delivery by eximstats. |
| 34171 | |
| 34172 | Though normally more deliveries than receipts are reported (as messages may |
| 34173 | have multiple recipients), it is possible for eximstats to report more messages |
| 34174 | received than delivered, even though the queue is empty at the start and end of |
| 34175 | the period in question. If an incoming message contains no valid recipients, no |
| 34176 | deliveries are recorded for it. A bounce message is handled as an entirely |
| 34177 | separate message. |
| 34178 | |
| 34179 | eximstats always outputs a grand total summary giving the volume and number of |
| 34180 | messages received and deliveries made, and the number of hosts involved in each |
| 34181 | case. It also outputs the number of messages that were delayed (that is, not |
| 34182 | completely delivered at the first attempt), and the number that had at least |
| 34183 | one address that failed. |
| 34184 | |
| 34185 | The remainder of the output is in sections that can be independently disabled |
| 34186 | or modified by various options. It consists of a summary of deliveries by |
| 34187 | transport, histograms of messages received and delivered per time interval |
| 34188 | (default per hour), information about the time messages spent on the queue, a |
| 34189 | list of relayed messages, lists of the top fifty sending hosts, local senders, |
| 34190 | destination hosts, and destination local users by count and by volume, and a |
| 34191 | list of delivery errors that occurred. |
| 34192 | |
| 34193 | The relay information lists messages that were actually relayed, that is, they |
| 34194 | came from a remote host and were directly delivered to some other remote host, |
| 34195 | without being processed (for example, for aliasing or forwarding) locally. |
| 34196 | |
| 34197 | There are quite a few options for eximstats to control exactly what it outputs. |
| 34198 | These are documented in the Perl script itself, and can be extracted by running |
| 34199 | the command perldoc on the script. For example: |
| 34200 | |
| 34201 | perldoc /usr/exim/bin/eximstats |
| 34202 | |
| 34203 | |
| 34204 | 53.8 Checking access policy (exim_checkaccess) |
| 34205 | ---------------------------------------------- |
| 34206 | |
| 34207 | The -bh command line argument allows you to run a fake SMTP session with |
| 34208 | debugging output, in order to check what Exim is doing when it is applying |
| 34209 | policy controls to incoming SMTP mail. However, not everybody is sufficiently |
| 34210 | familiar with the SMTP protocol to be able to make full use of -bh, and |
| 34211 | sometimes you just want to answer the question "Does this address have access?" |
| 34212 | without bothering with any further details. |
| 34213 | |
| 34214 | The exim_checkaccess utility is a "packaged" version of -bh. It takes two |
| 34215 | arguments, an IP address and an email address: |
| 34216 | |
| 34217 | exim_checkaccess 10.9.8.7 A.User@a.domain.example |
| 34218 | |
| 34219 | The utility runs a call to Exim with the -bh option, to test whether the given |
| 34220 | email address would be accepted in a RCPT command in a TCP/IP connection from |
| 34221 | the host with the given IP address. The output of the utility is either the |
| 34222 | word "accepted", or the SMTP error response, for example: |
| 34223 | |
| 34224 | Rejected: |
| 34225 | 550 Relay not permitted |
| 34226 | |
| 34227 | When running this test, the utility uses "<>" as the envelope sender address |
| 34228 | for the MAIL command, but you can change this by providing additional options. |
| 34229 | These are passed directly to the Exim command. For example, to specify that the |
| 34230 | test is to be run with the sender address himself@there.example you can use: |
| 34231 | |
| 34232 | exim_checkaccess 10.9.8.7 A.User@a.domain.example \ |
| 34233 | -f himself@there.example |
| 34234 | |
| 34235 | Note that these additional Exim command line items must be given after the two |
| 34236 | mandatory arguments. |
| 34237 | |
| 34238 | Because the exim_checkaccess uses -bh, it does not perform callouts while |
| 34239 | running its checks. You can run checks that include callouts by using -bhc, but |
| 34240 | this is not yet available in a "packaged" form. |
| 34241 | |
| 34242 | |
| 34243 | 53.9 Making DBM files (exim_dbmbuild) |
| 34244 | ------------------------------------- |
| 34245 | |
| 34246 | The exim_dbmbuild program reads an input file containing keys and data in the |
| 34247 | format used by the lsearch lookup (see section 9.3). It writes a DBM file using |
| 34248 | the lower-cased alias names as keys and the remainder of the information as |
| 34249 | data. The lower-casing can be prevented by calling the program with the -nolc |
| 34250 | option. |
| 34251 | |
| 34252 | A terminating zero is included as part of the key string. This is expected by |
| 34253 | the dbm lookup type. However, if the option -nozero is given, exim_dbmbuild |
| 34254 | creates files without terminating zeroes in either the key strings or the data |
| 34255 | strings. The dbmnz lookup type can be used with such files. |
| 34256 | |
| 34257 | The program requires two arguments: the name of the input file (which can be a |
| 34258 | single hyphen to indicate the standard input), and the name of the output file. |
| 34259 | It creates the output under a temporary name, and then renames it if all went |
| 34260 | well. |
| 34261 | |
| 34262 | If the native DB interface is in use (USE_DB is set in a compile-time |
| 34263 | configuration file - this is common in free versions of Unix) the two file |
| 34264 | names must be different, because in this mode the Berkeley DB functions create |
| 34265 | a single output file using exactly the name given. For example, |
| 34266 | |
| 34267 | exim_dbmbuild /etc/aliases /etc/aliases.db |
| 34268 | |
| 34269 | reads the system alias file and creates a DBM version of it in /etc/aliases.db. |
| 34270 | |
| 34271 | In systems that use the ndbm routines (mostly proprietary versions of Unix), |
| 34272 | two files are used, with the suffixes .dir and .pag. In this environment, the |
| 34273 | suffixes are added to the second argument of exim_dbmbuild, so it can be the |
| 34274 | same as the first. This is also the case when the Berkeley functions are used |
| 34275 | in compatibility mode (though this is not recommended), because in that case it |
| 34276 | adds a .db suffix to the file name. |
| 34277 | |
| 34278 | If a duplicate key is encountered, the program outputs a warning, and when it |
| 34279 | finishes, its return code is 1 rather than zero, unless the -noduperr option is |
| 34280 | used. By default, only the first of a set of duplicates is used - this makes it |
| 34281 | compatible with lsearch lookups. There is an option -lastdup which causes it to |
| 34282 | use the data for the last duplicate instead. There is also an option -nowarn, |
| 34283 | which stops it listing duplicate keys to stderr. For other errors, where it |
| 34284 | doesn't actually make a new file, the return code is 2. |
| 34285 | |
| 34286 | |
| 34287 | 53.10 Finding individual retry times (exinext) |
| 34288 | ---------------------------------------------- |
| 34289 | |
| 34290 | A utility called exinext (mostly a Perl script) provides the ability to fish |
| 34291 | specific information out of the retry database. Given a mail domain (or a |
| 34292 | complete address), it looks up the hosts for that domain, and outputs any retry |
| 34293 | information for the hosts or for the domain. At present, the retry information |
| 34294 | is obtained by running exim_dumpdb (see below) and post-processing the output. |
| 34295 | For example: |
| 34296 | |
| 34297 | $ exinext piglet@milne.fict.example |
| 34298 | kanga.milne.example:192.168.8.1 error 146: Connection refused |
| 34299 | first failed: 21-Feb-1996 14:57:34 |
| 34300 | last tried: 21-Feb-1996 14:57:34 |
| 34301 | next try at: 21-Feb-1996 15:02:34 |
| 34302 | roo.milne.example:192.168.8.3 error 146: Connection refused |
| 34303 | first failed: 20-Jan-1996 13:12:08 |
| 34304 | last tried: 21-Feb-1996 11:42:03 |
| 34305 | next try at: 21-Feb-1996 19:42:03 |
| 34306 | past final cutoff time |
| 34307 | |
| 34308 | You can also give exinext a local part, without a domain, and it will give any |
| 34309 | retry information for that local part in your default domain. A message id can |
| 34310 | be used to obtain retry information pertaining to a specific message. This |
| 34311 | exists only when an attempt to deliver a message to a remote host suffers a |
| 34312 | message-specific error (see section 48.2). exinext is not particularly |
| 34313 | efficient, but then it is not expected to be run very often. |
| 34314 | |
| 34315 | The exinext utility calls Exim to find out information such as the location of |
| 34316 | the spool directory. The utility has -C and -D options, which are passed on to |
| 34317 | the exim commands. The first specifies an alternate Exim configuration file, |
| 34318 | and the second sets macros for use within the configuration file. These |
| 34319 | features are mainly to help in testing, but might also be useful in |
| 34320 | environments where more than one configuration file is in use. |
| 34321 | |
| 34322 | |
| 34323 | 53.11 Hints database maintenance |
| 34324 | -------------------------------- |
| 34325 | |
| 34326 | Three utility programs are provided for maintaining the DBM files that Exim |
| 34327 | uses to contain its delivery hint information. Each program requires two |
| 34328 | arguments. The first specifies the name of Exim's spool directory, and the |
| 34329 | second is the name of the database it is to operate on. These are as follows: |
| 34330 | |
| 34331 | * retry: the database of retry information |
| 34332 | |
| 34333 | * wait-<transport name>: databases of information about messages waiting for |
| 34334 | remote hosts |
| 34335 | |
| 34336 | * callout: the callout cache |
| 34337 | |
| 34338 | * ratelimit: the data for implementing the ratelimit ACL condition |
| 34339 | |
| 34340 | * misc: other hints data |
| 34341 | |
| 34342 | The misc database is used for |
| 34343 | |
| 34344 | * Serializing ETRN runs (when smtp_etrn_serialize is set) |
| 34345 | |
| 34346 | * Serializing delivery to a specific host (when serialize_hosts is set in an |
| 34347 | smtp transport) |
| 34348 | |
| 34349 | * Limiting the concurrency of specific transports (when max_parallel is set |
| 34350 | in a transport) |
| 34351 | |
| 34352 | |
| 34353 | 53.12 exim_dumpdb |
| 34354 | ----------------- |
| 34355 | |
| 34356 | The entire contents of a database are written to the standard output by the |
| 34357 | exim_dumpdb program, which has no options or arguments other than the spool and |
| 34358 | database names. For example, to dump the retry database: |
| 34359 | |
| 34360 | exim_dumpdb /var/spool/exim retry |
| 34361 | |
| 34362 | Two lines of output are produced for each entry: |
| 34363 | |
| 34364 | T:mail.ref.example:192.168.242.242 146 77 Connection refused |
| 34365 | 31-Oct-1995 12:00:12 02-Nov-1995 12:21:39 02-Nov-1995 20:21:39 * |
| 34366 | |
| 34367 | The first item on the first line is the key of the record. It starts with one |
| 34368 | of the letters R, or T, depending on whether it refers to a routing or |
| 34369 | transport retry. For a local delivery, the next part is the local address; for |
| 34370 | a remote delivery it is the name of the remote host, followed by its failing IP |
| 34371 | address (unless retry_include_ip_address is set false on the smtp transport). |
| 34372 | If the remote port is not the standard one (port 25), it is added to the IP |
| 34373 | address. Then there follows an error code, an additional error code, and a |
| 34374 | textual description of the error. |
| 34375 | |
| 34376 | The three times on the second line are the time of first failure, the time of |
| 34377 | the last delivery attempt, and the computed time for the next attempt. The line |
| 34378 | ends with an asterisk if the cutoff time for the last retry rule has been |
| 34379 | exceeded. |
| 34380 | |
| 34381 | Each output line from exim_dumpdb for the wait-xxx databases consists of a host |
| 34382 | name followed by a list of ids for messages that are or were waiting to be |
| 34383 | delivered to that host. If there are a very large number for any one host, |
| 34384 | continuation records, with a sequence number added to the host name, may be |
| 34385 | seen. The data in these records is often out of date, because a message may be |
| 34386 | routed to several alternative hosts, and Exim makes no effort to keep |
| 34387 | cross-references. |
| 34388 | |
| 34389 | |
| 34390 | 53.13 exim_tidydb |
| 34391 | ----------------- |
| 34392 | |
| 34393 | The exim_tidydb utility program is used to tidy up the contents of a hints |
| 34394 | database. If run with no options, it removes all records that are more than 30 |
| 34395 | days old. The age is calculated from the date and time that the record was last |
| 34396 | updated. Note that, in the case of the retry database, it is not the time since |
| 34397 | the first delivery failure. Information about a host that has been down for |
| 34398 | more than 30 days will remain in the database, provided that the record is |
| 34399 | updated sufficiently often. |
| 34400 | |
| 34401 | The cutoff date can be altered by means of the -t option, which must be |
| 34402 | followed by a time. For example, to remove all records older than a week from |
| 34403 | the retry database: |
| 34404 | |
| 34405 | exim_tidydb -t 7d /var/spool/exim retry |
| 34406 | |
| 34407 | Both the wait-xxx and retry databases contain items that involve message ids. |
| 34408 | In the former these appear as data in records keyed by host - they were |
| 34409 | messages that were waiting for that host - and in the latter they are the keys |
| 34410 | for retry information for messages that have suffered certain types of error. |
| 34411 | When exim_tidydb is run, a check is made to ensure that message ids in database |
| 34412 | records are those of messages that are still on the queue. Message ids for |
| 34413 | messages that no longer exist are removed from wait-xxx records, and if this |
| 34414 | leaves any records empty, they are deleted. For the retry database, records |
| 34415 | whose keys are non-existent message ids are removed. The exim_tidydb utility |
| 34416 | outputs comments on the standard output whenever it removes information from |
| 34417 | the database. |
| 34418 | |
| 34419 | Certain records are automatically removed by Exim when they are no longer |
| 34420 | needed, but others are not. For example, if all the MX hosts for a domain are |
| 34421 | down, a retry record is created for each one. If the primary MX host comes back |
| 34422 | first, its record is removed when Exim successfully delivers to it, but the |
| 34423 | records for the others remain because Exim has not tried to use those hosts. |
| 34424 | |
| 34425 | It is important, therefore, to run exim_tidydb periodically on all the hints |
| 34426 | databases. You should do this at a quiet time of day, because it requires a |
| 34427 | database to be locked (and therefore inaccessible to Exim) while it does its |
| 34428 | work. Removing records from a DBM file does not normally make the file smaller, |
| 34429 | but all the common DBM libraries are able to re-use the space that is released. |
| 34430 | After an initial phase of increasing in size, the databases normally reach a |
| 34431 | point at which they no longer get any bigger, as long as they are regularly |
| 34432 | tidied. |
| 34433 | |
| 34434 | Warning: If you never run exim_tidydb, the space used by the hints databases is |
| 34435 | likely to keep on increasing. |
| 34436 | |
| 34437 | |
| 34438 | 53.14 exim_fixdb |
| 34439 | ---------------- |
| 34440 | |
| 34441 | The exim_fixdb program is a utility for interactively modifying databases. Its |
| 34442 | main use is for testing Exim, but it might also be occasionally useful for |
| 34443 | getting round problems in a live system. It has no options, and its interface |
| 34444 | is somewhat crude. On entry, it prompts for input with a right angle-bracket. A |
| 34445 | key of a database record can then be entered, and the data for that record is |
| 34446 | displayed. |
| 34447 | |
| 34448 | If "d" is typed at the next prompt, the entire record is deleted. For all |
| 34449 | except the retry database, that is the only operation that can be carried out. |
| 34450 | For the retry database, each field is output preceded by a number, and data for |
| 34451 | individual fields can be changed by typing the field number followed by new |
| 34452 | data, for example: |
| 34453 | |
| 34454 | > 4 951102:1000 |
| 34455 | |
| 34456 | resets the time of the next delivery attempt. Time values are given as a |
| 34457 | sequence of digit pairs for year, month, day, hour, and minute. Colons can be |
| 34458 | used as optional separators. |
| 34459 | |
| 34460 | |
| 34461 | 53.15 Mailbox maintenance (exim_lock) |
| 34462 | ------------------------------------- |
| 34463 | |
| 34464 | The exim_lock utility locks a mailbox file using the same algorithm as Exim. |
| 34465 | For a discussion of locking issues, see section 26.3. Exim_lock can be used to |
| 34466 | prevent any modification of a mailbox by Exim or a user agent while |
| 34467 | investigating a problem. The utility requires the name of the file as its first |
| 34468 | argument. If the locking is successful, the second argument is run as a command |
| 34469 | (using C's system() function); if there is no second argument, the value of the |
| 34470 | SHELL environment variable is used; if this is unset or empty, /bin/sh is run. |
| 34471 | When the command finishes, the mailbox is unlocked and the utility ends. The |
| 34472 | following options are available: |
| 34473 | |
| 34474 | -fcntl |
| 34475 | |
| 34476 | Use fcntl() locking on the open mailbox. |
| 34477 | |
| 34478 | -flock |
| 34479 | |
| 34480 | Use flock() locking on the open mailbox, provided the operating system |
| 34481 | supports it. |
| 34482 | |
| 34483 | -interval |
| 34484 | |
| 34485 | This must be followed by a number, which is a number of seconds; it sets |
| 34486 | the interval to sleep between retries (default 3). |
| 34487 | |
| 34488 | -lockfile |
| 34489 | |
| 34490 | Create a lock file before opening the mailbox. |
| 34491 | |
| 34492 | -mbx |
| 34493 | |
| 34494 | Lock the mailbox using MBX rules. |
| 34495 | |
| 34496 | -q |
| 34497 | |
| 34498 | Suppress verification output. |
| 34499 | |
| 34500 | -retries |
| 34501 | |
| 34502 | This must be followed by a number; it sets the number of times to try to |
| 34503 | get the lock (default 10). |
| 34504 | |
| 34505 | -restore_time |
| 34506 | |
| 34507 | This option causes exim_lock to restore the modified and read times to the |
| 34508 | locked file before exiting. This allows you to access a locked mailbox (for |
| 34509 | example, to take a backup copy) without disturbing the times that the user |
| 34510 | subsequently sees. |
| 34511 | |
| 34512 | -timeout |
| 34513 | |
| 34514 | This must be followed by a number, which is a number of seconds; it sets a |
| 34515 | timeout to be used with a blocking fcntl() lock. If it is not set (the |
| 34516 | default), a non-blocking call is used. |
| 34517 | |
| 34518 | -v |
| 34519 | |
| 34520 | Generate verbose output. |
| 34521 | |
| 34522 | If none of -fcntl, -flock, -lockfile or -mbx are given, the default is to |
| 34523 | create a lock file and also to use fcntl() locking on the mailbox, which is the |
| 34524 | same as Exim's default. The use of -flock or -fcntl requires that the file be |
| 34525 | writeable; the use of -lockfile requires that the directory containing the file |
| 34526 | be writeable. Locking by lock file does not last for ever; Exim assumes that a |
| 34527 | lock file is expired if it is more than 30 minutes old. |
| 34528 | |
| 34529 | The -mbx option can be used with either or both of -fcntl or -flock. It assumes |
| 34530 | -fcntl by default. MBX locking causes a shared lock to be taken out on the open |
| 34531 | mailbox, and an exclusive lock on the file /tmp/.n.m where n and m are the |
| 34532 | device number and inode number of the mailbox file. When the locking is |
| 34533 | released, if an exclusive lock can be obtained for the mailbox, the file in / |
| 34534 | tmp is deleted. |
| 34535 | |
| 34536 | The default output contains verification of the locking that takes place. The |
| 34537 | -v option causes some additional information to be given. The -q option |
| 34538 | suppresses all output except error messages. |
| 34539 | |
| 34540 | A command such as |
| 34541 | |
| 34542 | exim_lock /var/spool/mail/spqr |
| 34543 | |
| 34544 | runs an interactive shell while the file is locked, whereas |
| 34545 | |
| 34546 | exim_lock -q /var/spool/mail/spqr <<End |
| 34547 | <some commands> |
| 34548 | End |
| 34549 | |
| 34550 | runs a specific non-interactive sequence of commands while the file is locked, |
| 34551 | suppressing all verification output. A single command can be run by a command |
| 34552 | such as |
| 34553 | |
| 34554 | exim_lock -q /var/spool/mail/spqr \ |
| 34555 | "cp /var/spool/mail/spqr /some/where" |
| 34556 | |
| 34557 | Note that if a command is supplied, it must be entirely contained within the |
| 34558 | second argument - hence the quotes. |
| 34559 | |
| 34560 | |
| 34561 | |
| 34562 | =============================================================================== |
| 34563 | 54. THE EXIM MONITOR |
| 34564 | |
| 34565 | The Exim monitor is an application which displays in an X window information |
| 34566 | about the state of Exim's queue and what Exim is doing. An admin user can |
| 34567 | perform certain operations on messages from this GUI interface; however all |
| 34568 | such facilities are also available from the command line, and indeed, the |
| 34569 | monitor itself makes use of the command line to perform any actions requested. |
| 34570 | |
| 34571 | |
| 34572 | 54.1 Running the monitor |
| 34573 | ------------------------ |
| 34574 | |
| 34575 | The monitor is started by running the script called eximon. This is a shell |
| 34576 | script that sets up a number of environment variables, and then runs the binary |
| 34577 | called eximon.bin. The default appearance of the monitor window can be changed |
| 34578 | by editing the Local/eximon.conf file created by editing exim_monitor/EDITME. |
| 34579 | Comments in that file describe what the various parameters are for. |
| 34580 | |
| 34581 | The parameters that get built into the eximon script can be overridden for a |
| 34582 | particular invocation by setting up environment variables of the same names, |
| 34583 | preceded by "EXIMON_". For example, a shell command such as |
| 34584 | |
| 34585 | EXIMON_LOG_DEPTH=400 eximon |
| 34586 | |
| 34587 | (in a Bourne-compatible shell) runs eximon with an overriding setting of the |
| 34588 | LOG_DEPTH parameter. If EXIMON_LOG_FILE_PATH is set in the environment, it |
| 34589 | overrides the Exim log file configuration. This makes it possible to have |
| 34590 | eximon tailing log data that is written to syslog, provided that MAIL.INFO |
| 34591 | syslog messages are routed to a file on the local host. |
| 34592 | |
| 34593 | X resources can be used to change the appearance of the window in the normal |
| 34594 | way. For example, a resource setting of the form |
| 34595 | |
| 34596 | Eximon*background: gray94 |
| 34597 | |
| 34598 | changes the colour of the background to light grey rather than white. The |
| 34599 | stripcharts are drawn with both the data lines and the reference lines in |
| 34600 | black. This means that the reference lines are not visible when on top of the |
| 34601 | data. However, their colour can be changed by setting a resource called |
| 34602 | "highlight" (an odd name, but that's what the Athena stripchart widget uses). |
| 34603 | For example, if your X server is running Unix, you could set up lighter |
| 34604 | reference lines in the stripcharts by obeying |
| 34605 | |
| 34606 | xrdb -merge <<End |
| 34607 | Eximon*highlight: gray |
| 34608 | End |
| 34609 | |
| 34610 | In order to see the contents of messages on the queue, and to operate on them, |
| 34611 | eximon must either be run as root or by an admin user. |
| 34612 | |
| 34613 | The command-line parameters of eximon are passed to eximon.bin and may contain |
| 34614 | X11 resource parameters interpreted by the X11 library. In addition, if the |
| 34615 | first parameter starts with the string "gdb" then it is removed and the binary |
| 34616 | is invoked under gdb (the parameter is used as the gdb command-name, so |
| 34617 | versioned variants of gdb can be invoked). |
| 34618 | |
| 34619 | The monitor's window is divided into three parts. The first contains one or |
| 34620 | more stripcharts and two action buttons, the second contains a "tail" of the |
| 34621 | main log file, and the third is a display of the queue of messages awaiting |
| 34622 | delivery, with two more action buttons. The following sections describe these |
| 34623 | different parts of the display. |
| 34624 | |
| 34625 | |
| 34626 | 54.2 The stripcharts |
| 34627 | -------------------- |
| 34628 | |
| 34629 | The first stripchart is always a count of messages on the queue. Its name can |
| 34630 | be configured by setting QUEUE_STRIPCHART_NAME in the Local/eximon.conf file. |
| 34631 | The remaining stripcharts are defined in the configuration script by regular |
| 34632 | expression matches on log file entries, making it possible to display, for |
| 34633 | example, counts of messages delivered to certain hosts or using certain |
| 34634 | transports. The supplied defaults display counts of received and delivered |
| 34635 | messages, and of local and SMTP deliveries. The default period between |
| 34636 | stripchart updates is one minute; this can be adjusted by a parameter in the |
| 34637 | Local/eximon.conf file. |
| 34638 | |
| 34639 | The stripchart displays rescale themselves automatically as the value they are |
| 34640 | displaying changes. There are always 10 horizontal lines in each chart; the |
| 34641 | title string indicates the value of each division when it is greater than one. |
| 34642 | For example, "x2" means that each division represents a value of 2. |
| 34643 | |
| 34644 | It is also possible to have a stripchart which shows the percentage fullness of |
| 34645 | a particular disk partition, which is useful when local deliveries are confined |
| 34646 | to a single partition. |
| 34647 | |
| 34648 | This relies on the availability of the statvfs() function or equivalent in the |
| 34649 | operating system. Most, but not all versions of Unix that support Exim have |
| 34650 | this. For this particular stripchart, the top of the chart always represents |
| 34651 | 100%, and the scale is given as "x10%". This chart is configured by setting |
| 34652 | SIZE_STRIPCHART and (optionally) SIZE_STRIPCHART_NAME in the Local/eximon.conf |
| 34653 | file. |
| 34654 | |
| 34655 | |
| 34656 | 54.3 Main action buttons |
| 34657 | ------------------------ |
| 34658 | |
| 34659 | Below the stripcharts there is an action button for quitting the monitor. Next |
| 34660 | to this is another button marked "Size". They are placed here so that shrinking |
| 34661 | the window to its default minimum size leaves just the queue count stripchart |
| 34662 | and these two buttons visible. Pressing the "Size" button causes the window to |
| 34663 | expand to its maximum size, unless it is already at the maximum, in which case |
| 34664 | it is reduced to its minimum. |
| 34665 | |
| 34666 | When expanding to the maximum, if the window cannot be fully seen where it |
| 34667 | currently is, it is moved back to where it was the last time it was at full |
| 34668 | size. When it is expanding from its minimum size, the old position is |
| 34669 | remembered, and next time it is reduced to the minimum it is moved back there. |
| 34670 | |
| 34671 | The idea is that you can keep a reduced window just showing one or two |
| 34672 | stripcharts at a convenient place on your screen, easily expand it to show the |
| 34673 | full window when required, and just as easily put it back to what it was. The |
| 34674 | idea is copied from what the twm window manager does for its f.fullzoom action. |
| 34675 | The minimum size of the window can be changed by setting the MIN_HEIGHT and |
| 34676 | MIN_WIDTH values in Local/eximon.conf. |
| 34677 | |
| 34678 | Normally, the monitor starts up with the window at its full size, but it can be |
| 34679 | built so that it starts up with the window at its smallest size, by setting |
| 34680 | START_SMALL=yes in Local/eximon.conf. |
| 34681 | |
| 34682 | |
| 34683 | 54.4 The log display |
| 34684 | -------------------- |
| 34685 | |
| 34686 | The second section of the window is an area in which a display of the tail of |
| 34687 | the main log is maintained. To save space on the screen, the timestamp on each |
| 34688 | log line is shortened by removing the date and, if log_timezone is set, the |
| 34689 | timezone. The log tail is not available when the only destination for logging |
| 34690 | data is syslog, unless the syslog lines are routed to a local file whose name |
| 34691 | is passed to eximon via the EXIMON_LOG_FILE_PATH environment variable. |
| 34692 | |
| 34693 | The log sub-window has a scroll bar at its lefthand side which can be used to |
| 34694 | move back to look at earlier text, and the up and down arrow keys also have a |
| 34695 | scrolling effect. The amount of log that is kept depends on the setting of |
| 34696 | LOG_BUFFER in Local/eximon.conf, which specifies the amount of memory to use. |
| 34697 | When this is full, the earlier 50% of data is discarded - this is much more |
| 34698 | efficient than throwing it away line by line. The sub-window also has a |
| 34699 | horizontal scroll bar for accessing the ends of long log lines. This is the |
| 34700 | only means of horizontal scrolling; the right and left arrow keys are not |
| 34701 | available. Text can be cut from this part of the window using the mouse in the |
| 34702 | normal way. The size of this subwindow is controlled by parameters in the |
| 34703 | configuration file Local/eximon.conf. |
| 34704 | |
| 34705 | Searches of the text in the log window can be carried out by means of the ^R |
| 34706 | and ^S keystrokes, which default to a reverse and a forward search, |
| 34707 | respectively. The search covers only the text that is displayed in the window. |
| 34708 | It cannot go further back up the log. |
| 34709 | |
| 34710 | The point from which the search starts is indicated by a caret marker. This is |
| 34711 | normally at the end of the text in the window, but can be positioned explicitly |
| 34712 | by pointing and clicking with the left mouse button, and is moved automatically |
| 34713 | by a successful search. If new text arrives in the window when it is scrolled |
| 34714 | back, the caret remains where it is, but if the window is not scrolled back, |
| 34715 | the caret is moved to the end of the new text. |
| 34716 | |
| 34717 | Pressing ^R or ^S pops up a window into which the search text can be typed. |
| 34718 | There are buttons for selecting forward or reverse searching, for carrying out |
| 34719 | the search, and for cancelling. If the "Search" button is pressed, the search |
| 34720 | happens and the window remains so that further searches can be done. If the |
| 34721 | "Return" key is pressed, a single search is done and the window is closed. If ^ |
| 34722 | C is typed the search is cancelled. |
| 34723 | |
| 34724 | The searching facility is implemented using the facilities of the Athena text |
| 34725 | widget. By default this pops up a window containing both "search" and "replace" |
| 34726 | options. In order to suppress the unwanted "replace" portion for eximon, a |
| 34727 | modified version of the TextPop widget is distributed with Exim. However, the |
| 34728 | linkers in BSDI and HP-UX seem unable to handle an externally provided version |
| 34729 | of TextPop when the remaining parts of the text widget come from the standard |
| 34730 | libraries. The compile-time option EXIMON_TEXTPOP can be unset to cut out the |
| 34731 | modified TextPop, making it possible to build Eximon on these systems, at the |
| 34732 | expense of having unwanted items in the search popup window. |
| 34733 | |
| 34734 | |
| 34735 | 54.5 The queue display |
| 34736 | ---------------------- |
| 34737 | |
| 34738 | The bottom section of the monitor window contains a list of all messages that |
| 34739 | are on the queue, which includes those currently being received or delivered, |
| 34740 | as well as those awaiting delivery. The size of this subwindow is controlled by |
| 34741 | parameters in the configuration file Local/eximon.conf, and the frequency at |
| 34742 | which it is updated is controlled by another parameter in the same file - the |
| 34743 | default is 5 minutes, since queue scans can be quite expensive. However, there |
| 34744 | is an "Update" action button just above the display which can be used to force |
| 34745 | an update of the queue display at any time. |
| 34746 | |
| 34747 | When a host is down for some time, a lot of pending mail can build up for it, |
| 34748 | and this can make it hard to deal with other messages on the queue. To help |
| 34749 | with this situation there is a button next to "Update" called "Hide". If |
| 34750 | pressed, a dialogue box called "Hide addresses ending with" is put up. If you |
| 34751 | type anything in here and press "Return", the text is added to a chain of such |
| 34752 | texts, and if every undelivered address in a message matches at least one of |
| 34753 | the texts, the message is not displayed. |
| 34754 | |
| 34755 | If there is an address that does not match any of the texts, all the addresses |
| 34756 | are displayed as normal. The matching happens on the ends of addresses so, for |
| 34757 | example, cam.ac.uk specifies all addresses in Cambridge, while |
| 34758 | xxx@foo.com.example specifies just one specific address. When any hiding has |
| 34759 | been set up, a button called "Unhide" is displayed. If pressed, it cancels all |
| 34760 | hiding. Also, to ensure that hidden messages do not get forgotten, a hide |
| 34761 | request is automatically cancelled after one hour. |
| 34762 | |
| 34763 | While the dialogue box is displayed, you can't press any buttons or do anything |
| 34764 | else to the monitor window. For this reason, if you want to cut text from the |
| 34765 | queue display to use in the dialogue box, you have to do the cutting before |
| 34766 | pressing the "Hide" button. |
| 34767 | |
| 34768 | The queue display contains, for each unhidden queued message, the length of |
| 34769 | time it has been on the queue, the size of the message, the message id, the |
| 34770 | message sender, and the first undelivered recipient, all on one line. If it is |
| 34771 | a bounce message, the sender is shown as "<>". If there is more than one |
| 34772 | recipient to which the message has not yet been delivered, subsequent ones are |
| 34773 | listed on additional lines, up to a maximum configured number, following which |
| 34774 | an ellipsis is displayed. Recipients that have already received the message are |
| 34775 | not shown. |
| 34776 | |
| 34777 | If a message is frozen, an asterisk is displayed at the left-hand side. |
| 34778 | |
| 34779 | The queue display has a vertical scroll bar, and can also be scrolled by means |
| 34780 | of the arrow keys. Text can be cut from it using the mouse in the normal way. |
| 34781 | The text searching facilities, as described above for the log window, are also |
| 34782 | available, but the caret is always moved to the end of the text when the queue |
| 34783 | display is updated. |
| 34784 | |
| 34785 | |
| 34786 | 54.6 The queue menu |
| 34787 | ------------------- |
| 34788 | |
| 34789 | If the shift key is held down and the left button is clicked when the mouse |
| 34790 | pointer is over the text for any message, an action menu pops up, and the first |
| 34791 | line of the queue display for the message is highlighted. This does not affect |
| 34792 | any selected text. |
| 34793 | |
| 34794 | If you want to use some other event for popping up the menu, you can set the |
| 34795 | MENU_EVENT parameter in Local/eximon.conf to change the default, or set |
| 34796 | EXIMON_MENU_EVENT in the environment before starting the monitor. The value set |
| 34797 | in this parameter is a standard X event description. For example, to run eximon |
| 34798 | using ctrl rather than shift you could use |
| 34799 | |
| 34800 | EXIMON_MENU_EVENT='Ctrl<Btn1Down>' eximon |
| 34801 | |
| 34802 | The title of the menu is the message id, and it contains entries which act as |
| 34803 | follows: |
| 34804 | |
| 34805 | * message log: The contents of the message log for the message are displayed |
| 34806 | in a new text window. |
| 34807 | |
| 34808 | * headers: Information from the spool file that contains the envelope |
| 34809 | information and headers is displayed in a new text window. See chapter 56 |
| 34810 | for a description of the format of spool files. |
| 34811 | |
| 34812 | * body: The contents of the spool file containing the body of the message are |
| 34813 | displayed in a new text window. There is a default limit of 20,000 bytes to |
| 34814 | the amount of data displayed. This can be changed by setting the BODY_MAX |
| 34815 | option at compile time, or the EXIMON_BODY_MAX option at run time. |
| 34816 | |
| 34817 | * deliver message: A call to Exim is made using the -M option to request |
| 34818 | delivery of the message. This causes an automatic thaw if the message is |
| 34819 | frozen. The -v option is also set, and the output from Exim is displayed in |
| 34820 | a new text window. The delivery is run in a separate process, to avoid |
| 34821 | holding up the monitor while the delivery proceeds. |
| 34822 | |
| 34823 | * freeze message: A call to Exim is made using the -Mf option to request that |
| 34824 | the message be frozen. |
| 34825 | |
| 34826 | * thaw message: A call to Exim is made using the -Mt option to request that |
| 34827 | the message be thawed. |
| 34828 | |
| 34829 | * give up on msg: A call to Exim is made using the -Mg option to request that |
| 34830 | Exim gives up trying to deliver the message. A bounce message is generated |
| 34831 | for any remaining undelivered addresses. |
| 34832 | |
| 34833 | * remove message: A call to Exim is made using the -Mrm option to request |
| 34834 | that the message be deleted from the system without generating a bounce |
| 34835 | message. |
| 34836 | |
| 34837 | * add recipient: A dialog box is displayed into which a recipient address can |
| 34838 | be typed. If the address is not qualified and the QUALIFY_DOMAIN parameter |
| 34839 | is set in Local/eximon.conf, the address is qualified with that domain. |
| 34840 | Otherwise it must be entered as a fully qualified address. Pressing RETURN |
| 34841 | causes a call to Exim to be made using the -Mar option to request that an |
| 34842 | additional recipient be added to the message, unless the entry box is |
| 34843 | empty, in which case no action is taken. |
| 34844 | |
| 34845 | * mark delivered: A dialog box is displayed into which a recipient address |
| 34846 | can be typed. If the address is not qualified and the QUALIFY_DOMAIN |
| 34847 | parameter is set in Local/eximon.conf, the address is qualified with that |
| 34848 | domain. Otherwise it must be entered as a fully qualified address. Pressing |
| 34849 | RETURN causes a call to Exim to be made using the -Mmd option to mark the |
| 34850 | given recipient address as already delivered, unless the entry box is |
| 34851 | empty, in which case no action is taken. |
| 34852 | |
| 34853 | * mark all delivered: A call to Exim is made using the -Mmad option to mark |
| 34854 | all recipient addresses as already delivered. |
| 34855 | |
| 34856 | * edit sender: A dialog box is displayed initialized with the current |
| 34857 | sender's address. Pressing RETURN causes a call to Exim to be made using |
| 34858 | the -Mes option to replace the sender address, unless the entry box is |
| 34859 | empty, in which case no action is taken. If you want to set an empty sender |
| 34860 | (as in bounce messages), you must specify it as "<>". Otherwise, if the |
| 34861 | address is not qualified and the QUALIFY_DOMAIN parameter is set in Local/ |
| 34862 | eximon.conf, the address is qualified with that domain. |
| 34863 | |
| 34864 | When a delivery is forced, a window showing the -v output is displayed. In |
| 34865 | other cases when a call to Exim is made, if there is any output from Exim (in |
| 34866 | particular, if the command fails) a window containing the command and the |
| 34867 | output is displayed. Otherwise, the results of the action are normally apparent |
| 34868 | from the log and queue displays. However, if you set ACTION_OUTPUT=yes in Local |
| 34869 | /eximon.conf, a window showing the Exim command is always opened, even if no |
| 34870 | output is generated. |
| 34871 | |
| 34872 | The queue display is automatically updated for actions such as freezing and |
| 34873 | thawing, unless ACTION_QUEUE_UPDATE=no has been set in Local/eximon.conf. In |
| 34874 | this case the "Update" button has to be used to force an update of the display |
| 34875 | after one of these actions. |
| 34876 | |
| 34877 | In any text window that is displayed as result of a menu action, the normal |
| 34878 | cut-and-paste facility is available, and searching can be carried out using ^R |
| 34879 | and ^S, as described above for the log tail window. |
| 34880 | |
| 34881 | |
| 34882 | |
| 34883 | =============================================================================== |
| 34884 | 55. SECURITY CONSIDERATIONS |
| 34885 | |
| 34886 | This chapter discusses a number of issues concerned with security, some of |
| 34887 | which are also covered in other parts of this manual. |
| 34888 | |
| 34889 | For reasons that this author does not understand, some people have promoted |
| 34890 | Exim as a "particularly secure" mailer. Perhaps it is because of the existence |
| 34891 | of this chapter in the documentation. However, the intent of the chapter is |
| 34892 | simply to describe the way Exim works in relation to certain security concerns, |
| 34893 | not to make any specific claims about the effectiveness of its security as |
| 34894 | compared with other MTAs. |
| 34895 | |
| 34896 | What follows is a description of the way Exim is supposed to be. Best efforts |
| 34897 | have been made to try to ensure that the code agrees with the theory, but an |
| 34898 | absence of bugs can never be guaranteed. Any that are reported will get fixed |
| 34899 | as soon as possible. |
| 34900 | |
| 34901 | |
| 34902 | 55.1 Building a more "hardened" Exim |
| 34903 | ------------------------------------ |
| 34904 | |
| 34905 | There are a number of build-time options that can be set in Local/Makefile to |
| 34906 | create Exim binaries that are "harder" to attack, in particular by a rogue Exim |
| 34907 | administrator who does not have the root password, or by someone who has |
| 34908 | penetrated the Exim (but not the root) account. These options are as follows: |
| 34909 | |
| 34910 | * ALT_CONFIG_PREFIX can be set to a string that is required to match the |
| 34911 | start of any file names used with the -C option. When it is set, these file |
| 34912 | names are also not allowed to contain the sequence "/../". (However, if the |
| 34913 | value of the -C option is identical to the value of CONFIGURE_FILE in Local |
| 34914 | /Makefile, Exim ignores -C and proceeds as usual.) There is no default |
| 34915 | setting for ALT_CONFIG_PREFIX. |
| 34916 | |
| 34917 | If the permitted configuration files are confined to a directory to which |
| 34918 | only root has access, this guards against someone who has broken into the |
| 34919 | Exim account from running a privileged Exim with an arbitrary configuration |
| 34920 | file, and using it to break into other accounts. |
| 34921 | |
| 34922 | * If a non-trusted configuration file (i.e. not the default configuration |
| 34923 | file or one which is trusted by virtue of being listed in the |
| 34924 | TRUSTED_CONFIG_LIST file) is specified with -C, or if macros are given with |
| 34925 | -D (but see the next item), then root privilege is retained only if the |
| 34926 | caller of Exim is root. This locks out the possibility of testing a |
| 34927 | configuration using -C right through message reception and delivery, even |
| 34928 | if the caller is root. The reception works, but by that time, Exim is |
| 34929 | running as the Exim user, so when it re-execs to regain privilege for the |
| 34930 | delivery, the use of -C causes privilege to be lost. However, root can test |
| 34931 | reception and delivery using two separate commands. |
| 34932 | |
| 34933 | * The WHITELIST_D_MACROS build option declares some macros to be safe to |
| 34934 | override with -D if the real uid is one of root, the Exim run-time user or |
| 34935 | the CONFIGURE_OWNER, if defined. The potential impact of this option is |
| 34936 | limited by requiring the run-time value supplied to -D to match a regex |
| 34937 | that errs on the restrictive side. Requiring build-time selection of safe |
| 34938 | macros is onerous but this option is intended solely as a transition |
| 34939 | mechanism to permit previously-working configurations to continue to work |
| 34940 | after release 4.73. |
| 34941 | |
| 34942 | * If DISABLE_D_OPTION is defined, the use of the -D command line option is |
| 34943 | disabled. |
| 34944 | |
| 34945 | * FIXED_NEVER_USERS can be set to a colon-separated list of users that are |
| 34946 | never to be used for any deliveries. This is like the never_users runtime |
| 34947 | option, but it cannot be overridden; the runtime option adds additional |
| 34948 | users to the list. The default setting is "root"; this prevents a non-root |
| 34949 | user who is permitted to modify the runtime file from using Exim as a way |
| 34950 | to get root. |
| 34951 | |
| 34952 | |
| 34953 | 55.2 Root privilege |
| 34954 | ------------------- |
| 34955 | |
| 34956 | The Exim binary is normally setuid to root, which means that it gains root |
| 34957 | privilege (runs as root) when it starts execution. In some special cases (for |
| 34958 | example, when the daemon is not in use and there are no local deliveries), it |
| 34959 | may be possible to run Exim setuid to some user other than root. This is |
| 34960 | discussed in the next section. However, in most installations, root privilege |
| 34961 | is required for two things: |
| 34962 | |
| 34963 | * To set up a socket connected to the standard SMTP port (25) when |
| 34964 | initialising the listening daemon. If Exim is run from inetd, this |
| 34965 | privileged action is not required. |
| 34966 | |
| 34967 | * To be able to change uid and gid in order to read users' .forward files and |
| 34968 | perform local deliveries as the receiving user or as specified in the |
| 34969 | configuration. |
| 34970 | |
| 34971 | It is not necessary to be root to do any of the other things Exim does, such as |
| 34972 | receiving messages and delivering them externally over SMTP, and it is |
| 34973 | obviously more secure if Exim does not run as root except when necessary. For |
| 34974 | this reason, a user and group for Exim to use must be defined in Local/Makefile |
| 34975 | . These are known as "the Exim user" and "the Exim group". Their values can be |
| 34976 | changed by the run time configuration, though this is not recommended. Often a |
| 34977 | user called exim is used, but some sites use mail or another user name |
| 34978 | altogether. |
| 34979 | |
| 34980 | Exim uses setuid() whenever it gives up root privilege. This is a permanent |
| 34981 | abdication; the process cannot regain root afterwards. Prior to release 4.00, |
| 34982 | seteuid() was used in some circumstances, but this is no longer the case. |
| 34983 | |
| 34984 | After a new Exim process has interpreted its command line options, it changes |
| 34985 | uid and gid in the following cases: |
| 34986 | |
| 34987 | * If the -C option is used to specify an alternate configuration file, or if |
| 34988 | the -D option is used to define macro values for the configuration, and the |
| 34989 | calling process is not running as root, the uid and gid are changed to |
| 34990 | those of the calling process. However, if DISABLE_D_OPTION is defined in |
| 34991 | Local/Makefile, the -D option may not be used at all. If WHITELIST_D_MACROS |
| 34992 | is defined in Local/Makefile, then some macro values can be supplied if the |
| 34993 | calling process is running as root, the Exim run-time user or |
| 34994 | CONFIGURE_OWNER, if defined. |
| 34995 | |
| 34996 | * If the expansion test option (-be) or one of the filter testing options ( |
| 34997 | -bf or -bF) are used, the uid and gid are changed to those of the calling |
| 34998 | process. |
| 34999 | |
| 35000 | * If the process is not a daemon process or a queue runner process or a |
| 35001 | delivery process or a process for testing address routing (started with -bt |
| 35002 | ), the uid and gid are changed to the Exim user and group. This means that |
| 35003 | Exim always runs under its own uid and gid when receiving messages. This |
| 35004 | also applies when testing address verification (the -bv option) and testing |
| 35005 | incoming message policy controls (the -bh option). |
| 35006 | |
| 35007 | * For a daemon, queue runner, delivery, or address testing process, the uid |
| 35008 | remains as root at this stage, but the gid is changed to the Exim group. |
| 35009 | |
| 35010 | The processes that initially retain root privilege behave as follows: |
| 35011 | |
| 35012 | * A daemon process changes the gid to the Exim group and the uid to the Exim |
| 35013 | user after setting up one or more listening sockets. The initgroups() |
| 35014 | function is called, so that if the Exim user is in any additional groups, |
| 35015 | they will be used during message reception. |
| 35016 | |
| 35017 | * A queue runner process retains root privilege throughout its execution. Its |
| 35018 | job is to fork a controlled sequence of delivery processes. |
| 35019 | |
| 35020 | * A delivery process retains root privilege throughout most of its execution, |
| 35021 | but any actual deliveries (that is, the transports themselves) are run in |
| 35022 | subprocesses which always change to a non-root uid and gid. For local |
| 35023 | deliveries this is typically the uid and gid of the owner of the mailbox; |
| 35024 | for remote deliveries, the Exim uid and gid are used. Once all the delivery |
| 35025 | subprocesses have been run, a delivery process changes to the Exim uid and |
| 35026 | gid while doing post-delivery tidying up such as updating the retry |
| 35027 | database and generating bounce and warning messages. |
| 35028 | |
| 35029 | While the recipient addresses in a message are being routed, the delivery |
| 35030 | process runs as root. However, if a user's filter file has to be processed, |
| 35031 | this is done in a subprocess that runs under the individual user's uid and |
| 35032 | gid. A system filter is run as root unless system_filter_user is set. |
| 35033 | |
| 35034 | * A process that is testing addresses (the -bt option) runs as root so that |
| 35035 | the routing is done in the same environment as a message delivery. |
| 35036 | |
| 35037 | |
| 35038 | 55.3 Running Exim without privilege |
| 35039 | ----------------------------------- |
| 35040 | |
| 35041 | Some installations like to run Exim in an unprivileged state for more of its |
| 35042 | operation, for added security. Support for this mode of operation is provided |
| 35043 | by the global option deliver_drop_privilege. When this is set, the uid and gid |
| 35044 | are changed to the Exim user and group at the start of a delivery process (and |
| 35045 | also queue runner and address testing processes). This means that address |
| 35046 | routing is no longer run as root, and the deliveries themselves cannot change |
| 35047 | to any other uid. |
| 35048 | |
| 35049 | Leaving the binary setuid to root, but setting deliver_drop_privilege means |
| 35050 | that the daemon can still be started in the usual way, and it can respond |
| 35051 | correctly to SIGHUP because the re-invocation regains root privilege. |
| 35052 | |
| 35053 | An alternative approach is to make Exim setuid to the Exim user and also setgid |
| 35054 | to the Exim group. If you do this, the daemon must be started from a root |
| 35055 | process. (Calling Exim from a root process makes it behave in the way it does |
| 35056 | when it is setuid root.) However, the daemon cannot restart itself after a |
| 35057 | SIGHUP signal because it cannot regain privilege. |
| 35058 | |
| 35059 | It is still useful to set deliver_drop_privilege in this case, because it stops |
| 35060 | Exim from trying to re-invoke itself to do a delivery after a message has been |
| 35061 | received. Such a re-invocation is a waste of resources because it has no |
| 35062 | effect. |
| 35063 | |
| 35064 | If restarting the daemon is not an issue (for example, if mua_wrapper is set, |
| 35065 | or inetd is being used instead of a daemon), having the binary setuid to the |
| 35066 | Exim user seems a clean approach, but there is one complication: |
| 35067 | |
| 35068 | In this style of operation, Exim is running with the real uid and gid set to |
| 35069 | those of the calling process, and the effective uid/gid set to Exim's values. |
| 35070 | Ideally, any association with the calling process' uid/gid should be dropped, |
| 35071 | that is, the real uid/gid should be reset to the effective values so as to |
| 35072 | discard any privileges that the caller may have. While some operating systems |
| 35073 | have a function that permits this action for a non-root effective uid, quite a |
| 35074 | number of them do not. Because of this lack of standardization, Exim does not |
| 35075 | address this problem at this time. |
| 35076 | |
| 35077 | For this reason, the recommended approach for "mostly unprivileged" running is |
| 35078 | to keep the Exim binary setuid to root, and to set deliver_drop_privilege. This |
| 35079 | also has the advantage of allowing a daemon to be used in the most |
| 35080 | straightforward way. |
| 35081 | |
| 35082 | If you configure Exim not to run delivery processes as root, there are a number |
| 35083 | of restrictions on what you can do: |
| 35084 | |
| 35085 | * You can deliver only as the Exim user/group. You should explicitly use the |
| 35086 | user and group options to override routers or local transports that |
| 35087 | normally deliver as the recipient. This makes sure that configurations that |
| 35088 | work in this mode function the same way in normal mode. Any implicit or |
| 35089 | explicit specification of another user causes an error. |
| 35090 | |
| 35091 | * Use of .forward files is severely restricted, such that it is usually not |
| 35092 | worthwhile to include them in the configuration. |
| 35093 | |
| 35094 | * Users who wish to use .forward would have to make their home directory and |
| 35095 | the file itself accessible to the Exim user. Pipe and append-to-file |
| 35096 | entries, and their equivalents in Exim filters, cannot be used. While they |
| 35097 | could be enabled in the Exim user's name, that would be insecure and not |
| 35098 | very useful. |
| 35099 | |
| 35100 | * Unless the local user mailboxes are all owned by the Exim user (possible in |
| 35101 | some POP3 or IMAP-only environments): |
| 35102 | |
| 35103 | 1. They must be owned by the Exim group and be writeable by that group. |
| 35104 | This implies you must set mode in the appendfile configuration, as well |
| 35105 | as the mode of the mailbox files themselves. |
| 35106 | |
| 35107 | 2. You must set no_check_owner, since most or all of the files will not be |
| 35108 | owned by the Exim user. |
| 35109 | |
| 35110 | 3. You must set file_must_exist, because Exim cannot set the owner |
| 35111 | correctly on a newly created mailbox when unprivileged. This also |
| 35112 | implies that new mailboxes need to be created manually. |
| 35113 | |
| 35114 | These restrictions severely restrict what can be done in local deliveries. |
| 35115 | However, there are no restrictions on remote deliveries. If you are running a |
| 35116 | gateway host that does no local deliveries, setting deliver_drop_privilege |
| 35117 | gives more security at essentially no cost. |
| 35118 | |
| 35119 | If you are using the mua_wrapper facility (see chapter 51), |
| 35120 | deliver_drop_privilege is forced to be true. |
| 35121 | |
| 35122 | |
| 35123 | 55.4 Delivering to local files |
| 35124 | ------------------------------ |
| 35125 | |
| 35126 | Full details of the checks applied by appendfile before it writes to a file are |
| 35127 | given in chapter 26. |
| 35128 | |
| 35129 | |
| 35130 | 55.5 Running local commands |
| 35131 | --------------------------- |
| 35132 | |
| 35133 | There are a number of ways in which an administrator can configure Exim to run |
| 35134 | commands based upon received, untrustworthy, data. Further, in some |
| 35135 | configurations a user who can control a .forward file can also arrange to run |
| 35136 | commands. Configuration to check includes, but is not limited to: |
| 35137 | |
| 35138 | * Use of use_shell in the pipe transport: various forms of shell command |
| 35139 | injection may be possible with this option present. It is dangerous and |
| 35140 | should be used only with considerable caution. Consider constraints which |
| 35141 | whitelist allowed characters in a variable which is to be used in a pipe |
| 35142 | transport that has use_shell enabled. |
| 35143 | |
| 35144 | * A number of options such as forbid_filter_run, forbid_filter_perl, |
| 35145 | forbid_filter_dlfunc and so forth which restrict facilities available to |
| 35146 | .forward files in a redirect router. If Exim is running on a central mail |
| 35147 | hub to which ordinary users do not have shell access, but home directories |
| 35148 | are NFS mounted (for instance) then administrators should review the list |
| 35149 | of these forbid options available, and should bear in mind that the options |
| 35150 | that may need forbidding can change as new features are added between |
| 35151 | releases. |
| 35152 | |
| 35153 | * The ${run...} expansion item does not use a shell by default, but |
| 35154 | administrators can configure use of /bin/sh as part of the command. Such |
| 35155 | invocations should be viewed with prejudicial suspicion. |
| 35156 | |
| 35157 | * Administrators who use embedded Perl are advised to explore how Perl's |
| 35158 | taint checking might apply to their usage. |
| 35159 | |
| 35160 | * Use of ${expand...} is somewhat analogous to shell's eval builtin and |
| 35161 | administrators are well advised to view its use with suspicion, in case |
| 35162 | (for instance) it allows a local-part to contain embedded Exim directives. |
| 35163 | |
| 35164 | * Use of ${match_local_part...} and friends becomes more dangerous if Exim |
| 35165 | was built with EXPAND_LISTMATCH_RHS defined: the second string in each can |
| 35166 | reference arbitrary lists and files, rather than just being a list of |
| 35167 | opaque strings. The EXPAND_LISTMATCH_RHS option was added and set false by |
| 35168 | default because of real-world security vulnerabilities caused by its use |
| 35169 | with untrustworthy data injected in, for SQL injection attacks. Consider |
| 35170 | the use of the inlisti expansion condition instead. |
| 35171 | |
| 35172 | |
| 35173 | 55.6 Trust in configuration data |
| 35174 | -------------------------------- |
| 35175 | |
| 35176 | If configuration data for Exim can come from untrustworthy sources, there are |
| 35177 | some issues to be aware of: |
| 35178 | |
| 35179 | * Use of ${expand...} may provide a path for shell injection attacks. |
| 35180 | |
| 35181 | * Letting untrusted data provide a regular expression is unwise. |
| 35182 | |
| 35183 | * Using ${match...} to apply a fixed regular expression against untrusted |
| 35184 | data may result in pathological behaviour within PCRE. Be aware of what |
| 35185 | "backtracking" means and consider options for being more strict with a |
| 35186 | regular expression. Avenues to explore include limiting what can match |
| 35187 | (avoiding "." when "[a-z0-9]" or other character class will do), use of |
| 35188 | atomic grouping and possessive quantifiers or just not using regular |
| 35189 | expressions against untrusted data. |
| 35190 | |
| 35191 | * It can be important to correctly use ${quote:...}, ${quote_local_part:...} |
| 35192 | and ${quote_<lookup-type>:...} expansion items to ensure that data is |
| 35193 | correctly constructed. |
| 35194 | |
| 35195 | * Some lookups might return multiple results, even though normal usage is |
| 35196 | only expected to yield one result. |
| 35197 | |
| 35198 | |
| 35199 | 55.7 IPv4 source routing |
| 35200 | ------------------------ |
| 35201 | |
| 35202 | Many operating systems suppress IP source-routed packets in the kernel, but |
| 35203 | some cannot be made to do this, so Exim does its own check. It logs incoming |
| 35204 | IPv4 source-routed TCP calls, and then drops them. Things are all different in |
| 35205 | IPv6. No special checking is currently done. |
| 35206 | |
| 35207 | |
| 35208 | 55.8 The VRFY, EXPN, and ETRN commands in SMTP |
| 35209 | ---------------------------------------------- |
| 35210 | |
| 35211 | Support for these SMTP commands is disabled by default. If required, they can |
| 35212 | be enabled by defining suitable ACLs. |
| 35213 | |
| 35214 | |
| 35215 | 55.9 Privileged users |
| 35216 | --------------------- |
| 35217 | |
| 35218 | Exim recognizes two sets of users with special privileges. Trusted users are |
| 35219 | able to submit new messages to Exim locally, but supply their own sender |
| 35220 | addresses and information about a sending host. For other users submitting |
| 35221 | local messages, Exim sets up the sender address from the uid, and doesn't |
| 35222 | permit a remote host to be specified. |
| 35223 | |
| 35224 | However, an untrusted user is permitted to use the -f command line option in |
| 35225 | the special form -f <> to indicate that a delivery failure for the message |
| 35226 | should not cause an error report. This affects the message's envelope, but it |
| 35227 | does not affect the Sender: header. Untrusted users may also be permitted to |
| 35228 | use specific forms of address with the -f option by setting the |
| 35229 | untrusted_set_sender option. |
| 35230 | |
| 35231 | Trusted users are used to run processes that receive mail messages from some |
| 35232 | other mail domain and pass them on to Exim for delivery either locally, or over |
| 35233 | the Internet. Exim trusts a caller that is running as root, as the Exim user, |
| 35234 | as any user listed in the trusted_users configuration option, or under any |
| 35235 | group listed in the trusted_groups option. |
| 35236 | |
| 35237 | Admin users are permitted to do things to the messages on Exim's queue. They |
| 35238 | can freeze or thaw messages, cause them to be returned to their senders, remove |
| 35239 | them entirely, or modify them in various ways. In addition, admin users can run |
| 35240 | the Exim monitor and see all the information it is capable of providing, which |
| 35241 | includes the contents of files on the spool. |
| 35242 | |
| 35243 | By default, the use of the -M and -q options to cause Exim to attempt delivery |
| 35244 | of messages on its queue is restricted to admin users. This restriction can be |
| 35245 | relaxed by setting the no_prod_requires_admin option. Similarly, the use of -bp |
| 35246 | (and its variants) to list the contents of the queue is also restricted to |
| 35247 | admin users. This restriction can be relaxed by setting |
| 35248 | no_queue_list_requires_admin. |
| 35249 | |
| 35250 | Exim recognizes an admin user if the calling process is running as root or as |
| 35251 | the Exim user or if any of the groups associated with the calling process is |
| 35252 | the Exim group. It is not necessary actually to be running under the Exim |
| 35253 | group. However, if admin users who are not root or the Exim user are to access |
| 35254 | the contents of files on the spool via the Exim monitor (which runs |
| 35255 | unprivileged), Exim must be built to allow group read access to its spool |
| 35256 | files. |
| 35257 | |
| 35258 | |
| 35259 | 55.10 Spool files |
| 35260 | ----------------- |
| 35261 | |
| 35262 | Exim's spool directory and everything it contains is owned by the Exim user and |
| 35263 | set to the Exim group. The mode for spool files is defined in the Local/ |
| 35264 | Makefile configuration file, and defaults to 0640. This means that any user who |
| 35265 | is a member of the Exim group can access these files. |
| 35266 | |
| 35267 | |
| 35268 | 55.11 Use of argv[0] |
| 35269 | -------------------- |
| 35270 | |
| 35271 | Exim examines the last component of argv[0], and if it matches one of a set of |
| 35272 | specific strings, Exim assumes certain options. For example, calling Exim with |
| 35273 | the last component of argv[0] set to "rsmtp" is exactly equivalent to calling |
| 35274 | it with the option -bS. There are no security implications in this. |
| 35275 | |
| 35276 | |
| 35277 | 55.12 Use of %f formatting |
| 35278 | -------------------------- |
| 35279 | |
| 35280 | The only use made of "%f" by Exim is in formatting load average values. These |
| 35281 | are actually stored in integer variables as 1000 times the load average. |
| 35282 | Consequently, their range is limited and so therefore is the length of the |
| 35283 | converted output. |
| 35284 | |
| 35285 | |
| 35286 | 55.13 Embedded Exim path |
| 35287 | ------------------------ |
| 35288 | |
| 35289 | Exim uses its own path name, which is embedded in the code, only when it needs |
| 35290 | to re-exec in order to regain root privilege. Therefore, it is not root when it |
| 35291 | does so. If some bug allowed the path to get overwritten, it would lead to an |
| 35292 | arbitrary program's being run as exim, not as root. |
| 35293 | |
| 35294 | |
| 35295 | 55.14 Dynamic module directory |
| 35296 | ------------------------------ |
| 35297 | |
| 35298 | Any dynamically loadable modules must be installed into the directory defined |
| 35299 | in "LOOKUP_MODULE_DIR" in Local/Makefile for Exim to permit loading it. |
| 35300 | |
| 35301 | |
| 35302 | 55.15 Use of sprintf() |
| 35303 | ---------------------- |
| 35304 | |
| 35305 | A large number of occurrences of "sprintf" in the code are actually calls to |
| 35306 | string_sprintf(), a function that returns the result in malloc'd store. The |
| 35307 | intermediate formatting is done into a large fixed buffer by a function that |
| 35308 | runs through the format string itself, and checks the length of each conversion |
| 35309 | before performing it, thus preventing buffer overruns. |
| 35310 | |
| 35311 | The remaining uses of sprintf() happen in controlled circumstances where the |
| 35312 | output buffer is known to be sufficiently long to contain the converted string. |
| 35313 | |
| 35314 | |
| 35315 | 55.16 Use of debug_printf() and log_write() |
| 35316 | ------------------------------------------- |
| 35317 | |
| 35318 | Arbitrary strings are passed to both these functions, but they do their |
| 35319 | formatting by calling the function string_vformat(), which runs through the |
| 35320 | format string itself, and checks the length of each conversion. |
| 35321 | |
| 35322 | |
| 35323 | 55.17 Use of strcat() and strcpy() |
| 35324 | ---------------------------------- |
| 35325 | |
| 35326 | These are used only in cases where the output buffer is known to be large |
| 35327 | enough to hold the result. |
| 35328 | |
| 35329 | |
| 35330 | |
| 35331 | =============================================================================== |
| 35332 | 56. FORMAT OF SPOOL FILES |
| 35333 | |
| 35334 | A message on Exim's queue consists of two files, whose names are the message id |
| 35335 | followed by -D and -H, respectively. The data portion of the message is kept in |
| 35336 | the -D file on its own. The message's envelope, status, and headers are all |
| 35337 | kept in the -H file, whose format is described in this chapter. Each of these |
| 35338 | two files contains the final component of its own name as its first line. This |
| 35339 | is insurance against disk crashes where the directory is lost but the files |
| 35340 | themselves are recoverable. |
| 35341 | |
| 35342 | Some people are tempted into editing -D files in order to modify messages. You |
| 35343 | need to be extremely careful if you do this; it is not recommended and you are |
| 35344 | on your own if you do it. Here are some of the pitfalls: |
| 35345 | |
| 35346 | * You must ensure that Exim does not try to deliver the message while you are |
| 35347 | fiddling with it. The safest way is to take out a write lock on the -D |
| 35348 | file, which is what Exim itself does, using fcntl(). If you update the file |
| 35349 | in place, the lock will be retained. If you write a new file and rename it, |
| 35350 | the lock will be lost at the instant of rename. |
| 35351 | |
| 35352 | * If you change the number of lines in the file, the value of $body_linecount |
| 35353 | , which is stored in the -H file, will be incorrect and can cause |
| 35354 | incomplete transmission of messages or undeliverable messages. |
| 35355 | |
| 35356 | * If the message is in MIME format, you must take care not to break it. |
| 35357 | |
| 35358 | * If the message is cryptographically signed, any change will invalidate the |
| 35359 | signature. |
| 35360 | |
| 35361 | All in all, modifying -D files is fraught with danger. |
| 35362 | |
| 35363 | Files whose names end with -J may also be seen in the input directory (or its |
| 35364 | subdirectories when split_spool_directory is set). These are journal files, |
| 35365 | used to record addresses to which the message has been delivered during the |
| 35366 | course of a delivery attempt. If there are still undelivered recipients at the |
| 35367 | end, the -H file is updated, and the -J file is deleted. If, however, there is |
| 35368 | some kind of crash (for example, a power outage) before this happens, the -J |
| 35369 | file remains in existence. When Exim next processes the message, it notices the |
| 35370 | -J file and uses it to update the -H file before starting the next delivery |
| 35371 | attempt. |
| 35372 | |
| 35373 | |
| 35374 | 56.1 Format of the -H file |
| 35375 | -------------------------- |
| 35376 | |
| 35377 | The second line of the -H file contains the login name for the uid of the |
| 35378 | process that called Exim to read the message, followed by the numerical uid and |
| 35379 | gid. For a locally generated message, this is normally the user who sent the |
| 35380 | message. For a message received over TCP/IP via the daemon, it is normally the |
| 35381 | Exim user. |
| 35382 | |
| 35383 | The third line of the file contains the address of the message's sender as |
| 35384 | transmitted in the envelope, contained in angle brackets. The sender address is |
| 35385 | empty for bounce messages. For incoming SMTP mail, the sender address is given |
| 35386 | in the MAIL command. For locally generated mail, the sender address is created |
| 35387 | by Exim from the login name of the current user and the configured |
| 35388 | qualify_domain. However, this can be overridden by the -f option or a leading |
| 35389 | "From " line if the caller is trusted, or if the supplied address is "<>" or an |
| 35390 | address that matches untrusted_set_senders. |
| 35391 | |
| 35392 | The fourth line contains two numbers. The first is the time that the message |
| 35393 | was received, in the conventional Unix form - the number of seconds since the |
| 35394 | start of the epoch. The second number is a count of the number of messages |
| 35395 | warning of delayed delivery that have been sent to the sender. |
| 35396 | |
| 35397 | There follow a number of lines starting with a hyphen. These can appear in any |
| 35398 | order, and are omitted when not relevant: |
| 35399 | |
| 35400 | -acl <number> <length> |
| 35401 | |
| 35402 | This item is obsolete, and is not generated from Exim release 4.61 onwards; |
| 35403 | -aclc and -aclm are used instead. However, -acl is still recognized, to |
| 35404 | provide backward compatibility. In the old format, a line of this form is |
| 35405 | present for every ACL variable that is not empty. The number identifies the |
| 35406 | variable; the acl_cx variables are numbered 0-9 and the acl_mx variables |
| 35407 | are numbered 10-19. The length is the length of the data string for the |
| 35408 | variable. The string itself starts at the beginning of the next line, and |
| 35409 | is followed by a newline character. It may contain internal newlines. |
| 35410 | |
| 35411 | -aclc <rest-of-name> <length> |
| 35412 | |
| 35413 | A line of this form is present for every ACL connection variable that is |
| 35414 | defined. Note that there is a space between -aclc and the rest of the name. |
| 35415 | The length is the length of the data string for the variable. The string |
| 35416 | itself starts at the beginning of the next line, and is followed by a |
| 35417 | newline character. It may contain internal newlines. |
| 35418 | |
| 35419 | -aclm <rest-of-name> <length> |
| 35420 | |
| 35421 | A line of this form is present for every ACL message variable that is |
| 35422 | defined. Note that there is a space between -aclm and the rest of the name. |
| 35423 | The length is the length of the data string for the variable. The string |
| 35424 | itself starts at the beginning of the next line, and is followed by a |
| 35425 | newline character. It may contain internal newlines. |
| 35426 | |
| 35427 | -active_hostname <hostname> |
| 35428 | |
| 35429 | This is present if, when the message was received over SMTP, the value of |
| 35430 | $smtp_active_hostname was different to the value of $primary_hostname. |
| 35431 | |
| 35432 | -allow_unqualified_recipient |
| 35433 | |
| 35434 | This is present if unqualified recipient addresses are permitted in header |
| 35435 | lines (to stop such addresses from being qualified if rewriting occurs at |
| 35436 | transport time). Local messages that were input using -bnq and remote |
| 35437 | messages from hosts that match recipient_unqualified_hosts set this flag. |
| 35438 | |
| 35439 | -allow_unqualified_sender |
| 35440 | |
| 35441 | This is present if unqualified sender addresses are permitted in header |
| 35442 | lines (to stop such addresses from being qualified if rewriting occurs at |
| 35443 | transport time). Local messages that were input using -bnq and remote |
| 35444 | messages from hosts that match sender_unqualified_hosts set this flag. |
| 35445 | |
| 35446 | -auth_id <text> |
| 35447 | |
| 35448 | The id information for a message received on an authenticated SMTP |
| 35449 | connection - the value of the $authenticated_id variable. |
| 35450 | |
| 35451 | -auth_sender <address> |
| 35452 | |
| 35453 | The address of an authenticated sender - the value of the |
| 35454 | $authenticated_sender variable. |
| 35455 | |
| 35456 | -body_linecount <number> |
| 35457 | |
| 35458 | This records the number of lines in the body of the message, and is always |
| 35459 | present. |
| 35460 | |
| 35461 | -body_zerocount <number> |
| 35462 | |
| 35463 | This records the number of binary zero bytes in the body of the message, |
| 35464 | and is present if the number is greater than zero. |
| 35465 | |
| 35466 | -deliver_firsttime |
| 35467 | |
| 35468 | This is written when a new message is first added to the spool. When the |
| 35469 | spool file is updated after a deferral, it is omitted. |
| 35470 | |
| 35471 | -frozen <time> |
| 35472 | |
| 35473 | The message is frozen, and the freezing happened at <time>. |
| 35474 | |
| 35475 | -helo_name <text> |
| 35476 | |
| 35477 | This records the host name as specified by a remote host in a HELO or EHLO |
| 35478 | command. |
| 35479 | |
| 35480 | -host_address <address>.<port> |
| 35481 | |
| 35482 | This records the IP address of the host from which the message was received |
| 35483 | and the remote port number that was used. It is omitted for locally |
| 35484 | generated messages. |
| 35485 | |
| 35486 | -host_auth <text> |
| 35487 | |
| 35488 | If the message was received on an authenticated SMTP connection, this |
| 35489 | records the name of the authenticator - the value of the |
| 35490 | $sender_host_authenticated variable. |
| 35491 | |
| 35492 | -host_lookup_failed |
| 35493 | |
| 35494 | This is present if an attempt to look up the sending host's name from its |
| 35495 | IP address failed. It corresponds to the $host_lookup_failed variable. |
| 35496 | |
| 35497 | -host_name <text> |
| 35498 | |
| 35499 | This records the name of the remote host from which the message was |
| 35500 | received, if the host name was looked up from the IP address when the |
| 35501 | message was being received. It is not present if no reverse lookup was |
| 35502 | done. |
| 35503 | |
| 35504 | -ident <text> |
| 35505 | |
| 35506 | For locally submitted messages, this records the login of the originating |
| 35507 | user, unless it was a trusted user and the -oMt option was used to specify |
| 35508 | an ident value. For messages received over TCP/IP, this records the ident |
| 35509 | string supplied by the remote host, if any. |
| 35510 | |
| 35511 | -interface_address <address>.<port> |
| 35512 | |
| 35513 | This records the IP address of the local interface and the port number |
| 35514 | through which a message was received from a remote host. It is omitted for |
| 35515 | locally generated messages. |
| 35516 | |
| 35517 | -local |
| 35518 | |
| 35519 | The message is from a local sender. |
| 35520 | |
| 35521 | -localerror |
| 35522 | |
| 35523 | The message is a locally-generated bounce message. |
| 35524 | |
| 35525 | -local_scan <string> |
| 35526 | |
| 35527 | This records the data string that was returned by the local_scan() function |
| 35528 | when the message was received - the value of the $local_scan_data variable. |
| 35529 | It is omitted if no data was returned. |
| 35530 | |
| 35531 | -manual_thaw |
| 35532 | |
| 35533 | The message was frozen but has been thawed manually, that is, by an |
| 35534 | explicit Exim command rather than via the auto-thaw process. |
| 35535 | |
| 35536 | -N |
| 35537 | |
| 35538 | A testing delivery process was started using the -N option to suppress any |
| 35539 | actual deliveries, but delivery was deferred. At any further delivery |
| 35540 | attempts, -N is assumed. |
| 35541 | |
| 35542 | -received_protocol |
| 35543 | |
| 35544 | This records the value of the $received_protocol variable, which contains |
| 35545 | the name of the protocol by which the message was received. |
| 35546 | |
| 35547 | -sender_set_untrusted |
| 35548 | |
| 35549 | The envelope sender of this message was set by an untrusted local caller |
| 35550 | (used to ensure that the caller is displayed in queue listings). |
| 35551 | |
| 35552 | -spam_score_int <number> |
| 35553 | |
| 35554 | If a message was scanned by SpamAssassin, this is present. It records the |
| 35555 | value of $spam_score_int. |
| 35556 | |
| 35557 | -tls_certificate_verified |
| 35558 | |
| 35559 | A TLS certificate was received from the client that sent this message, and |
| 35560 | the certificate was verified by the server. |
| 35561 | |
| 35562 | -tls_cipher <cipher name> |
| 35563 | |
| 35564 | When the message was received over an encrypted connection, this records |
| 35565 | the name of the cipher suite that was used. |
| 35566 | |
| 35567 | -tls_peerdn <peer DN> |
| 35568 | |
| 35569 | When the message was received over an encrypted connection, and a |
| 35570 | certificate was received from the client, this records the Distinguished |
| 35571 | Name from that certificate. |
| 35572 | |
| 35573 | Following the options there is a list of those addresses to which the message |
| 35574 | is not to be delivered. This set of addresses is initialized from the command |
| 35575 | line when the -t option is used and extract_addresses_remove_arguments is set; |
| 35576 | otherwise it starts out empty. Whenever a successful delivery is made, the |
| 35577 | address is added to this set. The addresses are kept internally as a balanced |
| 35578 | binary tree, and it is a representation of that tree which is written to the |
| 35579 | spool file. If an address is expanded via an alias or forward file, the |
| 35580 | original address is added to the tree when deliveries to all its child |
| 35581 | addresses are complete. |
| 35582 | |
| 35583 | If the tree is empty, there is a single line in the spool file containing just |
| 35584 | the text "XX". Otherwise, each line consists of two letters, which are either Y |
| 35585 | or N, followed by an address. The address is the value for the node of the |
| 35586 | tree, and the letters indicate whether the node has a left branch and/or a |
| 35587 | right branch attached to it, respectively. If branches exist, they immediately |
| 35588 | follow. Here is an example of a three-node tree: |
| 35589 | |
| 35590 | YY darcy@austen.fict.example |
| 35591 | NN alice@wonderland.fict.example |
| 35592 | NN editor@thesaurus.ref.example |
| 35593 | |
| 35594 | After the non-recipients tree, there is a list of the message's recipients. |
| 35595 | This is a simple list, preceded by a count. It includes all the original |
| 35596 | recipients of the message, including those to whom the message has already been |
| 35597 | delivered. In the simplest case, the list contains one address per line. For |
| 35598 | example: |
| 35599 | |
| 35600 | 4 |
| 35601 | editor@thesaurus.ref.example |
| 35602 | darcy@austen.fict.example |
| 35603 | rdo@foundation |
| 35604 | alice@wonderland.fict.example |
| 35605 | |
| 35606 | However, when a child address has been added to the top-level addresses as a |
| 35607 | result of the use of the one_time option on a redirect router, each line is of |
| 35608 | the following form: |
| 35609 | |
| 35610 | <top-level address> <errors_to address> <length>,<parent number>#<flag bits> |
| 35611 | |
| 35612 | The 01 flag bit indicates the presence of the three other fields that follow |
| 35613 | the top-level address. Other bits may be used in future to support additional |
| 35614 | fields. The <parent number> is the offset in the recipients list of the |
| 35615 | original parent of the "one time" address. The first two fields are the |
| 35616 | envelope sender that is associated with this address and its length. If the |
| 35617 | length is zero, there is no special envelope sender (there are then two space |
| 35618 | characters in the line). A non-empty field can arise from a redirect router |
| 35619 | that has an errors_to setting. |
| 35620 | |
| 35621 | A blank line separates the envelope and status information from the headers |
| 35622 | which follow. A header may occupy several lines of the file, and to save effort |
| 35623 | when reading it in, each header is preceded by a number and an identifying |
| 35624 | character. The number is the number of characters in the header, including any |
| 35625 | embedded newlines and the terminating newline. The character is one of the |
| 35626 | following: |
| 35627 | |
| 35628 | <blank> header in which Exim has no special interest |
| 35629 | "B" Bcc: header |
| 35630 | "C" Cc: header |
| 35631 | "F" From: header |
| 35632 | "I" Message-id: header |
| 35633 | "P" Received: header - P for "postmark" |
| 35634 | "R" Reply-To: header |
| 35635 | "S" Sender: header |
| 35636 | "T" To: header |
| 35637 | "*" replaced or deleted header |
| 35638 | |
| 35639 | Deleted or replaced (rewritten) headers remain in the spool file for debugging |
| 35640 | purposes. They are not transmitted when the message is delivered. Here is a |
| 35641 | typical set of headers: |
| 35642 | |
| 35643 | 111P Received: by hobbit.fict.example with local (Exim 4.00) |
| 35644 | id 14y9EI-00026G-00; Fri, 11 May 2001 10:28:59 +0100 |
| 35645 | 049 Message-Id: <E14y9EI-00026G-00@hobbit.fict.example> |
| 35646 | 038* X-rewrote-sender: bb@hobbit.fict.example |
| 35647 | 042* From: Bilbo Baggins <bb@hobbit.fict.example> |
| 35648 | 049F From: Bilbo Baggins <B.Baggins@hobbit.fict.example> |
| 35649 | 099* To: alice@wonderland.fict.example, rdo@foundation, |
| 35650 | darcy@austen.fict.example, editor@thesaurus.ref.example |
| 35651 | 104T To: alice@wonderland.fict.example, rdo@foundation.example, |
| 35652 | darcy@austen.fict.example, editor@thesaurus.ref.example |
| 35653 | 038 Date: Fri, 11 May 2001 10:28:59 +0100 |
| 35654 | |
| 35655 | The asterisked headers indicate that the envelope sender, From: header, and To: |
| 35656 | header have been rewritten, the last one because routing expanded the |
| 35657 | unqualified domain foundation. |
| 35658 | |
| 35659 | |
| 35660 | |
| 35661 | =============================================================================== |
| 35662 | 57. SUPPORT FOR DKIM (DOMAINKEYS IDENTIFIED MAIL) |
| 35663 | |
| 35664 | DKIM is a mechanism by which messages sent by some entity can be provably |
| 35665 | linked to a domain which that entity controls. It permits reputation to be |
| 35666 | tracked on a per-domain basis, rather than merely upon source IP address. DKIM |
| 35667 | is documented in RFC 4871. |
| 35668 | |
| 35669 | DKIM support is compiled into Exim by default if TLS support is present. It can |
| 35670 | be disabled by setting DISABLE_DKIM=yes in Local/Makefile. |
| 35671 | |
| 35672 | Exim's DKIM implementation allows for |
| 35673 | |
| 35674 | 1. Signing outgoing messages: This function is implemented in the SMTP |
| 35675 | transport. It can co-exist with all other Exim features (including |
| 35676 | transport filters) except cutthrough delivery. |
| 35677 | |
| 35678 | 2. Verifying signatures in incoming messages: This is implemented by an |
| 35679 | additional ACL (acl_smtp_dkim), which can be called several times per |
| 35680 | message, with different signature contexts. |
| 35681 | |
| 35682 | In typical Exim style, the verification implementation does not include any |
| 35683 | default "policy". Instead it enables you to build your own policy using Exim's |
| 35684 | standard controls. |
| 35685 | |
| 35686 | Please note that verification of DKIM signatures in incoming mail is turned on |
| 35687 | by default for logging purposes. For each signature in incoming email, exim |
| 35688 | will log a line displaying the most important signature details, and the |
| 35689 | signature status. Here is an example (with line-breaks added for clarity): |
| 35690 | |
| 35691 | 2009-09-09 10:22:28 1MlIRf-0003LU-U3 DKIM: |
| 35692 | d=facebookmail.com s=q1-2009b |
| 35693 | c=relaxed/relaxed a=rsa-sha1 |
| 35694 | i=@facebookmail.com t=1252484542 [verification succeeded] |
| 35695 | |
| 35696 | You might want to turn off DKIM verification processing entirely for internal |
| 35697 | or relay mail sources. To do that, set the dkim_disable_verify ACL control |
| 35698 | modifier. This should typically be done in the RCPT ACL, at points where you |
| 35699 | accept mail from relay sources (internal hosts or authenticated senders). |
| 35700 | |
| 35701 | |
| 35702 | 57.1 Signing outgoing messages |
| 35703 | ------------------------------ |
| 35704 | |
| 35705 | Signing is enabled by setting private options on the SMTP transport. These |
| 35706 | options take (expandable) strings as arguments. |
| 35707 | |
| 35708 | +--------------------------------------------------+ |
| 35709 | |dkim_domain|Use: smtp|Type: string*|Default: unset| |
| 35710 | +--------------------------------------------------+ |
| 35711 | |
| 35712 | MANDATORY: The domain you want to sign with. The result of this expanded option |
| 35713 | is put into the $dkim_domain expansion variable. If it is empty after |
| 35714 | expansion, DKIM signing is not done. |
| 35715 | |
| 35716 | +----------------------------------------------------+ |
| 35717 | |dkim_selector|Use: smtp|Type: string*|Default: unset| |
| 35718 | +----------------------------------------------------+ |
| 35719 | |
| 35720 | MANDATORY: This sets the key selector string. You can use the $dkim_domain |
| 35721 | expansion variable to look up a matching selector. The result is put in the |
| 35722 | expansion variable $dkim_selector which may be used in the dkim_private_key |
| 35723 | option along with $dkim_domain. |
| 35724 | |
| 35725 | +-------------------------------------------------------+ |
| 35726 | |dkim_private_key|Use: smtp|Type: string*|Default: unset| |
| 35727 | +-------------------------------------------------------+ |
| 35728 | |
| 35729 | MANDATORY: This sets the private key to use. You can use the $dkim_domain and |
| 35730 | $dkim_selector expansion variables to determine the private key to use. The |
| 35731 | result can either |
| 35732 | |
| 35733 | * be a valid RSA private key in ASCII armor, including line breaks. |
| 35734 | |
| 35735 | * start with a slash, in which case it is treated as a file that contains the |
| 35736 | private key. |
| 35737 | |
| 35738 | * be "0", "false" or the empty string, in which case the message will not be |
| 35739 | signed. This case will not result in an error, even if dkim_strict is set. |
| 35740 | |
| 35741 | +-------------------------------------------------+ |
| 35742 | |dkim_canon|Use: smtp|Type: string*|Default: unset| |
| 35743 | +-------------------------------------------------+ |
| 35744 | |
| 35745 | OPTIONAL: This option sets the canonicalization method used when signing a |
| 35746 | message. The DKIM RFC currently supports two methods: "simple" and "relaxed". |
| 35747 | The option defaults to "relaxed" when unset. Note: the current implementation |
| 35748 | only supports using the same canonicalization method for both headers and body. |
| 35749 | |
| 35750 | +--------------------------------------------------+ |
| 35751 | |dkim_strict|Use: smtp|Type: string*|Default: unset| |
| 35752 | +--------------------------------------------------+ |
| 35753 | |
| 35754 | OPTIONAL: This option defines how Exim behaves when signing a message that |
| 35755 | should be signed fails for some reason. When the expansion evaluates to either |
| 35756 | "1" or "true", Exim will defer. Otherwise Exim will send the message unsigned. |
| 35757 | You can use the $dkim_domain and $dkim_selector expansion variables here. |
| 35758 | |
| 35759 | +--------------------------------------------------------+ |
| 35760 | |dkim_sign_headers|Use: smtp|Type: string*|Default: unset| |
| 35761 | +--------------------------------------------------------+ |
| 35762 | |
| 35763 | OPTIONAL: When set, this option must expand to (or be specified as) a |
| 35764 | colon-separated list of header names. Headers with these names will be included |
| 35765 | in the message signature. When unspecified, the header names recommended in |
| 35766 | RFC4871 will be used. |
| 35767 | |
| 35768 | |
| 35769 | 57.2 Verifying DKIM signatures in incoming mail |
| 35770 | ----------------------------------------------- |
| 35771 | |
| 35772 | Verification of DKIM signatures in SMTP incoming email is implemented via the |
| 35773 | acl_smtp_dkim ACL. By default, this ACL is called once for each syntactically |
| 35774 | (!) correct signature in the incoming message. A missing ACL definition |
| 35775 | defaults to accept. If any ACL call does not accept, the message is not |
| 35776 | accepted. If a cutthrough delivery was in progress for the message it is |
| 35777 | summarily dropped (having wasted the transmission effort). |
| 35778 | |
| 35779 | To evaluate the signature in the ACL a large number of expansion variables |
| 35780 | containing the signature status and its details are set up during the runtime |
| 35781 | of the ACL. |
| 35782 | |
| 35783 | Calling the ACL only for existing signatures is not sufficient to build more |
| 35784 | advanced policies. For that reason, the global option dkim_verify_signers, and |
| 35785 | a global expansion variable $dkim_signers exist. |
| 35786 | |
| 35787 | The global option dkim_verify_signers can be set to a colon-separated list of |
| 35788 | DKIM domains or identities for which the ACL acl_smtp_dkim is called. It is |
| 35789 | expanded when the message has been received. At this point, the expansion |
| 35790 | variable $dkim_signers already contains a colon-separated list of signer |
| 35791 | domains and identities for the message. When dkim_verify_signers is not |
| 35792 | specified in the main configuration, it defaults as: |
| 35793 | |
| 35794 | dkim_verify_signers = $dkim_signers |
| 35795 | |
| 35796 | This leads to the default behaviour of calling acl_smtp_dkim for each DKIM |
| 35797 | signature in the message. Current DKIM verifiers may want to explicitly call |
| 35798 | the ACL for known domains or identities. This would be achieved as follows: |
| 35799 | |
| 35800 | dkim_verify_signers = paypal.com:ebay.com:$dkim_signers |
| 35801 | |
| 35802 | This would result in acl_smtp_dkim always being called for "paypal.com" and |
| 35803 | "ebay.com", plus all domains and identities that have signatures in the |
| 35804 | message. You can also be more creative in constructing your policy. For |
| 35805 | example: |
| 35806 | |
| 35807 | dkim_verify_signers = $sender_address_domain:$dkim_signers |
| 35808 | |
| 35809 | If a domain or identity is listed several times in the (expanded) value of |
| 35810 | dkim_verify_signers, the ACL is only called once for that domain or identity. |
| 35811 | |
| 35812 | Inside the acl_smtp_dkim, the following expansion variables are available (from |
| 35813 | most to least important): |
| 35814 | |
| 35815 | $dkim_cur_signer |
| 35816 | |
| 35817 | The signer that is being evaluated in this ACL run. This can be a domain or |
| 35818 | an identity. This is one of the list items from the expanded main option |
| 35819 | dkim_verify_signers (see above). |
| 35820 | |
| 35821 | $dkim_verify_status |
| 35822 | |
| 35823 | A string describing the general status of the signature. One of |
| 35824 | |
| 35825 | + none: There is no signature in the message for the current domain or |
| 35826 | identity (as reflected by $dkim_cur_signer). |
| 35827 | |
| 35828 | + invalid: The signature could not be verified due to a processing error. |
| 35829 | More detail is available in $dkim_verify_reason. |
| 35830 | |
| 35831 | + fail: Verification of the signature failed. More detail is available in |
| 35832 | $dkim_verify_reason. |
| 35833 | |
| 35834 | + pass: The signature passed verification. It is valid. |
| 35835 | |
| 35836 | $dkim_verify_reason |
| 35837 | |
| 35838 | A string giving a little bit more detail when $dkim_verify_status is either |
| 35839 | "fail" or "invalid". One of |
| 35840 | |
| 35841 | + pubkey_unavailable (when $dkim_verify_status="invalid"): The public key |
| 35842 | for the domain could not be retrieved. This may be a temporary problem. |
| 35843 | |
| 35844 | + pubkey_syntax (when $dkim_verify_status="invalid"): The public key |
| 35845 | record for the domain is syntactically invalid. |
| 35846 | |
| 35847 | + bodyhash_mismatch (when $dkim_verify_status="fail"): The calculated |
| 35848 | body hash does not match the one specified in the signature header. |
| 35849 | This means that the message body was modified in transit. |
| 35850 | |
| 35851 | + signature_incorrect (when $dkim_verify_status="fail"): The signature |
| 35852 | could not be verified. This may mean that headers were modified, |
| 35853 | re-written or otherwise changed in a way which is incompatible with |
| 35854 | DKIM verification. It may of course also mean that the signature is |
| 35855 | forged. |
| 35856 | |
| 35857 | $dkim_domain |
| 35858 | |
| 35859 | The signing domain. IMPORTANT: This variable is only populated if there is |
| 35860 | an actual signature in the message for the current domain or identity (as |
| 35861 | reflected by $dkim_cur_signer). |
| 35862 | |
| 35863 | $dkim_identity |
| 35864 | |
| 35865 | The signing identity, if present. IMPORTANT: This variable is only |
| 35866 | populated if there is an actual signature in the message for the current |
| 35867 | domain or identity (as reflected by $dkim_cur_signer). |
| 35868 | |
| 35869 | $dkim_selector |
| 35870 | |
| 35871 | The key record selector string. |
| 35872 | |
| 35873 | $dkim_algo |
| 35874 | |
| 35875 | The algorithm used. One of 'rsa-sha1' or 'rsa-sha256'. |
| 35876 | |
| 35877 | $dkim_canon_body |
| 35878 | |
| 35879 | The body canonicalization method. One of 'relaxed' or 'simple'. |
| 35880 | |
| 35881 | dkim_canon_headers |
| 35882 | |
| 35883 | The header canonicalization method. One of 'relaxed' or 'simple'. |
| 35884 | |
| 35885 | $dkim_copiedheaders |
| 35886 | |
| 35887 | A transcript of headers and their values which are included in the |
| 35888 | signature (copied from the 'z=' tag of the signature). Note that RFC6376 |
| 35889 | requires that verification fail if the From: header is not included in the |
| 35890 | signature. Exim does not enforce this; sites wishing strict enforcement |
| 35891 | should code the check explicitly. |
| 35892 | |
| 35893 | $dkim_bodylength |
| 35894 | |
| 35895 | The number of signed body bytes. If zero ("0"), the body is unsigned. If no |
| 35896 | limit was set by the signer, "9999999999999" is returned. This makes sure |
| 35897 | that this variable always expands to an integer value. |
| 35898 | |
| 35899 | $dkim_created |
| 35900 | |
| 35901 | UNIX timestamp reflecting the date and time when the signature was created. |
| 35902 | When this was not specified by the signer, "0" is returned. |
| 35903 | |
| 35904 | $dkim_expires |
| 35905 | |
| 35906 | UNIX timestamp reflecting the date and time when the signer wants the |
| 35907 | signature to be treated as "expired". When this was not specified by the |
| 35908 | signer, "9999999999999" is returned. This makes it possible to do useful |
| 35909 | integer size comparisons against this value. |
| 35910 | |
| 35911 | $dkim_headernames |
| 35912 | |
| 35913 | A colon-separated list of names of headers included in the signature. |
| 35914 | |
| 35915 | $dkim_key_testing |
| 35916 | |
| 35917 | "1" if the key record has the "testing" flag set, "0" if not. |
| 35918 | |
| 35919 | $dkim_key_nosubdomains |
| 35920 | |
| 35921 | "1" if the key record forbids subdomaining, "0" otherwise. |
| 35922 | |
| 35923 | $dkim_key_srvtype |
| 35924 | |
| 35925 | Service type (tag s=) from the key record. Defaults to "*" if not specified |
| 35926 | in the key record. |
| 35927 | |
| 35928 | $dkim_key_granularity |
| 35929 | |
| 35930 | Key granularity (tag g=) from the key record. Defaults to "*" if not |
| 35931 | specified in the key record. |
| 35932 | |
| 35933 | $dkim_key_notes |
| 35934 | |
| 35935 | Notes from the key record (tag n=). |
| 35936 | |
| 35937 | $dkim_key_length |
| 35938 | |
| 35939 | Number of bits in the key. |
| 35940 | |
| 35941 | In addition, two ACL conditions are provided: |
| 35942 | |
| 35943 | dkim_signers |
| 35944 | |
| 35945 | ACL condition that checks a colon-separated list of domains or identities |
| 35946 | for a match against the domain or identity that the ACL is currently |
| 35947 | verifying (reflected by $dkim_cur_signer). This is typically used to |
| 35948 | restrict an ACL verb to a group of domains or identities. For example: |
| 35949 | |
| 35950 | # Warn when Mail purportedly from GMail has no gmail signature |
| 35951 | warn log_message = GMail sender without gmail.com DKIM signature |
| 35952 | sender_domains = gmail.com |
| 35953 | dkim_signers = gmail.com |
| 35954 | dkim_status = none |
| 35955 | |
| 35956 | Note that the above does not check for a total lack of DKIM signing; for |
| 35957 | that check for empty $h_DKIM-Signature: in the data ACL. |
| 35958 | |
| 35959 | dkim_status |
| 35960 | |
| 35961 | ACL condition that checks a colon-separated list of possible DKIM |
| 35962 | verification results against the actual result of verification. This is |
| 35963 | typically used to restrict an ACL verb to a list of verification outcomes, |
| 35964 | for example: |
| 35965 | |
| 35966 | deny message = Mail from Paypal with invalid/missing signature |
| 35967 | sender_domains = paypal.com:paypal.de |
| 35968 | dkim_signers = paypal.com:paypal.de |
| 35969 | dkim_status = none:invalid:fail |
| 35970 | |
| 35971 | The possible status keywords are: 'none','invalid','fail' and 'pass'. |
| 35972 | Please see the documentation of the $dkim_verify_status expansion variable |
| 35973 | above for more information of what they mean. |
| 35974 | |
| 35975 | |
| 35976 | |
| 35977 | =============================================================================== |
| 35978 | 58. PROXIES |
| 35979 | |
| 35980 | A proxy is an intermediate system through which communication is passed. |
| 35981 | Proxies may provide a security, availability or load-distribution function. |
| 35982 | |
| 35983 | |
| 35984 | 58.1 Inbound proxies |
| 35985 | -------------------- |
| 35986 | |
| 35987 | Exim has support for receiving inbound SMTP connections via a proxy that uses |
| 35988 | "Proxy Protocol" to speak to it. To include this support, include |
| 35989 | "SUPPORT_PROXY=yes" in Local/Makefile. |
| 35990 | |
| 35991 | It was built on specifications from: (http://haproxy.1wt.eu/download/1.5/doc/ |
| 35992 | proxy-protocol.txt). That URL was revised in May 2014 to version 2 spec: (http: |
| 35993 | //git.1wt.eu/web?p=haproxy.git;a=commitdiff;h=afb768340c9d7e50d8e). |
| 35994 | |
| 35995 | The purpose of this facility is so that an application load balancer, such as |
| 35996 | HAProxy, can sit in front of several Exim servers to distribute load. Exim uses |
| 35997 | the local protocol communication with the proxy to obtain the remote SMTP |
| 35998 | system IP address and port information. There is no logging if a host passes or |
| 35999 | fails Proxy Protocol negotiation, but it can easily be determined and recorded |
| 36000 | in an ACL (example is below). |
| 36001 | |
| 36002 | Use of a proxy is enabled by setting the hosts_proxy main configuration option |
| 36003 | to a hostlist; connections from these hosts will use Proxy Protocol. Exim |
| 36004 | supports both version 1 and version 2 of the Proxy Protocol and automatically |
| 36005 | determines which version is in use. |
| 36006 | |
| 36007 | The Proxy Protocol header is the first data received on a TCP connection and is |
| 36008 | inserted before any TLS-on-connect handshake from the client; Exim negotiates |
| 36009 | TLS between Exim-as-server and the remote client, not between Exim and the |
| 36010 | proxy server. |
| 36011 | |
| 36012 | The following expansion variables are usable ("internal" and "external" here |
| 36013 | refer to the interfaces of the proxy): |
| 36014 | |
| 36015 | proxy_external_address |
| 36016 | IP of host being proxied or IP of remote interface of proxy |
| 36017 | proxy_external_port |
| 36018 | Port of host being proxied or Port on remote interface of proxy |
| 36019 | proxy_local_address |
| 36020 | IP of proxy server inbound or IP of local interface of proxy |
| 36021 | proxy_local_port |
| 36022 | Port of proxy server inbound or Port on local interface of proxy |
| 36023 | proxy_session boolean: SMTP connection via proxy |
| 36024 | |
| 36025 | If $proxy_session is set but $proxy_external_address is empty there was a |
| 36026 | protocol error. |
| 36027 | |
| 36028 | Since the real connections are all coming from the proxy, and the per host |
| 36029 | connection tracking is done before Proxy Protocol is evaluated, |
| 36030 | smtp_accept_max_per_host must be set high enough to handle all of the parallel |
| 36031 | volume you expect per inbound proxy. With the option set so high, you lose the |
| 36032 | ability to protect your server from many connections from one IP. In order to |
| 36033 | prevent your server from overload, you need to add a per connection ratelimit |
| 36034 | to your connect ACL. A possible solution is: |
| 36035 | |
| 36036 | # Set max number of connections per host |
| 36037 | LIMIT = 5 |
| 36038 | # Or do some kind of IP lookup in a flat file or database |
| 36039 | # LIMIT = ${lookup{$sender_host_address}iplsearch{/etc/exim/proxy_limits}} |
| 36040 | |
| 36041 | defer message = Too many connections from this IP right now |
| 36042 | ratelimit = LIMIT / 5s / per_conn / strict |
| 36043 | |
| 36044 | |
| 36045 | 58.2 Outbound proxies |
| 36046 | --------------------- |
| 36047 | |
| 36048 | Exim has support for sending outbound SMTP via a proxy using a protocol called |
| 36049 | SOCKS5 (defined by RFC1928). The support can be optionally included by defining |
| 36050 | SUPPORT_SOCKS=yes in Local/Makefile. |
| 36051 | |
| 36052 | Use of a proxy is enabled by setting the socks_proxy option on an smtp |
| 36053 | transport. The option value is expanded and should then be a list |
| 36054 | (colon-separated by default) of proxy specifiers. Each proxy specifier is a |
| 36055 | list (space-separated by default) where the initial element is an IP address |
| 36056 | and any subsequent elements are options. |
| 36057 | |
| 36058 | Options are a string <name>=<value>. The list of options is in the following |
| 36059 | table: |
| 36060 | |
| 36061 | auth authentication method |
| 36062 | name authentication username |
| 36063 | pass authentication password |
| 36064 | port tcp port |
| 36065 | tmo connection timeout |
| 36066 | pri priority |
| 36067 | weight selection bias |
| 36068 | |
| 36069 | More details on each of these options follows: |
| 36070 | |
| 36071 | * auth: Either "none" (default) or "name". Using "name" selects username/ |
| 36072 | password authentication per RFC 1929 for access to the proxy. Default is |
| 36073 | "none". |
| 36074 | |
| 36075 | * name: sets the username for the "name" authentication method. Default is |
| 36076 | empty. |
| 36077 | |
| 36078 | * pass: sets the password for the "name" authentication method. Default is |
| 36079 | empty. |
| 36080 | |
| 36081 | * port: the TCP port number to use for the connection to the proxy. Default |
| 36082 | is 1080. |
| 36083 | |
| 36084 | * tmo: sets a connection timeout in seconds for this proxy. Default is 5. |
| 36085 | |
| 36086 | * pri: specifies a priority for the proxy within the list, higher values |
| 36087 | being tried first. The default priority is 1. |
| 36088 | |
| 36089 | * weight: specifies a selection bias. Within a priority set servers are |
| 36090 | queried in a random fashion, weighted by this value. The default value for |
| 36091 | selection bias is 1. |
| 36092 | |
| 36093 | Proxies from the list are tried according to their priority and weight settings |
| 36094 | until one responds. The timeout for the overall connection applies to the set |
| 36095 | of proxied attempts. |
| 36096 | |
| 36097 | |
| 36098 | 58.3 Logging |
| 36099 | ------------ |
| 36100 | |
| 36101 | To log the (local) IP of a proxy in the incoming or delivery logline, add |
| 36102 | "+proxy" to the log_selector option. This will add a component tagged with "PRX |
| 36103 | =" to the line. |
| 36104 | |
| 36105 | |
| 36106 | |
| 36107 | =============================================================================== |
| 36108 | 59. INTERNATIONALISATION |
| 36109 | |
| 36110 | Exim has support for Internationalised mail names. To include this it must be |
| 36111 | built with SUPPORT_I18N and the libidn library. Standards supported are RFCs |
| 36112 | 2060, 5890, 6530 and 6533. |
| 36113 | |
| 36114 | If Exim is built with SUPPORT_I18N_2008 (in addition to SUPPORT_I18N, not |
| 36115 | instead of it) then IDNA2008 is supported; this adds an extra library |
| 36116 | requirement, upon libidn2. |
| 36117 | |
| 36118 | |
| 36119 | 59.1 MTA operations |
| 36120 | ------------------- |
| 36121 | |
| 36122 | The main configuration option smtputf8_advertise_hosts specifies a host list. |
| 36123 | If this matches the sending host and accept_8bitmime is true (the default) then |
| 36124 | the ESMTP option SMTPUTF8 will be advertised. |
| 36125 | |
| 36126 | If the sender specifies the SMTPUTF8 option on a MAIL command international |
| 36127 | handling for the message is enabled and the expansion variable |
| 36128 | $message_smtputf8 will have value TRUE. |
| 36129 | |
| 36130 | The option allow_utf8_domains is set to true for this message. All DNS lookups |
| 36131 | are converted to a-label form whatever the setting of allow_utf8_domains when |
| 36132 | Exim is built with SUPPORT_I18N. |
| 36133 | |
| 36134 | Both localparts and domain are maintained as the original UTF-8 form |
| 36135 | internally; any comparison or regular-expression use will require appropriate |
| 36136 | care. Filenames created, eg. by the appendfile transport, will have UTF-8 |
| 36137 | names. |
| 36138 | |
| 36139 | HELO names sent by the smtp transport will have any UTF-8 components expanded |
| 36140 | to a-label form, and any certificate name checks will be done using the a-label |
| 36141 | form of the name. |
| 36142 | |
| 36143 | Log lines and Received-by: header lines will acquire a "utf8" prefix on the |
| 36144 | protocol element, eg. utf8esmtp. |
| 36145 | |
| 36146 | The following expansion operators can be used: |
| 36147 | |
| 36148 | ${utf8_domain_to_alabel:str} |
| 36149 | ${utf8_domain_from_alabel:str} |
| 36150 | ${utf8_localpart_to_alabel:str} |
| 36151 | ${utf8_localpart_from_alabel:str} |
| 36152 | |
| 36153 | ACLs may use the following modifier: |
| 36154 | |
| 36155 | control = utf8_downconvert |
| 36156 | control = utf8_downconvert/<value> |
| 36157 | |
| 36158 | This sets a flag requiring that addresses are converted to a-label form before |
| 36159 | smtp delivery, for use in a Message Submission Agent context. If a value is |
| 36160 | appended it may be: |
| 36161 | |
| 36162 | 1 (default) mandatory downconversion |
| 36163 | 0 no downconversion |
| 36164 | -1 if SMTPUTF8 not supported by destination host |
| 36165 | |
| 36166 | If mua_wrapper is set, the utf8_downconvert control is initially set to -1. |
| 36167 | |
| 36168 | There is no explicit support for VRFY and EXPN. Configurations supporting these |
| 36169 | should inspect $smtp_command_argument for an SMTPUTF8 argument. |
| 36170 | |
| 36171 | There is no support for LMTP on Unix sockets. Using the "lmtp" protocol option |
| 36172 | on an smtp transport, for LMTP over TCP, should work as expected. |
| 36173 | |
| 36174 | There is no support for DSN unitext handling, and no provision for converting |
| 36175 | logging from or to UTF-8. |
| 36176 | |
| 36177 | |
| 36178 | 59.2 MDA operations |
| 36179 | ------------------- |
| 36180 | |
| 36181 | To aid in constructing names suitable for IMAP folders the following expansion |
| 36182 | operator can be used: |
| 36183 | |
| 36184 | ${imapfolder {<string>} {<sep>} {<specials>}} |
| 36185 | |
| 36186 | The string is converted from the charset specified by the "headers charset" |
| 36187 | command (in a filter file) or headers_charset main configuration option |
| 36188 | (otherwise), to the modified UTF-7 encoding specified by RFC 2060, with the |
| 36189 | following exception: All occurences of <sep> (which has to be a single |
| 36190 | character) are replaced with periods ("."), and all periods and slashes that |
| 36191 | are not <sep> and are not in the <specials> string are BASE64 encoded. |
| 36192 | |
| 36193 | The third argument can be omitted, defaulting to an empty string. The second |
| 36194 | argument can be omitted, defaulting to "/". |
| 36195 | |
| 36196 | This is the encoding used by Courier for Maildir names on disk, and followed by |
| 36197 | many other IMAP servers. |
| 36198 | |
| 36199 | Examples: |
| 36200 | |
| 36201 | ${imapfolder {Foo/Bar}} yields Foo.Bar |
| 36202 | ${imapfolder {Foo/Bar}{.}{/}} yields Foo&AC8-Bar |
| 36203 | ${imapfolder {R?ksm?rg?s}} yields R&AOQ-ksm&APY-rg&AOU-s |
| 36204 | |
| 36205 | Note that the source charset setting is vital, and also that characters must be |
| 36206 | representable in UTF-16. |
| 36207 | |
| 36208 | |
| 36209 | |
| 36210 | =============================================================================== |
| 36211 | 60. EVENTS |
| 36212 | |
| 36213 | The events mechanism in Exim can be used to intercept processing at a number of |
| 36214 | points. It was originally invented to give a way to do customised logging |
| 36215 | actions (for example, to a database) but can also be used to modify some |
| 36216 | processing actions. |
| 36217 | |
| 36218 | Most installations will never need to use Events. The support can be left out |
| 36219 | of a build by defining DISABLE_EVENT=yes in Local/Makefile. |
| 36220 | |
| 36221 | There are two major classes of events: main and transport. The main |
| 36222 | configuration option event_action controls reception events; a transport option |
| 36223 | event_action controls delivery events. |
| 36224 | |
| 36225 | Both options are a string which is expanded when the event fires. An example |
| 36226 | might look like: |
| 36227 | |
| 36228 | event_action = ${if eq {msg:delivery}{$event_name} \ |
| 36229 | {${lookup pgsql {SELECT * FROM record_Delivery( \ |
| 36230 | '${quote_pgsql:$sender_address_domain}',\ |
| 36231 | '${quote_pgsql:${lc:$sender_address_local_part}}', \ |
| 36232 | '${quote_pgsql:$domain}', \ |
| 36233 | '${quote_pgsql:${lc:$local_part}}', \ |
| 36234 | '${quote_pgsql:$host_address}', \ |
| 36235 | '${quote_pgsql:${lc:$host}}', \ |
| 36236 | '${quote_pgsql:$message_exim_id}')}} \ |
| 36237 | } {}} |
| 36238 | |
| 36239 | Events have names which correspond to the point in process at which they fire. |
| 36240 | The name is placed in the variable $event_name and the event action expansion |
| 36241 | must check this, as it will be called for every possible event type. |
| 36242 | |
| 36243 | The current list of events is: |
| 36244 | |
| 36245 | msg:complete after main per message |
| 36246 | msg:delivery after transport per recipient |
| 36247 | msg:rcpt:host:defer after transport per recipient per host |
| 36248 | msg:rcpt:defer after transport per recipient |
| 36249 | msg:host:defer after transport per attempt |
| 36250 | msg:fail:delivery after main per recipient |
| 36251 | msg:fail:internal after main per recipient |
| 36252 | tcp:connect before transport per connection |
| 36253 | tcp:close after transport per connection |
| 36254 | tls:cert before both per certificate in verification chain |
| 36255 | smtp:connect after transport per connection |
| 36256 | |
| 36257 | New event types may be added in future. |
| 36258 | |
| 36259 | The event name is a colon-separated list, defining the type of event in a tree |
| 36260 | of possibilities. It may be used as a list or just matched on as a whole. There |
| 36261 | will be no spaces in the name. |
| 36262 | |
| 36263 | The second column in the table above describes whether the event fires before |
| 36264 | or after the action is associates with. Those which fire before can be used to |
| 36265 | affect that action (more on this below). |
| 36266 | |
| 36267 | An additional variable, $event_data, is filled with information varying with |
| 36268 | the event type: |
| 36269 | |
| 36270 | msg:delivery smtp confirmation message |
| 36271 | msg:rcpt:host:defer error string |
| 36272 | msg:rcpt:defer error string |
| 36273 | msg:host:defer error string |
| 36274 | tls:cert verification chain depth |
| 36275 | smtp:connect smtp banner |
| 36276 | |
| 36277 | The :defer events populate one extra variable: $event_defer_errno. |
| 36278 | |
| 36279 | For complex operations an ACL expansion can be used in event_action however due |
| 36280 | to the multiple contexts that Exim operates in during the course of its |
| 36281 | processing: |
| 36282 | |
| 36283 | * variables set in transport events will not be visible outside that |
| 36284 | transport call |
| 36285 | |
| 36286 | * acl_m variables in a server context are lost on a new connection, and after |
| 36287 | smtp helo/ehlo/mail/starttls/rset commands |
| 36288 | |
| 36289 | Using an ACL expansion with the logwrite modifier can be a useful way of |
| 36290 | writing to the main log. |
| 36291 | |
| 36292 | The expansion of the event_action option should normally return an empty |
| 36293 | string. Should it return anything else the following will be forced: |
| 36294 | |
| 36295 | msg:delivery (ignored) |
| 36296 | msg:host:defer (ignored) |
| 36297 | msg:fail:delivery (ignored) |
| 36298 | tcp:connect do not connect |
| 36299 | tcp:close (ignored) |
| 36300 | tls:cert refuse verification |
| 36301 | smtp:connect close connection |
| 36302 | |
| 36303 | No other use is made of the result string. |
| 36304 | |
| 36305 | For a tcp:connect event, if the connection is being made to a proxy then the |
| 36306 | address and port variables will be that of the proxy and not the target system. |
| 36307 | |
| 36308 | For tls:cert events, if GnuTLS is in use this will trigger only per chain |
| 36309 | element received on the connection. For OpenSSL it will trigger for every chain |
| 36310 | element including those loaded locally. |
| 36311 | |
| 36312 | |
| 36313 | |
| 36314 | =============================================================================== |
| 36315 | 61. ADDING NEW DRIVERS OR LOOKUP TYPES |
| 36316 | |
| 36317 | The following actions have to be taken in order to add a new router, transport, |
| 36318 | authenticator, or lookup type to Exim: |
| 36319 | |
| 36320 | 1. Choose a name for the driver or lookup type that does not conflict with any |
| 36321 | existing name; I will use "newdriver" in what follows. |
| 36322 | |
| 36323 | 2. Add to src/EDITME the line: |
| 36324 | |
| 36325 | <type>_NEWDRIVER=yes |
| 36326 | |
| 36327 | where <type> is ROUTER, TRANSPORT, AUTH, or LOOKUP. If the code is not to |
| 36328 | be included in the binary by default, comment this line out. You should |
| 36329 | also add any relevant comments about the driver or lookup type. |
| 36330 | |
| 36331 | 3. Add to src/config.h.defaults the line: |
| 36332 | |
| 36333 | #define <type>_NEWDRIVER |
| 36334 | |
| 36335 | 4. Edit src/drtables.c, adding conditional code to pull in the private header |
| 36336 | and create a table entry as is done for all the other drivers and lookup |
| 36337 | types. |
| 36338 | |
| 36339 | 5. Edit scripts/lookups-Makefile if this is a new lookup; there is a for-loop |
| 36340 | near the bottom, ranging the "name_mod" variable over a list of all |
| 36341 | lookups. Add your "NEWDRIVER" to that list. As long as the dynamic module |
| 36342 | would be named newdriver.so, you can use the simple form that most lookups |
| 36343 | have. |
| 36344 | |
| 36345 | 6. Edit Makefile in the appropriate sub-directory (src/routers, src/transports |
| 36346 | , src/auths, or src/lookups); add a line for the new driver or lookup type |
| 36347 | and add it to the definition of OBJ. |
| 36348 | |
| 36349 | 7. Create newdriver.h and newdriver.c in the appropriate sub-directory of src. |
| 36350 | |
| 36351 | 8. Edit scripts/MakeLinks and add commands to link the .h and .c files as for |
| 36352 | other drivers and lookups. |
| 36353 | |
| 36354 | Then all you need to do is write the code! A good way to start is to make a |
| 36355 | proforma by copying an existing module of the same type, globally changing all |
| 36356 | occurrences of the name, and cutting out most of the code. Note that any |
| 36357 | options you create must be listed in alphabetical order, because the tables are |
| 36358 | searched using a binary chop procedure. |
| 36359 | |
| 36360 | There is a README file in each of the sub-directories of src describing the |
| 36361 | interface that is expected. |
| 36362 | |