Category:Community Sandbox

Revision as of 14:29, 10 May 2019 by JDunphy (talk | contribs) (All in One Method (Simplest))

JDunphy Letsencrypt - Another Method Using to Generate Certs

   KB 2441        Last updated on 2019-05-10  

(0 votes)


Letsencrypt is a free, automated, and open Certificate Authority to generate all your PKI certificates so a browser can see & display that trusted green secure lock for your domains. Instead of installing a development environment like other Letsencrypt methods, this article describes a single bash script and can be installed and operated without being root. Here is how to get Zimbra up and running with your Letsencrypt certificate.

Requirements (1 time only)

  1. Install bash script in your home directory. Ref:
% curl | sh
% wget -O - | sh

Note: This will do three things.

  1. create a directory ~/
  2. update your .cshrc and .bashrc so that script is in your path
  3. create a cron job for the local user for automatic renewal

Issue Your Certificate

Letsencrypt needs to verify you have control of your domains before they will sign your certificate. To do that, we complete a challenge and prove we have control of the domains using their acme protocol. The script supports all challenge methods but for this article we will focus on the Automatic DNS challenge. See for other methods or my own documentation which lists 3 different type of DNS methods. All challenge methods that supports work with this article including --standalone/--tls if you prefer an alternative to the DNS method described here.

When using the Automatic DNS Method for the first time, you will need to update ~/ to contain your DNS provider api key. A list of supported DNS providers can be found at ~/ In this article we will use CloudFlare. Login to your CloudFlare account to get your API key before proceeding and then add these 2 lines to your ~/ file

  1. SAVED_CF_Key= '......Your API key..........'
  2. CF_EMAIL=''

From now on, anytime we need a certificate or renew a certificate we can do the following: --issue --dns dns_cf -d

If we have multiple domains associated with our Zimbra server, then it works like this: --issue --dns dns_cf -d -d -d 

Wild card certs are supported with ACME v2 protocol --issue --dns dns_cf -d -d '*'

Your certificates can be found at: ~/ ... It uses the first '-d' name to create a directory to store your certificates

Install Certificate With Zimbra

Regardless of which challenge method you used with the bash script, the following commands will install it. Note: I have also created a script to perform these steps automatically at and the forums have a thread on this method for additional background information. For this article we walk through those steps.

Step 1 (Append IdentTrust CERT to fullchain)

cd ~/ 
echo '-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----' >> fullchain.cer

Because zmcertmgr will chdir during install which can abort when permissions are incorrect in some circumstances, we do the following.

% cd
% cp fullchain.cer /tmp

Note: For version 8.7 and above, zmcertmgr runs as zimbra. For all earlier versions you will run zmcertmgr as root. Example below is for 8.7 and 8.8 versions.

Step 2 Verify your certificate

% su - zimbra
% cd /tmp
% /opt/zimbra/bin/zmcertmgr verifycrt comm fullchain.cer

If there were no errors, you can install the certificate

Step 3 Install your certificate

% su - zimbra
% cd /tmp
% cp mail.example.key /opt/zimbra/ssl/zimbra/commercial/commercial.key
% /opt/zimbra/bin/zmcertmgr deploycrt comm fullchain.cer

If there were no errors, proceed to restart zimbra

Step 4 Restart Zimbra

% su - zimbra
% zmcontrol restart

All in One Method (Simplest)

Once you understand how to issue your certificates and install, you can use the --deploy and --deploy-hook options and have perform the zimbra installation for you. This method requires you install and run the bash script as the zimbra user and will also handle the identTrust intermediate certificate for you during your certificate installation to zimbra. Note: If you leave the crontab entry, all subsequent renewals including the loading of the certificate with zimbra will happen automatically for future unattended renewals approximately every 60 days. Versions prior to 8.7, need to modify the hook script below so that the two zmcertmgr commands are run as root.

  1. Copy the hook script below to /opt/zimbra/ You can also get it from here:

# Zimbra Assumptions:
#    1) is installed as Zimbra
#    2) see:

########  Public functions #####################

