Category:Community Sandbox: Difference between revisions

(Replaced content with "Use this page to identify user pages, notes, rants, ideas, questions, and other Zimbra related community material. '''''Note:''' Technical articles about Zimbra products...")
 
(23 intermediate revisions by the same user not shown)
Line 1: Line 1:
=JDunphy Letsencrypt - Another Method Using acme.sh to Generate Certs=
Use this page to identify user pages, notes, rants, ideas, questions, and other Zimbra related community material.
{{KB|{{Unsupported}}|{{ZCS 8.8}}|{{ZCS 8.7}}|{{ZCS 8.6}}|}}
{{WIP}}
= Introduction =
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)=
# Install acme.sh bash script in your home directory. Ref: https://github.com/Neilpang/acme.sh
<pre>
% curl https://get.acme.sh | sh
Or:
% wget -O -  https://get.acme.sh | sh
</pre>


Note: This will do three things.
'''''Note:''' Technical articles about Zimbra products that are not part of a User Page or page of notes should not be labeled with this category.''
# create a directory ~/.acme.sh
# update your .cshrc and .bashrc so that script is in your path
# 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 acme.sh script supports all challenge methods but for this article we will focus on the Automatic DNS challenge. See https://github.com/Neilpang/acme.sh for other methods or my own documentation https://github.com/JimDunphy/deploy-zimbra-letsencrypt.sh/tree/master/Recipies/SingleServer which lists 3 different type of DNS methods. All challenge methods that acme.sh 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 '''~/.acme.sh/account.conf''' to contain your DNS provider api key. A list of supported DNS providers can be found at ~/.acme.sh/dnsapi. 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 '''~/.acme.sh/account.conf file'''
 
# SAVED_CF_Key= '......Your API key..........'
# CF_EMAIL='XXXX@example.com'
 
From now on, anytime we need a certificate or renew a certificate we can do the following:
<pre>
acme.sh --issue --dns dns_cf -d mail.example.com
</pre>
If we have multiple domains associated with our Zimbra server, then it works like this:
<pre>
acme.sh --issue --dns dns_cf -d mail.example.com -d mail.example.net -d mail.example.org
</pre>
Wild card certs are supported with ACME v2 protocol
<pre>
acme.sh --issue --dns dns_cf -d example.com -d '*.example.com'
</pre>
Your certificates can be found at: ~/.acme.sh/mail.example.com ... 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 acme.sh bash script, the following commands will install it. Note: I have also created a script to perform these steps automatically at https://github.com/JimDunphy/deploy-zimbra-letsencrypt.sh and the forums have a thread on this method https://forums.zimbra.org/viewtopic.php?f=15&t=60781 for additional background information. For this article we walk through those steps.
 
= Step 1 (Append IdentTrust CERT to fullchain) =
<pre>
cd ~/.acme.sh/mail.example.com
echo '-----BEGIN CERTIFICATE-----
MIIDSjCCAjKgAwIBAgIQRK+wgNajJ7qJMDmGLvhAazANBgkqhkiG9w0BAQUFADA/
MSQwIgYDVQQKExtEaWdpdGFsIFNpZ25hdHVyZSBUcnVzdCBDby4xFzAVBgNVBAMT
DkRTVCBSb290IENBIFgzMB4XDTAwMDkzMDIxMTIxOVoXDTIxMDkzMDE0MDExNVow
PzEkMCIGA1UEChMbRGlnaXRhbCBTaWduYXR1cmUgVHJ1c3QgQ28uMRcwFQYDVQQD
Ew5EU1QgUm9vdCBDQSBYMzCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEB
AN+v6ZdQCINXtMxiZfaQguzH0yxrMMpb7NnDfcdAwRgUi+DoM3ZJKuM/IUmTrE4O
rz5Iy2Xu/NMhD2XSKtkyj4zl93ewEnu1lcCJo6m67XMuegwGMoOifooUMM0RoOEq
OLl5CjH9UL2AZd+3UWODyOKIYepLYYHsUmu5ouJLGiifSKOeDNoJjj4XLh7dIN9b
xiqKqy69cK3FCxolkHRyxXtqqzTWMIn/5WgTe1QLyNau7Fqckh49ZLOMxt+/yUFw
7BZy1SbsOFU5Q9D8/RhcQPGX69Wam40dutolucbY38EVAjqr2m7xPi71XAicPNaD
aeQQmxkqtilX4+U9m5/wAl0CAwEAAaNCMEAwDwYDVR0TAQH/BAUwAwEB/zAOBgNV
HQ8BAf8EBAMCAQYwHQYDVR0OBBYEFMSnsaR7LHH62+FLkHX/xBVghYkQMA0GCSqG
SIb3DQEBBQUAA4IBAQCjGiybFwBcqR7uKGY3Or+Dxz9LwwmglSBd49lZRNI+DT69
ikugdB/OEIKcdBodfpga3csTS7MgROSR6cz8faXbauX+5v3gTt23ADq1cEmv8uXr
AvHRAosZy5Q6XkjEGB5YGV8eAlrwDPGxrancWYaLbumR9YbK+rlmM6pZW87ipxZz
R8srzJmwN0jP41ZL9c8PDHIyh8bwRLtTcm1D9SZImlJnt1ir/md2cXjbDaJWFBM5
JDGFoqgCWjBH4d1QB7wCCZAA62RjYJsWvIjJEubSfZGL+T0yjWW06XyxV3bqxbYo
Ob8VZRzI9neWagqNdwvYkQsEjgfbKbYK7p2CNTUQ
-----END CERTIFICATE-----' >> fullchain.cer
</pre>
Because zmcertmgr will chdir during install which can abort when permissions are incorrect in some circumstances, we do the following.
<pre>
% cd ~.acme.sh/mail.example.com
% cp mail.example.com.key mail.example.com.cer fullchain.cer /tmp
</pre>
 
