svn commit: r352086 - stable/12/sbin/bectl

Mon Sep 9 17:53:16 UTC 2019

Author: kevans
Date: Mon Sep  9 17:53:15 2019
New Revision: 352086
URL: https://svnweb.freebsd.org/changeset/base/352086

Log:
  MFC r345845-r345846: bectl(8) manpage clarity
  
  r345845:
  bectl.8: Clean up & clarify the create subcommand
  
  - Improve formatting
  - Use consistent variable names
  - Improve the description of the create subcommand (1)
  
  PR:		235850
  
  r345846:
  bectl.8: Bump date after r345845

Modified:
  stable/12/sbin/bectl/bectl.8
Directory Properties:
  stable/12/   (props changed)

Modified: stable/12/sbin/bectl/bectl.8
==============================================================================

--- stable/12/sbin/bectl/bectl.8	Mon Sep  9 17:44:14 2019	(r352085)
+++ stable/12/sbin/bectl/bectl.8	Mon Sep  9 17:53:15 2019	(r352086)
@@ -18,12 +18,12 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd May 12, 2019
+.Dd September 9, 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 at 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 at snapshot
-.Nm
 .Cm destroy
 .Op Fl \&Fo
-.Brq Ar beName | beName at 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,28 +99,27 @@ 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 at 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 at snapshot .
-If the
 .Fl r
 flag is given, a recursive boot environment will be made.
-.It Xo
-.Cm create
-.Op Fl r
-.Ar beName at 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 create
 .Op Fl r
@@ -139,14 +137,14 @@ No new boot environment is created with this command.
 .It Xo
 .Cm destroy
 .Op Fl \&Fo
-.Brq Ar beName | beName at snapshot
+.Ar beName Ns Op Cm @ Ns Ar snapshot
 .Xc
-Destroys the given
+Destroy the given
 .Ar beName
 boot environment or
-.Ar beName at 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.
@@ -162,22 +160,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
@@ -216,7 +214,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:
@@ -224,17 +222,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
@@ -257,14 +262,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
@@ -274,12 +285,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 ,
@@ -287,7 +306,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
@@ -295,11 +314,11 @@ and was implemented as a project for the 2017 Summer o
 was written by
 .An Kyle Kneitinger (kneitinger) Aq Mt kyle at kneit.in .
 .Pp
-.Nm beadm
+.Xr beadm 1
 was written and is maintained by
 .An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden at interia.pl .
 .Pp
 .An Bryan Drewery (bdrewery) Aq Mt bryan at shatow.net
 wrote the original
-.Nm beadm
+.Xr beadm 1
 manual page that this one is derived from.
