cd816834d4
Instead of always running /bin/sh, allow the user to specify the command to run. The jail is not removed when the command finishes. Meaning, `bectl unjail` will still need to be run. For example: ``` bectl jail newBE pkg upgrade bectl ujail newBE ``` Submitted by: Shawn Webb Obtained from: HardenedBSD (8b451014ab)
290 lines
5.8 KiB
Groff
290 lines
5.8 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 August 17, 2018
|
|
.Dt BECTL 8
|
|
.Os
|
|
.Sh NAME
|
|
.Nm bectl
|
|
.Nd Utility to manage Boot Environments on ZFS
|
|
.Sh SYNOPSIS
|
|
.Nm
|
|
activate
|
|
.Op Fl t
|
|
.Ao Ar beName Ac
|
|
.Nm
|
|
create
|
|
.Op Fl r
|
|
.Op Fl e Ar nonActiveBe | Fl e Ar beName@snapshot
|
|
.Ao Ar beName Ac
|
|
.Nm
|
|
create
|
|
.Op Fl r
|
|
.Ao Ar beName@snapshot Ac
|
|
.Nm
|
|
destroy
|
|
.Op Fl F
|
|
.Ao Ar beName | beName@snapshot Ac
|
|
.Nm
|
|
export
|
|
.Ao Ar sourceBe Ac
|
|
.Nm
|
|
import
|
|
.Ao Ar targetBe Ac
|
|
.Nm
|
|
jail
|
|
.Op Fl b
|
|
.Oo Fl o Ar key Ns = Ns Ar value | Fl u Ar key Oc Ns ...
|
|
.Ao Ar jailID | jailName Ac
|
|
.Ao Ar bootenv Ac
|
|
.Op Ar utility Op Ar argument ...
|
|
.Nm
|
|
list
|
|
.Op Fl a
|
|
.Op Fl D
|
|
.Op Fl H
|
|
.Op Fl s
|
|
.Nm
|
|
mount
|
|
.Ao Ar beName Ac
|
|
.Op mountpoint
|
|
.Nm
|
|
rename
|
|
.Ao Ar origBeName Ac
|
|
.Ao Ar newBeName Ac
|
|
.Nm
|
|
{ ujail | unjail }
|
|
.Ao Ar jailID | jailName Ac
|
|
.Ao Ar bootenv Ac
|
|
.Nm
|
|
{ umount | unmount }
|
|
.Op Fl f
|
|
.Ao Ar beName Ac
|
|
.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 Ic activate
|
|
.Op Fl t
|
|
.Ar <beName>
|
|
.Pp
|
|
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 Ic create
|
|
.Op Fl r
|
|
.Op Fl e Ar nonActiveBe | Fl e Ar beName@snapshot
|
|
.Ao Ar beName Ac
|
|
.Pp
|
|
Creates a new boot environment named
|
|
.Ar beName .
|
|
If the -e param is specified, the new environment will be cloned from the given
|
|
.Ar nonActiveBe | Ar beName@snapshot .
|
|
If the
|
|
.Op Fl r
|
|
flag is given, a recursive boot environment will be made.
|
|
.It Ic create
|
|
.Op Fl r
|
|
.Ao Ar beName@snapshot Ac
|
|
.Pp
|
|
Creates a snapshot of the existing boot environment named
|
|
.Ar beName .
|
|
If the
|
|
.Op Fl r
|
|
flag is given, a recursive boot environment will be made.
|
|
.It Ic destroy
|
|
.Op Fl F
|
|
.Ao Ar beName | beName@snapshot Ac
|
|
.Pp
|
|
Destroys the given
|
|
.Ar beName
|
|
boot environment or
|
|
.Ar beName@snapshot
|
|
snapshot.
|
|
Specifying
|
|
.Fl F
|
|
will automatically unmount without confirmation.
|
|
.It Ic export
|
|
.Ao Ar sourceBe Ac
|
|
.Pp
|
|
Export
|
|
.Ar sourceBe
|
|
to
|
|
.Dv stdout .
|
|
.Dv stdout
|
|
must be piped or redirected to a file.
|
|
.It Ic import
|
|
.Ao Ar targetBe Ac
|
|
.Pp
|
|
Import
|
|
.Ar targetBe
|
|
from
|
|
.Dv stdin .
|
|
.It Ic jail
|
|
.Oo Fl o Ar key Ns = Ns Ar value | Fl u Ar key Oc Ns ...
|
|
.Ao Ar jailID | jailName Ac
|
|
.Ao Ar bootenv Ac
|
|
.Op Ar utility Op Ar argument ...
|
|
.Pp
|
|
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 .
|
|
.Pp
|
|
The
|
|
.Fl b
|
|
argument enables batch mode, thereby disabling interactive 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 ,
|
|
.Ar value
|
|
pairs are interpreted as jail parameters as described in
|
|
.Xr jail 8 .
|
|
The following default parameters are provided:
|
|
.Bl -tag -width -indent
|
|
.It Va allow.mount Ns = Ns Ar true
|
|
.It Va allow.mount.devfs Ns = Ns Ar true
|
|
.It Va enforce_statfs Ns = Ns Ar 1
|
|
.It Va name Ns = Ns Ar bootenv
|
|
.It Va host.hostname Ns = Ns Ar bootenv
|
|
.It Va path
|
|
Set to a path in /tmp generated by
|
|
.Xr libbe 3 .
|
|
.El
|
|
.Pp
|
|
All default parameters may be overwritten.
|
|
.It Ic list
|
|
.Op Fl a
|
|
.Op Fl D
|
|
.Op Fl H
|
|
.Op Fl s
|
|
.Pp
|
|
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 Ic mount
|
|
.Ao Ar beName Ac
|
|
.Op mountpoint
|
|
.Pp
|
|
Temporarily mount the boot environment.
|
|
Mount at the specified
|
|
.Ar mountpoint
|
|
if provided.
|
|
.It Ic rename Ao Ar origBeName Ac Ao Ar newBeName Ac
|
|
.Pp
|
|
Renames the given nonactive
|
|
.Ar origBeName
|
|
to the given
|
|
.Ar newBeName
|
|
.It Ic unjail Ao Ar jailID | jailName | beName Ac
|
|
.Pp
|
|
Destroys the jail created from the given boot environment.
|
|
.It Ic unmount
|
|
.Op Fl f
|
|
.Ao Ar beName Ac
|
|
.Pp
|
|
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 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
|
|
.Bl -bullet
|
|
.It
|
|
.An Kyle Kneitinger (kneitinger) Aq Mt kyle@kneit.in
|
|
.Pp
|
|
Creator of
|
|
.Nm .
|
|
.It
|
|
.An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl
|
|
.Pp
|
|
Creator and maintainer of
|
|
.Xr beadm 1 .
|
|
.It
|
|
.An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net
|
|
.Pp
|
|
Wrote the original
|
|
.Xr beadm 1
|
|
manual page that this one is derived from.
|
|
.El
|