# @(#) Install.info 1.19 99/03/08 SMI

#       Copyright(c) 1999 SunSoft. All rights reserved.

Patch Installation Instructions:

    Note: In Solaris 2.6 new patch installation and removal commands 
    exist as /usr/sbin/patchadd and /usr/sbin/patchrm. These patch
    commands are invoked by the installpatch and backoutpatch contained
    in every 2.6 patch. A WARNING message is displayed that states
    patchadd or patchrm is being used to install or remove a patch.
    This message is part of the normal procedure for installing or
    removing a patch on a Solaris 2.6 system.

    On a Solaris 2.6 system any patch can be installed using 
    /usr/sbin/patchadd and removed by using /usr/sbin/patchrm.
    It is recommended that patch administrators start using
    patchadd and patchrm since installpatch and backoutpatch
    will no longer be part of the patch construct in the next
    major release of Solaris.

	The following instructions and diagnostics still apply to
    patchadd and patchrm. Just invoke the new commands instead of
    installpatch and backoutpatch.

Instructions for installing a patch using "installpatch"
--------------------------------------------------

    1. Become super-user.

    2. Apply the patch by typing:

       <dir>installpatch <patch-dir>

       where <dir> is the directory containing installpatch, and
       <patch-dir> is the directory containing the patch itself.

    Example:

       # cd /tmp_patchdir/123456-01
       # ./installpatch .

    3. If any errors are reported, see "Patch Installation Errors" in
       the Command Descriptions section below.

       Rebooting the system or restarting the application after a successful
       patch installation is usually necessary to utilize patch.

    NOTE: On client/server machines the patch package is NOT applied
       to existing clients, to the client root template space or to
       the shared /usr partition of the server.  
       Therefore, when appropriate, ALL CLIENT MACHINES WILL NEED 
       THE PATCH APPLIED DIRECTLY USING THIS SAME INSTALLPATCH 
       METHOD ON THE CLIENT. It is recommended that any client/server
       combinations of the same OS level and architecture should have 
       the equivalent patch base installed. See the next section for instructions
       for installing a patch on a client.

Instructions for installing a patch on a dataless client
--------------------------------------------------------------------

    1. Before applying the patch, the following command must be executed
       on the server to give the client read-only, root access to the
       exported /usr file system so that the client can execute the
       pkgadd command:

       share -F nfs -o ro,anon=0 /export/exec/<os_version>/usr

       The command:

       share -F nfs -o ro,root=<client_name> \
		/export/exec/<os_version>/usr

       accomplishes the same goal, but only gives root access to the
       client specified in the command.

    2. Login to the client system and become super-user.

    3. Continue with step 2 in the "Instructions to install patch using
       installpatch" section above.

Instructions for installing a patch on a diskless client
--------------------------------------------------------------------

    To install a patch on a diskless client, you may either follow the
    instructions for installing on a dataless client (that is, you may
    logon to the client and install the patch), or you may use the
    following instructions to install the patch while on the server.

    1. Find the complete path for the root directory of the diskless
       client.

    2. Install the patch normally, but add the command option -R <path>
       to the command line. <path> should be the completely specified.

    Example:

       # cd /tmp_patchdir/123456-01
       # ./installpatch -R /export/root/client1 .

    3. To ensure that the clients root path and the shared servers /usr
       file system are at the same patch level, the patch must be applied
       to the servers service area also. This service area
       needs to patched only if there are /usr packages in the patch.
       This example assumes that the server is supplying services for
       Solaris 2.4 client.

    Example:

       # cd /tmp_patchdir/123456-01
       # ./installpatch -S Solaris_2.4

Instructions for installing multiple patches.
--------------------------------------------------------------------

    1. Become super-user.

    2. Apply the patch by typing.

       <dir>installpatch -M <patch_directory> <patch_id>... | <patch_file>

       where patch <patch_directory> is the directory that contains all the 
       spooled patches i.e. /var/sadm/spool/patch. <patch_id> is the patch 
       number of a given patch i.e. 104945-02. <patch_file> is a file 
       containing a list of patches to install, physically located in the 
       <patch_directory>.
       
    Example:

       1. # <dir>installpatch -M /var/spool/patch 102345-02 103098-01 103456-01

       2. # <dir>installpatch -M /var/spool/patch patch_file

    Example patch_file:

       One patch per line.

       102345-02 
       103098-01
       103456-01
          .
          .
          .

