From nobody Mon Jul 14 17:27:00 2025 X-Original-To: dev-commits-src-all@mlmmj.nyi.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mlmmj.nyi.freebsd.org (Postfix) with ESMTP id 4bgq4j2pTZz620r9; Mon, 14 Jul 2025 17:27:01 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from mxrelay.nyi.freebsd.org (mxrelay.nyi.freebsd.org [IPv6:2610:1c1:1:606c::19:3]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256 client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "R10" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 4bgq4j0CyHz3X9g; Mon, 14 Jul 2025 17:27:01 +0000 (UTC) (envelope-from git@FreeBSD.org) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1752514021; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=gg6jMp7dchFosPoiIV178f5qibAdHR/VvsTy+btaNFM=; b=AE1Tb0PPj0w/1bOdKMini4yQz67X/se0RNghjQI8X4juIn9+Hk2RXf+oDOimxumTVxfSxB FWAbr6K9FYA1wFEMrYKzecEX6zoFl7uyAK8BVqNfFcVLIXZvLWsQqwea5My77KIEOFcoZm 2jtMYpvUfeuCcTfJ6R/IrFBjGJBxPc+thxXJgoHlNHRO7CZf3ppZzfPOlSwOQw8Gvwf7zd 56oDeCYrYhawmeVx82RGtkSiJtDDUQWoBqRwW/KMsPm0+nHIYU8PMG4vyLZu875xdoxqjX sAeiq4a1XfTnndoMm2fxev9lgw86XRSbhF2z2H6x/XrGbPh6p719dhItZ2jS+g== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=freebsd.org; s=dkim; t=1752514021; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=gg6jMp7dchFosPoiIV178f5qibAdHR/VvsTy+btaNFM=; b=BwA2zCXUUomH1TT5MbMwIr5/NyVV/cVAdafjhZESgZPgfXL9L+8cGJLfxA9IqkMkgvVnwE YX2112T/2o7wBab5KqVcQ8wf2CLxbbqmDX0frIDHlUDoUvchifOr/6ZZsFgcr1Gc3yCfq+ Zs2fsjprMwlEhSDP6SOZrkw/WXkZhFYYhjdE2c4YS9et99sqXaC5Q/yljXqQIv2Le7j2KS +ln2FajpUjbbyLATaNoWqh4QScm0N//T5/I3LNZa/HKT557PwikSBYLw2V+WO/gPJP/NtW KyY6ELgtjLRnOKzO7QV3xTZAHr+uBblEkhuOzua2xJWK/VIbX663k357Z/J9LA== ARC-Authentication-Results: i=1; mx1.freebsd.org; none ARC-Seal: i=1; s=dkim; d=freebsd.org; t=1752514021; a=rsa-sha256; cv=none; b=mmhGHIwNjgosFPXAosC2HQ+Jv9gXKo7vYHu8RqujnfGgp/jD4p6HLeNEdo7ukPm2ZE7x5y EFHeJtZ99AxYl6/LNkBGfJB7Uwnwx7XpB+s7hCbKd0MmzhKUWvjtYw9UeQpmZyTmkSbtNz kKbmSz9T/0DF7Y4c4iORHEr1hrt5g24OrMPcl/7f3VPatXRW4ePDZdRGraB58uwizDMuF0 5ilx6r1KWSX2zuDFU/O/DU15P41xxxcIPOxv5jy+gfTiN+xGp30LEzexNQEb6pU9ZKm5GF pqbqXUCjnfrevJ2tQshIFKpSUILd8jiYTuVnSLmPBPZMLn+5ZiXxhPM8ESLP8Q== Received: from gitrepo.freebsd.org (gitrepo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:5]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange X25519 server-signature RSA-PSS (4096 bits) server-digest SHA256) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 4bgq4h6k5Yz13fS; Mon, 14 Jul 2025 17:27:00 +0000 (UTC) (envelope-from git@FreeBSD.org) Received: from gitrepo.freebsd.org ([127.0.1.44]) by gitrepo.freebsd.org (8.18.1/8.18.1) with ESMTP id 56EHR07m041211; Mon, 14 Jul 2025 17:27:00 GMT (envelope-from git@gitrepo.freebsd.org) Received: (from git@localhost) by gitrepo.freebsd.org (8.18.1/8.18.1/Submit) id 56EHR0PD041208; Mon, 14 Jul 2025 17:27:00 GMT (envelope-from git) Date: Mon, 14 Jul 2025 17:27:00 GMT Message-Id: <202507141727.56EHR0PD041208@gitrepo.freebsd.org> To: src-committers@FreeBSD.org, dev-commits-src-all@FreeBSD.org, dev-commits-src-branches@FreeBSD.org From: Alexander Ziaee Subject: git: 23e4075a4add - stable/14 - bectl.8: Describe better List-Id: Commit messages for all branches of the src repository List-Archive: https://lists.freebsd.org/archives/dev-commits-src-all List-Help: List-Post: List-Subscribe: List-Unsubscribe: X-BeenThere: dev-commits-src-all@freebsd.org Sender: owner-dev-commits-src-all@FreeBSD.org MIME-Version: 1.0 Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: 8bit X-Git-Committer: ziaee X-Git-Repository: src X-Git-Refname: refs/heads/stable/14 X-Git-Reftype: branch X-Git-Commit: 23e4075a4add6af5d83be3bd47779a99667cff7a Auto-Submitted: auto-generated The branch stable/14 has been updated by ziaee: URL: https://cgit.FreeBSD.org/src/commit/?id=23e4075a4add6af5d83be3bd47779a99667cff7a commit 23e4075a4add6af5d83be3bd47779a99667cff7a Author: Alexander Ziaee AuthorDate: 2025-06-13 19:37:23 +0000 Commit: Alexander Ziaee CommitDate: 2025-07-14 17:24:13 +0000 bectl.8: Describe better + Concise document description for consistency and apropos results + Improve introductory paragraph, mentioning boot loader support + Explain -r in "Supported Subcommands and Flags" + Clarify the purpose of the check subcommand + Add two basic examples, creating and mounting + Fold some long lines, correct a stray capitalization. MFC after: 3 days Co-authored-by: kevans (cherry picked from commit d7baf5f70802a9045f5792a7063b2614bf17356a) --- sbin/bectl/bectl.8 | 121 ++++++++++++++++++++++++++++------------------------- 1 file changed, 65 insertions(+), 56 deletions(-) diff --git a/sbin/bectl/bectl.8 b/sbin/bectl/bectl.8 index a77039c94d26..fd939f20e694 100644 --- a/sbin/bectl/bectl.8 +++ b/sbin/bectl/bectl.8 @@ -5,12 +5,12 @@ .\" .\" @(#)be.1 .\" -.Dd March 18, 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 @@ -82,34 +82,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 @@ -124,19 +121,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 @@ -164,8 +161,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 @@ -176,8 +173,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. @@ -243,8 +242,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 @@ -271,11 +270,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. @@ -300,8 +299,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 @@ -353,8 +352,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 , @@ -364,7 +363,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. @@ -392,8 +391,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 @@ -421,7 +420,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 @@ -447,8 +447,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 @@ -470,16 +470,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