/// article
How to Check and Troubleshoot SSL Certificates in Zimbra
SSL certificate problems in Zimbra can affect more than the webmail login page. Zimbra uses certificates across several services, including the web proxy, mailbox service, LDAP, and MTA. An expired certificate, incorrect hostname, missing intermediate CA, or mismatched private key can cause browser warnings, TLS failures, and communication problems betwee...
SSL certificate problems in Zimbra can affect more than the webmail login page. Zimbra uses certificates across several services, including the web proxy, mailbox service, LDAP, and MTA. An expired certificate, incorrect hostname, missing intermediate CA, or mismatched private key can cause browser warnings, TLS failures, and communication problems between Zimbra components. Although SSL is still the common term administrators use, modern Zimbra connections normally use TLS. This guide explains how to inspect deployed Zimbra certificates, check expiration dates, verify certificate chains, confirm that a certificate belongs to its private key, inspect the certificate presented by a running server, and safely use zmcertmgr. It also distinguishes the certificate checks that were part of our Zimbra recovery case from general certificate administration procedures. What We Checked During Our Zimbra Recovery Case During our Zimbra troubleshooting and recovery work, certificate status was included as one of the dependency checks while investigating service failures, particularly problems involving mailboxd. The important point is that we did not determine that SSL certificates were the root cause of the recovery incident. Certificate checking was performed because Zimbra services such as mailboxd, proxy, LDAP, and other components depend on working certificate infrastructure. When troubleshooting a Zimbra server where several services are unhealthy, certificates should therefore be checked together with MySQL, Java, filesystem health, permissions, ports, configuration, and disk status. The certificate-related checks relevant to our case included: Checking the certificates deployed to Zimbra services. Reviewing certificate validity and expiration information. Confirming that Zimbra was able to recognize its deployed certificates. Considering certificate or keystore problems as a possible mailboxd dependency issue. The deeper certificate-chain reconstruction, private-key comparison methods, hostname verification, expiration monitoring, and live TLS testing described later in this article are general Zimbra administration recommendations. They should not be interpreted as failures that were discovered during our incident. 1. Check the Certificates Currently Deployed by Zimbra The first command I normally use is: su - zimbra /opt/zimbra/bin/zmcertmgr viewdeployedcrt Depending on your Zimbra installation, you should see certificate information for services such as: ::service mta:: notBefore=... notAfter=... subject=... issuer=... SubjectAltName=... ::service proxy:: ... ::service mailboxd:: ... ::service ldap:: ... viewdeployedcrt displays certificates that Zimbra has deployed to its local services. Zimbra documents support checking certificates for services including LDAP, mailboxd, MTA, and proxy. The command operates on the local server, so administrators of multi-server Zimbra environments should check each relevant node. Pay attention to four fields. notBefore This tells you when the certificate becomes valid. notAfter This is the certificate expiration date. subject This identifies the certificate holder. SubjectAltName The Subject Alternative Name, or SAN, contains the hostnames covered by the certificate. For example: SubjectAltName=mail.example.com, webmail.example.com If users connect using: https://mail.example.com then mail.example.com should normally appear in the certificate’s SAN. Modern certificate hostname validation relies on SAN when it is present. Zimbra’s certificate documentation also emphasizes including all required hostnames in Subject Alternative Names. 2. Check Certificate Expiration with zmcertmgr Zimbra provides a specific expiration check: /opt/zimbra/bin/zmcertmgr checkcrtexpiration all You can also check whether a certificate will expire within a specific number of days. For example: /opt/zimbra/bin/zmcertmgr checkcrtexpiration all -days 30 This is useful for monitoring because it gives you time to renew a certificate before users start receiving errors. The checkcrtexpiration function is part of Zimbra’s documented zmcertmgr certificate-management commands. I recommend checking certificates at least 30 days before expiration. For automated monitoring, you can also create alerts at thresholds such as: 30 days 14 days 7 days 3 days 1 day Do not wait for the certificate to expire before starting renewal. 3. Inspect a Certificate Directly with OpenSSL If you have the certificate file, OpenSSL can display its complete contents: openssl x509 \ -in certificate.crt \ -noout \ -text This shows information including: Subject Issuer Validity period Public key Signature algorithm Subject Alternative Names Key usage Extended key usage Certificate extensions OpenSSL officially documents openssl x509 as its X.509 certificate inspection and management command. For a shorter report: openssl x509 \ -in certificate.crt \ -noout \ -subject \ -issuer \ -dates \ -serial \ -fingerprint \ -sha256 A typical result might look like: subject=CN = mail.example.com issuer=C = US, O = Example CA, CN = Example Intermediate CA notBefore=Sep 1 00:00:00 2026 GMT notAfter=Nov 30 23:59:59 2026 GMT serial=... sha256 Fingerprint=... The -dates option prints both the notBefore and notAfter values, while -subject, -issuer, -serial, and -fingerprint provide useful identification information. 4. Check Whether a Certificate Is About to Expire OpenSSL can perform an expiration test that is useful in scripts. For example, check whether the certificate expires within the next 30 days: openssl x509 \ -in certificate.crt \ -noout \ -checkend 2592000 There are: 30 × 24 × 60 × 60 = 2,592,000 seconds OpenSSL returns a nonzero exit status if the certificate expires within the specified period. You can use this in a shell script: if openssl x509 -in certificate.crt -noout -checkend 2592000; then echo "Certificate is valid for more than 30 days." else echo "WARNING: Certificate expires within 30 days." fi 5. Check the Certificate Hostname A certificate can be perfectly valid and still generate warnings if it does not cover the hostname users actually access. With recent OpenSSL versions: openssl x509 \ -in certificate.crt \ -noout \ -checkhost mail.example.com OpenSSL provides -checkhost specifically for verifying whether a certificate matches a hostname. You can also inspect the SAN extension: openssl x509 \ -in certificate.crt \ -noout \ -ext subjectAltName For example: X509v3 Subject Alternative Name: DNS:mail.example.com, DNS:webmail.example.com A common mistake occurs after administrators change the Zimbra public hostname but continue using a certificate issued for the previous hostname. For example: Certificate: mail.example.com Users access: webmail.example.com Unless webmail.example.com is included in the certificate SAN, clients may report a hostname mismatch. 6. Verify That the Certificate Matches the Private Key A commercial certificate must correspond to the private key used when its CSR was created. Zimbra provides a convenient way to verify this. For example: /opt/zimbra/bin/zmcertmgr verifycrt comm \ /opt/zimbra/ssl/zimbra/commercial/commercial.key \ /tmp/commercial.crt \ /tmp/ca_chain.crt When everything matches, Zimbra should report that the certificate and private key match and that the certificate is valid. Zimbra documents verifycrt as a combination of private-key matching and certificate-chain verification. You can also test only the certificate and private key: /opt/zimbra/bin/zmcertmgr verifycrtkey \ /opt/zimbra/ssl/zimbra/commercial/commercial.key \ /tmp/commercial.crt This is especially important when certificates have been: Restored from backups. Copied from another server. Renewed manually. Migrated between servers. Mixed with files from an older certificate. If the certificate does not belong to the private key, deploying it will not fix the problem. Generic OpenSSL Key Comparison For a method that also works outside Zimbra, extract and hash the public key from both files. From the certificate: openssl x509 \ -in certificate.crt \ -pubkey \ -noout | openssl pkey \ -pubin \ -outform DER | openssl sha256 From the private key: openssl pkey \ -in private.key \ -pubout \ -outform DER | openssl sha256 The hashes should be identical. This method is preferable to old RSA-only modulus comparisons when you want a method that can also work with other supported key types. OpenSSL’s key tools can extract the public component of private keys, and OpenSSL provides APIs specifically for checking consistency between certificates and private keys. 7. Verify the Certificate Chain A certificate can be valid, unexpired, and matched to the correct private key while still failing in browsers or applications because its CA chain is incomplete. A typical chain looks like: Server Certificate | v Intermediate CA | v Root CA The server certificate is normally provided separately from the CA chain during Zimbra deployment. For example: /tmp/commercial.crt /tmp/ca_chain.crt Zimbra documents combining intermediate and root CA certificates into a CA-chain file before verification and deployment. For example: cat intermediate.crt root.crt > ca_chain.crt Then verify it with Zimbra: /opt/zimbra/bin/zmcertmgr verifycrt comm \ /opt/zimbra/ssl/zimbra/commercial/commercial.key \ commercial.crt \ ca_chain.crt Do this before deployment. 8. Verify the Chain with OpenSSL OpenSSL also provides a dedicated certificate verification command. For example: openssl verify \ -CAfile root.crt \ -untrusted intermediate.crt \ commercial.crt A successful result should look like: commercial.crt: OK OpenSSL documents openssl verify specifically for building and validating certificate chains. The -CAfile option supplies trusted certificates, while -untrusted supplies certificates that can be used during chain construction, such as intermediates. You can also display the chain OpenSSL built: openssl verify \ -show_chain \ -CAfile root.crt \ -untrusted intermediate.crt \ commercial.crt 9. Common CA-Chain Errors One of the most common certificate errors is: unable to get local issuer certificate Another is: unable to get issuer certificate These messages often indicate that OpenSSL or the application cannot construct a complete trust path from the server certificate to a trusted CA. Zimbra specifically documents depth lookup: unable to get issuer certificate as a problem commonly caused by missing CA files, often an intermediate or root certificate. Typical causes include: Missing intermediate CA certificate. Wrong intermediate CA. Old intermediate certificate retained after CA renewal. Certificate files combined incorrectly. Certificate issued by a different CA hierarchy than expected. Restored certificate files that do not belong together. Do not simply download a random certificate with the same CA name. Get the current intermediate and root CA certificates directly from your certificate authority and confirm their identities before deployment. 10. Inspect the Certificate Actually Presented to Users Checking files on disk does not prove that the running Zimbra service is presenting the same certificate. Test the actual HTTPS service: openssl s_client \ -connect mail.example.com:443 \ -servername mail.example.com \ -showcerts The -servername option is important when Server Name Indication, or SNI, is involved. Look for: Certificate chain subject= issuer= Verify return code: A healthy verification result normally shows: Verify return code: 0 (ok) OpenSSL documents s_client as a TLS diagnostic client. It can validate the server certificate and certificate chain against trusted CA certificates. You can retrieve only the certificate presented by the service: openssl s_client \ -connect mail.example.com:443 \ -servername mail.example.com \ </dev/null 2>/dev/null | openssl x509 \ -noout \ -subject \ -issuer \ -dates \ -fingerprint \ -sha256 This is very useful after renewing a Zimbra certificate. If the certificate file on disk shows the new certificate but this command still shows the old one, investigate which service is terminating TLS and whether the affected Zimbra services were properly reloaded or restarted. 11. Common SSL Symptoms in Zimbra Certificate problems can appear in several ways. Browser Certificate Warning Users may see warnings such as: Your connection is not private Possible causes include: Expired certificate. Untrusted certificate. Hostname mismatch. Missing intermediate CA. Self-signed certificate not trusted by the browser. Webmail Cannot Establish HTTPS The proxy or mailbox service may fail TLS negotiation. Check: zmcontrol status Then inspect relevant logs and certificate status. Do not assume every webmail failure is SSL related. Database failure, Java problems, proxy configuration, filesystem issues, port conflicts, and mailboxd failures can produce similar symptoms. Mail Clients Report Certificate Errors IMAP, POP, or SMTP clients may report: Certificate expired Certificate not trusted Hostname mismatch Unable to verify certificate Inspect the certificate presented by the actual service and port rather than checking only HTTPS. SMTP STARTTLS Problems Remote servers or mail clients can reject or warn about SMTP TLS if the MTA certificate is expired, incorrectly configured, or cannot establish the expected certificate chain. Check the MTA certificate with: /opt/zimbra/bin/zmcertmgr viewdeployedcrt mta Then test the actual SMTP endpoint when required. LDAP or Internal Service TLS Problems Zimbra components can communicate with LDAP and other internal services. Certificate problems can therefore affect internal connections as well as browser access. This is one reason certificate verification should be included when several Zimbra services fail together. However, correlation does not prove that the certificate caused the service failure. 12. Check Individual Zimbra Services Instead of displaying everything: /opt/zimbra/bin/zmcertmgr viewdeployedcrt you can inspect individual services where supported: /opt/zimbra/bin/zmcertmgr viewdeployedcrt ldap /opt/zimbra/bin/zmcertmgr viewdeployedcrt mailboxd /opt/zimbra/bin/zmcertmgr viewdeployedcrt mta /opt/zimbra/bin/zmcertmgr viewdeployedcrt proxy This can help you spot a situation where one Zimbra component is still using an older certificate. 13. Safe Use of zmcertmgr zmcertmgr can create, verify, stage, and deploy certificates. Treat deployment operations carefully on production systems. Before changing anything, inspect what is currently deployed: su - zimbra /opt/zimbra/bin/zmcertmgr viewdeployedcrt Check your installed version’s available options: /opt/zimbra/bin/zmcertmgr help Then verify the new certificate before deployment: /opt/zimbra/bin/zmcertmgr verifycrt comm \ /opt/zimbra/ssl/zimbra/commercial/commercial.key \ /tmp/commercial.crt \ /tmp/ca_chain.crt Only when verification succeeds should deployment be considered. A typical Zimbra commercial certificate deployment uses: /opt/zimbra/bin/zmcertmgr deploycrt comm \ /tmp/commercial.crt \ /tmp/ca_chain.crt Zimbra’s documentation shows that deploycrt comm installs the certificate into the locations required by Zimbra services, including components such as the MTA, LDAP, proxy, and mailbox keystore. After deployment, inspect the result: /opt/zimbra/bin/zmcertmgr viewdeployedcrt Zimbra documentation also calls for restarting Zimbra after certificate changes where required for the services to load the new certificate. For example: su - zimbra zmcontrol restart Then verify again: /opt/zimbra/bin/zmcertmgr viewdeployedcrt Finally, test the certificate exposed over the network: openssl s_client \ -connect mail.example.com:443 \ -servername mail.example.com \ </dev/null Do not consider the job complete simply because deploycrt finished without an obvious error. 14. Back Up the Existing Certificate Configuration First Before replacing certificates on an important Zimbra server, make a protected backup of the current certificate files. For example, as root: mkdir -p /root/zimbra-cert-backup cp -a /opt/zimbra/ssl/zimbra \ /root/zimbra-cert-backup/ You may also want to preserve related CA configuration relevant to your Zimbra version. Restrict access: chmod 700 /root/zimbra-cert-backup Remember that certificate directories can contain private keys. Never copy private keys into: /tmp public Git repositories shared documentation support tickets chat systems public web directories unless you fully understand the security consequences. A leaked private key should be treated as compromised. 15. Recommended Zimbra SSL Troubleshooting Sequence When troubleshooting a Zimbra certificate problem, I recommend following this order: 1. Check Zimbra service status | v 2. View deployed certificates | v 3. Check expiration | v 4. Check hostname and SAN | v 5. Verify certificate and private key | v 6. Verify CA chain | v 7. Inspect certificate presented by live service | v 8. Check Zimbra logs | v 9. Back up existing certificate configuration | v 10. Deploy only after verification succeeds | v 11. Restart or reload affected Zimbra services | v 12. Test externally again Useful initial commands are: su - zimbra zmcontrol status /opt/zimbra/bin/zmcertmgr viewdeployedcrt /opt/zimbra/bin/zmcertmgr checkcrtexpiration all -days 30 Then inspect the certificate: openssl x509 \ -in certificate.crt \ -noout \ -subject \ -issuer \ -dates Verify it: /opt/zimbra/bin/zmcertmgr verifycrt comm \ private.key \ certificate.crt \ ca_chain.crt Finally, test the live endpoint: openssl s_client \ -connect mail.example.com:443 \ -servername mail.example.com \ -showcerts This sequence helps separate four different questions: Is the certificate valid? Is it the correct certificate? Does it belong to the private key? Is the running service actually presenting it? Those are different checks. A certificate can pass one and fail another. 16. A Certificate Problem Is Not Always an SSL Problem This was particularly important in our recovery case. A failed Zimbra web interface does not automatically mean the HTTPS certificate is broken. Before replacing certificates, also check: zmcontrol status and investigate: mailboxd status MySQL availability LDAP availability Zimbra proxy status Java processes listening ports filesystem state available disk space file permissions Zimbra configuration system logs Zimbra logs Certificate replacement should be based on evidence. If: zmcertmgr viewdeployedcrt shows a valid certificate, zmcertmgr verifycrt passes, and: openssl s_client shows the expected certificate with successful verification, the certificate is probably not where you should spend most of your troubleshooting time. That was the reason certificate verification was useful during our Zimbra recovery. It helped us check and eliminate one possible dependency problem while continuing investigation into the other unhealthy Zimbra components. Command Reference View all deployed certificates /opt/zimbra/bin/zmcertmgr viewdeployedcrt Check certificates expiring within 30 days /opt/zimbra/bin/zmcertmgr checkcrtexpiration all -days 30 Inspect a certificate openssl x509 -in certificate.crt -noout -text Show certificate dates openssl x509 -in certificate.crt -noout -dates Check hostname openssl x509 \ -in certificate.crt \ -noout \ -checkhost mail.example.com Check expiration within 30 days openssl x509 \ -in certificate.crt \ -noout \ -checkend 2592000 Verify Zimbra certificate, key, and CA chain /opt/zimbra/bin/zmcertmgr verifycrt comm \ private.key \ certificate.crt \ ca_chain.crt Verify certificate chain using OpenSSL openssl verify \ -CAfile root.crt \ -untrusted intermediate.crt \ certificate.crt Test live HTTPS certificate openssl s_client \ -connect mail.example.com:443 \ -servername mail.example.com \ -showcerts References Zimbra Tech Center, Administration Console and CLI Certificate Tools: Zimbra Certificate and zmcertmgr Documentation Zimbra Tech Center, Self-Signed CA SSL Certificate: Zimbra Self-Signed Certificate Documentation Zimbra Tech Center, Fix depth lookup: unable to get issuer certificate: Zimbra CA Chain Troubleshooting Zimbra Tech Center, Regenerate Self-Signed SSL Certificate, Single Server: Zimbra Certificate Regeneration Guide OpenSSL Documentation, openssl-x509: OpenSSL X.509 Documentation OpenSSL Documentation, openssl-verify: OpenSSL Certificate Verification Documentation OpenSSL Documentation, openssl-s_client: OpenSSL TLS Client Documentation