Instructions for installing a patch and saving the backout data
to location other than the default save directory
--------------------------------------------------------------------

    1. Become super-user.

    2. Apply the patch by typing.

       <dir>installpatch -B <backout-directory> <patch-dir>

       where <backout-directory> is the user specified directory
       to save the backout data.

Instructions for backing out a patch using "backoutpatch"
-----------------------------------------------------------

    1. Become super-user. 

    2. Change directory to /var/sadm/patch:
 
       cd /var/sadm/patch
 
    3. Backout patch by typing:
 
       <patch-id>/backoutpatch <patch-id>
 
       where <patch-id> is the patch number.

    Example:

       # cd /var/sadm/patch
       # 123456-01/backoutpatch 123456-01

    4. If any errors are reported, see "Patch Backout Errors" in 
       the Command Descriptions section below.

Instructions for backing out a patch where the backout data was
saved to a directory other than the default location
--------------------------------------------------------------------

    1. Follow steps 1 thru 4 above

    2. If the backout data was moved, supply backoutpatch with the
       new location of the backout data.

       <patch-id>/backoutpatch -B <new-backout-directory> <patch-id>

Instructions for backing out a patch on a dataless client
----------------------------------------------------------

    1. Give the client root access to /usr as specified in the installpatch
       section.

    2. Logon to the client and follow backoutpatch instructions as
       specified above.

Instructions for backing out a patch on a diskless client
-----------------------------------------------------------

    To backout a patch on a diskless client, you may either follow the
    instructions for backout on a dataless client (that is, you may
    logon to the client and backout the patch), or you may use the
    following instructions to backout the patch while on the server.

    1. Find the complete path for the root directory of the diskless
       client.

    2. Backout the patch normally, but add the command option -R <path>
       to the command line. <path> should be the completely specified.

    Example:

       # cd /export/root/client1/var/sadm/patch
       # ./123456-01/backoutpatch -R /export/root/client1 123456-01

Instructions for identifying patches installed on system:
----------------------------------------------------------

    Patch packages that have been installed can be identified by
    using the -p option. To find out which patches are installed on
    a diskless client, use both the -R <dir> option and the -p
    option, where <dir> is the fully specified path to the client's
    root directory.

	#cd /tmp_patchdir/123456-01
	#./installpatch -p
	#./installpatch -R /export/root/client1 -p

    Also note that the command "showrev -p" will show the patches installed
    on the local machine, but will not show patches installed on clients.

Command Descriptions
--------------------

NAME

    installpatch - apply patch package to Solaris 2.x system
    backoutpatch - remove patch package, restore previously saved files

SYNOPSIS

       installpatch [-u] [-d] [-V] [-B <backout_dir>]
                    [-S <service> | -R <root_path>] <patch>
       installpatch [-u] [-d] [-V] [-B <backout_dir>]
                    [-S <service> | -R <root_path>]
                    -M <patch_directory> <patch_id>... | <patch_file>
       installpatch [-S <service> | -R <root_path>] -p

       backoutpatch [-f] [-V] [-B <backout_dir>] [-R <root_path> | -S
                    <service>] <patch>
DESCRIPTION

    These installation and backout utilities apply only to
    Solaris 2.x associated patches. They do not apply to Solaris
    1.x associated patches. These utilities are currently only
    provided with each patch package and are not included with
    the standard Solaris 2.x release software.

