Preliminary Discussions for a Handbook of Certbot Best Practices

This was exactly my concern. I don’t know if the configuration got updated with the new set. I don’t know why it wouldn’t though either.

It is for this type of reason that I’m in the midst of putting together the initial structure of a “task-oriented” best practices handbook for certification/certbot as the seed for a roundtable discussion. I feel like cerbot in its flexibility has a great deal of duplication and uncertainty inherent in its functionality. Its documentation is almost like reading through a legal compendium, which certainly isn’t the the most straightforward way to learn or accomplish typical tasks. I’m looking forward to your contributions in hammering out this handbook so hopefully we can establish a brief, streamlined reference of “minimal, but effective” ways, if you will, to accomplish certain tasks, like establishing the set of domains in a certificate. For instance, I think that building, expanding, reducing, and generally changing the domain names can all be accomplished through --cert-name without needing to find ultra-specific functionality like --allow-subset-of-names.

1 Like

The list of hostnames at renewal is read from the active certificate. So if a certain certificate is issued, the included set of hostnames of that certificate “sticks” by design for the renewals. In that regard it isn’t necessary for the “allow-subset-of-names” option to stick itself.

3 Likes

Thanks for the clarification @Osiris . This hasn’t been inherently evident to me. It is the logical place to “search” for the domains though. I feel at times like the who handles what role of the “configuration” isn’t always evident.

1 Like

certbot certificates
[will clear up any/all questions]

2 Likes

That will let you know which certificates exist, but doesn’t inherently clarify what’s in which “configuration file” where the certificate itself is also a “configuration file”. :slightly_smiling_face:

1 Like

It shows all the current names used by all the certs issued.
What else do we need to know?

1 Like

How certain operations of certbot do or don’t influence the future configuration used for renewals and under what circumstances. This isn’t just about determining the domain names that will be used, which @Osiris clarified. It is also about understanding which sets of operations change the configuration and how so as to streamline the outcomes. For example if I successfully authenticate using webroot and fail to install via apache, what exactly gets “saved”.

… deep …

1 Like

Reverse engineer it ! ! !

OR

Just read through the “open source” ?

1 Like

We should start a TEAMS project
With this specific goal in mind
[and see how that goes - and go from there]

(post withdrawn by author, will be automatically deleted in 24 hours unless flagged)

That is an excellent start - I await your commencement

Thanks for your interest in this @griffin!

I agree that Certbot’s documentation at https://certbot.eff.org/docs/ could be more clear and actionable.

The Certbot team is pretty busy so while I don’t think we’d have a lot of time to dedicate to this right now and I can’t make any promises, I/we would potentially be willing to help with this. You’re of course welcome to do your own thing and again I can’t promise anything, but we could potentially merge whatever you create into Certbot’s official docs if that seems appropriate.

I’m open to other ideas, but I think the best way that we could help is to answer any questions about how Certbot works and verify that whatever is written really is the current best practice for Certbot. I think the larger community here could help with most of this, but we could try and clarify any areas of uncertainty.

5 Likes

It basically comes down to two “ways” of using “help files”.

  1. Basic “MAN PAGE” for the techiest of techs.
  2. User-friendly “how to” with examples and detailed explanations

#1 already exists
#2 @griffin will champion!
[and we will all help too :slight_smile: ]

4 Likes

Great to finally meet you! Absolutely! I wasn’t at the point of sending out invites yet, but you guys are definitely critical in this.

The goal here isn’t so much to replace our supersede the official documentation, but to offer a streamlined card of sorts to present a “minified” set of functionality that could serve to formalize/clarify the process. If suggestions towards or merge with the official documentation happens, that’s great too though. For an example, the anatomy of a basic certbot command could be presented with -a and -i to emphasize the two aspects. This addresses the --apache -a webroot type of confusion we see around here every other day. This would correspond to a straightforward map of the steps and scope involved with http-> https.

Exactly @rg305. Though I’m not looking to be a one-man operation. I really want the collective input of the certbot guys and the Let’s Encrypt Community.

There ideally would be specific references to the official manual for deeper reading or specific situations.

3 Likes

I think that may just be the default behavior of the documentation tool we use. https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents describes using the backlinks option to control this.

I couldn’t quickly find any documentation about what the default is, but we don’t set this value so I assume it’s defaulting to the value of “entry” described there.

2 Likes

Makes sense. Frameworks. Can’t live without them. Lose hair with them.

3 Likes

Some thoughts for good topics:

  • certbot, certbot-auto, and letsencrypt all refer to ways of running the same software
  • Difference between “certonly” and “run” for getting your cert the first time
  • Difference between “certonly” and “renew” for renewing your cert
  • Never use --renew-by-default!!
  • How to change the names covered by your certificate
  • How to avoid getting duplicative overlapping certificates (-0001) and how to deal with the problem if you have them
  • Prerequisites for --standalone, --webroot, --apache, and --nginx; when would you use one rather than another?
  • Automated renewal and wildcard certificates
  • Do you need to add a cron job for automated renewal?
  • What if Certbot says your certificate is renewed, but you don’t see the new certificate active on your site?
  • How to delete certificates safely
3 Likes
  • How to change the renewal method or other options for an existing certificate
4 Likes

Those are all EXCELLENT suggestions @schoen. I will definitely incorporate them into the initial writeup. This should be fun. I feel a bit like I’m trying to wrap a 9-headed octopus with multi-staged camouflage in Christmas wrap. :upside_down_face: