→ Applies to: SynetoOS 6.x and above

An SSL/TLS certificate encrypts the connection between your browser and a server, and proves the server's identity by being issued and signed by a trusted Certificate Authority (CA). Browsers maintain a built-in list of trusted CAs — when a certificate is signed by one of them, the connection is marked secure with no warning.

SynetoOS ships with a self-signed certificate — one the appliance generates and signs for itself, rather than one issued by a recognized CA. This still encrypts traffic, but browsers can't verify the appliance's identity against a trusted CA, which is why they show a warning. Installing your own CA-issued certificate resolves this by replacing the self-signed one with a certificate your browser already trusts.

To address this, administrators should:

• Obtain a CA-issued certificate (full chain) and its matching unencrypted private key.
• Install and pin the certificate on the appliance, using either the supported tool or the manual procedure.
• Verify the certificate is served correctly and the browser warning is gone.

Ensure the following prerequisites are met before starting:

– Certificate (full chain): leaf (server) certificate followed by the issuing intermediate CA certificate(s), in a single PEM file, leaf first
– Private key: PEM format, unencrypted (no passphrase). RSA and ECDSA are both supported
– Certificate names (SAN): must include the hostname used to reach the appliance (e.g. syneto.example.com

Symptom

When opening the SynetoOS management UI, the browser shows a certificate warning (NET::ERR_CERT_AUTHORITY_INVALID, "connection is not secure", or similar). This occurs because the appliance ships with a self-signed certificate that no public CA vouches for.

The management UI is served by nginx, which reads its certificate and key from two fixed files on the appliance:

/etc/nginx/cert/server.crt
/etc/nginx/cert/server.key

NOTE
A built-in SynetoOS service automatically (re)generates a self-signed certificate into those files — at boot, on a periodic timer, and whenever the appliance's hostname or management IP changes.

IMPORTANT
Simply copying your own certificate over those files is not enough. The renewal service will overwrite it again, usually within minutes. SynetoOS provides a supported way to pin your own certificate so automatic renewal leaves it alone.

Step 1. Connect to SynetoOS appliance via SSH as admin

ssh admin@<your_ip_address_or_hostname>

Step 2. Get root privileges

sudo su -

Step 1. Run the decryption command

If you have an RSA key:

openssl rsa -in encrypted.key -out server.key

If you have an ECDSA key:

openssl ec -in encrypted.key -out server.key

Step 2. Enter the current passphrase when prompted

Enter pass phrase for encrypted.key:
writing RSA key

The resulting server.key file now contains your private key in plaintext, ready to use with the syneto-custom-ssl tool in place of your original encrypted key.

IMPORTANT
The server.key file is now unencrypted. Keep its permissions locked down (chmod 600 server.key) and do not share it — anyone with access to this file can use the key without a password

Installation Method 1 — Syneto-Custom-SSL Tool (Recommended)

This tool installs your certificate, pins it so automatic renewal cannot overwrite it, and installs a scheduled job that keeps it in place across reboots and OS upgrades. If your certificate expires, it automatically falls back to the self-signed certificate and logs a warning beforehand.

Step 1. Download the tool

curl -fsSL https://storage.googleapis.com/syneto_public_files/downloads/Syneto-Tools/SSL/syneto-custom-ssl.sh -o /tmp/syneto-custom-ssl.sh

Step 2. Install the tool

bash /tmp/syneto-custom-ssl.sh self-install

NOTE
self-install creates the working folders, records the appliance's current self-signed certificate as a fallback, and schedules the keep-in-place job. It verifies its own contents before installing anything.

Step 3. Install the certificate

syneto-custom-ssl upload \
  --cert /path/to/fullchain.pem \
  --key  /path/to/privkey.pem

NOTE
if your intermediates are in a separate file instead of being included in --cert, add --chain /path/to/intermediates.pem and the tool will assemble the full chain for you.
The tool validates the certificate and key (that they parse, match, and are not expired), installs and pins them, reloads nginx without interrupting the service (port 443 stays up; storage and data services are never touched), and confirms nginx is serving the new certificate.

Step 4. Verify the certificate status

syneto-custom-ssl status

Step 5. Verify from terminal

curl -sSI https://<your_ip_address_or_hostname>

EXAMPLE OUTPUT

HTTP/1.1 200 OK
...

Step 6. Log in to the SynetoOS GUI and verify the warning is gone

https://<your_ip_address_or_hostname>

IMPORTANT
Certificates expire, and renewal is your responsibility — the tool does not auto-renew. When you have a renewed certificate, run the same upload command again with the new files. The change is picked up immediately (or within 15 minutes via the scheduled job).
If a certificate is allowed to expire, the appliance automatically reverts to its self-signed certificate until you upload a renewed one. The tool also logs a warning (visible in the system journal) starting 30 days before expiry.

Step 7 (Optional). In case of errors, revert to your default certificate

syneto-custom-ssl restore-default --yes

Installation Method 2 — Manual Installation

Use this only if you'd rather not use the automated tool. The steps below reproduce by hand what syneto-custom-ssl does.

Step 1. Back up the current certificate

cp -a /etc/nginx/cert/server.crt /etc/nginx/cert/server.crt.bak

Step 2. Back up the current key

cp -a /etc/nginx/cert/server.key /etc/nginx/cert/server.key.bak

Step 3. Install the certificate chain

cp fullchain.pem /etc/nginx/cert/server.crt

Step 4. Install the private key

cp privkey.pem /etc/nginx/cert/server.key

Step 5. Set ownership and permissions

chown root:root /etc/nginx/cert/server.crt /etc/nginx/cert/server.key

chmod 644 /etc/nginx/cert/server.crt

chmod 600 /etc/nginx/cert/server.key

Step 6. Confirm the certificate and key match

openssl x509 -in /etc/nginx/cert/server.crt -noout -pubkey | openssl md5

openssl pkey -in /etc/nginx/cert/server.key -pubout        | openssl md5

IMPORTANT
the two hashes must be identical. If they aren't, the certificate and key don't match — do not proceed further.

Step 7. Pin the certificate

touch /etc/nginx/cert/server.keep

IMPORTANT
This step is mandatory. Without the /etc/nginx/cert/server.keep flag file, the appliance will regenerate a self-signed certificate over yours, usually within minutes.

Step 8. Validate nginx

nginx -t

Step 9. Reload nginx

nginx -s reload

This keeps port 443 up with no storage impact.

Important notes & limitations

• Provide the full chain: leaf certificate first, followed by all intermediate CA certificates, in the single server.crt file. The root CA is optional.
• You own renewal: while your certificate is pinned, SynetoOS does not auto-renew it. Re-apply a renewed certificate before it expires. (With the tool, an expired certificate automatically falls back to self-signed until you upload a new one.)
• Any public or private CA works: the appliance simply serves whatever chain you provide; trust is decided by the client's trust store, not the appliance.
• Hostname / management-IP changes: if you change the appliance's hostname or management IP, your certificate's names (SAN) will no longer match. Issue and install a new certificate for the new name. SynetoOS will not silently overwrite your custom certificate during such a change.
• Re-apply after a factory reset or OS reinstall: these operations restore the default certificate; re-run the install afterward. After a major OS upgrade, verify the certificate is still in place.
• Service impact: the certificate is applied with an nginx reload, which does not drop connections. nginx serves only the web UI/API; it does not touch storage, pools, or replication.

Troubleshooting

If a warning still appears after installation, confirm that the certificate name (SAN) matches the URL being used, and that the full intermediate chain is included.

What the Appliance Is Serving

Check what the appliance is actually serving, from a workstation:

echo | openssl s_client -connect <appliance>:443 -servername <name> 2>/dev/null | openssl x509 -noout -subject -issuer

syneto-custom-ssl upload \
    --cert /path/to/fullchain.pem \
    --key  /path/to/privkey.pem

touch /etc/nginx/cert/server.keep

openssl rsa -in encrypted.key -out server.key

syneto-custom-ssl upload \
    --cert /path/to/fullchain.pem \
    --key  server.key

cp server.key /etc/nginx/cert/server.key

chown root:root /etc/nginx/cert/server.key

chmod 600 /etc/nginx/cert/server.key

nginx -t

nginx -s reload

Rollback (Manual Installation)

If you need to revert the manual installation due to any error, follow these steps in order.

Step 1. Remove the pin flag file

rm /etc/nginx/cert/server.keep

Step 2. Restore the backed-up certificate

cp -a /etc/nginx/cert/server.crt.bak /etc/nginx/cert/server.crt

Step 3. Restore the backed-up key

cp -a /etc/nginx/cert/server.key.bak /etc/nginx/cert/server.key

Step 4. Reload nginx

nginx -s reload

NOTE
This restores the certificate and key you backed up in steps 1 and 2 of the manual installation (server.crt.bak / server.key.bak). If you skipped that backup step, you won't have these files to restore from — in that case, you can instead let SynetoOS regenerate a fresh self-signed certificate automatically once server.keep is removed.