Date: Wed, 6 Apr 2022 03:41:12 GMT From: Kyle Evans <kevans@FreeBSD.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org Subject: git: af21459aca19 - stable/12 - bectl: add some discussion about boot environment layouts Message-ID: <202204060341.2363fCNf088648@gitrepo.freebsd.org>
next in thread | raw e-mail | index | archive | help
The branch stable/12 has been updated by kevans: URL: https://cgit.FreeBSD.org/src/commit/?id=af21459aca19aa0d4bc35ce367682a41ce42a8bd commit af21459aca19aa0d4bc35ce367682a41ce42a8bd Author: Kyle Evans <kevans@FreeBSD.org> AuthorDate: 2022-03-31 22:41:53 +0000 Commit: Kyle Evans <kevans@FreeBSD.org> CommitDate: 2022-04-06 03:40:31 +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. (cherry picked from commit c0f846ff235296249271b1235ff6a52b7d23cefb) --- 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 809a0d2f51a8..ed0029afe78f 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 @@ -124,6 +124,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 @@ -148,6 +151,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 @@ -336,6 +342,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
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?202204060341.2363fCNf088648>