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> | |
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> | |
89fb561f AM |
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. | |
de45f55a AM |
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 | |
89fb561f AM |
490 | Exim specification chapter <phrase>"Domain, host, address, and |
491 | local part lists"</phrase> | |
492 | and the exim4-config_files man page. | |
de45f55a AM |
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 | |
89fb561f AM |
514 | specified (See Exim specification, chapter |
515 | <phrase>"The manualroute router"</phrase>, section | |
516 | <phrase>"How the list of hosts is used"</phrase>.) | |
de45f55a AM |
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 | |
89fb561f | 778 | touching dpkg-conffiles itself is explicitly allowed and wanted, |
de45f55a AM |
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 | |
89fb561f AM |
805 | <phrase>"The Exim run time configuration file"</phrase>, for |
806 | details how macro expansion works. | |
de45f55a AM |
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 | |
89fb561f | 1144 | SMTPLISTENEROPTIONS='-oX 465:25 -oP /run/exim4/exim.pid' |
de45f55a AM |
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> | |
89fb561f | 1154 | It might be appropriate to add "+tls_cipher" to |
de45f55a AM |
1155 | any log_selector statement you might already have, or to add a |
1156 | log_selector statement setting these two options in a local | |
89fb561f AM |
1157 | configuration file. (For Debian's configuration simply define |
1158 | the MAIN_LOG_SELECTOR macro.) | |
1159 | This option makes Exim log what cipher | |
de45f55a | 1160 | your Exim and the peer's mailer have negotiated to use to |
89fb561f | 1161 | encrypt the transaction. |
de45f55a AM |
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. | |
89fb561f AM |
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. | |
de45f55a AM |
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, | |
89fb561f | 1500 | <filename>/etc/exim4/lowuid-aliases</filename> is an alias |
de45f55a AM |
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 | |
89fb561f | 1507 | format of <filename>/etc/exim4/lowuid-aliases</filename> is |
de45f55a AM |
1508 | just another alias file. |
1509 | </para> | |
1510 | </section> | |
1511 | <section> <title>How to bypass local routing specialities</title> | |
1512 | <para> | |
89fb561f | 1513 | Sometimes, it might be desirable to be able to bypass local |
de45f55a AM |
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> | |
89fb561f | 1784 | On Debian systems the PAM modules run as the same user |
de45f55a AM |
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 | |
89fb561f | 1800 | mail to lower case before the comparison done by the |
de45f55a AM |
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> | |
89fb561f AM |
1887 | <itemizedlist> |
1888 | <listitem> | |
1889 | <simpara> | |
1890 | Install the exim binary as /usr/sbin/exim4 instead of | |
1891 | /usr/sbin/exim-<version> 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 | |
de45f55a AM |
1934 | functions without recompiling Exim. Use |
1935 | local_scan_path = /path/to/sharedobject to utilize | |
1936 | local_scan() in <filename>/path/to/sharedobject</filename>. | |
89fb561f AM |
1937 | </simpara> |
1938 | </listitem> | |
1939 | </itemizedlist> | |
de45f55a AM |
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> |