Enterprise

# Set up TLS

> Start a Synnax Core that encrypts every connection with a TLS certificate.

A Synnax Core started without `--insecure` encrypts every connection with TLS. It needs a certificate for the name that clients use to reach it.

That name is the host in `--listen`, such as `synnax.example.com` in `--listen=synnax.example.com:9090`. The Core binds the port on all network interfaces, whatever the host is. The host must be a name or address that clients can reach, so do not use `0.0.0.0`. Use `localhost` only when every client runs on the same computer.

`--insecure` turns off TLS only. Users still log in.

## Choose a certificate

| Certificate                                                                                             | Use it when                                         | Clients                                                                                                                |
| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
| [Self-signed](https://docs.synnaxlabs.com/reference/enterprise/tls#use-a-self-signed-certificate)       | You have no certificate authority.                  | Each client computer must [install the CA certificate](https://docs.synnaxlabs.com/reference/enterprise/certificates). |
| [From your organization](https://docs.synnaxlabs.com/reference/enterprise/tls#use-your-own-certificate) | Your organization issues certificates to its hosts. | Computers that already trust your organization’s CA need nothing.                                                      |
| [From a public CA](https://docs.synnaxlabs.com/reference/enterprise/tls#use-your-own-certificate)       | The Core has a public DNS name.                     | Clients trust it already.                                                                                              |

## Use a self-signed certificate

1. Start the Core with `--auto-cert`:

   ```bash
   synnax start --listen=synnax.example.com:9090 --auto-cert
   ```

   The Core creates a certificate authority (CA) and a certificate for the `--listen` host. It writes `ca.crt`, `ca.key`, `node.crt`, and `node.key` to `/usr/local/synnax/certs`. To use a different folder, set `--certs-dir`.

2. [Install `ca.crt`](https://docs.synnaxlabs.com/reference/enterprise/certificates) on each client computer.

The certificate covers only the `--listen` host. It does not cover `localhost` or other names of the computer. If you change the host, the next start replaces `node.crt` and `node.key` with a pair signed by the same CA, so clients need no new CA certificate.

> `--auto-cert` replaces a `node.crt` that does not cover the `--listen` host, that `ca.crt` did not sign, or whose subject matches its issuer, even one you supplied. Do not use it with your own certificate.

In Docker, the certificate folder is inside the container. Mount a volume at `/usr/local/synnax/certs`, or a new container makes a new CA and every client must install it again:

```bash
docker run --name synnax -p 9090:9090 --mac-address 02:5a:00:00:00:01 \
  -v synnax-data:/synnax/synnax-data -v synnax-certs:/usr/local/synnax/certs \
  synnaxlabs/synnax --listen=synnax.example.com:9090 --auto-cert
```

To create the files without starting the Core, run `synnax cert ca`, then `synnax cert node synnax.example.com`. `synnax cert node` does not replace files that exist.

## Use your own certificate

1. Put the certificate and its private key, both in PEM format, in one folder. The certificate must cover the `--listen` host.

2. Start the Core with the folder and the two file names:

   ```bash
   synnax start --listen=synnax.example.com:9090 \
     --certs-dir=/etc/synnax/certs --node-cert=synnax.crt --node-key=synnax.key
   ```

If the certificate does not cover the host, the Core does not start. It logs an error such as `serves a certificate that does not cover that host; no client can verify it: x509: certificate is valid for localhost, not synnax.example.com`.

The Core needs no CA files for your own certificate. When you replace the certificate files, the Core uses the new files for the next connection, with no restart.

### Example: Let’s Encrypt

Get a certificate for the domain with [Certbot](https://certbot.eff.org/). The domain must have a public DNS record. The Core then reads the files in place, in `/etc/letsencrypt/live/<domain>`.

The Core serves a renewed certificate at once. Its embedded Driver and its sessions keep the files the Core read at start, so restart the Core after each renewal. Certbot runs each program in `/etc/letsencrypt/renewal-hooks/deploy` after a renewal.

**Linux**

For a Core that runs as the `synnax` user, as in [Run the Core as a service](https://docs.synnaxlabs.com/reference/enterprise/service):

1. Let the `synnax` group read the private key. Certbot keeps the group and mode at each renewal:

   ```bash
   sudo chmod 0755 /etc/letsencrypt/live /etc/letsencrypt/archive
   sudo chgrp synnax /etc/letsencrypt/live/synnax.example.com/privkey.pem
   sudo chmod 0640 /etc/letsencrypt/live/synnax.example.com/privkey.pem
   ```

2. Start the Core with the Certbot files. Do not use `--auto-cert`:

   ```bash
   synnax start --listen=synnax.example.com:9090 \
     --certs-dir=/etc/letsencrypt/live/synnax.example.com \
     --node-cert=fullchain.pem --node-key=privkey.pem
   ```

3. Restart the Core after each renewal:

   ```bash
   printf '#!/bin/sh\nsystemctl restart synnax\n' \
     | sudo tee /etc/letsencrypt/renewal-hooks/deploy/restart-synnax
   sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/restart-synnax
   ```

**Docker**

The Core in the image runs as user and group `65532`.

1. Let group `65532` read the private key. Certbot keeps the group and mode at each renewal:

   ```bash
   sudo chmod 0755 /etc/letsencrypt/live /etc/letsencrypt/archive
   sudo chgrp 65532 /etc/letsencrypt/live/synnax.example.com/privkey.pem
   sudo chmod 0640 /etc/letsencrypt/live/synnax.example.com/privkey.pem
   ```

2. Mount all of `/etc/letsencrypt` read-only, so the links in `live` resolve, and start the Core with the Certbot files. Do not use `--auto-cert`:

   ```bash
   docker run -d --name synnax -p 9090:9090 --mac-address 02:5a:00:00:00:01 \
     --stop-timeout 30 \
     -v synnax-data:/synnax/synnax-data -v /etc/letsencrypt:/etc/letsencrypt:ro \
     synnaxlabs/synnax --listen=synnax.example.com:9090 \
     --certs-dir=/etc/letsencrypt/live/synnax.example.com \
     --node-cert=fullchain.pem --node-key=privkey.pem
   ```

3. Restart the container after each renewal:

   ```bash
   printf '#!/bin/sh\ndocker restart synnax\n' \
     | sudo tee /etc/letsencrypt/renewal-hooks/deploy/restart-synnax
   sudo chmod +x /etc/letsencrypt/renewal-hooks/deploy/restart-synnax
   ```

## Connect to the Core

* **Console** -> when you add the Core, turn on **Secure**. See [Connect the Console](https://docs.synnaxlabs.com/reference/enterprise/console#add-a-core).
* **Browser** -> use `https://`, for example `https://synnax.example.com:9090`.
* **Client libraries** -> set `secure` to true. See [Connect with TLS](https://docs.synnaxlabs.com/reference/client/connect#connect-with-tls).

For more than one address with different certificates, see [Serve multiple listeners](https://docs.synnaxlabs.com/reference/enterprise/listeners).
