git: 20d97b6cbd74 - stable/13 - bectl(8): clarifications, expansion

From: Dag-Erling Smørgrav <>
Date: Fri, 22 Mar 2024 09:15:03 UTC
The branch stable/13 has been updated by des:


commit 20d97b6cbd7487eb930190e7a8d2d09f0f38a20e
Author:     Graham Perrin <>
AuthorDate: 2023-06-28 02:05:26 +0000
Commit:     Dag-Erling Smørgrav <>
CommitDate: 2024-03-22 08:07:34 +0000

    bectl(8): clarifications, expansion
    Reviewed-by:  imp
    (cherry picked from commit 6927176113ee775983952edb3c201fed6be318d3)
 sbin/bectl/bectl.8 | 68 ++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 43 insertions(+), 25 deletions(-)

diff --git a/sbin/bectl/bectl.8 b/sbin/bectl/bectl.8
index 2b2dd02bc8ef..45c676a7876c 100644
--- a/sbin/bectl/bectl.8
+++ b/sbin/bectl/bectl.8
@@ -15,7 +15,7 @@
 .\"     @(#)be.1
-.Dd April 26, 2023
+.Dd June 28, 2023
 .Dt BECTL 8
@@ -23,6 +23,8 @@
 .Nd Utility to manage boot environments on ZFS
+.Op Fl h\&?
 .Op Fl r Ar beroot
 .Cm activate
 .Op Fl t | Fl T
@@ -87,18 +89,14 @@
 .Brq Cm umount | unmount
 .Op Fl f
 .Ar beName
-.Op Fl h\&?
 command is used to setup and interact with ZFS boot environments, which are
 bootable clones of datasets.
-Boot environments
-allow the system to be upgraded, while preserving the old system environment in
-a separate ZFS dataset.
+A boot environment allows the system to be upgraded, while preserving the
+pre-upgrade system environment.
 itself accepts an
@@ -117,10 +115,13 @@ one of the system's resident disks will require the
 .Fl r
 flag to work.
-The following commands are supported by
-.Nm :
+.Ss Supported Subcommands and Flags
 .Bl -tag -width activate
 .It Xo
+.Fl h |
+.Fl \&?
+Print usage information.
+.It Xo
 .Cm activate
 .Op Fl t | Fl T
 .Ar beName
@@ -192,7 +193,7 @@ See
 .Sx Boot Environment Structures
 for a discussion on different layouts.
-No new boot environment is created with this command.
+No new boot environment is created with this subcommand.
 .It Xo
 .Cm destroy
 .Op Fl \&Fo
@@ -319,18 +320,20 @@ arbitrary white space.
 .It Fl s
 Display all snapshots as well.
 .It Fl c Ar property
-Sort boot environments by given property name.
+Sort boot environments by the given ZFS dataset property.
 The following properties are supported:
 .Bl -tag -width 4n -offset indent -compact
-.It name (default output)
+.It name (the default)
 .It creation
 .It origin
 .It used
-.It usedds
-.It usedsnap
-.It usedrefreserv
+.It usedbydataset
+.It usedbyrefreservation
+.It usedbysnapshots
+Short forms usedds, usedrefreserv and usedsnap are also supported.
 .It Fl C Ar property
 Same as the
 .Fl c
@@ -345,10 +348,28 @@ or
 .Fl a
 option is used.
 .It Cm mount Ar beName Op Ar mountpoint
-Temporarily mount the boot environment.
-Mount at the specified
+Mount the given boot environment.
+If a nonexistent
 .Ar mountpoint
-if provided.
+is given:
+will make the directory, including intermediate directories as required.
+If no
+.Ar mountpoint
+is given:
+will make a directory such as
+.Pa be_mount.c6Sf
+.Pa /tmp .
+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 ,
+will result in a different randomly-named mountpoint.
 .It Cm rename Ar origBeName newBeName
 Rename the given
 .Ar origBeName
@@ -372,14 +393,10 @@ Unmount the given boot environment, if it is mounted.
 .Fl f
 will force the unmount if busy.
+Unmount will not remove the mount point.
-prints usage information if
-.Fl h
-.Fl \&?
-is specified.
 .Ss Boot Environment Structures
 The traditional
@@ -452,7 +469,7 @@ In this example,
 is excluded from the boot environment.
-commands that have their own
+subcommands that have their own
 .Fl r
 operate on this second,
 .Dq deep
@@ -471,6 +488,7 @@ flags.
 \" .El
 .Xr libbe 3 ,
+.Xr zfsprops 7 ,
 .Xr 8 ,
 .Xr jail 8 ,
 .Xr zfs 8 ,