1 files changed, 65 insertions, 56 deletions
diff --git a/sbin/bectl/bectl.8 b/sbin/bectl/bectl.8
index cc88c7019d13..0e08b3383e9a 100644
--- a/sbin/bectl/bectl.8
+++ b/sbin/bectl/bectl.8
@@ -3,12 +3,12 @@
 .\"
 .\" SPDX-License-Identifier: BSD-2-Clause
 .\"
-.Dd April 9, 2024
+.Dd June 13, 2025
 .Dt BECTL 8
 .Os
 .Sh NAME
 .Nm bectl
-.Nd Utility to manage boot environments on ZFS
+.Nd manage ZFS boot environments
 .Sh SYNOPSIS
 .Nm
 .Op Fl h
@@ -80,34 +80,31 @@
 .Sh DESCRIPTION
 The
 .Nm
-command is used to setup and interact with ZFS boot environments, which are
-bootable clones of datasets.
-.Pp
-A boot environment allows the system to be upgraded, while preserving the
-pre-upgrade system environment.
-.Pp
-.Nm
-itself accepts an
-.Fl r
-flag specified before the command to indicate the
-.Ar beroot
-that should be used as the boot environment root, or the dataset whose children
-are all boot environments.
-Normally this information is derived from the bootfs property of the pool that
-is mounted at
-.Pa / ,
-but it is useful when the system has not been booted into a ZFS root or a
-different pool should be operated on.
-For instance, booting into the recovery media and manually importing a pool from
-one of the system's resident disks will require the
-.Fl r
-flag to work.
+utility manages bootable ZFS clones called boot environments.
+Boot envionments allow system changes to be tested safely,
+as they are selectable directly from the boot
+.Xr loader 8 .
+This utility can
+.Cm create ,
+.Cm list ,
+.Cm mount ,
+or
+.Cm jail
+boot environments.
+Once the changes have been tested, the boot environment can be
+.Cm unmount Ns ed ,
+.Cm activate Ns d ,
+.Cm rename Ns d ,
+and
+.Cm destroy Ns ed .
 .Ss Supported Subcommands and Flags
-.Bl -tag -width activate
-.It Xo
-.Fl h
-.Xc
+.Bl -tag -width indent
+.It Fl h
 Print usage information and exit.
+.It Fl r Ar beroot Sy Ar subcommand
+Specify a parent dataset for the boot environment to use for
+.Ar subcommand
+for operation on manually imported pools or unusual layouts.
 .It Xo
 .Cm activate
 .Op Fl t | Fl T
@@ -122,19 +119,19 @@ flag is given, this takes effect only for the next boot.
 Flag
 .Fl T
 removes temporary boot once configuration.
-Without temporary configuration, the next boot will use zfs dataset specified
-in boot pool
+Without temporary configuration,
+the next boot will use zfs dataset specified in boot pool
 .Ar bootfs
 property.
 .It Xo
 .Cm check
 .Xc
-Performs a silent sanity check on the current system.
+Perform a check to see if the current system can use boot environments.
 If boot environments are supported and used,
 .Nm
 will exit with a status code of 0.
-Any other status code is not currently defined and may, in the future, grow
-special meaning for different degrees of sanity check failures.
+Any other status code is not currently defined and may, in the future,
+grow special meaning for different degrees of sanity check failures.
 .It Xo
 .Cm create
 .Op Fl r
@@ -162,8 +159,8 @@ environment.
 .Pp
 If
 .Nm
-is creating from another boot environment, a snapshot of that boot environment
-will be created to clone from.
+is creating from another boot environment,
+a snapshot of that boot environment will be created to clone from.
 .It Xo
 .Cm create
 .Op Fl r
@@ -174,8 +171,10 @@ Create a snapshot of the boot environment named
 .Pp
 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.
+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.
@@ -241,8 +240,8 @@ If
 .Ar utility
 is specified, it will be executed instead of
 .Pa /bin/sh .
-The jail will be destroyed and the boot environment unmounted when the command
-finishes executing, unless the
+The jail will be destroyed and the boot environment unmounted
+when the command finishes executing, unless the
 .Fl U
 argument is specified.
 .Pp
@@ -269,11 +268,11 @@ The following default parameters are provided:
 .It Va allow.mount Ta Cm true
 .It Va allow.mount.devfs Ta Cm true
 .It Va enforce_statfs Ta Cm 1
-.It Va name Ta Set to jail ID.
+.It Va name Ta set to jail ID
 .It Va host.hostname Ta Va bootenv
-.It Va path Ta Set to a path in Pa /tmp
+.It Va path Ta set to a path in Pa /tmp
 generated by
-.Xr libbe 3 .
+.Xr libbe 3
 .El
 .Pp
 All default parameters may be overwritten.
@@ -298,8 +297,8 @@ or combination of
 .It Fl a
 Display all datasets.
 .It Fl D
-Display the full space usage for each boot environment, assuming all
-other boot environments were destroyed.
+Display the full space usage for each boot environment,
+assuming all other boot environments were destroyed.
 .It Fl H
 Used for scripting.
 Do not print headers and separate fields by a single tab instead of
@@ -351,8 +350,8 @@ will make a directory such as
 .Pa be_mount.c6Sf
 in
 .Pa /tmp .
-Randomness in the last four characters of the directory name will prevent
-mount point conflicts.
+Randomness in the last four characters of the directory name
+will prevent mount point conflicts.
 Unmount of an environment, followed by mount of the same environment
 without giving a
 .Ar mountpoint ,
@@ -362,7 +361,7 @@ Rename the given
 .Ar origBeName
 to the given
 .Ar newBeName .
-The boot environment will not be unmounted in order for this rename to occur.
+The boot environment will not be unmounted for this rename to occur.
 .It Cm ujail Brq Ar jailId | jailName | beName
 .It Cm unjail Brq Ar jailId | jailName | beName
 Destroy the jail created from the given boot environment.
@@ -390,8 +389,8 @@ 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.
+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
@@ -419,7 +418,8 @@ set to
 .Dv off ,
 thus files in
 .Pa /usr
-typically fall into the boot environment because this dataset is not mounted.
+typically fall into the boot environment
+because this dataset is not mounted.
 .Pa zroot/usr/src
 is mounted, thus files in
 .Pa /usr/src
@@ -445,8 +445,8 @@ 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 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
@@ -468,16 +468,25 @@ A future version of
 may default to handling both styles and deprecate the various
 .Fl r
 flags.
-.\" .Sh EXAMPLES
-.\" .Bl -bullet
-.\" .It
+.Sh EXAMPLES
+Create a boot environment, named with today's date,
+containing snapshots of the root dataset and of all child datasets:
+.Pp
+.Dl bectl create -r `date +%Y%m%d`
+.Pp
+Mount a previous boot environment,
+.Ar yesterdaysbe ,
+to
+.Pa /mnt :
+.Pp
+.Dl bectl mount yesterdaysbe /mnt
 .\" To fill in with jail upgrade example when behavior is firm.
-.\" .El
 .Sh SEE ALSO
 .Xr libbe 3 ,
 .Xr zfsprops 7 ,
 .Xr beinstall.sh 8 ,
 .Xr jail 8 ,
+.Xr loader 8 ,
 .Xr zfs 8 ,
 .Xr zpool 8
 .Sh HISTORY