Prerequisites

• A domain name and a Let's Encrypt certificate for the website's domain. You can create one quickly in EzySupport at **Load balancing** > **Nginx** by selecting the domain and setting up SSL (EzySupport runs `certbot --nginx` for that domain; certbot must be installed and a contact email entered at **Load balancing** > **Certbot** first). Alternatively, run certbot on the server yourself.
• Once the certificate is issued, certbot creates these files:
  • /etc/letsencrypt/live/<domain>/cert.pem
  • /etc/letsencrypt/live/<domain>/privkey.pem
• openssl and keytool must be on the PATH of the user running the Admin server. keytool ships with the JDK.
• Read permission on /etc/letsencrypt/live and /etc/letsencrypt/archive. By default only root can read these directories. If the Admin server does not run as root, grant read access to its user, otherwise the conversion step will fail.
• Open port 2812 on the firewall / security group.

Configure in the EzySupport admin

• Save: only saves the two paths, does not create the keystore.
• Reload: saves the two paths, creates the keystore from the certificate and enables Websocket SSL. On success, a dialog appears with a link to the Socket dashboard.

Tip: if some clients (Android, Java, ...) fail to verify the certificate, use fullchain.pem instead of cert.pem so the keystore also contains the intermediate certificates.

Restart the Socket server

Update the websocket URL

wss://<domain>:2812/ws

• Enable Websocket SSL: already enabled by EzySupport during the Reload step.
• Allow SSL To Reload Automatically: enabled by default. Keep it enabled so the Socket server picks up the new keystore when the certificate is renewed.
• SSL certificate password, SSL keystore file, SSL keystore password: no need to enter them manually, EzySupport has already generated them.

Automatic update on certificate renewal

1. At the top of the Socket settings page, on the Socket SSL keystore reloader row, click the start button to run the reloader. It is not running by default.
2. The reloader checks the last modified time of the cert pem file roughly every 1.5 seconds. When the file is newer than the last processed one, it recreates the keystore, the same as clicking Reload.
3. The Socket server checks the keystore file every 5 seconds (when Allow SSL To Reload Automatically is enabled). When the keystore changes, the Socket server loads the new SSL context without a restart.

How it works

1. Generates a random 32-character password if absent and stores it in the socket/settings/ssl directory of the EzyPlatform installation:
   • ssl-keystore-password.txt
   • ssl-certificate-password.txt
   If the keystore password was just generated, the old keystore file is deleted so it can be recreated.
2. Converts the PEM certificate to PKCS12:

   openssl pkcs12 -export -in <cert pem> -inkey <private key> \
        -out socket/settings/ssl/certificate.p12 -name "certificate" \
        -passout pass:<certificate password>
   

3. Imports the PKCS12 into the Socket server keystore:

   yes | keytool -importkeystore \
        -srckeystore socket/settings/ssl/certificate.p12 -srcstoretype pkcs12 \
        -srcstorepass <certificate password> \
        -destkeystore socket/settings/ssl/ssl-keystore.txt \
        -deststorepass <keystore password>
   

4. If the command exits with a non-zero code, reports an error and stops. On success, writes websocket.ssl.enable=true to socket/settings/config.properties (if not already enabled).

ssl.keystore=ssl/ssl-keystore.txt
ssl.keystore_password=ssl/ssl-keystore-password.txt
ssl.certificate_password=ssl/ssl-certificate-password.txt

Troubleshooting

• Reload fails: check the Admin server log. EzySupport logs the executed commands along with the stdout/stderr output of openssl and keytool. Common causes:
  • Wrong path or no read permission on the cert pem / private key file.
  • openssl or keytool not found on the PATH.
• SSL is enabled but clients cannot connect via wss://: check that the Socket server has been restarted, port 2812 is open, and Websocket URL has been changed to wss://<domain>:2812/ws.
• The certificate was renewed but the websocket still uses the old one: check that the Socket SSL keystore reloader is running and Allow SSL To Reload Automatically is enabled. You can also click Reload manually to recreate the keystore immediately.
• To change the passwords: clear the contents of ssl-keystore-password.txt and ssl-certificate-password.txt, then click Reload. New passwords and a new keystore will be generated.

Notes

• You must open port 2812 or whichever ports you use for WebSocket connections.
• The certificate password and keystore password appear in the commands written to the Admin server log. Restrict access to the log files.
• Avoid editing ssl-keystore.txt manually while the Socket server is running. Any change to this file makes the Socket server reload SSL.