Updated documentation

README.md

@@ -13,45 +13,71 @@ 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 <service_names>: 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`
 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

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