luupgrade(1M)
NAME
luupgrade - installs, upgrades, and performs other functions
on software 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 Run an installer program to install software from an
installation medium (-i option).
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
either the lucreate(1M) command or lu(1M), the FMLI-based
user interface. 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 opera-
tion, 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 different marketing release of the Solaris operating
system from the release running on the machine from which
you invoke luupgrade. This feature has the following condi-
tions:
o You can install Live Upgrade packages (SUNWluu and
SUNWlur) 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 ver-
sion 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 operating
system.
See the Solaris Installation Guide for instructions on ins-
talling Live Upgrade packages.
The luupgrade command requires root privileges.
Options that Apply to All Uses
The following options are available for all uses of luup-
grade:
-l error_log
Error and status messages are sent to error_log, in
addition to where they are sent in your current
environment.
-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 -s os_image_path [ -j profile_path [-D] ]
[ -l error_log ] [ -o outfile ] [-N]
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.
-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
CD-ROM or can be an NFS or UFS directory.
-j profile_path
Path to a JumpStart profile. See the section
"JumpStart Profile Keywords," below, for a list of
valid keywords for use in a profile invoked by luup-
grade. See pfinstall(1M) and the Solaris installation
documentation for information on the JumpStart
software.
-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 creates log files,
specified in its output, which allow you to examine
the command's results.
Before upgrading a boot environment, run analyze_patches,
available in the /Misc directory on the Solaris installation
CD, to determine which patches would be removed as a result
of the upgrade. Then, following the upgrade, you can rein-
stall the list of patches provided by analyze_patches.
Note that if you are upgrading from a medium with multiple
components, such as from multiple CDs, use luupgrade with
the -i option, as described in the section below, to install
software from the second and any following media.
Running an Installer Program
The luupgrade command uses -i to run an installer program.
The syntax is as follows:
luupgrade -i -n BE_name -s installation_medium [ -N ]
[ -O "installer_options" ] [ -l error_log ] [ -o outfile ]
The first option, -i, indicates the function to perform-to
run an installer program on the installation 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 installer pro-
gram. See installer(1M) for descriptions of the
installer options.
-s installation_medium
Path name of an installation medium. This can be a CD,
or an NFS or UFS directory.
With the -i option, luupgrade looks for an installation pro-
gram on the specified medium and runs that program.
The -i option has a special use when you use the -u option,
described above, to install software from a multiple-
component medium, such as multiple CDs. See EXAMPLES.
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 -s os_image_path ( -a archive | -j profile_path
| -J "profile" ) [ -l error_log ] [ -o outfile ] [-D] [ -N ]
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.
-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 CD-ROM, or can be an NFS or UFS directory.
-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 documenta-
tion 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 documentation for infor-
mation on the JumpStart software. You must specify one
of -a, -j, or -J.
-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.
Note that the version of the OS image specified with -s must
be identical to the version of the OS contained in the
Solaris Flash archive specified with the -a, -j, or -J
options.
Add or Remove Packages
The luupgrade command uses -p to add a package and -P to
remove a package. The syntax is as follows:
For adding packages:
luupgrade -p -n BE_name -s packages_path [ -l error_log ][ -o outfile ]
[ -O "pkgadd_options" ] [ -a admin ] [ pkginst [ pkginst...]] [ -N ]
For removing packages:
luupgrade -P -n BE_name [ -l error_log ][ -o outfile ]
[ -O "pkgrm_options" ] [ pkginst [ pkginst...]] [ -N ]
The first option, -p, to add packages, or -P to remove pack-
ages, 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 to which packages will be added or from
which packages 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 descrip-
tions 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 com-
pliant with the SVR4 Advanced Packaging Guidelines. See
WARNINGS, below.
Add or Remove 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 -s patch_path [ -l error_log ][ -o outfile ]
[ -O "patchadd_options" ] [ patch_name [ patch_name...]] [ -N ]
For removing patches:
luupgrade -T -n BE_name [ -l error_log ][ -o outfile ]
[ -O "patchrm_options" ] [ patch_name [ patch_name...]] [ -N ]
The first option, -t, to add patches, or -T to remove
patches, 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 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.
-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 com-
pliant with the SVR4 Advanced Packaging Guidelines. See
WARNINGS, below.
Check or Return 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 ]
[ -O "pkgchk_options" ][ pkginst [ pkginst...]] [ -N ]
For performing a pkginfo:
luupgrade -I -n BE_name [ -l error_log ][ -o outfile ]
[ -O "pkginfo_options" ][ pkginst [ pkginst...]] [ -N ]
The first option, -C, for pkgchk, or -I, for pkginfo, indi-
cates the function to perform. The remaining options for
this use of luupgrade, shown above, are described as fol-
lows:
-n BE_name
Name of the BE on which packages will be checked or on
whose packages information will be returned. " .nr )I
pkgchk_options"n
-O Options passed directly to pkgchk (for -C) or pkginfo
(for -I). See pkgchk(1M) or pkginfo(1) for a descrip-
tion of these options.
pkginst [ pkginst... ]
Zero or more packages to check or for which to have
information returned. If you omit package names, luup-
grade returns information on all of the packages on
the BE. Separate multiple package names with spaces.
Check an OS Installation Medium
With the -c option, luupgrade allows you to check that a
local or remote medium, such as a CD, is a valid installa-
tion medium. The -c option returns useful information about
the specified medium. The syntax for this use of luupgrade
is as follows:
luupgrade -c -s path_to_medium [ -l error_log ] [ -o outfile ]
The first option, -c, indicates the function to perform-to
check on an installation medium. The -s option, shown above,
is described as follows:
-s path_to_medium
Path name to an installation medium such as a CD-ROM.
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 differential flash
archive. Also for the -f option with the -j option, you must
specify the -a (archive location) option or specify the
archive_location 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 pro-
files 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
system.
The following keywords must not be used in a profile used
with luupgrade:
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 pack-
ages 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 activate 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, replace the s0 in the argument to -s with
s2.
When the installer is finished with the contents of the
first CD, insert the next CD in the drive and enter the fol-
lowing:
# luupgrade -i -n second_disk -s /cdrom/cdrom0 \
-O "-nodisplay -noconsole"
Note the use of -i rather than -u in the preceding. Were
there additional 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 complete 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 actu-
ally performing the flash installation.
# 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 dif-
ferential 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
and SUNWlur, passing to pkgchk the -v option.
# luupgrade -C -n second_disk -O "-v" SUNWluu SUNWlur
The following command runs pkginfo on the same set of pack-
ages:
# luupgrade -I -n second_disk -O "-v" SUNWluu SUNWlur
For both commands, if the package names were omitted, luup-
grade 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 attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWluu |
|_____________________________|_____________________________|
SEE ALSO
installer(1M), lu(1M), luactivate(1M), lucancel(1M),
lucompare(1M), lucreate(1M), lucurr(1M), ludelete(1M),
ludesc(1M), lufslist(1M), lumake(1M), lumount(1M),
lurename(1M), lustatus(1M), lutab(4), attributes(5),
live_upgrade(5)
WARNINGS
For adding packages or patches (-p, -P, -t, or -T), luup-
grade requires packages or patches that comply with the SVR4
Advanced Packaging Guidelines and the guidelines spelled out
in Appendix C of the Solaris 9 9/04 Installation Guide. 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
Live Upgrade supports the release it is distributed on and
up to three marketing releases back. For example, if you
obtained Live Upgrade with Solaris 9 (including a Solaris 9
upgrade), that version of Live Upgrade supports Solaris ver-
sions 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.
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 con-
sulting http://sunsolve.sun.com. Search for the infodoc
72099 on the SunSolve web site.
Man(1) output converted with
man2html