/usr/sbin/luupgrade [-iIufpPtTcC] [options]
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:
Before using luupgrade, you must have created a BE, using the lucreate(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 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 conditions:
See the Solaris Installation Guide for instructions on installing Live Upgrade packages.
The luupgrade command requires root privileges.
The following options are available for all uses of luupgrade:
The luupgrade command uses -u to upgrade an operating system image. The syntax is as follows:
luupgrade -u -n BE_name [ -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:
Before upgrading a boot environment, do the following:
The analyze_patches command is available in the /Misc directory on the Solaris software DVD (formerly the Solaris installation CD). This command 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.
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 installer program on the installation medium specified with -s. The remaining options for this use of luupgrade, shown above, are described as follows:
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.
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:
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.
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 [ -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, indicates the function to perform. The remaining options for this use of luupgrade, shown above, are described as follows:
-O "pkgadd_options" or "pkgrm_options"
pkginst [ pkginst... ]
It is critically important that any packages you add be compliant with the SVR4 Advanced Packaging Guidelines. See WARNINGS, below.
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, indicates the function to perform. The remaining options for this use of luupgrade, shown above, are described as follows:
-O "patchadd_options" or "patchrm_options"
patch_name [ patch_name... ]
It is critically important that any patches you add be compliant with the SVR4 Advanced Packaging Guidelines. See WARNINGS, below.
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:
-O "pkgchk_options" or "pkginfo_options"
pkginst [ pkginst... ]
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 follows:
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 profiles used with the -u and -f options:
The following keywords must not be used in a profile used with luupgrade:
See the Solaris Installation Guide for descriptions of all JumpStart profile keywords and instructions for creating a JumpStart profile.
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 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 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 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 actually 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 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.
The following exit values are returned:
See attributes(5) for descriptions of the following attributes:
installer(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), zones(5)
For adding packages or patches (-p, -P, -t, or -T), luupgrade requires packages or patches that comply with the SVR4 Advanced Packaging Guidelines 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.
For versions of the Solaris operating system prior to Solaris 10, 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 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 supports 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.