luupgrade(1M) System Administration Commands luupgrade(1M)NAMEluupgrade - installs, upgrades, and performs other functions on soft‐
ware on a boot environment
SYNOPSIS
/usr/sbin/luupgrade [-iIufpPtTcC] [options]
DESCRIPTION
The luupgrade 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.
The luupgrade command enables you to install software on a specified
boot environment (BE). Specifically, luupgrade performs the following
functions:
o Upgrades an operating system image on a BE (-u option). The
source for the image can be any valid Solaris installation
medium, including a Solaris Flash archive.
o Extract a Solaris Flash archive onto a BE (-f option). (See
flar(1M).)
o Add a package to (-p) or remove a package from (-P) a BE.
o Add a patch to (-t) or remove a patch from (-T) a BE.
o Check (-C) or obtain information about (-I) packages.
o Check an operating system installation medium (-c).
Before using luupgrade, you must have created a BE, using the lucre‐
ate(1M) command. You can upgrade only BEs other than the current BE.
The functions described in the preceding list each has its own set of
options, which are described separately for each function.
Note that, for successful completion of an luupgrade operation, the
status of a BE must be complete, as reported by lustatus(1M). Also, the
BE must not have any mounted disk slices, mounted either with
lumount(1M) or mount(1M).
luupgrade allows you to install an operating system image from a dif‐
ferent marketing release of the Solaris operating system from the
release running on the machine from which you invoke luupgrade. This
feature has the following conditions:
o You can install Live Upgrade packages (SUNWluu, SUNWlur, and
SUNWlucfg) from a given release of the Solaris operating
system on a machine running a previous release. You can
install these packages on a machine running a version of
Solaris that is up to three releases prior to the release of
the Live Upgrade packages. Live Upgrade is not supported on
Solaris releases prior to Solaris 2.6. Thus, you can, for
example, install Solaris 2.9 packages on Solaris 2.8, 2.7,
and 2.6 machines.
o You can upgrade to a release of the Solaris operating system
that is the same as the release of the Live Upgrade packages
installed on a machine. This feature allows you to upgrade
to Solaris upgrade releases within a marketing release. For
example, if have the Solaris 9 FCS Live Upgrade packages
installed on a machine, you can use luupgrade to upgrade a
BE to the Solaris 9 update 3 release of the Solaris operat‐
ing system.
See the Solaris Installation Guide for instructions on installing Live
Upgrade packages.
The luupgrade command requires root privileges.
Options that Apply to All Uses
The following options are available for all uses of luupgrade:
-l error_log Error and status messages are sent to error_log, in
addition to where they are sent in your current envi‐
ronment.
-o outfile All command output is sent to outfile, in addition to
where it is sent in your current environment.
-N Dry-run mode. Enables you to determine whether your
command arguments are correctly formed. Does not apply
to the -c (check medium) function.
-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.
Upgrading an Operating System Image
The luupgrade command uses -u to upgrade an operating system image. The
syntax is as follows:
luupgrade-u -n BE_name -k autoreg_file [ -l error_log ]
[ -o outfile ][-N] -s os_image_path [ -j profile_path [-D] ]
The first option, -u, indicates the function to perform—to install an
OS image. The remaining options for this use of luupgrade, shown above,
are described as follows:
-n BE_name Name of the BE to receive an OS upgrade.
-k autoreg_file Path to auto-registration information file. See
sysidcfg(4) for a list of valid keywords for use in
this file.
-s os_image_path Path name of a directory containing an OS image.
This can be a directory on an installation medium
such as a DVD or CD, or can be an NFS or UFS direc‐
tory.
-j profile_path Path to a JumpStart profile. See the section "Jump‐
Start Profile Keywords," below, for a list of valid
keywords for use in a profile invoked by luupgrade.
See pfinstall(1M) and the Solaris installation doc‐
umentation for information on the JumpStart soft‐
ware.
-D Tests the profile values provided with -j against
the disk configuration of the specified BE. The
upgrade is not performed. The effect of this option
is a dry run to test your profile. luupgrade cre‐
ates log files, specified in its output, which
allow you to examine the command's results.
Before upgrading a boot environment, do the following:
o Run analyze_patches.
o Install Live Upgrade packages for the operating system ver‐
sion to which you are upgrading.
The analyze_patches command is available in the /Misc directory on the
Solaris software DVD (formerly the Solaris installation CD). This com‐
mand determines which patches would be removed as a result of the
upgrade. Then, following the upgrade, you can reinstall the list of
patches provided by analyze_patches.
The Live Upgrade packages, SUNWluu, SUNWlur, and SUNWlucfg, are
available on the Solaris software DVD (or CD, depending on the Solaris
version). Before running luupgrade with the -u option, ensure that you
have installed the packages from the version of Solaris to which you
want to upgrade.
Note that if you are upgrading from a medium with multiple components,
such as from multiple DVDs, use luupgrade with the -i option, as
described in the section below, to install software from the second and
any following media.
Continuing an Upgrade by Running an Installer Program
The luupgrade command uses -i to run an installer program. As discussed
below, its primary use is following an invocation of luupgrade with the
-u option. The syntax for -i is as follows:
luupgrade-i -n BE_name [ -l error_log ] [ -o outfile ] [ -N ]
-s installation_medium [ -O "installer_options" ]
The first option, -i, indicates the function to perform—to run an in‐
staller program on the installation medium specified with -s. The
remaining options for this use of luupgrade, shown above, are described
as follows:
-n BE_name Name of the BE on which software is to be
installed.
-O "installer_options" Options passed directly to the Solaris in‐
staller program. See installer(1M) for
descriptions of the installer options.
-s installation_medium Path name of an installation medium. This can
be a DVD, CD, or an NFS or UFS directory.
With the -i option, luupgrade looks for an installation program on the
specified medium and runs that program.
The primary use of the -i option is to upgrade an operating system
image from a multiple-component medium, such as multiple DVDs. In this
use, an luupgrade command with the -i option follows an invocation of
luupgrade with -u. See EXAMPLES. The -u option is described above.
Installing from a Solaris Flash Archive
The luupgrade command uses -f to install an operating system from a
Solaris Flash archive. Note that installing an archive overwrites all
files on the target BE. The syntax is as follows:
luupgrade-f -n BE_name [ -l error_log ] [ -o outfile ] [ -N ] [-D]
-s os_image_path ( -a archive | -j profile_path | -J "profile" )
The first option, -f, indicates the function to perform—to install an
OS from a Solaris Flash archive. The remaining options for this use of
luupgrade, shown above, are described as follows:
-n BE_name Name of the BE to receive an OS installation.
-D Tests the profile values provided with -j or -J
against the disk configuration of the specified BE.
The upgrade is not performed. The effect of this
option is a dry run to test your profile. luupgrade
creates log files, specified in its output, which
allow you to examine the command's results.
-s os_image_path Path name of a directory containing an OS image.
This can be a directory on an installation medium,
such as a DVD or CD, or can be an NFS or UFS direc‐
tory.
-a archive Path to the Solaris Flash archive when the archive
is available on the local file system. You must
specify one of -a, -j, or -J.
-j profile_path Path to a JumpStart profile that is configured for
a Solaris Flash installation. See the section
"JumpStart Profile Keywords," below, for a list of
valid keywords for use in a profile invoked by
luupgrade. See pfinstall(1M) and the Solaris
installation documentation for information on the
JumpStart software. You must specify one of -a, -j,
or -J.
-J "profile" Entry from a JumpStart profile that is configured
for a Solaris Flash installation. The only valid
keyword for this option is archive_location. See
pfinstall(1M) and the Solaris installation documen‐
tation for information on the JumpStart software.
You must specify one of -a, -j, or -J.
Note that the version of the OS image specified with -s must be identi‐
cal to the version of the OS contained in the Solaris Flash archive
specified with the -a, -j, or -J options.
Adding or Removing Packages
The luupgrade command uses -p to add a package and -P to remove a pack‐
age. The syntax is as follows:
For adding packages:
luupgrade-p -n BE_name [ -l error_log ][ -o outfile ] [ -N ]
-s packages_path [ -O "pkgadd_options" ] [ -a admin ]
[ pkginst [ pkginst...]]
For removing packages:
luupgrade-P -n BE_name [ -l error_log ][ -o outfile ] [ -N ]
[ -O "pkgrm_options" ] [ pkginst [ pkginst...]]
The first option, -p, to add packages, or -P to remove packages, indi‐
cates the function to perform. The remaining options for this use of
luupgrade, shown above, are described as follows:
-n BE_name
Name of the BE to which packages will be added or from which pack‐
ages will be removed.
-s packages_path
(For adding packages only.) Path name of a directory containing
packages to add. You can substitute -d for -s. The -d support is
for pkgadd(1M) compatibility.
-d packages_path
Identical to -s. Use of -s is recommended.
-O "pkgadd_options" or "pkgrm_options"
Options passed directly to pkgadd (for -p) or pkgrm (for -P). See
pkgadd(1M) and pkgrm(1M) for descriptions of the options for those
commands.
-a admin
(For adding packages only.) Path to an admin file. Identical to the
pkgadd -a option. Use of the -a option here is identical to -O "-a
admin"
pkginst [ pkginst... ]
Zero or more packages to add or remove. For adding packages, the
default is to add all of the packages specified with the -s option,
above. Separate multiple package names with spaces.
It is critically important that any packages you add be compliant with
the SVR4 Advanced Packaging Guidelines. See WARNINGS, below.
Adding or Removing Patches
The luupgrade command uses -t to add a patch and -T to remove a patch.
The syntax is as follows:
For adding patches:
luupgrade-t -n BE_name [ -l error_log ][ -o outfile ] [ -N ]
-s patch_path [ -O "patchadd_options" ] [ patch_name [ patch_name...]]
For removing patches:
luupgrade-T -n BE_name [ -l error_log ][ -o outfile ] [ -N ]
[ -O "patchrm_options" ] [ patch_name [ patch_name...]]
The first option, -t, to add patches, or -T to remove patches, indi‐
cates the function to perform. The remaining options for this use of
luupgrade, shown above, are described as follows:
-n BE_name
Name of the BE to which patches will be added or from which patches
will be removed.
-s patch_path
(For adding patches only.) Path name of a directory containing
patches to add or path name of a patch_order file.
-O "patchadd_options" or "patchrm_options"
Options passed directly to patchadd (for -p) or patchrm (for -P).
See patchadd(1M) or patchrm(1M) for a description of these options.
patch_name [ patch_name... ]
Zero or more patches to add or remove. For adding patches, the
default is to add all of the patches specified with the -s option,
above. Separate multiple patch names with spaces.
It is critically important that any patches you add be compliant with
the SVR4 Advanced Packaging Guidelines. See WARNINGS, below.
Checking or Returning Information on Packages
Use the -C to perform a pkgchk(1M) on all or the specified packages on
a BE. Use the -I option to perform a pkginfo(1).
For performing a pkgchk:
luupgrade-C -n BE_name [ -l error_log ][ -o outfile ] [ -N ]
[ -O "pkgchk_options" ][ pkginst [ pkginst...]]
For performing a pkginfo:
luupgrade-I -n BE_name [ -l error_log ][ -o outfile ] [ -N ]
[ -O "pkginfo_options" ][ pkginst [ pkginst...]]
The first option, -C, for pkgchk, or -I, for pkginfo, indicates the
function to perform. The remaining options for this use of luupgrade,
shown above, are described as follows:
-n BE_name
Name of the BE on which packages will be checked or on whose pack‐
ages information will be returned.
-O "pkgchk_options" or "pkginfo_options"
Options passed directly to pkgchk (for -C) or pkginfo (for -I). See
pkgchk(1M) or pkginfo(1) for a description of these options.
pkginst [ pkginst... ]
Zero or more packages to check or for which to have information
returned. If you omit package names, luupgrade returns information
on all of the packages on the BE. Separate multiple package names
with spaces.
Checking an OS Installation Medium
With the -c option, luupgrade allows you to check that a local or
remote medium, such as a DVD or CD, is a valid installation medium. The
-c option returns useful information about the specified medium. The
syntax for this use of luupgrade is as follows:
luupgrade-c [ -l error_log ] [ -o outfile ] -s path_to_medium
The first option, -c, indicates the function to perform—to check on an
installation medium. The -s option, shown above, is described as fol‐
lows:
-s path_to_medium Path name to an installation medium such as a DVD
or CD.
JumpStart Profile Keywords
This section specifies the Solaris JumpStart keywords that can be used
in a profile with luupgrade, using the -j option in conjunction with
the -u (upgrade) or -f (flash) options. For -u, there are no required
keywords. For -f, you must specify a value for install_type:
flash_install for a full flash archive or flash_update for a differen‐
tial flash archive. Also for the -f option with the -j option, you must
specify the -a (archive location) option or specify the archive_loca‐
tion keyword in your profile.
The archive_location keyword is the only valid argument for the -J
option.
The following optional keywords are sometimes used in profiles used
with the -u and -f options:
cluster Designates the software group to add to the system.
geo Designates the regional locale or locales that you want to
install on or add to a system. See the Solaris Installation
Guide for a list of possible values.
isa_bits Specifies whether 64-bit or 32-bit packages are to be
installed. Valid values are 64 and 32.
locale Designates the locale packages you want to install on or
add to a system. See the Solaris Installation Guide for a
list of possible values.
package Specifies a package to be added to or deleted from a sys‐
tem.
The following keywords must not be used in a profile used with luup‐
grade:
o boot_device
o dontuse
o fdisk
o filesys
o layout_constraint
o noreboot
o partitioning
o root_device
o usedisk
See the Solaris Installation Guide for descriptions of all JumpStart
profile keywords and instructions for creating a JumpStart profile.
EXAMPLES
Example 1 Removing, then Adding Packages
The following example removes from then adds a set of packages to a
boot environment.
# luupgrade-P -n second_disk SUNWabc SUNWdef SUNWghi
Now, to add the same packages:
# luupgrade-p -n second_disk -s /net/installmachine/export/packages \
SUNWabc SUNWdef SUNWghi
The following command adds the -O option to the preceding command. This
option passes arguments directly to pkgadd.
# luupgrade-p -n second_disk -s /net/installmachine/export/packages \
-O "-r /net/testmachine/export/responses" SUNWabc SUNWdef SUNWghi
See pkgadd(1M) for a description of the options for that command.
Example 2 Upgrading to a New OS from a Combined Image
The following example upgrades the operating environment on a boot
environment. The source image is stored as a combined image on a remote
disk or on a DVD.
# luupgrade-u -n second_disk \
-s /net/installmachine/export/solarisX/OS_image
Following the command above you could enter the command below to acti‐
vate the upgraded BE.
# luactivate second_disk
Then, upon the next reboot, second_disk would become the current boot
environment. See luactivate(1M).
Example 3 Upgrading to a New OS from Multiple CDs
The following example is a variation on the preceding. The OS upgrade
resides on two CDs. To begin the upgrade on a SPARC machine, you enter:
# luupgrade-u -n second_disk -s /cdrom/cdrom0/s0
On x86 machines, omit the s0 in the argument to -s, entering: -s
/cdrom/cdrom0.
When the installer is finished with the contents of the first CD,
insert the next CD in the drive and enter the following:
# luupgrade-i -n second_disk -s /cdrom/cdrom0 \
-O "-nodisplay -noconsole"
Note the use of -i rather than -u in the preceding. Were there addi‐
tional CDs, you would enter the same command as the one immediately
above. The -O options, above, are passed to installer(1M). If you omit
these options, a graphical interface is invoked following the insertion
and reading of the second CD. See installer(1M) for a description of
the -O options.
Note that a multiple-CD upgrade is not complete until you have entered
and completed luupgrade commands for all of the CDs in a set. Following
installation of packages from a CD, you might receive a message such
as:
WARNING: <num> packages must be installed on boot environment <disk_device>.
Such a message indicates the requirement that you install packages from
one or more additional CDs, as in the example above. If you do not com‐
plete package installation, you will not be able to use luactivate to
activate (designate for booting) the upgraded BE.
Example 4 Upgrading Using a JumpStart Profile
The following example command uses the -D option to test the profile
/home2/profiles/test.profile.
# luupgrade-u -n second_disk \
-s /net/installmachine/export/solarisX/OS_image \
-j /home2/profiles/test.profile -D
Assuming the results of this command were acceptable, you could omit
the -D in the preceding command to perform the upgrade.
Example 5 Installing a New OS from a Solaris Flash Archive
The following example installs the operating environment on a boot
environment, using a Solaris Flash archive. The file pointed to by -J
is a JumpStart profile that specifies a flash installation.
# luupgrade-f -n second_disk \
-s /net/installmachine/export/solarisX/OS_image \
-J "archive_location http://example.com/myflash.flar"
The following command differs from the preceding only in that -j
replaces -J. You could append the -D option to either of these commands
to test the profile prior to actually performing the flash installa‐
tion.
# luupgrade-f -n second_disk \
-s /net/installmachine/export/solarisX/OS_image \
-j /net/example/flash_archives/flash_gordon
Either of the preceding commands works for a full or differential flash
installation. Whether a flash installation is differential or full is
determined by the value of the install_type keyword in the profile. See
"JumpStart Profile Keywords," above.
Example 6 Obtaining Information on Packages
The following example runs a pkgchk on the packages SUNWluu, SUNWlur,
and SUNWlucfg, passing to pkgchk the -v option.
# luupgrade-C -n second_disk -O "-v" SUNWluu SUNWlur SUNWlucfg
The following command runs pkginfo on the same set of packages:
# luupgrade-I -n second_disk -O "-v" SUNWluu SUNWlur SUNWlucfg
For both commands, if the package names were omitted, luupgrade returns
package information on all of the packages in the specified BE. See
pkgchk(1M) and pkginfo(1) for a description of the options for those
commands.
EXIT STATUS
The following exit values are returned:
0 Successful completion.
>0 An error occurred.
FILES
/etc/lutab
list of BEs on the system
/usr/share/lib/xml/dtd/lu_cli.dtd.<num>
Live Upgrade DTD (see -X option in "Options that Apply to All
Uses," above)
ATTRIBUTES
See attributes(5) for descriptions of the following attributes:
┌─────────────────────────────┬─────────────────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├─────────────────────────────┼─────────────────────────────┤
│Availability │SUNWluu │
└─────────────────────────────┴─────────────────────────────┘
SEE ALSOinstaller(1M), luactivate(1M), lucancel(1M), lucompare(1M), lucre‐
ate(1M), lucurr(1M), ludelete(1M), ludesc(1M), lufslist(1M),
lumake(1M), lumount(1M), lurename(1M), lustatus(1M), lutab(4), sysid‐
cfg(4), attributes(5), live_upgrade(5), zones(5)WARNINGS
For adding packages or patches (-p, -P, -t, or -T), luupgrade requires
packages or patches that comply with the SVR4 Advanced Packaging Guide‐
lines and the guidelines spelled out in Appendix C of the . This means
that the package or patch is compliant with the pkgadd(1M) or
patchadd(1M)-R option, described in the man pages for those utilities.
While nearly all Sun packages and patches conform to these guidelines,
Sun cannot guarantee the conformance of packages and patches from
third-party vendors. Some older Sun packages and patches might not be
-R compliant. If you encounter such a package or patch, please report
it to Sun. A non-conformant package can cause the package- or patch-
addition software in luupgrade to fail or, worse, alter the current BE.
NOTES
For versions of the Solaris operating system prior to Solaris 10, Live
Upgrade supports the release it is distributed on and up to three mar‐
keting releases back. For example, if you obtained Live Upgrade with
Solaris 9 (including a Solaris 9 upgrade), that version of Live Upgrade
supports Solaris versions 2.6, Solaris 7, and Solaris 8, in addition to
Solaris 9. No version of Live Upgrade supports a Solaris version prior
to Solaris 2.6.
Starting with version 10 of the Solaris operating system, Live Upgrade
supports the release it is distributed on and up to two marketing
releases back. For example, if you obtained Live Upgrade with Solaris
10 (including a Solaris 10 upgrade), that version of Live Upgrade sup‐
ports Solaris 8 and Solaris 9, in addition to Solaris 10.
Correct operation of Solaris Live Upgrade requires that a limited set
of patch revisions be installed for a given OS version. Before
installing or running Live Upgrade, you are required to install the
limited set of patch revisions. Make sure you have the most recently
updated patch list by consulting http://sunsolve.sun.com. Search for
the infodoc 72099 on the SunSolve web site.
SunOS 5.10 12 Dec 2011 luupgrade(1M)
