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

prodreg


NAME
     prodreg - Solaris Product Registry administration

SYNOPSIS
     prodreg  [--help] | [subcommand operand ...]

DESCRIPTION
     The prodreg utility  browses,  unregisters,  and  uninstalls
     components in the Solaris Product Registry.

     Some installers make use of the libwsreg(3LIB) interface  to
     register  information. The Solaris Product Registry contains
     information about this installed software.

     The database associated with the Solaris Product Registry is
     relative to the root of the installed file system. Normally,
     this is the root of  the  file  system  (/).  Sometimes,  an
     alternate  root,  with  a different Solaris Product Registry
     install database is used, as during live  upgrade  installa-
     tion. See live_upgrade(5).

     The Registry database  informs  installers  about  installed
     software.  The  Registry  and  the  prodreg  utility  do not
     directly perform  installation  or  deinstallation.  prodreg
     supports   installers  which  are  executed  externally  and
     launched by the prodreg utility or other means.

     Depending on the  subcommand,  the  prodreg  command  offers
     equivalent  functions from the command line or a GUI viewer.
     Two versions of the GUI viewer are available. The default is
     the  Java  Swing GUI. The other version, the Java awt GUI is
     provided for environments without Java Swing support.

     The only feature which  exists  in  the  CLI  which  is  not
     present  in the GUI is the unregister subcommand. It is pos-
     sible for the product registry to become corrupted,  if  for
     example,  some  software  is  removed manually instead of by
     means of an uninstaller program. These entries  can  confuse
     installers  which  are run subsequently. The unregister sub-
     command allows stale entries to be removed, even forcefully.
     Care  should  be  exercised when unregistering software with
     the recursive or force options so that valid entries in  the
     registry are not removed by mistake.

     The prodreg command, whether it launches the GUI or the com-
     mand  line  interface  browser, displays the contents of the
     registry at that time only.  If  software  is  installed  or
     uninstalled  subsequent  to  or  concurrent  with  launching
     either prodreg viewer, the view can be inconsistent with the
     Solaris Product Registry.


SUBCOMMANDS
     You can specify  options  to  the  prodreg  command  without
     specifying  a  subcommand. If the subcommand is omitted, the
     swing subcommand is assumed.

     The following subcommands are supported:

     awt

         Launch the Java awt GUI.

         The awt subcommand has the following format:

         awt [-R alt_root | --help]




     browse

         Display the Solaris Product  Registry  using  a  command
         line interface. The text output of this command displays
         identifying information of any component in the  product
         registry  tree, including its ancestors and children. If
         you repeatedly invoke this subcommand, you can  interac-
         tively browse the product registry.

         The database components are  related  as  a  tree.  Com-
         ponents  may  have  one or more children. Except for the
         root,  components  have  one  parent.  This   subcommand
         displays  the  ancestors  and  children for a given com-
         ponent in the Solaris Product Registry database.

         Each time the prodreg browse subcommand is executed, one
         component  in  the  Registry  is  shown,  along with its
         ancestry to the root of the Registry,  as  well  as  the
         component's  children.  To  browse in the prodreg GUI, a
         user selects a node to expand  and  clicks  on  it.  The
         analogous  activity  using the command line interface is
         to browse  on  children  of  nodes  successively,  which
         effectively expands a view into the registry.

         Start by browsing the root of the Registry with  prodreg
         browse.  Select  components  to  expand the scope of the
         browsing activity. Use browse numbers as  a  convenience
         during  this  interactive  browsing, but not in scripts.
         Browse numbers can change from one session to  the  next
         or  on different systems. This is because browse numbers
         are generated as they are first used, by a given user on
         a particular system.

         The browse subcommand has the following format:
         browse [-R alt_root] [-u uuid [-i instance | -p location]]
         browse [-R alt_root] -n bnum [-i instance | -p location]
         browse [-R alt_root] -m name
         browse --help

         This following information is output for each component:


         BROWSE #

             This is the browse number associated with each  com-
             ponent.  This  number  can be used as an argument to
             either the prodreg browse or info subcommands  as  a
             convenience




         +/-/.

             The + indicates a component in the tree  with  chil-
             dren who are not shown. - indicates a component with
             children of which at least one child is being shown.
             The  .  indicates a component which has no children.
             This field is arranged so that each  space  (reading
             left to right) depicts a successive generation.



         UUID

             This is the component's unique identifier.



         #

             This  is  the  instance  number  of  the  component.
             Software components can be installed multiple times.
             The software registry assigns a unique  instance  to
             each one.



         NAME

             Each component in the Solaris Product Registry data-
             base has a localized name which is displayed in this
             field. It is possible that  this  name  may  not  be
             unique  in the registry since there could be another
             component that has the same name.

         The browse subcommand provides four distinct options for
         viewing the registry database. If multiple instances are
         associated with the same component, then the  output  of
         the  subcommand  is the ambiguous list. The request must
         be made unambiguous. The instance or  location  operands
         can  be  used to disambiguate the browse subcommand when
         used with the -u or -n options.


           o  If no operand information is given, the root of the
              registry  tree  is  displayed, as well as its chil-
              dren. This is the starting  point  for  interactive
              browsing of the entire registry database.

           o  If the browse number is given, the component  asso-
              ciated is output.

           o  If the uuid is given, the component associated with
              it is output.

           o  If the name is given, the component associated with
              it is output.


     info

         Display attributes for any component in the Solaris Pro-
         duct  Registry  by supplying identifying information for
         the component.

         Components in the product registry are  associated  with
         attributes.  These attributes are composed of a name and
         a single value string.

         This subcommand outputs attribute information associated
         with components in the Solaris Product Registry. Indivi-
         dual components in the product registry are specified as
         for  the browse subcommand, except that either the uuid,
         name or bnum must be specified.

         If a component requested is ambiguous  as  it  has  more
         than  one  instance or the name is assigned to more than
         one component in the registry, the list of possibilities
         is output, not the attribute information.

         The default output of this subcommand is a complete list
         of  each  attributes,  each on a new line. The attribute
         name is followed by a  colon  (:)  and  a  <SPACE>.  The
         attribute  value  follows,  after  which  a  <RETURN> is
         appended. Other options include can be  specified  using
         -a and -d.

         The info subcommand has the following format:

         info --help
         info [-R alt_root] -u uuid [-i instance | -p location]
         info [-R alt_root] -n bnum [-i instance | -p location]
         info [-R alt_root] -m name [-a attr | -d ]




     help | --help | -?

         Display help text.

         The help subcommand has the following format:

         help | --help | -?




     swing

         Launch the Java Swing GUI. If the Java Swing GUI is  not
         available, this subcommand fails.

         The swing subcommand has the following format:

         swing  [-R alt_root | --help]




     version | --version | -V

         Outputs a current version string.

         The version subcommand has the following format:

         version | --version | -V




     unregister

         Unregister an entry in the registry.

         Remove a component from the  Solaris  Product  Registry.
         The  component  corresponding to the uuid specified with
         the -u option must be a single instance. If it  is  not,
         the  subcommand  fails and returns the list of instances
         with the associated uuid. The subcommand must  be  reis-
         sued  using  either -p or -i to uniquely determine which
         component instance to unregister.

         The unregister subcommand fails if there are  components
         in  the  registry which depend on the component which is
         to be unregistered.

         The unregister subcommand fails if  the  user  does  not
         have    write    access    to    the    registry.    See
         wsreg_can_access_registry(3WSREG).  The unregister  sub-
         command  fails if the user attempts to unregister a sys-
         tem component, instead of a  component  registered  with
         the  Solaris Product Registry. System components include
         those which include the attribute PKG and  certain  spe-
         cial Registry nodes including the following:


         UUID                                  Name
         ====================================  =============================
         root                                  System Registry
         a01ee8dd-1dd1-11b2-a3f2-0800209a5b6b  Solaris System Software
         8f64eabf-1dd2-11b2-a3f1-0800209a5b6b  Unclassified Software
         b96ae9a9-1dd1-11b2-a3f2-0800209a5b6b  System Software Localizations
         b1c43601-1dd1-11b2-a3f2-0800209a5b6b  Additional System Software
         a8dcab4f-1dd1-11b2-a3f2-0800209a5b6b  Software Localizations

         Before the unregister subcommand with the -f  option  is
         used, you should carefully review what components depend
         upon the component which is to be unregistered.  The  -r
         option  is  even  more dangerous, since all children and
         software components depending  upon  the  component  are
         also  deregistered. You can obtain the list of dependent
         components for a component with UUID uuid using :

         prodreg info -u uuid -a "Dependent Components"

         You can obtain a list of required components using:

         prodreg info -u <uuid> -a "Required Components"

         The output lists the name, UUID and instance of the com-
         ponent.

         The unregister subcommand has the following format:

         unregister [-R alt_root] [-fr] -u uuid [-p location | -i instance]
         unregister --help




     uninstall

         Launch an uninstaller program.

         Each component in the registry can have  an  uninstaller
         associated  with it. This subcommand executes this asso-
         ciated installer, if there is one, for  a  component  in
         the  registry  given  by  the  -u option. If there is no
         uninstaller associated with the component,  the  subcom-
         mand  fails.  If the component given by the -u option is
         not unique (as there is more than one  instance  of  the
         component  installed),  the subcommand outputs a list of
         all instances. The  subcommand  must  then  be  reissued
         using  -i  or -p to disambiguate the uuid given with the
         -u option. Finally, if the  component  to  uninstall  is
         depended upon by other components, the command fails.

         The command may also launch an  uninstaller  with  a  -x
         option.  No  checks  for  whether this uninstalls a com-
         ponent upon which other components depend in this case.

         The uninstall command is not executed if the  user  does
         not   have   write   access   to   the   registry.   See
         wsreg_can_access_registry(3WSREG).

         The uninstall command has the following format:

         uninstall [-R alt_root] [-f] -u uuid -p location
         uninstall [-R alt_root] -i instance[arguments ...]
         uninstall --help




