luupgrade(1M)                                                                                                                        luupgrade(1M)

NAME

       luupgrade - installs, upgrades, and performs other functions on software on a boot environment

SYNOPSIS

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

         o  Upgrades an operating system image on a BE (-u option). The source for the image can be any valid Solaris installation medium, includ-
            ing 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 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 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:

         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 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 exam-
            ple, 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 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 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 DVD or CD, 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 luupgrade. 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, do the following:

         o  Run analyze_patches.

         o  Install Live Upgrade packages for the operating system version 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
       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 and SUNWlur, 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 -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 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 installer 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 . 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 -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 DVD or CD, 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 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  ar-
           chive_location.  See pfinstall(1M) and the Solaris installation documentation for information on the JumpStart software. You must spec-
           ify 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 exam-
           ine 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 packages, 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 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.

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

   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, 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 packages 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.

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

       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.

       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  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 inser-
       tion 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. Fol-
       lowing 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 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 packages:

       # luupgrade -I -n second_disk -O "-v" SUNWluu SUNWlur

       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:

       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 in "Options that Apply to All Uses," above)

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

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE         |      ATTRIBUTE VALUE        |
       +-----------------------------+-----------------------------+
       |Availability                 |SUNWluu                      |
       +-----------------------------+-----------------------------+

       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), 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  guide-
       lines,  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.

       The Live Upgrade feature does not support the upgrade of a system running the current Solaris release that has installed non-global  zones.
       (See zones(5).) See  for further details.

                                                                    5 Oct 2005                                                       luupgrade(1M)