- online man pages   

SunOS man pages : lucreate (1)

Maintenance Commands                                 lucreate(1M)


lucreate - create a new boot environment


lucreate [ -c BE_name ] [ -C ( boot_device | - ) ] - n BE_name [ -l error_log ] [ -o outfile ] [ -s ( - | source_BE_name ) ] [ [ -M slice_list ] | [ -m mountpoint:device:fs_type [ -m... ] ] ]


The lucreate command is part of a suite of commands that make up the Live Upgrade feature of the Solaris operating environment. See live_upgrade(5) for a description of the Live Upgrade feature and its associated terminology. The lucreate command offers a set of command line options that enable you to perform the following functions: o Create a new boot environment (BE), based on the current BE. o Create a new BE, based on a BE other than the current BE. o Join or separate the file systems of a BE onto a new BE. For example, join /var and /opt under /, or separate these directories to be mounted under dif- ferent disk slices. o Create the file systems for a BE, but leave those file systems unpopulated. You can perform the preceding functions using only lucreate command-line options or you can enter a set of options that will automatically invoke an FMLI-based interface that pro- vides curses-based screens for Live Upgrade administration. The creation of a BE includes selecting the disk or device slices for all the mount points of the BE. You can also change the mount points of the BE using the SPLIT and MERGE functions of the FMLI-based configuration screen. Upon successful creation of a BE, you can use lustatus(1M) to view the state of that BE and lufslist(1M) to view the BE's file systems. You use luupgrade(1M) to upgrade the OS on that BE and luactivate(1M) to make a BE active, that is, designate it as the BE to boot from at the next reboot of the system. The lucreate command makes a distinction between the file systems that contain the OS-/, /usr, /var, and /opt-and those that do not, such as /export, /home, and other, user- SunOS 5.8 Last change: 22 Oct 2001 1 Maintenance Commands lucreate(1M) defined file systems. The file systems in the first category cannot be shared between the source BE and the BE being created; they are always copied from the source BE to the target BE. By contrast, the user-defined file systems are shared by default. For Live Upgrade purposes, the file sys- tems that contain the OS are referred to as non-shareable file systems; other file systems are referred to as share- able. A non-shareable file system listed in the source BE's vfstab is always copied to a new BE. For a shareable file system, if you specify a destination slice, the file system is copied. If you do not, the file system is shared. Except for a special use of the -s option, described below, you must have a source BE for the creation of a new BE. By default, it is the current BE. You can use the -s option to specify a BE other than the current BE. By default, all swap partitions on a source BE are shared between the source and target BE. You can use the -m option (see below) to specify a subset of swap partitions on a source BE for sharing with a target BE. The lucreate command requires root privileges.