OPTIONS
     The awt subcommand supports the following options:

     --help          Display help text, do not launch the viewer.



     -R alt_root     Use the specified alternate root  to  locate
                     the database to display with the GUI viewer.

                     See  OPERANDS  for   information   regarding
                     specification of alt_root.


                     Note -  The root file  system  of  any  non-
                             global  zones must not be referenced
                             with the -R option. Doing  so  might
                             damage   the   global   zone's  file
                             system, might compromise  the  secu-
                             rity  of  the global zone, and might
                             damage the  non-global  zone's  file
                             system. See zones(5).



     The browse subcommand supports the following options:

     -help           Display help text, do not execute the browse
                     subcommand.



     -i instance     Output the specified component instance.



     -m name         Output the  component  instances  associated
                     with the name.



     -n bnum         Output the  component  instances  associated
                     with the browse number.



     -p location     Output the component instance  installed  in
                     the specified location. The install location
                     for a component can be  obtained  using  the
                     'info' subcommand.



     -R alt_root     Use the specified alternate root  to  locate
                     the database.


                     Note -  The root file  system  of  any  non-
                             global  zones must not be referenced
                             with the -R option. Doing  so  might
                             damage  the  global zone's file sys-
                             tem, might compromise  the  security
                             of the global zone, and might damage
                             the non-global zone's  file  system.
                             See zones(5).



     -u uuid         Output the  component  instances  associated
                     with the uuid.

     The info subcommand supports the following options:

     -a attr         Output only  the  attribute  whose  name  is
                     given  by the operand 'attr', instead of all
                     attributes of the specified component.



     -d              Output only  the  attribute  whose  name  is
                     isDamaged,  instead of all attributes of the
                     specified component. If the value is set  to
                     true, this attribute indicates that the com-
                     ponent in the registry



     --help          Output help text, do not execute the  browse
                     subcommand.



     -i instance     The  instance  operand  distinguishes  among
                     multiple  instances  of  components with the
                     same uuid or browse number.



     -m name         The name operand indicates one or more  com-
                     ponents in the registry.



     -n bnum         Output  the  attributes  of  the   component
                     instance  associated  with the browse number
                     bnum. If there is more  than  one  instance,
                     the  command must be disambiguated using the
                     -ior -p options.



     -p location     The install location indicated distinguishes
                     among  multiple instances of components with
                     the same uuid or browse number.



     -R alt_root     Use the specified alternate root  to  locate
                     the database.


                     Note -  The root file  system  of  any  non-
                             global  zones must not be referenced
                             with the -R option. Doing  so  might
                             damage  the  global zone's file sys-
                             tem, might compromise  the  security
                             of the global zone, and might damage
                             the non-global zone's  file  system.
                             See zones(5).



     -u uuid         Output  the  attributes  of  the   component
                     instance  associated with the uuid. If there
                     is more than one  instance,  the  subcommand
                     must  be  disambiguated  using  the -i or -p
                     options.



     The swing subcommand supports the following options:

     --help          Output help text, do not execute the install
                     subcommand.



     -R alt_root     Use the specified alternate root  to  locate
                     the database.


                     Note -  The root file  system  of  any  non-
                             global  zones must not be referenced
                             with the -R option. Doing  so  might
                             damage  the  global zone's file sys-
                             tem, might compromise  the  security
                             of the global zone, and might damage
                             the non-global zone's  file  system.
                             See zones(5).



     The uninstall subcommand supports the following options:

     -f              Force the  uninstall.  A  forced  subcommand
                     uninstalls  all  instances  of  a component,
                     even  if  there   are   multiple   ambiguous
                     instances of the uuid operand.



     --help          Output help text, do not execute  the  unre-
                     gister subcommand.


     -i instance     Disambiguate the uuid operand.



     -p location     Disambiguate  the  uuid  operand.   location
                     corresponds  to  the where the software com-
                     ponent was installed.



     -R alt_root     Use the specified alternate root  to  locate
                     the database.


                     Note -  The root file  system  of  any  non-
                             global  zones must not be referenced
                             with the -R option. Doing  so  might
                             damage  the  global zone's file sys-
                             tem, might compromise  the  security
                             of the global zone, and might damage
                             the non-global zone's  file  system.
                             See zones(5).



     -u uuid         Unregister the uuid component. If this  com-
                     ponent  has  been  installed multiple times,
                     the instance to unregister must be indicated
                     unambiguously by using the -i or -p option.



     The unregister subcommand supports the following options:

     -f              Force the unregistration. A  forced  subcom-
                     mand  unregisters  a component even if there
                     are other components which are dependent  on
                     this component.



     --help          Output help text, do not execute  the  unre-
                     gister subcommand.



     -i instance     Disambiguate the uuid operand.



     -p location     Disambiguate the uuid operand. The  location
                     corresponds   to   the  where  the  software
                     component was installed.



     -r              Causes a recursive deregistration of a  com-
                     ponent  as well as that component's children
                     and dependencies.



     -R alt_root     Use the specified alternate root  to  locate
                     the database.


                     Note -  The root file  system  of  any  non-
                             global  zones must not be referenced
                             with the -R option. Doing  so  might
                             damage  the  global zone's file sys-
                             tem, might compromise  the  security
                             of the global zone, and might damage
                             the non-global zone's  file  system.
                             See zones(5).



     -u uuid         Unregister component uuid of  the  component
                     to  unregister.  If  this component has been
                     installed multiple times,  the  instance  to
                     unregister  must  be indicated unambiguously
                     by using the -i or -p option.



