# # PREREQUISITES # You must install the following software at the indicated release or a later release: - LDoms 1.1 - Solaris 10 Update 6 - VxVM 5.0 MP3 # # INSTALL INSTRUCTIONS # To install the Boot Image Management tool, perform the following steps: 1. In a temporary directory copy and untar the bim.tar archive: # tar xf //bim.tar is the directory where you put the bim.tar file. The temporary directory now contains the following files: /bim.tar_path/default.xml /bim.tar_path/install_bim.sh /bim.tar_path/input.txt /bim.tar_path/vxbootadm /bim.tar_path/bimutility/vxlo /bim.tar_path/vxlo.conf /bim.tar_path/vxloadm /bim.tar_path/vxsnap 2. Run the install_bim.sh script to install the binaries associated with the tool: # ./install_bim.sh -i This will create the /opt/VRTS/bimutility directory and copy the neccessary files into it. 3. Verify that your PATH environment variable contains "/usr/sbin": # set | grep PATH PATH=:/usr/bin:/usr/local/bin 4. If PATH does not contain /usr/sbin, add /usr/sbin: # export PATH=$PATH:/usr/sbin # # INTRODUCTION AND CONCEPTS # The Boot Image Management tool aims at providing an automatic way of provisioning boot disks for guest Logical Domains (LDoms). Consider the scenario where you have a golden boot image that has been created by installing the required OS level and patches. You now want to use this image as a basis for installing multiple guest domains. Everytime you need to create a boot disk based off of the golden image, you must perform the following steps: 1. Ensure that you have enough storage for creating a clone of the golden image. 2. Use the appropriate cloning mechanism depending on the backend of the golden image to create a clone of the golden image. 3. Customize the new boot image such that the system parameters, such as IP address and hostname, are updated to work with the target LDom. On Solaris, you can enter the new system parameters by booting from the cloned image, running the sys-unconfig command, and then rebooting. 4. Change the OS native name in the /etc/vfstab file of the target image to match with the image's position in the operating system device tree at the time of booting the guest. These steps must be performed manually and must be repeated each time you create a clone. # WHAT THE TOOL DOES: The Boot Image Management tool makes the above set of manual steps transparent to the user by means of encapsulating the steps and eliminating the need for any manual intervention. VxVM instant snapshots are the ideal backing store in this scenario, as they are quick to create and minimize the space requirements. If the boot image that you are creating is intended for an existing LDom that is up and running, the tool provisions the image without shutting down the LDom. If the named LDom does not exist, the tool provisions the LDom using the specifications in the default.xml file. Refer to this file for details of the specifications. The tool operates on a simple set of principles: - The golden image must be contained in a VxVM volume. - The golden image must be created by the user; the tool does not do this for you currently. # WHAT THE TOOL DOES NOT DO: - All golden images and snapshots must be contained in a single disk group. The tool currently cannot operate on multiple disk groups. - Currently, the tool exports all snapshot volumes through the same virtual disk server interface: primary-vds0. - The tool does not support renaming the snapshot volumes that are serving as boot disks of the LDoms. The tool depends on the current naming convention to identify which boot disk services which LDom. # # USAGE INSTRUCTIONS # The golden image must be pre-created on a VxVM volume before trying to use this tool to provision LDom boot disks based off of the golden image. The usage options of the tool: vxbootadm - Logical Domains boot disk management utility vxbootadm create [-d ] vxbootadm create -g -v -l \ -i -h -s [ -f xml_file ] vxbootadm remove vxbootadm destroy ldom vxbootadm cache list vxbootadm list [] vxbootadm help [ keywords | options ] Use the "help keywords" and "help options" to get more details on the supported keywords and their options. 1) Create Options: 1.1) Interactive option: 'vxbootadm create' When used without any options, create launches an interactive menu that prompts the user to enter the following parameters: - Disk group containing the golden image - Volume containing the golden image - Target LDom's logical name - Target LDom's IP address - Target LDom's fully qualified hostname - Snapshot type for the boot image (so|full) - Cache object name, in the case of a Space Optimized(SO) snapshot. Upon completion of the provisioning process, if the user choose for the LDom to be started, it displays the port ID of the assigned console and exits. Example screenshot: ********************************************************************** Enter the diskgroup name:Bootdg Enter the source golden image volume name:gvol Enter the target ldom logical name:ldom_A Enter the target ldom hostname:t5240vm8-1.engba.symantec.com Enter the target ldom ip address:10.182.110.20 Here is a list of the input values entered by you: --------------------------------------------------- 1 Diskgroup Name: Bootdg 2 Volume Containing Golden Boot Image: gvol 3 Target LDom Name: ldom_A 4 Target LDom IP Address: 10.182.110.20 5 Target LDom host name: t5240vm8-1.engba.symantec.com --------------------------------------------------- Is the above information correct[Y|N]: Please enter the type of snapshot to be taken[so|full]:so Do you want to use an existing cache object?[Y|N]:Y -----List of existing cache objects----- CACHE NAME TOTAL(Mb) USED(Mb) (%) AVAIL(Mb) (%) cache_default 2048 149 (7) 1899 (92) cache_new 2048 40 (1) 2008 (98) Enter cache object name:cache_default Creating Snapshot for ldom_A using cache_default.... ... *************************************************************************** 1.2) Non-interactive option: 'vxbootadm create -g ...' This option allows the user to enter all of the parameters in a single instance, making the command non-interactive. Example: 1) To create a Space-Optimized boot image for an LDom: # vxbootadm create -g ldom_dg -v gvol -l ldom_D -i 10.182.110.23 \ -h t5240vm8-4.engba.symantec.com -s so The LDom boot image is allocated on a SO snapshot which depends on the golden volume for read operations on un-synchronized regions and any new writes are allocated out of the cache object. 2) To create a Full snapshot based boot image of an LDom: # vxbootadm create -g ldom_dg -v gold_sol10_u6 -l ldg_host5_full \ -i 192.0.0.1 -h t5240vm8-5.engba.symantec.com -s full A Full snapshot is independent from the source volume. 3) To provision a space-optimized snapshot based boot image for a non-existant LDom: # vxbootadm create -g ldom_dg -v gold_sol10_u6 .l apacheserver \ -i 10.180.192.12 .h sfapache1.engba.symantec.com -s so \ -x /tmp/apache1.xml The -x option allows the user to specify his own xml configuration file. NOTES: - The valid snapshot types are "so" or "full". The following error is displayed upon entering an invalid type: /usr/sbin/vxbootadm:ERROR: Invalid snapshot type specified Valid types are: so : space optimized instant snapshot full : full sized instant snapshot - The interactive option gives the user the flexiblity to choose the cache object to be used as the backing store for the space-optimized snapshot that is being created. You can choose from a list of existing cache objects, or you can choose to create a new cache object. The non-interactive options default to using an existing cache object that has less than 80% used space. 1.3) Option to take input from a file: 'vxbootadm create -d ' This option allows you to specify all input parameters in a file. You then pass the file to the tool, which reads and processes the input parameters from the file. The file must be in a specific format. See the sample file, "input.txt", for the format. Example: # vxbootadm create -d /opt/VRTS/bimutility/input.txt NOTE: When adding a boot disk which is not the first disk exported to the ldom, please run "devfsadm -C" after booting from that boot disk to create the /dev/dsk devlinks if they are not already created. 2) Removing a boot image: 'vxbootadm remove ' This command removes the snapshot and the snapshot's virtual disk bindings from the associated LDom. This operation requires a shutdown of the LDom because removal of a VxVM snapshot requires the snapshot not to have any opens on it. As long as a snapshot is exported to a guest that is bound, the snapshot cannot be removed. Example: # vxbootadm remove sboot2_ldom_G Removing sboot2_ldom_G from ldom_G.... 3) Destroying an LDom: 'vxbootadm destroy ' This option will remove any boot devices containing the boot image from the named LDom and then also delete the underlying snapshot volumes. It will finally delete the LDom as well. This option will fail if the named LDom has any non-boot devices exported to it. Example: # ./vxbootadm destroy ldom_E Removing sboot1_ldom_E from ldom_E.... Removing domain ldom_E... If an LDom with one or more non-boot devices (devices not created using vxbootadm utility) is specified, following error is printed: # ./vxbootadm destroy ldom_B ./vxbootadm:ERROR: The ldom ldom_B has at least one non-boot device ./vxbootadm:ERROR: destroy cannot be executed on such an LDom 4) Listing the boot images: 'vxbootadm list ' The list option displays the following fields: Listing all Logical Domains and their boot disk bindings: VDISK VDSDEV LDOM SIZE TYPE PARENT CHANGED_DATA VOLUME_PATH The fields are as follows: VDISK virtual disk name. VDSDEV virtual disk service name. LDOM Logical Domain Name. SIZE Logical size of the boot image in Gigabytes. TYPE snapshot type, full or space-optimized. PARENT source volume of the snapshot or volume containing the golden image. CHANGED_DATA Data change in MB and % since the snapshot was taken. VOLUME_PATH Block device path of the snapshot volume. 5) Listing the cache object statistics: 'vxbootadm cache list' This displays the statistical overview of the various cache objects that the tool manages. In addition, it also gives a detailed view of each cache object which includes the names of each snapshots associated with that cache object, it's storage attributes in terms of megabytes and percentages. Along with displaying the snapshot name, it also displays the data changed on the snapshot since it was taken. It also maps the snapshot name to the Logical Domain name that it provides a boot image to. Example: # vxbootadm cache list ---------- Cache Object Overview ---------- Cache Object Name Total(MB) Used(MB)(%) Avail(MB) (%) cache_default 2048 154 (7) 1894 (92) cache_new 2048 40 (1) 2008 (98) ---------- Cache Object Details ---------- Details for cache object: cache_default Cache Object Name Total(MB) Used(MB)(%) Avail(MB) (%) cache_default 2048 154 (7) 1894 (92) Volume Name Modified data(MB) (%) Logical Domain sboot1_ldom_A 28.4M (0.3%) ldom_A sboot1_ldom_C 21.2M (0.2%) ldom_C Details for cache object: cache_new Cache Object Name Total(MB) Used(MB)(%) Avail(MB) (%) cache_new 2048 40 (1) 2008 (98) Volume Name Modified data(MB) (%) Logical Domain sboot1_ldom_E 34.9M (0.3%) ldom_E # # UNINSTALL INSTRUCTIONS # Go to the /bim.tar_path/ directory containing the untared BIM related files and run the following command: # ./install_bim.sh -u This removes the binaries associated with the tool and also updates the Solaris boot archive.