mirror of
https://github.com/freebsd/freebsd-src
synced 2024-07-22 10:48:02 +00:00
20b5e47c93
Discussed with Kyle in Discord. Reviewed by: imp Pull Request: https://github.com/freebsd/freebsd-src/pull/857
519 lines
11 KiB
Groff
519 lines
11 KiB
Groff
.\"
|
|
.\" SPDX-License-Identifier: BSD-2-Clause
|
|
.\"
|
|
.\" 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.
|
|
.\"
|
|
.\"
|
|
.Dd April 9, 2024
|
|
.Dt BECTL 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm bectl
|
|
.Nd Utility to manage boot environments on ZFS
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
.Op Fl h
|
|
.Nm
|
|
.Op Fl r Ar beroot
|
|
.Cm activate
|
|
.Op Fl t | Fl T
|
|
.Ar beName
|
|
.Nm
|
|
.Op Fl r Ar beroot
|
|
.Cm check
|
|
.Nm
|
|
.Op Fl r Ar beroot
|
|
.Cm create
|
|
.Op Fl r
|
|
.Op Fl e Brq Ar nonActiveBe | Ar beName Ns Cm @ Ns Ar snapshot
|
|
.Ar newBeName
|
|
.Nm
|
|
.Op Fl r Ar beroot
|
|
.Cm create
|
|
.Op Fl r
|
|
.Ar beName@snapshot
|
|
.Nm
|
|
.Op Fl r Ar beroot
|
|
.Cm destroy
|
|
.Op Fl \&Fo
|
|
.Ar beName Ns Op Cm @ Ns Ar snapshot
|
|
.Nm
|
|
.Op Fl r Ar beroot
|
|
.Cm export
|
|
.Ar sourceBe
|
|
.Nm
|
|
.Op Fl r Ar beroot
|
|
.Cm import
|
|
.Ar targetBe
|
|
.Nm
|
|
.Op Fl r Ar beroot
|
|
.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
|
|
.Op Fl r Ar beroot
|
|
.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
|
|
.Op Fl r Ar beroot
|
|
.Cm mount
|
|
.Ar beName
|
|
.Op Ar mountpoint
|
|
.Nm
|
|
.Op Fl r Ar beroot
|
|
.Cm rename
|
|
.Ar origBeName
|
|
.Ar newBeName
|
|
.Nm
|
|
.Op Fl r Ar beroot
|
|
.Brq Cm ujail | unjail
|
|
.Brq Ar jailId | jailName | beName
|
|
.Nm
|
|
.Op Fl r Ar beroot
|
|
.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
|
|
A boot environment allows the system to be upgraded, while preserving the
|
|
pre-upgrade system environment.
|
|
.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.
|
|
.Ss Supported Subcommands and Flags
|
|
.Bl -tag -width activate
|
|
.It Xo
|
|
.Fl h
|
|
.Xc
|
|
Print usage information and exit.
|
|
.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 subcommand.
|
|
.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 8 .
|
|
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 .
|
|
.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 the given ZFS dataset property.
|
|
The following properties are supported:
|
|
.Pp
|
|
.Bl -tag -width 4n -offset indent -compact
|
|
.It name (the default)
|
|
.It creation
|
|
.It origin
|
|
.It used
|
|
.It usedbydataset
|
|
.It usedbyrefreservation
|
|
.It usedbysnapshots
|
|
.El
|
|
.Pp
|
|
Short forms usedds, usedrefreserv and usedsnap are also supported.
|
|
.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
|
|
Mount the given boot environment.
|
|
.Pp
|
|
If a nonexistent
|
|
.Ar mountpoint
|
|
is given:
|
|
.Nm
|
|
will make the directory, including intermediate directories as required.
|
|
.Pp
|
|
If no
|
|
.Ar mountpoint
|
|
is given:
|
|
.Nm
|
|
will make a directory such as
|
|
.Pa be_mount.c6Sf
|
|
in
|
|
.Pa /tmp .
|
|
Randomness in the last four characters of the directory name will prevent
|
|
mount point conflicts.
|
|
Unmount of an environment, followed by mount of the same environment
|
|
without giving a
|
|
.Ar mountpoint ,
|
|
will result in a different randomly-named mountpoint.
|
|
.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.
|
|
.Pp
|
|
Unmount will not remove the mount point.
|
|
.El
|
|
.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/home on /home
|
|
zroot/usr off /usr
|
|
zroot/usr/src on /usr/src
|
|
zroot/var off /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/src
|
|
is mounted, thus files in
|
|
.Pa /usr/src
|
|
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
|
|
subcommands 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 zfsprops 7 ,
|
|
.Xr beinstall.sh 8 ,
|
|
.Xr jail 8 ,
|
|
.Xr zfs 8 ,
|
|
.Xr zpool 8
|
|
.Sh HISTORY
|
|
.Nm
|
|
and
|
|
.Xr libbe 3
|
|
were written by
|
|
.An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in
|
|
as a 2017 Google Summer of Code project, with
|
|
.An Allan Jude (allanjude) Aq Mt allanjude@freebsd.org
|
|
as mentor.
|
|
.Pp
|
|
.Nm
|
|
and this manual page were derived from
|
|
.Xr beadm 8 .
|
|
.Sh AUTHORS
|
|
.An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl
|
|
is the creator and maintainer of
|
|
.Xr beadm 8 .
|
|
.An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net
|
|
contributed child dataset fixes, and wrote the
|
|
.Xr beadm 8
|
|
manual page.
|
|
.Pp
|
|
Most later changes to
|
|
.Nm ,
|
|
and to this page, were written by
|
|
.An Kyle Evans (kevans) Aq Mt kevans@freebsd.org .
|