| 1 | <?xml version="1.0" encoding="utf-8"?> |
| 2 | <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" |
| 3 | "http://www.docbook.org/xml/4.4/docbookx.dtd"> |
| 4 | <article> <title>Exim 4 for Debian</title> |
| 5 | <section> <title>Introduction</title> |
| 6 | <para> |
| 7 | If you're reading this, you have found the README.Debian |
| 8 | file. This is good, thanks! Please continue reading this file in |
| 9 | its entirety. It is full of important information and has been |
| 10 | written with the questions in mind that keep popping up on the |
| 11 | mailing lists. |
| 12 | </para> |
| 13 | <section> <title>How to find your way around the Documentation</title> |
| 14 | <para> |
| 15 | Exim comes with very extensive documentation. Here is how to |
| 16 | find it. |
| 17 | <orderedlist> |
| 18 | <listitem> |
| 19 | <simpara> |
| 20 | A lot of information about Debian's Exim 4 |
| 21 | packaging can be found in this document. |
| 22 | </simpara> |
| 23 | </listitem> |
| 24 | <listitem> |
| 25 | <simpara> |
| 26 | The packages contain a lot of Debian-specific man pages. |
| 27 | Use the <command>apropos exim</command> command to get a list. |
| 28 | </simpara> |
| 29 | </listitem> |
| 30 | <listitem> |
| 31 | <simpara> |
| 32 | Most files that control the default configuration are |
| 33 | documented in the exim4-config_files(5) man page, which |
| 34 | is symlinked to the file names. man <filename> should |
| 35 | lead you to the page. |
| 36 | </simpara> |
| 37 | </listitem> |
| 38 | <listitem> |
| 39 | <para> |
| 40 | The very extensive Upstream documentation is shipped |
| 41 | <orderedlist> |
| 42 | <listitem> |
| 43 | <simpara> |
| 44 | in text form |
| 45 | (<filename>/usr/share/doc/exim4-base/spec.txt.gz</filename>) |
| 46 | with the binary packages. |
| 47 | </simpara> |
| 48 | </listitem> |
| 49 | <listitem> |
| 50 | <simpara> |
| 51 | in HTML in the package |
| 52 | <filename>exim4-doc-html</filename> |
| 53 | </simpara> |
| 54 | </listitem> |
| 55 | <listitem> |
| 56 | <simpara> |
| 57 | as a Texinfo file in the package |
| 58 | <filename>exim4-doc-info</filename> |
| 59 | </simpara> |
| 60 | </listitem> |
| 61 | </orderedlist> |
| 62 | </para> |
| 63 | </listitem> |
| 64 | </orderedlist> |
| 65 | </para> |
| 66 | <para> |
| 67 | Please note that documentation found on the web or in other |
| 68 | parts of the Debian system (such as the Debian Reference) |
| 69 | might be outdated and thus give wrong advice. In doubt, the |
| 70 | documentation listed above should take precedence. |
| 71 | </para> |
| 72 | </section> |
| 73 | <section> <title>Getting Support</title> |
| 74 | <para> |
| 75 | For your questions and comments, there is a <ulink |
| 76 | url="http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users"> |
| 77 | Debian-specific mailing list</ulink>. Please ask Debian-specific |
| 78 | questions there, and only write to the upstream exim-users mailing |
| 79 | list if |
| 80 | you are sure that your question is not Debian-specific. |
| 81 | Debian-specific questions are more likely to find answers on |
| 82 | our pkg-exim4-users mailing list, while complex custom |
| 83 | configuration issues might be more easily solved on the |
| 84 | upstream exim-users mailing list because of the broader and |
| 85 | more experienced audience there. You can subscribe to |
| 86 | pkg-exim4-users <ulink |
| 87 | url="http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users"> |
| 88 | via the subscription web page;</ulink> you need to be |
| 89 | subscribed to post. |
| 90 | </para> |
| 91 | <para> |
| 92 | If you think that your question might be more easily answered |
| 93 | if one knows a bit about your configuration, you might want to |
| 94 | execute <command>reportbug --subject="none" --offline --quiet |
| 95 | --severity=wishlist --body="none" --output=exim4.reportbug |
| 96 | exim4-config</command> on the system in question, answer yes |
| 97 | to both "include [extended] configuration" questions and include |
| 98 | the contents of the exim4.reportbug file generated by this |
| 99 | command with your question. Please check whether the file |
| 100 | contains any confidential information before sending. |
| 101 | </para> |
| 102 | </section> |
| 103 | <section> <title>Packaging</title> |
| 104 | <para> |
| 105 | Similar to the Apache2 package, Exim 4 is an entirely |
| 106 | different package that does not currently offer a smooth |
| 107 | upgrade path from Debian's Exim 3 packages. |
| 108 | </para> |
| 109 | <para> |
| 110 | It is the first Exim package in Debian that can be configured |
| 111 | using debconf. However, the entire configuration framework is |
| 112 | extremely flexible, allowing you to get exactly the amount of |
| 113 | control you need for the job at hand. |
| 114 | </para> |
| 115 | <section> <title>Feature Sets in the daemon packages</title> |
| 116 | <para> |
| 117 | To use Exim 4, you need at least the following packages: |
| 118 | <variablelist> |
| 119 | <varlistentry> |
| 120 | <term>exim4-base</term> |
| 121 | <listitem> |
| 122 | <simpara>support files for all Exim MTA (v4) packages</simpara> |
| 123 | </listitem> |
| 124 | </varlistentry> |
| 125 | <varlistentry> |
| 126 | <term>exim4-config</term> |
| 127 | <listitem> |
| 128 | <simpara>configuration for the Exim MTA (v4)</simpara> |
| 129 | </listitem> |
| 130 | </varlistentry> |
| 131 | <varlistentry> |
| 132 | <term>exim4-daemon-light</term> |
| 133 | <listitem> |
| 134 | <simpara>lightweight exim MTA (v4) daemon</simpara> |
| 135 | </listitem> |
| 136 | </varlistentry> |
| 137 | </variablelist> |
| 138 | </para> |
| 139 | <para> |
| 140 | Just apting the metapackage <command>exim4</command> will pull |
| 141 | in the other packages per dependency. You'll get an exim daemon |
| 142 | with minimal feature set (no external lookups). |
| 143 | </para> |
| 144 | <para> |
| 145 | If you need more advanced features like LDAP, sqlite, PostgreSQL |
| 146 | and MySQL data lookups, SASL and SPA SMTP authentication, embedded |
| 147 | Perl interpreter, and exiscan-acl for integration of |
| 148 | virus-scanners and SpamAssassin, you can replace |
| 149 | <command>exim4-daemon-heavy</command> instead of |
| 150 | <command>exim4-daemon-light</command>. Additionally, the source |
| 151 | package offers infrastructure to build your own custom-tailored |
| 152 | exim4-daemon-custom which exactly fits your special local needs. |
| 153 | The infrastructure to do so is already in place, see |
| 154 | debian/rules for instructions. |
| 155 | </para> |
| 156 | </section> |
| 157 | <section> <title>How to build a custom daemon</title> |
| 158 | <para> |
| 159 | The process of building a custom daemon is partially |
| 160 | documented in the <filename>debian/rules</filename> file |
| 161 | in the source package. Patches for more documentation are welcome. |
| 162 | </para> |
| 163 | </section> |
| 164 | </section> |
| 165 | </section> |
| 166 | <section> <title>Configuration of Exim 4 in the Debian packages</title> |
| 167 | <para> |
| 168 | Generally, the Debian Exim 4 packages are configured through |
| 169 | debconf. You have been asked some questions on package installation, |
| 170 | and your initial Exim configuration has been created from your |
| 171 | answers. You can repeat the configuration process any time by invoking |
| 172 | <command>dpkg-reconfigure exim4-config</command>. If you are an |
| 173 | experienced Exim administrator and prefer to have your own, |
| 174 | hand-crafted, non-automatic Exim configuration, you will find |
| 175 | information about how to do so in |
| 176 | <xref linkend="completely-different-configuration"/>. |
| 177 | </para> |
| 178 | <para> |
| 179 | The debconf-driven configuration is mainly geared for a |
| 180 | one-domain shell account machine/workstation with local delivery |
| 181 | as suggested by the original upstream default configuration. |
| 182 | If you configure the packages to handle more than one local |
| 183 | domain, all local domains are treated identically. The domain |
| 184 | part is not used for routing and filtering decisions. |
| 185 | </para> |
| 186 | <para> |
| 187 | Despite the default configuration being extended somewhat from |
| 188 | the original upstream, chances are that you'll need to |
| 189 | manually change the Exim configuration with an editor if you intend to |
| 190 | do something that is not covered by the debconf-driven configuration. |
| 191 | It has never been the packages' intention to offer all possible |
| 192 | configuration methods through debconf. The configuration files are |
| 193 | there to be changed, feel free to do so if you see fit. The Debian |
| 194 | Exim 4 maintainers have tried to make the configuration as flexible as |
| 195 | possible so that manual intervention can be minimized. |
| 196 | </para> |
| 197 | <para> |
| 198 | If you need to make manual changes to the Exim configuration, |
| 199 | please be familiar with how Exim works. At minimum, have read this |
| 200 | README file and the manpages delivered with the Debian Exim 4 |
| 201 | packages, and <filename>/usr/share/doc/exim4-base/spec.txt.gz</filename> |
| 202 | chapters <phrase>"How Exim receives and delivers mail"</phrase> and |
| 203 | <phrase>"The Exim run time configuration file"</phrase>. |
| 204 | <filename>spec.txt.gz</filename> is an excellent reference. |
| 205 | </para> |
| 206 | <para> |
| 207 | Please note that while most free-form fields in the |
| 208 | debconf-driven configuration have the entered string end up |
| 209 | verbatim in Exim's configuration file (and thus using more |
| 210 | advanced features like host, address and domain lists is possible |
| 211 | and will probably work), this is not officially supported. |
| 212 | Only plain lists are supported in the debconf dialogs. You may |
| 213 | use more advanced features, but they may stop working any time |
| 214 | during upgrades. |
| 215 | </para> |
| 216 | <section> <title>The Configuration System</title> |
| 217 | <section id="debconf-questions"> <title>The Debconf questions</title> |
| 218 | <para> |
| 219 | In this section, we try to document and explain the debconf |
| 220 | questions, which are themselves limited to a small screen of |
| 221 | information and might leave questions unanswered. Since you |
| 222 | can usually read this file only after having answered the |
| 223 | questions, the process can always be repeated by invoking |
| 224 | <command>dpkg-reconfigure exim4-config.</command> |
| 225 | <filename>/etc/exim4/update-exim4.conf.conf</filename>, |
| 226 | documented in the <command>update-exim4.conf</command> |
| 227 | manual page, is |
| 228 | a simple shell-script snippet used to store the answers |
| 229 | that you passed to debconf when initially configuring Exim. |
| 230 | You may also modify this file with an editor of your choice. |
| 231 | The package maintainer scripts can handle this and will |
| 232 | preserve your changes. |
| 233 | </para> |
| 234 | <section> <title>General type of mail configuration</title> |
| 235 | <para> |
| 236 | This is the main configuration question which will |
| 237 | control which of the remaining questions are |
| 238 | presented to you. It also controls things like daemon |
| 239 | invocation and delivery of outgoing mail. |
| 240 | </para> |
| 241 | <section> <title> internet site; mail is sent and |
| 242 | received directly using SMTP</title> |
| 243 | <para> |
| 244 | This option is suitable for a standalone system |
| 245 | with full internet connectivity. |
| 246 | </para> |
| 247 | <itemizedlist> |
| 248 | <listitem> |
| 249 | <para> |
| 250 | The Exim SMTP daemon will accept messages |
| 251 | to local domains, and deliver them locally. |
| 252 | </para> |
| 253 | </listitem> |
| 254 | <listitem> |
| 255 | <para> |
| 256 | Outgoing mail will be delivered directly |
| 257 | to the mail exchange servers of the |
| 258 | recipient domain |
| 259 | </para> |
| 260 | </listitem> |
| 261 | </itemizedlist> |
| 262 | </section> |
| 263 | <section> <title> mail sent by smarthost; received via |
| 264 | SMTP or fetchmail</title> |
| 265 | <para> |
| 266 | This option is suitable for a standalone client system |
| 267 | which has restricted internet connectivity, for |
| 268 | example on a residential connection where an SMTP |
| 269 | smarthost is used. Some ISPs block outgoing SMTP |
| 270 | connections to combat the spam problem, thus |
| 271 | requiring the use of their smarthosts. It is |
| 272 | generally a good idea to use the ISPs smart host |
| 273 | if one is connected with a dynamic IP address |
| 274 | since quite a few sites do not accept mail |
| 275 | directly delivered from a dial-in pool. |
| 276 | </para> |
| 277 | <para> |
| 278 | fetchmail can be used to retrieve incoming mail |
| 279 | from the ISP's POP3 or IMAP mail server and |
| 280 | deliver it to Exim via SMTP. |
| 281 | </para> |
| 282 | <itemizedlist> |
| 283 | <listitem> |
| 284 | <para> |
| 285 | The Exim SMTP daemon will accept messages |
| 286 | to local domains, and deliver them locally. |
| 287 | </para> |
| 288 | </listitem> |
| 289 | <listitem> |
| 290 | <para> |
| 291 | Outgoing mail will always be delivered to |
| 292 | the smarthost configured in exim4. |
| 293 | </para> |
| 294 | </listitem> |
| 295 | </itemizedlist> |
| 296 | </section> |
| 297 | <section> <title>mail sent by smarthost; no local mail</title> |
| 298 | <para> |
| 299 | This option is suitable for a client system in a |
| 300 | computer pool which is not responsible for a local |
| 301 | e-mail domain. All locally generated e-mail is |
| 302 | sent to the smarthost without any local domains. |
| 303 | </para> |
| 304 | </section> |
| 305 | <section> <title>local delivery only; not on a network</title> |
| 306 | <para> |
| 307 | This option is suitable for a standalone system |
| 308 | with no networking at all. Only messages for configured |
| 309 | local domains are accepted and delivered locally; |
| 310 | messages for all other domains are rejected: |
| 311 | ``Mailing to remote domains not supported''. |
| 312 | </para> |
| 313 | </section> |
| 314 | <section> <title>no configuration at this time</title> |
| 315 | <para> |
| 316 | This option disables most of Debian's automatisms |
| 317 | and leaves exim in an unconfigured state. |
| 318 | update-exim4.conf will still copy |
| 319 | <filename>/etc/exim4/exim4.conf.template</filename> |
| 320 | or concatenate the files from |
| 321 | <filename>/etc/exim4/conf.d,</filename> and will |
| 322 | not generate any configuration control macros. |
| 323 | Unless you manually edit the configuration source, |
| 324 | this will leave Exim with a syntactically invalid |
| 325 | configuration file, thus in a state where the |
| 326 | daemon won't even start. |
| 327 | </para> |
| 328 | <para> |
| 329 | Only choose this option if you know what you're |
| 330 | doing and are prepared to create your own Exim |
| 331 | configuration. |
| 332 | </para> |
| 333 | <para> |
| 334 | dpkg-conffile handling is still in place, and you |
| 335 | will be offered updates for configuration |
| 336 | snippets, as soon as they become available. |
| 337 | </para> |
| 338 | </section> |
| 339 | </section> |
| 340 | <section> <title>System mail name</title> |
| 341 | <para> |
| 342 | The "mail name" is the domain name used to "qualify" |
| 343 | mail addresses without a domain name. |
| 344 | </para> |
| 345 | <para> |
| 346 | This name will also be used by other programs. It |
| 347 | should be the single, full domain name (FQDN). |
| 348 | </para> |
| 349 | <para> |
| 350 | For example, if a mail address on the local host is |
| 351 | foo@example.org, then the correct value for this |
| 352 | option would be example.org. |
| 353 | </para> |
| 354 | <para> |
| 355 | Exim, as a rule, handles only fully qualified mail |
| 356 | addresses, that is, addresses with a local part, an @ |
| 357 | sign and a domain. If confronted with an unqualified |
| 358 | address, that is, one without @ sign and without |
| 359 | domain, first thing exim does is qualify the address |
| 360 | by adding the @ sign and a domain. |
| 361 | </para> |
| 362 | <para> |
| 363 | This qualification happens for all addresses exim |
| 364 | encounters, be it sender, recipient or else. |
| 365 | </para> |
| 366 | <para> |
| 367 | The domain name used to qualify unqualified mail addresses |
| 368 | is called ``mail name'' on Debian systems and entered |
| 369 | in this debconf dialog. What you enter here will end |
| 370 | up in <filename>/etc/mailname,</filename> which is a |
| 371 | file that might be used by other programs as well. |
| 372 | </para> |
| 373 | <para> |
| 374 | In some configuration types, the package configuration |
| 375 | will offer you, at a later step, to hide this name |
| 376 | from outgoing messages by rewriting the headers. |
| 377 | </para> |
| 378 | </section> |
| 379 | <section> <title>IP addresses to listen on for incoming SMTP |
| 380 | connections</title> |
| 381 | <para> |
| 382 | Please enter a semicolon-separated list of IP addresses. |
| 383 | The Exim SMTP listener daemon will listen on all IP |
| 384 | addresses listed here. |
| 385 | </para> |
| 386 | <para> |
| 387 | An empty value will cause Exim to listen for connections |
| 388 | on all available network interfaces. |
| 389 | </para> |
| 390 | <para> |
| 391 | If this system does only receive e-mail directly from |
| 392 | local services (and not from other hosts), |
| 393 | it is suggested to prohibit external connections to the |
| 394 | local Exim daemon. Such services include e-mail |
| 395 | programs (MUSs) which talk to localhost only as well as |
| 396 | fetchmail. External connections are impossible when |
| 397 | 127.0.0.1 is entered here, as this will disable listening |
| 398 | on public network interfaces. |
| 399 | </para> |
| 400 | <para> |
| 401 | Do not change this unless you know what you are doing. |
| 402 | Altering this value could post a security risk to your |
| 403 | system. For most users, the default value is sufficient. |
| 404 | </para> |
| 405 | </section> |
| 406 | <section> <title>Other destinations for which mail is accepted</title> |
| 407 | <para> |
| 408 | Please enter a semicolon-separated list of recipient |
| 409 | domains for which this machine should consider itself |
| 410 | the final destination. These domains are commonly |
| 411 | called 'local domains'. The local hostname and 'localhost' |
| 412 | are always added to the list given here. |
| 413 | </para> |
| 414 | <para> |
| 415 | By default all local domains will be treated |
| 416 | identically. If both a.example and b.example are |
| 417 | local domains, acc@a.example and acc@b.example will |
| 418 | be delivered to the same final destination. If |
| 419 | different domain names should be treated differently, |
| 420 | it is necessary to edit the config files afterwards. |
| 421 | </para> |
| 422 | <para> |
| 423 | The answer to this question ends up in the list of |
| 424 | domains that Exim will consider local domains. Mail |
| 425 | for recipients in one of these domains will be |
| 426 | subject to local alias expansion and then delivered |
| 427 | locally in the appropriate configuration types. |
| 428 | </para> |
| 429 | </section> |
| 430 | <section> <title>Domains to relay mail for</title> |
| 431 | <para> |
| 432 | Please enter a semicolon-separated list of recipient |
| 433 | domains for which this system will relay mail, for |
| 434 | example as a fallback MX or mail gateway. This means |
| 435 | that this system will accept mail for these domains |
| 436 | from anywhere on the Internet and deliver them |
| 437 | according to local delivery rules. |
| 438 | </para> |
| 439 | <para> |
| 440 | Do not mention local domains here. Wildcards may be used. |
| 441 | </para> |
| 442 | <para> |
| 443 | The answer to this question is a list of the domains |
| 444 | for which Exim will relay messages coming in from anywhere |
| 445 | on the Internet. |
| 446 | </para> |
| 447 | </section> |
| 448 | <section> <title>Machines to relay mail for</title> |
| 449 | <para> |
| 450 | Please enter a semicolon-separated list of IP address |
| 451 | ranges for which this system will unconditionally relay |
| 452 | mail, functioning as a smarthost. |
| 453 | </para> |
| 454 | <para> |
| 455 | You should use the standard address/prefix format |
| 456 | (e.g. 194.222.242.0/24 or 5f03:1200:836f::/48). |
| 457 | </para> |
| 458 | <para> |
| 459 | If this system should not be a smarthost for any |
| 460 | other host, leave this list blank. |
| 461 | </para> |
| 462 | <para> |
| 463 | Please note that systems not listed here can still use |
| 464 | SMTP AUTH to relay through this system. If this system |
| 465 | only has clients on dynamic IP addresses that use SMTP |
| 466 | AUTH, leave this list blank as well. Do |
| 467 | <emphasis>NOT</emphasis> list 0.0.0.0/0! |
| 468 | </para> |
| 469 | <para> |
| 470 | Warning: While it is possible to use |
| 471 | host<emphasis>names</emphasis> instead of IP addresses in this |
| 472 | list extra care needs to be taken in this case. |
| 473 | <emphasis>Unresolvable names in the host list will break |
| 474 | relaying.</emphasis> See |
| 475 | Exim specification chapter <phrase>"Domain, host, address, and |
| 476 | local part lists"</phrase> |
| 477 | and the exim4-config_files man page. |
| 478 | </para> |
| 479 | </section> |
| 480 | <section> <title>IP address or host name of the outgoing |
| 481 | smarthost</title> |
| 482 | <para> |
| 483 | Please enter the IP address or the host name of a mail |
| 484 | server that this system should use as outgoing |
| 485 | smarthost. If the smarthost only accepts your mail on |
| 486 | a port different from TCP/25, append two colons and |
| 487 | the port number (for example smarthost.example::587 or |
| 488 | 192.168.254.254::2525). Colons in IPv6 addresses need |
| 489 | to be doubled. |
| 490 | </para> |
| 491 | <para> |
| 492 | If the smarthost requires authentication, please refer |
| 493 | to <xref linkend="smtp-auth"/> for notes about setting |
| 494 | up SMTP authentication. |
| 495 | </para> |
| 496 | <para> |
| 497 | Multiple smarthost entries are permitted, semicolon |
| 498 | separated. Each of the hosts is tried, in the order |
| 499 | specified (See Exim specification, chapter |
| 500 | <phrase>"The manualroute router"</phrase>, section |
| 501 | <phrase>"How the list of hosts is used"</phrase>.) |
| 502 | </para> |
| 503 | </section> |
| 504 | <section> <title>Hide local mail name in outgoing mail</title> |
| 505 | <para> |
| 506 | The headers of outgoing mail can be rewritten to make |
| 507 | it appear to have been generated on a different |
| 508 | system, replacing the local host name in From, |
| 509 | Reply-To, Sender and Return-Path. |
| 510 | </para> |
| 511 | </section> |
| 512 | <section> <title>Visible domain name for local users</title> |
| 513 | <para> |
| 514 | If you ask Exim to hide the local mail name in |
| 515 | outgoing mail, it will next ask you for the domain |
| 516 | name that should be visible for your local users. |
| 517 | These information is then used to establish the |
| 518 | appropriate rewriting rules. |
| 519 | </para> |
| 520 | </section> |
| 521 | <section> <title>Keep number of DNS queries minimal |
| 522 | (Dial-on-Demand)</title> |
| 523 | <para> |
| 524 | In normal mode of operation Exim does DNS lookups at |
| 525 | startup, and when receiving or delivering messages. |
| 526 | This is for logging purposes and allows keeping down |
| 527 | the number of hard-coded values in the configuration. |
| 528 | </para> |
| 529 | <para> |
| 530 | If this system does not have a DNS full service |
| 531 | resolver available at all times (for example if its |
| 532 | Internet access is a dial-up line using |
| 533 | dial-on-demand), this might have unwanted |
| 534 | consequences. For example, starting up Exim or |
| 535 | running the queue (even with no messages waiting) |
| 536 | might trigger a costly dial-up-event. |
| 537 | </para> |
| 538 | <para> |
| 539 | This option should be selected if this system is |
| 540 | using Dial-on-Demand. If it has always-on Internet |
| 541 | access, this option should be disabled. |
| 542 | </para> |
| 543 | </section> |
| 544 | <section><title>Delivery method for local mail</title> |
| 545 | <para> |
| 546 | Exim is able to store locally delivered mail in |
| 547 | different formats. The most commonly used ones are |
| 548 | mbox and Maildir. mbox uses a single file for the |
| 549 | complete mail folder stored in /var/mail/. With |
| 550 | Maildir format every single message is stored in a |
| 551 | separate file in ~/Maildir/. |
| 552 | </para> |
| 553 | <para> |
| 554 | Please note that most mail tools in Debian expect the |
| 555 | local delivery method to be mbox in their default. |
| 556 | </para> |
| 557 | </section> |
| 558 | <section> <title>Split configuration into small files</title> |
| 559 | <para> |
| 560 | Our packages offer two (actually three, see |
| 561 | <xref linkend="completely-different-configuration"/>) |
| 562 | possibilities: |
| 563 | </para> |
| 564 | <orderedlist> |
| 565 | <listitem> |
| 566 | <simpara> |
| 567 | Generate Exim's configuration from |
| 568 | <filename>/etc/exim4/exim4.conf.template,</filename> |
| 569 | which is basically a normal Exim run-time |
| 570 | configuration file which will be supplemented |
| 571 | with some macros generated from Debconf in a |
| 572 | post-processing step before it is passed to exim. |
| 573 | </simpara> |
| 574 | </listitem> |
| 575 | <listitem> |
| 576 | <simpara> |
| 577 | Generate Exim's configuration from the |
| 578 | multiple files in |
| 579 | <filename>/etc/exim4/conf.d/</filename>. The |
| 580 | directories in |
| 581 | <filename>/etc/exim4/conf.d/</filename> |
| 582 | correspond to the sections of the Exim |
| 583 | run-time configuration file, so you should |
| 584 | easily find your way around there. |
| 585 | </simpara> |
| 586 | </listitem> |
| 587 | </orderedlist> |
| 588 | <para> |
| 589 | Splitting the configuration across multiple files |
| 590 | means that you have the actual configuration file |
| 591 | automatically generated from the files below |
| 592 | <filename>/etc/exim4/conf.d/</filename> by invoking |
| 593 | <command>update-exim4.conf</command>. Each section |
| 594 | of Exim's configuration has its own subdirectory and |
| 595 | the files in there are supposed to be read in |
| 596 | alphanumeric order. |
| 597 | <filename>router/00_exim4-config_header</filename> |
| 598 | is followed by |
| 599 | <filename>router/100_exim4-config_domain_literal</filename>, |
| 600 | ... |
| 601 | </para> |
| 602 | <para> |
| 603 | If you chose unsplit configuration, |
| 604 | <command>update-exim4.conf</command> builds the |
| 605 | configuration from |
| 606 | <filename>/etc/exim4/exim4.conf.template</filename>, |
| 607 | which is basically the files from |
| 608 | <filename>/etc/exim4/conf.d/</filename> concatenated |
| 609 | together at package build time, and thus guarantees |
| 610 | consistency on the target system. |
| 611 | </para> |
| 612 | <para> |
| 613 | In both cases, <command>update-exim4.conf</command> |
| 614 | generates exim configuration macros from the debconf |
| 615 | configuration values and puts them into |
| 616 | the actual configuration file, which is then used by |
| 617 | the Exim daemon. See the |
| 618 | <command>update-exim4.conf</command> manual |
| 619 | page for more in-depth information about this |
| 620 | mechanism. |
| 621 | </para> |
| 622 | <para> |
| 623 | Benefits of the split configuration approach: |
| 624 | <itemizedlist> |
| 625 | <listitem> |
| 626 | <simpara> |
| 627 | it means less work for you when upgrading. |
| 628 | If we shipped one big file and modified |
| 629 | for example the Maildir transport in a new |
| 630 | version you won't have to do manual |
| 631 | conffile merging unless you had changed |
| 632 | exactly <emphasis>this</emphasis> |
| 633 | transport. |
| 634 | </simpara> |
| 635 | </listitem> |
| 636 | <listitem> |
| 637 | <simpara> |
| 638 | It allows other packages (e.g. sa-exim) to |
| 639 | modify Exim's configuration by dropping |
| 640 | files into |
| 641 | <filename>/etc/exim4/conf.d</filename>. |
| 642 | This needs, however quite exact syncing |
| 643 | between the exim4 packages and the other, |
| 644 | cooperating package. |
| 645 | </simpara> |
| 646 | </listitem> |
| 647 | </itemizedlist> |
| 648 | </para> |
| 649 | <para> |
| 650 | Drawbacks of the split configuration approach: |
| 651 | <itemizedlist> |
| 652 | <listitem> |
| 653 | <simpara> |
| 654 | It is more fragile. If files from |
| 655 | different sources (package, manually |
| 656 | changed, or other package) get out of |
| 657 | sync, it is possible for Exim to break |
| 658 | until you manually correct this. This can |
| 659 | for example happen if we decide to add a |
| 660 | new option to the Debian setup of a later |
| 661 | version, and you have already set this |
| 662 | option in a local file. |
| 663 | </simpara> |
| 664 | </listitem> |
| 665 | </itemizedlist> |
| 666 | </para> |
| 667 | <para> |
| 668 | Benefits of the unsplit configuration approach: |
| 669 | <itemizedlist> |
| 670 | <listitem> |
| 671 | <simpara> |
| 672 | People familiar with configuring Exim may |
| 673 | find this approach easier to understand as |
| 674 | <filename>exim4.conf.template</filename> |
| 675 | basically is a complete Exim configuration |
| 676 | file which will only undergo some basic |
| 677 | string replacement before is it passed to |
| 678 | exim. |
| 679 | </simpara> |
| 680 | </listitem> |
| 681 | <listitem> |
| 682 | <simpara> |
| 683 | Split-config's fragility mentioned |
| 684 | above does not occur. |
| 685 | </simpara> |
| 686 | </listitem> |
| 687 | </itemizedlist> |
| 688 | </para> |
| 689 | <para> |
| 690 | Drawbacks of the unsplit configuration approach: |
| 691 | <itemizedlist> |
| 692 | <listitem> |
| 693 | <simpara> |
| 694 | Will require manual intervention in case of an |
| 695 | upgrade. |
| 696 | </simpara> |
| 697 | </listitem> |
| 698 | </itemizedlist> |
| 699 | </para> |
| 700 | <para> |
| 701 | If in doubt go for the unsplit config, because it is |
| 702 | easier to roll back to Debian's default configuration |
| 703 | in one step. If you intend to do many changes to the |
| 704 | Debian setup, you might want to use the split config |
| 705 | at the price of having to more closely examine the |
| 706 | config file after an update. |
| 707 | </para> |
| 708 | <para> |
| 709 | We'd appreciate a patch that uses ucf and the |
| 710 | 3-way-merge mechanism offered by that package. It |
| 711 | might be the best way to handle the big configuration |
| 712 | file. |
| 713 | </para> |
| 714 | <para> |
| 715 | If you are using unsplit configuration, have local |
| 716 | changes to <filename>/etc/exim4/conf.d/</filename> |
| 717 | (either made by yourself or by other packages dropping |
| 718 | their own routers or transports in) and want to |
| 719 | re-generate |
| 720 | <filename>/etc/exim4/exim4.conf.template</filename> to |
| 721 | activate these changes, you can do so by using |
| 722 | <command>update-exim4.conf.template</command>. |
| 723 | </para> |
| 724 | </section> |
| 725 | </section> |
| 726 | <section> <title>Access Control in the default configuration</title> |
| 727 | <para> |
| 728 | The Debian exim 4 packages come with a default configuration |
| 729 | that allows flexible access control and blacklisting of |
| 730 | sites and hosts. The acls involved can be found in |
| 731 | /etc/exim4/conf.d/acl, or in /etc/exim4/exim4.conf.template, |
| 732 | depending on which configuration scheme you use. Most |
| 733 | rejections of messages due to this mechanism happen at RCPT |
| 734 | time. Local configuration of the mechanisms happens through |
| 735 | data files in /etc/exim4 or via Exim macros that you can set |
| 736 | in /etc/exim4/conf.d/main, so there is normally no need to |
| 737 | change the files in the acl subdirectory in a split-config |
| 738 | setup. If you use the non-split config, you need to edit |
| 739 | /etc/exim4/exim4.conf.template, which, as a big |
| 740 | dpkg-conffile, won't give you any advantage of the .ifdef |
| 741 | scheme. |
| 742 | </para> |
| 743 | <para> |
| 744 | The data files are documented in the exim4-config_files man |
| 745 | page. |
| 746 | </para> |
| 747 | <para> |
| 748 | The access lists delivered with the exim4 packages also |
| 749 | contain quite a few configuration options that are too |
| 750 | restrictive to be active by default on a real-life site. |
| 751 | These are masked by .ifdef statements, can be activated by |
| 752 | setting the appropriate macros, and are documented in the |
| 753 | ACL files itself. |
| 754 | </para> |
| 755 | </section> |
| 756 | <section id='macros'> <title>Using Exim Macros to control the |
| 757 | configuration</title> |
| 758 | <para> |
| 759 | Our configuration can be controlled in a limited way by |
| 760 | setting macros. That way, you can switch on and off certain |
| 761 | parts of the default configuration and/or override values set |
| 762 | in Debconf without having to touch the dpkg-conffiles. While |
| 763 | touching dpkg-conffiles itself is explicitly allowed and wanted, |
| 764 | it can be quite a nuisance to be asked on package upgrade |
| 765 | whether one wants to use the locally changed file or the |
| 766 | file changed by the package maintainer. |
| 767 | </para> |
| 768 | <para> |
| 769 | Whenever you see an <command>.ifdef</command> or |
| 770 | <command>.ifndef</command> clause in the configuration file, |
| 771 | you can control the appropriate clause by setting the macro in |
| 772 | a local configuration file. For split configuration, you can |
| 773 | drop the local configuration file anywhere in |
| 774 | <filename>/etc/exim4/conf.d/main</filename>. Just make sure it |
| 775 | gets read before the macro is first used. |
| 776 | <filename>000_localmacros</filename> is a possible name, |
| 777 | guaranteeing first order. For a non-split configuration, |
| 778 | <filename>/etc/exim4/exim4.conf.localmacros</filename> gets |
| 779 | read before |
| 780 | <filename>/etc/exim4/exim4.conf.template</filename>. To |
| 781 | actually set the macro <varname>EXIM4_EXAMPLE</varname> to the |
| 782 | value "this is a sample", write the following line |
| 783 | </para> |
| 784 | <para> |
| 785 | EXIM4_EXAMPLE = this is a sample |
| 786 | </para> |
| 787 | <para> |
| 788 | into the appropriate file. For more detailed discussion of the |
| 789 | general macro mechanism, see the Exim specification, chapter |
| 790 | <phrase>"The Exim run time configuration file"</phrase>, for |
| 791 | details how macro expansion works. |
| 792 | </para> |
| 793 | </section> |
| 794 | <section> <title>How does this work?</title> |
| 795 | <para> |
| 796 | The script <command>update-exim4.conf</command> parses the |
| 797 | <filename>/etc/exim4/update-exim4.conf.conf</filename> file |
| 798 | and provides the configuration for the exim daemon. |
| 799 | </para> |
| 800 | <para> |
| 801 | Depending on the value of |
| 802 | <varname>dc_use_split_config</varname>, it either |
| 803 | <itemizedlist> |
| 804 | <listitem> |
| 805 | <simpara> |
| 806 | takes all the files below |
| 807 | <filename>/etc/exim4/conf.d/</filename> and |
| 808 | concatenates them together or |
| 809 | </simpara> |
| 810 | </listitem> |
| 811 | <listitem> |
| 812 | <simpara> |
| 813 | uses <filename>exim4.conf.template</filename> as |
| 814 | input. |
| 815 | </simpara> |
| 816 | </listitem> |
| 817 | </itemizedlist> |
| 818 | The debconf-managed information from |
| 819 | <filename>/etc/exim4/update-exim4.conf.conf</filename> is |
| 820 | merged into the generated configuration file by generating a |
| 821 | number of Exim configuration macros. |
| 822 | </para> |
| 823 | <para> |
| 824 | <varname>DCsmarthost</varname>, for example, is set to the |
| 825 | value of <varname>$dc_smarthost</varname> |
| 826 | in <filename>/etc/exim4/update-exim4.conf.conf</filename> |
| 827 | which holds the answer to "Which machine will act as the |
| 828 | smarthost and handle outgoing mail?" |
| 829 | </para> |
| 830 | <para> |
| 831 | The result of these operations is saved as |
| 832 | <filename>/var/lib/exim4/config.autogenerated</filename>, |
| 833 | which is <emphasis>not</emphasis> a dpkg-conffile! Manual |
| 834 | changes to this file will be overwritten by |
| 835 | <command>update-exim4.conf</command>. |
| 836 | </para> |
| 837 | <para> |
| 838 | Please consult <command>update-exim4.conf</command> manpage |
| 839 | for more detailed information. |
| 840 | </para> |
| 841 | <para> |
| 842 | <command>update-exim4.conf</command> is invoked by the init |
| 843 | script prior to any operation that may invoke an exim process, |
| 844 | and gives an error message if the generated config file is |
| 845 | syntactically invalid. If you want to activate your changes to |
| 846 | files in conf.d/ just execute <command>invoke-rc.d exim4 restart</command>. |
| 847 | </para> |
| 848 | </section> |
| 849 | <section id="howto-change-config"><title>How do I do minor tweaks to the configuration?</title> |
| 850 | <para> |
| 851 | Some times, you want to do minor adjustments to the Exim |
| 852 | configuration to make Exim behave exactly like you want it |
| 853 | to behave. There are the following possibilities to modify |
| 854 | Exim's behavior. |
| 855 | </para> |
| 856 | <section><title>Adjustments supported by the debconf configuration</title> |
| 857 | <para> |
| 858 | If you want to modify parameters that are supported by the |
| 859 | debconf configuration, things are easy. Just invoke |
| 860 | <command>dpkg-reconfigure exim4-config</command> or hand-edit |
| 861 | <filename>/etc/exim4/update-exim4.conf.conf</filename> to your |
| 862 | liking and restart Exim. |
| 863 | </para> |
| 864 | <para> |
| 865 | You can find explanation of the debconf questions in <xref |
| 866 | linkend="debconf-questions"/>. |
| 867 | Additionally, |
| 868 | <filename>/etc/exim4/update-exim4.conf.conf</filename> |
| 869 | is documented in the <command>update-exim4.conf</command> |
| 870 | man page. |
| 871 | </para> |
| 872 | </section> |
| 873 | <section><title>Adjustments controlled by macros in the Debian Exim configuration</title> |
| 874 | <para> |
| 875 | Some aspects of the Debian Exim configuration can be |
| 876 | controlled by Exim macros. To find out about these, you |
| 877 | need basic understanding of Exim configuration. Just look |
| 878 | in our Exim configuration and see which macro needs to be |
| 879 | set to a different value to alter Exim's behavior. |
| 880 | </para> |
| 881 | <para> |
| 882 | <xref linkend="macros"/> gives a closer explanation about |
| 883 | how to do this. |
| 884 | </para> |
| 885 | </section> |
| 886 | <section><title>Making direct changes to the Debian Exim configuration</title> |
| 887 | <para> |
| 888 | You can, of course, make direct change to the |
| 889 | configuration. All configuration files in /etc/exim4 are |
| 890 | dpkg-conffiles, and you can thus edit them any time. Your |
| 891 | changes will be preserved through updates. You need to |
| 892 | know about how to configure Exim to be successful. |
| 893 | </para> |
| 894 | <para> |
| 895 | If you use unsplit configuration, edit |
| 896 | <filename>/etc/exim4/exim4.conf.template</filename>. If you use |
| 897 | split configuration, edit the Exim configuration snippets in |
| 898 | <filename>/etc/exim4/conf.d</filename>. |
| 899 | </para> |
| 900 | <para> |
| 901 | More information about how the Exim configuration is built |
| 902 | can be found in this document and in the |
| 903 | <command>update-exim4.conf</command> manual page. |
| 904 | </para> |
| 905 | </section> |
| 906 | </section> |
| 907 | <section id="completely-different-configuration"> <title>Using a completely different configuration scheme</title> |
| 908 | <para> |
| 909 | If you are an experienced Exim administrator, you might feel |
| 910 | working with our pre-fabricated configuration |
| 911 | cumbersome and complex. You might feel right if you need to |
| 912 | make more complex changes and do not need to receive updates |
| 913 | from us. This section is going to tell about how to use |
| 914 | your own configuration. |
| 915 | </para> |
| 916 | <para> |
| 917 | But, you might profit from keeping the Debian magic. Most |
| 918 | files that come with Debian exim4 are conffiles. Debian is |
| 919 | going to care about your changes and keeps them around. |
| 920 | Additionally, a lot of configuration options can be |
| 921 | overridden with a macro, which does not require you to |
| 922 | actually change our configuration file. A lot of people are |
| 923 | using our configuration scheme, and maybe it is going to |
| 924 | save you a lot of time if you decide to spend some time |
| 925 | familiarizing yourself with our scheme. |
| 926 | </para> |
| 927 | <section> <title>Override exim4-config configuration magic</title> |
| 928 | <para> |
| 929 | If you are only running a small number of systems and |
| 930 | want to completely disable Debian's magic, just take |
| 931 | your monolithic configuration file and install it as |
| 932 | <filename>/etc/exim4/exim4.conf</filename>. Exim will |
| 933 | use that file verbatim. To have something to start, |
| 934 | you can either take |
| 935 | <filename>/etc/exim4/exim4.conf.template</filename>, |
| 936 | run <command>update-exim4.conf --keepcomments --output |
| 937 | /etc/exim4/exim4.conf</command>, or use upstream's |
| 938 | default configuration file that is installed as |
| 939 | <filename>/usr/share/doc/exim4-base/examples/example.conf.gz</filename>. |
| 940 | You are going to lose all magic you get from packaging |
| 941 | though, so you need to be familiar with Exim to build |
| 942 | an actually working config. |
| 943 | </para> |
| 944 | <para> |
| 945 | <filename>/var/lib/exim4/config.autogenerated</filename>, |
| 946 | the file generated by |
| 947 | <command>update-exim4.conf</command>, is ignored as soon |
| 948 | as <filename>/etc/exim4/exim4.conf</filename> is found. |
| 949 | You should not edit |
| 950 | <filename>/etc/exim4/exim4.conf</filename> directly when |
| 951 | Exim is running, because the forked processes Exim starts |
| 952 | for SMTP receiving or queue running would use the new |
| 953 | configuration file, while the original main exim-daemon |
| 954 | would still use the old configuration file. |
| 955 | </para> |
| 956 | <para> |
| 957 | Some third-party HOWTOs that reference Debian and |
| 958 | claim to make things easy suggest dumping a |
| 959 | pre-fabricated, static config file to |
| 960 | <filename>/etc/exim4/exim4.conf</filename>. This is |
| 961 | considered bad advice by the Debian maintainers since |
| 962 | you are going to disable all updates and service magic |
| 963 | that Debian might deliver in the future this way. If |
| 964 | you do not know exactly what you're doing here, this |
| 965 | is a bad choice. We try to comment on external HOWTOs |
| 966 | found on the web in the <ulink |
| 967 | url="http://wiki.debian.org/PkgExim4UserFAQ">Debian |
| 968 | Exim4 User FAQ</ulink> to help you find out which |
| 969 | advice to follow. |
| 970 | </para> |
| 971 | </section> |
| 972 | <section> <title>Replacing exim4-config with your own exim4 configuration package.</title> |
| 973 | <para> |
| 974 | We split off Exim's configuration system (debconf, |
| 975 | <command>update-exim4.conf</command>, and the files in |
| 976 | <filename>/etc/exim4/conf.d)</filename> to a separate |
| 977 | package, exim4-config. If you want to, you can replace |
| 978 | exim4-config by something entirely different. The other |
| 979 | packages don't care. Your package needs to: |
| 980 | <itemizedlist> |
| 981 | <listitem> |
| 982 | <simpara> |
| 983 | Provides: exim4-config-2, Conflicts: |
| 984 | exim4-config-2,exim4-config |
| 985 | </simpara> |
| 986 | </listitem> |
| 987 | <listitem> |
| 988 | <simpara> |
| 989 | drop the Exim 4 configuration either into |
| 990 | <filename>/var/lib/exim4/config.autogenerated</filename> |
| 991 | or into <filename>/etc/exim4/exim4.conf</filename>. |
| 992 | </simpara> |
| 993 | </listitem> |
| 994 | </itemizedlist> |
| 995 | Your package must provide an executable <command>update-exim4.conf</command> |
| 996 | that must be in root's path (<filename>/usr/sbin</filename> recommended). The init |
| 997 | script will invoke that executable prior to invoking the |
| 998 | actual exim daemon. If you do not need that script, have it exit 0. |
| 999 | </para> |
| 1000 | <para> |
| 1001 | If you want to create your own configuration packages, there is a |
| 1002 | number of helpers available. |
| 1003 | <itemizedlist> |
| 1004 | <listitem> |
| 1005 | <simpara> |
| 1006 | The Exim 4 Debian svn repository holds sources for a |
| 1007 | exim4-config-simple package which contains a simple, not |
| 1008 | debconf-driven configuration scheme as an example which can |
| 1009 | be used as a template for a classical, exim4.conf based |
| 1010 | configuration scheme. |
| 1011 | </simpara> |
| 1012 | </listitem> |
| 1013 | <listitem> |
| 1014 | <simpara> |
| 1015 | The Exim 4 Debian svn repository holds sources for a |
| 1016 | exim4-config-medium package which contains the conf.d |
| 1017 | driven configuration of the main package with the |
| 1018 | debconf interaction removed. This can be used to create |
| 1019 | your own non-debconf configuration package that uses the |
| 1020 | conf.d mechanism. |
| 1021 | </simpara> |
| 1022 | </listitem> |
| 1023 | <listitem> |
| 1024 | <simpara> |
| 1025 | Finally, you can invoke the script |
| 1026 | <filename>debian/config-custom/create-custom-config-package</filename> |
| 1027 | which will create a new source package |
| 1028 | "exim4-config-custom" with the debconf-driven config |
| 1029 | scheme of exim4-config for your local modification. |
| 1030 | </simpara> |
| 1031 | </listitem> |
| 1032 | </itemizedlist> |
| 1033 | Please note that exim4-config-simple and |
| 1034 | exim4-config-medium are only targeted to be used as a |
| 1035 | template. The configurations contained are not |
| 1036 | suitable for productive use. Of course, the Debian |
| 1037 | maintainers appreciate any patches you might find |
| 1038 | suitable. The scripts in exim4-config-simple and |
| 1039 | exim4-config-medium may not work at all in your |
| 1040 | environment. Unfortunately, they have not been |
| 1041 | updated in a long time as well. We are willing to |
| 1042 | accept patches. |
| 1043 | </para> |
| 1044 | <para> |
| 1045 | See the development web page for links to the subversion |
| 1046 | repository. |
| 1047 | </para> |
| 1048 | <para> |
| 1049 | Exchanging the entire exim4-config package with |
| 1050 | something custom comes particularly handy for sites |
| 1051 | that have more than a few machines that are |
| 1052 | similarly configured, but do not want to use the |
| 1053 | original exim4-config package. Build your own |
| 1054 | exim4-config-custom or exim4-config-foo, and simply |
| 1055 | apt that package to the machines that need to have |
| 1056 | that configuration. Future updates can then be |
| 1057 | handled via the dpkg-conffile mechanism, properly |
| 1058 | detecting local modifications. |
| 1059 | </para> |
| 1060 | <para> |
| 1061 | In the future, it might be possible that Debian will |
| 1062 | contain multiple flavours of Exim4 configuration. |
| 1063 | However, these packages would have to be maintained |
| 1064 | by someone else because the exim4 package |
| 1065 | maintainers think that the scheme delivered with |
| 1066 | exim4-config is the least of all evils and would |
| 1067 | rather not spend the time to maintain multiple configuration |
| 1068 | schemes while only actually using one. It would be |
| 1069 | nice to have a configuration scheme using a |
| 1070 | monolithic config file, managed by ucf in |
| 1071 | three-way-merge mode. If anybody feels ready to |
| 1072 | maintain it, please go ahead. |
| 1073 | </para> |
| 1074 | </section> |
| 1075 | </section> |
| 1076 | </section> |
| 1077 | <section id="TLS"> <title>Using TLS</title> |
| 1078 | <section> <title>Exim 4 as TLS/SSL client</title> |
| 1079 | <para> |
| 1080 | Both exim4-daemon-heavy and exim4-daemon-light support TLS/SSL |
| 1081 | using the GnuTLS library and STARTTLS. Exim will use TLS |
| 1082 | via STARTTLS <emphasis>automatically</emphasis> as client if |
| 1083 | the server Exim connects to offers it. |
| 1084 | </para> |
| 1085 | <para> |
| 1086 | This means that you will not need any special configuration if |
| 1087 | you want to use TLS for outgoing mail. However, to enforce |
| 1088 | TLS and successful certificate verification, a few things |
| 1089 | need to be configured. |
| 1090 | </para> |
| 1091 | <para> |
| 1092 | To enforce TLS and prevent fallback to unencrypted |
| 1093 | connections, ensure that hosts_require_tls = * is in effect on |
| 1094 | the respective transport. For the remote_smtp_smarthost |
| 1095 | transport, this setting can be controlled via the |
| 1096 | REMOTE_SMTP_SMARTHOST_HOSTS_REQUIRE_TLS macro. |
| 1097 | </para> |
| 1098 | <para> |
| 1099 | The certificate presented by the remote host is checked |
| 1100 | against the system CA certificate store |
| 1101 | (<filename>/etc/ssl/certs/</filename>) and the verification |
| 1102 | result is logged (CV=...). However successful certificate |
| 1103 | verification is <emphasis>not enforced</emphasis> by default. |
| 1104 | This can be changed by setting tls_verify_hosts = * on the |
| 1105 | respective transport. |
| 1106 | </para> |
| 1107 | <para> |
| 1108 | Another possibility would be to use DANE for certificate |
| 1109 | verification. This requires support on the server side and |
| 1110 | a resolver with DNSSEC support on the client side. |
| 1111 | </para> |
| 1112 | <para> |
| 1113 | If your |
| 1114 | server setup mandates the use of client certificates, you |
| 1115 | need to amend your remote_smtp and/or remote_smtp_smarthost |
| 1116 | transports with a tls_certificate option. This is not |
| 1117 | commonly needed. |
| 1118 | </para> |
| 1119 | <para id="tls_client_certicate"> |
| 1120 | To make exim send a TLS certificate to the remote host set |
| 1121 | REMOTE_SMTP_TLS_CERTIFICATE/REMOTE_SMTP_PRIVATEKEY or for |
| 1122 | the remote_smtp_smarthost transport |
| 1123 | REMOTE_SMTP_SMARTHOST_TLS_CERTIFICATE/REMOTE_SMTP_SMARTHOST_PRIVATEKEY |
| 1124 | respectively. |
| 1125 | </para> |
| 1126 | <para> |
| 1127 | TLS on connect is not natively supported. |
| 1128 | </para> |
| 1129 | </section> |
| 1130 | <section> <title>Enabling TLS support for Exim as server</title> |
| 1131 | <para> |
| 1132 | You should have created certificates in |
| 1133 | <filename>/etc/exim4/</filename> either by hand or by usage of |
| 1134 | the exim-gencert (which requires openssl). exim-gencert is |
| 1135 | shipped in |
| 1136 | <filename>/usr/share/doc/exim4-base/examples/</filename> and |
| 1137 | takes care of proper access privileges on the private key |
| 1138 | file. |
| 1139 | </para> |
| 1140 | <para> |
| 1141 | Now, enable TLS by setting the macro MAIN_TLS_ENABLE in a |
| 1142 | local configuration file as described in <xref linkend="macros"/>. |
| 1143 | </para> |
| 1144 | <para> |
| 1145 | After this configuration, Exim will advertise STARTTLS when |
| 1146 | connected to on the normal SMTP ports. Some broken clients |
| 1147 | (most prominent example being nearly all versions of Microsoft |
| 1148 | Outlook and Outlook Express, and Incredimail) insist on doing |
| 1149 | TLS on connect on Port 465. If you need to support these, set |
| 1150 | SMTPLISTENEROPTIONS='-oX 465:25 -oP /run/exim4/exim.pid' |
| 1151 | in <filename>/etc/default/exim4</filename> and |
| 1152 | "tls_on_connect_ports=465" in the main configuration section. |
| 1153 | </para> |
| 1154 | <para> |
| 1155 | The -oP is needed because Exim does not write an implicit pid |
| 1156 | file if -oX is given. Without pid file, init script and cron |
| 1157 | job will malfunction. |
| 1158 | </para> |
| 1159 | <para> |
| 1160 | It might be appropriate to add "+tls_cipher" to |
| 1161 | any log_selector statement you might already have, or to add a |
| 1162 | log_selector statement setting these two options in a local |
| 1163 | configuration file. (For Debian's configuration simply define |
| 1164 | the MAIN_LOG_SELECTOR macro.) |
| 1165 | This option makes Exim log what cipher |
| 1166 | your Exim and the peer's mailer have negotiated to use to |
| 1167 | encrypt the transaction. |
| 1168 | </para> |
| 1169 | <para> |
| 1170 | Exim can be configured to ask a client for a certificate and to |
| 1171 | try to verify it. Debian's exim configuration used to enable |
| 1172 | this by default, but stopped doing so since it caused TLS errors |
| 1173 | with a couple of popular clients (Outlook, Incredimail, etc.). |
| 1174 | To enable this again set the macro MAIN_TLS_TRY_VERIFY_HOSTS to |
| 1175 | the lists hosts whose certificates you want to check. (Use * to |
| 1176 | try checking all hosts. The value of the macro is used to |
| 1177 | populate exim's main option tls_try_verify_hosts.) You should |
| 1178 | also point MAIN_TLS_VERIFY_CERTIFICATES to a file containing the |
| 1179 | accepted certificates, since its default setting |
| 1180 | (/etc/ssl/certs/ca-certificates.crt) can contain a large list of |
| 1181 | certificates which causes the interoperabilty problems with |
| 1182 | Outlook et.al. noted above. |
| 1183 | </para> |
| 1184 | <para> |
| 1185 | The server certificate is only used for incoming connections, |
| 1186 | please consult <xref linkend="tls_client_certicate"/> for the |
| 1187 | corresponding outgoing conncection options. |
| 1188 | </para> |
| 1189 | </section> |
| 1190 | <section> <title>Troubleshooting</title> |
| 1191 | <para> |
| 1192 | If Exim complains in an SMTP session that TLS is unavailable, |
| 1193 | the Exim mainlog or paniclog frequently has exact information |
| 1194 | about what might be wrong. Fo example, you might see |
| 1195 | </para> |
| 1196 | <para> |
| 1197 | 2003-01-27 19:06:45 TLS error on connection from localhost [127.0.0.1] |
| 1198 | (cert/key setup): Error while reading file) |
| 1199 | </para> |
| 1200 | <para> |
| 1201 | showing that there has been an error while accessing the |
| 1202 | certificate or the private key file. |
| 1203 | </para> |
| 1204 | <para> |
| 1205 | Insuffient entropy available is a frequent cause of TLS |
| 1206 | failures in Exim context. If Exim logs "not enough random bytes |
| 1207 | available", or simply hangs silently when an encrypted |
| 1208 | connection should be established, then Exim was |
| 1209 | unable to read enough random data from |
| 1210 | <filename>/dev/random</filename> to do whatever cryptographic |
| 1211 | operation is requested. Please check that your |
| 1212 | <filename>/dev/random</filename> device is setup properly. |
| 1213 | </para> |
| 1214 | <para> |
| 1215 | You might also find "TLS error on connection to [...] |
| 1216 | (gnutls_handshake): The Diffie-Hellman prime sent by the server is |
| 1217 | not acceptable (not long enough)." given as reason. Exim by default |
| 1218 | requires a DH prime length of 1024 bits. This requirement can be |
| 1219 | downgraded by setting the tls_dh_min_bits option on the SMTP |
| 1220 | transport. The setting is accessible in the Debian configuration by |
| 1221 | setting the macro TLS_DH_MIN_BITS. (e.g. "TLS_DH_MIN_BITS = 768"). |
| 1222 | </para> |
| 1223 | </section> |
| 1224 | </section> |
| 1225 | <section id="smtp-auth"> <title>SMTP-AUTH</title> |
| 1226 | <para> |
| 1227 | Exim can do SMTP AUTH both as a client and as a server. |
| 1228 | </para> |
| 1229 | <para> |
| 1230 | AUTH PLAIN and AUTH LOGIN are disabled for connections which are |
| 1231 | not protected by SSL/TLS per default. These authentication |
| 1232 | methods use cleartext passwords, and allowing the |
| 1233 | transmission of cleartext passwords on unencrypted connections |
| 1234 | is a security risk. Therefore, the default configuration configures |
| 1235 | Exim not to use and/or allow AUTH PLAIN and AUTH LOGIN over |
| 1236 | unencrypted connections. |
| 1237 | </para> |
| 1238 | <para> |
| 1239 | It is thus recommended to set up Exim to use TLS to encrypt |
| 1240 | the connections. Please refer to <xref linkend="TLS"/> for |
| 1241 | documentation about this. Note that most Microsoft clients |
| 1242 | need special handling for TLS. |
| 1243 | </para> |
| 1244 | <section> <title>Using Exim as SMTP-AUTH client</title> |
| 1245 | <para> |
| 1246 | If you want to set up Exim as SMTP AUTH client for delivery |
| 1247 | to your internet access provider's smarthost put the name of |
| 1248 | the server, your login and password in |
| 1249 | <filename>/etc/exim4/passwd.client</filename>. See the man |
| 1250 | page for exim4-config_files(5) for more information about the |
| 1251 | required format. |
| 1252 | </para> |
| 1253 | <para> |
| 1254 | If you need to enable AUTH PLAIN or AUTH LOGIN for unencrypted |
| 1255 | connections because your service provider does support neither |
| 1256 | TLS encryption nor the CRAM MD5 authentication method, you can |
| 1257 | do so by setting the AUTH_CLIENT_ALLOW_NOTLS_PASSWORDS macro. |
| 1258 | Please refer to <xref linkend="macros"/> for an explanation of |
| 1259 | how best to do this. |
| 1260 | </para> |
| 1261 | <para> |
| 1262 | <filename>/etc/exim4/passwd.client</filename> needs to be |
| 1263 | readable for the exim user (user Debian-exim, group |
| 1264 | Debian-exim). It is suggested that you keep the default |
| 1265 | permissions root:Debian-exim 0640. |
| 1266 | </para> |
| 1267 | </section> |
| 1268 | <section> <title>Using Exim as SMTP-AUTH server</title> |
| 1269 | <para> |
| 1270 | The configuration files include many, verbosely commented, |
| 1271 | examples for server-side smtp-authentication which just need |
| 1272 | to be uncommented. |
| 1273 | </para> |
| 1274 | <para> |
| 1275 | If you need to enable AUTH PLAIN or AUTH LOGIN for unencrypted |
| 1276 | connections because your clients neither support TLS encryption |
| 1277 | nor the CRAM MD5 authentication method, you can do so by setting |
| 1278 | the AUTH_SERVER_ALLOW_NOTLS_PASSWORDS macro. Please refer to |
| 1279 | <xref linkend="macros"/> for an explanation of how best to |
| 1280 | do this. |
| 1281 | </para> |
| 1282 | <para> |
| 1283 | If you want to authenticate against system passwords (e.g. |
| 1284 | <filename>/etc/shadow</filename>) the easiest way is to use |
| 1285 | saslauthd in the Debian package sasl2-bin. You have to add the |
| 1286 | exim-user (currently Debian-exim) to the sasl group, to give |
| 1287 | exim permission to use the saslauthd service. |
| 1288 | </para> |
| 1289 | <para> |
| 1290 | The Debian exim4 maintainers consider using system login |
| 1291 | passwords a bad idea for the following reasons: |
| 1292 | <itemizedlist> |
| 1293 | <listitem> |
| 1294 | <simpara> |
| 1295 | A compromised password will give access to a system account. |
| 1296 | </simpara> |
| 1297 | </listitem> |
| 1298 | <listitem> |
| 1299 | <simpara> |
| 1300 | E-Mail passwords could accidentally be transmitted unencrypted. |
| 1301 | </simpara> |
| 1302 | </listitem> |
| 1303 | <listitem> |
| 1304 | <simpara> |
| 1305 | E-Mail passwords are likely to be stored with the |
| 1306 | client software, which greatly increases the chance of a |
| 1307 | compromise. |
| 1308 | </simpara> |
| 1309 | </listitem> |
| 1310 | </itemizedlist> |
| 1311 | </para> |
| 1312 | </section> |
| 1313 | </section> |
| 1314 | |
| 1315 | <section> <title>How the Exim daemon is started</title> |
| 1316 | <para> |
| 1317 | The Debian Exim 4 packages' init script is located in |
| 1318 | <filename>/etc/init.d/exim4</filename>. Apart from the |
| 1319 | functions that are required by Debian policy and the LSB, it |
| 1320 | supports the commands <command>what</command>, which executes |
| 1321 | <command>exiwhat</command> to show what your Exim processes |
| 1322 | are doing, and <command>force_stop</command> which |
| 1323 | unconditionally kills all Exim processes. |
| 1324 | </para> |
| 1325 | <para> |
| 1326 | The init script can be configured to start listening and/or |
| 1327 | queue running daemons. This configuration can be found in |
| 1328 | <filename>/etc/default/exim4</filename>. This file is |
| 1329 | extensively documented. |
| 1330 | </para> |
| 1331 | </section> |
| 1332 | |
| 1333 | <section> <title>Miscellaneous packaging issues</title> |
| 1334 | <section> <title>The daily cron job</title> |
| 1335 | <para> |
| 1336 | Exim4's daily cron job |
| 1337 | (<filename>/etc/cron.daily/exim4-base</filename>) |
| 1338 | does basic housekeeping tasks: |
| 1339 | <itemizedlist> |
| 1340 | <listitem> |
| 1341 | <simpara> |
| 1342 | It reads <filename>/etc/default/exim4</filename>, so you |
| 1343 | can use this file to change any of the variables used in |
| 1344 | the cron job. |
| 1345 | </simpara> |
| 1346 | </listitem> |
| 1347 | <listitem> |
| 1348 | <simpara> |
| 1349 | It is a no-op if no Exim4 binary is found. |
| 1350 | </simpara> |
| 1351 | </listitem> |
| 1352 | <listitem> |
| 1353 | <simpara> |
| 1354 | If <command>$E4BCD_DAILY_REPORT_TO</command> is set |
| 1355 | to a non-empty string, the output of eximstats is |
| 1356 | mailed to the address given in that variable. The |
| 1357 | default is empty, so no reports are sent. Options |
| 1358 | for eximstats can be given in |
| 1359 | <command>$E4BCD_DAILY_REPORT_OPTIONS</command>. |
| 1360 | </simpara> |
| 1361 | </listitem> |
| 1362 | <listitem> |
| 1363 | <simpara> |
| 1364 | A non-empty paniclog is a nearly sure sign of bad |
| 1365 | things going on. Thus, the cron job will send out |
| 1366 | warning messages to the syslog and root if it finds |
| 1367 | the panic log non-empty. |
| 1368 | Please note that the paniclog is not rotated daily, |
| 1369 | so existing issues will be reported daily until |
| 1370 | either the paniclog is rotated due to its sheer |
| 1371 | size, or you manually move it away, for example by |
| 1372 | calling <command>logrotate -f |
| 1373 | /etc/logrotate.d/exim4-paniclog</command> from a shell. |
| 1374 | </simpara> |
| 1375 | <simpara> |
| 1376 | Just in case your system logs transient error |
| 1377 | situations to the panic log as well (see, for |
| 1378 | example, |
| 1379 | <ulink url="http://www.exim.org/bugzilla/show_bug.cgi?id=92">Exim Bug 92</ulink>), |
| 1380 | you can configure |
| 1381 | <command>$E4BCD_PANICLOG_NOISE</command> to a |
| 1382 | regular expression. If the paniclog contains only |
| 1383 | lines that match that regular expression, no warning |
| 1384 | messages are generated. |
| 1385 | </simpara> |
| 1386 | <simpara> |
| 1387 | If you want to disable paniclog monitoring |
| 1388 | completely, set <command>$E4BCD_WATCH_PANICLOG</command> |
| 1389 | to no. <command>E4BCD_WATCH_PANICLOG=once</command> will |
| 1390 | rotate a non-empty paniclog automatically after sending out |
| 1391 | the warning e-mail. |
| 1392 | </simpara> |
| 1393 | <simpara> |
| 1394 | The <command>E4BCD_PANICLOG_LINES</command> setting can be |
| 1395 | used to limit the number of lines of paniclog quoted in |
| 1396 | warning email. It is set to 10 by default. |
| 1397 | </simpara> |
| 1398 | </listitem> |
| 1399 | <listitem> |
| 1400 | <simpara> |
| 1401 | It tidies up the retry and hints databases. |
| 1402 | </simpara> |
| 1403 | </listitem> |
| 1404 | </itemizedlist> |
| 1405 | </para> |
| 1406 | </section> |
| 1407 | </section> |
| 1408 | |
| 1409 | <section> <title>Using Exim with inetd/xinetd</title> |
| 1410 | <para> |
| 1411 | Exim4 is run as a separate daemon instead of inetd/xinetd for |
| 1412 | two reasons: |
| 1413 | <variablelist> |
| 1414 | <varlistentry> |
| 1415 | <term>Ease of maintenance:</term> |
| 1416 | <listitem> |
| 1417 | <simpara> |
| 1418 | update-inetd is difficult to impossible to handle |
| 1419 | correctly (Just check the archived bug reports of Exim.) |
| 1420 | and update-inetd seems to be unmaintained for a long |
| 1421 | time, nobody dares to touch it. To quote Mark Baker, the |
| 1422 | maintainer of Exim (v3): "I really wish I had never used |
| 1423 | inetd in the first place, but simply set up exim to run |
| 1424 | as a daemon, but it's too late to change that now." |
| 1425 | </simpara> |
| 1426 | </listitem> |
| 1427 | </varlistentry> |
| 1428 | <varlistentry> |
| 1429 | <term>Extended features</term> |
| 1430 | <listitem> |
| 1431 | <simpara> |
| 1432 | Running from <command>inetd</command> interferes with |
| 1433 | Exim's resource controls (e.g it disables |
| 1434 | smtp_accept_max_per_host and smtp_accept_max). |
| 1435 | </simpara> |
| 1436 | </listitem> |
| 1437 | </varlistentry> |
| 1438 | </variablelist> |
| 1439 | </para> |
| 1440 | <para> |
| 1441 | If you introduce bugs on your systems by running from (x)inetd |
| 1442 | you are on your own! If you want to run exim from |
| 1443 | <command>xinetd</command>, follow these steps: |
| 1444 | <orderedlist> |
| 1445 | <listitem> |
| 1446 | <simpara> |
| 1447 | Disable Exim 4's listening daemon by executing |
| 1448 | <command>update-exim4defaults --queuerunner |
| 1449 | queueonly</command> |
| 1450 | </simpara> |
| 1451 | </listitem> |
| 1452 | <listitem> |
| 1453 | <para> |
| 1454 | Create <filename>/etc/xinetd.d/exim4</filename> |
| 1455 | <programlisting> |
| 1456 | service smtp |
| 1457 | { |
| 1458 | disable = no |
| 1459 | flags = NAMEINARGS |
| 1460 | socket_type = stream |
| 1461 | protocol = tcp |
| 1462 | wait = no |
| 1463 | user = Debian-exim |
| 1464 | group = Debian-exim |
| 1465 | server = /usr/sbin/exim4 |
| 1466 | server_args = exim4 -bs |
| 1467 | } |
| 1468 | </programlisting> |
| 1469 | </para> |
| 1470 | </listitem> |
| 1471 | <listitem> |
| 1472 | <simpara>Run <command>invoke-rc.d exim4 restart; invoke-rc.d |
| 1473 | (x)inetd restart</command></simpara> |
| 1474 | </listitem> |
| 1475 | </orderedlist> |
| 1476 | </para> |
| 1477 | <para>If you want to use plain inetd, insert following line into |
| 1478 | <filename>/etc/inetd.conf</filename>:<programlisting> |
| 1479 | smtp stream tcp nowait Debian-exim /usr/sbin/exim4 exim4 -bs |
| 1480 | </programlisting> |
| 1481 | </para> |
| 1482 | </section> |
| 1483 | |
| 1484 | <section> <title>Handling incoming mail for local accounts with low UID</title> |
| 1485 | <para> |
| 1486 | Since system accounts (mail, uucp, lp etc) are usually aliased |
| 1487 | to root, and root's mailbox is usually read by a human, these |
| 1488 | account names have started to be a common target for spammers. |
| 1489 | The Debian Exim 4 packages have a mechanism to deal with this |
| 1490 | situation. However, since this derives rather far from normal |
| 1491 | behavior, it is disabled by default. |
| 1492 | </para> |
| 1493 | <para> |
| 1494 | To enable it, set the macro FIRST_USER_ACCOUNT_UID to a numeric, |
| 1495 | non-zero value. Incoming mail for local users that have a UID |
| 1496 | lower than FIRST_USER_ACCOUNT_UID is rejected with the message "no |
| 1497 | mail to system accounts". Incoming mail for local users that |
| 1498 | have a UID greater or equal FIRST_USER_ACCOUNT_UID are processed as |
| 1499 | usual. Therefore, the default value of 0 ensures that the |
| 1500 | mechanism is disabled. On Debian systems, setting |
| 1501 | FIRST_USER_ACCOUNT_UID to 500 or 1000 (depending on your local policy) |
| 1502 | will disable incoming mail for system accounts. |
| 1503 | </para> |
| 1504 | <para> |
| 1505 | Just in case that you need exceptions to the rule, |
| 1506 | <filename>/etc/exim4/lowuid-aliases</filename> is an alias |
| 1507 | file that is only honored for local accounts with UID lower |
| 1508 | than FIRST_USER_ACCOUNT_UID. If you define an alias for such an |
| 1509 | account here, incoming mail is processed according to the |
| 1510 | alias. If you alias the account to itself, messages are |
| 1511 | delivered to the account itself, which is an exception to the |
| 1512 | rule that messages for low-UID accounts are rejected. The |
| 1513 | format of <filename>/etc/exim4/lowuid-aliases</filename> is |
| 1514 | just another alias file. |
| 1515 | </para> |
| 1516 | </section> |
| 1517 | <section> <title>How to bypass local routing specialities</title> |
| 1518 | <para> |
| 1519 | Sometimes, it might be desirable to be able to bypass local |
| 1520 | routing specialities like the alias file or a user-forward |
| 1521 | file. This is possible in the Debian Exim4 packages by |
| 1522 | prefixing the account name with "real-". For a local account |
| 1523 | name "foo", "real-foo@hostname.example" will result in direct |
| 1524 | delivery to foo's local Mailbox. |
| 1525 | </para> |
| 1526 | <para> |
| 1527 | This feature is by default only available for locally |
| 1528 | generated messages. If you want it to be accessible for |
| 1529 | messages delivered from remote as well, set the Exim macro |
| 1530 | COND_LOCAL_SUBMITTER to true. If you do not want this at all, |
| 1531 | set the macro to false. Please note that the userforward |
| 1532 | router uses this feature to get error messages delivered, i.e. |
| 1533 | notifying the user of a syntax error in her |
| 1534 | <filename>.forward</filename> file. |
| 1535 | </para> |
| 1536 | </section> |
| 1537 | <section> <title>Using more complex deliveries from alias files</title> |
| 1538 | <para> |
| 1539 | Delivery to arbitrary files, directory or to pipes in the |
| 1540 | <filename>/etc/aliases</filename> file is disabled by default |
| 1541 | in the Debian Exim 4 packages. The delivery process including the |
| 1542 | program being piped to would run as the exim admin-user |
| 1543 | Debian-exim, which might open up security holes. |
| 1544 | </para> |
| 1545 | <para> |
| 1546 | Invoking pipes from <filename>/etc/aliases</filename> file is |
| 1547 | widely considered obsolete and deprecated. The Debian Exim |
| 1548 | package maintainers would like to suggest using a dedicated |
| 1549 | router/transport pair to invoke local processes for mail |
| 1550 | processing. For example, the Debian mailman package contains a |
| 1551 | <filename>/usr/share/doc/mailman/README.Exim4.Debian</filename> file |
| 1552 | that gives a good example how to implement this. Using a |
| 1553 | dedicated router/transport pair have the following advantages: |
| 1554 | <itemizedlist> |
| 1555 | <listitem> |
| 1556 | <para> |
| 1557 | The router/transport pair can be put in place by another |
| 1558 | package, giving a well-defined transaction point between |
| 1559 | Exim 4 and $PACKAGE. |
| 1560 | </para> |
| 1561 | </listitem> |
| 1562 | <listitem> |
| 1563 | <para> |
| 1564 | Not allowing pipe deliveries from alias files makes it |
| 1565 | harder to accidentally run programs with wrong |
| 1566 | privileges. |
| 1567 | </para> |
| 1568 | </listitem> |
| 1569 | <listitem> |
| 1570 | <para> |
| 1571 | It is possible to run different pipe processes under |
| 1572 | different accounts. |
| 1573 | </para> |
| 1574 | </listitem> |
| 1575 | <listitem> |
| 1576 | <para> |
| 1577 | Even if only invoking a single local program, it is easier |
| 1578 | to do with your dedicated router/transport since you won't |
| 1579 | need to change this file, making automatic updates of this |
| 1580 | file possible for future versions of the Exim 4 packages. If |
| 1581 | you do local changes here, dpkg conffile handling will |
| 1582 | bother you on future updates. |
| 1583 | </para> |
| 1584 | </listitem> |
| 1585 | </itemizedlist> |
| 1586 | If you insist on using <filename>/etc/aliases</filename> in |
| 1587 | the traditional way, you will need to activate the |
| 1588 | respective functions by setting the transport options on the |
| 1589 | system_aliases router appropriately. Macros are defined to make |
| 1590 | this easier. See |
| 1591 | |
| 1592 | <filename>/etc/exim4/conf.d/router/400_exim4-config_system_aliases</filename> |
| 1593 | for information about which macros are available. You might |
| 1594 | find the address_file, address_pipe and/or address_directory |
| 1595 | transports that are used for the userforward router helpful in |
| 1596 | writing your own transports for use in the system_aliases router. |
| 1597 | </para> |
| 1598 | <para> |
| 1599 | If any of your aliases expand to pipes or files or directories |
| 1600 | you should set up a user and a group for these deliveries to run |
| 1601 | under. You can do this by setting the "user" and - if necessary |
| 1602 | - a "group" option and adding a "group" option if necessary. |
| 1603 | Alternatively, you can specify "user" and/or "group" on the |
| 1604 | transports that are used. |
| 1605 | </para> |
| 1606 | </section> |
| 1607 | |
| 1608 | <section> <title>Putting Exim 4 and UUCP together</title> |
| 1609 | <para> |
| 1610 | UUCP is a traditional way to execute remote jobs (e.g. spool |
| 1611 | mails), and as a lot of old things there are much more than one |
| 1612 | way to do it. However, today, the ways to handle it have boiled |
| 1613 | down to more or less two different ways. |
| 1614 | </para> |
| 1615 | <para> |
| 1616 | Our recommendation is to use bsmtp/rsmtp wherever possible, |
| 1617 | because it supports all kinds of mail addresses (also the empty |
| 1618 | ones in bounces), and is also better from the security point of |
| 1619 | view. |
| 1620 | </para> |
| 1621 | <section> <title>Sending mail via UUCP</title> |
| 1622 | <section> <title>rmail with full addresses</title> |
| 1623 | <para> |
| 1624 | rmail is the oldest way to transfer mail to a remote system. |
| 1625 | However, today it is normally required to use addresses with |
| 1626 | full domains for that (Well, they look like any normal address |
| 1627 | for you, and we do not tell about the other way to not confuse |
| 1628 | you ;). If you want this, you can use this transport: |
| 1629 | </para> |
| 1630 | <programlisting> |
| 1631 | rmail: |
| 1632 | debug_print = "T: rmail for $pipe_addresses" |
| 1633 | driver=pipe |
| 1634 | command = uux - -r -a$sender_address -gC $domain_data!rmail $pipe_addresses |
| 1635 | return_fail_output |
| 1636 | user=uucp |
| 1637 | batch_max = 20 |
| 1638 | </programlisting> |
| 1639 | <para> |
| 1640 | However, all recipients are handled via the command line, so |
| 1641 | you are discouraged to use it. |
| 1642 | </para> |
| 1643 | </section> |
| 1644 | <section> <title>bsmtp/rsmtp</title> |
| 1645 | <para> |
| 1646 | This is a more efficient way to transfer mails. It works |
| 1647 | like sending SMTP via a pipe, but instead of waiting for an |
| 1648 | answer, the SMTP is just batched; from this is also the name |
| 1649 | batched SMTP or short bsmtp. |
| 1650 | </para> |
| 1651 | <para> |
| 1652 | Furthermore, this way won't fail on addresses like " |
| 1653 | "@do.main. If you want this, please use this, if the remote |
| 1654 | site uses rsmtp (e.g. is Exim 4): |
| 1655 | </para> |
| 1656 | <programlisting> |
| 1657 | rsmtp: |
| 1658 | debug_print = "T: rsmtp for $pipe_addresses" |
| 1659 | driver=pipe |
| 1660 | command = /usr/bin/uux - -r -a$sender_address -gC $domain_data!rsmtp |
| 1661 | use_bsmtp |
| 1662 | return_fail_output |
| 1663 | user=uucp |
| 1664 | batch_max = 100 |
| 1665 | </programlisting> |
| 1666 | <para> |
| 1667 | and this if it wants bsmtp as the command: |
| 1668 | </para> |
| 1669 | <programlisting> |
| 1670 | bsmtp: |
| 1671 | debug_print = "T: bsmtp for $pipe_addresses" |
| 1672 | driver=pipe |
| 1673 | command = /usr/bin/uux - -r -a$sender_address -gC $domain_data!bsmtp |
| 1674 | use_bsmtp |
| 1675 | return_fail_output |
| 1676 | user=uucp |
| 1677 | batch_max = 100 |
| 1678 | </programlisting> |
| 1679 | <para> |
| 1680 | Of course, these examples can be extended for e.g. |
| 1681 | compression (but you can also use ssh for compression, if |
| 1682 | you want). |
| 1683 | </para> |
| 1684 | </section> |
| 1685 | <section> <title>The router</title> |
| 1686 | <para> |
| 1687 | You need a router to tell Exim 4 which mails to forward to |
| 1688 | UUCP. You can use this one; please adopt the last line. Of |
| 1689 | course, it is also possible to send mail via more than one way. |
| 1690 | </para> |
| 1691 | <programlisting> |
| 1692 | uucp_router: |
| 1693 | debug_print = "R: uucp_router for $local_part@$domain" |
| 1694 | driver=accept |
| 1695 | require_files = +/usr/bin/uux |
| 1696 | domains = wildlsearch;/etc/exim4/uucp |
| 1697 | transport = rsmtp |
| 1698 | </programlisting> |
| 1699 | <para> |
| 1700 | The file <filename>/etc/exim4/uucp</filename> looks like: |
| 1701 | </para> |
| 1702 | <programlisting> |
| 1703 | *.do.main uucp.name.of.remote.side |
| 1704 | </programlisting> |
| 1705 | </section> |
| 1706 | <section> <title>Speaking UUCP with the smarthost</title> |
| 1707 | <para> |
| 1708 | If you have a leaf system (i.e. all your mail not for your |
| 1709 | local system goes to a single remote system), you can just |
| 1710 | forward all non-local mail to the remote UUCP system. In |
| 1711 | this case, you can replace "domains = ..." with "domains = ! |
| 1712 | +local_domains", but then you need also to replace |
| 1713 | $domain_data in the transport by the UUCP-name of your |
| 1714 | smarthost. The file <filename>/etc/exim4/uucp</filename> is |
| 1715 | not needed in this case. |
| 1716 | </para> |
| 1717 | </section> |
| 1718 | </section> |
| 1719 | <section> <title>Receiving mail via UUCP</title> |
| 1720 | <section> <title>Allow UUCP to use any envelope address</title> |
| 1721 | <para> |
| 1722 | Depending how much you trust your local users, you might use |
| 1723 | trusted_users and add uucp to it or use |
| 1724 | local_sender_retain=true and local_from_check=false. |
| 1725 | </para> |
| 1726 | </section> |
| 1727 | <section> <title>If you get batched smtp</title> |
| 1728 | <para> |
| 1729 | Allow uucp to execute rsmtp via |
| 1730 | <programlisting> |
| 1731 | commands rmail rnews rsmtp |
| 1732 | </programlisting> |
| 1733 | in your <filename>/etc/uucp/sys</filename>, and ask the |
| 1734 | sending site to use rsmtp (and not bsmtp) as the batched |
| 1735 | command. |
| 1736 | </para> |
| 1737 | </section> |
| 1738 | </section> |
| 1739 | </section> |
| 1740 | <section> <title>Notes on running SpamAssassin at SMTP time</title> |
| 1741 | <para> |
| 1742 | Exim can run |
| 1743 | <ulink url="https://spamassassin.apache.org/"> |
| 1744 | SpamAssassin</ulink> while receiving a message by SMTP which |
| 1745 | allows one to avoid acceptance of spam messages. The Debian |
| 1746 | configuration contains some example code for running SpamAssassin, |
| 1747 | but like all filtering this needs to be handled carefully. |
| 1748 | </para> |
| 1749 | <para> |
| 1750 | SpamAssassin's default report should not be used in a add_header |
| 1751 | statement since it contains empty lines. (This triggers e.g. |
| 1752 | Amavis' warning "BAD HEADER SECTION, Improper folded header field |
| 1753 | made up entirely of whitespace".) This is a safe, terse alternative: |
| 1754 | <programlisting> |
| 1755 | clear_report_template |
| 1756 | report (_SCORE_ / _REQD_ requ) _TESTSSCORES(,)_ autolearn=_AUTOLEARN_ |
| 1757 | </programlisting> |
| 1758 | </para> |
| 1759 | <para> |
| 1760 | Rejecting spam messages: Do not reject spam-messages received on |
| 1761 | (non-spam) mailing lists, this can/will cause auto-unsubscription. |
| 1762 | This also applies to messages received via forwarding services |
| 1763 | (e.g. @debian.org addresses). If theses messages are rejected the |
| 1764 | forwarding services will need to send a bounce address to the |
| 1765 | spammer and will probably disable the forwarding if it happens all |
| 1766 | the time. You will need to have some kind of whitelist to exclude |
| 1767 | these hosts. |
| 1768 | </para> |
| 1769 | <para> |
| 1770 | Security considerations: By default <command>spamd</command> |
| 1771 | runs as root and changes uid/gid to the requested user to run |
| 1772 | SpamAssassin. The example uses SpamAssassin default non-privileged |
| 1773 | user (nobody) which prevents use of Bayesian filtering since this |
| 1774 | requires persistent storage. You might want to setup a dedicated |
| 1775 | user for exim spam scanning and use that one, either for a separate |
| 1776 | SpamAssassin user profile or to run SpamAssassin as non-privileged |
| 1777 | user. |
| 1778 | </para> |
| 1779 | </section> |
| 1780 | </section> |
| 1781 | |
| 1782 | <section> <title>Updating from Exim 3</title> |
| 1783 | <para> |
| 1784 | If you use <command>exim4-config</command> from Debian, you will |
| 1785 | get the debconf based configuration scheme that is intended to |
| 1786 | cover the majority of cases. |
| 1787 | </para> |
| 1788 | <para> |
| 1789 | If <command>exim4-config</command> is installed while an Exim 3 |
| 1790 | package is present on the system, |
| 1791 | <command>exim4-config</command> tries to parse the Exim 3 config |
| 1792 | file to determine the answers that were given to |
| 1793 | <command>eximconfig</command> on Exim 3 installation. These |
| 1794 | answers are then taken as default values for the debconf based |
| 1795 | configuration process. Be warned! <command>eximconfig</command> |
| 1796 | from the Exim 3 packages does not record the explicit answers |
| 1797 | given on Exim 3 configuration. So we have to guess the answers |
| 1798 | from the Exim 3 configuration file |
| 1799 | <filename>/etc/exim/exim.conf</filename>, which is bound to fail |
| 1800 | if the config file has been modified after using |
| 1801 | <command>eximconfig</command>. |
| 1802 | </para> |
| 1803 | <para> |
| 1804 | This is the reason why we refrained from doing a "silent update", but |
| 1805 | only use the guessed answers to get reasonable defaults for our |
| 1806 | debconf based configuration process. |
| 1807 | </para> |
| 1808 | <para> |
| 1809 | Please note that we do not use the |
| 1810 | <command>exim_convert4r4</command> script, but try to configure |
| 1811 | the Exim 4 package in the same way Exim 3 was. This will |
| 1812 | hopefully aid future updates. |
| 1813 | </para> |
| 1814 | <para> |
| 1815 | If you have used a customized Exim 3 configuration, you can of |
| 1816 | course use <command>exim_convert4r4</command>, and install the |
| 1817 | resulting file as <filename>/etc/exim4/exim4.conf</filename> |
| 1818 | after careful inspection. Exim 4 will then use that file and |
| 1819 | ignore the file that it generated from the debconf |
| 1820 | configuration. To aid future updates, we do, however, encourage |
| 1821 | you not to use the |
| 1822 | <filename>exim_convert4r4-generated</filename> file verbatim but |
| 1823 | instead drop appropriate configuration snippets in their |
| 1824 | appropriate place in <filename>/etc/exim4/conf.d</filename>. |
| 1825 | </para> |
| 1826 | </section> |
| 1827 | <section> <title>Misc Notes</title> |
| 1828 | <section> <title>PAM</title> |
| 1829 | <para> |
| 1830 | On Debian systems the PAM modules run as the same user |
| 1831 | as the calling program, so they cannot do anything you |
| 1832 | could not do yourself, and in particular cannot access |
| 1833 | <filename>/etc/shadow</filename> unless the user is in group |
| 1834 | shadow. - If you want to use |
| 1835 | <filename>/etc/shadow</filename> for Exim's SMTP AUTH you |
| 1836 | will need to run exim as group shadow. Only |
| 1837 | exim4-daemon-heavy is linked against libpam. We suggest using |
| 1838 | saslauthd instead. |
| 1839 | </para> |
| 1840 | </section> |
| 1841 | <section> <title>Account name restrictions</title> |
| 1842 | <para> |
| 1843 | In the default configuration, Exim cannot locally deliver |
| 1844 | mail to accounts which have capitals in their name. This is |
| 1845 | caused by the fact that Exim converts the local part of incoming |
| 1846 | mail to lower case before the comparison done by the |
| 1847 | check_local_user directive in routers is done. |
| 1848 | </para> |
| 1849 | <para> |
| 1850 | The router option caseful_local_part can be used to control |
| 1851 | this, and we decided not to set this option in the Debian |
| 1852 | configuration since it would be a rather big change to Exim's |
| 1853 | default behavior. |
| 1854 | </para> |
| 1855 | </section> |
| 1856 | <section> <title>No deliveries to root!</title> |
| 1857 | <para> |
| 1858 | No Exim 4 version released with any Debian OS can run |
| 1859 | deliveries as root. If you don't redirect mail for root via |
| 1860 | <filename>/etc/aliases</filename> to a nonprivileged |
| 1861 | account, the mail will be delivered to |
| 1862 | <filename>/var/mail/mail</filename> with permissions 0600 and |
| 1863 | owner mail:mail. |
| 1864 | </para> |
| 1865 | <para> |
| 1866 | This redirection is done by the mail4root router which |
| 1867 | is last in the list and will thus catch mail for root that has not |
| 1868 | been taken care of earlier. |
| 1869 | </para> |
| 1870 | </section> |
| 1871 | <section> <title>Debugging maintainer and init scripts</title> |
| 1872 | <para> |
| 1873 | Most of the scripts that come with this Debian package do a |
| 1874 | <command>set -x</command> if invoked with the environment |
| 1875 | variable EX4DEBUG defined and non-zero. This is particularly |
| 1876 | handy if you need to debug the maintainer scripts that are |
| 1877 | invoked during package installation. Since dpkg redirects |
| 1878 | stdout of maintainer scripts, calling dpkg with EX4DEBUG |
| 1879 | set might yield interesting results. If in doubt, invoke |
| 1880 | the maintainer scripts with EX4DEBUG set manually directly |
| 1881 | from the command line. |
| 1882 | </para> |
| 1883 | </section> |
| 1884 | <section> <title>SELinux</title> |
| 1885 | <para> |
| 1886 | There is no SELinux policy for Exim4 available so far. |
| 1887 | Until this is resolved, users should use postfix or |
| 1888 | sendmail if they intend to run SELinux. |
| 1889 | </para> |
| 1890 | <para> |
| 1891 | The Debian Exim4 maintainers would appreciate if |
| 1892 | somebody could write an SELinux policy. We will gladly |
| 1893 | use them in the Debian packages as long as there is |
| 1894 | somebody available to test, debug and support. |
| 1895 | </para> |
| 1896 | </section> |
| 1897 | <section> <title>misc</title> |
| 1898 | <itemizedlist> |
| 1899 | <listitem> |
| 1900 | <simpara> |
| 1901 | <command>convert4r4</command> is installed as |
| 1902 | <filename>/usr/sbin/exim_convert4r4.</filename> |
| 1903 | </simpara> |
| 1904 | </listitem> |
| 1905 | <listitem> |
| 1906 | <simpara> |
| 1907 | The charset for $header_foo expansions defaults to |
| 1908 | UTF-8 instead of ISO-8859-1. |
| 1909 | </simpara> |
| 1910 | </listitem> |
| 1911 | <listitem> |
| 1912 | <simpara> |
| 1913 | <ulink url="http://marc.merlins.org/linux/exim/"> |
| 1914 | Marc Merlin's Exim 4 Page</ulink> has a lot of ACL |
| 1915 | examples. |
| 1916 | </simpara> |
| 1917 | </listitem> |
| 1918 | <listitem> |
| 1919 | <simpara> |
| 1920 | For an example of Exim usage in a |
| 1921 | <emphasis>large</emphasis> installation, see |
| 1922 | Tony Finch's |
| 1923 | <ulink |
| 1924 | url="http://www-uxsup.csx.cam.ac.uk/~fanf2/hermes/doc/talks/2005-02-eximconf/"> |
| 1925 | paper</ulink> |
| 1926 | about the Exim installation at University of Cambridge: |
| 1927 | </simpara> |
| 1928 | </listitem> |
| 1929 | </itemizedlist> |
| 1930 | </section> |
| 1931 | </section> |
| 1932 | <section> <title>Debian modifications to the Exim source</title> |
| 1933 | <itemizedlist> |
| 1934 | <listitem> |
| 1935 | <simpara> |
| 1936 | Install the exim binary as /usr/sbin/exim4 instead of |
| 1937 | /usr/sbin/exim-<version> with a symlink /usr/sbin/exim. Also |
| 1938 | adapt the documentation. |
| 1939 | </simpara> |
| 1940 | </listitem> |
| 1941 | <listitem> |
| 1942 | <simpara> |
| 1943 | Make the build reproducible. Pull date/time from debian/changelog |
| 1944 | and use it as build time instead of using __DATE__. |
| 1945 | </simpara> |
| 1946 | </listitem> |
| 1947 | <listitem> |
| 1948 | <simpara> |
| 1949 | Documentation updates |
| 1950 | </simpara> |
| 1951 | <itemizedlist> |
| 1952 | <listitem> |
| 1953 | <simpara> |
| 1954 | Mention how to install the Debian packaged perl-modules needed |
| 1955 | for eximstats' graphs. |
| 1956 | </simpara> |
| 1957 | </listitem> |
| 1958 | <listitem> |
| 1959 | <simpara> |
| 1960 | Add a warning about convert4r4. |
| 1961 | </simpara> |
| 1962 | </listitem> |
| 1963 | <listitem> |
| 1964 | <simpara> |
| 1965 | Point to the <ulink |
| 1966 | url="mailto:pkg-exim4-users@lists.alioth.debian.org"> |
| 1967 | Debian-specific mailing list</ulink> instead of |
| 1968 | the <ulink url="mailto:exim-users@exim.org">official |
| 1969 | exim-users list</ulink>. |
| 1970 | </simpara> |
| 1971 | </listitem> |
| 1972 | </itemizedlist> |
| 1973 | </listitem> |
| 1974 | <listitem> |
| 1975 | <simpara> |
| 1976 | <ulink |
| 1977 | url="http://marc.merlins.org/linux/exim/files/sa-exim-current/">localscan_dlopen.patch</ulink>: |
| 1978 | This patch makes it possible to use and switch between |
| 1979 | different local_scan |
| 1980 | functions without recompiling Exim. Use |
| 1981 | local_scan_path = /path/to/sharedobject to utilize |
| 1982 | local_scan() in <filename>/path/to/sharedobject</filename>. |
| 1983 | </simpara> |
| 1984 | </listitem> |
| 1985 | </itemizedlist> |
| 1986 | </section> |
| 1987 | |
| 1988 | <section> <title>Credits</title> |
| 1989 | <para><variablelist> |
| 1990 | <varlistentry> |
| 1991 | <term><ulink url="mailto:aba@not.so.argh.org">Andreas |
| 1992 | Barth</ulink></term> |
| 1993 | <listitem> |
| 1994 | <simpara>UUCP documentation</simpara> |
| 1995 | </listitem> |
| 1996 | </varlistentry> |
| 1997 | <varlistentry> |
| 1998 | <term>Dan Weber, Ryen Underwood</term> |
| 1999 | <listitem> |
| 2000 | <simpara>inetd/xinetd documentation</simpara> |
| 2001 | </listitem> |
| 2002 | </varlistentry> |
| 2003 | </variablelist> |
| 2004 | </para> |
| 2005 | </section> |
| 2006 | |
| 2007 | </article> |