d/freebsd-skq
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

bectl.8: Clean up & clarify the create subcommand

Browse Source 
- 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
This commit is contained in:
0mp 2019-04-03 13:46:43 +00:00
parent 66028726ba
commit 72c3605219
1 changed files with 81 additions and 62 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

143
sbin/bectl/bectl.8
View File

@ -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
.Nm
.Cm create
.Op Fl r
.Ar beName@snapshot
.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
.Ar newBeName
.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 boot.
.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 r
flag is given, a recursive boot environment will be made.
.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 .
If the
.Fl r
flag is given, a recursive boot environment will be made.
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,13 +248,19 @@ 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
@ -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 firm.
.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 of Code, along with
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.