Add information about cert management to the docs #4092
Conversation
docs/using.rst
Outdated
|
|
||
| If your account key has been compromised or you otherwise need to revoke a certificate, | ||
| use the revoke command to do so. Note that the revoke command is passed the certificate path | ||
| (ending in ``cert.pem``), not a certificate name or domain. Additionally, if a certificate |
There was a problem hiding this comment.
This is one of those places where explaining lineages would really help people. After all, if you revoke a cert but don't delete it, your renewal cron job will come along later and reissue it for you (!).
There was a problem hiding this comment.
Great point! @pconrad-fb is taking a pass on this; I can make these changes now or block on that, whichever.
There was a problem hiding this comment.
I don't have a strong opinion on the documentation side; I suspect that we should actually add a little polish to this in the UI though (either offering to delete the cert, or telling the user that unless they delete the cert it will be renewed at the next renewal event).
There was a problem hiding this comment.
I made #4108 to track that UX issue.
There was a problem hiding this comment.
I've got using.rst from the Managing Docs branch open locally right now. I can talk about lineages in this pass through the doc—but I don't know what lineages are. Where can I learn about them?
There was a problem hiding this comment.
@pconrad-fb unfortunately, #4016.
Quickly: a lineage is what is elsewhere just called a certificate. We use the term internally to create the illusion of consistence across renewals. There is not really any such thing as renewing a cert, to a CA, only getting a new one that might have related/ the same domains in it. Within Certbot, each lineage is attached to a single renewal configuration file, and its related information is stored in the archive and live directories. Then the links in the live directories point to the updated file in the appropriate archive directory whenever you renew.
There was a problem hiding this comment.
So, to close the loop with @pde, the takeaway is that Certbot makes it a no-brainer to get and maintain certificates; and therefore it's useful to think of them as "lineages" of certificates that have the same domain; and that if you want to end a lineage, so to speak, you really have to explicitly delete them and not just revoke them. Right?
There was a problem hiding this comment.
Mostly! They don't always necessarily have the same domain (you could always include more domains on a certificate with --expand, and now you can change them entirely by using --cert-name) although they often do have that in common. The last half is definitely true and important to note!
docs/using.rst
Outdated
| renewal configuration file, located at ``/etc/letsencrypt/renewal/CERTNAME``. | ||
|
|
||
| .. warning:: Modifying any files in ``/etc/letsencrypt`` can make it so Certbot can no longer | ||
| properly manage its certificates, and we do not recommend doing so for most users. |
There was a problem hiding this comment.
Perhaps add: "For most tasks, it is safest to limit yourself to pointing symlinks at the files there, or using --renew-hook to copy / make new files based upon those files, if your operational situation requires it (for instance, combining certs and keys in different way, or having copies of things with different specific permissions that are demanded by other programs)."
|
Feel free to either merge as is or make the changes I suggested and then merge. |
|
@SwartzCr, @pde - moving back to this PR from #4137. This has the updated version of my changes, @pconrad-fb's changes, and incorporated comments. |
No description provided.