OPERANDS
     The following operands are supported:

     alt_root        Pathname to a file indicating  an  alternate
                     root.  The Solaris Product Registry database
                     is located relative to the  alternate  root.
                     If  database  relative to this location does
                     not exist, it is created.


                     Note -  The root file  system  of  any  non-
                             global  zones must not be referenced
                             by alt_root. Doing so  might  damage
                             the global zone's file system, might
                             compromise the security of the  glo-
                             bal  zone, and might damage the non-
                             global  zone's  file   system.   See
                             zones(5).

     attr            Name of an attribute. This operand  is  used
                     only  with  the  info subcommand. If attr is
                     associated with a component,  the  attribute
                     name and value is displayed.



     bnum            The browse number.

                     Each component in the Solaris Product Regis-
                     try is associated with a browse number. This
                     number is generated for the  convenience  of
                     an  interactive  user. The browse number can
                     change if the system is  rebooted  or  rein-
                     stalled.  Do  not  store  or  use the browse
                     number except to facilitate the  browse  and
                     info  subcommands. Browse numbers are always
                     output by  the  prodreg  browse  subcommand.
                     Only  these  values  can  be  used  as input
                     values to the browse or info subcommand.



     instance        Software can be installed in more  than  one
                     location. The Solaris Product Registry asso-
                     ciates a unique instance  number  for  each.
                     The  browse  subcommand  shows  the instance
                     number associated with each component in the
                     registry.   The  instance operand is used to
                     distinguish between installed, and  possibly
                     different,  copies  of  software,  when such
                     exist.



     location        A path to a specific file  or  directory  in
                     the  file system. This operand indicates the
                     installed location of  registered  software.
                     For instance, if software is installed rela-
                     tive to /usr/local the value of this operand
                     would be /usr/local. The install location is
                     used to installer or to indicate  the  loca-
                     tion  of  an  installer  or  to disambiguate
                     which instance is intended,  of  a  software
                     component which can have multiple instances.



     name            Each software component in the Solaris  Pro-
                     duct  Registry  is  associated  with a name.
                     This name is output by  the  browse  subcom-
                     mand.  Some  subcommands  allow  the user to
                     input the software by name as an operand  as
                     a  convenience.  These  names  might  not be
                     unique. If the user  supplies  an  ambiguous
                     name,  for  which  more  than one components
                     exist, the subcommand outputs a list of pos-
                     sible  choices.  The  name can be localized;
                     depending on the language setting  the  name
                     can differ.



     uuid            Each software component in the Solaris  Pro-
                     duct  Registry  is  associated with a unique
                     identifier.  This  identifier  is  a  handle
                     which  accesses  an  entry  in  the registry
                     database. The uuid corresponds to  the  com-
                     ponent irrespective of how many instances of
                     the component have been installed, and  what
                     the localized name of the component is.



