                             OPATCH USERS GUIDE
                Copyright (c) Oracle Corporation 2006

INTRODUCTION
------------

OPatch is a set of Perl scripts that allow the application and rolling back 
of interim patches to an Oracle product. The program has sub-commands that 
may take arguments. The program requires that the Perl language interpreter
(ref: http://www.cpan/org/ ) is available on the current system. 

Help is available for all commands.

OPatch relies upon Perl version 5.005_03 or greater to run but version
5.6 or greater is recommended.

We will update this user-guide as arguments and commands change.

OPatch expects users to have commands such as jar, java, ar, cp and make
(depending on platforms) available in their PATH.

ENVIRONMENTAL VARIABLES
-----------------------

$ORACLE_HOME must point to a valid Oracle Home and matches the value when that Oracle Home was installed. A list of products that have been installed can be retrieved from the inventory by using "lsinventory -all".

REAL APPLICATION CLUSTERS
-------------------------

When patching a RAC installation with either a rolling patch or minimum
downtime the user is prompted for which nodes to patch during the patch
installation process. A rolling RAC patch is identified inside the patch
and cannot be enabled when invoking the patch tool. More details are in
the FAQ that should be in the same directory as this file.

When patching a RAC on certain platforms, it is important that the LD_LIBRARY_PATH must be set up correctly.  Please see the FAQ for details.

LIMITATIONS
-----------

The current version of OPatch has some limitions that will be resolved
in the future. These limitations are:

1.	Shared ORACLE_HOMEs (clustered file systems):

	Rolling RAC and minimum down options are not supported and should
	not be used on RAC clusers with a shared ORACLE_HOME. This 
	is normally seen when CFS (clustered file systems) are used for
	the installation.

	Patching this type of installtion should be done on a single machine.
	Any instance that uses the ORACLE_HOME on a CFS that is to be 
	patched should be stopped on all nodes before patching the
	installation.

2.	Simultaneous installing new instances and patching:

	Currently installing a new instance while patching an existing
	installation is not supported. Inventory corruption may 
	result from this activity.

3.    Patch process must finish
      
      Currently a partially installed interim patch cannot be removed. 
   The patch process must finish. Once the patch process has finished 
   the patch can be removed.


GENERAL USAGE
-------------

      $ 'opatch apply ...' is to apply a patch
      $ 'opatch rollback ...' is to roll back a patch
      $ 'opatch lsinventory' is to show installed patches
      $ 'opatch lsinventory -detail' is to show installed products
      $ 'opatch lsinventory -all' is to show all products on all Oracle Homes
      $ 'opatch version' is to show version of OPatch

SYNOPSIS
--------

    < perl > < opatch > < opatch sub-command > [ < command_arguments > ]

where:

    perl:               A version of perl. The version must be 5.005_03 or
                        greater but 5.6 or greater is recommended.
    opatch:             The path to the opatch program.
    opatch sub-command: The sub-command to use.
    command_arguments:  Any arguments supported by the sub-command.


DETAILS
-------

Invoking OPatch without arguments or with the 'help' sub-command returns
the list of valid sub-commands to the user:

$ opatch

 Usage: opatch [ -h[elp] ] [ -r[eport] ] [ command ]

            command := apply
                       lsinventory
                       query
                       rollback
                       version

 <global_arguments> := -help   Displays the help message for the command.
                       -report Print the actions without executing (deprecated).

                       


APPLY
-----

The apply command is used to install a interim patch.

$ opatch apply -h

    SYNOPSIS:

         apply <patch_location>  [ -delay <value> ] [ -force ]
                                 [ -invPtrLoc <Path to oraInst.loc> ]
                                 [ -jdk <LOC> ] [ -jre <LOC> ] [ -local ]
                                 [ -minimize_downtime ] [ -no_bug_superset ]
                                 [ -no_inventory ] [ -oh <ORACLE_HOME> ]
                                 [ -opatch_post_end ] [ -opatch_pre_end ]
                                 [ -post <options to be passed into post> [-opatch_post_end] ]
                                 [ -pre <options to be passed into pre> [-opatch_pre_end] ]
                                 [ -retry <value> ]
                                 [ -silent ] [ -verbose ] [  ]

    DESCRIPTION:

         Applies an interim patch to an ORACLE_HOME from the current 
         directory. The patch location can be changed by using patch_location. 
         A different installation can be specified by using ORACLE_HOME.

    ARGUMENTS:

         -delay              If -retry is specified, this option tells
                             OPatch how many seconds it should wait before
                             attempting to lock inventory again in case
                             of a previous failure.

         -error_on_conflict  Deprecated.  Has no effect.

         -force              If a conflict exist which prevents the patch 
                             from being applied, the -force flag can be 
                             used to apply the patch.
                             *** This removes the conflicting patches from 
                             the system.

         -invPtrLoc          Used to locate the oraInst.loc file.
                             Needed when the installation used the
                             invPtrLoc flag. This should 
                             be the path to the oraInst.loc file

         -jdk                This option tells OPatch to use JDK (jar)
                             from the specified location instead of
                             the default location under Oracle Home.
                             
         -jre                This option tells OPatch to use JRE (java)
                             from the specified location instead of
                             the default location under Oracle Home.
                             
         -local              Patch the local node, then update
                             inventory of the local node. 
                             Do not propagate the patch or
                             inventory update to other nodes.

            			     This command-line argument can be used on Oracle
			                 Real Application Clusters environments and
            			     non-clustered environments. If an entire cluster 
			                 is shutdown before patching, then this argument 
            			     can be used for non-rolling patches;
                             
         -minimize_downtime  Only applied to RAC instances. User supplies
                             the order of nodes to be patched.
                             This option can not be used in
                             conjunction with -local option
                             or with a rolling patch.
                             
         -no_bug_superset    This option tells OPatch to error out if the
                             current patch's bugs-to-fix is a super-set
                             (or same set) of an installed patch's bugs-fixed
                             in the Oracle Home.
                             
         -no_inventory       Bypass the inventory for reading and updates.
                             This option can not be used in
                             conjunction with -local option
                             *** This puts the installation ***
                             *** into an unsupported state. ***
                             

         -oh                 The directory to use instead of the default of
                             $ORACLE_HOME.

         -opatch_post_end    This option is used to mark the
                             end of post options. Without this option
                             everything after post till end of
                             the command is passed into post.
                             This option is meaningless without
                             -post option
                             

         -opatch_pre_end     This option is used to mark the
                             end of pre options. Without this option
                             everything after pre till end of
                             the command is passed into pre.
                             This option is meaningless without
                             -pre option
                             

         -post               This option specifies the parameters
                             to be passed inside post script apart
                             from the standard ones.
                             Without this option OPatch calls post
                             as 'post -<operation> <patch-id>'
                             With this option OPatch will call post
                             as 'post -<operation> <patch-id> <post options>'
                             

         -pre                This option specifies the parameters
                             to be passed inside pre script apart
                             from the standard ones.
                             Without this option OPatch calls pre
                             as 'pre -<operation> <patch-id>'
                             With this option OPatch will call pre
                             as 'pre -<operation> <patch-id> <pre options>'
                             

         -retry              This option tells OPatch how many times
                             it should retry in case of an inventory
                             lock failure.

         -silent             This suppresses any user-interaction and defaults
                             any Y|N question to Y.
                             This option to be used with -local to automate
                             RAC patching.
                             

         -verbose            This option prints more OPatch output
                             to the screen as well as to the log file
                             

         patch_location      Where to install the interim patch from.
                             This should be a directory with the same name as
                             the interim patch.


LSINVENTORY
-----------

This command reports what's installed on the current system.

$ opatch lsinventory -h    


    SYNOPSIS:

         lsinventory 
             [ -all ] [ -detail ] [ -invPtrLoc ] <Path to oraInst.loc> ] 
             [ -jre <LOC> ] [ -oh <ORACLE_HOME> ]

    DESCRIPTION:

  List the inventory for a particular $ORACLE_HOME or display all installations that can be found.

    ARGUMENTS:

         -all        Report the name and installation directory for each 
                     $ORACLE_HOME found.

         -detail     Report installed products and other details.
                     This option can not be used in conjunction with -all option 
                     
         -invPtrLoc  Used to locate the oraInst.loc file.
                     Needed when the installation used the invPtrLoc flag. This should 
                     be the path to oraInst.loc file

         -jre        This option tells OPatch to use JRE (java) from the specified location 
                     instead of the default location under Oracle Home.
                     
         -oh         The directory to use instead of the default of $ORACLE_HOME. 


