Skip to content
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

systemd-cryptenroll: add page #10731

Merged
merged 9 commits into from
Oct 2, 2023
Merged

systemd-cryptenroll: add page #10731

merged 9 commits into from
Oct 2, 2023

Conversation

RoepLuke
Copy link
Contributor

@RoepLuke RoepLuke commented Sep 18, 2023

Hello there, I stumbled upon systemd-cryptenroll today and when trying to understand it, I found it had no TLDR yet.

I tried to make it as compact as possible, but the very dynamic parameter set of this command did not allow me to compress it further without leaving out important points. Furthermore, I had to use H2-Headings to distance the different Unlocking Methods from each other.

I wasn't able to find a relatable / about as complex example to base this one on, but I would be inclined to adapt this pull request if you could provide me with one.

Also, the Heading/Introduction had to be larger than normal because of the important distinction from the system boot behavior defined in crypttab and to tell the User that the volume needs to be unlocked by systemd-cryptenroll via a currently present Method to make any changes.

EDIT / TODO: I read the content guidelines a bit too late and need to slim the tldr before it can be reviewed and accepted.

  • The page(s) are in the correct platform directories: common, linux, osx, windows, sunos, android, etc.
  • The page(s) have at most 8 examples.
  • The page description(s) have links to documentation or a homepage.
  • The page(s) follow the content guidelines.
  • The PR title conforms to the recommended templates.
  • Version of the command being documented (if known): systemd 253 (253.9-1.fc38)

Hello there, I stumbled upon systemd-cryptenroll today and when trying to understand it, I found it had no TLDR yet.

I tried to make it as compact as possible, but the very dynamic parameter set of this command did not allow me to compress it further without leaving out important points. Furthermore, I had to use H2-Headings to distance the different Unlocking Methods from each other. 

I wasn't able to find a relatable / about as complex example to base this one on, but I would be inclined to adapt this pull request if you could provide me with one. 

Also, the Heading/Introduction had to be larger than normal because of the important distinction from the system boot behavior defined in crypttab and to tell the User that the volume needs to be unlocked by systemd-cryptenroll via a currently present Method to make any changes.
@github-actions github-actions bot added the new command Issues requesting creation of a new page or PRs adding a new page for a command. label Sep 18, 2023
@tldr-bot

This comment was marked as outdated.

@RoepLuke RoepLuke changed the title systemd-cryptenroll: add page [Draft] systemd-cryptenroll: add page Sep 18, 2023
@RoepLuke RoepLuke mentioned this pull request Sep 18, 2023
56 tasks
@RoepLuke
Copy link
Contributor Author

I'd propose removing all semi-duplicate "Unlock with FIDO2-Device" and "Unlock with Key-File" examples.
They could be replaced by a single general example for using FIDO2/KeyFile to Unlock changing the volume Key Slots.
Or they could just be left out. That would cut the examples down from 28 to about 19.

systemd-cryptenroll --unlock-fido2-device={{path/to/fido_hidraw_unlock_device}} --fido2-device={{path/to/fido_hidraw_enroll_device}} {{path/to/luks2_block_device}} is kind of an exception here because it shows the difference between the two "fido2-device" parameters.

@RoepLuke
Copy link
Contributor Author

Removing all semi-duplicate [...] --wipe-slots= [...] examples would cut them down from 19 to 15.

@RoepLuke
Copy link
Contributor Author

The examples using [...] --tpm2-device=list [...] or [...] --fido2-device=list [...] or [...] --pkcs11-token-uri=list [...] could be combined with their other respective examples.
Like this:
systemd-cryptenroll --pkcs11-token-uri={{list|auto|pkcs11_token_uri}} {{path/to/luks2_block_device}}

That would remove another 3 examples, bringing us down to 12. An now I'm not sure what to cut next.
Open for approval / disapproval / feeedback.

Remove extra H2-Headlines
Shorten the Description.
@tldr-bot

This comment was marked as resolved.

Fix Errors in Heading
@tldr-bot

This comment was marked as resolved.

@tldr-bot

This comment was marked as resolved.

@tldr-bot

This comment was marked as resolved.

There was a Whitespace at the end of line 29.
Make Heading more precise and add recommendation to update initramfs.

Add missing parameters to command examples

Correct "fido" to "fido2"
@RoepLuke
Copy link
Contributor Author

The page/file has been updated to only contain 8 examples and its main description shortened.
The descriptions of the examples may still be considered too long, but I'm not sure on that.

grafik

@RoepLuke RoepLuke marked this pull request as ready for review September 21, 2023 22:48
Copy link
Member

@kbdharun kbdharun left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Welcome to tldr and thanks for your contribution. I have some suggestions for this page.

We generally prefer to not leave spaces between / (slashes) across our pages.

@kbdharun kbdharun requested a review from acuteenvy October 1, 2023 19:16
RoepLuke and others added 2 commits October 1, 2023 21:29
Co-authored-by: K.B.Dharun Krishna <kbdharunkrishna@gmail.com>
@kbdharun kbdharun merged commit d845efb into tldr-pages:main Oct 2, 2023
@RoepLuke RoepLuke deleted the patch-1 branch October 2, 2023 13:09
@acuteenvy acuteenvy removed their request for review October 2, 2023 13:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
new command Issues requesting creation of a new page or PRs adding a new page for a command.
Projects
None yet
Development

Successfully merging this pull request may close these issues.

4 participants