BE Utility for Snap Upgrade Design Specifications Revision 0.4 1. Introduction 1.1 Overview The BE utility is the user interface for managing Boot Environments and is the replacement for the Live Upgrade commands (luupgrade(1M), lucreate(1M)...) This utility is intended to be used by System Administrators who want to manage multiple Solaris Instances on a single system. The BE utility will be implemented with ZFS support only, however a migration path from UFS to ZFS will also be supported but not in the Spring release. 1.2 Definitions BE - Boot Environment This is an instance of a bootable Solaris environment consisting of a set of mount points, file systems, ZFS data sets and nes. The file systems that make up a BE, which are supported by beadm, will only be ZFS file systems. The currently active UFS BE's will be migrated to a ZFS BE. 2. Requirements The BE utility will support the following operations: - Create a new BE, based on the active BE. - Create a new BE, based on a BE other than the active BE. - Mount a BE. - Unmount a BE. - Destroy a BE. - Rename a BE. - Activate a BE. - Upgrading of a BE will be done by pkg(1) - List all BE's in a human readable format. - List all BE's in a pragmatic format. 3. Command line interface Name: /usr/sbin/beadm Manage Boot Environments Synopsis: beadm [-?] Display usage. beadm create [-a] [-f] [-z] [-e non-activeBeName | beSnapshot] [-o property=value] ... [-p zpool] [-u] beName beadm create beSnapshot -a - Activate the newly created BE. Default is to not activate the newly created BE. -e - non-activeBeName - Create a new BE from a non-active BE. Default is to create the BE from the active BE. -e - beSnapshot - Create a new BE from a previously created snapshot. beSnapshot must be of the form BE@ -p zpool - Create a new BE in the specified root zpool. Default is to create the BE in the active zpool. -o - property=value - Create a new BE with ZFS properties. Multiple -o options can be specified. See zfs(1M) for more information on the -o option. beName - Name of the BE to create. beSnapshot - Name of the snapshot to create. beadm destroy [-f] [-F] beSnapshot | beName -f - Force the BE to be umounted before destroying. -F - Don't prompt if interaction is needed. beSnapshot - must be of the form beName@description beadm rename beName newBeName beadm list [[-a] | [-d] [-s] [-z]] [-H] [beName] -a - List snapshots, containers and datasets. -d - List the datasets. -H - Don't list any header information. -s - List the snapshots. -z - List the containers. beName - If beName is not provided then list all BE's. The default is to list BE's without any additional information. If beName resides in a non-active zpool then the list subcommand will attempt to find it. beadm mount beName mountpoint beadm unmount [-f] beName beadm activate beName Make beName the active BE upon next reboot. Returns 0 - Success >0 - Failure 3.1 Log interface /var/log/beadm//create.log. 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 /var/log is chosen since it will probably be shared across all BE's. The actual information contained in the log is yet to be determined. 3.2 Command line interface details 3.2.1 beadm create ... The create option will create a boot environment on a ZFS enabled system from the active BE or any non-active BE. Each BE will be its own dataset in a reserved namespace. Each BE could also contain separate datasets for traditional file systems (/usr, /var...) and separate datasets for any zones that are configured with zonecfg(1M). The following shows datasets for some example BE's and zones: rpool1/ROOT/BE1 rpool1/ROOT/BE1/var rpool1/ROOT/BE1/usr rpool1/zones/zone1/ROOT rpool1/zones/zone2/ROOT rpool2/ROOT/BE2 rpool2/zones/zone3/ROOT rpool2/zones/zone4/ROOT rpool1 and rpool2 are zpool's. Note that the zpool names are just an example and the pools will already exist on the system, previously setup by initial install or upgrade. ROOT is the default name given to the directory containing the boot environments. All BE's will be located within the default name space. BE1 and BE2 are the names of the BE's. zone{1,2,3,4} are zones within BE's BE1 and BE2 respectively. If the -o option is provided then the behavior of the -o option is exactly as described in zfs(1M). The properties will be passed to zfs when creating the Boot Environment. If an invalid property is provided and zfs(1M) fails to add the property to the dataset, then the creation of the Boot Environment will fail and appropriate message will indicate the error. If a snapshot is provided as the -e argument then the source of the target BE is a previously created snapshot of a BE. If a snapshot is not a previously created snapshot of a BE then beadm will exit with an error and display an appropriate message. If a snapshot is the target of the create subcommand, the second form in section 3, then a snapshot will be attempted to be created insted of a BE. A snapshot will only be taken from the active BE. 3.2.1.1 Creating Zones By default, zones on the source BE, if they exist, will automatically be created on the target BE depending upon there location on the source BE. The following sections describe the different scenarios and how "beadm create" will handle them. 3.2.1.2 Zone(s) in the BE root name space In this case, all the zones datasets within the root BE will automatically be cloned. The zones in the root name space will be handled like any other dataset and no special handling will be done for these zones. Zones should not be created in the BE's root area. 3.2.1.3 Zone(s) in a shared dataset When a zone resides in a shared file system it will not be cloned sine it is shared between multiple zones. An example of a file systems with a zone in a shared dataset follows: Existing source BE: rpool/ROOT/BE1/ rpool/ROOT/BE1/usr rpool/ROOT/BE1/var rpool/ROOT/BE1/opt rpool/zones/zone1/ROOT (mounted as /zones/zone1) rpool/zones/export (mounted as /zones/export) Target BE after creation: rpool/ROOT/BE2/ rpool/ROOT/BE2/usr rpool/ROOT/BE2/var rpool/ROOT/BE2/opt rpool/zones/zone1-BE2/ROOT (mounted as /zones/zone1) rpool/zones/export (mounted as /zones/export) rpool/zones is a shared dataset which contains the zone zone1 and a shared area, export. zone1 will be cloned since it is in a private area and export will not be cloned. 3.2.1.4 Zones using dedicated datasets/file systems A dedicated dataset for a zone will be outside the "ROOT" area of the current BE (/ROOT). When these zones are copied from one BE to another BE only the private dataset for the zone will be cloned. The shared datasets will not be cloned. Existing source BE: rpool/ROOT/BE1/ rpool/ROOT/BE1/usr rpool/ROOT/BE1/var rpool/ROOT/BE1/opt rpool/zones/zone1/ROOT rpool/zones/zone1/ROOT/zone1-BE1 (mounted as /zones/zone1/ZBE1) rpool/zones/zone1/ROOT/zone1-BE1/var (mounted as /zones/zone1/ZBE1/var) zone1 is a zone in a dedicated dataset. ZBE1 is a BE in zone1. Target BE after creation: rpool/ROOT/BE2/ rpool/ROOT/BE2/usr rpool/ROOT/BE2/var rpool/ROOT/BE2/opt rpool/zones/zone1/ROOT (mounted as /zones/zone1) rpool/zones/zone1/ROOT/zone1-BE2 (mounted as /zones/zone1/ZBE2) rpool/zones/zone1/ROOT/zone1-BE2/var (mounted as /zones/zone1/var) 3.2.2 beadm list ... Will list all the BE's created by beadm create and any other BE that resides in the reserved namespace. The following will be the default output: BE Active Mountpoint Space Policy Created -- ------ --------- ----- ------ ------- be2 N / 183.08M static 2008-08-27 16:48 be3 - - 0B static 2008-08-28 08:49 snv_95 R - 5.70G static 2008-08-27 15:23 The old tool for listing BE's is lustatus(1). It listed the following attributes that will not be listed by beadm: - Is Complete - Can Delete - Copy Status beadm create will never create a partial BE. It will either have succeeded or failed. There will never be an in between state. The "Can Delete" attribute is redundant since all BE's, except the active BE can be destroyed. "destroy" subcommand will not allow the active BE to be destroyed. See "beadm destroy" for more information. The "Copy Status" attribute is not necessary. The "create" subcommand will either successfully create a new BE based off an existing BE or it will not. beadm will not provide a mechanism for managing read/write control. As displayed above there will be five attributes describing a BE with the "list" subcommand. All are self explanatory except the "Active" column. The "Active column uses character's to indicate the status of a BE. Currently there are 2 states available, N and R, Note that there can be additional states added in the future: N - Is the currently active BE R - Will be the active BE after a reboot 3.2.2.1 beadm list -d If the -d option is provided beadm list will display the datasets that make up the BE's. The status of those datasets will either be mounted or unmounted as follows: BE/Dataset Active Mountpoint Space Policy Created ---------- ------ ---------- ----- ------ ------- be2 rpool/ROOT/be2 N / 183.08M static 2008-08-27 16:48 be3 rpool/ROOT/be3 - - 0B static 2008-08-28 08:49 snv_95 rpool/ROOT/snv_95 R - 5.67G static 2008-08-27 15:23 3.2.2.2 beadm list -z If the -z option is provided beadm list will display the zones, if any, that are contained within BE's. The status of those zones will be the same list that zoneadm(1M) list displays. The following is an example of the output of the subcommand on a global zone: BE/Zone Zonepath Dataset Space Created ------- -------- ------- ----- ------- be2 zone1 /zones/zone1 rpool/zones/zone1 13.08M 2008-08-28 21:48 be3 zone2 /zones/zone2 rpool/zones/zone1 0B 2008-08-29 18:49 snv_95 zone3 /zones/zone3 rpool/zones/zone1 810.00M 2008-08-29 22:23 Note that each zone can contain one or more BE's. Any BE within a zone will not be displayed from the active BE. To display the BE's in a zone, one must login to the zone first before invoking "beadm list ...". 3.2.2.3 beadm list -s If the -s option is provided beadm list will display the Snapshots, if any, that exist for any BE. The status of those Snapshots will be the same list that zfs(1M) list displays. The following is an example of the output of the subcommand: BE/Snapshot Space Policy Created ----------- ----- ------ ------- be2 be3 snv_95 snv_95@be2 166.0K static 2008-08-27 16:48 snv_95@be3 4.75M static 2008-08-28 08:49 3.2.2.4 beadm list -a If the -a option is provided beadm list will display Datasets, zones and Snapshots that exist for any BE. The following is an example of the output of the subcommand: BE/Dataset/Snapshot/Zone Active Mountpoint Space Policy Created ------------------------ ------ ---------- ----- ------ ------- be2 rpool/ROOT/be2 N / 183.08M static 2008-08-27 16:48 zone1 - /zones/zone1 13.08M - 2008-08-27 16:48 be3 rpool/ROOT/be3 - - 0B static 2008-08-28 08:49 zone2 - - 0B - 2008-08-27 16:48 snv_95 zone3 - - 810.08M - 2008-08-27 16:48 rpool/ROOT/snv_95 R - 5.67G static 2008-08-27 15:23 rpool/ROOT/snv_95@be2 - - 166.0K static 2008-08-27 16:48 rpool/ROOT/snv_95@be3 - - 4.75M static 2008-08-28 08:49 3.2.2.5 beadm list -H If the -H option is provided, beadm list will display the BE's and associated fields without header information. The list -H subcommand and option will display BE's, the UUID of the BE, Datasets, Zones and Snapshots. The ';' delimits BE's, Datasets, Zones and Snapshots. The ':' delimits attributes for BE's, Datasets, Zones and Snapshots. The ',' delimits multiple Datasets, Zones and Snapshots. Multiple BE's are delimited with a carriage return. The following is an example of what will be output on stdout for the BE's listed in section 3.2.2.4: BE:UUID:ACTIVE_FLAG:MOUNTPOINT:SIZE:POLICY:DATE_CREATED be2:123-4FG56-43RTON:N:/:191972864:static:1219880900 be3:123-4FG56-4369WQ:::0:static:1219938597 snv_95:473-4FG56-19IO6P:R::6118979584:static:1219875794 Note that the format of the UUID is yet to be determined. 3.2.2.6 beadm list -Hs Shows only the snapshot information: Since snv_95 is the only BE that has snapshots, only those are shown: BE;{SNAPSHOT:ACTIVE_FLAG:MOUNTPOINT:SIZE:POLICY:DATE_CREATED}... snv_95;snv_95@be2:169984:static:1219880900,snv_95@be3:4975616:static:1219938597,snv_95@snv_95.2:25953280:static:1219880200 3.2.2.7 beadm list -Hd Shows the BE and the dataset information: BE;{DATASET:ACTIVE_FLAG:MOUNTPOINT:SIZE:POLICY:DATE_CREATED}... be2;rpool/ROOT/be2:N:/:191972864:static:1219880900 be3;rpool/ROOT/be3:::0:static:1219938597 snv_95;rpool/ROOT/snv_95:R::6087880704:static:1219875794 3.2.2.8 beadm list -Ha Shows the BE, dataset, snapshot and zone information: BE:UUID;{DATASET:ACTIVE_FLAG:MOUNTPOINT:SIZE:POLICY:DATE_CREATED}... be2:123-4FG56-43RTON;rpool/ROOT/be2:N:/:191972864:static:1219880900 be3:123-4FG56-43RTON;rpool/ROOT/be3:::0:static:1219938597 snv_95:123-4FG56-43RTON;rpool/ROOT/snv_95:R::6087880704:static:1219875794;rpool/ROOT/snv_95@be2:::169984:static:1219880900,rpool/ROOT/snv_95@be3:::4975616:static:1219938597,rpool/ROOT/snv_95@snv_95.2:::25953280:static:1219880200 3.2.3 beadm destroy ... beadm destroy will only destroy a non-active BE. If the active BE is attempted to be destroyed, beadm will not allow the destruction. If zones exist within the non-active BE then those zones will also be destroyed. beadm destroy will prompt the user to continue with the destruction unless the -F option is provided. If the -F option is provided the BE will be destroyed without prompting. If -f is provided then the BE will be destroyed even if it has datasets mounted. Those datasets will be attempted to be unmounted before the BE is destroyed. 3.2.4 beadm rename ... beadm rename will allow the user to rename a BE to another name. Since the name of a BE is a part of a ZFS dataset as described above, the dataset name will need to be changed. Once changed the ZFS list command will show the new name in the listing as well as will the beadm list command. If the BE to be renamed contains zones then those zones root paths will not be renamed. If a dataset exists and is named the same as then the attempt to rename the BE will fail. The user will have to do a "zfs destroy" and "zfs rename" if they want to change names to an existing dataset. The active BE will not be allowed to be renamed since the active BE cannot be unmounted. A rename will not allow a BE to be renamed if and reside in different zpools. 3.2.5 beadm mount & unmount 3.2.5.1 mount beadm mount will allow a user to mount a non-active BE to a mount point. If that mount point doesn't exist beadm mount will attempt to create it. If the BE is already mounted at an existing mount point it will be unmounted and mounted at the new mount point. All mount points must be within the namespace mentioned in 3.2.2. If the mount point doesn't reside within the supported namespace then beadm will halt and provide an appropriate message to stderr. If a is not provided on the command line then beadm will halt and provide an appropriate message to stderr. 3.2.5.2 unmount A non-active BE can be unmounted if it is mounted. If that mounted BE contains zones and those zones have separate mountable file systems then those file systems will be unmounted if they are mounted. 3.2.6 beadm activate beadm activate will, with no arguments, display the name of the BE that will be active upon the next reboot of the system. When beName is provided, beadm activate activates the specified BE associated with beName. beadm activate activates a BE by setting the zpool bootable property, bootfs, to true. The bootfs property of the zpool will be set for the root dataset of the BE that's being activated. beadm activate will then create a grub entry in the BE's menu.lst file. The title displayed to the user will be the name of the BE and the dataset that corresponds to the name of the BE. e.g: Solaris Boot Environment "BE2" pool/ROOT/BE1 Once a BE has been activated it will continue to be an option upon boot. This means that if there are 4 BE's configured on a system and 2 of the 4 have been activated, those 2 will be selectable during boot. The default BE will be the last BE that has been activated. So the boot menu could look as follows: Solaris Boot Environment "BE2" pool/ROOT/BE1 Solaris Boot Environment "BE1" pool/ROOT/BE2 OpenSolaris Preview ... ... If a BE fails to boot, information on how to recover will be displayed at boot time and not at activation time. For most failed boot attempts the instructions will be to simply boot from the previously booted BE. If the first BE created fails to boot then either the old UFS BE will still be available for booting if the BE has been migrated from UFS or the last ZFS BE will be available. 4.0 References Snap Upgrade project page http://www.opensolaris.org/os/project/caiman/Snap_Upgrade/ 5.0 Issues The design calls out features that depend on other projects, see Section 2. If those dependencies can't be met then either the features listed need to be re-worked or the project will deliver a subset of the features described in this document.