Change the TLS certificate of Cyberwatch

Required format for the certificate and the key

The certificate and key must be in PEM format.

The key must not be encrypted.

This format is actually just a naming convention, the certificate and key files extension are not technically significant.

This indicates that the files required are text files, and that the certificate content must be encoded in base 64 and between by the following strings:

-----BEGIN CERTIFICATE-----
...encoded_certificate...
-----END CERTIFICATE-----

With Docker Swarm

Copy your new certificate to the nginx container:
```
docker cp myfile.crt $(docker ps -f name=cbwonpremise_nginx -q):/etc/nginx/ssl/nginx.crt
docker cp myfile.key $(docker ps -f name=cbwonpremise_nginx -q):/etc/nginx/ssl/nginx.key
```
The nginx.crt file contains the certificate, followed by the intermediate certificates if needed. There is no need to change the file permissions: at startup, Cyberwatch assigns them to the nginx container user and restricts access to them.
(Recommended) Activate the HSTS header:
Activating the HSTS header is recommended to strengthen connection security by enforcing the use of the HTTPS protocol.
Add the following line in the file /etc/cyberwatch/containers.env:
```
ENABLE_HSTS="true"
```
Restart Cyberwatch:
```
sudo cyberwatch restart
```

Check the files seen by the nginx container:

sudo cyberwatch exec nginx ls -l /etc/nginx/ssl

total 8
-rw-------    1 nginx    nginx         1274 Oct  6 09:22 nginx.crt
-rw-------    1 nginx    nginx         1705 Oct  6 09:22 nginx.key

The certificate issued by Cyberwatch, used by default, is renewed automatically at startup before it expires. However, Cyberwatch never replaces a certificate it did not issue: a warning is displayed at startup as its expiration date approaches, and a new certificate must then be installed by following this procedure.

Troubleshooting

In case Cyberwatch does not restart, it is possible to consult the nginx container logs using the following command:

sudo cyberwatch logs nginx -f

If a problem occurred when changing the certificate, an error should be present in these logs.

A bad certificate configuration can result in a crash of the nginx container. This container must be started to allow the certificate configuration, so it is first necessary to revert to a certificate issued by Cyberwatch:

Replace the installed certificate with a certificate issued by Cyberwatch:
```
sudo cyberwatch renew-certificates --force nginx-ssl
```
Restart Cyberwatch:
```
sudo cyberwatch restart
```
Follow the certificate configuration above from the start again

The cyberwatch renew-certificates command is available from version 5.32 of the orchestrator base.

With Kubernetes

Prerequisite: Cyberwatch must have been started at least one time
Replace files nginx.crt and nginx.key respectively by the TLS certificate and the private key in folder /var/lib/volumes/cyberwatch/ssl/
Restart Cyberwatch:
```
sudo cyberwatch restart
```

With Podman

This procedure applies starting with Podman orchestrator version 1.4, which stores the certificate presented by the web interface in the /etc/cyberwatch/ssl folder.

Copy the new certificate and the key to the /etc/cyberwatch/ssl folder, assigning them to the cyberwatch user that runs the containers:
```
sudo install -o cyberwatch -g cyberwatch -m 600 myfile.crt /etc/cyberwatch/ssl/nginx.crt
sudo install -o cyberwatch -g cyberwatch -m 600 myfile.key /etc/cyberwatch/ssl/nginx.key
```
The nginx.crt file contains the certificate, followed by the intermediate certificates if needed.
(Recommended) Activate the HSTS header by setting the ENABLE_HSTS variable to true in the /etc/cyberwatch/containers.env file:
```
ENABLE_HSTS='true'
```
Restart Cyberwatch:
```
sudo cyberwatch restart
```

Check the certificate presented by the web interface, on port 8443 by default:

openssl s_client -connect localhost:8443 </dev/null 2>/dev/null | openssl x509 -noout -subject -enddate

Troubleshooting with Podman

In case Cyberwatch does not restart, an error related to the certificate should appear in the nginx container logs:

sudo cyberwatch logs nginx -f

To revert to a self-signed certificate, delete the certificate and the key, then restart Cyberwatch. The nginx container then generates a new certificate:

sudo rm /etc/cyberwatch/ssl/nginx.crt /etc/cyberwatch/ssl/nginx.key
sudo cyberwatch restart