Automated letsencrypt/certbot certificate deploy script for Zimbra hosts.
The script tweaks zimbra's nginx config to allow access of .well-known webserver location from local files instead of redirecting upstream to jsp. So it may not be used if there's no zimbra-nginx package installed.
Letsencrypt by default tries to verify a domain using https, so the script should work fine if zimbraReverseProxyMailModes is set to both or https. May not work for http only.
This is still a BETA script. Tested on:
- zimbra-proxy package is required (for !https mode)
- of course either
letsencryptbinary is required
The preferred way is to install it is by using the wizard at certbot's home. Choose None of the above as software and your operating system. This will allow you to install easily upgradable system packages.
By installing Certbot via packages it automatically creates a cron schedule to renew certificates. We must disable this schedule because after the renew we must deploy it in Zimbra. So open
/etc/cron.d/certbot with your favourite editor and comment the last line.
- The script doesn't handle multiple certificates on the same server. See #8 and #17
Zimbra 8.7 single server
it should do everything by itself, including restarting zimbra.
EFF suggest to run renew twice a day. Since this would imply restarting zimbra, once a day outside workhours should be fine. So in your favourite place (like
/etc/cron.d/zimbracrontab) schedule the commands below, as suitable for your setup:
12 5 * * * root /usr/bin/certbot renew --pre-hook "/usr/local/bin/certbot_zimbra.sh -p" --renew-hook "/usr/local/bin/certbot_zimbra.sh -r -d $(/opt/zimbra/bin/zmhostname)"
--pre-hook ensures Zimbra's nginx is patched to allow certificate verification. You can omit it if you remember to manually execute that command after an upgrade or
a reinstall which may restore nginx's templates to their default.
--renew-hook parameter has been added since certbot 0.7.0, so check your version before using it. If it's not supported you should get a workaround, but probably the easiest way is to upgrade it.
-d option is required in order to avoid domain confirmation prompt by the script.
Renewal using Systemd
The example below uses the renew-hook which will only rerun the script if a renewal was successfull and thus only reloading zimbra when needed.
Create a service file eg: /etc/systemd/system/renew-letsencrypt.service
[Unit] Description=Renew Let's Encrypt certificates After=network-online.target [Service] Type=oneshot # check for renewal, only start/stop nginx if certs need to be renewed ExecStart=/usr/bin/certbot renew --quiet --agree-tos --pre-hook "/usr/local/bin/certbot_zimbra.sh -p" --renew-hook "/usr/local/bin/certbot_zimbra.sh -r -d $(/opt/zimbra/bin/zmhostname)"
Create a timer file to run the above once a day at 2am: /etc/systemd/system/renew-letsencrypt.timer
[Unit] Description=Daily renewal of Let's Encrypt's certificates [Timer] # once a day, at 2AM OnCalendar=*-*-* 02:00:00 # Be kind to the Let's Encrypt servers: add a random delay of 0–3600 seconds RandomizedDelaySec=3600 Persistent=true [Install] WantedBy=timers.target
Then reload the unit file with
systemctl daemon-reload systemctl start renew-letsencrypt.timer systemctl enable renew-letsencrypt.timer
Check the timers status:
systemctl list-timers renew-letsencrypt.timer
If you have another webserver in front
(It may happen even in the best families)
Say you have apache in front of zimbra (or listening on port 80 only) just run
certbot-auto to request the certificate for apache, and when done run
/usr/local/bin/certbot_zimbra.sh --renew --no-nginx
so that it will deploy the certificate in zimbra without patching nginx.
Creating a patch
Since v0.2 patches are embedded into the script. To produce a patch:
- make a fresh zimbra installation
- make a copy of the vanilla
cp -r /opt/zimbra/conf/nginx/templates /opt/zimbra/conf/nginx/templates_ORIG)
- patch the templates file by adding the
.well-known/acme-challengelocation with a webroot (see existing patches)
- produce a patchfile, making sure to have only one directory below:
cd /opt/zimbra/conf/nginx/ ; diff -Naur templates_ORIG templates > /tmp/zimbra_YOURVERSION.patch
- embed the patch in the patches section
- add the version condition in
Upgrade from v0.1
If you originally requested the certificate with the first version of the script, which used standalone method, newer version will fail to renew. This because it now uses webroot mode by patching Zimbra's nginx, making it more simple to work and to mantain.
To check if you have the old method, run
grep authenticator /etc/letsencrypt/renewal/YOURDOMAIN.conf. If it says standalone you got it!
To get it back working, @andrewmur on issue #43 suggests to stop (and kill, to make sure) nginx before renewal. This is proven to work (by him).
A more definitive solution would be to try forcing the issue of a new certificate in webroot mode, so that it will work with newver versions of the scripts. But this is untested. ;)
Disclaimer of Warranty
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
© Lorenzo Milesi email@example.com
Feedback, bugs, PR are welcome on GitHub.