#domain keyfile certfile cafile fullchain
zimbra_deploy() {

  _debug _cdomain "$_cdomain"
  _debug _ckey "$_ckey"
  _debug _ccert "$_ccert"
  _debug _cca "$_cca"
  _debug _cfullchain "$_cfullchain"

  # Zimbra's javastore still needs DST Root CA X3 to verify on some versions
  _IdentTrust="$(dirname "$_cca")/../IdentTrust.pem"
  _debug _IdentTrust "$_IdentTrust"

  # grab it if we don't have it
  if [ ! -f "$_IdentTrust" ]; then
     _debug No "$_IdentTrust"
     wget -q "" -O "$_IdentTrust" || return 1

  # append Intermediate 
  cat "$_cfullchain" "$(dirname "$_cca")/../IdentTrust.pem" > "${_cca}.real"
  /opt/zimbra/bin/zmcertmgr verifycrt comm "$_ckey" "$_ccert" "${_cca}.real" || return 1

  #if it verifies we can deploy it
  /bin/logger -p NETWORK "Certificate has been Renewed for $_cdomain"
  cp -f "$_ckey" /opt/zimbra/ssl/zimbra/commercial/commercial.key
  /opt/zimbra/bin/zmcertmgr deploycrt comm "$_ccert" "${_cca}.real" || return 1

  # %%% ldap wasn't being restarted leading to failed communication in the future if we hadn't done a restart.
  # Adding a ldap restart was not tested so perhaps. Reload is restart when not defined by zimbra with
  # exception of ldap which they didn't provide a reload.
  #/opt/zimbra/bin/ldap restart
  #/opt/zimbra/bin/zmmailboxdctl reload
  #/opt/zimbra/bin/zmproxyctl reload
  #/opt/zimbra/bin/zmmtactl reload

  /opt/zimbra/bin/zmcontrol restart
  return 0

Complete example including installation of bash script.

% su - zimbra
% wget -O - | sh
% cd

issue the certificates

% --issue --dns dns_cf -d -d -d 

install the certificates

% --issue --deploy --deploy-hook zimbra --dns dns_cf -d -d -d
% --deploy --deploy-hook zimbra -d

Note: if you get an error attempting to install as the zimbra user, do this as /opt/zimbra is owned by root. Switch to root before switching back to zimbra. Here is an example:

% su -
# cd /opt/zimbra/
# mkdir
# chown zimbra:zimbra
# su - zimbra
% cd
% wget -O - | sh

Subsequent issues or renewals are performed automatically every 60 days via a cron entry for but could be done manually like this (issue the cert and if successful then deploy the certificate):

% su - zimbra
% --issue --dns dns_cf -d -d -d 
% --deploy --deploy-hook zimbra -d 

Note: You don't need to worry about the IdentTrust.pem certificate described above as the deploy-hook handles this automatically including its fetch. The hook will be called on your successful certificate verification and restart/reload zimbra. If it fails to renew the certificate, the hook will not be called. While the automatic dns method is shown above, any of the challenge methods that supports can be used.

Pro Tip: look into the --challenge-alias option with the automatic DNS method to further isolate/secure your zone updates with letsencrypt. You only require a CNAME entry for your trusted zimbra domains for the domains above. In other words, each letsencrypt secured zimbra domain would have this in their zone file. Same entry for every one.

_acme-challenge           IN CNAME

where is a completely different and managed zone and not a zimbra domain. It can be any of the supported automatic DNS providers including BIND directly.

Here is how this would look using the CNAME alias where,, and are not managed by CF (cloudflare) but we want to secure for zimbra:

% su - zimbra
% --issue --dns dns_cf --challenge-alias -d -d -d 
% --issue --deploy --deploy-hook zimbra --dns dns_cf -d -d -d


Zimbra has 4 major daemons that require certificates. nginx, ldap, postfix, and mailboxd... Below is where zmcertmgr installs the certificate. Because mailboxd is java based, it uses a keystore. Note: /opt/zimbra/ssl contains your certificates. The other locations are copies from here. Further: nginx, ldap, and postfix can reload those new certificates hot without shutting down the services so in theory we are performing a restart because mailboxd and taking an outage during certificate renewal.

% ls -lt /opt/zimbra/conf/slapd.*
-rw-r----- 1 zimbra zimbra 7213 Aug  4 10:46 slapd.crt
-rw-r----- 1 zimbra zimbra 1679 Aug  4 10:46 slapd.key
% ls -lt /opt/zimbra/ssl/zimbra/commercial
-rw-r----- 1 zimbra zimbra 5030 Aug  4 10:46 commercial_ca.crt
-rw-r----- 1 zimbra zimbra 7213 Aug  4 10:46 commercial.crt
-rw-r----- 1 zimbra zimbra 1679 Aug  4 10:46 commercial.key
% ls -lt /opt/zimbra/conf/nginx.???
-rw-r----- 1 zimbra zimbra 7213 Aug  4 10:46 /opt/zimbra/conf/nginx.crt
-rw-r----- 1 zimbra zimbra 1679 Aug  4 10:46 /opt/zimbra/conf/nginx.key
%  -l /opt/zimbra/conf/smtpd.???
-rw-r----- 1 zimbra zimbra 7213 Aug  4 10:46 /opt/zimbra/conf/smtpd.crt
-rw-r----- 1 zimbra zimbra 1679 Aug  4 10:46 /opt/zimbra/conf/smtpd.key
% ls -l /opt/zimbra/mailboxd/etc/keystore
-rw-r----- 1 zimbra zimbra 4965 Aug  4 10:46 /opt/zimbra/mailboxd/etc/keystore
% ls -l /opt/zimbra/ssl/zimbra/jetty.pkcs12
-rw-r----- 1 zimbra zimbra 6952 Aug  4 10:46 /opt/zimbra/ssl/zimbra/jetty.pkcs12

Bad Certificate Recovery

Should you receive an error with your new certificates because they were not validated correctly you can recover by re-issuing your certificate and then re-install to zimbra. Should zimbra not allow you to re-install the corrected certificates, issue a self signed as a quick workaround before proceeding to re-install your corrected letsencrypt certs. Ref: Ref:

Confirm that your SSL certs are all valid and not-expired

% /opt/zimbra/bin/zmcertmgr viewdeployedcrt all

- ldap: /opt/zimbra/conf/slapd.crt
notBefore=Oct 27 18:10:32 2018 GMT
notAfter=Jan 25 18:10:32 2019 GMT
subject= /
issuer= /C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X3,,
- mailboxd: /opt/zimbra/mailboxd/etc/mailboxd.pem
notBefore=Oct 27 18:10:32 2018 GMT
notAfter=Jan 25 18:10:32 2019 GMT
subject= /
issuer= /C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X3,,
- mta: /opt/zimbra/conf/smtpd.crt
notBefore=Oct 27 18:10:32 2018 GMT
notAfter=Jan 25 18:10:32 2019 GMT
subject= /
issuer= /C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X3,,
- proxy: /opt/zimbra/conf/nginx.crt
notBefore=Oct 27 18:10:32 2018 GMT
notAfter=Jan 25 18:10:32 2019 GMT
subject= /
issuer= /C=US/O=Let's Encrypt/CN=Let's Encrypt Authority X3,, can also tell you when renewal would occur if you have this automated via the supplied crontab entry.

./ --list
Main_Domain   KeyLength  SAN_Domains                                                                                                              Created                                      Renew       ""                                                              Sat Mar 16 14:13:39 UTC 2019  Wed May 15 14:13:39 UTC 2019        "",                                              Sat Mar 16 14:15:08 UTC 2019  Wed May 15 14:15:08 UTC 2019       "",,,                   Sat Mar 16 14:30:40 UTC 2019  Wed May 15 14:30:40 UTC 2019


This category has the following 2 subcategories, out of 2 total.

Pages in category "Community Sandbox"

The following 200 pages are in the current category.

(previous page) (next page)


(previous page) (next page)
Jump to: navigation, search