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