EXAMPLES
     Example 1: Using the prodreg Command to Browse

     Browsing is performed by means of the prodreg browse subcom-
     mand.  Using  these requests iteratively, one can peruse the
     tree, much as one would using a GUI by expanding  components
     which  are  collections  of other components. Browsing using
     browse numbers for convenience should be  done  only  during
     this  iterative browsing process, since the numbers are gen-
     erated as a result of the browsing operation.

     Evoking the browse subcommand without any arguments  browses
     from the top of the registry. The output varies depending on
     the software installed on a particular system.

     $ prodreg browse
     BROWSE # +/-/.  UUID                                  #  NAME
     ======== =====  ====================================  =  ============
     1        -      root                                  1  System
                                                              Registry
     2         +     a01ee8dd-1dd1-11b2-a3f2-0800209a5b6b  1  Solaris 10
                                                              System
                                                              Software
     3         +     8f64eabf-1dd2-11b2-a3f1-0800209a5b6b  1  Unclassified
                                                              Software

     The output of this command lists the  browse  number,  UUID,
     instance number and name of the root component and its chil-
     dren. The ancestors of a component, each parent  up  to  the
     root, are also shown. The +/-/. column indicates whether the
     component in the tree is an expanded  parent  (-),  a  child
     with children (+) or a child without children (.).

     Example 2: Requesting Information About the Components in  a
     Tree

     The UUID, name and browse  number  fields  can  be  used  to
     request  browsing  information about components in the tree.
     The next example shows how a component  can  be  browsed  by
     UUID.

     $ prodreg browse -u a01ee8dd-1dd1-11b2-a3f2-0800209a5b6b
     BROWSE #  +/-/.  UUID                                  #  NAME
     ========  =====  ====================================  =  ===========
     1         -      root                                  1  System
                                                               Registry
     2          -     a01ee8dd-1dd1-11b2-a3f2-0800209a5b6b  1  Solaris 10
                                                               System
                                                               Software
     4           +    b96ae9a9-1dd1-11b2-a3f2-0800209a5b6b  1  System
                                                               Software
                                                               Localizations
     5           +    SUNWCall                              1  Entire
                                                               Distribution

     Example 3: Browsing a Node by Name

     The following example shows how a node  can  be  browsed  by
     name.

     $ prodreg browse -m "System Software Localizations"
     BROWSE #  +/-/.  UUID                                  #  NAME
     ========  =====  ====================================  =  ===========
     1         -      root                                  1  System
                                                               Registry
     2          -     a01ee8dd-1dd1-11b2-a3f2-0800209a5b6b  1  Solaris 10
                                                               System
                                                               Software
     4           -    b96ae9a9-1dd1-11b2-a3f2-0800209a5b6b  1  System
                                                               Software
                                                               Localizations
     316          .   SUNWceuow                             1  Central
                                                               Europe OW
                                                               Support
     317          .   SUNWcsfw                              1  Simplified
                                                               Chinese
                                                               freeware
                                                               message
     318          .   SUNWceuox                             1  Central
                                                               Europe
                                                               64-bit OS
                                                               Support

     Example 4: Browsing Iteratively

     Additional output has been omitted. As  a  convenience,  the
     browse  number  can  be  used  for  iterative browsing. This
     number should not be stored,  as  it  differs  depending  on
     which  system  the  prodreg command is run on, which user is
     running the command, and the log in  session  in  which  the
     command is run.

     $ prodreg browse -n 3

     BROWSE #  +/-/.  UUID                                  #  NAME
     ========  =====  ====================================  =  ===========
     1         -      root                                  1  System
                                                               Registry
     2          -     a01ee8dd-1dd1-11b2-a3f2-0800209a5b6b  1  Solaris 10
                                                               System
                                                               Software
     5           -    SUNWCall                              1  Entire
                                                               Software
                                                               Distribution
     6            .   SUNWrsmo                              1  RSMPI
                                                               Operations
                                                               Registration
                                                               Module
     7            +   SUNWCjvx                              1  JavaVM
                                                               (64-bit)
     8            .   SUNWrsmx                              1  Remote
                                                               Shared
                                                               Memory
                                                               (64-bit)
     9            +   SUNWCacc                              1  System
                                                               Accounting

     Example 5: Browsing Using an Ambiguous Value

     If the requested value is ambiguous, the list  of  ambiguous
     instances are displayed. In the following example, there are
     two distinct software components with the same name.

     $ ./prodreg browse -m JavaVM
     The request failed because multiple components correspond to the
     criteria given. Use the list of possible components given below,
     select one and try again.

     BROWSE #  +/-/.  UUID                                  #  NAME
     ========  =====  ====================================  =  ===========
     12        .      org.spybeam.javavm                    1  JavaVM
     51        .      SUNWCjv                               1  JavaVM



     Issue one of the following requests again:

     $ prodreg browse -u SUNWCjv

     or

     $ prodreg browse -u org.spybeam.javavm

     Example 6: Browsing Multiple Installations of Software

     Another possible ambiguous response arises when a particular
     software component is installed multiple times. In the exam-
     ple below Example software is registered three times.

     $ prodreg browse -m Example
     The request failed because multiple components correspond to the
     criteria given. Use the list of possible components given below,
     select one and try again.
     BROWSE #  +/-/.  UUID                                  #  NAME
     ========  =====  ====================================  =  ===========
     7         .      org.spybeam.example                   2  Example
     7         .      org.spybeam.example                   3  Example
     7         .      org.spybeam.example                   1  Example
     The component requested could not be found.

     Example 7: Browsing Using a Particular Instance

     The request can be repeated specifying a particular instance
     to  disambiguate  it.  It is also possible to disambiguate a
     request with the -p option, followed by  the  install  loca-
     tion.  In  this  case,  to  browse the first instance of the
     Example software, one would use the command:

     $ prodreg browse -u org.spybeam.example -i 1

     Example 8: Using the info Subcommand

     The install location, as well as other attributes of a  com-
     ponent  can  be  obtained with the info subcommand. The info
     subcommand  accepts  the  same  disambiguating  options  and
     returns  all the attributes of a component, each on a single
     line.

     $ prodreg info -m Example
     The request failed because multiple components correspond to the
     criteria given. Use the list of possible components given below,
     select one and try again.
     BROWSE # +/-/. UUID                                 # NAME
     ======== ===== ==================================== = ===========
     7        .     org.spybeam.example                  2 Example
     7        .     org.spybeam.example                  3 Example
     7        .     org.spybeam.example                  1 Example
     The component requested could not be found.

     This variation of the info subcommand outputs  all  informa-
     tion  associated  with  instance 1 of the Example component.
     The output from this variation is not displayed

     $ prodreg info -u org.spybeam.example -i 1

     Example 9: Obtaining Information on the Install Location

     You can use the info subcommand to obtain the install  loca-
     tion  and  other attributes of a component. The info subcom-
     mand accepts the same disambiguating options as  the  browse
     subcommand.  It  returns  all the attributes of a component,
     each on a single line. You can also request a single  attri-
     bute.

     The following command outputs the value of the install loca-
     tion attribute:

     $ prodreg info -n 23 -a Location

     Example 10: Idenitifying and Unregistering Damaged Software

     Removing installed software  without  using  the  associated
     uninstaller  can damage the software in the registry. A dam-
     aged component indicates that certain software is installed,
     when  in  fact it is not present. A component can be damaged
     by removing files or packages directly, without running  the
     associated  uninstaller.  The  general rule to follow is: If
     software has been installed  by  an  installer  program,  it
     should  be  uninstalled  using the supplied uninstaller pro-
     gram.

     This example  shows  how  to  identify  and  repair  damaged
     software components so that software can be reinstalled.

     Browsing for Examplesoft, produces the following:

     $ prodreg browse -m Examplesoft
     BROWSE #  +/-/.  UUID                                  #  NAME
     ========  =====  ====================================  =  ============
     1         -      root                                  1  System
                                                               Registry
     2          +     a01ee8dd-1dd1-11b2-a3f2-0800209a5b6b  1  Solaris 10
                                                               System
                                                               Software
     3          +     8f64eabf-1dd2-11b2-a3f1-0800209a5b6b  1  Unclassified
                                                               Software
     4          -     95842091-725a-8501-ef29-0472985982be  1  ExampleSoft
     233         .    90209809-9785-b89e-c821-0472985982be  1  Example Doc
     234         .    EXSOzzt                               1
     235         .    EXSOblob                              1  Example Data

     The Examplesoft child EXSOzzt, representing a  package  com-
     ponent  of  registered  software  does not display its name.
     This is likely to be because  the  software  Examplesoft  is
     damaged. Verify this with the following command:

     $ prodreg info -u 95842091-725a-8501-ef29-0472985982be \
          -i 1 -d
     isDamaged=TRUE
     Since Damaged is TRUE, some part of Examplesoft is  damaged.
     The following command lists the packages which make up Exam-
     plesoft:

     $ prodreg info \
          -u 95842091-725a-8501-ef29-0472985982be\
          -i 1 -a PKGS pkgs:
     EXSOzzt EXSOblob
     Use the pkginfo command to verify if EXSO is installed:

     $ pkginfo EXSOzzt
     ERROR: information for "EXSOzzt" was not found
     $ pkginfo EXSOblob
     application EXSOblob       Example Data
     The output of these commands shows that the package  EXSOzzt
     has been removed, probably with the pkgrm command. The Exam-
     plesoft software will probably not function.  To repair  the
     software,  one  should  run  the uninstaller registered with
     Examplesoft. You probably need to run the  uninstaller  with
     root  permissions,  as  it unregisters the software and runs
     pkgrm commands. Both of these operations require  root  per-
     missions.

     # prodreg uninstall -u 95842091-725a-8501-ef29-0472985982be -i 1
     The install program requested could not be found.

     Something is wrong, or else you  would  be  able  to  access
     uninstall program to uninstall the software. One possibility
     is that the uninstaller program has been  removed  manually.
     It is possible to determine where the uninstaller is located
     by requesting the uninstallprogram attribute:

     $ prodreg info -m ExampleSoft -a uninstallprogram
     uninstallprogram: /usr/bin/java -mx64m -classpath
     /var/sadm/prod/org.example.ExampleSoft/987573587 uninstall_ExampleSoft

     Check to see if there is an uninstaller  in  the  registered
     location.

     # ls /var/sadm/prod/org.example.ExampleSoft/987573587
     /var/sadm/prod/org.example.ExampleSoft/987573587:
     No such file or directory
     Since there is no uninstaller at the desired  location,  you
     have  two  options. One is to load the uninstaller from back
     up storage and run it manually. Use the command line  stored
     in the registry:

     # /usr/bin/java -mmx64m -classpath \
          /var/sadm/prod/org.example.ExampleSoft/987573587 \
          uninstall_ExampleSoft
     If there is no other possibility,  manually  unregister  the
     software.

     # prodreg unregister -u 95842091-725a-8501-ef29-0472985982be -i 1
     This does not remove the  remaining  package  EXSOblob.  You
     must do this manually.

     # pkgrm EXSOblob

     Example 11: Removing Multiple Components

     Component A has children B and C, and C has children  D  and
     E, and the you wish to remove all of the components at once.
     This is useful if the whole hierarchy has to be  reinstalled
     and the uninstaller has been lost or cannot be run

     $ prodreg browse -u UUID-of-C
     BROWSE #  +/-/.  UUID                                  #  NAME
     ========  =====  ====================================  =  ============
     1         -      root                                  1  System
                                                               Registry
     2          +     a01ee8dd-1dd1-11b2-a3f2-0800209a5b6b  1  Solaris 10
                                                               System
                                                               Software
     3          +     8f64eabf-1dd2-11b2-a3f1-0800209a5b6b  1  Unclassified
                                                               Software
     1423       -     UUID-of-A                             1  Example A
     1436        .    UUID-of-B                             1  Example B
     1437        -    UUID-of-C                             1  Example C
     1462         .   UUID-of-D                             1  Example D
     1463         .   UUID-of-E                             1  Example E

     # prodreg uninstall -u UUID-of-A -i 1

     The uninstall subcommand can fail various ways, for  example
     if  the  java  classes  have  been  removed, if the user has
     insufficient permissions or if Java software is not  present
     on  the  system.  The recursive unregistration subcommand is
     very powerful and dangerous. Not  only  does  it  unregister
     every  child  of a component, it also unregisters every com-
     ponent which depends upon the component to unregister. It is
     a  good  idea to view all information about the component to
     determine if any components will  be  unintentionally  unre-
     gistered with UUID-of-A.
     $ prodreg info -u UUID-of-A
     Title: Example A Software
     Version: 5.8.0.2001.11.02
     Location: /usr
     Vendor: Example Vendor
     uninstallprogram: /usr/bin/java -mx64m -classpath
     /var/sadm/prod/org.example.ExampleA/90820965 uninstall_ExampleA
     vendorurl: http://www.example.org
     description: Example A Software has many uses
     Supported Languages: en

     Child Components:
     Name                        UUID                                  #
     --------------------------  ------------------------------------  -
     Example B                   UUID-of-B                             1
     Example C                   UUID-of-C                             1

     Required Components:
     Name                        UUID                                  #
     --------------------------  ------------------------------------  -
     Example B                   UUID-of-B                             1
     Example C                   UUID-of-C                             1

     No software depends on Example  A,  or  else  an  additional
     field,  Dependent  Components  would  be  shown.  To further
     ensure that there are no surprises, one should  examine  the
     dependent  components and children of UUID-of-B and UUID-of-
     C, all the components which depend on  UUID-of-B,  UUID-of-C
     and their children, and so on.

     If you examine the browse tree, you know the entire list  of
     descendents of UUID-of-A. You can also examine the dependent
     component attributes of all of Example A's descendents.

     $ prodreg info -u UUID-of-B -i 1 -a "Dependent Components"
     Dependent Components:
     Name                         UUID                                  #
     ---------------------------  ------------------------------------  -
     Example A                    UUID-of-A                             1

     $ prodreg info -u UUID-of-C -i 1 -a "Dependent Components"
     Dependent Components:
     Name                         UUID                                  #
     ---------------------------  ------------------------------------  -
     Example A                    UUID-of-A                             1

     $ prodreg info -u UUID-of-D -i 1 -a "Dependent Components"
     Dependent Components:
     Name                         UUID                                  #
     ---------------------------  ------------------------------------  -
     Example C                    UUID-of-C                             1

     $ prodreg info -u UUID-of-E -i 1 -a "Dependent Components"
     Dependent Components:
     Name                         UUID                                  #
     ---------------------------  ------------------------------------  -
     Example C                    UUID-of-C                             1

     A recursive unregistration of  Example  A  only  results  in
     unregistering Example A and its descendents, as intended.

     # prodreg unregister -r -u UUID-of-A -i 1

     Example 12: Reinstalling a Damaged Component

     In this example, there is a component, Software ZZZ which is
     depended  upon by other software. Software ZZZ has been dam-
     aged and you need to reinstall  it.  The  reinstallation  is
     impossible until Software ZZZ is unregistered.

     First, you check what depends upon Software ZZZ:

     $ prodreg info -m "Software ZZZ" -a "Dependent Components"
     Dependent Components:
     Name                         UUID                                  #
     ---------------------------  ------------------------------------  -
     Software Foobar              d9723500-9823-1432-810c-0100e09832ff  1

     Normally, you would have to uninstall Software Foobar before
     unregistering Software ZZZ, since Software Foobar depends on
     Software ZZZ. You decide that it is impossible or  unreason-
     able  to  reinstall  Software Foobar. Performing a recursive
     unregister of Software ZZZ is not  an  option  as  it  would
     unregister  Software  Foobar  as  well. Instead you can do a
     forced unregister of Software ZZZ. The UUID of Software  ZZZ
     is 90843fb1-9874-3a20-9b88-984b32098432.

     # prodreg unregister -f -u 90843fb1-9874-3a20-9b88-984b32098432 -i 1

     You can then reinstall Software ZZZ:

     # /usr/bin/java -cp /usr/installers/org.example.softwarezzz

