git: 41e0b07a5e2a - releng/13.1 - bectl: add some discussion about boot environment layouts

The branch releng/13.1 has been updated by kevans:

URL: https://cgit.FreeBSD.org/src/commit/?id=41e0b07a5e2a42cc2d6532ee529b6190bd14a69d

commit 41e0b07a5e2a42cc2d6532ee529b6190bd14a69d
Author:     Kyle Evans <kevans@FreeBSD.org>
AuthorDate: 2022-03-31 22:41:53 +0000
Commit:     Kyle Evans <kevans@FreeBSD.org>
CommitDate: 2022-04-06 14:32:48 +0000

    bectl: add some discussion about boot environment layouts
    
    Discuss the standard type of layout, as well as the "deep" BE layout,
    and some of the properties of both.  Point the various -r flags at this
    new section, to help users understand which they're working with and
    what the -r flag is actually doing. Note that we may just deprecate the
    -r flag in future versions, but the flag will be recognized as a NOP at
    that point.
    
    Approved by:    re (gjb)
    
    (cherry picked from commit c0f846ff235296249271b1235ff6a52b7d23cefb)
    (cherry picked from commit 0e90da6549d177874437dc2e7bab085873538da2)
---
 sbin/bectl/bectl.8 | 92 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 91 insertions(+), 1 deletion(-)

diff --git a/sbin/bectl/bectl.8 b/sbin/bectl/bectl.8
index 4b7868e093eb..79bdec751a86 100644
--- a/sbin/bectl/bectl.8
+++ b/sbin/bectl/bectl.8
@@ -17,7 +17,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd January 6, 2021
+.Dd March 31, 2022
 .Dt BECTL 8
 .Os
 .Sh NAME
@@ -131,6 +131,9 @@ Create a new boot environment named
 If the
 .Fl r
 flag is given, a recursive boot environment will be made.
+See
+.Sx Boot Environment Structures
+for a discussion on different layouts.
 .Pp
 If the
 .Fl e
@@ -155,6 +158,9 @@ If the
 .Fl r
 flag is given, a recursive snapshot of the boot environment will be created.
 A snapshot is created for each descendant dataset of the boot environment.
+See
+.Sx Boot Environment Structures
+for a discussion on different layouts.
 .Pp
 No new boot environment is created with this command.
 .It Xo
@@ -345,6 +351,90 @@ prints usage information if
 or
 .Fl \&?
 is specified.
+.Ss Boot Environment Structures
+The traditional
+.Fx
+boot environment layout, as created by the Auto ZFS option to
+.Xr bsdinstall 8 ,
+is a
+.Dq shallow
+boot environment structure, where boot environment datasets do not have any
+directly subordinate datasets.
+Instead, they're organized off in
+.Pa zroot/ROOT ,
+and they rely on datasets elsewhere in the pool having
+.Dv canmount
+set to
+.Dv off .
+For instance, a simplified pool may be laid out as such:
+.Bd -literal -offset indent
+% zfs list -o name,canmount,mountpoint
+NAME			CANMOUNT	MOUNTPOINT
+zroot
+zroot/ROOT		noauto		none
+zroot/ROOT/default	noauto		none
+zroot/usr		off		/usr
+zroot/usr/home		on		/usr/home
+zroot/var		on		/var
+.Ed
+.Pp
+In that example,
+.Pa zroot/usr
+has
+.Dv canmount
+set to
+.Dv off ,
+thus files in
+.Pa /usr
+typically fall into the boot environment because this dataset is not mounted.
+.Pa zroot/usr/home
+is mounted, thus files in
+.Pa /usr/home
+are not in the boot environment.
+.Pp
+The other style of boot environments in use, frequently called
+.Dq deep boot environments ,
+organizes some or all of the boot environment as subordinate to the boot
+environment dataset.
+For example:
+.Bd -literal -offset indent
+% zfs list -o name,canmount,mountpoint
+NAME				CANMOUNT	MOUNTPOINT
+zroot
+zroot/ROOT			noauto		none
+zroot/ROOT/default		noauto		none
+zroot/ROOT/default/usr		noauto		/usr
+zroot/ROOT/default/usr/local	noauto		/usr/local
+zroot/var			on		/var
+.Ed
+.Pp
+Note that the subordinate datasets now have
+.Dv canmount
+set to
+.Dv noauto .
+These are more obviously a part of the boot environment, as indicated by their
+positioning in the layout.
+These subordinate datasets will be mounted by the
+.Dv zfsbe
+.Xr rc 8
+script at boot time.
+In this example,
+.Pa /var
+is excluded from the boot environment.
+.Pp
+.Nm
+commands that have their own
+.Fl r
+operate on this second,
+.Dq deep
+style of boot environment, when the
+.Fl r
+flag is set.
+A future version of
+.Nm
+may default to handling both styles and deprecate the various
+.Fl r
+flags.
 \" .Sh EXAMPLES
 \" .Bl -bullet
 \" .It