path: root/debian/README.Debian

This is the Debian package for exim4.

As with the apache package, exim4 is an entirely different package
that does not currently offer a smooth upgrade path from the Debian
exim 3 packages.

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.

To use exim4, you need at least the following packages:
exim4-base         EXperimental Internal Mailer -- a Mail Transport
exim4-config       Debian configuration for exim4
exim4-daemon-light Lightweight version of the Exim (v4) MTA

Just apting the meta-package exim4 will pull in the other packages per
dependency. You'll get an exim daemon with minimal feature set (no external
lookups).

If you want to have a different feature set, you can install one of
the other exim4-daemon-Packages instead of exim4-daemon-light, or you
can modify the source package to build exim4-daemon-custom according
to your needs. The infrastructure to do so is already in place, see
debian/rules for instructions.

********************************************
Updating from exim 3 ***********************
********************************************

If you use exim4-config from Debian, you'll get the debconf based
configuration scheme that is intended to cover the majority of cases.

If exim4-config is installed while an exim 3 package is present on the
system, exim4-config tries to parse the exim 3 config file to
determine the answers that were given to eximconfig on exim 3
installation. These answers are then taken as default values for the
debconf based configuration process. Be warned! eximconfig 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 /etc/exim/exim.conf, which is bound to fail if the
config file has been modified after using eximconfig.

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.

Please note that we do not use the exim_convert4r4 script, but try to
configure the exim 4 package in the same way exim 3 was. This will
hopefully aid future updates.

If you have used a customized exim 3 configuration, you can of course
use exim_convert4r4, and install the resulting file as /etc/exim4/exim4.conf
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
exim_convert4r4-generated file verbatim but instead drop appropriate
configuration snippets in their appropriate place in
/etc/exim4/conf.d.

*******************************************************
What are these gazillion number of files in /etc/exim4/conf.d? How do I
get rid of them? How does the configuration work? What kind of crack are
you smoking?
*******************************************************

Our packages offer two (actually three, see below at
/etc/exim4/exim4.conf) possibilities:

#1 Generate exim's configuration from /etc/exim4/exim4.conf.template
#2 Generate exim's configuration from the multiple files in
   /etc/exim4/conf.d/.

You can choose between the alternatives with dpkg-reconfigure
exim4-config or by changing the value of dc_use_split_config in
update-exim4.conf.conf manually.

The split into multiple files below /etc/exim4/conf.d/ is quite
straightforward. Each section of exim's configuration has its own
subdirectory and the files in there are supposed to be read in
alphanumeric order. router/00_exim4-config_header is followed by
router/100_exim4-config_domain_literal, ...

Benefits of this approach:
   * 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 _this_ transport.
   * It allows other packages (e.g. sa-exim) to modify exim's
     configuration by shipping files in /etc/exim4/conf.d.

Downsides of this approach:
   * It is more fragile. If I 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.

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.

What about debconf?
------
Debconf just "manages" the file /etc/exim4/update-exim4.conf.conf. 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.

How does this work? Exim cannot handle the gazillion files or parse
/etc/exim4/update-exim4.conf.conf.
------
The script update-exim4.conf does the work.

Depending on the value of dc_use_split_config, it either
- takes all the files below /etc/exim4/conf.d/ and concatenates
  them together or
- uses exim4.conf.template as input.

The debconf-managed information from /etc/exim4/update-exim4.conf.conf
is merged into the generated configuration file. Strings like
DEBCONFfooDEBCONF are replaced by the value that is set in
/etc/exim4/update-exim4.conf.conf for the keyword dc_foo.

DEBCONFsmarthostDEBCONF, for example, is replaced with the value of
$dc_smarthost in /etc/exim4/update-exim4.conf.conf which holds the
answer to "Which machine will act as the smarthost and handle outgoing
mail?"

The result of these operations is saved as
/var/lib/exim4/config.autogenerated, which is _NOT_ a dpkg-conffile!
Manual changes to this file will be overwritten by update-exim4.conf.

Please consult the manpage of update-exim4.conf for more detailed
information.

update-exim4.conf 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 reload".

I still don't like it. I want one monolithic file.
------
No problem. Take your file and install it as /etc/exim4/exim4.conf. Exim
will use that file.  /var/lib/exim4/config.autogenerated, the file
generated by update-exim4.conf, is ignored in that case. You should not
edit /etc/exim4/exim4.conf 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.


*******************************************************
Using a completely different configuration scheme *****
*******************************************************

We have split off exim's configuration system (debconf,
update-exim4.conf, and the files in /etc/exim4/conf.d) 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:

   * Provides: exim4-config-2, Conflicts: exim4-config-2,exim4-config
   * drop the exim 4 configuration either into
     /var/lib/exim4/config.autogenerated or into /etc/exim4/exim4.conf.

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.

The source package contains a number of little helpers that can aid
you in creating your own configuration packages:

   * The subdirectory debian/exim4-config-simple contains a simple,
     not debconf-driven configuration scheme as example (in form of a
     Debian source package) which can be used as template for a
     classical, exim4.conf based configuration scheme.

   * The subdirectory debian/exim4-config-medium 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.
   
   * 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.

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.

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.

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.


********************************************
Misc Notes *********************************
********************************************

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 /etc/shadow unless the user is in group shadow. - If you want to use
/etc/shadow for Exim's SMTP AUTH you will need to run exim as group shadow.
Only exim4-daemon-heavy is linked against libpam.

I suggest using saslauthd instead.
_____________________________________________

convert4r4 is installed as /usr/sbin/exim_convert4r4.
_____________________________________________

The CVS repository of the Debian package is publically accessible on
alioth.debian.org, see https://alioth.debian.org/projects/pkg-exim4
_____________________________________________

Changed defaults:
* charset for $header_foo expansions defaults to UTF-8 instead of
  ISO-8859-1
_____________________________________________

Since version 4.23 exim cannot run deliveries as root anymore. If you
don't redirect mail for root via /etc/aliases to a nonpriviledged
account on Debian the mail will be delivered to /var/mail/mail with
permissions 0600 and owner mail:mail.

This is done by /etc/exim4/conf.d/router/mmm_mail4root.
_____________________________________________

Most of the scripts that come with this Debian package do a set -x 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.
_____________________________________________


********************************************
Modifications ******************************
********************************************
Patches by Steve Haslam available from
 http://www.arise.demon.co.uk/exim-patches/:
******
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)

******
Other stuff
******
* link exim dynamically against pcre.

* The main binary is /usr/sbin/exim4:
   - src/globals.c was changed to use 'US BIN_DIRECTORY "/exim4"' as default
     for exim_path.
   - 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.
   - OS/Makefile-Linux:EXIWHAT_MULTIKILL_ARG=exim4

* localscan_dlopen.patch downloaded from
  http://marc.merlins.org/linux/exim/files/sa-exim-current/
  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 /path/to/sharedobject

# vim:tw=72:expandtab