54abda0420
Those two manual pages are already referencing each other in the HISTORY sections, which people might skip. Mention those manual pages explicitly in the SEE ALSO sections. Also, remove a reference to be(1) from libbe(3). Reviewed by: bcr Approved by: krion (mentor, implicit), mat (mentor, implicit) Differential Revision: https://reviews.freebsd.org/D18136
289 lines
6.0 KiB
Groff
289 lines
6.0 KiB
Groff
.\"
|
|
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
|
|
.\"
|
|
.\" Copyright (c) 2017 Kyle J. Kneitinger <kyle@kneit.in>
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\"
|
|
.\" @(#)be.1
|
|
.\"
|
|
.\" $FreeBSD$
|
|
.\"
|
|
.Dd November 21, 2018
|
|
.Dt BECTL 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm bectl
|
|
.Nd Utility to manage Boot Environments on ZFS
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Cm activate
|
|
.Op Fl t
|
|
.Ar beName
|
|
.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
|
|
.Nm
|
|
.Cm destroy
|
|
.Op Fl F
|
|
.Brq Ar beName | beName@snapshot
|
|
.Nm
|
|
.Cm export
|
|
.Ar sourceBe
|
|
.Nm
|
|
.Cm import
|
|
.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 ...
|
|
.Brq Ar jailID | jailName
|
|
.Ar bootenv
|
|
.Op Ar utility Op Ar argument ...
|
|
.Nm
|
|
.Cm list
|
|
.Op Fl DHas
|
|
.Nm
|
|
.Cm mount
|
|
.Ar beName
|
|
.Op mountpoint
|
|
.Nm
|
|
.Cm rename
|
|
.Ar origBeName
|
|
.Ar newBeName
|
|
.Nm
|
|
.Brq Cm ujail | unjail
|
|
.Brq Ar jailID | jailName
|
|
.Ar bootenv
|
|
.Nm
|
|
.Brq Cm umount | unmount
|
|
.Op Fl f
|
|
.Ar beName
|
|
.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
|
|
a separate ZFS dataset.
|
|
.Sh COMMANDS
|
|
The following commands are supported by
|
|
.Nm :
|
|
.Bl -tag -width activate
|
|
.It Xo
|
|
.Cm activate
|
|
.Op Fl t
|
|
.Ar beName
|
|
.Xc
|
|
Activate the given
|
|
.Ar beName
|
|
as the default boot filesystem.
|
|
If the
|
|
.Op Fl t
|
|
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
|
|
.Xc
|
|
Creates a new boot environment named
|
|
.Ar beName .
|
|
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.
|
|
.It Xo
|
|
.Cm destroy
|
|
.Op Fl F
|
|
.Brq Ar beName | beName@snapshot
|
|
.Xc
|
|
Destroys the given
|
|
.Ar beName
|
|
boot environment or
|
|
.Ar beName@snapshot
|
|
snapshot without confirmation, unlike in
|
|
.Nm beadm .
|
|
Specifying
|
|
.Fl F
|
|
will automatically unmount without confirmation.
|
|
.It Cm export Ar sourceBe
|
|
Export
|
|
.Ar sourceBe
|
|
to
|
|
.Dv stdout .
|
|
.Dv stdout
|
|
must be piped or redirected to a file.
|
|
.It Cm import Ar targetBe
|
|
Import
|
|
.Ar targetBe
|
|
from
|
|
.Dv stdin .
|
|
.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 ...
|
|
.Brq Ar jailID | jailName
|
|
.Ao Ar bootenv Ac
|
|
.Op Ar utility Op Ar argument ...
|
|
.Xc
|
|
Creates a jail of the given boot environment.
|
|
Multiple
|
|
.Fl o
|
|
and
|
|
.Fl u
|
|
arguments may be specified.
|
|
.Fl o
|
|
will set a jail parameter, and
|
|
.Fl u
|
|
will unset a jail parameter.
|
|
.Pp
|
|
By default, jails are created in interactive mode and
|
|
.Pa /bin/sh
|
|
is
|
|
executed within the jail.
|
|
If
|
|
.Ar utility
|
|
is specified, it will be executed instead of
|
|
.Pa /bin/sh .
|
|
The jail will be destroyed and the boot environment unmounted when the command
|
|
finishes executing, unless the
|
|
.Fl U
|
|
argument is specified.
|
|
.Pp
|
|
The
|
|
.Fl b
|
|
argument enables batch mode, thereby disabling interactive mode.
|
|
The
|
|
.Fl U
|
|
argument will be ignored in batch mode.
|
|
.Pp
|
|
The
|
|
.Va name ,
|
|
.Va host.hostname ,
|
|
and
|
|
.Va path
|
|
may not actually be unset.
|
|
Attempts to unset any of these will revert them to the default values specified
|
|
below, if they have been overwritten by
|
|
.Fl o .
|
|
.Pp
|
|
All
|
|
.Ar key Ns = Ns Ar value
|
|
pairs are interpreted as jail parameters as described in
|
|
.Xr jail 8 .
|
|
The following default parameters are provided:
|
|
.Bl -column "allow.mount.devfs" ""
|
|
.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 Va bootenv
|
|
.It Va host.hostname Ta Va bootenv
|
|
.It Va path Ta Set to a path in /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).
|
|
.Pp
|
|
If
|
|
.Fl a
|
|
is used, display all datasets.
|
|
If
|
|
.Fl D
|
|
is used, display the full space usage for each boot environment, assuming all
|
|
other boot environments were destroyed.
|
|
The
|
|
.Fl H
|
|
option is used for scripting.
|
|
It does not print headers and separate fields by a single tab instead of
|
|
arbitrary white space.
|
|
If
|
|
.Fl s
|
|
is used, display all snapshots as well.
|
|
.It Cm mount Ar beName Op Ar mountpoint
|
|
Temporarily mount the boot environment.
|
|
Mount at the specified
|
|
.Ar mountpoint
|
|
if provided.
|
|
.It Cm rename Ar origBeName newBeName
|
|
Renames 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 Xo
|
|
.Cm unmount
|
|
.Op Fl f
|
|
.Ar beName
|
|
.Xc
|
|
Unmount the given boot environment, if it is mounted.
|
|
Specifying
|
|
.Fl f
|
|
will force the unmount if busy.
|
|
.El
|
|
.Sh EXAMPLES
|
|
.Bl -bullet
|
|
.It
|
|
To fill in with jail upgrade example when behavior is firm.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr libbe 3 ,
|
|
.Xr jail 8 ,
|
|
.Xr zfs 8 ,
|
|
.Xr zpool 8
|
|
.Sh HISTORY
|
|
.Nm
|
|
is based on
|
|
.Nm beadm
|
|
and was implemented as a project for the 2017 Summer of Code, along with
|
|
.Xr libbe 3 .
|
|
.Sh AUTHORS
|
|
.Nm
|
|
was written by
|
|
.An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in .
|
|
.Pp
|
|
.Nm beadm
|
|
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
|
|
manual page that this one is derived from.
|