Page MenuHomeFreeBSD
Files F147637633

D50838.1783951397.diff
No OneTemporary
Actions

Size
6 KB
Referenced Files
None
Subscribers
None

D50838.1783951397.diff
View Options

diff --git a/sbin/bectl/bectl.8 b/sbin/bectl/bectl.8
--- 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.
.It Xo
.Cm activate
.Op Fl t | Fl T
@@ -122,19 +119,19 @@
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 @@
.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 @@
.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 @@
.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 @@
.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 @@
.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 @@
.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 @@
.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 @@
.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 @@
.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 @@
.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,24 @@
may default to handling both styles and deprecate the various
.Fl r
flags.
-.\" .Sh EXAMPLES
-.\" .Bl -bullet
-.\" .It
+.Sh EXAMPLES
+Create a recursive boot environment, named with today's date:
+.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

File Metadata

Mime Type
text/plain
Expires
Mon, Jul 13, 2:03 PM (12 m, 49 s)
Storage Engine
blob
Storage Format
Raw Data
Storage Handle
29112540
Default Alt Text
D50838.1783951397.diff (6 KB)

Event Timeline