Replace a TLS Certificate for Any Linux Service

This guide covers any Linux service that reads certificate and key files - a mail server, a directory server, a Java application or your own daemon. The service's own documentation decides the format, the paths, who must be able to read the key, and whether a reload rereads the certificate. The steps below are the safe frame around it.

Before you beginCopy Anchor Link

• Identify the process, its systemd unit, the configuration directives that name the certificate and key, and the account it runs as (systemctl show -p User <unit>, or ps -o user= -p <pid>).
• Check whether it runs in a chroot or container, where paths differ from the host.
• Record the current paths, owner, mode and symlink targets (ls -lL), and keep the current files: the steps below put the new ones in a new directory.

Step-by-step certificate replacementCopy Anchor Link

1. Find the format in the service's documentation, and convert if needed:

   The service expects	How to produce it
   Separate certificate, chain and key (PEM)	Use the files as delivered
   Full chain (server certificate first) and key	cat leaf.pem intermediates.pem > fullchain.pem
   One file with chain and key	cat leaf.pem intermediates.pem private.key > bundle.pem
   PKCS#12	openssl pkcs12 -export -in leaf.pem -certfile intermediates.pem -inkey private.key -out cert.p12
   Java keystore	keytool -importkeystore -srckeystore cert.p12 -srcstoretype PKCS12 -destkeystore keystore.jks

2. Check names, dates, chain and key:

   Copy Text

   openssl x509 -in leaf.pem -noout -subject -enddate -ext subjectAltName
   openssl verify -untrusted intermediates.pem leaf.pem
   openssl pkey -in private.key -pubout | sha256sum
   openssl x509 -in leaf.pem -noout -pubkey | sha256sum

   openssl verify must print OK; the two hashes must be identical.

3. Install with the right permissions into a new directory:

   Copy Text

   install -d -m 0750 -g <service-group> /etc/myservice/tls/2026
   install -m 0644 fullchain.pem /etc/myservice/tls/2026/fullchain.pem
   install -m 0640 -g <service-group> private.key /etc/myservice/tls/2026/private.key
   restorecon -Rv /etc/myservice/tls/2026   # SELinux systems only

   If the service reads the key as root before dropping privileges, 0600 root:root is enough. If it reads the key as its own account, that account (or its group) needs read access - as above. Never make a private key world-readable.

4. Switch the symlink the configuration points to, and test the configuration with the service's own check, if it has one (for example postfix check, nginx -t):

   Copy Text

   ln -sfn /etc/myservice/tls/2026 /etc/myservice/tls/current

   The running process is not affected by the switch until it reloads, so testing after the switch is safe. If the test fails, point the symlink back.

5. Activate: use systemctl reload <unit> if the service rereads its certificate on reload (its documentation says so), otherwise systemctl restart <unit>. With several nodes, do one at a time and check it before the next.

Verify the new certificateCopy Anchor Link

Check the served certificate with a client that speaks the protocol:

openssl s_client -connect service.example.com:443 -servername service.example.com </dev/null   # HTTPS / TLS
openssl s_client -connect mail.example.com:25  -starttls smtp </dev/null   # SMTP STARTTLS
openssl s_client -connect mail.example.com:143 -starttls imap </dev/null   # IMAP STARTTLS
openssl s_client -connect ldap.example.com:389 -starttls ldap </dev/null   # LDAP StartTLS

Check subject and SAN, issuer, expiry date and the chain, on each node directly and through the public address. Also check the service's log for TLS errors.

RollbackCopy Anchor Link

Point the symlink back to the previous directory, test, and reload or restart the same way. Keep the old directory until the new certificate has been verified.

Common problemsCopy Anchor Link

• The service expects a different format or chain order.
• The file is correct on the host but not visible inside a chroot or container.
• Owner, mode, ACL or SELinux label prevents the service from reading the key.
• A reload does not make this service reread its certificate - restart it.
• The service resolves the symlink only at start and keeps the old target until a restart.

Automating certificate replacement with aethercertCopy Anchor Link

The aethercert Custom Linux target writes certificate, chain, and key material to the configured paths and can run an administrator-supplied reload command. The command and paths must match the service's documented behavior.

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

SourcesCopy Anchor Link

• OpenSSL: s_client
• OpenSSL: verify
• systemd: systemctl