Bug 243261 - geli manpage needs to add detail about the loader variables
Summary: geli manpage needs to add detail about the loader variables
Status: Closed FIXED
Alias: None
Product: Documentation
Classification: Unclassified
Component: Manual Pages (show other bugs)
Version: Latest
Hardware: Any Any
: --- Affects Only Me
Assignee: Mateusz Piotrowski
URL:
Keywords: patch
Depends on:
Blocks:
 
Reported: 2020-01-11 02:54 UTC by johannes
Modified: 2020-04-15 08:12 UTC (History)
2 users (show)

See Also:


Attachments

Note You need to log in before you can comment on or make changes to this bug.
Description johannes 2020-01-11 02:54:42 UTC
The geli manpage has an example for preloading keyfiles during boot.
There is no detail though on how the lookup of these variables actually works.

There seems to be some magic "geli_$device_..." pattern.

I've checked the source to find out how it works because i've wasted quite a bit of time trying to make sense and come up with the correct magic of the geli/device/keyfile combination.

Turns out none of that matters.

I propose to add something like (sorry I know nothing about manpage syntax):


diff --git a/lib/geom/eli/geli.8 b/lib/geom/eli/geli.8
index 43ca9a2928c..ee994d544cf 100644
--- a/lib/geom/eli/geli.8
+++ b/lib/geom/eli/geli.8
@@ -1013,6 +1013,12 @@ geli_da1s3a_keyfile_type="da1s3a:geli_keyfile"
 geli_da1s3a_keyfile_name="/boot/keys/da1s3a.key"
 .Ed
 .Pp
+By convention, these loader variables are called geli_$device_load. However, the
+actual name prefix before _load/_type/_name does not matter. At boot time, the
+geli module will search through all $something_type that have a value of
+"$device:geli_keyfile", leading to $something_name with has the path to the keyfile.
+In the example above, $something is "geli_da1s3a_keyfile".
+.Pp
 Not only configure encryption, but also data integrity verification using
 .Nm HMAC/SHA256 .
 .Bd -literal -offset indent
Comment 1 Mateusz Piotrowski freebsd_committer 2020-03-18 14:54:51 UTC
https://reviews.freebsd.org/D24114
Comment 2 commit-hook freebsd_committer 2020-03-19 09:24:25 UTC
A commit references this bug:

Author: 0mp
Date: Thu Mar 19 09:23:27 UTC 2020
New revision: 359125
URL: https://svnweb.freebsd.org/changeset/base/359125

Log:
  Document geli(8) loader variables conventions

  The geli(8) manual page has an example for preloading keyfiles during boot.
  There is no detail though on how the lookup of these variables actually
  works.

  Let's document that the name of a device does not have to be a part
  of the variable.

  PR:		243261
  Submitted by:	johannes@jo-t.de
  Approved by:	bcr (mentor)
  MFC after:	3 weeks
  Differential Revision:	https://reviews.freebsd.org/D24114

Changes:
  head/lib/geom/eli/geli.8
Comment 3 Mateusz Piotrowski freebsd_committer 2020-03-19 09:35:36 UTC
Thank you for the patch! It's a great addition to the manual page!
Comment 4 commit-hook freebsd_committer 2020-04-15 08:12:00 UTC
A commit references this bug:

Author: 0mp
Date: Wed Apr 15 08:11:19 UTC 2020
New revision: 359960
URL: https://svnweb.freebsd.org/changeset/base/359960

Log:
  MFC 359125:

  Document geli(8) loader variables conventions

  The geli(8) manual page has an example for preloading keyfiles during boot.
  There is no detail though on how the lookup of these variables actually
  works.

  Let's document that the name of a device does not have to be a part
  of the variable.

  PR:		243261
  Submitted by:	johannes@jo-t.de
  Approved by:	bcr (mentor)
  Differential Revision:	https://reviews.freebsd.org/D24114

Changes:
_U  stable/12/
  stable/12/lib/geom/eli/geli.8