ROLLBACK
--------

The rollback command removes a interim patch from the appropriate 
$ORACLE_HOME.

$ opatch rollback -h


    SYNOPSIS:

         rollback -id <ID> -ph <dir>  -delay <value>  
                                      [ -invPtrLoc <Path to oraInst.loc> ] -jdk <LOC>
                                      [ -jre <LOC> ] -local  [ -oh <ORACLE_HOME> ]
                                      [ -opatch_post_end ] -opatch_pre_end
                                      [ -post <options to be passed into post> [-opatch_post_end] 
                                      [ -pre <options to be passed into pre> [-opatch_pre_end]
                                      [ -retry <value>]
                                      [ -silent]
                                      [ -verbose ]

    DESCRIPTION:

         Rollback an existing one-off patch indicated by the reference-id.

    ARGUMENTS:

         -delay            If -retry is specified, this option tells
                           OPatch how many seconds it should wait before
                           attempting to lock inventory again in case
                           of a previous failure.

         -id               Use 'lsinventory' option to display all patch 
                           id's. Each one-off patch is indicated by it's 
                           id. To rollback a patch the id for that patch 
                           must be supplied.

         -invPtrLoc        Used to locate the oraInst.loc file.
                           Needed when the installation used the
                           invPtrLoc flag. This should 
                           be the path to the oraInst.loc file

         -jdk              This option tells OPatch to use JDK (jar)
                           from the specified location instead of
                           the default location under Oracle Home.
                           

         -jre              This option tells OPatch to use JRE (java)
                           from the specified location instead of
                           the default location under Oracle Home.
                           

         -local            Roll back then update inventory of the local node. 
                           Do not propagate the patch or 
                           inventory update to other nodes.

            			   This command-line argument can be used on Oracle 
			               Real Application clusters environments and 
            			   non-clustered environments. If an entire cluster 
			               is shutdown before patching, then this argument
            			   can be used for non-rolling patches.
                           
         -oh               The directory to use instead of the default of
                           $ORACLE_HOME.

         -opatch_post_end  This option is used to mark the
                           end of post options. Without this option
                           everything after post till end of
                           the command is passed into post.
                           This option is meaningless without
                           -post option
                           

         -opatch_pre_end   This option is used to mark the
                           end of pre options. Without this option
                           everything after pre till end of
                           the command is passed into pre.
                           This option is meaningless without
                           -pre option
                           

         -ph               Specify the valid patch directory area.
                           Rollback will use the command types 
                           found in the patch directory to
                           identify what commands are to be used
                           for the current operating system.

         -post             This option specifies the parameters
                           to be passed inside post script apart
                           from the standard ones.
                           Without this option OPatch calls post
                           as 'post -<operation> <patch-id>'
                           With this option OPatch will call post
                           as 'post -<operation> <patch-id> <post options>'
                           

         -pre              This option specifies the parameters
                           to be passed inside pre script apart
                           from the standard ones.
                           Without this option OPatch calls pre
                           as 'pre -<operation> <patch-id>'
                           With this option OPatch will call pre
                           as 'pre -<operation> <patch-id> <pre options>'
                           

         -retry            This option tells OPatch how many times
                           it should retry in case of an inventory
                           lock failure.

         -silent           This suppresses any user-interaction and defaults
                           any Y|N question to Y.
                           This option to be used with -local to automate
                           RAC patching.
                           

         -verbose          This option prints more OPatch output
                           to the screen as well as to the log file

To find the patch id numbers, use 'opatch lsinventory'.

Currently a patch directory must also be supplied. Under normal practice
the directory for the patch when it was installed is available. It is
needed so a list of commands can be retrieved. Any patch directory should 
suffice.

QUERY
-----

This command queries a given patch for specific details.

$ opatch query -h

    SYNOPSIS:

         query  [ -all ] [ -get_base_bug ] [ -get_component ]
                [ -get_date ] [ -get_os ] [ -get_system_change ]
                [ -invPtrLoc <Path to oraInst.loc> ] [ -is_rolling ] [ -is_shutdown ]
                [ -verify ]

    DESCRIPTION:

         Query various info. about a patch and the system being patched.


    ARGUMENTS:

         -all                Get everything available about a patch.
                             This is equivalent to setting all
                             available options.


         -get_base_bug       Get the base bugs fixed by a patch.


         -get_component      Get the Oracle components either optional
                             or required by a patch.


         -get_date           Get the built date of a patch.


         -get_os             Get the Operating System description
                             supported by a patch.


         -get_system_change  Get a description of what changes will
                             be made to this system by a patch.
                             (currently not available, use -all).

         -invPtrLoc          Used to locate the oraInst.loc file.
                             Needed when the installation used the
                             invPtrLoc flag. This should
                             be the path to the oraInst.loc file

         -is_rolling         Is it a rolling patch?


         -is_shutdown        Should Oracle instances be down
                             during patching process
                             (currently not available, use -all).

         -verify             Verify if a patch has been applied on Oracle Home.



VERSION
-------

This command prints the current version number of the patch tool.


==========================================================================
Modified 11/15/05.
