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.
Exim comes with very extensive documentation. Here is how to find it.
/usr/share/doc/exim4-base/spec.txt.gz)
with the binary packages.
exim4-doc-html
exim4-doc-info
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.
For your questions and comments, there is a Debian-specific 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; you need to be subscribed to post.
If you think that your question might be more easily answered if one knows a bit about your configuration, you might want to execute reportbug --subject="none" --offline --quiet --severity=wishlist --body="none" --output=exim4.reportbug exim4-config 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.
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 metapackage 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, 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 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. 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 Section 2.1.6, “Using a completely different configuration scheme”.
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.
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.
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.gz
chapters 3 and 6. spec.txt.gz is an excellent
reference.
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.
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
dpkg-reconfigure exim4-config.
/etc/exim4/update-exim4.conf.conf,
documented in the update-exim4.conf
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.
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.
This option is suitable for a standalone system with full internet connectivity.
The Exim SMTP daemon will accept messages to local domains, and deliver them locally.
Outgoing mail will be delivered directly to the mail exchange servers of the recipient domain
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.
fetchmail can be used to retrieve incoming mail from the ISP's POP3 or IMAP mail server and deliver it to Exim via SMTP.
The Exim SMTP daemon will accept messages to local domains, and deliver them locally.
Outgoing mail will always be delivered to the smarthost configured in exim4.
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.
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''.
This option disables most of Debian's automatisms
and leaves exim in an unconfigured state.
update-exim4.conf will still copy
/etc/exim4/exim4.conf.template
or concatenate the files from
/etc/exim4/conf.d, 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.
Only choose this option if you know what you're doing and are prepared to create your own Exim configuration.
dpkg-conffile handling is still in place, and you will be offered updates for configuration snippets, as soon as they become available.
The "mail name" is the domain name used to "qualify" mail addresses without a domain name.
This name will also be used by other programs. It should be the single, full domain name (FQDN).
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.
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.
This qualification happens for all addresses exim encounters, be it sender, recipient or else.
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 /etc/mailname, which is a
file that might be used by other programs as well.
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.
Please enter a semicolon-separated list of IP addresses. The Exim SMTP listener daemon will listen on all IP addresses listed here.
An empty value will cause Exim to listen for connections on all available network interfaces.
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.
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.
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.
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.
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.
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.
Do not mention local domains here. Wildcards may be used.
The answer to this question is a list of the domains for which Exim will relay messages coming in from anywhere on the Internet.
Please enter a semicolon-separated list of IP address ranges for which this system will unconditionally relay mail, functioning as a smarthost.
You should use the standard address/prefix format (e.g. 194.222.242.0/24 or 5f03:1200:836f::/48).
If this system should not be a smarthost for any other host, leave this list blank.
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 NOT list 0.0.0.0/0!
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.
If the smarthost requires authentication, please refer to Section 2.3, “SMTP-AUTH” for notes about setting up SMTP authentication.
Multiple smarthost entries are permitted, semicolon separated. Each of the hosts is tried, in the order specified (See Exim specification, chapter 20.5).
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.
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.
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.
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.
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.
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/.
Please note that most mail tools in Debian expect the local delivery method to be mbox in their default.
Our packages offer two (actually three, see Section 2.1.6, “Using a completely different configuration scheme”) possibilities:
/etc/exim4/exim4.conf.template,
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.
/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.
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,
...
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 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 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:
exim4.conf.template
basically is a complete Exim configuration
file which will only undergo some basic
string replacement before is it passed to
exim.
Drawbacks 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.
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.
The data files are documented in the exim4-config_files man page.
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.
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 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.
The script update-exim4.conf parses the
/etc/exim4/update-exim4.conf.conf file
and provides the configuration for the exim 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 by generating a
number of Exim configuration macros.
DCsmarthost, for example, is set to 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.
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.
If you want to modify parameters that are supported by the
debconf configuration, things are easy. Just invoke
dpkg-reconfigure exim4-config or hand-edit
/etc/exim4/update-exim4.conf.conf to your
liking and restart Exim.
You can find explanation of the debconf questions in Section 2.1.1, “The Debconf questions”.
Additionally,
/etc/exim4/update-exim4.conf.conf
is documented in the update-exim4.conf
man page.
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.
Section 2.1.3, “Using Exim Macros to control the configuration” gives a closer explanation about how to do this.
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.
If you use unsplit configuration, edit
/etc/exim4/exim4.conf.template. If you use
split configuration, edit the Exim configuration snippets in
/etc/exim4/conf.d.
More information about how the Exim configuration is built can be found in this document and in the update-exim4.conf manual page.
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.
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.
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
/etc/exim4/exim4.conf. Exim will
use that file verbatim. To have something to start,
you can either take
/etc/exim4/exim4.conf.template,
run update-exim4.conf --keepcomments --output
/etc/exim4/exim4.conf, or use upstream's
default configuration file that is installed as
/usr/share/doc/exim4-base/examples/example.conf.gz.
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.
/var/lib/exim4/config.autogenerated,
the file generated by
update-exim4.conf, is ignored as soon
as /etc/exim4/exim4.conf is found.
You should not edit
/etc/exim4/exim4.conf directly when
Exim is running, because the forked processly three, see
Section 2.1.6, “Using a completely different configuration scheme”)
possibilities:
/etc/exim4/exim4.conf.template,
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.
/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.
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,
...
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 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 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:
exim4.conf.template
basically is a complete Exim configuration
file which will only undergo some basic
string replacement before is it passed to
exim.
Drawbacks 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.
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.
The data files are documented in the exim4-config_files man page.
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.
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 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.
The script update-exim4.conf parses the
/etc/exim4/update-exim4.conf.conf file
and provides the configuration for the exim 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 by generating a
number of Exim configuration macros.
DCsmarthost, for example, is set to 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.
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.
If you want to modify parameters that are supported by the
debconf configuration, things are easy. Just invoke
dpkg-reconfigure exim4-config or hand-edit
/etc/exim4/update-exim4.conf.conf to your
liking and restart Exim.
You can find explanation of the debconf questions in Section 2.1.1, “The Debconf questions”.
Additionally,
/etc/exim4/update-exim4.conf.conf
is documented in the update-exim4.conf
man page.
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.
Section 2.1.3, “Using Exim Macros to control the configuration” gives a closer explanation about how to do this.
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.
If you use unsplit configuration, edit
/etc/exim4/exim4.conf.template. If you use
split configuration, edit the Exim configuration snippets in
/etc/exim4/conf.d.
More information about how the Exim configuration is built can be found in this document and in the update-exim4.conf manual page.
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.
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.
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
/etc/exim4/exim4.conf. Exim will
use that file verbatim. To have something to start,
you can either take
/etc/exim4/exim4.conf.template,
run update-exim4.conf --keepcomments --output
/etc/exim4/exim4.conf, or use upstream's
default configuration file that is installed as
/usr/share/doc/exim4-base/examples/example.conf.gz.
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.
/var/lib/exim4/config.autogenerated,
the file generated by
update-exim4.conf, is ignored as soon
as /etc/exim4/exim4.conf is found.
You should not edit
/etc/exim4/exim4.conf directly when
Exim is running, because the forked processly three, see
Section 2.1.6, “Using a completely different configuration scheme”)
possibilities:
/etc/exim4/exim4.conf.template,
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.
/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.
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,
...
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 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 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:
exim4.conf.template
basically is a complete Exim configuration
file which will only undergo some basic
string replacement before is it passed to
exim.
Drawbacks 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.
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.
The data files are documented in the exim4-config_files man page.
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.
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 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.
The script update-exim4.conf parses the
/etc/exim4/update-exim4.conf.conf file
and provides the configuration for the exim 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 by generating a
number of Exim configuration macros.
DCsmarthost, for example, is set to 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.
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.
If you want to modify parameters that are supported by the
debconf configuration, things are easy. Just invoke
dpkg-reconfigure exim4-config or hand-edit
/etc/exim4/update-exim4.conf.conf to your
liking and restart Exim.
You can find explanation of the debconf questions in Section 2.1.1, “The Debconf questions”.
Additionally,
/etc/exim4/update-exim4.conf.conf
is documented in the update-exim4.conf
man page.
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.
Section 2.1.3, “Using Exim Macros to control the configuration” gives a closer explanation about how to do this.
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.
If you use unsplit configuration, edit
/etc/exim4/exim4.conf.template. If you use
split configuration, edit the Exim configuration snippets in
/etc/exim4/conf.d.
More information about how the Exim configuration is built can be found in this document and in the update-exim4.conf manual page.
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.
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.
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
/etc/exim4/exim4.conf. Exim will
use that file verbatim. To have something to start,
you can either take
/etc/exim4/exim4.conf.template,
run update-exim4.conf --keepcomments --output
/etc/exim4/exim4.conf, or use upstream's
default configuration file that is installed as
/usr/share/doc/exim4-base/examples/example.conf.gz.
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.
/var/lib/exim4/config.autogenerated,
the file generated by
update-exim4.conf, is ignored as soon
as /etc/exim4/exim4.conf is found.
You should not edit
/etc/exim4/exim4.conf directly when
Exim is running, because the forked processly three, see
Section 2.1.6, “Using a completely different configuration scheme”)
possibilities:
/etc/exim4/exim4.conf.template,
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.
/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.
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,
...
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 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 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:
exim4.conf.template
basically is a complete Exim configuration
file which will only undergo some basic
string replacement before is it passed to
exim.
Drawbacks 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.
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.
The data files are documented in the exim4-config_files man page.
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.
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 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.
The script update-exim4.conf parses the
/etc/exim4/update-exim4.conf.conf file
and provides the configuration for the exim 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 by generating a
number of Exim configuration macros.
DCsmarthost, for example, is set to 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 i