Commit | Line | Data |
---|---|---|
de45f55a AM |
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> | |
de45f55a AM |
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> | |
de45f55a AM |
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> | |
0baa7b9d SB |
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. | |
de45f55a AM |
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 | |
0baa7b9d SB |
475 | Exim specification chapter <phrase>"Domain, host, address, and |
476 | local part lists"</phrase> | |
477 | and the exim4-config_files man page. | |
de45f55a AM |
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 | |
0baa7b9d SB |
499 | specified (See Exim specification, chapter |
500 | <phrase>"The manualroute router"</phrase>, section | |
501 | <phrase>"How the list of hosts is used"</phrase>.) | |
de45f55a AM |
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 | |
0baa7b9d | 763 | touching dpkg-conffiles itself is explicitly allowed and wanted, |
de45f55a AM |
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 | |
0baa7b9d SB |
790 | <phrase>"The Exim run time configuration file"</phrase>, for |
791 | details how macro expansion works. | |
de45f55a AM |
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, if your | |
1088 | server setup mandates the use of client certificates, you | |
1089 | need to amend your remote_smtp and/or remote_smtp_smarthost | |
1090 | transports with a tls_certificate option. This is not | |
1091 | commonly needed. | |
1092 | </para> | |
1093 | <para> | |
1094 | The certificate | |
1095 | presented by the remote host is not checked unless you | |
1096 | specify a tls_verify_certificate option on the transport. | |
1097 | </para> | |
1098 | <para id="tls_client_certicate"> | |
1099 | To make exim send a TLS certificate to the remote host set | |
1100 | REMOTE_SMTP_TLS_CERTIFICATE/REMOTE_SMTP_PRIVATEKEY or for | |
1101 | the remote_smtp_smarthost transport | |
1102 | REMOTE_SMTP_SMARTHOST_TLS_CERTIFICATE/REMOTE_SMTP_SMARTHOST_PRIVATEKEY | |
1103 | respectively. | |
1104 | </para> | |
1105 | <para> | |
1106 | TLS on connect is not natively supported. | |
1107 | </para> | |
1108 | </section> | |
1109 | <section> <title>Enabling TLS support for Exim as server</title> | |
1110 | <para> | |
1111 | You should have created certificates in | |
1112 | <filename>/etc/exim4/</filename> either by hand or by usage of | |
1113 | the exim-gencert (which requires openssl). exim-gencert is | |
1114 | shipped in | |
1115 | <filename>/usr/share/doc/exim4-base/examples/</filename> and | |
1116 | takes care of proper access privileges on the private key | |
1117 | file. | |
1118 | </para> | |
1119 | <para> | |
1120 | Now, enable TLS by setting the macro MAIN_TLS_ENABLE in a | |
1121 | local configuration file as described in <xref linkend="macros"/>. | |
1122 | </para> | |
1123 | <para> | |
1124 | After this configuration, Exim will advertise STARTTLS when | |
1125 | connected to on the normal SMTP ports. Some broken clients | |
1126 | (most prominent example being nearly all versions of Microsoft | |
1127 | Outlook and Outlook Express, and Incredimail) insist on doing | |
1128 | TLS on connect on Port 465. If you need to support these, set | |
0baa7b9d | 1129 | SMTPLISTENEROPTIONS='-oX 465:25 -oP /run/exim4/exim.pid' |
de45f55a AM |
1130 | in <filename>/etc/default/exim4</filename> and |
1131 | "tls_on_connect_ports=465" in the main configuration section. | |
1132 | </para> | |
1133 | <para> | |
1134 | The -oP is needed because Exim does not write an implicit pid | |
1135 | file if -oX is given. Without pid file, init script and cron | |
1136 | job will malfunction. | |
1137 | </para> | |
1138 | <para> | |
0baa7b9d | 1139 | It might be appropriate to add "+tls_cipher" to |
de45f55a AM |
1140 | any log_selector statement you might already have, or to add a |
1141 | log_selector statement setting these two options in a local | |
0baa7b9d SB |
1142 | configuration file. (For Debian's configuration simply define |
1143 | the MAIN_LOG_SELECTOR macro.) | |
1144 | This option makes Exim log what cipher | |
de45f55a | 1145 | your Exim and the peer's mailer have negotiated to use to |
0baa7b9d | 1146 | encrypt the transaction. |
de45f55a AM |
1147 | </para> |
1148 | <para> | |
1149 | Exim can be configured to ask a client for a certificate and to | |
1150 | try to verify it. Debian's exim configuration used to enable | |
1151 | this by default, but stopped doing so since it caused TLS errors | |
1152 | with a couple of popular clients (Outlook, Incredimail, etc.). | |
1153 | To enable this again set the macro MAIN_TLS_TRY_VERIFY_HOSTS to | |
1154 | the lists hosts whose certificates you want to check. (Use * to | |
1155 | try checking all hosts. The value of the macro is used to | |
1156 | populate exim's main option tls_try_verify_hosts.) You should | |
1157 | also point MAIN_TLS_VERIFY_CERTIFICATES to a file containing the | |
1158 | accepted certificates, since its default setting | |
1159 | (/etc/ssl/certs/ca-certificates.crt) can contain a large list of | |
1160 | certificates which causes the interoperabilty problems with | |
1161 | Outlook et.al. noted above. | |
1162 | </para> | |
1163 | <para> | |
1164 | The server certificate is only used for incoming connections, | |
1165 | please consult <xref linkend="tls_client_certicate"/> for the | |
1166 | corresponding outgoing conncection options. | |
1167 | </para> | |
1168 | </section> | |
1169 | <section> <title>Troubleshooting</title> | |
1170 | <para> | |
1171 | If Exim complains in an SMTP session that TLS is unavailable, | |
1172 | the Exim mainlog or paniclog frequently has exact information | |
1173 | about what might be wrong. Fo example, you might see | |
1174 | </para> | |
1175 | <para> | |
1176 | 2003-01-27 19:06:45 TLS error on connection from localhost [127.0.0.1] | |
1177 | (cert/key setup): Error while reading file) | |
1178 | </para> | |
1179 | <para> | |
1180 | showing that there has been an error while accessing the | |
1181 | certificate or the private key file. | |
1182 | </para> | |
1183 | <para> | |
1184 | Insuffient entropy available is a frequent cause of TLS | |
1185 | failures in Exim context. If Exim logs "not enough random bytes | |
1186 | available", or simply hangs silently when an encrypted | |
1187 | connection should be established, then Exim was | |
1188 | unable to read enough random data from | |
1189 | <filename>/dev/random</filename> to do whatever cryptographic | |
1190 | operation is requested. Please check that your | |
1191 | <filename>/dev/random</filename> device is setup properly. | |
1192 | </para> | |
1193 | <para> | |
1194 | You might also find "TLS error on connection to [...] | |
1195 | (gnutls_handshake): The Diffie-Hellman prime sent by the server is | |
1196 | not acceptable (not long enough)." given as reason. Exim by default | |
1197 | requires a DH prime length of 1024 bits. This requirement can be | |
1198 | downgraded by setting the tls_dh_min_bits option on the SMTP | |
1199 | transport. The setting is accessible in the Debian configuration by | |
1200 | setting the macro TLS_DH_MIN_BITS. (e.g. "TLS_DH_MIN_BITS = 768"). | |
1201 | </para> | |
1202 | </section> | |
1203 | </section> | |
1204 | <section id="smtp-auth"> <title>SMTP-AUTH</title> | |
1205 | <para> | |
1206 | Exim can do SMTP AUTH both as a client and as a server. | |
1207 | </para> | |
1208 | <para> | |
1209 | AUTH PLAIN and AUTH LOGIN are disabled for connections which are | |
1210 | not protected by SSL/TLS per default. These authentication | |
1211 | methods use cleartext passwords, and allowing the | |
1212 | transmission of cleartext passwords on unencrypted connections | |
1213 | is a security risk. Therefore, the default configuration configures | |
1214 | Exim not to use and/or allow AUTH PLAIN and AUTH LOGIN over | |
1215 | unencrypted connections. | |
1216 | </para> | |
1217 | <para> | |
1218 | It is thus recommended to set up Exim to use TLS to encrypt | |
1219 | the connections. Please refer to <xref linkend="TLS"/> for | |
1220 | documentation about this. Note that most Microsoft clients | |
1221 | need special handling for TLS. | |
1222 | </para> | |
1223 | <section> <title>Using Exim as SMTP-AUTH client</title> | |
1224 | <para> | |
1225 | If you want to set up Exim as SMTP AUTH client for delivery | |
1226 | to your internet access provider's smarthost put the name of | |
1227 | the server, your login and password in | |
1228 | <filename>/etc/exim4/passwd.client</filename>. See the man | |
1229 | page for exim4-config_files(5) for more information about the | |
1230 | required format. | |
1231 | </para> | |
1232 | <para> | |
1233 | If you need to enable AUTH PLAIN or AUTH LOGIN for unencrypted | |
1234 | connections because your service provider does support neither | |
1235 | TLS encryption nor the CRAM MD5 authentication method, you can | |
1236 | do so by setting the AUTH_CLIENT_ALLOW_NOTLS_PASSWORDS macro. | |
1237 | Please refer to <xref linkend="macros"/> for an explanation of | |
1238 | how best to do this. | |
1239 | </para> | |
1240 | <para> | |
1241 | <filename>/etc/exim4/passwd.client</filename> needs to be | |
1242 | readable for the exim user (user Debian-exim, group | |
1243 | Debian-exim). It is suggested that you keep the default | |
1244 | permissions root:Debian-exim 0640. | |
1245 | </para> | |
1246 | </section> | |
1247 | <section> <title>Using Exim as SMTP-AUTH server</title> | |
1248 | <para> | |
1249 | The configuration files include many, verbosely commented, | |
1250 | examples for server-side smtp-authentication which just need | |
1251 | to be uncommented. | |
1252 | </para> | |
1253 | <para> | |
1254 | If you need to enable AUTH PLAIN or AUTH LOGIN for unencrypted | |
1255 | connections because your clients neither support TLS encryption | |
1256 | nor the CRAM MD5 authentication method, you can do so by setting | |
1257 | the AUTH_SERVER_ALLOW_NOTLS_PASSWORDS macro. Please refer to | |
1258 | <xref linkend="macros"/> for an explanation of how best to | |
1259 | do this. | |
1260 | </para> | |
1261 | <para> | |
1262 | If you want to authenticate against system passwords (e.g. | |
1263 | <filename>/etc/shadow</filename>) the easiest way is to use | |
1264 | saslauthd in the Debian package sasl2-bin. You have to add the | |
1265 | exim-user (currently Debian-exim) to the sasl group, to give | |
1266 | exim permission to use the saslauthd service. | |
1267 | </para> | |
1268 | <para> | |
1269 | The Debian exim4 maintainers consider using system login | |
1270 | passwords a bad idea for the following reasons: | |
1271 | <itemizedlist> | |
1272 | <listitem> | |
1273 | <simpara> | |
1274 | A compromised password will give access to a system account. | |
1275 | </simpara> | |
1276 | </listitem> | |
1277 | <listitem> | |
1278 | <simpara> | |
1279 | E-Mail passwords could accidentally be transmitted unencrypted. | |
1280 | </simpara> | |
1281 | </listitem> | |
1282 | <listitem> | |
1283 | <simpara> | |
1284 | E-Mail passwords are likely to be stored with the | |
1285 | client software, which greatly increases the chance of a | |
1286 | compromise. | |
1287 | </simpara> | |
1288 | </listitem> | |
1289 | </itemizedlist> | |
1290 | </para> | |
1291 | </section> | |
1292 | </section> | |
1293 | ||
1294 | <section> <title>How the Exim daemon is started</title> | |
1295 | <para> | |
1296 | The Debian Exim 4 packages' init script is located in | |
1297 | <filename>/etc/init.d/exim4</filename>. Apart from the | |
1298 | functions that are required by Debian policy and the LSB, it | |
1299 | supports the commands <command>what</command>, which executes | |
1300 | <command>exiwhat</command> to show what your Exim processes | |
1301 | are doing, and <command>force_stop</command> which | |
1302 | unconditionally kills all Exim processes. | |
1303 | </para> | |
1304 | <para> | |
1305 | The init script can be configured to start listening and/or | |
1306 | queue running daemons. This configuration can be found in | |
1307 | <filename>/etc/default/exim4</filename>. This file is | |
1308 | extensively documented. | |
1309 | </para> | |
1310 | </section> | |
1311 | ||
1312 | <section> <title>Miscellaneous packaging issues</title> | |
1313 | <section> <title>The daily cron job</title> | |
1314 | <para> | |
1315 | Exim4's daily cron job | |
1316 | (<filename>/etc/cron.daily/exim4-base</filename>) | |
1317 | does basic housekeeping tasks: | |
1318 | <itemizedlist> | |
1319 | <listitem> | |
1320 | <simpara> | |
1321 | It reads <filename>/etc/default/exim4</filename>, so you | |
1322 | can use this file to change any of the variables used in | |
1323 | the cron job. | |
1324 | </simpara> | |
1325 | </listitem> | |
1326 | <listitem> | |
1327 | <simpara> | |
1328 | It is a no-op if no Exim4 binary is found. | |
1329 | </simpara> | |
1330 | </listitem> | |
1331 | <listitem> | |
1332 | <simpara> | |
1333 | If <command>$E4BCD_DAILY_REPORT_TO</command> is set | |
1334 | to a non-empty string, the output of eximstats is | |
1335 | mailed to the address given in that variable. The | |
1336 | default is empty, so no reports are sent. Options | |
1337 | for eximstats can be given in | |
1338 | <command>$E4BCD_DAILY_REPORT_OPTIONS</command>. | |
1339 | </simpara> | |
1340 | </listitem> | |
1341 | <listitem> | |
1342 | <simpara> | |
1343 | A non-empty paniclog is a nearly sure sign of bad | |
1344 | things going on. Thus, the cron job will send out | |
1345 | warning messages to the syslog and root if it finds | |
1346 | the panic log non-empty. | |
1347 | Please note that the paniclog is not rotated daily, | |
1348 | so existing issues will be reported daily until | |
1349 | either the paniclog is rotated due to its sheer | |
1350 | size, or you manually move it away, for example by | |
1351 | calling <command>logrotate -f | |
1352 | /etc/logrotate.d/exim4-paniclog</command> from a shell. | |
1353 | </simpara> | |
1354 | <simpara> | |
1355 | Just in case your system logs transient error | |
1356 | situations to the panic log as well (see, for | |
1357 | example, | |
1358 | <ulink url="http://www.exim.org/bugzilla/show_bug.cgi?id=92">Exim Bug 92</ulink>), | |
1359 | you can configure | |
1360 | <command>$E4BCD_PANICLOG_NOISE</command> to a | |
1361 | regular expression. If the paniclog contains only | |
1362 | lines that match that regular expression, no warning | |
1363 | messages are generated. | |
1364 | </simpara> | |
1365 | <simpara> | |
1366 | If you want to disable paniclog monitoring | |
1367 | completely, set <command>$E4BCD_WATCH_PANICLOG</command> | |
1368 | to no. <command>E4BCD_WATCH_PANICLOG=once</command> will | |
1369 | rotate a non-empty paniclog automatically after sending out | |
1370 | the warning e-mail. | |
0baa7b9d SB |
1371 | </simpara> |
1372 | <simpara> | |
1373 | The <command>E4BCD_PANICLOG_LINES</command> setting can be | |
1374 | used to limit the number of lines of paniclog quoted in | |
1375 | warning email. It is set to 10 by default. | |
de45f55a AM |
1376 | </simpara> |
1377 | </listitem> | |
1378 | <listitem> | |
1379 | <simpara> | |
1380 | It tidies up the retry and hints databases. | |
1381 | </simpara> | |
1382 | </listitem> | |
1383 | </itemizedlist> | |
1384 | </para> | |
1385 | </section> | |
1386 | </section> | |
1387 | ||
1388 | <section> <title>Using Exim with inetd/xinetd</title> | |
1389 | <para> | |
1390 | Exim4 is run as a separate daemon instead of inetd/xinetd for | |
1391 | two reasons: | |
1392 | <variablelist> | |
1393 | <varlistentry> | |
1394 | <term>Ease of maintenance:</term> | |
1395 | <listitem> | |
1396 | <simpara> | |
1397 | update-inetd is difficult to impossible to handle | |
1398 | correctly (Just check the archived bug reports of Exim.) | |
1399 | and update-inetd seems to be unmaintained for a long | |
1400 | time, nobody dares to touch it. To quote Mark Baker, the | |
1401 | maintainer of Exim (v3): "I really wish I had never used | |
1402 | inetd in the first place, but simply set up exim to run | |
1403 | as a daemon, but it's too late to change that now." | |
1404 | </simpara> | |
1405 | </listitem> | |
1406 | </varlistentry> | |
1407 | <varlistentry> | |
1408 | <term>Extended features</term> | |
1409 | <listitem> | |
1410 | <simpara> | |
1411 | Running from <command>inetd</command> interferes with | |
1412 | Exim's resource controls (e.g it disables | |
1413 | smtp_accept_max_per_host and smtp_accept_max). | |
1414 | </simpara> | |
1415 | </listitem> | |
1416 | </varlistentry> | |
1417 | </variablelist> | |
1418 | </para> | |
1419 | <para> | |
1420 | If you introduce bugs on your systems by running from (x)inetd | |
1421 | you are on your own! If you want to run exim from | |
1422 | <command>xinetd</command>, follow these steps: | |
1423 | <orderedlist> | |
1424 | <listitem> | |
1425 | <simpara> | |
1426 | Disable Exim 4's listening daemon by executing | |
1427 | <command>update-exim4defaults --queuerunner | |
1428 | queueonly</command> | |
1429 | </simpara> | |
1430 | </listitem> | |
1431 | <listitem> | |
1432 | <para> | |
1433 | Create <filename>/etc/xinetd.d/exim4</filename> | |
1434 | <programlisting> | |
1435 | service smtp | |
1436 | { | |
1437 | disable = no | |
1438 | flags = NAMEINARGS | |
1439 | socket_type = stream | |
1440 | protocol = tcp | |
1441 | wait = no | |
1442 | user = Debian-exim | |
1443 | group = Debian-exim | |
1444 | server = /usr/sbin/exim4 | |
1445 | server_args = exim4 -bs | |
1446 | } | |
1447 | </programlisting> | |
1448 | </para> | |
1449 | </listitem> | |
1450 | <listitem> | |
1451 | <simpara>Run <command>invoke-rc.d exim4 restart; invoke-rc.d | |
1452 | (x)inetd restart</command></simpara> | |
1453 | </listitem> | |
1454 | </orderedlist> | |
1455 | </para> | |
1456 | <para>If you want to use plain inetd, insert following line into | |
1457 | <filename>/etc/inetd.conf</filename>:<programlisting> | |
1458 | smtp stream tcp nowait Debian-exim /usr/sbin/exim4 exim4 -bs | |
1459 | </programlisting> | |
1460 | </para> | |
1461 | </section> | |
1462 | ||
1463 | <section> <title>Handling incoming mail for local accounts with low UID</title> | |
1464 | <para> | |
1465 | Since system accounts (mail, uucp, lp etc) are usually aliased | |
1466 | to root, and root's mailbox is usually read by a human, these | |
1467 | account names have started to be a common target for spammers. | |
1468 | The Debian Exim 4 packages have a mechanism to deal with this | |
1469 | situation. However, since this derives rather far from normal | |
1470 | behavior, it is disabled by default. | |
1471 | </para> | |
1472 | <para> | |
1473 | To enable it, set the macro FIRST_USER_ACCOUNT_UID to a numeric, | |
1474 | non-zero value. Incoming mail for local users that have a UID | |
1475 | lower than FIRST_USER_ACCOUNT_UID is rejected with the message "no | |
1476 | mail to system accounts". Incoming mail for local users that | |
1477 | have a UID greater or equal FIRST_USER_ACCOUNT_UID are processed as | |
1478 | usual. Therefore, the default value of 0 ensures that the | |
1479 | mechanism is disabled. On Debian systems, setting | |
1480 | FIRST_USER_ACCOUNT_UID to 500 or 1000 (depending on your local policy) | |
1481 | will disable incoming mail for system accounts. | |
1482 | </para> | |
1483 | <para> | |
1484 | Just in case that you need exceptions to the rule, | |
0baa7b9d | 1485 | <filename>/etc/exim4/lowuid-aliases</filename> is an alias |
de45f55a AM |
1486 | file that is only honored for local accounts with UID lower |
1487 | than FIRST_USER_ACCOUNT_UID. If you define an alias for such an | |
1488 | account here, incoming mail is processed according to the | |
1489 | alias. If you alias the account to itself, messages are | |
1490 | delivered to the account itself, which is an exception to the | |
1491 | rule that messages for low-UID accounts are rejected. The | |
0baa7b9d | 1492 | format of <filename>/etc/exim4/lowuid-aliases</filename> is |
de45f55a AM |
1493 | just another alias file. |
1494 | </para> | |
1495 | </section> | |
1496 | <section> <title>How to bypass local routing specialities</title> | |
1497 | <para> | |
0baa7b9d | 1498 | Sometimes, it might be desirable to be able to bypass local |
de45f55a AM |
1499 | routing specialities like the alias file or a user-forward |
1500 | file. This is possible in the Debian Exim4 packages by | |
1501 | prefixing the account name with "real-". For a local account | |
1502 | name "foo", "real-foo@hostname.example" will result in direct | |
1503 | delivery to foo's local Mailbox. | |
1504 | </para> | |
1505 | <para> | |
1506 | This feature is by default only available for locally | |
1507 | generated messages. If you want it to be accessible for | |
1508 | messages delivered from remote as well, set the Exim macro | |
1509 | COND_LOCAL_SUBMITTER to true. If you do not want this at all, | |
1510 | set the macro to false. Please note that the userforward | |
1511 | router uses this feature to get error messages delivered, i.e. | |
1512 | notifying the user of a syntax error in her | |
1513 | <filename>.forward</filename> file. | |
1514 | </para> | |
1515 | </section> | |
1516 | <section> <title>Using more complex deliveries from alias files</title> | |
1517 | <para> | |
1518 | Delivery to arbitrary files, directory or to pipes in the | |
1519 | <filename>/etc/aliases</filename> file is disabled by default | |
1520 | in the Debian Exim 4 packages. The delivery process including the | |
1521 | program being piped to would run as the exim admin-user | |
1522 | Debian-exim, which might open up security holes. | |
1523 | </para> | |
1524 | <para> | |
1525 | Invoking pipes from <filename>/etc/aliases</filename> file is | |
1526 | widely considered obsolete and deprecated. The Debian Exim | |
1527 | package maintainers would like to suggest using a dedicated | |
1528 | router/transport pair to invoke local processes for mail | |
1529 | processing. For example, the Debian mailman package contains a | |
1530 | <filename>/usr/share/doc/mailman/README.Exim4.Debian</filename> file | |
1531 | that gives a good example how to implement this. Using a | |
1532 | dedicated router/transport pair have the following advantages: | |
1533 | <itemizedlist> | |
1534 | <listitem> | |
1535 | <para> | |
1536 | The router/transport pair can be put in place by another | |
1537 | package, giving a well-defined transaction point between | |
1538 | Exim 4 and $PACKAGE. | |
1539 | </para> | |
1540 | </listitem> | |
1541 | <listitem> | |
1542 | <para> | |
1543 | Not allowing pipe deliveries from alias files makes it | |
1544 | harder to accidentally run programs with wrong | |
1545 | privileges. | |
1546 | </para> | |
1547 | </listitem> | |
1548 | <listitem> | |
1549 | <para> | |
1550 | It is possible to run different pipe processes under | |
1551 | different accounts. | |
1552 | </para> | |
1553 | </listitem> | |
1554 | <listitem> | |
1555 | <para> | |
1556 | Even if only invoking a single local program, it is easier | |
1557 | to do with your dedicated router/transport since you won't | |
1558 | need to change this file, making automatic updates of this | |
1559 | file possible for future versions of the Exim 4 packages. If | |
1560 | you do local changes here, dpkg conffile handling will | |
1561 | bother you on future updates. | |
1562 | </para> | |
1563 | </listitem> | |
1564 | </itemizedlist> | |
1565 | If you insist on using <filename>/etc/aliases</filename> in | |
1566 | the traditional way, you will need to activate the | |
1567 | respective functions by setting the transport options on the | |
1568 | system_aliases router appropriately. Macros are defined to make | |
1569 | this easier. See | |
1570 | ||
1571 | <filename>/etc/exim4/conf.d/router/400_exim4-config_system_aliases</filename> | |
1572 | for information about which macros are available. You might | |
1573 | find the address_file, address_pipe and/or address_directory | |
1574 | transports that are used for the userforward router helpful in | |
1575 | writing your own transports for use in the system_aliases router. | |
1576 | </para> | |
1577 | <para> | |
1578 | If any of your aliases expand to pipes or files or directories | |
1579 | you should set up a user and a group for these deliveries to run | |
1580 | under. You can do this by setting the "user" and - if necessary | |
1581 | - a "group" option and adding a "group" option if necessary. | |
1582 | Alternatively, you can specify "user" and/or "group" on the | |
1583 | transports that are used. | |
1584 | </para> | |
1585 | </section> | |
1586 | ||
1587 | <section> <title>Putting Exim 4 and UUCP together</title> | |
1588 | <para> | |
1589 | UUCP is a traditional way to execute remote jobs (e.g. spool | |
1590 | mails), and as a lot of old things there are much more than one | |
1591 | way to do it. However, today, the ways to handle it have boiled | |
1592 | down to more or less two different ways. | |
1593 | </para> | |
1594 | <para> | |
1595 | Our recommendation is to use bsmtp/rsmtp wherever possible, | |
1596 | because it supports all kinds of mail addresses (also the empty | |
1597 | ones in bounces), and is also better from the security point of | |
1598 | view. | |
1599 | </para> | |
1600 | <section> <title>Sending mail via UUCP</title> | |
1601 | <section> <title>rmail with full addresses</title> | |
1602 | <para> | |
1603 | rmail is the oldest way to transfer mail to a remote system. | |
1604 | However, today it is normally required to use addresses with | |
1605 | full domains for that (Well, they look like any normal address | |
1606 | for you, and we do not tell about the other way to not confuse | |
1607 | you ;). If you want this, you can use this transport: | |
1608 | </para> | |
1609 | <programlisting> | |
1610 | rmail: | |
1611 | debug_print = "T: rmail for $pipe_addresses" | |
1612 | driver=pipe | |
1613 | command = uux - -r -a$sender_address -gC $domain_data!rmail $pipe_addresses | |
1614 | return_fail_output | |
1615 | user=uucp | |
1616 | batch_max = 20 | |
1617 | </programlisting> | |
1618 | <para> | |
1619 | However, all recipients are handled via the command line, so | |
1620 | you are discouraged to use it. | |
1621 | </para> | |
1622 | </section> | |
1623 | <section> <title>bsmtp/rsmtp</title> | |
1624 | <para> | |
1625 | This is a more efficient way to transfer mails. It works | |
1626 | like sending SMTP via a pipe, but instead of waiting for an | |
1627 | answer, the SMTP is just batched; from this is also the name | |
1628 | batched SMTP or short bsmtp. | |
1629 | </para> | |
1630 | <para> | |
1631 | Furthermore, this way won't fail on addresses like " | |
1632 | "@do.main. If you want this, please use this, if the remote | |
1633 | site uses rsmtp (e.g. is Exim 4): | |
1634 | </para> | |
1635 | <programlisting> | |
1636 | rsmtp: | |
1637 | debug_print = "T: rsmtp for $pipe_addresses" | |
1638 | driver=pipe | |
1639 | command = /usr/bin/uux - -r -a$sender_address -gC $domain_data!rsmtp | |
1640 | use_bsmtp | |
1641 | return_fail_output | |
1642 | user=uucp | |
1643 | batch_max = 100 | |
1644 | </programlisting> | |
1645 | <para> | |
1646 | and this if it wants bsmtp as the command: | |
1647 | </para> | |
1648 | <programlisting> | |
1649 | bsmtp: | |
1650 | debug_print = "T: bsmtp for $pipe_addresses" | |
1651 | driver=pipe | |
1652 | command = /usr/bin/uux - -r -a$sender_address -gC $domain_data!bsmtp | |
1653 | use_bsmtp | |
1654 | return_fail_output | |
1655 | user=uucp | |
1656 | batch_max = 100 | |
1657 | </programlisting> | |
1658 | <para> | |
1659 | Of course, these examples can be extended for e.g. | |
1660 | compression (but you can also use ssh for compression, if | |
1661 | you want). | |
1662 | </para> | |
1663 | </section> | |
1664 | <section> <title>The router</title> | |
1665 | <para> | |
1666 | You need a router to tell Exim 4 which mails to forward to | |
1667 | UUCP. You can use this one; please adopt the last line. Of | |
1668 | course, it is also possible to send mail via more than one way. | |
1669 | </para> | |
1670 | <programlisting> | |
1671 | uucp_router: | |
1672 | debug_print = "R: uucp_router for $local_part@$domain" | |
1673 | driver=accept | |
1674 | require_files = +/usr/bin/uux | |
1675 | domains = wildlsearch;/etc/exim4/uucp | |
1676 | transport = rsmtp | |
1677 | </programlisting> | |
1678 | <para> | |
1679 | The file <filename>/etc/exim4/uucp</filename> looks like: | |
1680 | </para> | |
1681 | <programlisting> | |
1682 | *.do.main uucp.name.of.remote.side | |
1683 | </programlisting> | |
1684 | </section> | |
1685 | <section> <title>Speaking UUCP with the smarthost</title> | |
1686 | <para> | |
1687 | If you have a leaf system (i.e. all your mail not for your | |
1688 | local system goes to a single remote system), you can just | |
1689 | forward all non-local mail to the remote UUCP system. In | |
1690 | this case, you can replace "domains = ..." with "domains = ! | |
1691 | +local_domains", but then you need also to replace | |
1692 | $domain_data in the transport by the UUCP-name of your | |
1693 | smarthost. The file <filename>/etc/exim4/uucp</filename> is | |
1694 | not needed in this case. | |
1695 | </para> | |
1696 | </section> | |
1697 | </section> | |
1698 | <section> <title>Receiving mail via UUCP</title> | |
1699 | <section> <title>Allow UUCP to use any envelope address</title> | |
1700 | <para> | |
1701 | Depending how much you trust your local users, you might use | |
1702 | trusted_users and add uucp to it or use | |
1703 | local_sender_retain=true and local_from_check=false. | |
1704 | </para> | |
1705 | </section> | |
1706 | <section> <title>If you get batched smtp</title> | |
1707 | <para> | |
1708 | Allow uucp to execute rsmtp via | |
1709 | <programlisting> | |
1710 | commands rmail rnews rsmtp | |
1711 | </programlisting> | |
1712 | in your <filename>/etc/uucp/sys</filename>, and ask the | |
1713 | sending site to use rsmtp (and not bsmtp) as the batched | |
1714 | command. | |
1715 | </para> | |
1716 | </section> | |
1717 | </section> | |
1718 | </section> | |
01e60269 AM |
1719 | <section> <title>Notes on running SpamAssassin at SMTP time</title> |
1720 | <para> | |
1721 | Exim can run | |
1722 | <ulink url="https://spamassassin.apache.org/"> | |
1723 | SpamAssassin</ulink> while receiving a message by SMTP which | |
1724 | allows one to avoid acceptance of spam messages. The Debian | |
1725 | configuration contains some example code for running SpamAssassin, | |
1726 | but like all filtering this needs to be handled carefully. | |
1727 | </para> | |
1728 | <para> | |
1729 | SpamAssassin's default report should not be used in a add_header | |
1730 | statement since it contains empty lines. (This triggers e.g. | |
1731 | Amavis' warning "BAD HEADER SECTION, Improper folded header field | |
1732 | made up entirely of whitespace".) This is a safe, terse alternative: | |
1733 | <programlisting> | |
1734 | clear_report_template | |
1735 | report (_SCORE_ / _REQD_ requ) _TESTSSCORES(,)_ autolearn=_AUTOLEARN_ | |
1736 | </programlisting> | |
1737 | </para> | |
1738 | <para> | |
1739 | Rejecting spam messages: Do not reject spam-messages received on | |
1740 | (non-spam) mailing lists, this can/will cause auto-unsubscription. | |
1741 | This also applies to messages received via forwarding services | |
1742 | (e.g. @debian.org addresses). If theses messages are rejected the | |
1743 | forwarding services will need to send a bounce address to the | |
1744 | spammer and will probably disable the forwarding if it happens all | |
1745 | the time. You will need to have some kind of whitelist to exclude | |
1746 | these hosts. | |
1747 | </para> | |
1748 | <para> | |
1749 | Security considerations: By default <command>spamd</command> | |
1750 | runs as root and changes uid/gid to the requested user to run | |
1751 | SpamAssassin. The example uses SpamAssassin default non-privileged | |
1752 | user (nobody) which prevents use of Bayesian filtering since this | |
1753 | requires persistent storage. You might want to setup a dedicated | |
1754 | user for exim spam scanning and use that one, either for a separate | |
1755 | SpamAssassin user profile or to run SpamAssassin as non-privileged | |
1756 | user. | |
1757 | </para> | |
1758 | </section> | |
de45f55a AM |
1759 | </section> |
1760 | ||
1761 | <section> <title>Updating from Exim 3</title> | |
1762 | <para> | |
1763 | If you use <command>exim4-config</command> from Debian, you will | |
1764 | get the debconf based configuration scheme that is intended to | |
1765 | cover the majority of cases. | |
1766 | </para> | |
1767 | <para> | |
1768 | If <command>exim4-config</command> is installed while an Exim 3 | |
1769 | package is present on the system, | |
1770 | <command>exim4-config</command> tries to parse the Exim 3 config | |
1771 | file to determine the answers that were given to | |
1772 | <command>eximconfig</command> on Exim 3 installation. These | |
1773 | answers are then taken as default values for the debconf based | |
1774 | configuration process. Be warned! <command>eximconfig</command> | |
1775 | from the Exim 3 packages does not record the explicit answers | |
1776 | given on Exim 3 configuration. So we have to guess the answers | |
1777 | from the Exim 3 configuration file | |
1778 | <filename>/etc/exim/exim.conf</filename>, which is bound to fail | |
1779 | if the config file has been modified after using | |
1780 | <command>eximconfig</command>. | |
1781 | </para> | |
1782 | <para> | |
1783 | This is the reason why we refrained from doing a "silent update", but | |
1784 | only use the guessed answers to get reasonable defaults for our | |
1785 | debconf based configuration process. | |
1786 | </para> | |
1787 | <para> | |
1788 | Please note that we do not use the | |
1789 | <command>exim_convert4r4</command> script, but try to configure | |
1790 | the Exim 4 package in the same way Exim 3 was. This will | |
1791 | hopefully aid future updates. | |
1792 | </para> | |
1793 | <para> | |
1794 | If you have used a customized Exim 3 configuration, you can of | |
1795 | course use <command>exim_convert4r4</command>, and install the | |
1796 | resulting file as <filename>/etc/exim4/exim4.conf</filename> | |
1797 | after careful inspection. Exim 4 will then use that file and | |
1798 | ignore the file that it generated from the debconf | |
1799 | configuration. To aid future updates, we do, however, encourage | |
1800 | you not to use the | |
1801 | <filename>exim_convert4r4-generated</filename> file verbatim but | |
1802 | instead drop appropriate configuration snippets in their | |
1803 | appropriate place in <filename>/etc/exim4/conf.d</filename>. | |
1804 | </para> | |
1805 | </section> | |
1806 | <section> <title>Misc Notes</title> | |
1807 | <section> <title>PAM</title> | |
1808 | <para> | |
0baa7b9d | 1809 | On Debian systems the PAM modules run as the same user |
de45f55a AM |
1810 | as the calling program, so they cannot do anything you |
1811 | could not do yourself, and in particular cannot access | |
1812 | <filename>/etc/shadow</filename> unless the user is in group | |
1813 | shadow. - If you want to use | |
1814 | <filename>/etc/shadow</filename> for Exim's SMTP AUTH you | |
1815 | will need to run exim as group shadow. Only | |
1816 | exim4-daemon-heavy is linked against libpam. We suggest using | |
1817 | saslauthd instead. | |
1818 | </para> | |
1819 | </section> | |
1820 | <section> <title>Account name restrictions</title> | |
1821 | <para> | |
1822 | In the default configuration, Exim cannot locally deliver | |
1823 | mail to accounts which have capitals in their name. This is | |
1824 | caused by the fact that Exim converts the local part of incoming | |
0baa7b9d | 1825 | mail to lower case before the comparison done by the |
de45f55a AM |
1826 | check_local_user directive in routers is done. |
1827 | </para> | |
1828 | <para> | |
1829 | The router option caseful_local_part can be used to control | |
1830 | this, and we decided not to set this option in the Debian | |
1831 | configuration since it would be a rather big change to Exim's | |
1832 | default behavior. | |
1833 | </para> | |
1834 | </section> | |
1835 | <section> <title>No deliveries to root!</title> | |
1836 | <para> | |
1837 | No Exim 4 version released with any Debian OS can run | |
1838 | deliveries as root. If you don't redirect mail for root via | |
1839 | <filename>/etc/aliases</filename> to a nonprivileged | |
1840 | account, the mail will be delivered to | |
1841 | <filename>/var/mail/mail</filename> with permissions 0600 and | |
1842 | owner mail:mail. | |
1843 | </para> | |
1844 | <para> | |
1845 | This redirection is done by the mail4root router which | |
1846 | is last in the list and will thus catch mail for root that has not | |
1847 | been taken care of earlier. | |
1848 | </para> | |
1849 | </section> | |
1850 | <section> <title>Debugging maintainer and init scripts</title> | |
1851 | <para> | |
1852 | Most of the scripts that come with this Debian package do a | |
1853 | <command>set -x</command> if invoked with the environment | |
1854 | variable EX4DEBUG defined and non-zero. This is particularly | |
1855 | handy if you need to debug the maintainer scripts that are | |
1856 | invoked during package installation. Since dpkg redirects | |
1857 | stdout of maintainer scripts, calling dpkg with EX4DEBUG | |
1858 | set might yield interesting results. If in doubt, invoke | |
1859 | the maintainer scripts with EX4DEBUG set manually directly | |
1860 | from the command line. | |
1861 | </para> | |
1862 | </section> | |
1863 | <section> <title>SELinux</title> | |
1864 | <para> | |
1865 | There is no SELinux policy for Exim4 available so far. | |
1866 | Until this is resolved, users should use postfix or | |
1867 | sendmail if they intend to run SELinux. | |
1868 | </para> | |
1869 | <para> | |
1870 | The Debian Exim4 maintainers would appreciate if | |
1871 | somebody could write an SELinux policy. We will gladly | |
1872 | use them in the Debian packages as long as there is | |
1873 | somebody available to test, debug and support. | |
1874 | </para> | |
1875 | </section> | |
1876 | <section> <title>misc</title> | |
1877 | <itemizedlist> | |
1878 | <listitem> | |
1879 | <simpara> | |
1880 | <command>convert4r4</command> is installed as | |
1881 | <filename>/usr/sbin/exim_convert4r4.</filename> | |
1882 | </simpara> | |
1883 | </listitem> | |
1884 | <listitem> | |
1885 | <simpara> | |
1886 | The charset for $header_foo expansions defaults to | |
1887 | UTF-8 instead of ISO-8859-1. | |
1888 | </simpara> | |
1889 | </listitem> | |
1890 | <listitem> | |
1891 | <simpara> | |
1892 | <ulink url="http://marc.merlins.org/linux/exim/"> | |
1893 | Marc Merlin's Exim 4 Page</ulink> has a lot of ACL | |
1894 | examples. | |
1895 | </simpara> | |
1896 | </listitem> | |
1897 | <listitem> | |
1898 | <simpara> | |
1899 | For an example of Exim usage in a | |
1900 | <emphasis>large</emphasis> installation, see | |
1901 | Tony Finch's | |
1902 | <ulink | |
1903 | url="http://www-uxsup.csx.cam.ac.uk/~fanf2/hermes/doc/talks/2005-02-eximconf/"> | |
1904 | paper</ulink> | |
1905 | about the Exim installation at University of Cambridge: | |
1906 | </simpara> | |
1907 | </listitem> | |
1908 | </itemizedlist> | |
1909 | </section> | |
1910 | </section> | |
1911 | <section> <title>Debian modifications to the Exim source</title> | |
0baa7b9d SB |
1912 | <itemizedlist> |
1913 | <listitem> | |
1914 | <simpara> | |
1915 | Install the exim binary as /usr/sbin/exim4 instead of | |
1916 | /usr/sbin/exim-<version> with a symlink /usr/sbin/exim. Also | |
1917 | adapt the documentation. | |
1918 | </simpara> | |
1919 | </listitem> | |
1920 | <listitem> | |
1921 | <simpara> | |
1922 | Make the build reproducible. Pull date/time from debian/changelog | |
1923 | and use it as build time instead of using __DATE__. | |
1924 | </simpara> | |
1925 | </listitem> | |
1926 | <listitem> | |
1927 | <simpara> | |
1928 | Documentation updates | |
1929 | </simpara> | |
1930 | <itemizedlist> | |
1931 | <listitem> | |
1932 | <simpara> | |
1933 | Mention how to install the Debian packaged perl-modules needed | |
1934 | for eximstats' graphs. | |
1935 | </simpara> | |
1936 | </listitem> | |
1937 | <listitem> | |
1938 | <simpara> | |
1939 | Add a warning about convert4r4. | |
1940 | </simpara> | |
1941 | </listitem> | |
1942 | <listitem> | |
1943 | <simpara> | |
1944 | Point to the <ulink | |
1945 | url="mailto:pkg-exim4-users@lists.alioth.debian.org"> | |
1946 | Debian-specific mailing list</ulink> instead of | |
1947 | the <ulink url="mailto:exim-users@exim.org">official | |
1948 | exim-users list</ulink>. | |
1949 | </simpara> | |
1950 | </listitem> | |
1951 | </itemizedlist> | |
1952 | </listitem> | |
1953 | <listitem> | |
1954 | <simpara> | |
1955 | <ulink | |
1956 | url="http://marc.merlins.org/linux/exim/files/sa-exim-current/">localscan_dlopen.patch</ulink>: | |
1957 | This patch makes it possible to use and switch between | |
1958 | different local_scan | |
de45f55a AM |
1959 | functions without recompiling Exim. Use |
1960 | local_scan_path = /path/to/sharedobject to utilize | |
1961 | local_scan() in <filename>/path/to/sharedobject</filename>. | |
0baa7b9d SB |
1962 | </simpara> |
1963 | </listitem> | |
1964 | </itemizedlist> | |
de45f55a AM |
1965 | </section> |
1966 | ||
1967 | <section> <title>Credits</title> | |
1968 | <para><variablelist> | |
1969 | <varlistentry> | |
1970 | <term><ulink url="mailto:aba@not.so.argh.org">Andreas | |
1971 | Barth</ulink></term> | |
1972 | <listitem> | |
1973 | <simpara>UUCP documentation</simpara> | |
1974 | </listitem> | |
1975 | </varlistentry> | |
1976 | <varlistentry> | |
1977 | <term>Dan Weber, Ryen Underwood</term> | |
1978 | <listitem> | |
1979 | <simpara>inetd/xinetd documentation</simpara> | |
1980 | </listitem> | |
1981 | </varlistentry> | |
1982 | </variablelist> | |
1983 | </para> | |
1984 | </section> | |
1985 | ||
1986 | </article> |