c0f846ff23
Discuss the standard type of layout, as well as the "deep" BE layout, and some of the properties of both. Point the various -r flags at this new section, to help users understand which they're working with and what the -r flag is actually doing. Note that we may just deprecate the -r flag in future versions, but the flag will be recognized as a NOP at that point. Reviewed by: pauamma_gundo.com, rew Differential Revision: https://reviews.freebsd.org/D34538
468 lines
9.8 KiB
Groff
468 lines
9.8 KiB
Groff
.\"
|
|
.\" SPDX-License-Identifier: BSD-2-Clause-FreeBSD
|
|
.\"
|
|
.\" Copyright (c) 2017 Kyle J. Kneitinger <kyle@kneit.in>
|
|
.\"
|
|
.\" 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 March 31, 2022
|
|
.Dt BECTL 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm bectl
|
|
.Nd Utility to manage boot environments on ZFS
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Cm activate
|
|
.Op Fl t | Fl T
|
|
.Ar beName
|
|
.Nm
|
|
.Cm check
|
|
.Nm
|
|
.Cm create
|
|
.Op Fl r
|
|
.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
|
|
.Ar beName Ns Op Cm @ Ns Ar snapshot
|
|
.Nm
|
|
.Cm export
|
|
.Ar sourceBe
|
|
.Nm
|
|
.Cm import
|
|
.Ar targetBe
|
|
.Nm
|
|
.Cm jail
|
|
.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 aDHs
|
|
.Op Fl c Ar property
|
|
.Op Fl C Ar property
|
|
.Oo Bro Fl c Ar property | Fl C Ar property Brc Oc
|
|
.Nm
|
|
.Cm mount
|
|
.Ar beName
|
|
.Op Ar mountpoint
|
|
.Nm
|
|
.Cm rename
|
|
.Ar origBeName
|
|
.Ar newBeName
|
|
.Nm
|
|
.Brq Cm ujail | unjail
|
|
.Brq Ar jailId | jailName | 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
|
|
Boot environments
|
|
allow the system to be upgraded, while preserving the old system environment in
|
|
a separate ZFS dataset.
|
|
.Pp
|
|
The following commands are supported by
|
|
.Nm :
|
|
.Bl -tag -width activate
|
|
.It Xo
|
|
.Cm activate
|
|
.Op Fl t | Fl T
|
|
.Ar beName
|
|
.Xc
|
|
Activate the given
|
|
.Ar beName
|
|
as the default boot filesystem.
|
|
If the
|
|
.Fl t
|
|
flag is given, this takes effect only for the next boot.
|
|
Flag
|
|
.Fl T
|
|
removes temporary boot once configuration.
|
|
Without temporary configuration, the next boot will use zfs dataset specified
|
|
in boot pool
|
|
.Ar bootfs
|
|
property.
|
|
.It Xo
|
|
.Cm check
|
|
.Xc
|
|
Performs a silent sanity check on the current system.
|
|
If boot environments are supported and used,
|
|
.Nm
|
|
will exit with a status code of 0.
|
|
Any other status code is not currently defined and may, in the future, grow
|
|
special meaning for different degrees of sanity check failures.
|
|
.It Xo
|
|
.Cm create
|
|
.Op Fl r
|
|
.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
|
|
.Ar newBeName
|
|
.Xc
|
|
Create a new boot environment named
|
|
.Ar newBeName .
|
|
.Pp
|
|
If the
|
|
.Fl r
|
|
flag is given, a recursive boot environment will be made.
|
|
See
|
|
.Sx Boot Environment Structures
|
|
for a discussion on different layouts.
|
|
.Pp
|
|
If the
|
|
.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
|
|
.Ar beName@snapshot
|
|
.Xc
|
|
Create a snapshot of the boot environment named
|
|
.Ar beName .
|
|
.Pp
|
|
If the
|
|
.Fl r
|
|
flag is given, a recursive snapshot of the boot environment will be created.
|
|
A snapshot is created for each descendant dataset of the boot environment.
|
|
See
|
|
.Sx Boot Environment Structures
|
|
for a discussion on different layouts.
|
|
.Pp
|
|
No new boot environment is created with this command.
|
|
.It Xo
|
|
.Cm destroy
|
|
.Op Fl \&Fo
|
|
.Ar beName Ns Op Cm @ Ns Ar snapshot
|
|
.Xc
|
|
Destroy the given
|
|
.Ar beName
|
|
boot environment or
|
|
.Ar beName Ns Cm @ Ns Ar snapshot
|
|
snapshot without confirmation, unlike in
|
|
.Xr beadm 1 .
|
|
Specifying
|
|
.Fl F
|
|
will automatically unmount without confirmation.
|
|
.Pp
|
|
By default,
|
|
.Nm
|
|
will warn that it is not destroying the origin of
|
|
.Ar beName .
|
|
The
|
|
.Fl o
|
|
flag may be specified to destroy the origin as well.
|
|
.It Cm export Ar sourceBe
|
|
Export
|
|
.Ar sourceBe
|
|
to
|
|
.Xr stdout 4 .
|
|
.Xr stdout 4
|
|
must be piped or redirected to a file.
|
|
.It Cm import Ar targetBe
|
|
Import
|
|
.Ar targetBe
|
|
from
|
|
.Xr stdin 4 .
|
|
.It Xo
|
|
.Cm jail
|
|
.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
|
|
Create 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
|
|
must be set, the default values are specified below.
|
|
.Pp
|
|
All
|
|
.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:
|
|
.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 Set to jail ID.
|
|
.It Va host.hostname Ta Va bootenv
|
|
.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 Xo
|
|
.Cm list
|
|
.Op Fl aDHs
|
|
.Oo Bro Fl c Ar property | Fl C Ar property Brc Oc
|
|
.Xc
|
|
.Pp
|
|
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 ;
|
|
is used on next boot once
|
|
.Pq Em \&T ;
|
|
or combination of
|
|
.Pq Em \&NRT .
|
|
.Pp
|
|
.Bl -tag -width indent
|
|
.It Fl a
|
|
Display all datasets.
|
|
.It Fl D
|
|
Display the full space usage for each boot environment, assuming all
|
|
other boot environments were destroyed.
|
|
.It Fl H
|
|
Used for scripting.
|
|
Do not print headers and separate fields by a single tab instead of
|
|
arbitrary white space.
|
|
.It Fl s
|
|
Display all snapshots as well.
|
|
.It Fl c Ar property
|
|
Sort boot environments by given property name.
|
|
The following properties are supported:
|
|
.Pp
|
|
.Bl -tag -width 4n -offset indent -compact
|
|
.It name (default output)
|
|
.It creation
|
|
.It origin
|
|
.It used
|
|
.It usedds
|
|
.It usedsnap
|
|
.It usedrefreserv
|
|
.El
|
|
.It Fl C Ar property
|
|
Same as the
|
|
.Fl c
|
|
option, but displays in descending order.
|
|
.El
|
|
.Pp
|
|
The
|
|
.Fl D
|
|
option is ignored when either the
|
|
.Fl s
|
|
or
|
|
.Fl a
|
|
option is used.
|
|
.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
|
|
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 ujail Brq Ar jailId | jailName | beName
|
|
.It Cm unjail Brq Ar jailId | jailName | 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
|
|
.Xc
|
|
Unmount the given boot environment, if it is mounted.
|
|
Specifying
|
|
.Fl f
|
|
will force the unmount if busy.
|
|
.El
|
|
.Pp
|
|
.Nm
|
|
prints usage information if
|
|
.Fl h
|
|
or
|
|
.Fl \&?
|
|
is specified.
|
|
.Ss Boot Environment Structures
|
|
The traditional
|
|
.Fx
|
|
boot environment layout, as created by the Auto ZFS option to
|
|
.Xr bsdinstall 8 ,
|
|
is a
|
|
.Dq shallow
|
|
boot environment structure, where boot environment datasets do not have any
|
|
directly subordinate datasets.
|
|
Instead, they're organized off in
|
|
.Pa zroot/ROOT ,
|
|
and they rely on datasets elsewhere in the pool having
|
|
.Dv canmount
|
|
set to
|
|
.Dv off .
|
|
For instance, a simplified pool may be laid out as such:
|
|
.Bd -literal -offset indent
|
|
% zfs list -o name,canmount,mountpoint
|
|
NAME CANMOUNT MOUNTPOINT
|
|
zroot
|
|
zroot/ROOT noauto none
|
|
zroot/ROOT/default noauto none
|
|
zroot/usr off /usr
|
|
zroot/usr/home on /usr/home
|
|
zroot/var on /var
|
|
.Ed
|
|
.Pp
|
|
In that example,
|
|
.Pa zroot/usr
|
|
has
|
|
.Dv canmount
|
|
set to
|
|
.Dv off ,
|
|
thus files in
|
|
.Pa /usr
|
|
typically fall into the boot environment because this dataset is not mounted.
|
|
.Pa zroot/usr/home
|
|
is mounted, thus files in
|
|
.Pa /usr/home
|
|
are not in the boot environment.
|
|
.Pp
|
|
The other style of boot environments in use, frequently called
|
|
.Dq deep boot environments ,
|
|
organizes some or all of the boot environment as subordinate to the boot
|
|
environment dataset.
|
|
For example:
|
|
.Bd -literal -offset indent
|
|
% zfs list -o name,canmount,mountpoint
|
|
NAME CANMOUNT MOUNTPOINT
|
|
zroot
|
|
zroot/ROOT noauto none
|
|
zroot/ROOT/default noauto none
|
|
zroot/ROOT/default/usr noauto /usr
|
|
zroot/ROOT/default/usr/local noauto /usr/local
|
|
zroot/var on /var
|
|
.Ed
|
|
.Pp
|
|
Note that the subordinate datasets now have
|
|
.Dv canmount
|
|
set to
|
|
.Dv noauto .
|
|
These are more obviously a part of the boot environment, as indicated by their
|
|
positioning in the layout.
|
|
These subordinate datasets will be mounted by the
|
|
.Dv zfsbe
|
|
.Xr rc 8
|
|
script at boot time.
|
|
In this example,
|
|
.Pa /var
|
|
is excluded from the boot environment.
|
|
.Pp
|
|
.Nm
|
|
commands that have their own
|
|
.Fl r
|
|
operate on this second,
|
|
.Dq deep
|
|
style of boot environment, when the
|
|
.Fl r
|
|
flag is set.
|
|
A future version of
|
|
.Nm
|
|
may default to handling both styles and deprecate the various
|
|
.Fl r
|
|
flags.
|
|
\" .Sh EXAMPLES
|
|
\" .Bl -bullet
|
|
\" .It
|
|
\" To fill in with jail upgrade example when behavior is firm.
|
|
\" .El
|
|
.Sh SEE ALSO
|
|
.Xr libbe 3 ,
|
|
.Xr beinstall.sh 8 ,
|
|
.Xr jail 8 ,
|
|
.Xr zfs 8 ,
|
|
.Xr zpool 8
|
|
.Sh HISTORY
|
|
.Nm
|
|
is based on
|
|
.Xr beadm 1
|
|
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
|
|
.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
|
|
.Xr beadm 1
|
|
manual page that this one is derived from.
|