1 files changed, 92 insertions, 90 deletions
diff --git a/sbin/bectl/bectl.8 b/sbin/bectl/bectl.8
index 718f4e2597ae..0e08b3383e9a 100644
--- a/sbin/bectl/bectl.8
+++ b/sbin/bectl/bectl.8
@@ -1,29 +1,17 @@
 .\"
-.\" SPDX-License-Identifier: BSD-2-Clause
-.\"
 .\" Copyright (c) 2017 Kyle J. Kneitinger <kyle@kneit.in>
 .\"
-.\" Redistribution and use in source and binary forms, with or without
-.\" modification, are permitted provided that the following conditions
-.\" are met:
-.\" 1. Redistributions of source code must retain the above copyright
-.\"    notice, this list of conditions and the following disclaimer.
-.\" 2. Redistributions in binary form must reproduce the above copyright
-.\"    notice, this list of conditions and the following disclaimer in the
-.\"    documentation and/or other materials provided with the distribution.
-.\"
-.\"
-.\"     @(#)be.1
+.\" SPDX-License-Identifier: BSD-2-Clause
 .\"
-.Dd June 28, 2023
+.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\&?
+.Op Fl h
 .Nm
 .Op Fl r Ar beroot
 .Cm activate
@@ -92,35 +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.
-.Pp
+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 |
-.Fl \&?
-Print usage information.
+.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
@@ -135,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
@@ -175,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
@@ -187,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.
@@ -204,7 +190,7 @@ Destroy the given
 boot environment or
 .Ar beName Ns Cm @ Ns Ar snapshot
 snapshot without confirmation, unlike in
-.Xr beadm 1 .
+.Xr beadm 8 .
 Specifying
 .Fl F
 will automatically unmount without confirmation.
@@ -254,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
@@ -282,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.
@@ -311,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
@@ -364,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 ,
@@ -375,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.
@@ -396,7 +382,6 @@ will force the unmount if busy.
 .Pp
 Unmount will not remove the mount point.
 .El
-.Pp
 .Ss Boot Environment Structures
 The traditional
 .Fx
@@ -404,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
@@ -433,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
@@ -459,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
@@ -482,34 +468,50 @@ A future version of
 may default to handling both styles and deprecate the various
 .Fl r
 flags.
-\" .Sh EXAMPLES
-\" .Bl -bullet
-\" .It
-\" To fill in with jail upgrade example when behavior is firm.
-\" .El
+.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.
 .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
 .Nm
-is based on
-.Xr beadm 1
-and was implemented as a project for the 2017 Summer of Code, along with
-.Xr libbe 3 .
-.Sh AUTHORS
-.Nm
-was written by
-.An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in .
-.Pp
-.Xr beadm 1
-was written and is maintained by
-.An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl .
+and
+.Xr libbe 3
+were written by
+.An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in
+as a 2017 Google Summer of Code project, with
+.An Allan Jude (allanjude) Aq Mt allanjude@freebsd.org
+as mentor.
 .Pp
+.Nm
+and this manual page were derived from
+.Xr beadm 8 .
+.Sh AUTHORS
+.An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl
+is the creator and maintainer of
+.Xr beadm 8 .
 .An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net
-wrote the original
-.Xr beadm 1
-manual page that this one is derived from.
+contributed child dataset fixes, and wrote the
+.Xr beadm 8
+manual page.
+.Pp
+Most later changes to
+.Nm ,
+and to this page, were written by
+.An Kyle Evans (kevans) Aq Mt kevans@freebsd.org .