> ## 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.

# Replace MTA SMTP Certificate

> Replace the TLS certificate the MTA presents on SMTP connections.

<Warning>
  **Prerequisites**

  * New certificate and key available as two separate files in PEM format
  * We recommend that the certificate [SAN](https://en.wikipedia.org/wiki/Subject_Alternative_Name) matches the hostname
</Warning>

xorlab uses Postfix to handle SMTP connections. For additional information, have a look at the official [Postfix TLS documentation](http://www.postfix.org/TLS_README.html).

## Replace certificate

1. Copy the new certificate files as `tls.crt` (certificate) and `tls.key` (private key) into the folder `/etc/xorlab/tls`.
2. Execute the following commands to set the permission and ownership. The files need to be readable by user `ag_mta` (uid: 2020, gid: 2020):
   ```shell theme={null}
   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:
   ```shell theme={null}
   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
   ```
3. [Restart](/latest/operation-reference#start-and-stop) the MTA containers. This will lead to a 1-2 minute downtime, where the MTA does not accept emails:
   ```shell theme={null}
   cd /etc/xorlab/activeguard/ && docker compose down && docker compose up -d
   ```
4. 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/`:

```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](/latest/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/`:
   ```text theme={null}
   smtpd_tls_cert_file=/etc/ssl/custom/tls.crt
   smtpd_tls_key_file=/etc/ssl/custom/tls.key
   ```
3. 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.