New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add information about cert management to the docs #4092
Conversation
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Minor changes requested/suggested!
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I made #4108 to track that UX issue.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
@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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
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)."
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
(or something like that)
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.