Documentation: add systemd warning for rd.luks.key, clean up related text

Harald Hoyer <harald@redhat.com>: Squashed commit of the following:

commit 4b5e5da6061983964a85d1671bd1c97c48ee76f1
Author: jbash aka John Bashinski <jbash@velvet.com>
Date:   Thu Aug 1 13:21:35 2019 -0400

    Documentation: add systemd warning for rd.luks.key, clean up related text

diff --git a/dracut.cmdline.7.asc b/dracut.cmdline.7.asc
index bf52dd4ebd33e66e207c884c197255b8c7cefd8b..e91f967dd8c7ba562037b7433cd9555bf81a3900 100644 (file)
--- a/dracut.cmdline.7.asc
+++ b/dracut.cmdline.7.asc
@@ -318,22 +318,37 @@ crypto LUKS
 
 crypto LUKS - key on removable device support
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-**rd.luks.key=**__<keypath>__:__<keydev>__:__<luksdev>__::
-    _keypath_ is a path to key file to look for. It's REQUIRED. When _keypath_
-    ends with '.gpg' it's considered to be key encrypted symmetrically with GPG.
-    You will be prompted for password on boot. GPG support comes with
-    'crypt-gpg' module which needs to be added explicitly.
-+
-_keydev_ is a device on which key file resides. It might be kernel name of
-devices (should start with "/dev/"), UUID (prefixed with "UUID=") or label
-(prefix with "LABEL="). You don't have to specify full UUID. Just its beginning
-will suffice, even if its ambiguous. All matching devices will be probed.
-This parameter is recommended, but not required. If not present, all block
-devices will be probed, which may significantly increase boot time.
-+
-If _luksdev_ is given, the specified key will only be applied for that LUKS
-device. Possible values are the same as for _keydev_. Unless you have several
-LUKS devices, you don't have to specify this parameter. The simplest usage is:
+
+NB: If systemd is included in the dracut initrd, dracut's built in
+removable device keying support won't work. systemd will prompt for
+a password from the console even if you've supplied **rd.luks.key**.
+You may be able to use standard systemd *fstab*(5) syntax to
+get the same effect. If you do need **rd.luks.key** to work,
+you will have to exclude the "systemd" dracut module and any modules
+that depend on it. See *dracut.conf*(5) and
+https://bugzilla.redhat.com/show_bug.cgi?id=905683 for more
+information.
+
+**rd.luks.key=**_<keypath>[:<keydev>[:<luksdev>]]_::
+    _<keypath>_ is the pathname of a key file, relative to the root
+    of the filesystem on some device. It's REQUIRED. When
+    _<keypath>_ ends with '.gpg' it's considered to be key encrypted
+    symmetrically with GPG.  You will be prompted for the GPG password on
+    boot. GPG support comes with the 'crypt-gpg' module, which needs to be
+    added explicitly.
++
+_<keydev>_ identifies the device on which the key file resides. It may
+be the kernel name of the device (should start with "/dev/"), a UUID
+(prefixed with "UUID=") or a label (prefix with "LABEL="). You don't
+have to specify a full UUID. Just its beginning will suffice, even if
+its ambiguous. All matching devices will be probed.  This parameter is
+recommended, but not required. If it's not present, all block devices will
+be probed, which may significantly increase boot time.
++
+If _<luksdev>_ is given, the specified key will only be used for
+the specified LUKS device. Possible values are the same as for
+_<keydev>_. Unless you have several LUKS devices, you don't have to
+specify this parameter. The simplest usage is:
 +
 [listing]
 .Example
@@ -342,27 +357,40 @@ rd.luks.key=/foo/bar.key
 --
 +
 As you see, you can skip colons in such a case.
-+
+
 [NOTE]
 ===============================
-dracut pipes key to cryptsetup with _-d -_ argument, therefore you need to pipe
-to cryptsetup luksFormat with _-d -_, too!
+Your LUKS partition must match your key file.
+
+dracut provides keys to cryptsetup with _-d_ (an older alias for
+_--key-file_). This uses the entire binary
+content of the key file as part of the secret.  If
+you pipe a password into cryptsetup *without* _-d_ or _--key-file_,
+it will be treated as text user input, and only characters before
+the first newline will be used. Therefore, when you're creating
+an encrypted partition for dracut to mount, and you pipe a key into
+_cryptsetup luksFormat_,you must use _-d -_.
 
-Here follows example for key encrypted with GPG:
+Here is an example for a key encrypted with GPG (warning:
+_--batch-mode_ will overwrite the device without asking for
+confirmation):
 
 [listing]
 --
 gpg --quiet --decrypt rootkey.gpg | \
-cryptsetup -d - -v --cipher serpent-cbc-essiv:sha256 \
---key-size 256 luksFormat /dev/sda3
+cryptsetup --batch-mode --key-file - \
+           luksFormat /dev/sda47
 --
 
-If you use plain keys, just add path to _-d_ option:
+If you use unencrypted key files, just use the key file pathname
+instead of the standard input. For a random key with 256 bits of
+entropy, you might use:
 
 [listing]
 --
-cryptsetup -d rootkey.key -v --cipher serpent-cbc-essiv:sha256 \
- --key-size 256 luksFormat /dev/sda3
+head -32c /dev/urandom > rootkey.key
+cryptsetup --batch-mode --key-file rootkey.key \
+           luksFormat /dev/sda47
 --
 ===============================