bectl: document the -r flag to bectl
Independent of all of the commands, bectl itself takes an `-r` flag that specifies the BE root to use. This was originally added to facilitate testing, but it was later discovered to be incredibly useful in other scenarios; e.g., trying to recover some boot environments in rescue media. The "BE root" described here is the parent dataset that holds boot environments, but I've no idea if that's an accepted definition for that dataset. Reviewed by: gallatin, imp, Pau Amma MFC after: 1 week Differential Review: https://reviews.freebsd.org/D39710
This commit is contained in:
parent
37e6036b26
commit
4163bae030
@ -17,7 +17,7 @@
|
|||||||
.\"
|
.\"
|
||||||
.\" $FreeBSD$
|
.\" $FreeBSD$
|
||||||
.\"
|
.\"
|
||||||
.Dd March 31, 2022
|
.Dd April 26, 2023
|
||||||
.Dt BECTL 8
|
.Dt BECTL 8
|
||||||
.Os
|
.Os
|
||||||
.Sh NAME
|
.Sh NAME
|
||||||
@ -25,54 +25,67 @@
|
|||||||
.Nd Utility to manage boot environments on ZFS
|
.Nd Utility to manage boot environments on ZFS
|
||||||
.Sh SYNOPSIS
|
.Sh SYNOPSIS
|
||||||
.Nm
|
.Nm
|
||||||
|
.Op Fl r Ar beroot
|
||||||
.Cm activate
|
.Cm activate
|
||||||
.Op Fl t | Fl T
|
.Op Fl t | Fl T
|
||||||
.Ar beName
|
.Ar beName
|
||||||
.Nm
|
.Nm
|
||||||
|
.Op Fl r Ar beroot
|
||||||
.Cm check
|
.Cm check
|
||||||
.Nm
|
.Nm
|
||||||
|
.Op Fl r Ar beroot
|
||||||
.Cm create
|
.Cm create
|
||||||
.Op Fl r
|
.Op Fl r
|
||||||
.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
|
.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
|
||||||
.Ar newBeName
|
.Ar newBeName
|
||||||
.Nm
|
.Nm
|
||||||
|
.Op Fl r Ar beroot
|
||||||
.Cm create
|
.Cm create
|
||||||
.Op Fl r
|
.Op Fl r
|
||||||
.Ar beName@snapshot
|
.Ar beName@snapshot
|
||||||
.Nm
|
.Nm
|
||||||
|
.Op Fl r Ar beroot
|
||||||
.Cm destroy
|
.Cm destroy
|
||||||
.Op Fl \&Fo
|
.Op Fl \&Fo
|
||||||
.Ar beName Ns Op Cm @ Ns Ar snapshot
|
.Ar beName Ns Op Cm @ Ns Ar snapshot
|
||||||
.Nm
|
.Nm
|
||||||
|
.Op Fl r Ar beroot
|
||||||
.Cm export
|
.Cm export
|
||||||
.Ar sourceBe
|
.Ar sourceBe
|
||||||
.Nm
|
.Nm
|
||||||
|
.Op Fl r Ar beroot
|
||||||
.Cm import
|
.Cm import
|
||||||
.Ar targetBe
|
.Ar targetBe
|
||||||
.Nm
|
.Nm
|
||||||
|
.Op Fl r Ar beroot
|
||||||
.Cm jail
|
.Cm jail
|
||||||
.Op Fl bU
|
.Op Fl bU
|
||||||
.Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
|
.Oo Bro Fl o Ar key Ns Cm = Ns Ar value | Fl u Ar key Brc Oc Ns ...
|
||||||
.Ar beName
|
.Ar beName
|
||||||
.Op Ar utility Op Ar argument ...
|
.Op Ar utility Op Ar argument ...
|
||||||
.Nm
|
.Nm
|
||||||
|
.Op Fl r Ar beroot
|
||||||
.Cm list
|
.Cm list
|
||||||
.Op Fl aDHs
|
.Op Fl aDHs
|
||||||
.Op Fl c Ar property
|
.Op Fl c Ar property
|
||||||
.Op Fl C Ar property
|
.Op Fl C Ar property
|
||||||
.Oo Bro Fl c Ar property | Fl C Ar property Brc Oc
|
.Oo Bro Fl c Ar property | Fl C Ar property Brc Oc
|
||||||
.Nm
|
.Nm
|
||||||
|
.Op Fl r Ar beroot
|
||||||
.Cm mount
|
.Cm mount
|
||||||
.Ar beName
|
.Ar beName
|
||||||
.Op Ar mountpoint
|
.Op Ar mountpoint
|
||||||
.Nm
|
.Nm
|
||||||
|
.Op Fl r Ar beroot
|
||||||
.Cm rename
|
.Cm rename
|
||||||
.Ar origBeName
|
.Ar origBeName
|
||||||
.Ar newBeName
|
.Ar newBeName
|
||||||
.Nm
|
.Nm
|
||||||
|
.Op Fl r Ar beroot
|
||||||
.Brq Cm ujail | unjail
|
.Brq Cm ujail | unjail
|
||||||
.Brq Ar jailId | jailName | beName
|
.Brq Ar jailId | jailName | beName
|
||||||
.Nm
|
.Nm
|
||||||
|
.Op Fl r Ar beroot
|
||||||
.Brq Cm umount | unmount
|
.Brq Cm umount | unmount
|
||||||
.Op Fl f
|
.Op Fl f
|
||||||
.Ar beName
|
.Ar beName
|
||||||
@ -89,6 +102,23 @@ Boot environments
|
|||||||
allow the system to be upgraded, while preserving the old system environment in
|
allow the system to be upgraded, while preserving the old system environment in
|
||||||
a separate ZFS dataset.
|
a separate ZFS dataset.
|
||||||
.Pp
|
.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.
|
||||||
|
.Pp
|
||||||
The following commands are supported by
|
The following commands are supported by
|
||||||
.Nm :
|
.Nm :
|
||||||
.Bl -tag -width activate
|
.Bl -tag -width activate
|
||||||
@ -141,11 +171,13 @@ flag is specified, the new environment will be cloned from the given
|
|||||||
.Ar nonActiveBe
|
.Ar nonActiveBe
|
||||||
or
|
or
|
||||||
.Ar beName Ns Cm @ Ns Ar snapshot .
|
.Ar beName Ns Cm @ Ns Ar snapshot .
|
||||||
Otherwise, the new environment will be created from the currently booted environment.
|
Otherwise, the new environment will be created from the currently booted
|
||||||
|
environment.
|
||||||
.Pp
|
.Pp
|
||||||
If
|
If
|
||||||
.Nm
|
.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
|
.It Xo
|
||||||
.Cm create
|
.Cm create
|
||||||
.Op Fl r
|
.Op Fl r
|
||||||
@ -276,7 +308,6 @@ is used on next boot once
|
|||||||
.Pq Em \&T ;
|
.Pq Em \&T ;
|
||||||
or combination of
|
or combination of
|
||||||
.Pq Em \&NRT .
|
.Pq Em \&NRT .
|
||||||
.Pp
|
|
||||||
.Bl -tag -width indent
|
.Bl -tag -width indent
|
||||||
.It Fl a
|
.It Fl a
|
||||||
Display all datasets.
|
Display all datasets.
|
||||||
|
@ -69,23 +69,23 @@ usage(bool explicit)
|
|||||||
fprintf(fp, "%s",
|
fprintf(fp, "%s",
|
||||||
"Usage:\tbectl {-h | -? | subcommand [args...]}\n"
|
"Usage:\tbectl {-h | -? | subcommand [args...]}\n"
|
||||||
#if SOON
|
#if SOON
|
||||||
"\tbectl add (path)*\n"
|
"\tbectl [-r beroot] add (path)*\n"
|
||||||
#endif
|
#endif
|
||||||
"\tbectl activate [-t] beName\n"
|
"\tbectl [-r beroot] activate [-t] beName\n"
|
||||||
"\tbectl activate [-T]\n"
|
"\tbectl [-r beroot] activate [-T]\n"
|
||||||
"\tbectl check\n"
|
"\tbectl [-r beroot] check\n"
|
||||||
"\tbectl create [-r] [-e {nonActiveBe | beName@snapshot}] beName\n"
|
"\tbectl [-r beroot] create [-r] [-e {nonActiveBe | beName@snapshot}] beName\n"
|
||||||
"\tbectl create [-r] beName@snapshot\n"
|
"\tbectl [-r beroot] create [-r] beName@snapshot\n"
|
||||||
"\tbectl destroy [-Fo] {beName | beName@snapshot}\n"
|
"\tbectl [-r beroot] destroy [-Fo] {beName | beName@snapshot}\n"
|
||||||
"\tbectl export sourceBe\n"
|
"\tbectl [-r beroot] export sourceBe\n"
|
||||||
"\tbectl import targetBe\n"
|
"\tbectl [-r beroot] import targetBe\n"
|
||||||
"\tbectl jail [-bU] [{-o key=value | -u key}]... beName\n"
|
"\tbectl [-r beroot] jail [-bU] [{-o key=value | -u key}]... beName\n"
|
||||||
"\t [utility [argument ...]]\n"
|
"\t [utility [argument ...]]\n"
|
||||||
"\tbectl list [-aDHs] [{-c property | -C property}]\n"
|
"\tbectl [-r beroot] list [-aDHs] [{-c property | -C property}]\n"
|
||||||
"\tbectl mount beName [mountpoint]\n"
|
"\tbectl [-r beroot] mount beName [mountpoint]\n"
|
||||||
"\tbectl rename origBeName newBeName\n"
|
"\tbectl [-r beroot] rename origBeName newBeName\n"
|
||||||
"\tbectl {ujail | unjail} {jailID | jailName | beName}\n"
|
"\tbectl [-r beroot] {ujail | unjail} {jailID | jailName | beName}\n"
|
||||||
"\tbectl {umount | unmount} [-f] beName\n");
|
"\tbectl [-r beroot] {umount | unmount} [-f] beName\n");
|
||||||
|
|
||||||
return (explicit ? 0 : EX_USAGE);
|
return (explicit ? 0 : EX_USAGE);
|
||||||
}
|
}
|
||||||
|
Loading…
Reference in New Issue
Block a user