Repository: certbot/certbot

Issue:
Manpage bug: Shouldn't recommend certonly as the way to renew individual lineages
In the User Guide and manpage, it says:

    renew:
      The 'renew' subcommand will attempt to renew all certificates (or more
      precisely, certificate lineages) you have previously obtained if they are
      close to expiry, and print a summary of the results. By default, 'renew'
      will reuse the options used to create obtain or most recently successfully
      renew each certificate lineage. You can try it with `--dry-run` first. For
      more fine-grained control, you can renew individual lineages with the
      `certonly` subcommand. Hooks are available to run commands before and
      after renewal; see https://certbot.eff.org/docs/using.html#renewal for
      more information on these.

I think that the statement:

    "For more fine-grained control, you can renew individual lineages
    with the `certonly` subcommand"

should be changed to:

    "For more fine-grained control, you can renew individual lineages
    with the `--cert-name` option"

The existing statement made me think that it's OK to use certonly for renewals,
and it kind of works, but it doesn't work well, has surprising side effects, and can
easily do the wrong thing.

The renew subcommand performs all pre, post, and deploy hooks in the
/etc/letsencrypt/renewal-hooks directories, but the certonly subcommand
only runs the deploy hooks there. It doesn't run the pre or post hooks.

The renew subcommand remembers past renewal parameters and uses them.

I (naturally?) expected renewal parameters to be used when renewing, whether
the renewal is done by the renew subcommand or by the certonly subcommand.

But that's not the case. The certonly subcommand ignores most of the existing
renewal parameters and removes them from the renewal config file.

That surprised me because the manpage recommended it as a way to renew
a lineage. I'm a big fan of the principle of least astonishment.

If the purpose of the above statement is just to say how to renew an individual
certificate rather all of them, the above suggested replacement would be a better
way to say it, because it wouldn't lead people to use the certonly subcommand
when they really should be using the renew subcommand with the --cert-name
option.

On the other hand, if the reference to "fine-grained control" was actually hinting
at the ability of the certonly subcommand to discard most previously saved renewal
parameters and start again from scratch with an entirely new set of renewal parameters,
then perhaps a better replacement might be:

    "To renew individual lineages, you can use the --cert-name option.
    To prevent the reuse of previous options, and to define new options,
    you can use the `certonly` subcommand instead.

Also, if it is desirable that certonly doesn't run existing pre and post hooks
(and it isn't just a bug), then the statement:

    "Hooks are available to run commands before and after renewal"

should probably be changed to:

    "Hooks are available to run commands before and after renewal
    (but not certonly)"

So that the reader is informed explicitly. But it's complicated by the fact that
certonly will run pre/post hooks that are on the command line (I'm told). It
just doesn't run the ones in the /etc/letsencrypt/renewal-hooks directories.


Discussion:
I think changing the text to

    "For more fine-grained control, you can renew individual lineages
    with the `--cert-name` option"

sounds good to me.

Resolving patch:
diff --git a/certbot/certbot/_internal/cli/verb_help.py b/certbot/certbot/_internal/cli/verb_help.py
--- a/certbot/certbot/_internal/cli/verb_help.py
+++ b/certbot/certbot/_internal/cli/verb_help.py
@@ -23,14 +23,14 @@
     }),
     ("renew", {
         "short": "Renew all certificates (or one specified with --cert-name)",
-        "opts": ("The 'renew' subcommand will attempt to renew all"
-                 " certificates (or more precisely, certificate lineages) you have"
+        "opts": ("The 'renew' subcommand will attempt to renew any certificates"
                  " previously obtained if they are close to expiry, and print a"
-                 " summary of the results. By default, 'renew' will reuse the options"
-                 " used to create obtain or most recently successfully renew each"
-                 " certificate lineage. You can try it with `--dry-run` first. For"
-                 " more fine-grained control, you can renew individual lineages with"
-                 " the `certonly` subcommand. Hooks are available to run commands"
+                 " summary of the results. By default, 'renew' will reuse the"
+                 " plugins and options used to obtain or most recently renew each"
+                 " certificate. You can test whether future renewals will succeed"
+                 " with `--dry-run`."
+                 " Individual certificates can be renewed with the `--cert-name`"
+                 " option. Hooks are available to run commands"
                  " before and after renewal; see"
                  " https://certbot.eff.org/docs/using.html#renewal for more"
                  " information on these."),


Test patch: