BEADM(8) Maintenance Commands and Procedures BEADM(8)
NAME
beadm - utility for managing zfs boot environments
SYNOPSIS
beadm create [
-a |
-t] [
-d description]
[
-e non-activeBeName |
beName@snapshot]
[
-o property=value] ... [
-p zpool]
[
-v]
beName beadm create [
-v]
beName@snapshot beadm destroy [
-fFsv]
beName |
beName@snapshot beadm list [
-a |
-ds] [
-H]
[
-k|
-K date |
name |
space] [
-v] [
beName]
beadm mount [
-s ro|
rw] [
-v]
beName mountpoint beadm unmount [
-fv]
beName |
mountpoint beadm rename [
-v]
beName newBeName beadm activate [
-v] [
-t |
-T]
beName beadm rollback [
-v]
beName snapshot beadm rollback [
-v]
beName@snapshotDESCRIPTION
The
beadm command is the user interface for managing zfs Boot
Environments (BEs). This utility is intended to be used by System
Administrators who want to manage multiple Solaris Instances on a
single system.
The
beadm command supports the following operations:
- Create a new BE, based on the active BE.
- Create a new BE, based on an inactive BE.
- Create a snapshot of an existing BE.
- Create a new BE, based on an existing snapshot.
- Create a new BE, and copy it to a different zpool.
- Activate an existing, inactive BE.
- Mount a BE.
- Unmount a BE.
- Destroy a BE.
- Destroy a snapshot of a BE.
- Rename an existing, inactive BE.
- Roll back a BE to an existing snapshot of a BE.
- Display information about your snapshots and datasets.
SUBCOMMANDS
The
beadm command has the subcommands and options listed below. Also
see EXAMPLES below.
beadm Lists information for all boot environments. See
beadm list.
beadm create [
-a |
-t] [
-d description]
[
-e non-activeBeName |
beName@snapshot]
[
-o property=value] ... [
-p zpool]
[
-v]
beName Creates a new boot environment named
beName. If the
-e option is
not provided, the new boot environment will be created as a clone
of the currently running boot environment. If the
-d option is
provided then the description is also used as the title for the
BE's entry in the boot menu. If the
-d option is not provided,
beName will be used as the title.
-a Activate the newly created BE. The default is to not
activate the newly created BE. See also
-t.
-d description Create a new BE with a description associated with it.
-e non-activeBeName Create a new BE from an existing inactive BE.
-e beName@snapshot Create a new BE from an existing snapshot of the BE named
beName.
-o property=value Create the datasets for new BE with specific ZFS properties.
Multiple
-o options can be specified. See
zfs(8) for more
information on the
-o option.
-p zpool Create the new BE in the specified zpool. If this is not
provided, the default behavior is to create the new BE in the
same pool as as the origin BE. This option is not supported
in non-global zone.
-t Temporarily activate the newly created BE. The new BE will be
used for the next boot only and the temporary activation will
be automatically removed. The default is to not activate the
newly created BE. See also
-a.
-v Verbose mode. Displays verbose error messages from
beadm.
beadm create [
-v]
beName@snapshot Creates a snapshot of the existing BE named beName.
-v Verbose mode. Displays verbose error messages from
beadm.
beadm destroy [
-fFsv]
beName |
beName@snapshot Destroys the boot environment named
beName or destroys an
existing snapshot of the boot environment named
beName@snapshot.
Destroying a boot environment will also destroy all snapshots of
that boot environment. Use this command with caution.
-f Forcefully unmount the boot environment if it is currently
mounted.
-F Force the action without prompting to verify the destruction
of the boot environment.
-s Destroy all snapshots of the boot environment.
-v Verbose mode. Displays verbose error messages from
beadm.
beadm list [
-a |
-ds] [
-H]
[
-k|
-K date |
name |
space] [
-v] [
beName]
Lists information about the existing boot environment named
beName, or lists information for all boot environments if
beName is not provided. The 'Active' field indicates whether the boot
environment is active now, represented by 'N'; active on reboot,
represented by 'R'; or both, represented by 'NR'. If temporary
next boot configuration is used, the boot environment is marked
with 'T'. In non-global zone the 'Active' field also indicates
whether the boot environment has a non-active parent BE,
represented by 'x'; is active on boot in a non-active parent BE,
represented by 'b'. Activate, rollback and snapshot operations
for boot environments from non-active global parent BE aren't
supported, destroy is allowed if these boot environments aren't
active on boot.
Each line in the machine parsable output has the boot environment
name as the first field. The 'Space' field is displayed in bytes
and the 'Created' field is displayed in UTC format. The
-H option used with no other options gives the boot environment's
uuid in the second field. This field will be blank if the boot
environment does not have a uuid. See the EXAMPLES section. In
non-global zones, this field shows the uuid of the parent BE.
-a Lists all available information about the boot environment.
This includes subordinate file systems and snapshots.
-d Lists information about all subordinate file systems
belonging to the boot environment.
-s Lists information about the snapshots of the boot
environment.
-H Do not list header information. Each field in the list
information is separated by a semicolon.
-k date Sort BEs by date of creation in ascending order. This is
default.
-k name Lexical sort of BEs by name in ascending order.
-k space Sort BEs by space in ascending order.
-K date |
name |
space Same as the
-k option, but sorts in descending order.
-v Verbose mode. Displays verbose error messages from
beadm.
beadm mount [
-s ro|
rw] [
-v]
beName mountpoint Mounts a boot environment named beName at mountpoint. mountpoint
must be an already existing empty directory.
-s ro|
rw Mount the shared filesystems of the BE in read-only or read-
write mode.
-v Verbose mode. Displays verbose error messages from
beadm.
beadm unmount [
-fv]
beName |
mountpoint Unmounts the boot environment named beName. The command can also
be given a path to a beName mount point on the system.
-f Forcefully unmount the boot environment even if its currently
busy.
-v Verbose mode. Displays verbose error messages from
beadm.
beadm rename [
-v]
beName newBeName Renames the boot environment named
beName to
newBeName.
-v Verbose mode. Displays verbose error messages from
beadm.
beadm rollback [
-v]
beName snapshot |
beName@snapshot Roll back the boot environment named
beName to existing snapshot
of the boot environment named
beName@snapshot.
-v Verbose mode. Displays verbose error messages from
beadm.
beadm activate [
-v] [
-t |
-T]
beName Makes beName the active BE on next reboot.
-t Sets temporary, one time activation. For next boot, the
beName is used for boot, and the temporary activation is
removed. When temporary activation is removed, the next boot
will use zfs dataset specified in boot pool
bootfs property.
-T Removes temporary next boot configuration of
beName.
-v Verbose mode. Displays verbose error messages from
beadm.
ALTERNATE BE LOCATION
The alternate BE location outside rpool/ROOT can be configured by
modifying the BENAME_STARTS_WITH parameter in /etc/default/be. For
example: BENAME_STARTS_WITH=rootfs
EXAMPLES
Example 1: : Create a new BE named BE1, by cloning the current live BE.
# beadm create BE1 Example 2: : Create a new BE named BE2, by cloning the existing
inactive BE named BE1.
# beadm create -e BE1 BE2 Example 3: : Create a snapshot named now of the existing BE named BE1.
# beadm create BE1@now Example 4: : Create a new BE named BE3, by cloning an existing snapshot
of BE1.
# beadm create -e BE1@now BE3 Example 5: : Create a new BE named BE4 based on the currently running
BE. Create the new BE in rpool2.
# beadm create -p rpool2 BE4 Example 6: : Create a new BE named BE5 based on the currently running
BE. Create the new BE in rpool2, and create its datasets with
compression turned on.
# beadm create -p rpool2 -o compression=on BE5 Example 7: : Create a new BE named BE6 based on the currently running
BE and provide a description for it.
# beadm create -d "BE6 used as test environment" BE6 Example 8: : Activate an existing, inactive BE named BE3.
# beadm activate BE3 Example 9: : Mount the BE named BE3 at /mnt.
# beadm mount BE3 /mnt Example 10: : Unmount the mounted BE named BE3.
# beadm unmount BE3 Example 11: : Destroy the BE named BE3 without verification.
# beadm destroy -f BE3 Example 12: : Destroy the snapshot named now of BE1.
# beadm destroy BE1@now Example 13: : Rename the existing, inactive BE named BE1 to BE3.
# beadm rename BE1 BE3 Example 14: : Roll back the BE named BE1 to snapshot BE1@now.
# beadm rollback BE1 BE1@now Example 15: : List all existing boot environments.
# beadm list BE Active Mountpoint Space Policy Created
-- ------ ---------- ----- ------ -------
BE2 - - 72.0K static 2008-05-21 12:26
BE3 - - 332.0K static 2008-08-26 10:28
BE4 - - 15.78M static 2008-09-05 18:20
BE5 NR / 7.25G static 2008-09-09 16:53
Example 16: : List all existing boot environments and list all dataset
and snapshot information about those boot environments.
# beadm list -d -s BE/Dataset/Snapshot Active Mountpoint Space Policy Created
------------------- ------ ---------- ----- ------ -------
BE2
p/ROOT/BE2 - - 36.0K static 2008-05-21 12:26
p/ROOT/BE2/opt - - 18.0K static 2008-05-21 16:26
p/ROOT/BE2/opt@now - - 0 static 2008-09-08 22:43
p/ROOT/BE2@now - - 0 static 2008-09-08 22:43
BE3
p/ROOT/BE3 - - 192.0K static 2008-08-26 10:28
p/ROOT/BE3/opt - - 86.0K static 2008-08-26 10:28
p/ROOT/BE3/opt/local - - 36.0K static 2008-08-28 10:58
BE4
p/ROOT/BE4 - - 15.78M static 2008-09-05 18:20
BE5
p/ROOT/BE5 NR / 6.10G static 2008-09-09 16:53
p/ROOT/BE5/opt - /opt 24.55M static 2008-09-09 16:53
p/ROOT/BE5/opt@bar - - 18.38M static 2008-09-10 00:59
p/ROOT/BE5/opt@foo - - 18.38M static 2008-06-10 16:37
p/ROOT/BE5@bar - - 139.44M static 2008-09-10 00:59
p/ROOT/BE5@foo - - 912.85M static 2008-06-10 16:37
Example 17: : List all dataset and snapshot information about BE5
# beadm list -a BE5 BE/Dataset/Snapshot Active Mountpoint Space Policy Created
------------------- ------ ---------- ----- ------ -------
BE5
p/ROOT/BE5 NR / 6.10G static 2008-09-09 16:53
p/ROOT/BE5/opt - /opt 24.55M static 2008-09-09 16:53
p/ROOT/BE5/opt@bar - - 18.38M static 2008-09-10 00:59
p/ROOT/BE5/opt@foo - - 18.38M static 2008-06-10 16:37
p/ROOT/BE5@bar - - 139.44M static 2008-09-10 00:59
p/ROOT/BE5@foo - - 912.85M static 2008-06-10 16:37
Example 18: : List machine parsable information about all boot
environments.
# beadm list -H BE2;;;;55296;static;1211397974
BE3;;;;339968;static;1219771706
BE4;;;;16541696;static;1220664051
BE5;215b8387-4968-627c-d2d0-f4a011414bab;NR;/;7786206208;static;1221004384
Example 19: : Create and list temporary activation.
# beadm list BE Active Mountpoint Space Policy Created
-- ------ ---------- ----- ------ -------
BE2 - - 4,85M static 2016-10-30 14:29
BE3 - - 4,84M static 2016-10-30 18:53
BE4 - - 5,54M static 2016-10-30 23:53
BE5 NR / 12,6G static 2016-11-06 01:46
# beadm create BE6 # beadm activate -t BE6 # beadm list BE Active Mountpoint Space Policy Created
-- ------ ---------- ----- ------ -------
BE2 - - 4,85M static 2016-10-30 14:29
BE3 - - 4,84M static 2016-10-30 18:53
BE4 - - 5,54M static 2016-10-30 23:53
BE5 NR / 60,0K static 2016-11-06 01:46
BE6 T - 12,6G static 2016-11-06 12:56
EXIT STATUS
The following exit values are returned:
0 Successful completion
>0 Failure
FILES
/var/log/beadm/<beName>/create.log.<yyyymmdd_hhmmss> Log used for capturing beadm create output
yyyymmdd_hhmmss - 20071130_140558
yy - year; 2007
mm - month; 11
dd - day; 30
hh - hour; 14
mm - minute; 05
ss - second; 58
/etc/default/be Contains default value for BENAME_STARTS_WITH parameter
ATTRIBUTES
See
attributes(7) for descriptions of the following attributes:
+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Uncommitted |
+--------------------+-----------------+
SEE ALSO
zfs(8) March 10, 2023 BEADM(8)
