path: root/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>Getting Support</title>
      <para>
	For your questions and comments, there is a <ulink
	  url="mailto:pkg-exim4-users@lists.alioth.debian.org">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>.
      </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 meta-package <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, 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>
	  FIXME
	</para>
      </section>
    </section>
  </section>

  <section>
    <title>Configuration of Exim 4 in the Debian packages</title>
    <section>
      <title>The Configuration System</title>
      <para>
	Our packages offer two (actually three, see below at
	<filename>/etc/exim4/exim4.conf</filename>) possibilities:
      </para>
      <orderedlist>
	<listitem>
	  <simpara>
	    Generate exim's configuration from
	    <filename>/etc/exim4/exim4.conf.template</filename>
	  </simpara>
	</listitem>
	<listitem>
	  <simpara>
	    Generate exim's configuration from the multiple files in
	    <filename>/etc/exim4/conf.d/</filename>.
	  </simpara>
	</listitem>
      </orderedlist>
      <para>
	You can choose between the alternatives with dpkg-reconfigure
	exim4-config or by changing the value of
	<varname>dc_use_split_config</varname> in
	<filename>update-exim4.conf.conf</filename> manually.
      </para>
      <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>,
	... Please consult the manual page update-exim4.conf(8) for
	more details.
      </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> does
	integrate the debconf configuration values into the actual
	configuration file which is then used by the exim4 daemon. See
	the update-exim4.conf 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>.
	    </simpara>
	  </listitem>
	</itemizedlist>
      </para>
      <para>
	Benefits of the unsplit configuration approach:
	<itemizedlist>
	  <listitem>
	    <simpara>
	      It is less fragile. If we add optionfoo=bar to the Debian
	      setup of a later version, and you have already set this
	      option in a local file, exim will break with the new
	      version until you manually correct this.
	    </simpara>
	  </listitem>
	  <listitem>
	    <simpara>
	      People familiar with configuring exim may find this
	      approach easier to understand as exim4.conf.template
	      basically is a complete exim configuration file which will
	      only undergo some basic string replacement before is it
	      passed to exim.
	    </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>
	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>
      <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 without having to touch the
	dpkg-conffiles. While touching dpkg-conffiles itself is
	explitly 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
	6.4, for details how macro expansion works.
      </para>
      <section>
	<title>What about debconf?</title>
	<para>
	  Debconf just "manages" the file
	  <filename>/etc/exim4/update-exim4.conf.conf</filename>. This
	  is a simple shell-script snippet used to store the answers
	  that you passed to debconf when initially configuring exim4. 
	  You may also modify this file with an editor of your choice,
	  debconf can handle it and will preserve your changes.
	</para>
      </section>
      <section>
	<title>
	  How does this work?
	</title>
	<para>
	  The script <command>update-exim4.conf</command> parses teh 
	  <filename>/etc/exim4/update-exim4.conf.conf</filename> file
	  and provides the configuration for the exim4 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. Strings like
	  <varname>DEBCONFfooDEBCONF</varname> are replaced by the value
	  that is set in
	  <filename>/etc/exim4/update-exim4.conf.conf</filename> for the
	  keyword <varname>dc_foo</varname>.
	</para>
	<para>
	  <varname>DEBCONFsmarthostDEBCONF</varname>, for example, is
	  replaced with 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 "invoke-rc.d exim4 restart".
	</para>
      </section>
      <section>
	<title>Using a completely different configuration scheme</title>
	<para>
	  We have split off exim's configuration system (debconf,
	  update-exim4.conf, 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 might provide an executable update-exim4.conf
	  that must be in root's path (/usr/sbin recommended). The init
	  script will invoke that executable prior to invoking the
	  actual exim daemon.
	</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 example which can
		be used as 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
		you own non-debconf configuration package that uses the
		conf.d mechanism.
	      </simpara>
	    </listitem>
	    <listitem>
	      <simpara>
		Finally, you can invoke the script
		"debian/config-custom/create-custom-config-package"
		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 targetet to be used as 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.
	</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 doesn't 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 best of all worlds and wouldn't 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>
      <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 exim will use TLS
	  <emphasis>automatically</emphasis> as client if the server
	  exim connects to offers it. You can stop reading now if you
	  are not setting up a mailserver which needs to offer TLS for
	  incoming connections.
	</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 (documented below).
	</para>
	<para>
	  It might be appropriate to add "+tls_cipher +tls_peerdn" 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. These options have exim log what cipher
	  your exim and the peer's mailer have negotiated to use to
	  encrypt the transaction, and they have exim log the
	  Distinguished Name of the peer's certificate.
	</para>
      </section>
      <section>
	<title>Diffie-Hellman parameters</title>
	<para>
	  This version of Exim is compiled against GnuTLS. GnuTLS is a
	  replacement for the restrictive licensed OpenSSL libraries. 
	  GnuTLS does not support varying its Diffie-Hellman parameters. 
	  Therefore tls_dhparam settings are ignored in Exim's
	  configuration file, and no dhparam file is generated by
	  exim-gencerts. GnuTLS uses RSA and D-H parameters that are
	  computed when they are needed. When someone sends STARTTLS,
	  exim will compute these parameters and then store these
	  parameters in a cache file located in Exim's spool directory
	  (<filename>/var/spool/exim4/gnutls-params</filename>).
	</para>
	<para>
	  The daily cron job removes this file, so Exim creates a new
	  set of gnutls parameters. It is "more secure" when you have
	  this file regenerated more often. You can delete it any time
	  you wish without any need for synchronization. Exim will
	  regenerate it automatically. But remember that the exim
	  process that has to create the file could take a little longer
	  before it responds to a STARTTLS command. You should not
	  notice this on current computers.
	</para>
	<para>
	  NOTE! The fact that GnuTLS does not support generated
	  Diffie-Hellman parameters does NOT make it less secure.
	</para>
	<para>
	  For more reference, you can refer to
	  <filename>/usr/share/doc/exim4-base/spec.txt.gz</filename>,
	  section 38.
	</para>
      </section>
      <section>
	<title>Troubleshooting</title>
	<para>
	  If Exim complains in an SMTP session that TLS s unavailable,
	  the exim manlog 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>
	  If Exim says "not random bytes available", then Exim was
	  unable to read enough random data from /dev/random to seed
	  it's Diffie Hellman parameter generation. Please check that
	  your /dev/random device is setup properly.
	</para>
      </section>
    </section>
    <section>
      <title>SMTP-AUTH</title>
      <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>:
	</para>
	<programlisting>