= 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 =
<pre>
% su - zimbra
% cd /tmp
% /opt/zimbra/bin/zmcertmgr verifycrt comm mail.example.com.key mail.example.com.cer fullchain.cer
</pre>
 
If there were no errors, you can install the certificate
 
= Step 3 Install your certificate =
<pre>
% su - zimbra
% cd /tmp
% cp mail.example.key /opt/zimbra/ssl/zimbra/commercial/commercial.key
% /opt/zimbra/bin/zmcertmgr deploycrt comm mail.example.cer fullchain.cer
</pre>
 
If there were no errors, proceed to restart zimbra
 
= Step 4 Restart Zimbra =
<pre>
% su - zimbra
% zmcontrol restart
</pre>
 
= All in One Method =
Once you understand how to issue your certificates and install acme.sh, you can use the --deploy and --deploy-hook options and have acme.sh perform the zimbra installation for you. '''This method requires you install acme.sh as the zimbra user'''.  ''Versions prior to 8.7, need to modify the hook script below so that the two zmcertmgr commands are run as root.''
 
#Copy the hook script below to /opt/zimbra/.acme.sh/deploy/zimbra.sh
<pre>
#!/bin/bash
 
# Zimbra Assumptions:
#    1) acme.sh is installed as Zimbra
#    2) see: https://wiki.zimbra.com/wiki/index.php?curid=2441
 
########  Public functions #####################
 
#domain keyfile certfile cafile fullchain
zimbra_deploy() {
  _cdomain="$1"
  _ckey="$2"
  _ccert="$3"
  _cca="$4"
  _cfullchain="$5"
 
  _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 "https://ssl-tools.net/certificates/dac9024f54d8f6df94935fb1732638ca6ad77c13.pem" -O "$_IdentTrust" || return 1
  fi
 
  # 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
  cp -f "$_ckey" /opt/zimbra/ssl/zimbra/commercial/commercial.key
  /opt/zimbra/bin/zmcertmgr deploycrt comm "$_ccert" "${_cca}.real" || return 1
  /opt/zimbra/bin/zmmailboxdctl reload
  /opt/zimbra/bin/zmproxyctl reload
  /opt/zimbra/bin/zmmtactl reload
  return 0
}
</pre>
Complete example:
<pre>
% su - zimbra
% cd .acme.sh
% acme.sh --issue --dns dns_cf -d mail.example.com -d mail.example.net -d mail.example.org
% acme.sh --issue --deploy --deploy-hook zimbra --dns dns_cf -d mail.example.com -d mail.example.net -d mail.example.org
</pre>
Subsequent renewals are performed as:
<pre>
% acme.sh --issue --deploy --deploy-hook zimbra --dns dns_cf -d mail.example.com -d mail.example.net -d mail.example.org
</pre>
 
Note: You initially need to issue your cert the very first time without the --deploy/--deploy-hook if the -d mail.example.com directory doesn't previously exist in /opt/zimbra/.acme.sh/ (It's your very first time).  You also don't need to worry about the IdentTrust.pem certificate concatenation as the deploy-hook does this. The hook will be called on successful certificate verification and restart/reload zimbra.
= Notes  =
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.
<pre>
% 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
</pre>

Latest revision as of 15:02, 1 July 2019

Use this page to identify user pages, notes, rants, ideas, questions, and other Zimbra related community material.

Note: Technical articles about Zimbra products that are not part of a User Page or page of notes should not be labeled with this category.

Subcategories

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)

K

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