From 5a30e50ec60e032d2c53d52dab765ad1f12e4bce Mon Sep 17 00:00:00 2001 From: Lorenzo Milesi Date: Tue, 4 Sep 2018 16:28:48 +0200 Subject: [PATCH] Updated documentation --- README.md | 48 ++++++++++++++++++++++++++++++++++++----------- certbot_zimbra.sh | 2 +- 2 files changed, 38 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 03a1901..4848f98 100644 --- a/README.md +++ b/README.md @@ -13,22 +13,47 @@ This is still a BETA script. Tested on: # Requirements -* zimbra-proxy package is required (for !*https* mode) -* of course either `certbot` or `letsencrypt` binary is required +* zimbra-proxy package is required +* 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](https://certbot.eff.org/). 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**. +By installing Certbot via packages it automatically creates a cron schedule to renew certificates (at least on Ubuntu). +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 domains configured with SNI. See #8 +* The script doesn't handle multiple domains configured with SNI (see #8). You can still request a single certificate for multiple hostnames. # Usage -## Zimbra 8.6+ single server +```bash +USAGE: certbot_zimbra.sh < -n | -r | -p > [-d my.host.name] [-e extra.domain.tld] [-x] [-w /var/www] +``` + +## Command options + +Either one of these action is mandatory: + +* -n | --new: performs a request for a new certificate +* -r | --renew: deploys certificate, assuming it has just been renewed +* -p | --patch-only: does only nginx patching. Useful to be called before renew, in case nginx templates have been overwritten by an upgrade + +Optional arguments: +* -d | --hostname: hostname being requested. If not passed uses \`zmhostname\` +* -e | --extra-domain: additional domains being requested. Can be used multiple times +* -x | --no-nginx: doesn't check and patch zimbra's nginx. Assumes some other webserver is listening on port 80 +* -w | --webroot: if there's another webserver on port 80/443 specify its webroot +* -a | --agree-tos: agree with the Terms of Service of Let's Encrypt (avoids prompt) +* -c | --prompt-confirmation: ask for confirmation before proceding with cert request showing detected hostname +* -s | --services : the set of services to be used for a certificate. Valid services are 'all' or any of: ldap,mailboxd,mta,proxy. Default: 'all' +* -z | --no-zimbra-restart: do not restart zimbra after a certificate deployment +* -u | --no-public-hostname-detection: do not detect additional hostnames from domains' zimbraServicePublicHostname. Enabled when -e is passed + +## Zimbra 8.6+ single server example Run `./certbot_zimbra.sh -n` @@ -36,22 +61,23 @@ it should do everything by itself, including **restarting zimbra**. The domain of the certificate is obtained automatically by running `zmhostname`. If you want do request a specific hostname use the `-d/--hostname` option. -The certificate can be requested with additional hostnames. By default the script loops though all Zimbra domains and fetches -the zimbraPublicServiceHostname defined and adds them to the request. If you want to disable this behavior use the `-u/--no-public-hostname-detection` option. To indicate additional domains explicitly use the `-e/--extra-domain` option (can be specified multiple times). Note that `-e` disables additional hostname detection. +The certificate can be requested with additional hostnames. By default the script loops though all Zimbra domains, fetches +the `zimbraPublicServiceHostname` attribute and adds the value to the request. If you want to disable this behavior use the `-u/--no-public-hostname-detection` option. +To indicate additional domains explicitly use the `-e/--extra-domain` option (can be specified multiple times). Note that `-e` disables additional hostname detection. ## 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 (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)" +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 " ``` 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. +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 certbot. -The `-d` option is required in order to avoid domain confirmation prompt by the script. +The domain to renew is automatically obtained with `zmhostname`. If you need customized domain name pass the `-d` parameter after `-r`. ## 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. @@ -66,7 +92,7 @@ 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)" +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" ``` Create a timer file to run the above once a day at 2am: /etc/systemd/system/renew-letsencrypt.timer diff --git a/certbot_zimbra.sh b/certbot_zimbra.sh index 042904a..9b5005f 100755 --- a/certbot_zimbra.sh +++ b/certbot_zimbra.sh @@ -439,7 +439,7 @@ USAGE: $(basename $0) < -n | -r | -p > [-d my.host.name] [-e extra.domain.tld] [ -e | --extra-domain: additional domains being requested. Can be used multiple times -x | --no-nginx: doesn't check and patch zimbra's nginx. Assumes some other webserver is listening on port 80 -w | --webroot: if there's another webserver on port 80 specify its webroot - -a | --agree-tos: agree with the Terms of Service of Let's Encrypt + -a | --agree-tos: agree with the Terms of Service of Let's Encrypt (avoids prompt) -c | --prompt-confirmation: ask for confirmation before proceding with cert request showing detected hostname -s | --services : the set of services to be used for a certificate. Valid services are 'all' or any of: ldap,mailboxd,mta,proxy. Default: 'all' -z | --no-zimbra-restart: do not restart zimbra after a certificate deployment