Re: [dm-crypt] Do you accept contributions to manpage via patch?

Jörg Kastning
2020-10-20T19:53:47Z

[-- 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