beadm.8

.\"
.\" beadm - Illumos/Solaris-like utility for FreeBSD to manage
.\" Boot Environments on ZFS filesystems
.\"
.\" 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.
.\"
.\"
.\"     @(#)beadm.8
.\" $FreeBSD$
.\"
.Dd May 6, 2022
.Dt BEADM 8
.Os
.Sh NAME
.Nm beadm
.Nd manage boot environments with ZFS
.Sh SYNOPSIS
.Nm
.Cm activate Ar beName
.Nm
.Cm create Op Fl e Ar nonActiveBe Ns | Ns Ar beName Ns Cm @ Ns Ar snapshot
.Ar beName
.Nm
.Cm create
.Ar beName Ns Cm @ Ns Ar snapshot
.Nm
.Cm destroy Op Fl F
.Ar beName Ns | Ns Ar beName Ns Cm @ Ns Ar snapshot
.Nm
.Cm export
.Op Fl v
.Ar beName
.Nm
.Cm import
.Op Fl v
.Ar beName
.Nm Cm list
.Op Fl aDHs
.Nm
.Cm mount
.Ar beName
.Op Ar mountpoint
.Nm
.Cm rename Ar origBeName Ar newBeName
.Nm
.Cm umount Op Fl f Ar beName
.Nm
.Cm chroot Ar beName
.Nm
.Cm reroot Ar beName
.Nm
.Cm version
.Sh DESCRIPTION
The
.Nm
command is used to setup and interact with boot environments with ZFS.
.Pp
Boot environments allow 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 indent
.It Cm activate Ar beName
Activate the given
.Ar beName
for the next boot.
.It Cm create Xo
.Op Fl e Ar nonActiveBe Ns | Ns Ar beName Ns Cm @ Ns Ar snapshot
.Ar beName
.Xc
Create a new boot environment named
.Ar beName .
If the
.Fl e
option is specified, the new environment will be cloned from the given
.Ar nonActiveBe
boot environment
or
.Ar beName Ns Cm @ Ns Ar snapshot
snapshot.
.It Cm create Ar beName Ns Cm @ Ns Ar snapshot
Create a snapshot of the existing boot environment named
.Ar beName .
.It Xo
.Cm destroy Op Fl F
.Ar beName Ns | Ns Ar beName Ns Cm @ Ns Ar snapshot
.Xc
Destroy the given
.Ar beName
boot environment
or
.Ar beName Ns Cm @ Ns Ar snapshot
snapshot.
Specifying
.Fl F
will automatically unmount the target without confirmation.
.It Cm export Ar beName
Export
.Ar beName
to the
.Xr stdout 4 .
Use pipe or redirect the output to a file.
.Bl -tag -width "-v"
.It Fl v
Display verbose output on the export operation.
.El
.It Cm import Ar beName
Import
.Ar beName
from
.Xr stdin 4
input.
.Bl -tag -width "-v"
.It Fl v
Display verbose output on the export operation.
.El
.It Cm list Op Fl aDHs
Display all boot environments.
The
.Qq Active
field indicates whether the boot environment is active now
.Pq Qq N ;
active on reboot
.Pq Qq R ;
or both
.Pq Qq NR .
.Pp
The following options are available:
.Bl -tag -width "-a"
.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
Does not print headers and separate fields by a single tab instead of arbitrary
white space.
Use for scripting.
.It Fl s
Display all snapshots.
.El
.It Cm mount Ar beName Op Ar mountpoint
Temporarily mount the
.Ar beName
boot environment.
Mount at the specified
.Ar mountpoint
if provided.
.It Cm rename Ar origBeName Ar newBeName
Rename the given nonactive
.Ar origBeName
boot environment
to
.Ar newBeName .
.It Cm umount Op Fl f Ar beName
Unmount the given boot environment, if it is mounted.
Specifying
.Fl f
will force the unmount if busy.
This command can be called with either
.Cm umount
or
.Cm unmount .
.It Cm chroot
Enter to selected boot environment with the
.Xr chroot 8
command.
.It Cm reroot
Use 'reroot' feature from the
.Xr reboot 8 -r
command.
.It Cm version
Print the
.Nm
version and exit.
.El
.Sh EXAMPLES
.Bl -tag -width indent
.It Perform a system upgrade in a Xr jail 8 :
.Pp
Create a new boot environment called
.Em jailed :
.Bd -literal -offset indent
beadm create -e default jailed
.Ed
.Pp
Set a mountpoint for the new jail to
.Pa /usr/jails/jailed :
.Bd -literal -offset indent
beadm mount jailed /usr/jails/jailed
.Ed
.Pp
The currently active boot environment is now replicated into the jailed system
and ready for an upgrade.
Start up the jail, log in and perform the normal upgrade process.
Once this is done, stop the jail and disable it in
.Pa /etc/rc.conf .
Now activate the boot environment for the next boot:
.Bd -literal -offset indent
beadm activate jailed
.Ed
.Pp
Reboot into the new environment:
.Bd -literal -offset indent
reboot
.Ed
.El
.Sh SEE ALSO
.Xr jail 8 ,
.Xr zfs 8 ,
.Xr zpool 8
.Pp
The original
.Dq Fx ZFS Madness
how-to guide is available at the
.Fx
Forums:
.Lk https://forums.freebsd.org/showthread.php?t=31662
.Sh HISTORY
.Xr beadm 1M
originally appeared in Solaris.
.Sh AUTHORS
.Bl -tag -width indent
.It An Slawomir Wojciech Wojtczak (vermaden) Aq Mt vermaden@interia.pl :
.Bl -dash
.It
Creator and maintainer of
.Nm .
.El
.It An Bryan Drewery (bdrewery) Aq Mt bryan@shatow.net :
.Bl -dash
.It
Wrote this manual page and contributed child dataset fixes.
.El
.It An Mike Clarke (rawthey) Aq Mt jmc-fbsd@milibyte.co.uk :
.Bl -dash
.It
Wrote fast implementation of
.Nm Ar list .
.It
Contributed a lot of fixes and usability changes.
.El
.El