BUGS
     The registry can become out  of  date  because  of  software
     being manually removed, or removed using pkgrm(1M) directly.
     To avoid damaging the registry, use  uninstall  programs  to
     remove  software  which  was  initially  installed  using an
     install program.

ENVIRONMENT VARIABLES
     The following environment variable affects the execution  of
     prodreg:

     PKG_INSTALL_ROOT        If present, defines  the  full  path
                             name  of  a  directory to use as the
                             system's PKG_INSTALL_ROOT path.  All
                             product   and   package  information
                             files are then  looked  for  in  the
                             directory  tree,  starting  with the
                             specified PKG_INSTALL_ROOT path.  If
                             not present, the default system path
                             of / is used.





EXIT STATUS
     The following exit values are returned:

     0        Successful completion.



     >0       An error occurred.



ATTRIBUTES
     See attributes(5) for descriptions of the  following  attri-
     butes:

     ____________________________________________________________
    |       ATTRIBUTE TYPE        |       ATTRIBUTE VALUE       |
    |_____________________________|_____________________________|
    | Availability                | SUNWwsr2, SUNWwsrv          |
    |_____________________________|_____________________________|
    | Interface Stability         | Evolving                    |
    |_____________________________|_____________________________|


SEE ALSO
     pkgadd(1M),  pkgrm(1M),   wsreg_can_access_registry(3WSREG),
     libwsreg(3LIB), live_upgrade(5), attributes(5)

     Application Packaging Developer's Guide

