Where is the renewal config file grammar documented?

[raf]

I can't find the documentation anywhere. User Guide — Certbot 2.3.0 documentation has a section called "Modifying the Renewal Configuration File" which says "it is possible to manually modify the certificate’s renewal configuration file, but this is discouraged since it can easily break Certbot’s ability to renew your certificates".

Breakage would be less likely if the format/grammar were documented. Breakage would be even less likely if there was a tool to check its syntax after changes. This seems like an odd thing to omit.

Searching for "renewalparams site:certbot.eff.org" finds nothing helpful. I'm guessing (though I shouldn't have to), that it's a transformation of command line parameters e.g. "--paramname paramvalue" becomes "paramname = paramvalue" under the [renewalparams] section. But what if there's no value? Do I just put "reuse-key" underneath "[renewalparams]"? Or is it "reuse-key = yes"? Or is it something else?

There really should be documentation that lists every valid setting name and section name with information about possible values.

[_az]

All fair points. I left a comment about documenting these here the other day.

@raf

. I'm guessing (though I shouldn't have to), that it's a transformation of command line parameters e.g. "--paramname paramvalue" becomes "paramname = paramvalue" under the [renewalparams] section. But what if there's no value? Do I just put "reuse-key" underneath "[renewalparams]"? Or is it "reuse-key = yes"? Or is it something else?

Unfortunately I don't think there's any totally reliable way to predict what it should be. The CLI options and the renewal parameters are distinct things, even though they look like they overlap.

Right now the best solution that exists is to do a --force-renewal with the CLI flag you want, e.g.

certbot renew --cert-name example.com --force-renewal --reuse-key

and that would persist the option for future renewals.

We are also investigating adding a way to update existing renewal parameters without actually doing a renewal. I think this would be the best solution because it avoids having the user modify internal files and also avoids pointless renewals.

For reference, --reuse-key has this effect:

# Options used in the renewal process
[renewalparams]
reuse_key = True

[raf]

Thanks for that. And yes, a command to just update renewal parameters would also be good.