Replace MTA SMTP Certificate

Prerequisites

New certificate and key available as two separate files in PEM format
We recommend that the certificate SAN matches the hostname

xorlab uses Postfix to handle SMTP connections. For additional information, have a look at the official Postfix TLS documentation.

Replace certificate

Copy the new certificate files as tls.crt (certificate) and tls.key (private key) into the folder /etc/xorlab/tls.

Execute the following commands to set the permission and ownership. The files need to be readable by user ag_mta (uid: 2020, gid: 2020):

sudo chmod 400 tls.key
sudo chmod 644 tls.crt
sudo chown 2020:2020 tls.key
sudo chown 2020:2020 tls.crt

Then it should look like this:

admin@mta1:/etc/xorlab/tls$ ll
-rw-r--r-- 1 ag_mta ag_mta 3456 Dec  2 03:04 tls.crt
-r-------- 1 ag_mta ag_mta 1704 Dec  2 03:04 tls.key

Restart the MTA containers. This will lead to a 1-2 minute downtime, where the MTA does not accept emails:
cd /etc/xorlab/activeguard/ && docker compose down && docker compose up -d
Go to the folder /var/log/xorlab/activeguard/mta/ and check in the files mail.warn and mail.err that there are no errors related to the TLS certificates.

(Optional) Initial setup for older VMs

For older xorlab VMs, it may be required to reconfigure xorlab the first time before you can use the above procedure to replace certificates.

Change the docker config

In /etc/xorlab/activeguard/docker-compose.yml add a bind mount to the mta service to map the folder on the host containing the certificates files to the mta container. You are free to choose any path inside the container, however, do not choose /etc/ssl/my_certs as this directory will be overwritten by the internal config service. In this example, we will use /etc/ssl/custom/:

mta:
    image: ${XOR_REGISTRY}/ag/mta:${MTA_VERSION}
    container_name: ag_mta
    volumes:
      - $TLS_CERT_DIR:/etc/ssl/custom/                   # add this line

In /etc/xorlab/activeguard/.env set the $TLS_CERT_DIR variable:

TLS_CERT_DIR=/etc/xorlab/tls

Change the postfix config

In the XCC Expert Editor, open the main.cf file located in activeguard/mta/startup_cfg/postfix_custom/.
Set smtpd_tls_cert_file and smtpd_tls_key_file parameters based on the chosen path above, in this case /etc/ssl/custom/:
smtpd_tls_cert_file=/etc/ssl/custom/tls.crt smtpd_tls_key_file=/etc/ssl/custom/tls.key
Click Publish and add a comment to these edits, for example, Add custom TLS certificates.

The new Postfix setting becomes active within about one minute. If you do not want to wait, you can do a manual config reload in the MTA GUI on each MTA.

​Replace certificate

​(Optional) Initial setup for older VMs

​Change the docker config

​Change the postfix config

Replace certificate

(Optional) Initial setup for older VMs

Change the docker config

Change the postfix config