Install and configure Exim4

Install Exim4

To install Exim4, run the following command:

sudo apt install exim4

Configure Exim4

To configure Exim4, run the following command:

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:

/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:

sudo update-exim4.conf

The update-exim4.conf command will update the autogenerated 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:

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:

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:

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:

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 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:

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:

sudo gpasswd -a Debian-exim sasl

To make all these changes effective, the main configuration file needs to be updated, and Exim4 restarted:

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:

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:

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:

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:

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:

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:

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:

ubuntu:$1$ZvPA$HTddFobmJD1vURtJHBmbw/:ubuntusecret

Since this file contains secrets, it should be protected, and Exim4 has to be allowed to read it:

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:

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:

testsaslauthd -u ubuntu -p ubuntusecret

The result should be OK:

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.

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 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:

/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:

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 hang 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 connnection 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:

$ echo -n dWJ1bnR1c2VjcmV0 | base64 -d; echo
ubuntusecret

To test the PLAIN mechanism, add the -m plain command-line option:

/usr/lib/cyrus/bin/smtptest -t "" -a ubuntu -w ubuntusecret -m plain n-exim.lxd

In the new output, PLAIN was selected:

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.

References

• See exim.org for more information.

• Another resource is the Exim4 Ubuntu Wiki page.

• Further resources to set up mailman3 with Exim4.