OPTIONS

    installpatch:
        -u     unconditional install, turns off file validation.  Allows
               the patch to be applied even if some of the files to be
               patched have been modified since original installation.
        -d     Don't back up the files to be patched.  This means
               that the patch CANNOT BE BACKED OUT.
        -p     Print a list of the patches currently applied
        -V     Print script version number
        -R <root_path>
               Define the full path name of a subdirectory to use as the
               root_path. All package system information files are assumed
               to be located in a directory tree starting in the
               specified root_path. All patch files generated from the
               installpatch will be located in the same directory tree.
               Cannot be specified with the -S option.
        -B     Save backout data to a location other than the default
        -S <service>
               Specify an alternate service (e.g. Solaris_2.3) for
               patch package processing references. Cannot be specified
               with the -R option.
        -M <patch_directory> <patch_id>... | <patch_file>
               Specify one or more patchids on the command line. These patches
               must be physically located in the patch directory.
               Specify a file that contains a list of patches to be installed.
               This file must be physically located in the patch directory


    backoutpatch:
        -f     force the backout regardless of whether the patch was
               superseded
        -V     print version number only
        -R <root_path>
               Define the full path name of a subdirectory to use as the
               root_path.  All package system information files are assumed
               to be located in a directory tree starting in the specified
               root_path.  All patch files generated from the installpatch
               will be located in the same directory tree.  Cannot be
               specified with the -S option
        -B     Save backout data to a location other than the default
        -S <service>
                Specify an alternate service (e.g. Solaris_2.3) for
                patch package processing references.

