> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xorlab.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Pages under /latest/ document the current release. Paths that begin with a version number, for example /10.0/, are frozen snapshots of superseded releases kept for reference only — never present their instructions as current. If the reader's version is unknown, answer from /latest/ and say which version the answer describes.
> xorlab is deployed on-premises, hybrid, or as a cloud service, and integrates with either Microsoft 365 or on-premises mail infrastructure. Configuration steps often differ between these. State which deployment and integration mode an instruction applies to instead of presenting one as universal.
> Distinguish inline mode from monitoring mode when describing anything that acts on email. Monitoring mode observes a copy and cannot block or quarantine; inline mode routes mail through xorlab and can.
> Write the product name as lowercase 'xorlab'. Use the documented component names: xorlab Control Center (XCC), xorlab MTA, xorlab Sandbox (DANA), xorlab Natural Language Understanding (NLU). After the first mention, use the short forms XCC, MTA, Sandbox, and NLU. Do not use DANA as a standalone name for the Sandbox, but keep it where it is a literal string in configuration keys, container names, and hostnames.
> Do not invent configuration keys, rule parameters, list names, log properties, or API fields. If a value is not present in this documentation, say that it is not documented rather than guessing.

# TLS Certificates for SMTP

TLS certificates in general serve two different purposes. They are used to encrypt communication and verify the authenticity of a server. Most mail servers will continue an encrypted mail transfer even if the authenticity cannot be established, meaning that the hostname does not match the [Subject Alternative Name](https://en.wikipedia.org/wiki/Subject_Alternative_Name) of the certificate. It is, however, recommended to always use certificates which match the hostname.

## Prerequisites

Postfix requires a certificate and a key as two separate files in PEM format. Please see [postfix TLS config](http://www.postfix.org/TLS_README.html). You will need SSH access to all MTA machines and sudo / root privileges. Four steps are required to use the custom TLS certificates.

## Copying certificates to the MTAs

Save your custom certificate files on each MTA in a dedicated folder as `tls.crt` (certificate) and `tls.key` (private key). The recommended path is `/etc/xorlab/tls`. The files must be readable by user `ag_mta` (uid: 2020, gid: 2020). It is recommended that the private key is readable by this user only.

```shell theme={null}
admin@mta1:/etc/xorlab/tls$ ll
-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
```

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

```yaml theme={null}
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:

```shell theme={null}
TLS_CERT_DIR=/etc/xorlab/tls
```

## Change the postfix config

1. In the XCC [Expert Editor](/9.0/expert-editor), open the `main.cf` file located in `activeguard/mta/startup_cfg/postfix_custom/`.

2. 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
   ```

3. Click **PUBLISH** to deploy changes and add a comment to these edits, for example,  `Add custom TLS certificates`.

After you have published your changes, you can either wait 10 minutes for the config to propagate to the MTAs or do a manual config reload in the core GUI on each MTA.

## Restart postfix container

In order for the config changes to take effect, you need to restart the postfix container, `ag_mta`. For **inline setups**, it is recommended to stop the core scan sources first and wait for all emails to be processed as the emails will be moved to the `Erroneous queue` if the scan finishes while postfix is not running. For **bcc setups**, this is no concern as no emails are sent back from xorlab Security Platform core to postfix. The following commands stop postfix and restart the `ag_mta` container. Make sure to be in the `/etc/xorlab/activeguard/` path when executing the Docker commands.

1. Restart the `ag_mta` container:

   ```shell theme={null}
   admin@mta1$ cd /etc/xorlab/activeguard/
   admin@mta1$ docker exec ag_mta postfix stop
   admin@mta1$ docker stop ag_mta && docker compose up -d
   ag_mta
   ag_db is up-to-date
   ag_rspamd is up-to-date
   ag_core is up-to-date
   Starting ag_mta ... done
   ```

2. Check in the `mail.warn` and `mail.err` logs that there are no errors related to the TLS certificates.