Managing Your Boot Environments (Tasks)

In the OpenSolaris 2008.05 release, you can use a new BE utility to create and manage snapshots and clones of your BEs. The BE utility interface enables you to efficiently manage your boot environments. This new utility is particularly useful for system administrators who want to manage multiple OpenSolaris boot environments on a single system.

Advantages of BE Utility

The new BE utility has the following advantages:

The BE utility aggregates all datasets in a BE and performs actions on the entire BE at once. You no longer need to perform ZFS commands to modify each dataset individually.
The BE utility manages the dataset structures within BEs. For example, when the BE utility clones a BE that has shared file systems, the utility automatically recognizes and manages those shared file systems for the new BE.
The BE utility enables you to perform administrative tasks on your BEs, independent from upgrading your system.
The BE utility automatically manages and updates the GRUB menu. For example, when you use the BE utility to create a new BE, that BE is automatically added to the GRUB menu.

The new BE utility, enables you to perform the following tasks:

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
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
Display information about your BE snapshots and datasets

Note - A clone is a bootable copy of a boot environment. A snapshot is a read-only copy of a file system or boot environment at a given point in time. A snapshot is not bootable.

BE Utility Requirements

To use the new BE utility to manage your boot environments, your system must meet the following requirements.

Table 3-1 System Requirements

Requirement	Description
OpenSolaris 2008.05 release	You must have OpenSolaris 2008.05 release installed on your system. Prior OpenSolaris releases did not include the BE utility. For information about installing this release, see Installing OpenSolaris 2008.05.
ZFS file systems	All OpenSolaris Developer releases have ZFS file systems. The BE utility is designed for ZFS file systems.

Limitations in Current Release

Note the following limitations for the OpenSolaris 2008.05 release.

The installation of the OpenSolaris OS supports only one pool on one disk.
The BE utility is implemented with ZFS support only.
The BE utility manages BEs and snapshots that were created by the BE utility. If a user manually creates the datasets for a BE by using the zfs(1M) command, the BE utility should recognize the BE, but management of this BE might be undefined.

How to Create a New BE, Based on the Active BE

You can use the beadm command to create and mount a new BE that is based on your active BE.

Note - When you create a new BE, the process first automatically takes a snapshot of the original BE, then the process makes a new clone that is derived from this snapshot. Both the new snapshot and the new clone are retained by the system.

Become superuser or assume an equivalent role.
At the command line, type the following:
```
$ beadm create beName
```
beName is a variable for the name of the new boot environment. This new BE is inactive.

Note - beadm create does not create a partial BE. The command either successfully creates a full BE, or the command fails.
(Optional) You can use the beadm mount command to mount the new boot environment as follows:
```
$ beadm mount beName mountpoint
```
Note - The mount point must be an already existing directory that is empty.
If the BE is already mounted, the beadm mount command fails and does not remount the BE at the newly specified location.

The BE is mounted, but remains inactive. You can upgrade a mounted, inactive BE.
(Optional) If you want to boot to this new BE, use the following command to activate the BE:
```
$ beadm activate beName
```
beName is a variable for the name of the BE to be activated.
On reboot, the newly active BE is displayed as the default selection in the GRUB menu.

Note - The GRUB menu always displays the mostly recently activated BE as the default.

Example 3-1 Creating a New, Cloned BE Dataset (BE2)

The following example illustrates the dataset in a newly created BE.

Type the following command.

$ beadm create BE2

The original dataset in this example is BE1. The new boot environment, BE2, is contained in its own dataset. The new BE can also contain separate datasets for traditional file systems, such as /var or /opt.

rpool/ROOT/BE1
rpool/ROOT/BE1/usr
rpool/ROOT/BE1/var
rpool/ROOT/BE1/opt

rpool/ROOT/BE2
rpool/ROOT/BE2/usr
rpool/ROOT/BE2/var
rpool/ROOT/BE2/opt

rpool in this example is the name of the storage pool. The pool already exists on the system, previously set up by the initial installation or upgrade. ROOT is a special dataset that was also created previously by the initial installation or upgrade. ROOT is reserved exclusively for use by BE roots.

Example 3-2 Creating a Clone With Shared File Systems

The following example illustrates the dataset in a newly created BE that has shared file systems.

Type the following command.

$ beadm create BE2