NOTES
     The prodreg GUI and command line  interface  view  both  the
     Solaris Product Registry and the package database. Both look
     like components in the registry, but some of these cannot be
     unregistered or uninstalled. Packages do not have an associ-
     ated uninstaller, so they cannot be  uninstalled  using  the
     prodreg  uninstall  subcommand.  Solaris  packages cannot be
     unregistered  using  the  prodreg   unregister   subcommand.
     Packages  are  removed  using  the  pkgrm(1M) command, after
     which time the packages do not appear in the GUI or CLI pro-
     dreg viewer.

     It is preferable to remove software  using  the  uninstaller
     associated  with the software installed than to remove indi-
     vidual  packages  using  pkgrm(1M),  since  the  uninstaller
     software   takes   care  of  comprehensive  removal  of  all
     resources associated with the installed software,  including
     unregistering  information  in  Registry  and  removing  the
     appropriate packages.

     The prodreg uninstall subcommand launches an  external  pro-
     gram. The command line conventions of these programs have to
     be used to indicate  the  alternate  root  for  the  product
     registry. Another possibility is to use the PKG_INSTALL_ROOT
     environment variable for this purpose as the install program
     is  executed  in  the same environment as prodreg. Uninstall
     programs are frequently java classes which require  Java  to
     be  installed. If Java software has been removed or is miss-
     ing from a Solaris distribution, it  is  impossible  to  run
     java based uninstallers.

     Only the prodreg unregister and  uninstall  subcommands  can
     only  be  run  with  root  permissions. This is because they
     modify the product registry in the case of  unregister,  and
     remove  packages  in the case of uninstall. The other opera-
     tions merely read the registry and can be run with any  user
     permissions.  The prodreg uninstall subcommand might require
     root permissions as well, as installers can execute commands
     such  as  pkgadd(1M) or pkgrm(1M) which require root permis-
     sions to run.

     Attributes associated  with  components  are  documented  in
     various  places  -primarily  in  the  Application  Packaging
     Developer's  Guide.  The  attributes  associated  with   the
     Solaris Product Registry itself are described in the follow-
     ing glossary.

     Dependent Components

         List of components upon which the component depends.



     Location

         The location relative to which software was installed.




     pkgs

         List of packages  which  correspond  to  the  component.
         These packages are added with pkgadd after the component
         is registered. They are removed with  pkgrm  before  the
         component is unregistered.



     Required Components

         List of components on which the component depends.



     Source

         Media from which the install was done.



     Supported Languages

         List of locales for which there are registered titles.



     Title

         Name given by the prodreg browse subcommand.  This  name
         can  be  localized  to  the locale in which the shell is
         running.



     Unique Name

         Name used by previous versions of  the  Solaris  Product
         Registry.  This  value  is often set to the package name
         corresponding to a given component in the registry.



     Vendor

         Vendor who produced the component.



     Version

         Version string associated with the component.

     The Registry can contain components which do not  correspond
     to  software  actually  installed on the system. This can be
     detected several ways. The easiest is  to  check  using  the
     info subcommand if a component is damaged. Another way is to
     determine where software was installed using the  info  sub-
     command, and verify it is still there.










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