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, 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-signal SIGINT --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).