Sun Microsystems, Inc.
spacer | | |  
black dot
A   B   C   D   E   F   G   H   I   J   K   L   M   N   O   P   Q   R   S   T   U   V   W   X   Y   Z
System Administration Commandslucreate(1M)


 lucreate - create a new boot environment


 /usr/sbin/lucreate [-A BE_description] [-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...] ] ] [-X]



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:

  • Create a new boot environment (BE), based on the current BE.
  • Create a new BE, based on a BE other than the current BE.
  • 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 different disk slices.
  • 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 omit the -m and -M options (described below), which automatically invokes an FMLI-based interface that provides 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-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 systems that contain the OS are referred to as non-shareable (or critical) file systems; other file systems are referred to as shareable. 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 allows you to assign a description to a BE. A description is an optional attribute of a BE that can be of any format or length. It might be, for example, a text string or binary data. After you create a BE, you can change a BE description with the ludesc(1M) utility.

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; it cannot contain whitespace 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.

-A BE_description
Assigns the BE_description to a BE. BE_description can be a text string or other characters that can be entered on a Unix command line. See ludesc(1M) for additional information on BE descriptions.
-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 from which the source BE is booted. Without this option, lucreate attempts to determine the physical device from which a BE boots. If the device on which the root file system is located is not a physical disk (for example, if root is on a metadevice) and lucreate is able to make a reasonable guess as to the physical device, you receive the query:

Is the physical device devname the boot device for 
the logical device devname?

If you respond y, the command proceeds.

If you specify -C boot_device, lucreate skips the search for a physical device and uses the device you specify. The - (hyphen) with the -C option tells lucreate to proceed with whatever it determines is the boot device. If the command cannot find the device, you are prompted to enter it.

If you omit -C or specify -C boot_device and lucreate cannot find a 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 response to a subsequent query.

-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:

  • The name of a disk slice, of the form /dev/dsk/cnumtnumdnumsnum. Except for the mount point / (root), lucreate supports the names of metadevices in the device field. Root must be mounted on a physical device.
  • 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 arguments. 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 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 combine -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) to populate the BE or luupgrade(1M) to install a flash archive on the BE. This option is especially useful for installing a flash archive. See flar(1M).
Enable XML output. Characteristics of XML are defined in DTD, in /usr/share/lib/xml/dtd/lu_cli.dtd.<num>, where <num> is the version number of the DTD file.



The lucreate command produces copious output. In the following 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 environment 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.
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:

# 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 specifies 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:


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 specified on the command line before you enter the lucreate 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 following 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:


The following command creates a BE second_disk and performs the merge operation, merging /usr/opt with its parent, /usr.

# 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 different 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) components onto different disk slices is referred to as splitting a file system.

Example 10. Specifying Alternative Slices

The following command uses multiple -m options as alternative 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:

Successful completion.
An error occurred.


list of BEs on the system
Live Upgrade DTD (see -X option)



See attributes(5) for descriptions of the following attributes:




lu(1M), luactivate(1M), lucancel(1M), lucompare(1M), lucurr(1M), ludelete(1M), ludesc(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 symbolic link is created to replace the lost hard link.

lucreate cannot prevent you from making invalid configurations with respect to non-shareable file systems. For example, you could enter an lucreate command that would create separate file systems for / and /kernel--an invalid division of /. The resulting BE would be unbootable. When creating file systems for a boot environment, the rules are identical to the rules for creating file systems for the Solaris operating environment.

Mindful of the principle described in the preceding paragraph, consider the following:

  • In a source BE, you must have valid vfstab entries for every file system you want to copy to or share with a new BE.
  • You cannot create a new BE on a disk with overlapping partitions. The lucreate command that specifies such a disk might complete, but the resulting BE would be unbootable.

SunOS 5.9Go To TopLast Changed 24 Jan 2002

Copyright 2002 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms.