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).

-X

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.

The following exit values are returned:

0

Successful completion.

>0

An error occurred.

/etc/lutab

list of BEs on the system

/usr/share/lib/xml/dtd/lu_cli.dtd.<num>

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.