name.of.server.example:mylogin:secretpassword
	</programlisting>
	<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 (like telnet).
	</para>
	<para>
	  If you need to enable them 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 appropriate macro as mentioned in the comments in the
	  configuration file.
	</para>
	<para>
	  <filename>/etc/exim4/passwd.client</filename> needs to be
	  readable for the exim user (user Debian-exim, group
	  Debian-exim). I suggest you keep the default permissions
	  root:Debian-exim 0640.
	</para>
      </section>
      <section>
	<title>Using exim as SMTP-AUTH server</title>
	<para>
	  The configuration file includes multiple examples for
	  server-side smtp-authentication which just need to be
	  uncommented. There is a macro available to allow unencrypted
	  passwords in all active authenticators at once.
	</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>
      </section>
    </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 don't 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're 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's 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>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 maintainance:</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 exim4 from
	<command>xinetd</command>, follow these steps:
	<orderedlist>
	  <listitem>
	    <simpara>
	      Disable exim4'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>Using pipe deliveries from alias files</title>
      <para>
	Using pipes in the <filename>/etc/aliases</filename> file is
	disabled by default in the Debian exim 4 packages, because the
	program 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.EXIM</filename> file
	that gives a good example how to implement this. Using a
	dedicated router/transport pairs 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
	"pipe_transport = ..." entry manually for the
	system_aliases-router in
	<filename>/etc/exim4/exim4.conf.template</filename> (or if you
	are using split-configuration -- dc_use_split_config='true' in
	<filename>/etc/exim4/update-exim4.conf.conf</filename> --
	<filename>/etc/exim4/conf.d/router/400_exim4-config_system_aliases</filename>).
      </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. Note that the transports listed in the
	system_aliases router are the same as are used for .forward
	files; you might want to set up different ones for pipe and file
	deliveries from aliases.
      </para>
    </section>

  </section>

  <section>
    <title>Updating from Exim 3</title>
    <para>
      If you use <command>exim4-config</command> from Debian, you'll
      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 doesn't 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. exim4 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>
    <para>
      PAM: On Debian systems the PAM modules run as the same user as
      the calling program, so they can't do anything you couldn't do
      yourself, and in particular can't 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.
    </para>
    <para>
      I suggest using saslauthd instead.
      
      In the default configuration, exim cannot locally deliver
      e-mails to accounts which have capitals in their name. This is
      caused by the fact that exim converts the local part of incoming
      e-mail to lower case before the comparision done by the
      check_local_user directive in routers is done.

      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>
    <para>
      <command>convert4r4</command> is installed as
      <filename>/usr/sbin/exim_convert4r4.</filename>
    </para>
    <para>
