diff --git a/certbot/cli.py b/certbot/cli.py index e100c7715..fea83da29 100644 --- a/certbot/cli.py +++ b/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, diff --git a/docs/cli-help.txt b/docs/cli-help.txt index a5f77a3a1..91041458e 100644 --- a/docs/cli-help.txt +++ b/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 - keys; the shell variable $RENEWED_DOMAINS will contain - a space-delimited list of renewed cert domains - (default: None) + 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 (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 diff --git a/docs/using.rst b/docs/using.rst index a325ff413..7eaa92f84 100644 --- a/docs/using.rst +++ b/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``.