In this example, the shared file systems, rpool/export and rpool/export/home, are not cloned when the boot environment is cloned. The shared file systems are located outside the rpool/ROOT/<BE> datasets, and are referenced at their original locations by the cloned BE.

rpool/ROOT/BE1
rpool/ROOT/BE1/usr
rpool/ROOT/BE1/var
rpool/ROOT/BE1/opt
rpool/export
rpool/export/home

rpool/ROOT/BE2
rpool/ROOT/BE2/usr
rpool/ROOT/BE2/var
rpool/ROOT/BE2/opt
rpool/export/
rpool/export/home

How to Create a New BE, Based on an Inactive BE

By default, a new BE is created from the active BE. However, you can use the beadm create command to create a new boot environment that is based on an existing, inactive boot environment.

Become superuser or assume an equivalent role.
To create a new, inactive BE from an existing, inactive BE, type the following command:
```
$ beadm create -e non-activeBeName beName
```
non-activeBeName is a variable for the existing inactive BE that is cloned by this command.
beName is the variable for the new BE name.
By default, the new BE is inactive.

How to Create a Snapshot of a BE

You can manually create a snapshot of an existing BE. A snapshot is a read-only image of a file system or boot environment at a given point in time.

Become superuser or assume an equivalent role.
Use the following command to create a snapshot.
```
$ beadm create beName@snapshot
```
Replace the variable, beName@snapshot, with a custom name for your snapshot. The custom name must use the format BEname@snapshotdescription, where BEname is the name of an existing boot environment that you want to make a snapshot from. Type a custom snapshotdescription to identify the date or purpose of the snapshot.
Sample snapshot names include:
- BE1@0312200.12:15pm
- BE2@backup
- BE1@march132008

How to Create a BE From an Existing Snapshot

A snapshot is not bootable. However, you can create a BE, which is bootable, from an existing snapshot as described in this section.

Become superuser or assume an equivalent role.
Use the following command to create a new BE from a snapshot.
```
$ beadm create -e beName@snapshot beName
```
Replace the variable, beName@snapshot, with the name of an existing snapshot. As described in the previous task, snapshot names use the format BEname@snapshotdescription, where BEname is the name of an existing boot environment, and snapshotdescription is a description of a specific snapshot made from the existing BE.
Replace the variable, beName, with a custom name for your new boot environment.
See the following example.
```
$ beadm create -e BE1@now BE2
```
This command creates a new BE, named BE2, from the existing snapshot named BE1@now.

How to Activate an Existing BE

Become superuser or assume an equivalent role.
Use the following command to activate an existing, inactive boot environment:
```
$ beadm activate beName
```
beName is a variable for the name of the BE to be activated.
Note the following specifications.
- beadm activate beName activates a BE by setting the bootable pool property, bootfs, to the value of the ROOT dataset of the BE that is being activated.
- beadm activate sets the newly activated BE as the default in the menu.lst file.
  
  Note - When a BE is created, whether it is active or inactive, an entry is created for the BE on the GRUB menu. The default BE is the last BE that was activated.
Reboot.
The newly activated BE is now the default on the GRUB menu.

Note - If the BE fails to boot, reboot and select the previous BE from the GRUB menu.

How to Mount a BE

Become superuser or assume an equivalent role.
You can use the beadm mount command to mount a boot environment as follows:
```
$ beadm mount beName mountpoint
```
Note - The mount point must be an already existing directory that is empty.
If the BE is already mounted, the beadm mount command fails and does not remount the BE at the newly specified location.

The BE is mounted but remains inactive. You can upgrade a mounted, inactive BE.

How to Unmount an Existing BE

You can use the beadm command to unmount an existing boot environment.

Note - You cannot unmount the BE that is currently booted.

Become superuser or assume an equivalent role.
To unmount the BE, type the following:
```
$ beadm unmount beName
```

How to Destroy an Existing BE

You can use the beadm command to destroy an existing boot environment.

Note the following specifications:

You cannot destroy the BE that is currently booted.
The beadm destroy command destroys only the non-shared filesystems of the BE. Shared file systems are located outside of the BE root dataset area and are not affected when a BE is destroyed.
In this example, the shared file systems, rpool/export and rpool/export/home, are not destroyed when the boot environment BE2 is destroyed.
```
rpool/ROOT/BE1
rpool/ROOT/BE1/opt
rpool/ROOT/BE2
rpool/ROOT/BE2/opt
rpool/export
rpool/export/home 
```
The beadm destroy command automatically removes the destroyed BE's entry from the GRUB menu.

