* [dm-crypt] Do you accept contributions to manpage via patch? @ 2020-10-18 11:54 Jörg Kastning 2020-10-18 14:18 ` Milan Broz 0 siblings, 1 reply; 11+ messages in thread From: Jörg Kastning @ 2020-10-18 11:54 UTC (permalink / raw) To: dm-crypt Hello, Do you accept contributions to the cryptsetup manpage via patch sent by email? I don't have a GitLab account and therefore not able to submit a merge request. So I would like to submit a patch(1) by mail. Before doing so I would like to know whether you accept those or not. Regards, Joerg ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [dm-crypt] Do you accept contributions to manpage via patch? 2020-10-18 11:54 [dm-crypt] Do you accept contributions to manpage via patch? Jörg Kastning @ 2020-10-18 14:18 ` Milan Broz 2020-10-20 19:53 ` Jörg Kastning 0 siblings, 1 reply; 11+ messages in thread From: Milan Broz @ 2020-10-18 14:18 UTC (permalink / raw) To: Jörg Kastning, dm-crypt On 18/10/2020 13:54, Jörg Kastning wrote: > Do you accept contributions to the cryptsetup manpage via patch sent by > email? Hi, sure, you can send it by email (either to this list or to me directly). If you have a GitHub account, you can create PR there for the cryptsetup git mirror (But I will export patches and import them manually later.) Thanks, Milan ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [dm-crypt] Do you accept contributions to manpage via patch? 2020-10-18 14:18 ` Milan Broz @ 2020-10-20 19:53 ` Jörg Kastning 2020-10-22 8:36 ` Milan Broz 0 siblings, 1 reply; 11+ messages in thread From: Jörg Kastning @ 2020-10-20 19:53 UTC (permalink / raw) To: dm-crypt [-- Attachment #1: Type: text/plain, Size: 720 bytes --] On 18.10.20 16:18, Milan Broz wrote: > On 18/10/2020 13:54, Jörg Kastning wrote: >> Do you accept contributions to the cryptsetup manpage via patch sent by >> email? > > Hi, > > sure, you can send it by email (either to this list or to me directly). Hi, You'll find the manpage patch attached. I've renamed "BASIC COMMANDS" to "BASIC ACTIONS" because the commands are called action in the SYNOPSIS, too. Furthermore I changed a sentence saying that luksFormat would work on unmapped luks containers, only. And last but not least I've added the Section "EXAMPLE" with six examples of common use cases. Please, let me know what you think about the patch and whether you are going to merge it. Regards, Joerg [-- Attachment #2: cryptsetup.8-patch-2020-10-20 --] [-- Type: text/plain, Size: 3121 bytes --] *** cryptsetup.8 2020-10-18 16:28:13.000000000 +0200 --- cryptsetup.8-patch 2020-10-20 21:43:25.026366419 +0200 *************** *** 63,69 **** container creation. If you do not know how to do that, the cryptsetup FAQ describes several options. ! .SH BASIC COMMANDS The following are valid actions for all supported device types. \fIopen\fR <device> <name> \-\-type <device_type> --- 63,69 ---- container creation. If you do not know how to do that, the cryptsetup FAQ describes several options. ! .SH BASIC ACTIONS The following are valid actions for all supported device types. \fIopen\fR <device> <name> \-\-type <device_type> *************** *** 280,286 **** give '-' as file name, which results in the passphrase being read from stdin and the safety-question being skipped. ! You can only call luksFormat on a LUKS device that is not mapped. To use LUKS2, specify \fI\-\-type luks2\fR. --- 280,286 ---- give '-' as file name, which results in the passphrase being read from stdin and the safety-question being skipped. ! In case the device you are going to call luksFormat on already contains a LUKS device that is mapped, you have to close the device first in order to be able to format it. To use LUKS2, specify \fI\-\-type luks2\fR. *************** *** 838,844 **** .TP .B "\-\-type <device-type> Specifies required device type, for more info ! read \fIBASIC COMMANDS\fR section. .TP .B "\-\-hash, \-h \fI<hash\-spec>\fR" Specifies the passphrase hash for \fIopen\fR (for plain and --- 838,844 ---- .TP .B "\-\-type <device-type> Specifies required device type, for more info ! read \fIBASIC ACTIONS\fR section. .TP .B "\-\-hash, \-h \fI<hash\-spec>\fR" Specifies the passphrase hash for \fIopen\fR (for plain and *************** *** 1490,1495 **** --- 1490,1514 ---- .TP .B "\-\-help, \-?" Show help text and default parameters. + .SH EXAMPLE + .TP + Example 1: Create LUKS 2 container on block device /dev/sdX. + sudo cryptsetup --type luks2 luksFormat /dev/sdX + .TP + Example 2: Add an additional passphrase to key slot 5. + sudo cryptsetup --type luks2 luksAddKey --key-slot 5 /dev/sdX + .TP + Example 3: Create LUKS header backup and save it to file. + sudo cryptsetup --type luks2 luksHeaderBackup /dev/sdX --header-backup-file /var/tmp/NameOfBackupFile + .TP + Example 4: Open LUKS contaner on /dev/sdX and map it to sdX_crypt. + sudo cryptsetup open /dev/sdX sdX_crypt + .TP + Example 5: Erase all key slots on /dev/sdX. + sudo cryptsetup erase /dev/sdX + .TP + Example 6: Restore LUKS header from backup file. + sudo cryptsetup luksHeaderRestore /dev/sdX --header-backup-file /var/tmp/NameOfBackupFile .SH RETURN CODES Cryptsetup returns 0 on success and a non-zero value on error. *************** *** 1710,1715 **** --- 1729,1736 ---- Man page extensions by Milan Broz <gmazyland@gmail.com>. .br Man page rewrite and extension by Arno Wagner <arno@wagner.name>. + .br + Add Examples and minor rewrite by Joerg Kastning <jkastning@my-it-brain.de>. .SH COPYRIGHT Copyright \(co 2004 Jana Saout .br ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [dm-crypt] Do you accept contributions to manpage via patch? 2020-10-20 19:53 ` Jörg Kastning @ 2020-10-22 8:36 ` Milan Broz 2020-10-22 9:37 ` Jörg Kastning 0 siblings, 1 reply; 11+ messages in thread From: Milan Broz @ 2020-10-22 8:36 UTC (permalink / raw) To: Jörg Kastning; +Cc: dm-crypt On 20/10/2020 21:53, Jörg Kastning wrote: > > I've renamed "BASIC COMMANDS" to "BASIC ACTIONS" because the commands > are called action in the SYNOPSIS, too. Furthermore I changed a sentence > saying that luksFormat would work on unmapped luks containers, only. And > last but not least I've added the Section "EXAMPLE" with six examples of > common use cases. Hi, thanks for the patch. I would better use word "command" in future, but for now it is ok (we will split man page in future and unify terminology a little bit later). But I have some notes before I can merge this. - the example section - one example how to use --type is perhaps ok, but definitely normal user should never use this option. I will remove it from example 2 and 3. It has no meaning there anyway, the format is set during luksFormat only. (And LUKS2 is default format in many distros already.) - example 5 needs a strong warning, this command make the LUKS device unusable. (but still detected as LUKS block device). It is really meant only for data destruction by removing all volume keys slots from header. - please, is really your name in the man page necessary? There are a lot of contributors not mentioned there. This is quite trivial change and we track authors of such small changes through git commits only (I will reformat it so you are the patch author in git; or you can use use git format-patch) But in general, yes, we are missing the examples section there... strange :) Thanks, Milan *** 1490,1495 **** --- 1490,1514 ---- .TP .B "\-\-help, \-?" Show help text and default parameters. + .SH EXAMPLE + .TP + Example 1: Create LUKS 2 container on block device /dev/sdX. + sudo cryptsetup --type luks2 luksFormat /dev/sdX + .TP + Example 2: Add an additional passphrase to key slot 5. + sudo cryptsetup --type luks2 luksAddKey --key-slot 5 /dev/sdX + .TP + Example 3: Create LUKS header backup and save it to file. + sudo cryptsetup --type luks2 luksHeaderBackup /dev/sdX --header-backup-file /var/tmp/NameOfBackupFile + .TP + Example 4: Open LUKS contaner on /dev/sdX and map it to sdX_crypt. + sudo cryptsetup open /dev/sdX sdX_crypt + .TP + Example 5: Erase all key slots on /dev/sdX. + sudo cryptsetup erase /dev/sdX + .TP + Example 6: Restore LUKS header from backup file. + sudo cryptsetup luksHeaderRestore /dev/sdX --header-backup-file /var/tmp/NameOfBackupFile .SH RETURN CODES Cryptsetup returns 0 on success and a non-zero value on error. *************** *** 1710,1715 **** --- 1729,1736 ---- Man page extensions by Milan Broz <gmazyland@gmail.com>. .br Man page rewrite and extension by Arno Wagner <arno@wagner.name>. + .br + Add Examples and minor rewrite by Joerg Kastning <jkastning@my-it-brain.de>. .SH COPYRIGHT Copyright \(co 2004 Jana Saout .br ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [dm-crypt] Do you accept contributions to manpage via patch? 2020-10-22 8:36 ` Milan Broz @ 2020-10-22 9:37 ` Jörg Kastning 2020-10-22 9:56 ` Milan Broz 0 siblings, 1 reply; 11+ messages in thread From: Jörg Kastning @ 2020-10-22 9:37 UTC (permalink / raw) To: dm-crypt Am 22. Oktober 2020 10:36:07 MESZ schrieb Milan Broz <gmazyland@gmail.com>: >On 20/10/2020 21:53, Jörg Kastning wrote: [...] >But I have some notes before I can merge this. > >- the example section - one example how to use --type is perhaps ok, >but definitely >normal user should never use this option. I will remove it from example >2 and 3. That's OK for me. >- example 5 needs a strong warning, this command make the LUKS device >unusable. >(but still detected as LUKS block device). It is really meant only for >data destruction >by removing all volume keys slots from header. Would you like to add the warning? If you like I can add it an resubmit the patch again. >- please, is really your name in the man page necessary? >There are a lot of contributors not mentioned there. >This is quite trivial change and we track authors of such small changes >through git >commits only (I will reformat it so you are the patch author in git; or >you can use >use git format-patch) > >But in general, yes, we are missing the examples section there... >strange :) It's not necessary to mention my name in the manpage. I put it there because I didn't find any contribution guidelines and didn't know where else to put it. If you Set it as commit author I'm fine with it. Regards, Joerg >*** 1490,1495 **** >--- 1490,1514 ---- > .TP > .B "\-\-help, \-?" > Show help text and default parameters. >+ .SH EXAMPLE >+ .TP >+ Example 1: Create LUKS 2 container on block device /dev/sdX. >+ sudo cryptsetup --type luks2 luksFormat /dev/sdX >+ .TP >+ Example 2: Add an additional passphrase to key slot 5. >+ sudo cryptsetup --type luks2 luksAddKey --key-slot 5 /dev/sdX >+ .TP >+ Example 3: Create LUKS header backup and save it to file. >+ sudo cryptsetup --type luks2 luksHeaderBackup /dev/sdX >--header-backup-file /var/tmp/NameOfBackupFile >+ .TP >+ Example 4: Open LUKS contaner on /dev/sdX and map it to sdX_crypt. >+ sudo cryptsetup open /dev/sdX sdX_crypt >+ .TP >+ Example 5: Erase all key slots on /dev/sdX. >+ sudo cryptsetup erase /dev/sdX >+ .TP >+ Example 6: Restore LUKS header from backup file. >+ sudo cryptsetup luksHeaderRestore /dev/sdX --header-backup-file >/var/tmp/NameOfBackupFile > .SH RETURN CODES > Cryptsetup returns 0 on success and a non-zero value on error. > >*************** >*** 1710,1715 **** >--- 1729,1736 ---- > Man page extensions by Milan Broz <gmazyland@gmail.com>. > .br > Man page rewrite and extension by Arno Wagner <arno@wagner.name>. >+ .br >+ Add Examples and minor rewrite by Joerg Kastning ><jkastning@my-it-brain.de>. > .SH COPYRIGHT > Copyright \(co 2004 Jana Saout > .br >_______________________________________________ >dm-crypt mailing list >dm-crypt@saout.de >https://www.saout.de/mailman/listinfo/dm-crypt -- E-Mail: joerg.kastning@my-it-brain.de Twitter: https://twitter.com/JoergKastning Internet: https://www.my-it-brain.de Threema-ID: K2Y6W49N OpenPGP-ID: 7A302E30 OpenPGP-Fingerabdruck: 2026 DF56 89B6 F79A E776 B15B 55E2 83FB 7A30 2E30 ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [dm-crypt] Do you accept contributions to manpage via patch? 2020-10-22 9:37 ` Jörg Kastning @ 2020-10-22 9:56 ` Milan Broz 2020-10-22 16:05 ` Jörg Kastning 0 siblings, 1 reply; 11+ messages in thread From: Milan Broz @ 2020-10-22 9:56 UTC (permalink / raw) To: Jörg Kastning; +Cc: dm-crypt On 22/10/2020 11:37, Jörg Kastning wrote: > > > Am 22. Oktober 2020 10:36:07 MESZ schrieb Milan Broz <gmazyland@gmail.com>: >> On 20/10/2020 21:53, Jörg Kastning wrote: > [...] >> But I have some notes before I can merge this. >> >> - the example section - one example how to use --type is perhaps ok, >> but definitely >> normal user should never use this option. I will remove it from example >> 2 and 3. > > That's OK for me. > >> - example 5 needs a strong warning, this command make the LUKS device >> unusable. >> (but still detected as LUKS block device). It is really meant only for >> data destruction >> by removing all volume keys slots from header. > > Would you like to add the warning? If you like I can add it an resubmit the patch again. Yes, if you can, please resubmit it. (And the best would be if it is in git format-patch format, but I can reformat it later if you do not use git.) Thanks Milan ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [dm-crypt] Do you accept contributions to manpage via patch? 2020-10-22 9:56 ` Milan Broz @ 2020-10-22 16:05 ` Jörg Kastning 2020-11-05 20:02 ` Jörg Kastning 0 siblings, 1 reply; 11+ messages in thread From: Jörg Kastning @ 2020-10-22 16:05 UTC (permalink / raw) To: dm-crypt Am 22. Oktober 2020 11:56:20 MESZ schrieb Milan Broz <gmazyland@gmail.com>: >On 22/10/2020 11:37, Jörg Kastning wrote: >> >> Would you like to add the warning? If you like I can add it an >resubmit the patch again. > >Yes, if you can, please resubmit it. > >(And the best would be if it is in git format-patch format, but I can >reformat it later if you do not use git.) Sure. I've signed up for Gitlab. I'll send you a merge request when I'm ready. Regards, Jörg ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [dm-crypt] Do you accept contributions to manpage via patch? 2020-10-22 16:05 ` Jörg Kastning @ 2020-11-05 20:02 ` Jörg Kastning 2020-11-05 20:30 ` Milan Broz 0 siblings, 1 reply; 11+ messages in thread From: Jörg Kastning @ 2020-11-05 20:02 UTC (permalink / raw) To: dm-crypt Hi Milan, Just wanna ask if you saw the merge request [0] on GitLab, already. What do you think about it? Are you going to accept it in this form? [0] https://gitlab.com/cryptsetup/cryptsetup/-/merge_requests/115 Regards, Joerg On 22.10.20 18:05, Jörg Kastning wrote: > > > Am 22. Oktober 2020 11:56:20 MESZ schrieb Milan Broz <gmazyland@gmail.com>: >> On 22/10/2020 11:37, Jörg Kastning wrote: >>> >>> Would you like to add the warning? If you like I can add it an >> resubmit the patch again. >> >> Yes, if you can, please resubmit it. >> >> (And the best would be if it is in git format-patch format, but I can >> reformat it later if you do not use git.) > > Sure. I've signed up for Gitlab. I'll send you a merge request when I'm ready. > > Regards, > Jörg > ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [dm-crypt] Do you accept contributions to manpage via patch? 2020-11-05 20:02 ` Jörg Kastning @ 2020-11-05 20:30 ` Milan Broz 2020-11-05 22:50 ` Arno Wagner 0 siblings, 1 reply; 11+ messages in thread From: Milan Broz @ 2020-11-05 20:30 UTC (permalink / raw) To: Jörg Kastning; +Cc: dm-crypt On 05/11/2020 21:02, Jörg Kastning wrote: > Hi Milan, > > Just wanna ask if you saw the merge request [0] on GitLab, already. What > do you think about it? Are you going to accept it in this form? Yes, please stand by, once I can get back to devel work I will comment or merge it. Thanks, Milan ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [dm-crypt] Do you accept contributions to manpage via patch? 2020-11-05 20:30 ` Milan Broz @ 2020-11-05 22:50 ` Arno Wagner 2020-11-12 12:39 ` Milan Broz 0 siblings, 1 reply; 11+ messages in thread From: Arno Wagner @ 2020-11-05 22:50 UTC (permalink / raw) To: Milan Broz; +Cc: Jörg Kastning, dm-crypt Hi Milan, if you want me to review or comment on this, please let me know. Regards, Arno On Thu, Nov 05, 2020 at 21:30:09 CET, Milan Broz wrote: > On 05/11/2020 21:02, Jörg Kastning wrote: > > Hi Milan, > > > > Just wanna ask if you saw the merge request [0] on GitLab, already. What > > do you think about it? Are you going to accept it in this form? > > Yes, please stand by, once I can get back to devel work I will comment or merge it. > > Thanks, > Milan > _______________________________________________ > dm-crypt mailing list > dm-crypt@saout.de > https://www.saout.de/mailman/listinfo/dm-crypt -- Arno Wagner, Dr. sc. techn., Dipl. Inform., Email: arno@wagner.name GnuPG: ID: CB5D9718 FP: 12D6 C03B 1B30 33BB 13CF B774 E35C 5FA1 CB5D 9718 ---- A good decision is based on knowledge and not on numbers. -- Plato If it's in the news, don't worry about it. The very definition of "news" is "something that hardly ever happens." -- Bruce Schneier ^ permalink raw reply [flat|nested] 11+ messages in thread
* Re: [dm-crypt] Do you accept contributions to manpage via patch? 2020-11-05 22:50 ` Arno Wagner @ 2020-11-12 12:39 ` Milan Broz 0 siblings, 0 replies; 11+ messages in thread From: Milan Broz @ 2020-11-12 12:39 UTC (permalink / raw) To: dm-crypt On 05/11/2020 23:50, Arno Wagner wrote: > Hi Milan, > > if you want me to review or comment on this, please let me know. Hi, there was some discussion on that issue, but I merged that already. The documentation will need a lot of work in the future (mainly for the new features for the following releases with examples). If anyone would like to contribute, please send patches :-) Thanks, Milan ^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2020-11-12 12:39 UTC | newest] Thread overview: 11+ messages (download: mbox.gz / follow: Atom feed) -- links below jump to the message on this page -- 2020-10-18 11:54 [dm-crypt] Do you accept contributions to manpage via patch? Jörg Kastning 2020-10-18 14:18 ` Milan Broz 2020-10-20 19:53 ` Jörg Kastning 2020-10-22 8:36 ` Milan Broz 2020-10-22 9:37 ` Jörg Kastning 2020-10-22 9:56 ` Milan Broz 2020-10-22 16:05 ` Jörg Kastning 2020-11-05 20:02 ` Jörg Kastning 2020-11-05 20:30 ` Milan Broz 2020-11-05 22:50 ` Arno Wagner 2020-11-12 12:39 ` Milan Broz
This is an external index of several public inboxes, see mirroring instructions on how to clone and mirror all data and code used by this external index.