Table of Contents
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.
For your questions and comments, there is a mailing list. 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 via the subscription web page.
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.
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.
The development web page 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.
To use Exim 4, you need at least the following packages:
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 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 exim4-daemon-heavy instead of exim4-daemon-light. 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.
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 dpkg-reconfigure exim4-config.
The debconf-driven configuration is mainly geared for a one-domain shell account machine/workstation with local delivery. It has some small extensions, but 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.
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 /usr/share/doc/exim4-base/spec.txt
chapters 3 and 6. spec.txt is an excellent
reference.
Our packages offer two (actually three, see below at
/etc/exim4/exim4.conf) possibilities:
/etc/exim4/exim4.conf.template, which
is basically a normal exim run-time configuration file which is
subjected to some post-processing (mostly macro expansion) before it
is passed to exim.
/etc/exim4/conf.d/. The directories
in /etc/exim4/conf.d/ correspond to
the sections of the exim run-time configuration file, so
you should easily find your way around there.
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.
Splitting the configuration across multiple files means that
you have the actual configuration file automatically generated
from the files below /etc/exim4/conf.d/
by invoking update-exim4.conf. 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,
... Please consult the manual page update-exim4.conf(8) for
more details.
If you chose unsplit configuration,
update-exim4.conf builds the configuration
from /etc/exim4/exim4.conf.template, which
is basically the files from
/etc/exim4/conf.d/ concatenated together at
package build time, and thus guarantees consistency on the
target system.
In both cases, update-exim4.conf 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.
Benefits of the split configuration approach:
/etc/exim4/conf.d. This needs, however
quite exact syncing between the exim4 packages and the other,
cooperating package.
Drawbacks of the split configuration approach:
Benefits of the unsplit configuration approach:
Benefits of the unsplit configuration approach:
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.
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.
If you are using unsplit configuration, have local changes to
/etc/exim4/conf.d/ (either made by yourself
or by other packages dropping their own routers or transports
in) and want to re-generate
/etc/exim4/exim4.conf.template to activate
these changes, you can do so by using
update-exim4.conf.template.
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.
Whenever you see an .ifdef or
.ifndef 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
/etc/exim4/conf.d/main. Just make sure it
gets read before the macro is first used.
000_localmacros is a possible name,
guaranteeing first order. For a non-split configuration,
/etc/exim4/exim4.conf.localmacros gets
read before
/etc/exim4/exim4.conf.template. To
actually set the macro EXIM4_EXAMPLE to the
value "this is a sample", write the following line
EXIM4_EXAMPLE = this is a sample
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.
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.
The script update-exim4.conf parses teh
/etc/exim4/update-exim4.conf.conf file
and provides the configuration for the exim4 daemon.
Depending on the value of
dc_use_split_config, it either
/etc/exim4/conf.d/ and
concatenates them together or
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 update-exim4.conf manpage 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 restart".
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:
/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.
If you want to create your own configuration packages, there is a number of helpers available.
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.
See the development web page for links to the subversion repository.
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.
Both exim4-daemon-heavy and exim4-daemon-light support TLS/SSL using the GnuTLS library and STARTTLS. Exim will use TLS via STARTTLS automatically as client if the server exim connects to offers it. TLS on connect is not natively supported. You can stop reading now if you are not setting up a mailserver which needs to offer TLS for incoming connections.
You should have created certificates in
/etc/exim4/ either by hand or by usage of
the exim-gencert (which requires openssl). exim-gencert is
shipped in
/usr/share/doc/exim4-base/examples/ and
takes care of proper access privileges on the private key
file.
Now, enable TLS by setting the macro MAIN_TLS_ENABLE in a local configuration file (documented below).
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.
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
(/var/spool/exim4/gnutls-params).
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.
NOTE! The fact that GnuTLS does not support generated Diffie-Hellman parameters does NOT make it less secure.
For more reference, you can refer to
/usr/share/doc/exim4-base/spec.txt.gz,
section 38.
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
2003-01-27 19:06:45 TLS error on connection from localhost [127.0.0.1] (cert/key setup): Error while reading file)
showing that there has been an error while accessing the certificate or the private key file.
Insuffient entropy available is a frequent cause of TLS failures in Exim context. If Exim says "not random bytes available", or simply hangs silently when an encrypted connection should be established, then Exim was unable to read enough random data from /dev/random to do whatever cryptographic operation is requested. Please check that your /dev/random device is setup properly.
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
/etc/exim4/passwd.client. That file also
contains verbose information about the required format.
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).
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. Please refer to Section 2.1.1, “Using Exim Macros to control the configuration” for an explanation of how best to do this.
/etc/exim4/passwd.client 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.
The configuration files include many, verbosely commented, examples for server-side smtp-authentication which just need to be uncommented.
If you want to authenticate against system passwords (e.g.
/etc/shadow) 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.
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.
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.
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:
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
However, all recipients are handled via the command line, so you're discouraged to use it.
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.
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):
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
and this if it wants bsmtp as the command:
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
Of course, these examples can be extended for e.g. compression (but you can also use ssh for compression, if you want).
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.
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
The file /etc/exim4/uucp looks like:
*.do.main uucp.name.of.remote.side
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 /etc/exim4/uucp is
not needed in this case.
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.
Exim4 is run as a separate daemon instead of inetd/xinetd for two reasons:
If you introduce bugs on your systems by running from (x)inetd you are on your own! If you want to run exim4 from xinetd, follow these steps:
Create /etc/xinetd.d/exim4
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
}
If you want to use plain inetd, insert following line into
/etc/inetd.conf:
smtp stream tcp nowait Debian-exim /usr/sbin/exim4 exim4 -bs
Using pipes in the /etc/aliases 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.
Invoking pipes from /etc/aliases 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
/usr/share/doc/mailman/README.EXIM file
that gives a good example how to implement this. Using a
dedicated router/transport pairs have the following advantages:
The router/transport pair can be put in place by another package, giving a well-defined transaction point between Exim 4 and $PACKAGE.
Not allowing pipe deliveries from alias files makes it harder to accidentally run programs with wrong privileges.
It is possible to run different pipe processes under different accounts.
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.
If you insist on using /etc/aliases in
the traditional way, you will need to activate the
"pipe_transport = ..." entry manually for the
system_aliases-router in
/etc/exim4/exim4.conf.template (or if you
are using split-configuration -- dc_use_split_config='true' in
/etc/exim4/update-exim4.conf.conf --
/etc/exim4/conf.d/router/400_exim4-config_system_aliases).
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.
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.
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. 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.
convert4r4 is installed as
/usr/sbin/exim_convert4r4.
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.
Marc Merlin's Exim 4 Page has a lot of ACL examples.
For an example of Exim usage in a large installation, see Tony Finch's paper about the exim installation at University of Cambridge:
The main binary is /usr/sbin/exim4:
/path/to/sharedobject.
| 6.1. | exim4-config should depend on exim4-base, shouldn't it? |
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. 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!) | |
| 6.2. | I don't like the template-based configuration. How can I use one single monolithic configuration file that I'm used to? |
No problem. Take your file and install it as
| |
| 6.3. | The user name Debian-$PACKAGE is too long: it misalignes ls output and is truncated by ps and atop. And it's ugly! |
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. About the same time, Fabio Massimo Di Nitto started the same discussion on debian devel. In this thread, many things were said:
For the namespaces, we have the following suggestions:
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. 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. 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. 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. 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. 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. Marc Haber, 2004-05-11 | |
| 6.4. | How can I automatically replace my local username in all mail with my real public address? |
You can use | |
| 6.5. |
I setup Exim 4 to use Maildir and deliver to
|
Add dc_localdelivery=maildir_home to
| |
| 6.6. |
Why does take such a long time to start? (I think it is
making a DNS lookup although my
|
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
There is a number of ways to fix this:
| |
| 6.7. | Why are you not supporting SPF? |
exiscan 4.34-22 introduced support for the Sender Policy Framework? by means of a spf ACL condition. This functionality is currently not included in the official Debian packages. Rationale:
|