Become superuser or assume an equivalent role.
To destroy a BE, type the following:
```
$ beadm destroy beName
```
Note - The beadm destroy command asks for confirmation before destroying the BE. Add the -f option to the beadm destroy command to destroy the BE without this confirmation request.

How to Rename a Boot Environment

The beadm rename command enables you to rename an existing BE. The BE's dataset name is also changed to conform with the new BE name. This command enables you to create a custom name for a BE, a name that is more meaningful for your particular situation.

Note - An active BE cannot be renamed. Only an inactive BE can be renamed.

Become superuser or assume an equivalent role.
Use the following command to rename the boot environment:
```
$ beadm rename beName newBeName
```
Note - If the new name already is in use, the beadm rename fails.

How to Display Information About Your BE, Snapshots, and Datasets

All snapshots, BEs, and datasets that were created by the beadm command can be displayed with the beadm list subcommand.

Snapshots and BEs can be created by the beadm command. Snapshots and BEs can also be created by other utilities. For example, the pkg image-update command automatically creates a clone of a BE and upgrades that clone. beadm list also displays BEs that are created by the pkg image-update command.

Note the following definitions:

A snapshot is a read-only image of a file system or boot environment at a given point in time. A snapshot is not bootable.
A BE is a bootable OpenSolaris environment, consisting of a root file system and, optionally, other file systems mounted underneath it, such as /opt or /var. The root file system and all other file systems of the BE which contain system software are required to be ZFS datasets. Exactly one boot environment can be active at a time.
A clone is a BE that was created by copying another BE. A clone is a bootable BE.
A dataset is a generic name for ZFS entities such as clones, file systems, or snapshots. The dataset term more specifically refers to the file system specifications for a particular BE or snapshot.

Become superuser or assume an equivalent role.
Choose the information that you want to view, as described in this step.
- Choose an option for the beadm list command from the following list:
  - -a – Lists all available information about the boot environment. This option includes subordinate file systems and snapshots.
  - -d – Lists information about a BE's datasets.
  - -s – Lists information about a BE's snapshots.
  - -H – Omits the header information from the display. Choosing this option results in a display that can be more easily parsed for scripts or other programs.
- You can also choose whether to specify a BE name in the beadm list command.
  By default, if you do not include a BE name in the command, the results include all BEs.
  But, if you include a BE name in the beadm list command, the results include only information about that BE.
Type the beadm list command with preferred options.
For example, include the -a option and specify the BE1 environment as follows:
```
$ beadm list -a BE1
```
Review the information that is displayed.

Example 3-3 Viewing BE Specifications

This example includes the -a option and specifies the BE2 environment as follows:

$ beadm list -a BE2

Sample results are displayed.

BE       Active Active on Mountpoint Space
Name            reboot               Used
----     ------ --------- ---------- -----
BE2      no     yes       /tt        57.5K

   Datasets     Mountpoint Space Used
   --------     ---------- ----------
   BE2/opt      /tt/opt    0

Example 3-4 Viewing Snapshot Specifications

This example includes the -s option which displays information for any snapshots that exist on the current image. The status of those snapshots is the same list that the zfs(1M) command displays.

$ beadm list -s BE2

Sample results are displayed.

BE       Active Active on Mountpoint Space
Name            reboot               Used
----     ------ --------- ---------- -----
BE2      no     yes       /tt        57.5K

BE       Active Active on Mountpoint Space
Name            reboot               Used
----     ------ --------- ---------- -----
BE1      no     no        /tt2       57.5K

BE       Active Active on Mountpoint Space
Name            reboot               Used
----     ------ --------- ---------- -----
preview2 yes    no        legacy     2.02G

   Snapshots            Policy Date created
   ---------            ------ ------------
   preview2/opt@install static 2008-04-05 10:28:42
   preview2/opt@BE2     static 2008-04-06 20:09:27
   preview2/opt@BE1     static 2008-04-06 20:09:16
   preview2@BE1         static 2008-04-06 20:09:16
   preview2@BE2         static 2008-04-06 20:09:27
   preview2@install     static 2008-04-05 10:28:42