Import Debian changes 4.89-2+deb9u4

[hcoop/debian/exim4.git] / debian / README.Debian.xml

<?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 &lt;filename&gt; should
              lead you to the page.
            </simpara>
          </listitem>
          <listitem>
            <simpara>
              The Debian Exim 4 packages have their own
              <ulink url="http://pkg-exim4.alioth.debian.org">
                Home Page
              </ulink> which also links to a User FAQ.
            </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>
      <para>
        The <ulink url="http://pkg-exim4.alioth.debian.org"
          type="http">development web page</ulink> contains a lot of
        useful links and other information. The subversion repository
        of the Debian package is available for public read-only access
        and is linked from the development web page.
      </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. 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>
      <section> <title>Exim 4 as TLS/SSL client</title>
        <para>
          Both exim4-daemon-heavy and exim4-daemon-light support TLS/SSL
          using the GnuTLS library and STARTTLS. 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 TLS for outgoing mail. However, 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>
          The certificate
          presented by the remote host is not checked unless you
          specify a tls_verify_certificate option on the transport.
        </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>
           TLS on connect is not natively supported.
        </para>
      </section>
      <section> <title>Enabling TLS support for Exim as server</title>
        <para>
          You should have created certificates in
          <filename>/etc/exim4/</filename> either by hand or by usage of
          the exim-gencert (which requires openssl). exim-gencert is
          shipped in
          <filename>/usr/share/doc/exim4-base/examples/</filename> and
          takes care of proper access privileges on the private key
          file.
        </para>
        <para>
          Now, enable TLS by setting 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>

  <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-&lt;version&gt; 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>