The lucreate command has the options listed below. Note that a BE name must not exceed 30 characters in length and must consist only of alphanumeric characters and other ASCII characters that are not special to the Unix shell. See the "Quoting" section of sh(1). The BE name can contain only single-byte, 8-bit characters. Omission of -m or -M options (described below) in an lucreate command line invokes the FMLI-based interface, which allows you to select disk or device slices for a BE. -c BE_name Assigns the name BE_name to the current BE. This option is required only when the first BE is created. For the first time you run lucreate, if you omit -c you are prompted to name the current BE. If you use the -c option following the first BE creation, you receive an error message. -C (boot_device | -) Required when you have a mirrored root device on the source BE. Specifies the physical boot device the source BE is booted from. When you use - (hyphen) with the -C option, lucreate attempts to figure out the boot device. If you specify boot_device, you override this automatic lookup. When you specify boot_device, you are queried: SunOS 5.8 Last change: 22 Oct 2001 2 Maintenance Commands lucreate(1M) Is the physical device devname the boot device for the logical device devname? If you respond y, the command proceeds. With the -C -, the preceding query is suppressed. With either form of -C, if lucreate cannot find the boot device, you receive an error message. Use of the -C - form is a safe choice, because lucreate either finds the correct boot device or gives you the opportunity to specify that device in a subsequent command. -l error_log Error messages and other status messages are sent to error_log, in addition to where they are sent in your current environment. -m mountpoint:device:fs_type [- m mountpoint:device:fs_type] ... Specifies the vfstab(4) information for the new BE. The file systems specified as arguments to -m can be on the same disk or can be spread across multiple disks. mountpoint can be any valid mount point or - (hyphen), indicating a swap partition. The device field can be one of the following: o The name of a disk device, of the form /dev/dsk/cnumtnumdnumsnum. o The keyword merged, indicating that the file system at the specified mount point is to be merged with its parent. The fs_type field can be ufs, indicating a UFS file system; vxfs, indicating a Veritas file system; or swap, indicating a swap file system. At minimum, you must specify one disk or device slice, for root. You can do this with -m, -M (described below), or in the FMLI-based interface. You must specify an -m argument for each file system you want to create on a new BE. For example, if you have three file systems on a source BE (say, /, /usr, and /var) and want these three entities as separate file systems on a new BE, you must specify three -m argu- ments. If you were to specify only one, in our example, /, /usr, and /var would be merged on the new BE into a single file system, under /. When using the -m option to specify swap partition(s), you can designate only swap partitions (all or a SunOS 5.8 Last change: 22 Oct 2001 3 Maintenance Commands lucreate(1M) subset) on the source BE. Any swap assignment made with -m replaces (that is, does not add to) existing swap assignments. See EXAMPLES, below. -M slice_list List of -m options, collected in the file slice_list. Specify these arguments in the format specified for -m. Comment lines, beginning with a hash mark (#), are ignored. The -M option is useful where you have a long list of file systems for a BE. Note that you can com- bine -m and -M options. For example, you can store swap partitions in slice_list and specify / and /usr slices with -m. The -m and -M options support the listing of multiple slices for a given mount point. In processing these slices, lucreate skips any unavailable slices and selects the first available slice. See EXAMPLES. -n BE_name The name of the BE to be created. BE_name must be unique on a given system. -o outfile All command output is sent to outfile, in addition to where it is sent in your current environment. -s (- | BE_name) Source for the creation of the new BE. This option enables you to use a BE other than the current BE as the source for creation of a new BE. If you specify a hyphen (-) as an argument to -s, lucreate creates the new BE, but does not populate it. You can then use lumake(1M) or luupgrade(1M) to populate the BE. This option is especially useful for installing a flash archive. See flar(1M).


The lucreate command produces copious output. In the follow- ing examples, this output is not reproduced, except where it is needed for clarity. Example 1: Creating a New Boot Environment for the First Time The following command sequence creates a new boot environ- ment on a machine on which a BE has never been created. Note that, in the first command, the -c option is omitted. # lucreate -m /:/dev/dsk/c0t4d0s0:ufs -m /usr:/dev/dsk/c0t4d0s1:ufs \ -n second_disk lucreate: Please wait while your system configuration is determined. SunOS 5.8 Last change: 22 Oct 2001 4 Maintenance Commands lucreate(1M) lucreate: No name for Current BE. lucreate: ERROR: The current BE is not named - please provide the name to use for the current BE with the <-c> option. The same command is entered, with the addition of -c: # lucreate -c first_disk -m /:/dev/dsk/c0t4d0s0:ufs \ -m /usr:/dev/dsk/c0t4d0s1:ufs -n second_disk many lines of output lucreate: Creation of Boot Environment <second_disk> successful. Following creation of a BE, you use luupgrade(1M) to upgrade the OS on the new BE and luactivate(1M) to make that BE the BE you will boot from upon the next reboot of your machine. Note that the swap partition and all shareable file systems for first_disk will be available to (shared with) second_disk. # luupgrade -u -n second_disk \ -s /net/installmachine/export/solarisX/OS_image many lines of output luupgrade: Upgrade of Boot Environment <second_disk> successful. # luactivate second_disk See luupgrade(1M) and luactivate(1M) for descriptions of those commands. Example 2: Creating a BE using a Source Other than the Current BE The following command uses the -s option to specify a source BE other than the current BE. # lucreate -s third_disk -m /:/dev/dsk/c0t4d0s0:ufs \ -m /usr:/dev/dsk/c0t4d0s1:ufs -n second_disk many lines of output lucreate: Creation of Boot Environment <second_disk> successful. Example 3: Creating a BE from a Flash Archive Performing this task involves use of lucreate with the -s - option and luupgrade. # lucreate -s - -m /:/dev/dsk/c0t4d0s0:ufs -m /usr:/dev/dsk/c0t4d0s1:ufs \ -n second_disk brief messages lucreate: Creation of Boot Environment <second_disk> successful. With the -s option, the lucreate command completes it work within seconds. At this point, you can use luupgrade to install the flash archive: SunOS 5.8 Last change: 22 Oct 2001 5 Maintenance Commands lucreate(1M) # luupgrade -f -n second_disk \ -s /net/installmachine/export/solarisX/OS_image \ -J "archive_location" See luupgrade(1M) for a description of that command. Example 4: Using Swap Partitions on Multiple Disks The command below creates a BE on a second disk and speci- fies the sharing of swap partitions on both the first and second disks. Note that the current boot environment must already be using /dev/dsk/c0t0d0s1 and /dev/dsk/c0t4d0s1 (on the second disk) as its swap partitions before entering this command. # lucreate -m /:/dev/dsk/c0t4d0s0:ufs -m -:/dev/dsk/c0t4d0s1:swap \ -m -:/dev/dsk/c0t0d0s1:swap -n second_disk many lines of output lucreate: Creation of Boot Environment <second_disk> successful. Following completion of the preceding command, the BE second_disk will use both /dev/dsk/c0t0d0s1 and /dev/dsk/c0t4d0s1 as swap partitions. These swap assignments take effect only after booting from second_disk. If you have a long list of swap partitions, it is useful to use the -M option, as shown below. Example 5: Using a Combination of -m and -M Options In this example, a list of swap partitions is collected in the file /etc/lu/swapslices. The location and name of this file is user-defined. The contents of /etc/lu/swapslices: -:/dev/dsk/c0t3d0s2:swap -:/dev/dsk/c0t3d0s2:swap -:/dev/dsk/c0t4d0s2:swap -:/dev/dsk/c0t5d0s2:swap -:/dev/dsk/c1t3d0s2:swap -:/dev/dsk/c1t4d0s2:swap -:/dev/dsk/c1t5d0s2:swap This file is specified in the following command: # lucreate -m /:/dev/dsk/c02t4d0s0:ufs -m /usr:/dev/dsk/c02t4d0s1:ufs \ -M /etc/lu/swapslices -n second_disk many lines of output lucreate: Creation of Boot Environment <second_disk> successful. The BE second_disk will swap onto the partitions specified in /etc/lu/swapslices. As with the previous example, the current BE must already be using the swap partitions speci- fied on the command line before you enter the lucreate SunOS 5.8 Last change: 22 Oct 2001 6 Maintenance Commands lucreate(1M) command. Example 6: Copying Versus Sharing The following command copies the user file system /home (in addition to the non-shareable file systems / and /usr) from the current BE to the new BE: # lucreate /:/dev/dsk/c0t4d0s0:ufs -m /usr:/dev/dsk/c0t4d0s1:ufs \ -m /home:/dev/dsk/c0t4d0s4:ufs -n second_disk The following command differs from the preceding in that the -m option specifying a destination for /home is omitted. The result of this is that /home will be shared between the current BE and the BE second_disk. # lucreate /:/dev/dsk/c0t4d0s0:ufs -m /usr:/dev/dsk/c0t4d0s1:ufs \ -n second_disk Example 7: Invoking FMLI-based Interface The command below, by omitting -m or -M options, invokes the FMLI-based interface for Live Upgrade operations. See lu(1M) for a description of this interface. # lucreate -n second_disk The preceding command uses the current BE as the source for the target BE second_disk. In the FMLI interface, you can specify the target disk slices for second_disk. The follow- ing command is a variation on the preceding: # lucreate -n second_disk -s third_disk In the preceding command, a source for the target BE is specified. As before, the FMLI interface comes up, enabling you to specify target disk slices for the new BE. Example 8: Merging File Systems The command below merges the /usr/opt file system into the /usr file system. First, here are the disk slices in the BE first_disk, expressed in the format used for arguments to the -m option: /:/dev/dsk/c0t4d0s0:ufs /usr:/dev/dsk/c0t4d0s1:ufs /usr/opt:/dev/dsk/c0t4d0s3:ufs The following command creates a BE second_disk and performs the merge operation, merging /usr/opt with its parent, /usr. SunOS 5.8 Last change: 22 Oct 2001 7 Maintenance Commands lucreate(1M) # lucreate -m /:/dev/dsk/c0t4d0s0:ufs -m /usr:/dev/dsk/c0t4d0s1:ufs \ -m /usr/opt:merged:ufs -n second_disk Example 9: Splitting a File System Assume a source BE with /, /usr, and /var all mounted on the same disk slice. The following command creates a BE second_disk that has /, /usr, and /var all mounted on dif- ferent disk slices. # lucreate -m /:/dev/dsk/c0t4d0s0:ufs -m /usr:/dev/dsk/c0t4d0s1:ufs \ /var:/dev/dsk/c0t4d0s3:ufs -n second_disk This separation of a file system's (such as root's) com- ponents onto different disk slices is referred to as split- ting a file system. Example 10: Specifying Alternative Slices The following command uses multiple -m options as alterna- tive disk slices for the new BE second_disk. # lucreate -m /:/dev/dsk/c0t4d0s0:ufs -m /:/dev/dsk/c0t4d0s1:ufs \ -m /:/dev/dsk/c0t4d0s5:ufs -n second_disk many lines of output lucreate: Creation of Boot Environment <second_disk> successful. The preceding command specifies three possible disk slices, s0, s1, and s5 for the / file system. lucreate selects the first one of these slices that is not being used by another BE. Note that the -s option is omitted, meaning that the current BE is the source BE for the creation of the new BE.


The following exit values are returned: 0 Successful completion. >0 An error occurred.


/etc/lutab list of BEs on the system


See attributes(5) for descriptions of the following attri- butes: SunOS 5.8 Last change: 22 Oct 2001 8 Maintenance Commands lucreate(1M) ____________________________________________________________ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | |_____________________________|_____________________________| | Availability | SUNWluu | |_____________________________|_____________________________|


lu(1M), luactivate(1M), lucancel(1M), lucompare(1M), lucurr(1M), ludelete(1M), lufslist(1M), lumake(1M), lumount(1M), lurename(1M), lustatus(1M), luupgrade(1M), lutab(4), attributes(5), live_upgrade(5)


When splitting a directory into multiple mount points, hard links are not maintained across file systems. For example, if /usr/test1/buglist is hard linked to /usr/test2/buglist, and /usr/test1 and /usr/test2 are split into separate file systems, the link between the files will no longer exist. lucreate issues a warning message to that effect and a sym- bolic link is created to replace the lost hard link. lucreate cannot prevent you from making invalid configura- tions with respect to non-shareable file systems. For exam- ple, you could enter an lucreate command that would create separate file systems for / and /kernel-an invalid division of /. When creating file systems for a boot environment, the rules are identical to the rules for creating file systems for the Solaris operating environment. SunOS 5.8 Last change: 22 Oct 2001 9