BEADM(1M) Maintenance Commands BEADM(1M)


NAME


beadm - utility for managing zfs boot environments

SYNOPSIS


beadm create [-a] [-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] beName


beadm rollback [-v] beName snapshot


beadm rollback [-v] beName@snapshot


DESCRIPTION


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

Displays command usage.


beadm create [-a] [-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 upon creation. The default is to
not activate the newly created BE.

-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(1M) 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.

-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'. 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] beName

Makes beName the active BE on next reboot.

-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 environmets and list all dataset and


snapshot information about those bootenvironments.


# 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


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(5) for descriptions of the following attributes:


+--------------------+-----------------+
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+--------------------+-----------------+
|Interface Stability | Uncommitted |
+--------------------+-----------------+


SEE ALSO


zfs(1M)


February 21, 2016 BEADM(1M)