KB
SSL & Certificates

SSL Renewal for Zimbra Server

4 min read828 words13 code blocks

At a glance#

  • Purpose: Install a renewed commercial SSL certificate on a Zimbra Collaboration Suite mail server.
  • Applies to: Zimbra Collaboration Suite 8.x and 9.x.
  • Risk: High — a failed deployment stops mail services; a full restart is required.
  • Time: About 45 minutes including restart.

Overview#

Zimbra manages its own certificate store under /opt/zimbra/ssl/zimbra/commercial/ and uses the zmcertmgr tool to validate and deploy certificates. The certificate protects webmail, IMAP, POP, SMTP and the admin console — so a mistake here takes down mail entirely, not just the web interface.

The process has three stages: place the files with the exact names Zimbra expects, verify the chain, then deploy and restart.

Warning: Deployment requires a full Zimbra restart, which interrupts all mail services for several minutes. Schedule a maintenance window.

Required file names#

Zimbra is strict about naming. Files must be placed in /opt/zimbra/ssl/zimbra/commercial/ with exactly these names:

FileContents
commercial.keyPrivate key — already on the server from when the CSR was generated
commercial.crtThe newly issued certificate for your domain
commercial_ca.crtThe intermediate CA chain
Warning: Do not overwrite commercial.key or commercial.csr. The existing private key is the one the certificate was issued against. Replacing it makes the new certificate unusable and there is no way to recover it.

Before you start#

  • Root access to the Zimbra server.
  • The renewed certificate and CA bundle from the certificate authority.
  • A maintenance window agreed.
  • Confirmation that the renewal was issued against the existing CSR. If a new CSR was generated, the matching key is on whichever machine created it.

Back up the current certificate directory#

Always. This is your rollback.

bash
sudo cp -a /opt/zimbra/ssl/zimbra /opt/zimbra/ssl/zimbra.bak-$(date +%F)

Check the current certificate and its expiry#

bash
sudo /opt/zimbra/bin/zmcertmgr viewdeployedcrt

Procedure#

1. Copy the new certificate files onto the server#

Upload the files, then move them into place with the required names:

bash
sudo cp your-domain.crt      /opt/zimbra/ssl/zimbra/commercial/commercial.crt
sudo cp your-domain-ca.crt   /opt/zimbra/ssl/zimbra/commercial/commercial_ca.crt

If the CA supplied several separate intermediate files, concatenate them into one, ordered from the intermediate nearest your certificate outwards to the root:

bash
cat intermediate.crt root.crt | sudo tee /opt/zimbra/ssl/zimbra/commercial/commercial_ca.crt

2. Set ownership and permissions#

Zimbra runs as the zimbra user and cannot read files owned by root:

bash
sudo chown zimbra:zimbra /opt/zimbra/ssl/zimbra/commercial/commercial.crt
sudo chown zimbra:zimbra /opt/zimbra/ssl/zimbra/commercial/commercial_ca.crt
sudo chmod 640 /opt/zimbra/ssl/zimbra/commercial/*

3. Verify the certificate and key match#

This is the checkpoint. Do not proceed if it fails.

bash
sudo /opt/zimbra/bin/zmcertmgr verifycrt comm \
  /opt/zimbra/ssl/zimbra/commercial/commercial.key \
  /opt/zimbra/ssl/zimbra/commercial/commercial.crt \
  /opt/zimbra/ssl/zimbra/commercial/commercial_ca.crt

Expected output:

text
** Verifying commercial.crt against commercial.key
Certificate (commercial.crt) and private key (commercial.key) match.
Valid Certificate: commercial.crt: OK
Warning: If verification fails, stop. Deploying an unverified certificate leaves Zimbra unable to start its services. Common causes are covered in Troubleshooting below.

4. Deploy the certificate#

bash
sudo /opt/zimbra/bin/zmcertmgr deploycrt comm \
  /opt/zimbra/ssl/zimbra/commercial/commercial.crt \
  /opt/zimbra/ssl/zimbra/commercial/commercial_ca.crt

This copies the certificate into Zimbra's keystores for each service.

5. Restart Zimbra#

Switch to the zimbra user — these commands will not work as root:

bash
sudo su - zimbra
zmcontrol restart

A full restart takes 3–5 minutes. Watch for any service reporting as not running.

Check overall status:

bash
zmcontrol status

Every service should show Running.

Verification#

Confirm the deployed certificate is the new one:

bash
sudo /opt/zimbra/bin/zmcertmgr viewdeployedcrt

Check the expiry date has moved forward.

Test the live services from another machine — the web interface and the mail protocols each present the certificate separately:

bash
# Webmail
openssl s_client -connect mail.example.com:443 -servername mail.example.com

# IMAPS
openssl s_client -connect mail.example.com:993

# SMTP with STARTTLS
openssl s_client -connect mail.example.com:25 -starttls smtp

Look for Verify return code: 0 (ok) in each. Anything else usually means an incomplete chain.

Finally, log in to webmail in a browser and confirm the padlock shows the new expiry date.

Rollback#

If mail services fail to start after deployment:

bash
sudo su - zimbra -c "zmcontrol stop"
sudo rm -rf /opt/zimbra/ssl/zimbra
sudo cp -a /opt/zimbra/ssl/zimbra.bak-YYYY-MM-DD /opt/zimbra/ssl/zimbra
sudo su - zimbra -c "zmcontrol start"

Troubleshooting#

SymptomCause and fix
Certificate and private key do not matchThe certificate was issued against a different CSR. Compare moduli: `openssl x509 -noout -modulus -in commercial.crt \
Cannot verify certificate chainIntermediates missing or in the wrong order. Rebuild commercial_ca.crt with the intermediate first, root last.
Permission denied from zmcertmgrFile ownership is wrong. Re-run step 2.
Services will not start after deployBad certificate deployed. Roll back as above, then investigate.
Browser reports untrusted issuerCA bundle incomplete. Test with openssl s_client and check the chain depth.
zmcontrol: command not foundYou are running as root. Switch first with sudo su - zimbra.
Webmail correct but mail clients still warnSome services cache the old certificate. Do a full zmcontrol restart, not a reload.