Unix‎ > ‎Solaris‎ > ‎Solaris man pages‎ > ‎1m‎ > ‎

luupgrade


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

         o    Check an operating system installation medium (-c).


     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  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,
              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 operat-
              ing  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 [ -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.


     -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  ins-
                         tallation  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  per-
                         formed.  The  effect of this option is a
                         dry run to test your profile.  luupgrade
                         creates log files, specified in its out-
                         put, 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 direc-
     tory  on the Solaris software DVD (formerly the Solaris ins-
     tallation 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.

  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 invoca-
     tion 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 speci-
     fied with -s. The remaining options for this  use  of  luup-
     grade, 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 pro-
     gram 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 mul-
     tiple DVDs. In this use, an luupgrade command  with  the  -i
     option follows an invocation of luupgrade with -u. See EXAM-
     PLES. 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  instal-
                         lation.


     -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.  luup-
                         grade  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 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 con-
                         figured  for  a  Solaris Flash installa-
                         tion. 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 installa-
                         tion. The only valid  keyword  for  this
                         option    is    archive_location.    See
                         pfinstall(1M) and the Solaris  installa-
                         tion  documentation  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  identical  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 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 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 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 pack-
         ages,  the  default is to add all of the packages speci-
         fied with the -s option, above. Separate multiple  pack-
         age names with spaces.

     It is critically important that any packages you add be com-
     pliant  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,  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 con-
         taining  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 descrip-
         tion 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 speci-
         fied 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.

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


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


  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 ins-
     tallation medium. The -c option returns  useful  information
     about the specified medium. The syntax for this use of luup-
     grade 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:

     -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  pro-
     files used with the -u and -f options:

     cluster     Designates the software group to add to the sys-
                 tem.


     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,
     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  pack-
     ages:


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




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

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 . 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 distri-
     buted on and up to three marketing releases back. For  exam-
     ple,  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  con-
     sulting  http://sunsolve.sun.com.  Search  for  the  infodoc
     72099 on the SunSolve web site.










Man pages from Solaris 10 Update 8. See docs.sun.com and www.oracle.com for further documentation and Solaris information.
Comments