Date: Wed, 3 Apr 2019 13:46:43 +0000 (UTC) From: Mateusz Piotrowski <0mp@FreeBSD.org> To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r345845 - head/sbin/bectl Message-ID: <201904031346.x33DkhH3052471@repo.freebsd.org>
next in thread | raw e-mail | index | archive | help
Author: 0mp (ports committer) Date: Wed Apr 3 13:46:43 2019 New Revision: 345845 URL: https://svnweb.freebsd.org/changeset/base/345845 Log: bectl.8: Clean up & clarify the create subcommand - Improve formatting - Use consistent variable names - Improve the description of the create subcommand (1) PR: 235850 (1) Submitted by: kevans (1) Reported by: ler (1) Reviewed by: kevans Approved by: src (kevans) Differential Revision: https://reviews.freebsd.org/D19666 Modified: head/sbin/bectl/bectl.8 Modified: head/sbin/bectl/bectl.8 ============================================================================== --- head/sbin/bectl/bectl.8 Wed Apr 3 13:19:47 2019 (r345844) +++ head/sbin/bectl/bectl.8 Wed Apr 3 13:46:43 2019 (r345845) @@ -18,12 +18,12 @@ .\" .\" $FreeBSD$ .\" -.Dd February 10, 2019 +.Dd March 21, 2019 .Dt BECTL 8 .Os .Sh NAME .Nm bectl -.Nd Utility to manage Boot Environments on ZFS +.Nd Utility to manage boot environments on ZFS .Sh SYNOPSIS .Nm .Cm activate @@ -32,16 +32,12 @@ .Nm .Cm create .Op Fl r -.Op Fl e Brq Ar nonActiveBe | beName@snapshot -.Ar beName +.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot +.Ar newBeName .Nm -.Cm create -.Op Fl r -.Ar beName@snapshot -.Nm .Cm destroy .Op Fl \&Fo -.Brq Ar beName | beName@snapshot +.Ar beName Ns Op Cm @ Ns Ar snapshot .Nm .Cm export .Ar sourceBe @@ -50,39 +46,42 @@ .Ar targetBe .Nm .Cm jail -.Brq Fl b | Fl U -.Oo Bro Fl o Ar key Ns = Ns Ar value | Fl u Ar key Brc Oc Ns ... -.Ar bootenv +.Op Fl bU +.Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ... +.Ar beName .Op Ar utility Op Ar argument ... .Nm .Cm list -.Op Fl DHas +.Op Fl aDHs .Nm .Cm mount .Ar beName -.Op mountpoint +.Op Ar mountpoint .Nm .Cm rename .Ar origBeName .Ar newBeName .Nm .Brq Cm ujail | unjail -.Brq Ar jailID | jailName -.Ar bootenv +.Brq Ar jailId | jailName +.Ar beName .Nm .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 -.Em Boot Environments -allows the system to be upgraded, while preserving the old system environment in +Boot environments +allow the system to be upgraded, while preserving the old system environment in a separate ZFS dataset. -.Sh COMMANDS +.Pp The following commands are supported by .Nm : .Bl -tag -width activate @@ -100,39 +99,38 @@ flag is given, this takes effect only for the next boo .It Xo .Cm create .Op Fl r -.Op Fl e Brq Ar nonActiveBe | beName@snapshot -.Ar beName +.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot +.Ar newBeName .Xc -Creates a new boot environment named -.Ar beName . +Create a new boot environment named +.Ar newBeName . +.Pp If the -.Fl e -argument is specified, the new environment will be cloned from the given -.Brq Ar nonActiveBe | Ar beName@snapshot . -If the .Fl r flag is given, a recursive boot environment will be made. -.It Xo -.Cm create -.Op Fl r -.Ar beName@snapshot -.Xc -Creates a snapshot of the existing boot environment named -.Ar beName . +.Pp If the -.Fl r -flag is given, a recursive boot environment will be made. +.Fl e +flag is specified, the new environment will be cloned from the given +.Ar nonActiveBe +or +.Ar beName Ns Cm @ Ns Ar snapshot . +Otherwise, the new environment will be created from the currently booted environment. +.Pp +If +.Nm +is creating from another boot environment, a snapshot of that boot environment will be created to clone from. .It Xo .Cm destroy .Op Fl \&Fo -.Brq Ar beName | beName@snapshot +.Ar beName Ns Op Cm @ Ns Ar snapshot .Xc -Destroys the given +Destroy the given .Ar beName boot environment or -.Ar beName@snapshot +.Ar beName Ns Cm @ Ns Ar snapshot snapshot without confirmation, unlike in -.Nm beadm . +.Xr beadm 1 . Specifying .Fl F will automatically unmount without confirmation. @@ -148,22 +146,22 @@ flag may be specified to destroy the origin as well. Export .Ar sourceBe to -.Dv stdout . -.Dv stdout +.Xr stdout 4 . +.Xr stdout 4 must be piped or redirected to a file. .It Cm import Ar targetBe Import .Ar targetBe from -.Dv stdin . +.Xr stdin 4 . .It Xo .Cm jail -.Brq Fl b | Fl U -.Oo Bro Fl o Ar key Ns = Ns Ar value | Fl u Ar key Brc Oc Ns ... -.Ao Ar bootenv Ac +.Op Fl bU +.Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ... +.Ar beName .Op Ar utility Op Ar argument ... .Xc -Creates a jail of the given boot environment. +Create a jail of the given boot environment. Multiple .Fl o and @@ -202,7 +200,7 @@ and must be set, the default values are specified below. .Pp All -.Ar key Ns = Ns Ar value +.Ar key Ns Cm = Ns Ar value pairs are interpreted as jail parameters as described in .Xr jail 8 . The following default parameters are provided: @@ -210,17 +208,24 @@ 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 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 /tmp generated by +.It Va path Ta Set to a path in Pa /tmp +generated by .Xr libbe 3 . .El .Pp All default parameters may be overwritten. -.It Cm list Op Fl DHas -Displays all boot environments. -The Active field indicates whether the boot environment is active now (N); -active on reboot (R); or both (NR). +.It Cm list Op Fl aDHs +Display all boot environments. +The +.Em Active +field indicates whether the boot environment is active now +.Pq Em \&N ; +active on reboot +.Pq Em \&R ; +or both +.Pq Em \&NR . .Pp If .Fl a @@ -243,14 +248,20 @@ Mount at the specified .Ar mountpoint if provided. .It Cm rename Ar origBeName newBeName -Renames the given +Rename the given .Ar origBeName to the given .Ar newBeName . The boot environment will not be unmounted in order for this rename to occur. -.It Cm unjail Brq Ar jailID | jailName | beName -Destroys the jail created from the given boot environment. +.It Cm ujail Bro Ar jailId | jailName Brc Ar beName +.It Cm unjail Bro Ar jailId | jailName Brc Ar beName +Destroy the jail created from the given boot environment. .It Xo +.Cm umount +.Op Fl f +.Ar beName +.Xc +.It Xo .Cm unmount .Op Fl f .Ar beName @@ -260,12 +271,20 @@ Specifying .Fl f will force the unmount if busy. .El +.Pp +.Nm +prints usage information if +.Fl h +or +.Fl \&? +is specified. .Sh EXAMPLES .Bl -bullet .It To fill in with jail upgrade example when behavior is firm. .El .Sh SEE ALSO +.Xr beinstall.sh 1 , .Xr libbe 3 , .Xr jail 8 , .Xr zfs 8 , @@ -273,7 +292,7 @@ To fill in with jail upgrade example when behavior is .Sh HISTORY .Nm is based on -.Nm beadm +.Xr beadm 1 and was implemented as a project for the 2017 Summer of Code, along with .Xr libbe 3 . .Sh AUTHORS @@ -281,11 +300,11 @@ and was implemented as a project for the 2017 Summer o was written by .An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in . .Pp -.Nm beadm +.Xr beadm 1 was written and is maintained by .An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl . .Pp .An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net wrote the original -.Nm beadm +.Xr beadm 1 manual page that this one is derived from.
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201904031346.x33DkhH3052471>