1. Introduction 1.1. Project/Component Working Name: SNAP BE management 1.2. Name of Document Author/Supplier: Evan Layton 1.3. Date of This Document: 07/20/2009 1.3.1. Date this project was conceived: 09/24/2007 1.4. Name of Major Document Customer(s)/Consumer(s): 1.4.1. The PAC or CPT you expect to review your project: Solaris PAC 1.4.2. The ARC(s) you expect to review your project: PSARC 1.4.3. The Director/VP who is "Sponsoring" this project: Greg.Lavender@sun.com 1.4.4. The name of your business unit: Solaris Software 1.5. Email Aliases: 1.5.1. Responsible Manager: Eric.Ray@Sun.COM 1.5.2. Responsible Engineer: Evan.Layton@Sun.COM 1.5.3. Marketing Manager: Dan.Roberts@Sun.COM 1.5.4. Interest List: caiman-discuss@opensolaris.org 2. Project Summary 2.1. Project Description: Snap Boot Environment (BE) Management provides the mechanism to safely update system software by capturing system states and allowing previous system states to be re-enabled. It does this by creating a ZFS clone of the current system. The definition of a boot environment (also called a BE) is an instance of a bootable OpenSolaris environment consisting of a root file system and, optionally, other file systems mounted underneath it (e.g. /usr, /var). The root file system and all other file systems of the BE which contain system software must be zfs datasets. This project will allow a user to very quickly create a duplicate image of their running system or other inactive BE, which can then be updated and booted. This project will provide a CLI (beadm) and library (libbe) interfaces for consumers to perform the following functions: - list BE's - This includes a BE's attributes. - create/destroy a BE - mount/unmount a BE - activate a BE - This makes the named BE the default BE on the next reboot. - rename a BE - rollback a BE - This rolls the BE's back to the state of a previous snapshot. This functionality will be used to do upgrades of the system. This will be done through the functionality provied by the "pkg image-update" command from pkg(5). Management of the BEs createdi will be done through the beadm CLI. 2.2. Risks and Assumptions: - This project presents a risk to the Image Packaging System (IPS) project. The IPS project can not be completed until this project is delivered. Note: Information on IPS is available from: http://opensolaris.org/os/project/pkg/ - This project makes heavy use of the libzfs interfaces. Since these are not quite stable and are still evolving somewhat it is necessary that we obtain a contract so that any changes to libzfs are communicated with us. 3. Business Summary The current Solaris live upgrade offering is outdated. It has become impossible to maintain and will not work with the Image Packaging System (IPS). Due to these deficiencies the time has arrived to design a new, simpler, approach. This approach incorporates new technologies such as the ZFS file system bootable ZFS file systems and the Image Packaging System (IPS). These technologies make possible this simpler and more robust BE management and update functionality. 3.1. Problem Area: Provide an open and fast method for creating bootable clones of a running system, which can then be upgraded. 3.2. Market/Requester: The Image Packaging System (IPS) project needs this project for upgrading/updating a system into a newly created BE. 3.3. Business Justification: - 3.4. Competitive Analysis: The Nexenta Transactional Debian Upgrades also leverage ZFS cloning for creating a copy or clone of the running system. However this system is lacking basic functionality for manipulating boot environments. This project provides us with not only a method for creating upgradable boot environments but provides for the management and manipulation of those boot environments. 3.5. Opportunity Window/Exposure: - 3.6. How will you know when you are done?: - When the CLI can call the library to correctly perform the following functionality and an automated test suite is complete: - list BE's - create/destroy a BE - mount/unmount a BE - activate a BE - rename a BE - rollback a BE - When the IPS project is able to use the library to perform its "pkg image-update" operations. 4. Technical Description: 4.1. Details: 4.1.1 BE definition: Snap Boot Environment (BE) Management provides the mechanism to safely update software by capturing system states and allowing previous system states to be re-enabled. It does this by creating a clone of the system. The definition of a boot environment (also called a BE) is an instance of a bootable OpenSolaris environment consisting of a root file system and, optionally, other file systems mounted underneath it (e.g. /usr, /var). The root file system and all other file systems of the BE which contain system software must be zfs datasets. 4.1.2 BE ZFS dataset layout: Boot Environments (BE) are encapsulated within the container dataset namespace described in PSARC case 2006/370. A BE's datasets will be contained within /ROOT/ and any subordinate datasets for that BE will be found within that hierarchy. We depend on zfs boot's process of mounting all the subordinate datasets under a BE's root dataset when a BE is booting up. For example: /ROOT/myBE mounted as / /ROOT/myBE/usr mounted as /usr /ROOT/myBE/var mounted as /var /ROOT/myBE/opt mounted as /opt Datasets that reside outside the designated /ROOT area are "shared" across all BEs. These are seen and mounted identically by a BE regardless of which BE is currently booted. These would be file systems that are not considered system file systems and would be things like /export. For example: rpool/export mounted as /export rpool/export/home mounted as /export/home These shared datasets are not normally mounted when a BE is mounted. 4.1.3 Zones support and dataset layout: Support for zones will be limited to zones that either support pkg(5) or branded zones that are not tied to the current BE's OS version, such as Linux branded zones. For Solaris zones, only installed or running zones are copied into a new BE. Zones that don't support the use of IPS are not managed at all and are shared between BEs without any changes. zones datasets will use a similar name space scheme for their datasets. The name space for zones will use the following pattern: //ROOT/ When a global zone BE is created based on a BE with non-global zones these zones are cloned/copied into the new BE. The new zone dataset that is created will have the same layout as the original but the zone BE name will be incremented. For example the dataset would follow this pattern: //ROOT/- (or rpool/export/zones/zone1/ROOT/zbe-1) The ability to create BEs inside a zone will also be supported with the ability to run beadm inside a non-global zone. A more detailed description of zones support is available at: http://opensolaris.org/os/project/caiman/Snap_Upgrade/snap-documents/Snap_zones_layout.pdf 4.1.4 GRUB menu and SPARC boot menu management: New BE's will be added to the boot/GRUB menus and we will support setting the default entries, removing and changing entries. 4.1.5 beadm sub-command interfaces: beadm CLI subcommands: list - Lists the BEs on the system and the data about the BE. create - Creates a new BE or a snapshot of a BE. This snapshot can later be used to create a new BE. destroy - Destroys a BE mount - Mounts the BE and all of its filesystems. Shared filesystems are not normally mounted unless the user specifies that they should be. In the case of zones the shared filesystems for the zones are mounted. umount/unmount - Unmounts the BE and all of its filesystems. rename - Renames the BE activate - Makes this the BE that will be the default at the next reboot. 4.2. Bug/RFE Number(s): 15292 PSARC/2010/059: BE management 6937131 EOL of live upgrade 4.3. In Scope: BE discovery - The ability to find BE's on the system. BE management - Management of BE's using the functionality mentioned above. Zone support (only zones supporting IPS) - Functionality to copy zones from the BE being copied into the new BE. library to support IPS - Library to provide functionality for BE Management. 4.4. Out of Scope: Support for filesystems other than ZFS. Support for zones that do not support IPS. Will not support BEs created using liveupgrade. 4.5. Interface tables: _________________________________________________________ | Interfaces Exported | |_________________________________________________________| |Interface | Classification | Comments | |_____________________|________________________|__________| |be_init | Consolidation Private | See [1] | |be_mount | Consolidation Private | See [1] | |be_unmount | Consolidation Private | See [1] | |be_create | Consolidation Private | See [1] | |be_destroy | Consolidation Private | See [1] | |be_rename | Consolidation Private | See [1] | |be_activate | Consolidation Private | See [1] | |be_create_snapshot | Consolidation Private | See [1] | |be_destroy_snapshot | Consolidation Private | See [1] | |be_rollback | Consolidation Private | See [1] | |be_list | Consolidation Private | See [1] | |be_free_list | Consolidation Private | See [1] | |beadm list | Committed | See [2] | |beadm create | Committed | See [2] | |beadm destroy | Committed | See [2] | |beadm mount | Committed | See [2] | |beadm unmount/umount | Committed | See [2] | |beadm rename | Committed | See [2] | |beadm activate | Committed | See [2] | |_____________________|________________________|__________| 1. libbe library (system/library/install package) 2. CLI interface (install/beadm package) The project imports the following interfaces. __________________________________________________________ | Interfaces Imported | |__________________________________________________________| |Interface | Classification | Package | |______________|__________________|________________________| |libinstzones | Uncommitted | package/svr4 | |______________|__________________|________________________| |libzfs | Contract Private | system/file-system/zfs | |______________|__________________|________________________| |installgrub | Uncommitted | SUNWcs | |______________|__________________|________________________| Note: We're seeking minor release binding 4.6. Doc Impact: Man page for beadm(1M) at: http://src.opensolaris.org/source/xref/caiman/slim_source/usr/src/man/beadm.1m.txt Additions will also need to be made to the user and admin docs. - http://dlc.sun.com/osol/docs/content/dev/snapupgrade/index.html 4.7. Admin/Config Impact: Addition of the new beadm CLI. 4.8. HA Impact: None 4.9. I18N/L10N Impact: Error messages need to be localized. 4.10. Packaging & Delivery: Currently delivered in SUNWinstall-libs and SUNWbeadm 4.11. Security Impact: The following will be added to the rights profiles: :::::::::::::: etc/security/exec_attr.d/SUNWbeadm :::::::::::::: Software Installation:suser:cmd:::/sbin/beadm:uid=0;gid=bin :::::::::::::: etc/security/prof_attr.d/SUNWbeadm :::::::::::::: Software Installation::::profiles=ZFS File System Management 4.12. Dependencies: ZFS boot 5. Reference Documents: http://opensolaris.org/os/project/caiman/Snap_Upgrade/ http://opensolaris.org/os/project/caiman/Snap_Upgrade/snap-documents/ PSARC 2007/039 Caiman: New Solaris Installation Experience PSARC 2006/370 ZFS Boot Support http://opensolaris.org/os/project/pkg/ 6. Resources and Schedule: 6.1. Projected Availability: Q2 CY2010 6.2. Cost of Effort: - 6.3. Cost of Capital Resources: No new hardware will be required. 6.4. Product Approval Committee requested information: 6.4.1. Consolidation or Component Name: ON 6.4.3. Type of CPT Review and Approval expected: Standard 6.4.4. Project Boundary Conditions: 6.4.5. Is this a necessary project for OEM agreements: No 6.4.6. Notes: None 6.4.7. Target RTI Date/Release: March 2010 6.4.8. Target Code Design Review Date: Feburary 2010 6.4.9. Update approval addition: None 6.5. ARC review type: Standard 6.6. ARC Exposure: Open 7. Prototype Availability: 7.1. Prototype Availability: Working version is available now in OpenSolaris