Merge pull request #4028 from jwm/jwm/3502_renew_hook_examples

add example of --renew-hook envvar values and hook script (#3502)

certbot/cli.py

@@ -1064,9 +1064,11 @@ def prepare_and_parse_args(plugins, args, detect_defaults=False):  # pylint: dis
         "renew", "--renew-hook",
         help="Command to be run in a shell once for each successfully renewed"
         " certificate. For this command, the shell variable $RENEWED_LINEAGE"
-        " will point to the config live subdirectory containing the new certs"
+        " will point to the config live subdirectory (for example,"
+        " \"/etc/letsencrypt/live/example.com\") containing the new certs"
         " and keys; the shell variable $RENEWED_DOMAINS will contain a"
-        " space-delimited list of renewed cert domains")
+        " space-delimited list of renewed cert domains (for example,"
+        " \"example.com www.example.com\"")
     helpful.add(
         "renew", "--disable-hook-validation",
         action='store_false', dest='validate_hooks', default=True,

docs/cli-help.txt

@@ -265,10 +265,12 @@ renew:
                         Command to be run in a shell once for each
                         successfully renewed certificate. For this command,
                         the shell variable $RENEWED_LINEAGE will point to the
-                        config live subdirectory containing the new certs and
+                        config live subdirectory (for example,
-                        keys; the shell variable $RENEWED_DOMAINS will contain
+                        "/etc/letsencrypt/live/example.com") containing the
-                        a space-delimited list of renewed cert domains
+                        new certs and keys; the shell variable
-                        (default: None)
+                        $RENEWED_DOMAINS will contain a space-delimited list
+                        of renewed cert domains (for example,
+                        "example.com www.example.com") (default: None)
   --disable-hook-validation
                         Ordinarily the commands specified for --pre-hook
                         /--post-hook/--renew-hook will be checked for

docs/using.rst

@@ -387,6 +387,49 @@ non-zero exit code. Hooks will only be run if a certificate is due for
 renewal, so you can run the above command frequently without
 unnecessarily stopping your webserver.
 
+``--pre-hook`` and ``--post-hook`` hooks run before and after every renewal
+attempt. If you want your hook to run only after a successful renewal, use
+``--renew-hook`` in a command like this.
+
+``certbot renew --renew-hook /path/to/renew-hook-script``
+
+For example, if you have a daemon that does not read its certificates as the
+root user, a renew hook like this can copy them to the correct location and
+apply appropriate file permissions.
+
+/path/to/renew-hook-script
+
+.. code-block:: none
+
+   #!/bin/sh
+
+   set -e
+
+   for domain in $RENEWED_DOMAINS; do
+           case $domain in
+           example.com)
+                   daemon_cert_root=/etc/some-daemon/certs
+
+                   # Make sure the certificate and private key files are
+                   # never world readable, even just for an instant while
+                   # we're copying them into daemon_cert_root.
+                   umask 077
+
+                   cp "$RENEWED_LINEAGE/fullchain.pem" "$daemon_cert_root/$domain.cert"
+                   cp "$RENEWED_LINEAGE/privkey.pem" "$daemon_cert_root/$domain.key"
+
+                   # Apply the proper file ownership and permissions for
+                   # the daemon to read its certificate and key.
+                   chown some-daemon "$daemon_cert_root/$domain.cert" \
+                           "$daemon_cert_root/$domain.key"
+                   chmod 400 "$daemon_cert_root/$domain.cert" \
+                           "$daemon_cert_root/$domain.key"
+
+                   service some-daemon restart >/dev/null
+                   ;;
+           esac
+   done
+
  More information about renewal hooks can be found by running
 ``certbot --help renew``.