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

The branch stable/13 has been updated by des:

URL: https://cgit.FreeBSD.org/src/commit/?id=20d97b6cbd7487eb930190e7a8d2d09f0f38a20e

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

    bectl(8): clarifications, expansion
    
    Reviewed-by:  imp
    Pull-request: https://github.com/freebsd/freebsd-src/pull/728
    (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
 .Os
 .Sh NAME
@@ -23,6 +23,8 @@
 .Nd Utility to manage boot environments on ZFS
 .Sh SYNOPSIS
 .Nm
+.Op Fl h\&?
+.Nm
 .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
-.Pp
-.Nm
-.Op Fl h\&?
 .Sh DESCRIPTION
 The
 .Nm
 command is used to setup and interact with ZFS boot environments, which are
 bootable clones of datasets.
 .Pp
-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.
 .Pp
 .Nm
 itself accepts an
@@ -117,10 +115,13 @@ one of the system's resident disks will require the
 .Fl r
 flag to work.
 .Pp
-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.
 .Pp
-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:
 .Pp
 .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
 .El
+.Pp
+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.
+.Pp
+If a nonexistent
 .Ar mountpoint
-if provided.
+is given:
+.Nm
+will make the directory, including intermediate directories as required.
+.Pp
+If no
+.Ar mountpoint
+is given:
+.Nm
+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.
+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.
 Specifying
 .Fl f
 will force the unmount if busy.
+.Pp
+Unmount will not remove the mount point.
 .El
 .Pp
-.Nm
-prints usage information if
-.Fl h
-or
-.Fl \&?
-is specified.
 .Ss Boot Environment Structures
 The traditional
 .Fx
@@ -452,7 +469,7 @@ In this example,
 is excluded from the boot environment.
 .Pp
 .Nm
-commands that have their own
+subcommands that have their own
 .Fl r
 operate on this second,
 .Dq deep
@@ -471,6 +488,7 @@ flags.
 \" .El
 .Sh SEE ALSO
 .Xr libbe 3 ,
+.Xr zfsprops 7 ,
 .Xr beinstall.sh 8 ,
 .Xr jail 8 ,
 .Xr zfs 8 ,