From owner-svn-src-all@freebsd.org Wed Apr 3 13:46:44 2019 Return-Path: Delivered-To: svn-src-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2610:1c1:1:606c::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 8BCD4156EB72; Wed, 3 Apr 2019 13:46:44 +0000 (UTC) (envelope-from 0mp@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) server-signature RSA-PSS (4096 bits) client-signature RSA-PSS (4096 bits) client-digest SHA256) (Client CN "mxrelay.nyi.freebsd.org", Issuer "Let's Encrypt Authority X3" (verified OK)) by mx1.freebsd.org (Postfix) with ESMTPS id 3399D81F22; Wed, 3 Apr 2019 13:46:44 +0000 (UTC) (envelope-from 0mp@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mxrelay.nyi.freebsd.org (Postfix) with ESMTPS id 03916EBCE; Wed, 3 Apr 2019 13:46:44 +0000 (UTC) (envelope-from 0mp@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id x33Dkhve052472; Wed, 3 Apr 2019 13:46:43 GMT (envelope-from 0mp@FreeBSD.org) Received: (from 0mp@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id x33DkhH3052471; Wed, 3 Apr 2019 13:46:43 GMT (envelope-from 0mp@FreeBSD.org) Message-Id: <201904031346.x33DkhH3052471@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: 0mp set sender to 0mp@FreeBSD.org using -f From: Mateusz Piotrowski <0mp@FreeBSD.org> Date: Wed, 3 Apr 2019 13:46:43 +0000 (UTC) To: src-committers@freebsd.org, svn-src-all@freebsd.org, svn-src-head@freebsd.org Subject: svn commit: r345845 - head/sbin/bectl X-SVN-Group: head X-SVN-Commit-Author: 0mp X-SVN-Commit-Paths: head/sbin/bectl X-SVN-Commit-Revision: 345845 X-SVN-Commit-Repository: base MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-Rspamd-Queue-Id: 3399D81F22 X-Spamd-Bar: -- Authentication-Results: mx1.freebsd.org X-Spamd-Result: default: False [-2.97 / 15.00]; local_wl_from(0.00)[FreeBSD.org]; NEURAL_HAM_MEDIUM(-1.00)[-0.999,0]; NEURAL_HAM_SHORT(-0.97)[-0.971,0]; NEURAL_HAM_LONG(-1.00)[-1.000,0]; ASN(0.00)[asn:11403, ipnet:2610:1c1:1::/48, country:US] X-BeenThere: svn-src-all@freebsd.org X-Mailman-Version: 2.1.29 Precedence: list List-Id: "SVN commit messages for the entire src tree \(except for " user" and " projects" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 03 Apr 2019 13:46:44 -0000 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.