diff options
Diffstat (limited to 'debian/README.Debian.xml')
| -rw-r--r-- | debian/README.Debian.xml | 2051 |
1 files changed, 2051 insertions, 0 deletions
diff --git a/debian/README.Debian.xml b/debian/README.Debian.xml new file mode 100644 index 0000000..060c69a --- /dev/null +++ b/debian/README.Debian.xml @@ -0,0 +1,2051 @@ +<?xml version="1.0" encoding="utf-8"?> +<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" + "http://www.docbook.org/xml/4.4/docbookx.dtd"> +<article> <title>Exim 4 for Debian</title> + <section> <title>Introduction</title> + <para> + If you're reading this, you have found the README.Debian + file. This is good, thanks! Please continue reading this file in + its entirety. It is full of important information and has been + written with the questions in mind that keep popping up on the + mailing lists. + </para> + <section> <title>How to find your way around the Documentation</title> + <para> + Exim comes with very extensive documentation. Here is how to + find it. + <orderedlist> + <listitem> + <simpara> + A lot of information about Debian's Exim 4 + packaging can be found in this document. + </simpara> + </listitem> + <listitem> + <simpara> + The packages contain a lot of Debian-specific man pages. + Use the <command>apropos exim</command> command to get a list. + </simpara> + </listitem> + <listitem> + <simpara> + Most files that control the default configuration are + documented in the exim4-config_files(5) man page, which + is symlinked to the file names. man <filename> should + lead you to the page. + </simpara> + </listitem> + <listitem> + <para> + The very extensive Upstream documentation is shipped + <orderedlist> + <listitem> + <simpara> + in text form + (<filename>/usr/share/doc/exim4-base/spec.txt.gz</filename>) + with the binary packages. + </simpara> + </listitem> + <listitem> + <simpara> + in HTML in the package + <filename>exim4-doc-html</filename> + </simpara> + </listitem> + <listitem> + <simpara> + as a Texinfo file in the package + <filename>exim4-doc-info</filename> + </simpara> + </listitem> + </orderedlist> + </para> + </listitem> + </orderedlist> + </para> + <para> + Please note that documentation found on the web or in other + parts of the Debian system (such as the Debian Reference) + might be outdated and thus give wrong advice. In doubt, the + documentation listed above should take precedence. + </para> + </section> + <section> <title>Getting Support</title> + <para> + For your questions and comments, there is a <ulink + url="http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users"> + Debian-specific mailing list</ulink>. Please ask Debian-specific + questions there, and only write to the upstream exim-users mailing + list if + you are sure that your question is not Debian-specific. + Debian-specific questions are more likely to find answers on + our pkg-exim4-users mailing list, while complex custom + configuration issues might be more easily solved on the + upstream exim-users mailing list because of the broader and + more experienced audience there. You can subscribe to + pkg-exim4-users <ulink + url="http://lists.alioth.debian.org/mailman/listinfo/pkg-exim4-users"> + via the subscription web page;</ulink> you need to be + subscribed to post. + </para> + <para> + If you think that your question might be more easily answered + if one knows a bit about your configuration, you might want to + execute <command>reportbug --subject="none" --offline --quiet + --severity=wishlist --body="none" --output=exim4.reportbug + exim4-config</command> on the system in question, answer yes + to both "include [extended] configuration" questions and include + the contents of the exim4.reportbug file generated by this + command with your question. Please check whether the file + contains any confidential information before sending. + </para> + </section> + <section> <title>Packaging</title> + <para> + Similar to the Apache2 package, Exim 4 is an entirely + different package that does not currently offer a smooth + upgrade path from Debian's Exim 3 packages. + </para> + <para> + It is the first Exim package in Debian that can be configured + using debconf. However, the entire configuration framework is + extremely flexible, allowing you to get exactly the amount of + control you need for the job at hand. + </para> + <section> <title>Feature Sets in the daemon packages</title> + <para> + To use Exim 4, you need at least the following packages: + <variablelist> + <varlistentry> + <term>exim4-base</term> + <listitem> + <simpara>support files for all Exim MTA (v4) packages</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>exim4-config</term> + <listitem> + <simpara>configuration for the Exim MTA (v4)</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>exim4-daemon-light</term> + <listitem> + <simpara>lightweight exim MTA (v4) daemon</simpara> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + Just apting the metapackage <command>exim4</command> will pull + in the other packages per dependency. You'll get an exim daemon + with minimal feature set (no external lookups). + </para> + <para> + If you need more advanced features like LDAP, sqlite, PostgreSQL + and MySQL data lookups, SASL and SPA SMTP authentication, embedded + Perl interpreter, and exiscan-acl for integration of + virus-scanners and SpamAssassin, you can replace + <command>exim4-daemon-heavy</command> instead of + <command>exim4-daemon-light</command>. Additionally, the source + package offers infrastructure to build your own custom-tailored + exim4-daemon-custom which exactly fits your special local needs. + The infrastructure to do so is already in place, see + debian/rules for instructions. + </para> + </section> + <section> <title>How to build a custom daemon</title> + <para> + The process of building a custom daemon is partially + documented in the <filename>debian/rules</filename> file + in the source package. Patches for more documentation are welcome. + </para> + </section> + </section> + </section> + <section> <title>Configuration of Exim 4 in the Debian packages</title> + <para> + Generally, the Debian Exim 4 packages are configured through + debconf. You have been asked some questions on package installation, + and your initial Exim configuration has been created from your + answers. You can repeat the configuration process any time by invoking + <command>dpkg-reconfigure exim4-config</command>. If you are an + experienced Exim administrator and prefer to have your own, + hand-crafted, non-automatic Exim configuration, you will find + information about how to do so in + <xref linkend="completely-different-configuration"/>. + </para> + <para> + The debconf-driven configuration is mainly geared for a + one-domain shell account machine/workstation with local delivery + as suggested by the original upstream default configuration. + If you configure the packages to handle more than one local + domain, all local domains are treated identically. The domain + part is not used for routing and filtering decisions. + </para> + <para> + Despite the default configuration being extended somewhat from + the original upstream, chances are that you'll need to + manually change the Exim configuration with an editor if you intend to + do something that is not covered by the debconf-driven configuration. + It has never been the packages' intention to offer all possible + configuration methods through debconf. The configuration files are + there to be changed, feel free to do so if you see fit. The Debian + Exim 4 maintainers have tried to make the configuration as flexible as + possible so that manual intervention can be minimized. + </para> + <para> + If you need to make manual changes to the Exim configuration, + please be familiar with how Exim works. At minimum, have read this + README file and the manpages delivered with the Debian Exim 4 + packages, and <filename>/usr/share/doc/exim4-base/spec.txt.gz</filename> + chapters <phrase>"How Exim receives and delivers mail"</phrase> and + <phrase>"The Exim run time configuration file"</phrase>. + <filename>spec.txt.gz</filename> is an excellent reference. + </para> + <para> + Please note that while most free-form fields in the + debconf-driven configuration have the entered string end up + verbatim in Exim's configuration file (and thus using more + advanced features like host, address and domain lists is possible + and will probably work), this is not officially supported. + Only plain lists are supported in the debconf dialogs. You may + use more advanced features, but they may stop working any time + during upgrades. + </para> + <section> <title>The Configuration System</title> + <section id="debconf-questions"> <title>The Debconf questions</title> + <para> + In this section, we try to document and explain the debconf + questions, which are themselves limited to a small screen of + information and might leave questions unanswered. Since you + can usually read this file only after having answered the + questions, the process can always be repeated by invoking + <command>dpkg-reconfigure exim4-config.</command> + <filename>/etc/exim4/update-exim4.conf.conf</filename>, + documented in the <command>update-exim4.conf</command> + manual page, is + a simple shell-script snippet used to store the answers + that you passed to debconf when initially configuring Exim. + You may also modify this file with an editor of your choice. + The package maintainer scripts can handle this and will + preserve your changes. + </para> + <section> <title>General type of mail configuration</title> + <para> + This is the main configuration question which will + control which of the remaining questions are + presented to you. It also controls things like daemon + invocation and delivery of outgoing mail. + </para> + <section> <title> internet site; mail is sent and + received directly using SMTP</title> + <para> + This option is suitable for a standalone system + with full internet connectivity. + </para> + <itemizedlist> + <listitem> + <para> + The Exim SMTP daemon will accept messages + to local domains, and deliver them locally. + </para> + </listitem> + <listitem> + <para> + Outgoing mail will be delivered directly + to the mail exchange servers of the + recipient domain + </para> + </listitem> + </itemizedlist> + </section> + <section> <title> mail sent by smarthost; received via + SMTP or fetchmail</title> + <para> + This option is suitable for a standalone client system + which has restricted internet connectivity, for + example on a residential connection where an SMTP + smarthost is used. Some ISPs block outgoing SMTP + connections to combat the spam problem, thus + requiring the use of their smarthosts. It is + generally a good idea to use the ISPs smart host + if one is connected with a dynamic IP address + since quite a few sites do not accept mail + directly delivered from a dial-in pool. + </para> + <para> + fetchmail can be used to retrieve incoming mail + from the ISP's POP3 or IMAP mail server and + deliver it to Exim via SMTP. + </para> + <itemizedlist> + <listitem> + <para> + The Exim SMTP daemon will accept messages + to local domains, and deliver them locally. + </para> + </listitem> + <listitem> + <para> + Outgoing mail will always be delivered to + the smarthost configured in exim4. + </para> + </listitem> + </itemizedlist> + </section> + <section> <title>mail sent by smarthost; no local mail</title> + <para> + This option is suitable for a client system in a + computer pool which is not responsible for a local + e-mail domain. All locally generated e-mail is + sent to the smarthost without any local domains. + </para> + </section> + <section> <title>local delivery only; not on a network</title> + <para> + This option is suitable for a standalone system + with no networking at all. Only messages for configured + local domains are accepted and delivered locally; + messages for all other domains are rejected: + ``Mailing to remote domains not supported''. + </para> + </section> + <section> <title>no configuration at this time</title> + <para> + This option disables most of Debian's automatisms + and leaves exim in an unconfigured state. + update-exim4.conf will still copy + <filename>/etc/exim4/exim4.conf.template</filename> + or concatenate the files from + <filename>/etc/exim4/conf.d,</filename> and will + not generate any configuration control macros. + Unless you manually edit the configuration source, + this will leave Exim with a syntactically invalid + configuration file, thus in a state where the + daemon won't even start. + </para> + <para> + Only choose this option if you know what you're + doing and are prepared to create your own Exim + configuration. + </para> + <para> + dpkg-conffile handling is still in place, and you + will be offered updates for configuration + snippets, as soon as they become available. + </para> + </section> + </section> + <section> <title>System mail name</title> + <para> + The "mail name" is the domain name used to "qualify" + mail addresses without a domain name. + </para> + <para> + This name will also be used by other programs. It + should be the single, full domain name (FQDN). + </para> + <para> + For example, if a mail address on the local host is + foo@example.org, then the correct value for this + option would be example.org. + </para> + <para> + Exim, as a rule, handles only fully qualified mail + addresses, that is, addresses with a local part, an @ + sign and a domain. If confronted with an unqualified + address, that is, one without @ sign and without + domain, first thing exim does is qualify the address + by adding the @ sign and a domain. + </para> + <para> + This qualification happens for all addresses exim + encounters, be it sender, recipient or else. + </para> + <para> + The domain name used to qualify unqualified mail addresses + is called ``mail name'' on Debian systems and entered + in this debconf dialog. What you enter here will end + up in <filename>/etc/mailname,</filename> which is a + file that might be used by other programs as well. + </para> + <para> + In some configuration types, the package configuration + will offer you, at a later step, to hide this name + from outgoing messages by rewriting the headers. + </para> + </section> + <section> <title>IP addresses to listen on for incoming SMTP + connections</title> + <para> + Please enter a semicolon-separated list of IP addresses. + The Exim SMTP listener daemon will listen on all IP + addresses listed here. + </para> + <para> + An empty value will cause Exim to listen for connections + on all available network interfaces. + </para> + <para> + If this system does only receive e-mail directly from + local services (and not from other hosts), + it is suggested to prohibit external connections to the + local Exim daemon. Such services include e-mail + programs (MUSs) which talk to localhost only as well as + fetchmail. External connections are impossible when + 127.0.0.1 is entered here, as this will disable listening + on public network interfaces. + </para> + <para> + Do not change this unless you know what you are doing. + Altering this value could post a security risk to your + system. For most users, the default value is sufficient. + </para> + </section> + <section> <title>Other destinations for which mail is accepted</title> + <para> + Please enter a semicolon-separated list of recipient + domains for which this machine should consider itself + the final destination. These domains are commonly + called 'local domains'. The local hostname and 'localhost' + are always added to the list given here. + </para> + <para> + By default all local domains will be treated + identically. If both a.example and b.example are + local domains, acc@a.example and acc@b.example will + be delivered to the same final destination. If + different domain names should be treated differently, + it is necessary to edit the config files afterwards. + </para> + <para> + The answer to this question ends up in the list of + domains that Exim will consider local domains. Mail + for recipients in one of these domains will be + subject to local alias expansion and then delivered + locally in the appropriate configuration types. + </para> + </section> + <section> <title>Domains to relay mail for</title> + <para> + Please enter a semicolon-separated list of recipient + domains for which this system will relay mail, for + example as a fallback MX or mail gateway. This means + that this system will accept mail for these domains + from anywhere on the Internet and deliver them + according to local delivery rules. + </para> + <para> + Do not mention local domains here. Wildcards may be used. + </para> + <para> + The answer to this question is a list of the domains + for which Exim will relay messages coming in from anywhere + on the Internet. + </para> + </section> + <section> <title>Machines to relay mail for</title> + <para> + Please enter a semicolon-separated list of IP address + ranges for which this system will unconditionally relay + mail, functioning as a smarthost. + </para> + <para> + You should use the standard address/prefix format + (e.g. 194.222.242.0/24 or 5f03:1200:836f::/48). + </para> + <para> + If this system should not be a smarthost for any + other host, leave this list blank. + </para> + <para> + Please note that systems not listed here can still use + SMTP AUTH to relay through this system. If this system + only has clients on dynamic IP addresses that use SMTP + AUTH, leave this list blank as well. Do + <emphasis>NOT</emphasis> list 0.0.0.0/0! + </para> + <para> + Warning: While it is possible to use + host<emphasis>names</emphasis> instead of IP addresses in this + list extra care needs to be taken in this case. + <emphasis>Unresolvable names in the host list will break + relaying.</emphasis> See + Exim specification chapter <phrase>"Domain, host, address, and + local part lists"</phrase> + and the exim4-config_files man page. + </para> + </section> + <section> <title>IP address or host name of the outgoing + smarthost</title> + <para> + Please enter the IP address or the host name of a mail + server that this system should use as outgoing + smarthost. If the smarthost only accepts your mail on + a port different from TCP/25, append two colons and + the port number (for example smarthost.example::587 or + 192.168.254.254::2525). Colons in IPv6 addresses need + to be doubled. + </para> + <para> + If the smarthost requires authentication, please refer + to <xref linkend="smtp-auth"/> for notes about setting + up SMTP authentication. + </para> + <para> + Multiple smarthost entries are permitted, semicolon + separated. Each of the hosts is tried, in the order + specified (See Exim specification, chapter + <phrase>"The manualroute router"</phrase>, section + <phrase>"How the list of hosts is used"</phrase>.) + </para> + </section> + <section> <title>Hide local mail name in outgoing mail</title> + <para> + The headers of outgoing mail can be rewritten to make + it appear to have been generated on a different + system, replacing the local host name in From, + Reply-To, Sender and Return-Path. + </para> + </section> + <section> <title>Visible domain name for local users</title> + <para> + If you ask Exim to hide the local mail name in + outgoing mail, it will next ask you for the domain + name that should be visible for your local users. + These information is then used to establish the + appropriate rewriting rules. + </para> + </section> + <section> <title>Keep number of DNS queries minimal + (Dial-on-Demand)</title> + <para> + In normal mode of operation Exim does DNS lookups at + startup, and when receiving or delivering messages. + This is for logging purposes and allows keeping down + the number of hard-coded values in the configuration. + </para> + <para> + If this system does not have a DNS full service + resolver available at all times (for example if its + Internet access is a dial-up line using + dial-on-demand), this might have unwanted + consequences. For example, starting up Exim or + running the queue (even with no messages waiting) + might trigger a costly dial-up-event. + </para> + <para> + This option should be selected if this system is + using Dial-on-Demand. If it has always-on Internet + access, this option should be disabled. + </para> + </section> + <section><title>Delivery method for local mail</title> + <para> + Exim is able to store locally delivered mail in + different formats. The most commonly used ones are + mbox and Maildir. mbox uses a single file for the + complete mail folder stored in /var/mail/. With + Maildir format every single message is stored in a + separate file in ~/Maildir/. + </para> + <para> + Please note that most mail tools in Debian expect the + local delivery method to be mbox in their default. + </para> + </section> + <section> <title>Split configuration into small files</title> + <para> + Our packages offer two (actually three, see + <xref linkend="completely-different-configuration"/>) + possibilities: + </para> + <orderedlist> + <listitem> + <simpara> + Generate Exim's configuration from + <filename>/etc/exim4/exim4.conf.template,</filename> + which is basically a normal Exim run-time + configuration file which will be supplemented + with some macros generated from Debconf in a + post-processing step before it is passed to exim. + </simpara> + </listitem> + <listitem> + <simpara> + Generate Exim's configuration from the + multiple files in + <filename>/etc/exim4/conf.d/</filename>. The + directories in + <filename>/etc/exim4/conf.d/</filename> + correspond to the sections of the Exim + run-time configuration file, so you should + easily find your way around there. + </simpara> + </listitem> + </orderedlist> + <para> + Splitting the configuration across multiple files + means that you have the actual configuration file + automatically generated from the files below + <filename>/etc/exim4/conf.d/</filename> by invoking + <command>update-exim4.conf</command>. Each section + of Exim's configuration has its own subdirectory and + the files in there are supposed to be read in + alphanumeric order. + <filename>router/00_exim4-config_header</filename> + is followed by + <filename>router/100_exim4-config_domain_literal</filename>, + ... + </para> + <para> + If you chose unsplit configuration, + <command>update-exim4.conf</command> builds the + configuration from + <filename>/etc/exim4/exim4.conf.template</filename>, + which is basically the files from + <filename>/etc/exim4/conf.d/</filename> concatenated + together at package build time, and thus guarantees + consistency on the target system. + </para> + <para> + In both cases, <command>update-exim4.conf</command> + generates exim configuration macros from the debconf + configuration values and puts them into + the actual configuration file, which is then used by + the Exim daemon. See the + <command>update-exim4.conf</command> manual + page for more in-depth information about this + mechanism. + </para> + <para> + Benefits of the split configuration approach: + <itemizedlist> + <listitem> + <simpara> + it means less work for you when upgrading. + If we shipped one big file and modified + for example the Maildir transport in a new + version you won't have to do manual + conffile merging unless you had changed + exactly <emphasis>this</emphasis> + transport. + </simpara> + </listitem> + <listitem> + <simpara> + It allows other packages (e.g. sa-exim) to + modify Exim's configuration by dropping + files into + <filename>/etc/exim4/conf.d</filename>. + This needs, however quite exact syncing + between the exim4 packages and the other, + cooperating package. + </simpara> + </listitem> + </itemizedlist> + </para> + <para> + Drawbacks of the split configuration approach: + <itemizedlist> + <listitem> + <simpara> + It is more fragile. If files from + different sources (package, manually + changed, or other package) get out of + sync, it is possible for Exim to break + until you manually correct this. This can + for example happen if we decide to add a + new option to the Debian setup of a later + version, and you have already set this + option in a local file. + </simpara> + </listitem> + </itemizedlist> + </para> + <para> + Benefits of the unsplit configuration approach: + <itemizedlist> + <listitem> + <simpara> + People familiar with configuring Exim may + find this approach easier to understand as + <filename>exim4.conf.template</filename> + basically is a complete Exim configuration + file which will only undergo some basic + string replacement before is it passed to + exim. + </simpara> + </listitem> + <listitem> + <simpara> + Split-config's fragility mentioned + above does not occur. + </simpara> + </listitem> + </itemizedlist> + </para> + <para> + Drawbacks of the unsplit configuration approach: + <itemizedlist> + <listitem> + <simpara> + Will require manual intervention in case of an + upgrade. + </simpara> + </listitem> + </itemizedlist> + </para> + <para> + If in doubt go for the unsplit config, because it is + easier to roll back to Debian's default configuration + in one step. If you intend to do many changes to the + Debian setup, you might want to use the split config + at the price of having to more closely examine the + config file after an update. + </para> + <para> + We'd appreciate a patch that uses ucf and the + 3-way-merge mechanism offered by that package. It + might be the best way to handle the big configuration + file. + </para> + <para> + If you are using unsplit configuration, have local + changes to <filename>/etc/exim4/conf.d/</filename> + (either made by yourself or by other packages dropping + their own routers or transports in) and want to + re-generate + <filename>/etc/exim4/exim4.conf.template</filename> to + activate these changes, you can do so by using + <command>update-exim4.conf.template</command>. + </para> + </section> + </section> + <section> <title>Access Control in the default configuration</title> + <para> + The Debian exim 4 packages come with a default configuration + that allows flexible access control and blacklisting of + sites and hosts. The acls involved can be found in + /etc/exim4/conf.d/acl, or in /etc/exim4/exim4.conf.template, + depending on which configuration scheme you use. Most + rejections of messages due to this mechanism happen at RCPT + time. Local configuration of the mechanisms happens through + data files in /etc/exim4 or via Exim macros that you can set + in /etc/exim4/conf.d/main, so there is normally no need to + change the files in the acl subdirectory in a split-config + setup. If you use the non-split config, you need to edit + /etc/exim4/exim4.conf.template, which, as a big + dpkg-conffile, won't give you any advantage of the .ifdef + scheme. + </para> + <para> + The data files are documented in the exim4-config_files man + page. + </para> + <para> + The access lists delivered with the exim4 packages also + contain quite a few configuration options that are too + restrictive to be active by default on a real-life site. + These are masked by .ifdef statements, can be activated by + setting the appropriate macros, and are documented in the + ACL files itself. + </para> + </section> + <section id='macros'> <title>Using Exim Macros to control the + configuration</title> + <para> + Our configuration can be controlled in a limited way by + setting macros. That way, you can switch on and off certain + parts of the default configuration and/or override values set + in Debconf without having to touch the dpkg-conffiles. While + touching dpkg-conffiles itself is explicitly allowed and wanted, + it can be quite a nuisance to be asked on package upgrade + whether one wants to use the locally changed file or the + file changed by the package maintainer. + </para> + <para> + Whenever you see an <command>.ifdef</command> or + <command>.ifndef</command> clause in the configuration file, + you can control the appropriate clause by setting the macro in + a local configuration file. <command>.ifndef</command> checks + whether a specific macro is set (to a nonempty value), the + actual value does not matter. (Both + <quote>EXIM4_EXAMPLE = true</quote> and + <quote>EXIM4_EXAMPLE = false</quote> pass this test.) + For split configuration, you can + drop the local configuration file anywhere in + <filename>/etc/exim4/conf.d/main</filename>. Just make sure it + gets read before the macro is first used. + <filename>000_localmacros</filename> is a possible name, + guaranteeing first order. For a non-split configuration, + <filename>/etc/exim4/exim4.conf.localmacros</filename> gets + read before + <filename>/etc/exim4/exim4.conf.template</filename>. To + actually set the macro <varname>EXIM4_EXAMPLE</varname> to the + value "this is a sample", write the following line + </para> + <para> + EXIM4_EXAMPLE = this is a sample + </para> + <para> + into the appropriate file. For more detailed discussion of the + general macro mechanism, see the Exim specification, chapter + <phrase>"The Exim run time configuration file"</phrase>, for + details how macro expansion works. + </para> + </section> + <section> <title>How does this work?</title> + <para> + The script <command>update-exim4.conf</command> parses the + <filename>/etc/exim4/update-exim4.conf.conf</filename> file + and provides the configuration for the exim daemon. + </para> + <para> + Depending on the value of + <varname>dc_use_split_config</varname>, it either + <itemizedlist> + <listitem> + <simpara> + takes all the files below + <filename>/etc/exim4/conf.d/</filename> and + concatenates them together or + </simpara> + </listitem> + <listitem> + <simpara> + uses <filename>exim4.conf.template</filename> as + input. + </simpara> + </listitem> + </itemizedlist> + The debconf-managed information from + <filename>/etc/exim4/update-exim4.conf.conf</filename> is + merged into the generated configuration file by generating a + number of Exim configuration macros. + </para> + <para> + <varname>DCsmarthost</varname>, for example, is set to the + value of <varname>$dc_smarthost</varname> + in <filename>/etc/exim4/update-exim4.conf.conf</filename> + which holds the answer to "Which machine will act as the + smarthost and handle outgoing mail?" + </para> + <para> + The result of these operations is saved as + <filename>/var/lib/exim4/config.autogenerated</filename>, + which is <emphasis>not</emphasis> a dpkg-conffile! Manual + changes to this file will be overwritten by + <command>update-exim4.conf</command>. + </para> + <para> + Please consult <command>update-exim4.conf</command> manpage + for more detailed information. + </para> + <para> + <command>update-exim4.conf</command> is invoked by the init + script prior to any operation that may invoke an exim process, + and gives an error message if the generated config file is + syntactically invalid. If you want to activate your changes to + files in conf.d/ just execute <command>invoke-rc.d exim4 restart</command>. + </para> + </section> + <section id="howto-change-config"><title>How do I do minor tweaks to the configuration?</title> + <para> + Some times, you want to do minor adjustments to the Exim + configuration to make Exim behave exactly like you want it + to behave. There are the following possibilities to modify + Exim's behavior. + </para> + <section><title>Adjustments supported by the debconf configuration</title> + <para> + If you want to modify parameters that are supported by the + debconf configuration, things are easy. Just invoke + <command>dpkg-reconfigure exim4-config</command> or hand-edit + <filename>/etc/exim4/update-exim4.conf.conf</filename> to your + liking and restart Exim. + </para> + <para> + You can find explanation of the debconf questions in <xref + linkend="debconf-questions"/>. + Additionally, + <filename>/etc/exim4/update-exim4.conf.conf</filename> + is documented in the <command>update-exim4.conf</command> + man page. + </para> + </section> + <section><title>Adjustments controlled by macros in the Debian Exim configuration</title> + <para> + Some aspects of the Debian Exim configuration can be + controlled by Exim macros. To find out about these, you + need basic understanding of Exim configuration. Just look + in our Exim configuration and see which macro needs to be + set to a different value to alter Exim's behavior. + </para> + <para> + <xref linkend="macros"/> gives a closer explanation about + how to do this. + </para> + </section> + <section><title>Making direct changes to the Debian Exim configuration</title> + <para> + You can, of course, make direct change to the + configuration. All configuration files in /etc/exim4 are + dpkg-conffiles, and you can thus edit them any time. Your + changes will be preserved through updates. You need to + know about how to configure Exim to be successful. + </para> + <para> + If you use unsplit configuration, edit + <filename>/etc/exim4/exim4.conf.template</filename>. If you use + split configuration, edit the Exim configuration snippets in + <filename>/etc/exim4/conf.d</filename>. + </para> + <para> + More information about how the Exim configuration is built + can be found in this document and in the + <command>update-exim4.conf</command> manual page. + </para> + </section> + </section> + <section id="completely-different-configuration"> <title>Using a completely different configuration scheme</title> + <para> + If you are an experienced Exim administrator, you might feel + working with our pre-fabricated configuration + cumbersome and complex. You might feel right if you need to + make more complex changes and do not need to receive updates + from us. This section is going to tell about how to use + your own configuration. + </para> + <para> + But, you might profit from keeping the Debian magic. Most + files that come with Debian exim4 are conffiles. Debian is + going to care about your changes and keeps them around. + Additionally, a lot of configuration options can be + overridden with a macro, which does not require you to + actually change our configuration file. A lot of people are + using our configuration scheme, and maybe it is going to + save you a lot of time if you decide to spend some time + familiarizing yourself with our scheme. + </para> + <section> <title>Override exim4-config configuration magic</title> + <para> + If you are only running a small number of systems and + want to completely disable Debian's magic, just take + your monolithic configuration file and install it as + <filename>/etc/exim4/exim4.conf</filename>. Exim will + use that file verbatim. To have something to start, + you can either take + <filename>/etc/exim4/exim4.conf.template</filename>, + run <command>update-exim4.conf --keepcomments --output + /etc/exim4/exim4.conf</command>, or use upstream's + default configuration file that is installed as + <filename>/usr/share/doc/exim4-base/examples/example.conf.gz</filename>. + You are going to lose all magic you get from packaging + though, so you need to be familiar with Exim to build + an actually working config. + </para> + <para> + <filename>/var/lib/exim4/config.autogenerated</filename>, + the file generated by + <command>update-exim4.conf</command>, is ignored as soon + as <filename>/etc/exim4/exim4.conf</filename> is found. + You should not edit + <filename>/etc/exim4/exim4.conf</filename> directly when + Exim is running, because the forked processes Exim starts + for SMTP receiving or queue running would use the new + configuration file, while the original main exim-daemon + would still use the old configuration file. + </para> + <para> + Some third-party HOWTOs that reference Debian and + claim to make things easy suggest dumping a + pre-fabricated, static config file to + <filename>/etc/exim4/exim4.conf</filename>. This is + considered bad advice by the Debian maintainers since + you are going to disable all updates and service magic + that Debian might deliver in the future this way. If + you do not know exactly what you're doing here, this + is a bad choice. We try to comment on external HOWTOs + found on the web in the <ulink + url="http://wiki.debian.org/PkgExim4UserFAQ">Debian + Exim4 User FAQ</ulink> to help you find out which + advice to follow. + </para> + </section> + <section> <title>Replacing exim4-config with your own exim4 configuration package.</title> + <para> + We split off Exim's configuration system (debconf, + <command>update-exim4.conf</command>, and the files in + <filename>/etc/exim4/conf.d)</filename> to a separate + package, exim4-config. If you want to, you can replace + exim4-config by something entirely different. The other + packages don't care. Your package needs to: + <itemizedlist> + <listitem> + <simpara> + Provides: exim4-config-2, Conflicts: + exim4-config-2,exim4-config + </simpara> + </listitem> + <listitem> + <simpara> + drop the Exim 4 configuration either into + <filename>/var/lib/exim4/config.autogenerated</filename> + or into <filename>/etc/exim4/exim4.conf</filename>. + </simpara> + </listitem> + </itemizedlist> + Your package must provide an executable <command>update-exim4.conf</command> + that must be in root's path (<filename>/usr/sbin</filename> recommended). The init + script will invoke that executable prior to invoking the + actual exim daemon. If you do not need that script, have it exit 0. + </para> + <para> + If you want to create your own configuration packages, there is a + number of helpers available. + <itemizedlist> + <listitem> + <simpara> + The Exim 4 Debian svn repository holds sources for a + exim4-config-simple package which contains a simple, not + debconf-driven configuration scheme as an example which can + be used as a template for a classical, exim4.conf based + configuration scheme. + </simpara> + </listitem> + <listitem> + <simpara> + The Exim 4 Debian svn repository holds sources for a + exim4-config-medium package which contains the conf.d + driven configuration of the main package with the + debconf interaction removed. This can be used to create + your own non-debconf configuration package that uses the + conf.d mechanism. + </simpara> + </listitem> + <listitem> + <simpara> + Finally, you can invoke the script + <filename>debian/config-custom/create-custom-config-package</filename> + which will create a new source package + "exim4-config-custom" with the debconf-driven config + scheme of exim4-config for your local modification. + </simpara> + </listitem> + </itemizedlist> + Please note that exim4-config-simple and + exim4-config-medium are only targeted to be used as a + template. The configurations contained are not + suitable for productive use. Of course, the Debian + maintainers appreciate any patches you might find + suitable. The scripts in exim4-config-simple and + exim4-config-medium may not work at all in your + environment. Unfortunately, they have not been + updated in a long time as well. We are willing to + accept patches. + </para> + <para> + See the development web page for links to the subversion + repository. + </para> + <para> + Exchanging the entire exim4-config package with + something custom comes particularly handy for sites + that have more than a few machines that are + similarly configured, but do not want to use the + original exim4-config package. Build your own + exim4-config-custom or exim4-config-foo, and simply + apt that package to the machines that need to have + that configuration. Future updates can then be + handled via the dpkg-conffile mechanism, properly + detecting local modifications. + </para> + <para> + In the future, it might be possible that Debian will + contain multiple flavours of Exim4 configuration. + However, these packages would have to be maintained + by someone else because the exim4 package + maintainers think that the scheme delivered with + exim4-config is the least of all evils and would + rather not spend the time to maintain multiple configuration + schemes while only actually using one. It would be + nice to have a configuration scheme using a + monolithic config file, managed by ucf in + three-way-merge mode. If anybody feels ready to + maintain it, please go ahead. + </para> + </section> + </section> + </section> + <section id="TLS"> <title>Using TLS</title> + <para> + Both exim4-daemon-heavy and exim4-daemon-light support TLS/SSL + using the GnuTLS library. + </para> + <section> <title>Exim 4 as TLS/SSL client</title> + <para> + Exim will use TLS + via STARTTLS <emphasis>automatically</emphasis> as client if + the server Exim connects to offers it. + </para> + <para> + This means that you will not need any special configuration if + you want to use opportunistic TLS for outgoing mail. However, + to enforce TLS and successful certificate verification, a few + things need to be configured. + </para> + <para> + To enforce TLS and prevent fallback to unencrypted + connections, ensure that hosts_require_tls = * is in effect on + the respective transport. For the remote_smtp_smarthost + transport, this setting can be controlled via the + REMOTE_SMTP_SMARTHOST_HOSTS_REQUIRE_TLS macro. + </para> + <para> + The certificate presented by the remote host is checked + against the system CA certificate store + (<filename>/etc/ssl/certs/</filename>) and the verification + result is logged (CV=...). + For the remote_smtp_smarthost transport successful + certificate verification against the system trust store is + enforced by default on encrypted connections. + (<quote>REMOTE_SMTP_SMARTHOST_TLS_VERIFY_HOSTS = *</quote> + is set by default). Set this macro to an empty value to + disable this. To check against a certificate not present in + the system trust store point + REMOTE_SMTP_SMARTHOST_TLS_VERIFY_CERTIFICATES (which sets + tls_verify_certificates) to a file containing this (set of) + trusted certificates. + </para> + <para> + Successful certificate verification is + <emphasis>not enforced</emphasis> + by default for other transports. + </para> + <para> + Another possibility would be to use DANE for certificate + verification. This requires support on the server side and + a resolver with DNSSEC support on the client side. + </para> + <para> + If your + server setup mandates the use of client certificates, you + need to amend your remote_smtp and/or remote_smtp_smarthost + transports with a tls_certificate option. This is not + commonly needed. + </para> + <para id="tls_client_certicate"> + To make exim send a TLS certificate to the remote host set + REMOTE_SMTP_TLS_CERTIFICATE/REMOTE_SMTP_PRIVATEKEY or for + the remote_smtp_smarthost transport + REMOTE_SMTP_SMARTHOST_TLS_CERTIFICATE/REMOTE_SMTP_SMARTHOST_PRIVATEKEY + respectively. + </para> + <para> + To use TLS on connect set <quote>protocol = smtps</quote> on + the respective transport. (For the remote_smtp_smarthost + transport the macro REMOTE_SMTP_SMARTHOST_PROTOCOL can be used. + </para> + </section> + <section> <title>TLS support for Exim as server</title> + <para> + Exim supports incoming opportunistic TLS by using on-connect + autogenerated self-signed certificates. This is not optimal both for + performance reasons and because these certificates cannot be verified + by connecting clients/servers. + <para> + Each time an on-demand cert is created exim will log a info message + in the mainlog that looks like this: + <blockquote> + Warning: No server certificate defined; will use a selfsigned one. + Suggested action: either install a certificate or change + tls_advertise_hosts option + </blockquote> + This informative message can be ignored. + </para> + </para> + <para> + To avoid the (small) performance issue and the log message one can + locally create certificates. The exim-gencert script (which requires + openssl) can be helpful for this purpose. It is shipped in + <filename>/usr/share/doc/exim4-base/examples/</filename> and + takes care of proper access privileges on the private key + file when installing key/certificate in + <filename>/etc/exim4/</filename>. + </para> + <para> + One can also get a certificate from a CA and install the key in + <filename>/etc/exim4/exim.key</filename> and the certificate + in <filename>/etc/exim4/exim.crt</filename>. + </para> + <para> + To enable use of the installed certificates set the macro + MAIN_TLS_ENABLE in a local configuration file as described in + <xref linkend="macros"/>. + </para> + <para> + After this configuration, Exim will advertise STARTTLS when + connected to on the normal SMTP ports. Some broken clients + (most prominent example being nearly all versions of Microsoft + Outlook and Outlook Express, and Incredimail) insist on doing + TLS on connect on Port 465. If you need to support these, set + SMTPLISTENEROPTIONS='-oX 465:25 -oP /run/exim4/exim.pid' + in <filename>/etc/default/exim4</filename> and + "tls_on_connect_ports=465" in the main configuration section. + </para> + <para> + The -oP is needed because Exim does not write an implicit pid + file if -oX is given. Without pid file, init script and cron + job will malfunction. + </para> + <para> + It might be appropriate to add "+tls_cipher" to + any log_selector statement you might already have, or to add a + log_selector statement setting these two options in a local + configuration file. (For Debian's configuration simply define + the MAIN_LOG_SELECTOR macro.) + This option makes Exim log what cipher + your Exim and the peer's mailer have negotiated to use to + encrypt the transaction. + </para> + <para> + Exim can be configured to ask a client for a certificate and to + try to verify it. Debian's exim configuration used to enable + this by default, but stopped doing so since it caused TLS errors + with a couple of popular clients (Outlook, Incredimail, etc.). + To enable this again set the macro MAIN_TLS_TRY_VERIFY_HOSTS to + the lists hosts whose certificates you want to check. (Use * to + try checking all hosts. The value of the macro is used to + populate exim's main option tls_try_verify_hosts.) You should + also point MAIN_TLS_VERIFY_CERTIFICATES to a file containing the + accepted certificates, since its default setting + (/etc/ssl/certs/ca-certificates.crt) can contain a large list of + certificates which causes the interoperabilty problems with + Outlook et.al. noted above. + </para> + <para> + The server certificate is only used for incoming connections, + please consult <xref linkend="tls_client_certicate"/> for the + corresponding outgoing conncection options. + </para> + </section> + <section> <title>Troubleshooting</title> + <para> + If Exim complains in an SMTP session that TLS is unavailable, + the Exim mainlog or paniclog frequently has exact information + about what might be wrong. Fo example, you might see + </para> + <para> + 2003-01-27 19:06:45 TLS error on connection from localhost [127.0.0.1] + (cert/key setup): Error while reading file) + </para> + <para> + showing that there has been an error while accessing the + certificate or the private key file. + </para> + <para> + Insuffient entropy available is a frequent cause of TLS + failures in Exim context. If Exim logs "not enough random bytes + available", or simply hangs silently when an encrypted + connection should be established, then Exim was + unable to read enough random data from + <filename>/dev/random</filename> to do whatever cryptographic + operation is requested. Please check that your + <filename>/dev/random</filename> device is setup properly. + </para> + <para> + You might also find "TLS error on connection to [...] + (gnutls_handshake): The Diffie-Hellman prime sent by the server is + not acceptable (not long enough)." given as reason. Exim by default + requires a DH prime length of 1024 bits. This requirement can be + downgraded by setting the tls_dh_min_bits option on the SMTP + transport. The setting is accessible in the Debian configuration by + setting the macro TLS_DH_MIN_BITS. (e.g. "TLS_DH_MIN_BITS = 768"). + </para> + </section> + </section> + <section id="smtp-auth"> <title>SMTP-AUTH</title> + <para> + Exim can do SMTP AUTH both as a client and as a server. + </para> + <para> + AUTH PLAIN and AUTH LOGIN are disabled for connections which are + not protected by SSL/TLS per default. These authentication + methods use cleartext passwords, and allowing the + transmission of cleartext passwords on unencrypted connections + is a security risk. Therefore, the default configuration configures + Exim not to use and/or allow AUTH PLAIN and AUTH LOGIN over + unencrypted connections. + </para> + <para> + It is thus recommended to set up Exim to use TLS to encrypt + the connections. Please refer to <xref linkend="TLS"/> for + documentation about this. Note that most Microsoft clients + need special handling for TLS. + </para> + <section> <title>Using Exim as SMTP-AUTH client</title> + <para> + If you want to set up Exim as SMTP AUTH client for delivery + to your internet access provider's smarthost put the name of + the server, your login and password in + <filename>/etc/exim4/passwd.client</filename>. See the man + page for exim4-config_files(5) for more information about the + required format. + </para> + <para> + If you need to enable AUTH PLAIN or AUTH LOGIN for unencrypted + connections because your service provider does support neither + TLS encryption nor the CRAM MD5 authentication method, you can + do so by setting the AUTH_CLIENT_ALLOW_NOTLS_PASSWORDS macro. + Please refer to <xref linkend="macros"/> for an explanation of + how best to do this. + </para> + <para> + <filename>/etc/exim4/passwd.client</filename> needs to be + readable for the exim user (user Debian-exim, group + Debian-exim). It is suggested that you keep the default + permissions root:Debian-exim 0640. + </para> + </section> + <section> <title>Using Exim as SMTP-AUTH server</title> + <para> + The configuration files include many, verbosely commented, + examples for server-side smtp-authentication which just need + to be uncommented. + </para> + <para> + If you need to enable AUTH PLAIN or AUTH LOGIN for unencrypted + connections because your clients neither support TLS encryption + nor the CRAM MD5 authentication method, you can do so by setting + the AUTH_SERVER_ALLOW_NOTLS_PASSWORDS macro. Please refer to + <xref linkend="macros"/> for an explanation of how best to + do this. + </para> + <para> + If you want to authenticate against system passwords (e.g. + <filename>/etc/shadow</filename>) the easiest way is to use + saslauthd in the Debian package sasl2-bin. You have to add the + exim-user (currently Debian-exim) to the sasl group, to give + exim permission to use the saslauthd service. + </para> + <para> + The Debian exim4 maintainers consider using system login + passwords a bad idea for the following reasons: + <itemizedlist> + <listitem> + <simpara> + A compromised password will give access to a system account. + </simpara> + </listitem> + <listitem> + <simpara> + E-Mail passwords could accidentally be transmitted unencrypted. + </simpara> + </listitem> + <listitem> + <simpara> + E-Mail passwords are likely to be stored with the + client software, which greatly increases the chance of a + compromise. + </simpara> + </listitem> + </itemizedlist> + </para> + </section> + </section> + + <section> <title>How the Exim daemon is started</title> + <para> + The Debian Exim 4 packages' init script is located in + <filename>/etc/init.d/exim4</filename>. Apart from the + functions that are required by Debian policy and the LSB, it + supports the commands <command>what</command>, which executes + <command>exiwhat</command> to show what your Exim processes + are doing, and <command>force_stop</command> which + unconditionally kills all Exim processes. + </para> + <para> + The init script can be configured to start listening and/or + queue running daemons. This configuration can be found in + <filename>/etc/default/exim4</filename>. This file is + extensively documented. + </para> + </section> + + <section> <title>Miscellaneous packaging issues</title> + <section> <title>The daily cron job</title> + <para> + Exim4's daily cron job + (<filename>/etc/cron.daily/exim4-base</filename>) + does basic housekeeping tasks: + <itemizedlist> + <listitem> + <simpara> + It reads <filename>/etc/default/exim4</filename>, so you + can use this file to change any of the variables used in + the cron job. + </simpara> + </listitem> + <listitem> + <simpara> + It is a no-op if no Exim4 binary is found. + </simpara> + </listitem> + <listitem> + <simpara> + If <command>$E4BCD_DAILY_REPORT_TO</command> is set + to a non-empty string, the output of eximstats is + mailed to the address given in that variable. The + default is empty, so no reports are sent. Options + for eximstats can be given in + <command>$E4BCD_DAILY_REPORT_OPTIONS</command>. + </simpara> + </listitem> + <listitem> + <simpara> + A non-empty paniclog is a nearly sure sign of bad + things going on. Thus, the cron job will send out + warning messages to the syslog and root if it finds + the panic log non-empty. + Please note that the paniclog is not rotated daily, + so existing issues will be reported daily until + either the paniclog is rotated due to its sheer + size, or you manually move it away, for example by + calling <command>logrotate -f + /etc/logrotate.d/exim4-paniclog</command> from a shell. + </simpara> + <simpara> + Just in case your system logs transient error + situations to the panic log as well (see, for + example, + <ulink url="http://www.exim.org/bugzilla/show_bug.cgi?id=92">Exim Bug 92</ulink>), + you can configure + <command>$E4BCD_PANICLOG_NOISE</command> to a + regular expression. If the paniclog contains only + lines that match that regular expression, no warning + messages are generated. + </simpara> + <simpara> + If you want to disable paniclog monitoring + completely, set <command>$E4BCD_WATCH_PANICLOG</command> + to no. <command>E4BCD_WATCH_PANICLOG=once</command> will + rotate a non-empty paniclog automatically after sending out + the warning e-mail. + </simpara> + <simpara> + The <command>E4BCD_PANICLOG_LINES</command> setting can be + used to limit the number of lines of paniclog quoted in + warning email. It is set to 10 by default. + </simpara> + </listitem> + <listitem> + <simpara> + It tidies up the retry and hints databases. + </simpara> + </listitem> + </itemizedlist> + </para> + </section> + </section> + + <section> <title>Using Exim with inetd/xinetd</title> + <para> + Exim4 is run as a separate daemon instead of inetd/xinetd for + two reasons: + <variablelist> + <varlistentry> + <term>Ease of maintenance:</term> + <listitem> + <simpara> + update-inetd is difficult to impossible to handle + correctly (Just check the archived bug reports of Exim.) + and update-inetd seems to be unmaintained for a long + time, nobody dares to touch it. To quote Mark Baker, the + maintainer of Exim (v3): "I really wish I had never used + inetd in the first place, but simply set up exim to run + as a daemon, but it's too late to change that now." + </simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Extended features</term> + <listitem> + <simpara> + Running from <command>inetd</command> interferes with + Exim's resource controls (e.g it disables + smtp_accept_max_per_host and smtp_accept_max). + </simpara> + </listitem> + </varlistentry> + </variablelist> + </para> + <para> + If you introduce bugs on your systems by running from (x)inetd + you are on your own! If you want to run exim from + <command>xinetd</command>, follow these steps: + <orderedlist> + <listitem> + <simpara> + Disable Exim 4's listening daemon by executing + <command>update-exim4defaults --queuerunner + queueonly</command> + </simpara> + </listitem> + <listitem> + <para> + Create <filename>/etc/xinetd.d/exim4</filename> + <programlisting> +service smtp +{ + disable = no + flags = NAMEINARGS + socket_type = stream + protocol = tcp + wait = no + user = Debian-exim + group = Debian-exim + server = /usr/sbin/exim4 + server_args = exim4 -bs +} + </programlisting> + </para> + </listitem> + <listitem> + <simpara>Run <command>invoke-rc.d exim4 restart; invoke-rc.d +(x)inetd restart</command></simpara> + </listitem> + </orderedlist> + </para> + <para>If you want to use plain inetd, insert following line into + <filename>/etc/inetd.conf</filename>:<programlisting> +smtp stream tcp nowait Debian-exim /usr/sbin/exim4 exim4 -bs + </programlisting> + </para> + </section> + + <section> <title>Handling incoming mail for local accounts with low UID</title> + <para> + Since system accounts (mail, uucp, lp etc) are usually aliased + to root, and root's mailbox is usually read by a human, these + account names have started to be a common target for spammers. + The Debian Exim 4 packages have a mechanism to deal with this + situation. However, since this derives rather far from normal + behavior, it is disabled by default. + </para> + <para> + To enable it, set the macro FIRST_USER_ACCOUNT_UID to a numeric, + non-zero value. Incoming mail for local users that have a UID + lower than FIRST_USER_ACCOUNT_UID is rejected with the message "no + mail to system accounts". Incoming mail for local users that + have a UID greater or equal FIRST_USER_ACCOUNT_UID are processed as + usual. Therefore, the default value of 0 ensures that the + mechanism is disabled. On Debian systems, setting + FIRST_USER_ACCOUNT_UID to 500 or 1000 (depending on your local policy) + will disable incoming mail for system accounts. + </para> + <para> + Just in case that you need exceptions to the rule, + <filename>/etc/exim4/lowuid-aliases</filename> is an alias + file that is only honored for local accounts with UID lower + than FIRST_USER_ACCOUNT_UID. If you define an alias for such an + account here, incoming mail is processed according to the + alias. If you alias the account to itself, messages are + delivered to the account itself, which is an exception to the + rule that messages for low-UID accounts are rejected. The + format of <filename>/etc/exim4/lowuid-aliases</filename> is + just another alias file. + </para> + </section> + <section> <title>How to bypass local routing specialities</title> + <para> + Sometimes, it might be desirable to be able to bypass local + routing specialities like the alias file or a user-forward + file. This is possible in the Debian Exim4 packages by + prefixing the account name with "real-". For a local account + name "foo", "real-foo@hostname.example" will result in direct + delivery to foo's local Mailbox. + </para> + <para> + This feature is by default only available for locally + generated messages. If you want it to be accessible for + messages delivered from remote as well, set the Exim macro + COND_LOCAL_SUBMITTER to true. If you do not want this at all, + set the macro to false. Please note that the userforward + router uses this feature to get error messages delivered, i.e. + notifying the user of a syntax error in her + <filename>.forward</filename> file. + </para> + </section> + <section> <title>Using more complex deliveries from alias files</title> + <para> + Delivery to arbitrary files, directory or to pipes in the + <filename>/etc/aliases</filename> file is disabled by default + in the Debian Exim 4 packages. The delivery process including the + program being piped to would run as the exim admin-user + Debian-exim, which might open up security holes. + </para> + <para> + Invoking pipes from <filename>/etc/aliases</filename> file is + widely considered obsolete and deprecated. The Debian Exim + package maintainers would like to suggest using a dedicated + router/transport pair to invoke local processes for mail + processing. For example, the Debian mailman package contains a + <filename>/usr/share/doc/mailman/README.Exim4.Debian</filename> file + that gives a good example how to implement this. Using a + dedicated router/transport pair have the following advantages: + <itemizedlist> + <listitem> + <para> + The router/transport pair can be put in place by another + package, giving a well-defined transaction point between + Exim 4 and $PACKAGE. + </para> + </listitem> + <listitem> + <para> + Not allowing pipe deliveries from alias files makes it + harder to accidentally run programs with wrong + privileges. + </para> + </listitem> + <listitem> + <para> + It is possible to run different pipe processes under + different accounts. + </para> + </listitem> + <listitem> + <para> + Even if only invoking a single local program, it is easier + to do with your dedicated router/transport since you won't + need to change this file, making automatic updates of this + file possible for future versions of the Exim 4 packages. If + you do local changes here, dpkg conffile handling will + bother you on future updates. + </para> + </listitem> + </itemizedlist> + If you insist on using <filename>/etc/aliases</filename> in + the traditional way, you will need to activate the + respective functions by setting the transport options on the + system_aliases router appropriately. Macros are defined to make + this easier. See + +<filename>/etc/exim4/conf.d/router/400_exim4-config_system_aliases</filename> + for information about which macros are available. You might + find the address_file, address_pipe and/or address_directory + transports that are used for the userforward router helpful in + writing your own transports for use in the system_aliases router. + </para> + <para> + If any of your aliases expand to pipes or files or directories + you should set up a user and a group for these deliveries to run + under. You can do this by setting the "user" and - if necessary + - a "group" option and adding a "group" option if necessary. + Alternatively, you can specify "user" and/or "group" on the + transports that are used. + </para> + </section> + + <section> <title>Putting Exim 4 and UUCP together</title> + <para> + UUCP is a traditional way to execute remote jobs (e.g. spool + mails), and as a lot of old things there are much more than one + way to do it. However, today, the ways to handle it have boiled + down to more or less two different ways. + </para> + <para> + Our recommendation is to use bsmtp/rsmtp wherever possible, + because it supports all kinds of mail addresses (also the empty + ones in bounces), and is also better from the security point of + view. + </para> + <section> <title>Sending mail via UUCP</title> + <section> <title>rmail with full addresses</title> + <para> + rmail is the oldest way to transfer mail to a remote system. + However, today it is normally required to use addresses with + full domains for that (Well, they look like any normal address + for you, and we do not tell about the other way to not confuse + you ;). If you want this, you can use this transport: + </para> + <programlisting> +rmail: + debug_print = "T: rmail for $pipe_addresses" + driver=pipe + command = uux - -r -a$sender_address -gC $domain_data!rmail $pipe_addresses + return_fail_output + user=uucp + batch_max = 20 + </programlisting> + <para> + However, all recipients are handled via the command line, so + you are discouraged to use it. + </para> + </section> + <section> <title>bsmtp/rsmtp</title> + <para> + This is a more efficient way to transfer mails. It works + like sending SMTP via a pipe, but instead of waiting for an + answer, the SMTP is just batched; from this is also the name + batched SMTP or short bsmtp. + </para> + <para> + Furthermore, this way won't fail on addresses like " + "@do.main. If you want this, please use this, if the remote + site uses rsmtp (e.g. is Exim 4): + </para> + <programlisting> +rsmtp: + debug_print = "T: rsmtp for $pipe_addresses" + driver=pipe + command = /usr/bin/uux - -r -a$sender_address -gC $domain_data!rsmtp + use_bsmtp + return_fail_output + user=uucp + batch_max = 100 + </programlisting> + <para> + and this if it wants bsmtp as the command: + </para> + <programlisting> +bsmtp: + debug_print = "T: bsmtp for $pipe_addresses" + driver=pipe + command = /usr/bin/uux - -r -a$sender_address -gC $domain_data!bsmtp + use_bsmtp + return_fail_output + user=uucp + batch_max = 100 + </programlisting> + <para> + Of course, these examples can be extended for e.g. + compression (but you can also use ssh for compression, if + you want). + </para> + </section> + <section> <title>The router</title> + <para> + You need a router to tell Exim 4 which mails to forward to + UUCP. You can use this one; please adopt the last line. Of + course, it is also possible to send mail via more than one way. + </para> + <programlisting> +uucp_router: + debug_print = "R: uucp_router for $local_part@$domain" + driver=accept + require_files = +/usr/bin/uux + domains = wildlsearch;/etc/exim4/uucp + transport = rsmtp + </programlisting> + <para> + The file <filename>/etc/exim4/uucp</filename> looks like: + </para> + <programlisting> +*.do.main uucp.name.of.remote.side + </programlisting> + </section> + <section> <title>Speaking UUCP with the smarthost</title> + <para> + If you have a leaf system (i.e. all your mail not for your + local system goes to a single remote system), you can just + forward all non-local mail to the remote UUCP system. In + this case, you can replace "domains = ..." with "domains = ! + +local_domains", but then you need also to replace + $domain_data in the transport by the UUCP-name of your + smarthost. The file <filename>/etc/exim4/uucp</filename> is + not needed in this case. + </para> + </section> + </section> + <section> <title>Receiving mail via UUCP</title> + <section> <title>Allow UUCP to use any envelope address</title> + <para> + Depending how much you trust your local users, you might use + trusted_users and add uucp to it or use + local_sender_retain=true and local_from_check=false. + </para> + </section> + <section> <title>If you get batched smtp</title> + <para> + Allow uucp to execute rsmtp via + <programlisting> +commands rmail rnews rsmtp + </programlisting> + in your <filename>/etc/uucp/sys</filename>, and ask the + sending site to use rsmtp (and not bsmtp) as the batched + command. + </para> + </section> + </section> + </section> + <section> <title>Notes on running SpamAssassin at SMTP time</title> + <para> + Exim can run + <ulink url="https://spamassassin.apache.org/"> + SpamAssassin</ulink> while receiving a message by SMTP which + allows one to avoid acceptance of spam messages. The Debian + configuration contains some example code for running SpamAssassin, + but like all filtering this needs to be handled carefully. + </para> + <para> + SpamAssassin's default report should not be used in a add_header + statement since it contains empty lines. (This triggers e.g. + Amavis' warning "BAD HEADER SECTION, Improper folded header field + made up entirely of whitespace".) This is a safe, terse alternative: + <programlisting> + clear_report_template + report (_SCORE_ / _REQD_ requ) _TESTSSCORES(,)_ autolearn=_AUTOLEARN_ + </programlisting> + </para> + <para> + Rejecting spam messages: Do not reject spam-messages received on + (non-spam) mailing lists, this can/will cause auto-unsubscription. + This also applies to messages received via forwarding services + (e.g. @debian.org addresses). If theses messages are rejected the + forwarding services will need to send a bounce address to the + spammer and will probably disable the forwarding if it happens all + the time. You will need to have some kind of whitelist to exclude + these hosts. + </para> + <para> + Security considerations: By default <command>spamd</command> + runs as root and changes uid/gid to the requested user to run + SpamAssassin. The example uses SpamAssassin default non-privileged + user (nobody) which prevents use of Bayesian filtering since this + requires persistent storage. You might want to setup a dedicated + user for exim spam scanning and use that one, either for a separate + SpamAssassin user profile or to run SpamAssassin as non-privileged + user. + </para> + </section> + </section> + + <section> <title>Updating from Exim 3</title> + <para> + If you use <command>exim4-config</command> from Debian, you will + get the debconf based configuration scheme that is intended to + cover the majority of cases. + </para> + <para> + If <command>exim4-config</command> is installed while an Exim 3 + package is present on the system, + <command>exim4-config</command> tries to parse the Exim 3 config + file to determine the answers that were given to + <command>eximconfig</command> on Exim 3 installation. These + answers are then taken as default values for the debconf based + configuration process. Be warned! <command>eximconfig</command> + from the Exim 3 packages does not record the explicit answers + given on Exim 3 configuration. So we have to guess the answers + from the Exim 3 configuration file + <filename>/etc/exim/exim.conf</filename>, which is bound to fail + if the config file has been modified after using + <command>eximconfig</command>. + </para> + <para> + This is the reason why we refrained from doing a "silent update", but + only use the guessed answers to get reasonable defaults for our + debconf based configuration process. + </para> + <para> + Please note that we do not use the + <command>exim_convert4r4</command> script, but try to configure + the Exim 4 package in the same way Exim 3 was. This will + hopefully aid future updates. + </para> + <para> + If you have used a customized Exim 3 configuration, you can of + course use <command>exim_convert4r4</command>, and install the + resulting file as <filename>/etc/exim4/exim4.conf</filename> + after careful inspection. Exim 4 will then use that file and + ignore the file that it generated from the debconf + configuration. To aid future updates, we do, however, encourage + you not to use the + <filename>exim_convert4r4-generated</filename> file verbatim but + instead drop appropriate configuration snippets in their + appropriate place in <filename>/etc/exim4/conf.d</filename>. + </para> + </section> + <section> <title>Misc Notes</title> + <section> <title>PAM</title> + <para> + On Debian systems the PAM modules run as the same user + as the calling program, so they cannot do anything you + could not do yourself, and in particular cannot access + <filename>/etc/shadow</filename> unless the user is in group + shadow. - If you want to use + <filename>/etc/shadow</filename> for Exim's SMTP AUTH you + will need to run exim as group shadow. Only + exim4-daemon-heavy is linked against libpam. We suggest using + saslauthd instead. + </para> + </section> + <section> <title>Account name restrictions</title> + <para> + In the default configuration, Exim cannot locally deliver + mail to accounts which have capitals in their name. This is + caused by the fact that Exim converts the local part of incoming + mail to lower case before the comparison done by the + check_local_user directive in routers is done. + </para> + <para> + The router option caseful_local_part can be used to control + this, and we decided not to set this option in the Debian + configuration since it would be a rather big change to Exim's + default behavior. + </para> + </section> + <section> <title>No deliveries to root!</title> + <para> + No Exim 4 version released with any Debian OS can run + deliveries as root. If you don't redirect mail for root via + <filename>/etc/aliases</filename> to a nonprivileged + account, the mail will be delivered to + <filename>/var/mail/mail</filename> with permissions 0600 and + owner mail:mail. + </para> + <para> + This redirection is done by the mail4root router which + is last in the list and will thus catch mail for root that has not + been taken care of earlier. + </para> + </section> + <section> <title>Debugging maintainer and init scripts</title> + <para> + Most of the scripts that come with this Debian package do a + <command>set -x</command> if invoked with the environment + variable EX4DEBUG defined and non-zero. This is particularly + handy if you need to debug the maintainer scripts that are + invoked during package installation. Since dpkg redirects + stdout of maintainer scripts, calling dpkg with EX4DEBUG + set might yield interesting results. If in doubt, invoke + the maintainer scripts with EX4DEBUG set manually directly + from the command line. + </para> + </section> + <section> <title>SELinux</title> + <para> + There is no SELinux policy for Exim4 available so far. + Until this is resolved, users should use postfix or + sendmail if they intend to run SELinux. + </para> + <para> + The Debian Exim4 maintainers would appreciate if + somebody could write an SELinux policy. We will gladly + use them in the Debian packages as long as there is + somebody available to test, debug and support. + </para> + </section> + <section> <title>misc</title> + <itemizedlist> + <listitem> + <simpara> + <command>convert4r4</command> is installed as + <filename>/usr/sbin/exim_convert4r4.</filename> + </simpara> + </listitem> + <listitem> + <simpara> + The charset for $header_foo expansions defaults to + UTF-8 instead of ISO-8859-1. + </simpara> + </listitem> + <listitem> + <simpara> + <ulink url="http://marc.merlins.org/linux/exim/"> + Marc Merlin's Exim 4 Page</ulink> has a lot of ACL + examples. + </simpara> + </listitem> + <listitem> + <simpara> + For an example of Exim usage in a + <emphasis>large</emphasis> installation, see + Tony Finch's + <ulink +url="http://www-uxsup.csx.cam.ac.uk/~fanf2/hermes/doc/talks/2005-02-eximconf/"> +paper</ulink> + about the Exim installation at University of Cambridge: + </simpara> + </listitem> + </itemizedlist> + </section> + </section> + <section> <title>Debian modifications to the Exim source</title> + <itemizedlist> + <listitem> + <simpara> + Install the exim binary as /usr/sbin/exim4 instead of + /usr/sbin/exim-<version> with a symlink /usr/sbin/exim. Also + adapt the documentation. + </simpara> + </listitem> + <listitem> + <simpara> + Make the build reproducible. Pull date/time from debian/changelog + and use it as build time instead of using __DATE__. + </simpara> + </listitem> + <listitem> + <simpara> + Documentation updates + </simpara> + <itemizedlist> + <listitem> + <simpara> + Mention how to install the Debian packaged perl-modules needed + for eximstats' graphs. + </simpara> + </listitem> + <listitem> + <simpara> + Add a warning about convert4r4. + </simpara> + </listitem> + <listitem> + <simpara> + Point to the <ulink + url="mailto:pkg-exim4-users@lists.alioth.debian.org"> + Debian-specific mailing list</ulink> instead of + the <ulink url="mailto:exim-users@exim.org">official + exim-users list</ulink>. + </simpara> + </listitem> + </itemizedlist> + </listitem> + <listitem> + <simpara> + <ulink + url="http://marc.merlins.org/linux/exim/files/sa-exim-current/">localscan_dlopen.patch</ulink>: + This patch makes it possible to use and switch between + different local_scan + functions without recompiling Exim. Use + local_scan_path = /path/to/sharedobject to utilize + local_scan() in <filename>/path/to/sharedobject</filename>. + </simpara> + </listitem> + </itemizedlist> + </section> + + <section> <title>Credits</title> + <para><variablelist> + <varlistentry> + <term><ulink url="mailto:aba@not.so.argh.org">Andreas + Barth</ulink></term> + <listitem> + <simpara>UUCP documentation</simpara> + </listitem> + </varlistentry> + <varlistentry> + <term>Dan Weber, Ryen Underwood</term> + <listitem> + <simpara>inetd/xinetd documentation</simpara> + </listitem> + </varlistentry> + </variablelist> + </para> + </section> + +</article> |