DIAGNOSTICS

    Patch Installation Notes:
    -------------------------

    Pkgadd is invoked by installpatch and executes the 
    installation scripts in the <PKG>/install directory. The
    checkinstall script is executed with its ownership set to
    user "install", if there is no user "install" then pkgadd executes
    the checkinstall script as user "nobody". The SVR4 ABI states
    that the checkinstall shall only be used as an information 
    gathering script. If the permissions for the checkinstall
    script are changed to something other than the initial settings,
    pkgadd may not be able to open the file for reading, thus
    causing the patch installation to abort with the following error:

        pkgadd: ERROR: checkinstall script did not complete successfully

    The permission for the checkinstall script should not be changed.

    Also, if directories above the location of the spooled patch
    are not readable by user "other", the previous error will be
    displayed.

    Contents of log file for a successfull installation:
    ----------------------------------------------------

    Installpatch redirects pkgadd's output to the patch installation
    log file. For a successfull installation, pkgadd will produce the
    following message that gets inserted into the log file:

        This appears to be an attempt to install the same architecture and
        version of a package which is already installed.  This installation
        will attempt to overwrite this package.
    
    This message does not indicate a failure, it represents the correct
	behavior by pkgadd when a patch installs correctly.

    Patch Installation Errors:
    --------------------------

    Message:
        The prepatch script exited with return code <retcode>.
        Installpatch is terminating.

      Explanation and recommended action: The prepatch script supplied
        with the patch exited with a return code other than 0. Run a
        script trace of the installpatch and find out why the prepatch
        had a bad return code. Fix the problem and re-run installpatch.

	  To execute a script trace:

        # ksh -x ./installpatch . > /tmp/patchout 2>&1

        The file /tmp/patchout will list all commands executed by
        installpatch. You should be able to determine why your prepatch
        script failed by looking through the /tmp/patchout file. If
        you still can't determine the reason for failure, contact
        customer service.

    Message:
        The postpatch script exited with return code <retcode>.
        Backing out patch.

      Explanation and recommended action: The postpatch script
        provided with the patch exited with an error code other
        than 0. This script is mostly used to cleanup files 
        (i.e. When a  pkg is known to have ownership and/or permission
        problems) attributes that don't correspond
        to the patch pkg's objects.  After the user has noted all
        validation errors and taken the appropriate action for
        each one, the user should re-run installpatch using
        the "-u" (for "unconditional") option. This time, the
        patch installation will ignore validation errors and
        install the patch anyway. This script is not limited to
        any particular function and may be used for anything the
        patch engineer sees fit.

    Message:  
        Insufficient space in /var/sadm/patch to save old files.
        (For 2.4 systems and previous)

      Explanation and recommended action:  There is insufficient
        space in the /var/sadm/patch directory to save old files. 
        The user has three options for handling this problem: 
        (1) Use the -B option while invoking installpatch. This option
        will direct installpatch to save the backout data to the user
        specified File System. (See above synopsis)
        (2) generate additional disk space by deleting unneeded
        files, or (3) override the saving of the old files by
        using the "-d" (do not save) option when running installpatch.
        However if the user elects not to save the old versions of
        the files to be patched, backoutpatch CANNOT be used.

        One way to regain space on a system is to remove the
        save area for previously applied patches.  Once the user
        has decided that it is unlikely that a patch will be
        backed out, the user can remove the files that were saved
        by installpatch.  The following commands should be executed
        to remove the saved files for patch xxxxxx-yy:

        cd /var/sadm/patch/xxxxxx-yy
        rm -r save/*
        rm .oldfilessaved

        After these commands have been executed, patch xxxxxx-yy can
        no longer be backed out.

    Message:  
        Insufficient space in /var/sadm/pkg/<PKG>/save to save old files.
        (For 2.5 systems and later)

      Explanation and recommended action:  There is insufficient
        space in the /var/sadm/pkg/PKG/save directory to save old files. 
        The user has three options for handling this problem: 
        (1) Use the -B option while invoking installpatch. This option
        will direct installpatch to save the backout data to the user
        specified File System. (See above synopsis)
        (2) generate additional disk space by deleting unneeded
        files, or (3) override the saving of the old files by
        using the "-d" (do not save) option when running installpatch.
        However if the user elects not to save the old versions of
        the files to be patched, backoutpatch CANNOT be used.

        One way to regain space on a system is to remove the
        save area for previously applied patches.  Once the user
        has decided that it is unlikely that a patch will be
        backed out, the user can remove the files that were saved
        by installpatch.  The following commands should be executed
        to remove the saved files for patch xxxxxx-yy:

        cd /var/sadm/patch/xxxxxx-yy
        rm -r save/*
        rm .oldfilessaved

        After these commands have been executed, patch xxxxxx-yy can
        no longer be backed out.

    Message:  
        Save of old files failed.

      Explanation and recommended action:  Before applying the patch,
        the patch installation script uses cpio to save the old
        versions of the files to be patched.  This error message
        means that the cpio failed.  The output of the cpio
        would have been preceded this message.  The user should
        take the appropriate action to correct the cpio failure.
        A common reason for failure will be insufficient disk
        space to save the old versions of the files.  The user
        has two options for handling insufficient disk space:
        (1) generate additional disk space by deleting unneeded
        files, or (2) override the saving of the old files by
        using the "-d" option when running installpatch. However
        if the user elects not to save the old versions of the
        files to be patched, the patch CANNOT be backed out.

    Message: 
        Pkgadd of <pkgname> package failed with error code <code>.
        See /tmp/log.<patch-id> for reason for failure.

      Explanation and recommended action:  The installation of one of
        patch packages failed. Installpatch will backout the patch
        to leave the system in its pre-patched state.  See the log file
        for the reason for failure.  Correct the problem and
        re-apply the patch.

    Message:
        Pkgadd of <pkgname> package failed with error code <code>.
        Will not backout patch...patch re-installation.
        Warning: The system may be in an unstable state!
        See /tmp/log.<patch-id> for reason for failure.

      Explanation and recommended action:  The installation of one of
        the patch packages failed. Installpatch will NOT backout the 
        patch.  You may manually backout the patch using backoutpatch,
        then re-apply the entire patch. Look in the log file for the 
        reason pkgadd failed.  Correct the problem and re-apply the 
        patch.

    Message:
        installpatch is unable to find the INST_RELEASE file.  This file
        must be present for installpatch to function correctly.

      Explanation and recommended action:  The file INST_RELEASE is
        missing from the system.  This file is created during either 
        initial installation or during an update.  Contact customer 
        service.

    Message:
        A previous installation of patch <patchnum> was invoked
        that saved files that were to be patched.  Since files
        were saved, you must run this instance of installpatch
        without the -d option.

      Explanation and recommended action:  If a patch was previously
        installed without using the '-d' option, then the re-installation
        attempt must also be invoked without the '-d' option.  Execute
        installpatch without the '-d' option.

    Message:
        A previous installation of patch <patchnum> was invoked
        with the -d option.  (i.e. Do not save files that would
        be patched)  Therefore, this invocation of installpatch
        must also be run with the -d option.

      Explanation and recommended action:  If a patch was previously
        installed using the '-d' option, then the re-installation
        attempt must also be invoked with the '-d' option.  Execute
        installpatch with the '-d' option.

    Patch Installation Messages:
    ---------------------------

    Note: the messages listed below are not necessarily considered errors
    as indicated in the explanations given.  These messages are, however,
    recorded in the patch installation log for diagnostic reference.
    
    Message:
        Package not patched:
        PKG=SUNxxxx
        Original package not installed

      Explanation: One of the components of the patch would have patched a
        package that is not installed on your system. This is not
        necessarily an error. A Patch may fix a related bug for several
        packages. 

        Example: suppose a patch fixes a bug in both the
        online-backup and fddi packages. If you had online-backup installed
        but didn't have fddi installed, you would get the message

        Package not patched:
        PKG=SUNWbf
        Original package not installed

        This message only indicates an error if you thought the package
        was installed on your system. If this is the case, take the
        necessary action to install the package, backout the patch (if
        it installed other packages) and re-install the patch.
 
    Message:
        Package not patched:
        PKG=SUNxxx
        ARCH=xxxxxxx
        VERSION=xxxxxxx
        Architecture mismatch
 
      Explanation: One of the components of the patch would have patched a
        package for an architecture different from your system. This is not
        necessarily an error. Any patch to one of the architecture specific
        packages may contain one element for each of the possible
        architectures. For example, Assume you are running on a sun4m. If
        you were to install a patch to package SUNWcar, you would see the
        following (or similar) messages:
 
        Package not patched:
        PKG=SUNWcar
        ARCH=sparc.sun4c
        VERSION=11.5.0,REV=2.0.18
        Architecture mismatch
 
        Package not patched:
        PKG=SUNWcar
        ARCH=sparc.sun4d
        VERSION=11.5.0,REV=2.0.18
        Architecture mismatch
 
        Package not patched:
        PKG=SUNWcar
        ARCH=sparc.sun4e
        VERSION=11.5.0,REV=2.0.18
        Architecture mismatch
 
        Package not patched:
        PKG=SUNWcar
        ARCH=sparc.sun4
        VERSION=11.5.0,REV=2.0.18
        Architecture mismatch
 
        The only time these messages indicate an error condition
        is if installpatch does not correctly recognize your architecture.
 
    Message:
        Package not patched:
        PKG=SUNxxxx
        ARCH=xxxx
        VERSION=xxxxxxx
        Version mismatch
 
      Explanation: The version of software to which the patch is applied is
        not installed on your system. For example, if you were running Solaris
        5.3, and you tried to install a patch against Solaris 5.2, you would
        see the following (or similar) message:
 
        Package not patched:
        PKG=SUNWcsu
        ARCH=sparc
        VERSION=10.0.2
        Version mismatch
 
        This message does not necessarily indicate an error. If
        the version mismatch was for a package you needed patched, either
        get the correct patch version or install the correct package version.
        Then backout the patch (if necessary) and re-apply.
 
    Message:
	    Re-installing Patch.

      Explanation: The patch has already been applied, but there is
	    at least one package in the patch that could be added. For
	    example, if you applied a patch that had both OpenWindows and
	    AnswerBook components, but your system did not have AnswerBook
	    installed, the AnswerBook parts of the patch would not have
	    been applied. If, at a later time, you pkgadd AnswerBook, you
	    could re-apply the patch, and the AnswerBook components of the
	    patch would be applied to the system.
 
    Message:
	    Installpatch Interrupted.
	    Installpatch is terminating.

      Explanation: Installpatch was interrupted during execution
	    (usually through pressing ^C). Installpatch will clean up
	    its working files and exit.

    Message:
	    Installpatch Interrupted.
	    Backing out Patch...

      Explanation: Installpatch was interrupted during execution
	    (usually through pressing ^C). Installpatch will clean up
        its working files, backout the patch, and exit.

    Patch Backout Errors:
    ---------------------

    Message:
        prebackout patch exited with return code <retcode>.
        Backoutpatch exiting.

      Explanation and corrective action: the prebackout script
        supplied with the patch exited with a return code other
        than 0. Generate a script trace of backoutpatch to determine
        why the prebackout script failed. Correct the reason for
        failure, and re-execute backoutpatch.

    Message:
        postbackout patch exited with return code <retcode>.
        Backoutpatch exiting."

      Explanation and corrective action: the postbackout script
        supplied with the patch exited with a return code other than
        0. Look at the postbackout script to determine why it failed.
        Correct the failure and, if necessary, RE-EXECUTE THE 
        POSTBACKOUT SCRIPT ONLY.

    Message:
        Only one service may be defined.

      Explanation and corrective action: You have attempted to specify
        more than one service from which to backout a patch. Different
        services must have their patches backed out with different
        invocations of backoutpatch.

    Message:
        The -S and -R arguments are mutually exclusive.

      Explanation and recommended action: You have specified both a
        non-native service to backout, and a package installation root.
        These two arguments are mutually exclusive. If backing out a
        patch from a non-native usr partition, the -S option should be 
        used. If backing out a patch from a client's root 
        partition (either native or non-native), the -R option
        should be used.

    Message:
        The <service> service cannot be found on this system.

      Explanation and recommended action: You have specified a non-
        native service from which to backout a patch, but the 
        specified service is not installed on your system. Correctly
        specify the service when backing out the patch.

    Message:
        Only one rootdir may be defined.

      Explanation and recommended action: You have specified more than
        one package install root using the -R option. The -R option
        may be used only once per invocation of backoutpatch.

    Message:
        The <dir>  directory cannot be found on this system.

      Explanation and recommended action: You have specified a
        directory using the -R option which is either not mounted,
        or does not exist on your system. Verify the directory name
        and re-backout the patch.

    Message:  
        Patch <patch-id> has not been successfully applied to this system.

      Explanation and recommended action: You have attempted to backout
        a patch that is not applied to this system. If you must
        restore previous versions of patched files, you may have to
        restore the original files from the initial installation CD.

    Message:  
        Patch <patch-id> has not been successfully applied to this system.
        Will remove directory <dir>

      Explanation and recommended action: You have attempted to back
        out a patch that is not applied to this system. While the
        patch has not been applied, a residual 
        /var/sadm/patch/<patch-id> (perhaps from an unsuccessful
        installpatch) directory still exists. The patch cannot be 
        backed out. If you must restore old versions of the patched
        files, you may have to restore them from the initial 
        installation CD.

    Message:  
        This patch was obsoleted by patch <patch number>.
        Patches must be backed out in the order in
        which they were installed. Patch backout aborted.
 
      Explanation and recommended action: You are attempting to backout
        Patches out of order. Patches should never be backed-out out 
        of sequence.  This could undermine the integrity of the more 
        current patch.

    Message:
        Patch <patch-id> was installed without backing up the original 
        files.  It cannot be backed out.

      Explanation and recommended action:  Either the -d option of
        installpatch was set when the patch was applied, or the save
        area of the patch was deleted to regain space.  As a result, the
        original files are not saved and backoutpatch cannot be used.
        The original files can only be recovered from the original 
        installation CD.

    Message: 
        pkgrm of <pkgname> package failed return code <code>.
        See /var/sadm/patch/<patch-id>/log for reason for failure.

      Explanation and recommended action:  The removal of one of
        patch packages failed.  See the log file for the reason for
        failure.  Correct the problem and run the backout script again.

    Message:
        Restore of old files failed.

      Explanation and recommended action:  The backout script uses the
        cpio command to restore the previous versions of the files
        that were patched.  The output of the cpio command should
        have preceded this message.  The user should take the
        appropriate action to correct the cpio failure.

KNOWN PROBLEMS:

     On client server machines the patch package is NOT applied
     to existing clients or to the client root template space.
     Therefore, when appropriate, ALL CLIENT MACHINES WILL NEED
     THE PATCH APPLIED DIRECTLY USING THIS SAME INSTALLPATCH
     METHOD ON THE CLIENT.  See instructions above for
     applying patches to a client.
 
     A bug affecting a package utility (eg. pkgadd, pkgrm, pkgchk)
     could affect the reliability of installpatch or backoutpatch 
     which uses package utilities to install and backout the patch 
     package.  It is recommended that any patch that fixes package 
     utility problems be reviewed and, if necessary, applied before
     other patches are applied.  Such existing patches are:

100901	Solaris 2.1
101122	Solaris 2.2
101331	Solaris 2.3

SEE ALSO
     pkgadd, pkgchk, pkgrm, pkginfo, showrev, cpio

