How to change Certificate on NGINX

NGINX reads a PEM certificate chain and private key from the paths named by ssl_certificate and ssl_certificate_key. Replacing the files is not enough: the configuration must pass validation and the master process must reload it.

Before you begin

• Obtain a PEM leaf certificate, intermediate chain, and matching unencrypted PEM private key. The ssl_certificate file must contain leaf first, followed by the intermediate certificates.
• Find every active reference with nginx -T, not only files in sites-enabled.
• Back up the current files, configuration, ownership, permissions, and symlink targets.
• On multiple nodes, drain and update one node at a time.

Step-by-step certificate replacement

1. Build and validate the materials in a root-only staging directory:

   cat leaf.pem intermediates.pem > fullchain.pem
   openssl x509 -in fullchain.pem -noout -subject -issuer -dates -ext subjectAltName
   openssl pkey -in private.key -pubout -outform pem | sha256sum
   openssl x509 -in leaf.pem -pubkey -noout -outform pem | sha256sum

   The final two hashes must match.

2. Install atomically. A versioned directory and symlink make rollback predictable:

   install -d -m 0700 /etc/nginx/tls/example-2026
   install -m 0644 fullchain.pem /etc/nginx/tls/example-2026/fullchain.pem
   install -m 0600 private.key /etc/nginx/tls/example-2026/private.key
   ln -sfn /etc/nginx/tls/example-2026 /etc/nginx/tls/example-current

3. Confirm the server block references the intended paths:

   ssl_certificate     /etc/nginx/tls/example-current/fullchain.pem;
   ssl_certificate_key /etc/nginx/tls/example-current/private.key;

   The key needs to be readable by the NGINX master process. It does not normally need to be readable by unrelated users. Account/permission requirements can differ for non-root or containerized NGINX.

4. Validate and reload:

   nginx -t
   systemctl reload nginx
   systemctl is-active nginx

   A successful reload starts new workers with the new files and gracefully retires old workers. Existing connections may finish on old workers; new handshakes should receive the replacement.

Product-specific considerations

SNI makes the tested hostname essential. Multiple server blocks can reference different certificates on the same address. SELinux or AppArmor can deny access even when Unix mode bits look correct; preserve labels with the distribution's normal certificate path or apply the approved policy/label rather than disabling enforcement.

Do not concatenate the root CA unless the issuing CA explicitly requires it. NGINX documents leaf-first chain order; the wrong order can produce a key mismatch error.

Verify the new certificate

openssl s_client -connect www.example.com:443 -servername www.example.com -showcerts </dev/null
journalctl -u nginx --since "10 minutes ago"

Compare the served fingerprint with openssl x509 -in leaf.pem -noout -fingerprint -sha256, and check the complete chain from outside every load balancer.

Rollback

Point the symlink back to the previous version, run nginx -t, and reload. If files were replaced in place, restore the backup with its original owner, mode, and label.

Common problems

• Leaf and private key do not match.
• Intermediates are missing or ordered before the leaf.
• NGINX is reloaded without first passing nginx -t.
• The tested request omits SNI and reaches the default server.
• A symlink changes but a container or chroot sees another filesystem path.

Automating certificate replacement with aethercert

The aethercert NGINX target writes the certificate chain and private key, applies private-key ownership/mode handling based on the NGINX configuration, and runs the configured reload command.

See Deploy targets for the fields this preset takes, what it needs on the host, and how far it has been verified.

Sources

• NGINX: configuring HTTPS servers
• NGINX: ngx_http_ssl_module