certbot-zimbra

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 an ALPHA script, UNTESTED. The basic idea should work, but errors or typos are possible and it may not complete successfully, leaving your system in a unknown state.

The previous version was tested on:

• 8.7.11_UBUNTU16
• 8.7.11_RHEL7
• 8.6_RHEL7
• 8.6_UBUNTU12

Requirements

• zimbra-proxy package is required (for !https mode)
• of course either certbot or letsencrypt binary is required

Certbot installation

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.

Installing Certbot via the system's package mananger will automatically create 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.

Limitations

• The script doesn't handle multiple certificates on the same server. See #8 and #17

Usage

Zimbra 8.7 single server

Run ./certbot_zimbra.sh it should do everything by itself, including restarting zimbra.

Renewal

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 (crontab -u root -e, /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 -d"

This will run the --renew-hook only if a renewal was actually carried out, in order to deploy the renewed certificates and restart Zimbra.

The --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.

The --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.

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 -n --pre-hook "/usr/local/bin/certbot_zimbra.sh -p" --renew-hook "/usr/local/bin/certbot_zimbra.sh -d"

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 --deploy --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:

1. make a fresh zimbra installation
2. make a copy of the vanilla /opt/zimbra/conf/nginx/templates location (i.e. cp -r /opt/zimbra/conf/nginx/templates /opt/zimbra/conf/nginx/templates_ORIG)
3. patch the templates file by adding the .well-known/acme-challenge location with a webroot (see existing patches)
4. 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
5. embed the patch in the patches section
6. add the version condition in patch_nginx function

License

See LICENSE.

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.

Original Author

© Lorenzo Milesi maxxer@yetopen.it

Forked from: yetopen/certbot-zimbra.

Contributions

© 2018 Jernej Jakob jernej.jakob@gmail.com