---
myst:
  html_meta:
    description: Install and configure Exim4 mail transfer agent using the interactive dpkg-reconfigure wizard for email server setup on Ubuntu, using saslauthd or the exim4 user database.
---

(install-exim4)=
# Install and configure Exim4

## Install Exim4

To install [Exim4](https://www.exim.org/), run the following command:

```bash
sudo apt install exim4
```

## Configure Exim4

To configure Exim4, run the following command:

```bash
sudo dpkg-reconfigure exim4-config
```

This displays a "wizard" user interface for configuring the software. One important question in this configuration is whether Exim4 should split the configuration over multiple files, or use a single configuration file.

```{note}
The default configuration layout for Exim4 is the single configuration file one.
```

If using multiple configuration files, then the configuration will be split in a directory structure under `/etc/exim4/conf.d`, like so:
```text
/etc/exim4/
└── conf.d
    ├── acl
    ├── auth
    ├── main
    ├── retry
    ├── rewrite
    ├── router
    └── transport
```
Each subdirectory contains one or more individual configuration files.

If, however, Exim4 was set up to use a single configuration file, then that file will be `/etc/exim4/exim4.conf.template`. It will essentially be as if all individual configuration files from the previous layout were concatenated into one file.


In any of these scenarios, after making a change to the configuration, the following command must be executed to update the actual configuration file that Exim4 will use:

```text
sudo update-exim4.conf
```

The `update-exim4.conf` command will update the auto-generated configuration file stored in `/var/lib/exim4/config.autogenerated`. This is the actual configuration file that Exim4 uses.

```{warning}
You should never manually edit the configuration file `/var/lib/exim4/config.autogenerated`, because it is updated automatically every time you run `update-exim4.conf`. Any changes you make to it will eventually be lost.
```

If configuration changes were made, the service should also be restarted:
```text
sudo systemctl restart exim4
```

All the choices made via `dpkg-reconfigure exim4-config` are stored in the `/etc/exim4/update-exim4.conf.conf` file. To re-configure the software you can either re-run `dpkg-reconfigure` as before, or manually edit this file using your preferred editor.


## Start the Exim4 daemon

The following command will start the Exim4 daemon:

```bash
sudo service exim4 start
```

## SMTP authentication

There are multiple authentication options available for Exim4. Here we will document two methods:

 * Authenticate Linux users present in the local shadow file (`/etc/shadow`), via `saslauthd` and PAM.
 * Authenticate arbitrary users against a custom Exim4 password database (`/etc/exim4/passwd`).

Both of these methods use clear text passwords transmitted over the network, so they need to be protected by Transport Layer Security (TLS).

```{warning}
All configuration steps shown from now on will assume a split-configuration mode for Exim4. If you have selected the non-split mode, then all commands that edit a configuration file under `/etc/exim4/conf.d` in the sections below should be replaced with editing the single file `/etc/exim4/exim4.conf.template`.
```

### Enabling TLS

First, enter the following into a terminal prompt to create a certificate for use with TLS:

```bash
sudo /usr/share/doc/exim4-base/examples/exim-gencert
```
This command will ask some questions about the certificate, like country, city, and others. The most important one, and that must be correct otherwise TLS won't work for this server, is the "Server name" one. It **MUST** match the fully qualified hostname (FQDN) of the system where Exim4 is deployed.

```{warning}
This will install a self-signed certificate. If deploying this system in production, you must get a proper certificate signed by a recognized Certificate Authority (CA), or, if using an internal, you will have to distribute the CA to all clients expected to connect to this server.
```
Configure Exim4 for TLS by editing the `/etc/exim4/conf.d/main/03_exim4-config_tlsoptions` file and adding the following:

```text
MAIN_TLS_ENABLE = yes
```

### Authenticating existing Linux users

To authenticate existing Linux users, that is, users who already have accounts on this system, we will use the `saslauthd` service.

```{note}
To manage local Linux users, please refer to {ref}`User management <user-management>`.
```

Configure Exim4 to use the `saslauthd` daemon for authentication by editing `/etc/exim4/conf.d/auth/30_exim4-config_examples` -- uncomment the `plain_saslauthd_server` and `login_saslauthd_server` sections:

```text 
plain_saslauthd_server:
  driver = plaintext
  public_name = PLAIN
  server_condition = ${if saslauthd{{$auth2}{$auth3}}{1}{0}}
  server_set_id = $auth2
  server_prompts = :
  .ifndef AUTH_SERVER_ALLOW_NOTLS_PASSWORDS
  server_advertise_condition = ${if eq{$tls_cipher}{}{}{*}}
  .endif

login_saslauthd_server:
  driver = plaintext
  public_name = LOGIN
  server_prompts = "Username:: : Password::"
  # don't send system passwords over unencrypted connections
  server_condition = ${if saslauthd{{$auth1}{$auth2}}{1}{0}}
  server_set_id = $auth1
  .ifndef AUTH_SERVER_ALLOW_NOTLS_PASSWORDS
  server_advertise_condition = ${if eq{$tls_cipher}{}{}{*}}
  .endif
```

This enables the `PLAIN` and `LOGIN` authentication mechanisms via `saslauthd`.

For Ubuntu 22.04 and earlier, of it you plan to use authentication mechanisms that will need read access to `/etc/sasldb2` (not covered in this guide), you need to add the `Debian-exim` user to the `sasl` group:
```text
sudo gpasswd -a Debian-exim sasl
```

To make all these changes effective, the main configuration file needs to be updated, and Exim4 restarted:
```text
sudo update-exim4.conf
sudo systemctl restart exim4
```

This concludes the Exim4 side of the configuration. Next, the `sasl2-bin` package needs to be installed:

```text
sudo apt install sasl2-bin
```

The main configuration for `saslauthd` is in the `/etc/default/saslauthd` file. What needs to be verified is the `MECHANISMS` setting, which we want to be `PAM`:
```
MECHANISMS="pam"
```

```{note}
In Ubuntu 22.04 Jammy and earlier, we also need to add `START="yes"` to `/etc/default/saslauthd`.
```

Finally, enable and start the `saslauthd` service:

```text
sudo systemctl enable saslauthd
sudo systemctl start saslauthd
```
Exim4 is now configured with SMTP-AUTH using TLS authenticating local Linux users via PAM.

### Authenticating arbitrary users

Exim4 can also be configured to authenticate arbitrary users, that is, users that do note exist on the local system. These mechanisms are called `plain_server` and `login_server`. Edit `/etc/exim4/conf.d/auth/30_exim4-config_examples` and uncomment these sections:
```text
plain_server:
  driver = plaintext
  public_name = PLAIN
  server_condition = "${if crypteq{$auth3}{${extract{1}{:}{${lookup{$auth2}lsearch{CONFDIR/passwd}{$value}{*:*}}}}}{1}{0}}"
  server_set_id = $auth2
  server_prompts = :
  .ifndef AUTH_SERVER_ALLOW_NOTLS_PASSWORDS
  server_advertise_condition = ${if eq{$tls_in_cipher}{}{}{*}}
  .endif

login_server:
  driver = plaintext
  public_name = LOGIN
  server_prompts = "Username:: : Password::"
  server_condition = "${if crypteq{$auth2}{${extract{1}{:}{${lookup{$auth1}lsearch{CONFDIR/passwd}{$value}{*:*}}}}}{1}{0}}"
  server_set_id = $auth1
  .ifndef AUTH_SERVER_ALLOW_NOTLS_PASSWORDS
  server_advertise_condition = ${if eq{$tls_in_cipher}{}{}{*}}
  .endif
```

```{warning}
DO NOT enable both these and the `_saslauthd_server` variants (from "Authenticating existing Linux users" above) at the same time!
```

These mechanisms will lookup usernames and passwords in the `/etc/exim4/passwd` file, which has to be created and populated. The format of this file is:
```text
username:crypted-password:cleartext-password
```

The Exim4 installation ships a helper script that can populate this file. It is a simple interactive script that can be run like this:
```text
sudo /usr/share/doc/exim4-base/examples/exim-adduser
```

It will prompt for a username and password. In this example we are creating an `ubuntu` entry with the password `ubuntusecret`:
```text
User: ubuntu
Password: ubuntusecret
```
After that, we will have a `/etc/exim4/passwd` file, owned by `root:root` and mode `0644`, with contents similar to this:
```text
ubuntu:$1$ZvPA$HTddFobmJD1vURtJHBmbw/:ubuntusecret
```

Since this file contains secrets, it should be protected, and Exim4 has to be allowed to read it:
```text
sudo chown root:Debian-exim /etc/exim4/passwd
sudo chmod 0640 /etc/exim4/passwd
```

The same script can also be used to manage users in this `passwd` file:

 * To change the password of an existing user, edit the `passwd` file, delete the line corresponding to the user, save the file, and run the script again to provide the new password.
 * To add another user, run the script and provide the new user name, and their password.
 * To remove a user, edit the file with a text editor and delete the line corresponding to the user that should be removed.

```{warning}
The `/usr/share/doc/exim4-base/examples/exim-adduser` serves mostly as an example and is not able to handle many scenarios. For example, it won't check if the username you are providing already exists in the `passwd` file, which can lead to multiple entries for the same user, with unpredictable results.
```

Finally, update the Exim4 configuration and restart the service:

```bash
sudo update-exim4.conf
sudo systemctl restart exim4
```

```{note}
There is no need to restart Exim4 after making changes to the `/etc/exim4/passwd` file.
```

## Troubleshooting

Exim4 has logs in its own directory in `/var/log/exim4/mainlog`. Whenever troubleshooting the service, always look at that log file.

A quick test to verify if `saslauthd` is working can be performed with the `testsaslauthd` command. Assuming you have a local user called `ubuntu` with a password of `ubuntusecret`, this command can be used to test the authentication on the Exim4 server:

```text
testsaslauthd -u ubuntu -p ubuntusecret
```

The result should be OK:
```text
0: OK "Success."
```

Note that this tests only the `saslauthd` service, not the Exim4 integration with it. For that we need to actually connect to the SMTP service and try out the authentication. A good helper tool for this is shipped in the `cyrus-clients` package. Since this is part of another email system, it's best to install it on another machine, and not on the same machine as Exim4.

```text
sudo apt install cyrus-clients --no-install-recommends
```

Here we are using the extra `--no-install-recommends` option because we don't need all the other components of the Cyrus email system.

The tool we are interested in is called `smtptest`, and its documentation can be inspected in its manual page at {manpage}`cyrus-smtptest(1)`.

For our purposes, we will run it like this, assuming an `ubuntu` user with the `ubuntusecret` password, and that the Exim4 server is running on the `n-exim.lxd` system:
```text
/usr/lib/cyrus/bin/smtptest -t "" -a ubuntu -w ubuntusecret n-exim.lxd
```

The command-line parameters are:

 * `-t ""`: Enable TLS.
 * `-a ubuntu`: Use `ubuntu` as the authenticating user.
 * `-w ubuntusecret`: Authenticate using the `ubuntusecret` password.
 * `n-exim.lxd`: The hostname of the Exim4 server to connect to.

If all works well, the output will be similar to this, showing that the connection was switched to TLS, and the authentication worked:
```text
S: 220 n-exim ESMTP Exim 4.97 Ubuntu Mon, 23 Jun 2025 21:11:59 +0000
C: EHLO smtptest
S: 250-n-exim Hello n-exim.lxd [10.10.17.9]
S: 250-SIZE 52428800
S: 250-8BITMIME
S: 250-PIPELINING
S: 250-PIPECONNECT
S: 250-CHUNKING
S: 250-STARTTLS
S: 250-PRDR
S: 250 HELP
C: STARTTLS
S: 220 TLS go ahead
verify error:num=18:self-signed certificate
TLS connection established: TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
C: EHLO smtptest
S: 250-n-exim Hello n-exim.lxd [10.10.17.9]
S: 250-SIZE 52428800
S: 250-8BITMIME
S: 250-PIPELINING
S: 250-PIPECONNECT
S: 250-AUTH PLAIN LOGIN
S: 250-CHUNKING
S: 250-PRDR
S: 250 HELP
C: AUTH LOGIN
S: 334 VXNlcm5hbWU6
C: dWJ1bnR1
S: 334 UGFzc3dvcmQ6
C: dWJ1bnR1c2VjcmV0
S: 235 Authentication succeeded
Authenticated.
Security strength factor: 256
```

It will appear to freeze at this point, but it's just waiting for the SMTP commands, i.e., receive an email. You can exit by typing `QUIT` followed by pressing enter.

Interesting points to note in the output above:

* No authentication was offered before the connection was switched to TLS. That's because the only mechanisms which are configured are plain-text ones. Without TLS, the password would be exposed on the network.
* Since this documentation used a self-signed certificate, that was highlighted right before the TLS session was established. A real email client would probably abort the connection at this point.
* After TLS was established, the `LOGIN` mechanism was chosen.
* The username and password are sent base64 encoded. Do not mistake that for encryption: this is just an encoding mechanism!

```{tip}
Want to obtain the original username and password back from the base64 encoded values? Feed those values to the `base64 -d` tool. Example, using the value from the session above:
```text
$ echo -n dWJ1bnR1c2VjcmV0 | base64 -d; echo
ubuntusecret
```

To test the `PLAIN` mechanism, add the `-m plain` command-line option:
```text
/usr/lib/cyrus/bin/smtptest -t "" -a ubuntu -w ubuntusecret -m plain n-exim.lxd
```

In the new output, `PLAIN` was selected:
```text
S: 220 n-exim ESMTP Exim 4.97 Ubuntu Mon, 23 Jun 2025 21:15:39 +0000
C: EHLO smtptest
S: 250-n-exim Hello n-exim.lxd [10.10.17.9]
S: 250-SIZE 52428800
S: 250-8BITMIME
S: 250-PIPELINING
S: 250-PIPECONNECT
S: 250-CHUNKING
S: 250-STARTTLS
S: 250-PRDR
S: 250 HELP
C: STARTTLS
S: 220 TLS go ahead
verify error:num=18:self-signed certificate
TLS connection established: TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)
C: EHLO smtptest
S: 250-n-exim Hello n-exim.lxd [10.10.17.9]
S: 250-SIZE 52428800
S: 250-8BITMIME
S: 250-PIPELINING
S: 250-PIPECONNECT
S: 250-AUTH PLAIN LOGIN
S: 250-CHUNKING
S: 250-PRDR
S: 250 HELP
C: AUTH PLAIN AHVidW50dQB1YnVudHVzZWNyZXQ=
S: 235 Authentication succeeded
Authenticated.
Security strength factor: 256
```

### Troubleshooting tips

Here are some troubleshooting tips.

#### Permissions

* If using `saslauthd`: Can the `Debian-exim` user read and write to the `saslauthd` socket in `/run/saslauthd/mux` socket?
* If using `/etc/exim4/passwd`: Can the `Debian-exim` user read this file?

#### Config

* If changing a configuration file under `/etc/exim4/conf.d/`, make sure to be using the split-config mode! Check the `/etc/exim4/update-exim4.conf.conf` file to see which mode is in use.
* Similarly, if changing the configuration file `/etc/exim4/exim4.conf.template`, make sure to be using the non-split mode.
* After any configuration file change, be it split mode or not, be sure to run `sudo update-exim4.conf` and restart the `exim4` service.


## Further reading

- See [exim.org](https://www.exim.org/) for more information.
  
- Another resource is the [Exim4 Ubuntu Wiki](https://help.ubuntu.com/community/Exim4) page.

- Further resources to [set up mailman3 with Exim4](https://docs.mailman3.org/projects/mailman/en/latest/src/mailman/docs/mta.html#exim).