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

  1. 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
    
  2. Check the presence of both files:

    sudo cyberwatch exec nginx ls -l /etc/nginx/ssl
    
    total 12
    -rw-r--r-- 1 root root  424 Aug 20 09:22 dhparams.pem
    -rw-r--r-- 1 1000 1000 1274 Aug 10 12:20 nginx.crt
    -rw-r--r-- 1 1000 1000 1705 Aug 10 12:20 nginx.key
    
  3. (Optional) Activate the HSTS header:

    Add the following line in the file /etc/cyberwatch/containers.env:

    ENABLE_HSTS="true"
    
  4. Restart Cyberwatch:

    sudo cyberwatch restart
    

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. If this kind of error occurs, follow the procedure below:

  1. Remove the nginx Docker volume:

     sudo docker volume rm cbwonpremise_data_ssl
    
  2. Restart Cyberwatch, with the volume removed, this will allow the nginx container to restart and generate a new self-signed certificate:

     sudo cyberwatch restart
    
  3. Follow the certificate configuration above from the start again.

With Kubernetes

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

    sudo cyberwatch restart