<!-- FIXME -->
      Changed defaults:
      * charset for $header_foo expansions defaults to UTF-8 instead of
      ISO-8859-1
    </para>
    <para>
      Since version 4.23 exim cannot run deliveries as root anymore. 
      If you don't redirect mail for root via
      <filename>/etc/aliases</filename> to a nonpriviledged account on
      Debian the mail will be delivered to
      <filename>/var/mail/mail</filename> with permissions 0600 and
      owner mail:mail.

      This is done by
      <filename>/etc/exim4/conf.d/router/mmm_mail4root</filename>.
      </para>
    <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>
    <para>
      <ulink url="http://marc.merlins.org/linux/exim/">Marc Merlin's
      Exim 4 Page</ulink> has a lot of ACL examples.
    </para>
    <para>
      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:
    </para>
  </section>  

  <section>
    <title>Debian modifications to the Exim source</title>
    <variablelist>
      <varlistentry>
	<term>
	  <ulink url="http://www.arise.demon.co.uk/exim-patches/">
	    Patches</ulink> by Steve Haslam:
	</term>
	<listitem>
	  <simpara>
	    boolean_redefine_protect
	    [src/mytypes.h]
	    Surround the definition of TRUE and FALSE macros with #ifndef
	    /#endif, in case some other header defines them (from mixing  No
	    Perl and Exim, istr)
	  </simpara>
	</listitem>
      </varlistentry>
      <varlistentry>
	<term>
	  Other stuff
	</term>
	<listitem>
	  <itemizedlist>
	    <listitem>
	      <simpara>
		link exim dynamically against pcre.
	      </simpara>
	    </listitem>
	    <listitem>
	      <para>
		The main binary is /usr/sbin/exim4:
		<itemizedlist>
		  <listitem>
		    <simpara>
		      src/globals.c was changed to use 'US
		      BIN_DIRECTORY "/exim4"' as default for
		      exim_path.
		    </simpara>
		  </listitem>
		  <listitem>
		    <simpara>
		      changed default for $exim_path (modulo
		      lower/upper case) from BIN_DIRECTORY/exim to
		      BIN_DIRECTORY/exim4 in exicyclog.src,
		      exim_checkaccess.src, eximon.src, exinext.src,
		      exiqgrep.src, exiwhat.src.
		    </simpara>
		  </listitem>
		  <listitem>
		    <simpara>
		      OS/Makefile-Linux:EXIWHAT_MULTIKILL_ARG=exim4
		    </simpara>
		  </listitem>
		</itemizedlist>
	      </para>
	    </listitem>
	    <listitem>
	      <simpara>
		<ulink url="http://marc.merlins.org/linux/exim/files/sa-exim-current/">localscan_dlopen.patch</ulink>:
		Allow 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>
	    <listitem>
	      <simpara>
		changes to the documentation to have the <ulink
		url="mailto:pkg-exim4-users@lists.alioth.debian.org">
		Debian-specific mailing list</ulink> mentioned where
		the <ulink url="mailto:exim-users@exim.org">official
		exim-users list</ulink> is mentioned
	      </simpara>
	    </listitem>
	  </itemizedlist>
	</listitem>
      </varlistentry>
    </variablelist>
  </section>

  <section>
    <title>Frequently Asked Questions</title>
    <qandaset>
      <qandaentry>
	<question>
	  <para>exim4-config should depend on exim4-base, shouldn't
	    it?</para>
	</question>
	<answer>
	  <para>
	    No, it shouldn't. It's entirely possible to (want to)
	    install an exim4-config package on a machine that doesn't
	    run exim4 - for instance in order to examine the
	    configuration before upgrading the machine to the exim4
	    packages using that configuration.
	  </para>
	  <para>
	    exim4-base correctly depends on a package providing one of
	    the virtual packages exim4-config{,-2}. The requirement is
	    that installing exim4 ensures that an appropriate
	    configuration is installed, not vice versa. (Answer by Adam
	    D. Barratt, in response to #310750, thanks!)
	  </para>
	</answer>
      </qandaentry>
      <qandaentry>
	<question>
	  <para>I don't like the template-based configuration. How can
	    I use one single monolithic configuration file that I'm used
	    to?</para>
	</question>
	<answer>
	  <para>
	    No problem. Take your file and install it as
	    <filename>/etc/exim4/exim4.conf</filename>. Exim will use
	    that file. To have something to start, you can either take
	    <filename>/etc/exim4/exim4.conf.template</filename>, or
	    run update-exim4.conf --keepcomments --output
	    /path/to/some/file and use some/file as a starting point
	    for your configuration. You're going to lose all magic you
	    get from packaging though. 
	    <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>
	</answer>
      </qandaentry>

      <qandaentry>
	<question>
	  <para>The user name Debian-$PACKAGE is too long: it
	  misalignes ls output and is truncated by ps and atop. And
	  it's ugly!</para>
	</question>
	<answer>
	  <para>
	    The user name Debian-$PACKAGE was chosen in late 2003 when
	    we, the maintainers of the Debian exim4 package found it
	    necessary to create an account for exim to run under during
	    package installation. To avoid accidentylly zapping a
	    locally used account, we intended to use a name from a name
	    space with low potential for name conflicts.
	  </para>
	  <para>
	    About the same time, Fabio Massimo Di Nitto started the same
	    <ulink
	      url="http://lists.debian.org/debian-devel/2003/11/msg02231.html">discussion</ulink>
	    on debian devel.
	  </para>
	  <para>
	    In this thread, many things were said:
	    <itemizedlist>
	      <listitem>
		<para>
		  This should be decided by the LSB. However, to my
		  knowledge, that step has not yet happened.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  It needs to be in policy. However, policy has not been
		  amended, and there is no bug filed against policy.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  Purging a package should remove the account as well.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  Special care needs to be taken to avoid removing an
		  account that doesn't belong to us.
		</para>
	      </listitem>
	      <listitem>
		<para>
		  The numeric UID shouldn't be re-used.
		</para>
	      </listitem>
	    </itemizedlist>
	    For the namespaces, we have the following suggestions:
	    <itemizedlist>
	      <listitem>
		<para>
		  Prepend/Append "Debian" or "debian"
		</para>
	      </listitem>
	      <listitem>
		<para>
		  Prepend/Append a single <ulink
		    url="http://cr.yp.to/unixaccount.html">capital
		    letter</ulink>
		</para>
	      </listitem>
	      <listitem>
		<para>
		  Prepend/Append an underscore
		</para>
	      </listitem>
	    </itemizedlist>
	    Unfortunately, the way to get a LSB solution will take way
	    too long. Additionally, the LSB likes to have pre-existing
	    use as example before they change the standard.
	  </para>
	  <para>
	    So, it was our job to decide which account name to use. 
	    Andreas Metzler and me chose Debian-$PACKAGE, while Peter
	    Palfrader started using debian-$PACKAGE. So we currently
	    have Debian-exim, Debian-console-log, debian-tor,
	    debian-mixminion and debian-sks.
	  </para>
	  <para>
	    Again, the goal was to create accounts that don't conflict
	    with other, or with manually created accounts, and to get
	    pre-existing use before trying to change the LSB and even
	    Debian policy.
	  </para>
	  <para>
	    Migrating from one account name to another is extremely
	    painful and error-pronce since one needs to meddle with the
	    local account database and has to optionally chown files. 
	    Additionally, it is necessary to change every script that
	    accesses the account. To put it short: It's something you
	    want to avoid.
	  </para>
	  <para>
	    This is also the reason why the account names used by these
	    packages will not likely change before a namespace is
	    dedicated and allocated either in the LSB or in Debian
	    policy. The maintainers reserve the right of hurling this
	    FAQ in the direction of everybody filing bugs about the
	    "ugly" account names, and to close the bugs in the process.
	  </para>
	  <para>
	    We would appreciate, however, if people would aid in getting
	    the standardization process under way as soon as possible. 
	    This needs to be in policy, the sooner the better.
	  </para>
	  <para>
	    Marc Haber, 2004-05-11
	  </para>
	</answer>
      </qandaentry>
      <qandaentry>
	<question>
	  <para>How can I automatically replace my local username in
	    all mail with my real public address?</para>
	</question>
	<answer>
	  <para>
	    You can use <filename>/etc/email-addresses</filename> for
	    this purpose, which will cause exim to change Reply-To,
	    From, Sender and "MAIL FROM:" accordingly. The file
	    includes examples.
	  </para>
	</answer>
      </qandaentry>
      <qandaentry>
	<question>
	  <para>
	    I setup Exim 4 to use Maildir and deliver to
	    <filename>~/Maildir</filename> instead of to
	    /var/mail/username? I need this for Courier or Dovecot.
	  </para>
	</question>
	<answer>
	  <para>
	    Add dc_localdelivery=maildir_home to
	    <filename>/etc/exim4/update-exim4.conf.conf</filename> and
	    run "invoke-rc.d exim4 reload".
	  </para>
	</answer>
      </qandaentry>
      <qandaentry>
	<question>
	  <para>
	    Why does take such a long time to start? (I think it is
	    making a DNS lookup although my
	    <filename>/etc/hosts</filename> holds all the necessary
	    information.)
	  </para>
	</question>
	<answer>
	  <para>
	    Exim will indeed try to lookup the primary hostname at
	    startup, however it will first search for an AAAA record
	    (IPv6), therefore triggering a DNS lookup even if there is
	    an IPv4 address for the hostname listed in
	    <filename>/etc/hosts.</filename>.</para>
	  <para>
	    There is a number of ways to fix this:
	    <itemizedlist>
	      <listitem>
		<simpara>
		  use dc_minimaldns='true'. (Either edit
		  <filename>/etc/exim4/update-exim4.conf.conf</filename>
		  or use dpkg-reconfigure exim4-conf).
		</simpara>
	      </listitem>
	      <listitem>
		<simpara>
		  Use the FQDN as hostname in
		  <filename>/etc/hostname</filename>, i.e. 
		  "foo.example.com" instead of just "foo". (You have
		  to execute "hostname -F /etc/hostname" to implement
		  the change to <filename>/etc/hostname</filename>.)
		</simpara>
	      </listitem>
	      <listitem>
		<simpara>
		  Add an IPv6 record for your hostname (listed in
		  <filename>/etc/hostname</filename>) to
		  <filename>/etc/hosts</filename>. You can check with
		  "getent hosts your_hostname" whether this was
		  successful.
		</simpara>
	      </listitem>
	      <listitem>
		<simpara>
		  Disable IPv6 host lookups in exim by setting
		  "dns_ipv4_lookup = *".
		</simpara>
	      </listitem>
	      <listitem>
		<simpara>
		  Set "primary_hostname = your_hostname"
		</simpara>
	      </listitem>
	      <listitem>
		<simpara>
		  If this delay happens only during or directly after
		  Debian installation, it is likely that you have are
		  hit by a bug in base-config prior to 2.53.8, where
		  exim is invoked with a signal handler for SIGTERM
		  installed. Thus, stopping this exim daemon takes a
		  long time because exim keeps ignoring the SIGTERM. 
		  This is a one-shot issue, though, and fixed in
		  base-config 2.53.8 and later (see #301988).
		</simpara>
	      </listitem>
	    </itemizedlist>
	  </para>
	</answer>
      </qandaentry>
      <qandaentry>
	<question>
	  <para>Why are you not supporting SPF?</para>
	</question>
	<answer>
	  <para>
	    exiscan 4.34-22 introduced support for the <ulink
	      url="http://spf.pobox.com">Sender Policy Framework</ulink>? 
	    by means of a <command>spf</command> ACL condition. This
	    functionality is currently not included in the official
	    Debian packages.
	  </para>
	  <para>
	    Rationale:
	    <itemizedlist>
	      <listitem>
		<simpara>
		  IMHO, SPF has not reached the necessary amount of
		  standardization and acceptance for inclusion in a
		  Debian/stable release, it is still in flux.
		</simpara>
	      </listitem>
	      <listitem>
		<simpara>
		  I do not want to drag in another library dependency.
		</simpara>
	      </listitem>
	      <listitem>
		<simpara>
		  Checking with <ulink
		    url="http://packages.debian.org/libmail-spf-query-perl">spfd</ulink>
		  instead of exiscan's spf-condition offers the same
		  functionality, AFAICT.
		</simpara>
	      </listitem>
	      <listitem>
		<simpara>
		  SpamAssassin 3.0+ includes SPF support.
		</simpara>
	      </listitem>
	      <listitem>
		<simpara>
		  I do not want to encourage SPF because I am not
		  convinced of its benefits. (Discussion and links on
		  benefits and downsides of SPF are not listed here
		  intentionally.)
		</simpara>
	      </listitem>
	    </itemizedlist>
	  </para>
	</answer>
      </qandaentry>
    </qandaset>
  </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>

<!--
  <section>
    <title>Tweaking Configuration</title>
    <para>
      If you want to tweak the configuration you should modify
      <filename>/etc/exim4/exim4.conf.template</filename> if you have
      an "unsplit" configuration. If you have a "split" configuration
      modify or add to the files under
      <filename>/etc/exim4/conf.d/</filename>. In either case the
      files are extensively commented.
    </para>
  </section>

-->