svn commit: r363651 - stable/12/lib/geom/eli

[Gordon Bergling]

Author: gbe (doc committer)
Date: Tue Jul 28 16:10:51 2020
New Revision: 363651
URL: https://svnweb.freebsd.org/changeset/base/363651

Log:
  MFC r363363, r363416: geli(8): new example with file based storage
  
  r363363:
  geli(8): Add an example on how to use geli(8) with a file as encrypted storage
  
  Reviewed by:	bcr (mentor)
  Approved by:	bcr (mentor)
  Differential Revision:	https://reviews.freebsd.org/D25741
  
  r363416:
  geli(8): Add missing commands in the EXAMPLES section
  
  Reported by:	Fabian Keil <freebsd-listen at fabiankeil dot de>
  Reviewed by:	bcr (mentor)
  Approved by:	bcr (mentor)
  Differential Revision:	https://reviews.freebsd.org/D25761

Modified:
  stable/12/lib/geom/eli/geli.8
Directory Properties:
  stable/12/   (props changed)

Modified: stable/12/lib/geom/eli/geli.8
==============================================================================
--- stable/12/lib/geom/eli/geli.8	Tue Jul 28 16:08:14 2020	(r363650)
+++ stable/12/lib/geom/eli/geli.8	Tue Jul 28 16:10:51 2020	(r363651)
@@ -24,7 +24,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd March 19, 2020
+.Dd July 22, 2020
 .Dt GELI 8
 .Os
 .Sh NAME
@@ -1094,6 +1094,66 @@ resuming the laptop:
 # geli resume gpt/private
 Enter passphrase:
 .Ed
+.Pp
+To create a
+.Nm
+encrypted filesystem with a file as storage device follow this example.
+First a file named private0 is created in
+.Pa /usr
+and attached as a memory disk like
+.Pa /dev/md0
+for example.
+.Bd -literal -offset indent
+# dd if=/dev/zero of=/usr/private0 bs=1m count=256
+# chmod 0600 /usr/private0
+# mdconfig -t vnode -f /usr/private0
+.Ed
+.Pp
+It is recommended to place the following line in
+.Xr rc.conf 5
+to have the memory disk automatically created during boot.
+.Bd -literal -offset indent
+mdconfig_md0="-t vnode -f /usr/private0"
+.Ed
+.Pp
+After
+.Pa /dev/md0
+is created a random key has to be generated and stored in a secure location,
+like
+.Pa /root
+for example.
+This key should be protected by a passphrase, which
+is requested when geli init is called.
+.Bd -literal -offset indent
+# dd if=/dev/random of=/root/private0.key bs=64 count=1
+# geli init -K /root/private0.key -s 4096 /dev/md0
+Enter new passphrase:
+Reenter new passphrase:
+# geli attach -k /root/private0.key /dev/md0
+Enter passphrase:
+# dd if=/dev/random of=/dev/md0.eli bs=1m
+.Ed
+.Pp
+Once the initialization of the
+.Pa /dev/md0.eli
+device is ready create a UFS filesystem and mount it for example in
+.Pa /private .
+.Bd -literal -offset indent
+# newfs /dev/md0.eli
+# mount /dev/md0.eli /private
+.Ed
+.Pp
+After a system reboot the
+.Nm
+device can be mounted again with the following commands.
+The call of geli attach will ask for the passphrase.
+It is recommended to do this procedure after the boot, because otherwise
+the boot process would be waiting for the passphrase input.
+.Bd -literal -offset indent
+# geli attach -k /root/private0.key /dev/md0
+Enter passphrase:
+# mount /dev/md0.eli /private
+.Ed
 .Sh ENCRYPTION MODES
 .Nm
 supports two encryption modes:
@@ -1156,7 +1216,9 @@ block cipher was implemented by Yoshisato Yanagisawa i
 .Pp
 Highest
 .Nm GELI
-metadata version supported by the given FreeBSD version:
+metadata version supported by the given
+.Fx
+version:
 .Bl -column -offset indent ".Sy FreeBSD" ".Sy version"
 .It Sy FreeBSD Ta Sy GELI
 .It Sy version Ta Sy version