# @(#) install_notes 1.6 94/01/11 SMI
# @(#) install_notes 1.6 94/01/12 SMI
#
# Generic Patch README installation instructions for 
#
#	installpatch, rev 3.8 or higher
#	backoutpatch, rev 3.6 or higher
#
# This file required by the genreadme script.  When a 2.x readme is
# being created genreadme appends the contents of this file to complete
# the readme. (DO NOT REMOVE THE "BEGIN TEXT:" LABEL BELOW).
#
# BEGIN TEXT:

Instructions to install patch using "installpatch"
--------------------------------------------------

1.  Become super-user.

2.  Apply the patch by typing:

	<dir>/<patch-id>/installpatch <dir>/<patch-id>

    where <dir> is the directory containing the patch and <patch-id>
    is the patch number.  <dir> must be a full path name.

    Example:

	# /tmp/123456-01/installpatch /tmp/123456-01

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 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 the next section for instructions
	  for installing a patch on a client.


Instructions for installing a patch on a diskless or 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 backing out 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:

	# 123456-01/backoutpatch 123456-01

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


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

Patch packets that have been installed can be identified by
using the showrev command with the "-p" option:

    showrev -p

Also note that installpatch has a similar "-p" option which
will also just identify patches already installed.


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

NAME

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

SYNOPSIS

     installpatch [-udpV] [-S <service>] <patch number>
     backoutpatch [-fV] [-S <service>] <patch number>

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 can't be backed out.
          -p    Print a list of the patches currently applied
          -V    Print script version number
          -S <service>
                Specify an alternate service (e.g. Solaris_2.3) for
                patch package processing references.

     backoutpatch:
         -f     force the backout regardless of whether the patch was
                superseded
         -V     print version number only
         -S <service>
                Specify an alternate service (e.g. Solaris_2.3) for
                patch package processing references.


DIAGNOSTICS

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

    Error message: 
	Patch <patch-id> has already been applied.

      Explanation and recommended action: This patch has already been
	applied to the system.  If the patch has to be reapplied
	for some reason, backout the patch and then reapply it.

    Error message: 
	This patch is obsoleted by patch <patch-id> which has already
	been applied to this system. Patch installation is aborted.

      Explanation and recommended action: Occasionally, a patch
	is replaced by a new patch which incorporates the bug fixes
	in the old patch and supplies additional fixes also.  At
	this time, the earlier patch is no longer made available
	to users.  The second patch is said to "obsolete" the
	first patch.  However, it is possible that some users
	may still have the earlier patch and try to apply it to
	a system on which the later patch is already applied.
	If the obsoleted patch were allowed to be applied, the
	additional fixes supplied by the later patch would no
	longer be available, and the system would be left in an
	inconsistent state.  This error message indicates that
	the user attempted to install an obsoleted patch.  There
	is no need to apply this patch because the later patch
	has already supplied the fix.

    Error Message: 
	None of the packages to patch are installed on this system.

      Explanation and recommended action: The original packages for
	this patch have not been installed and therefore the patch
	cannot be applied.  The original packages need to be installed
	before applying the patch.

    Error message: 
	This patch is not applicable to client systems.

      Explanation and recommended action: The patch is only
	applicable to servers and standalone machines.  Attempting
	to apply this patch to a client system will have no effect on
	the system.

    Error message: 
	The /usr/sbin/pkgadd command is not executable.

      Explanation and recommended action:   The /usr/sbin/pkgadd
	command cannot be executed.  The most likely cause of this
	is that installpatch is being run on a diskless or dataless
	client and the /usr file system was not exported with
	root access to the client.  See the section above on
	"Instructions for installing a patch on a diskless or
	dataless client".

    Error message: 
	<patch-id> packages are not proper patch packages.

      Explanation and recommended action: The patch directory
	supplied as an argument to installpatch did not contain the
	expected package format.  Verify that the argument supplied
	to installpatch is correct. 

    Error message: 
	The following validation error was found:
	           <validation error(s)>

      Explanation and recommended action: Before applying the patch,
	the patch application script verifies that the current
	versions of the files to be patched have the expected
	fcs checksums and attributes.  If a file to be patched has
	been modified by the user, the user is notified of this
	fact.  The user then has the opportunity to save the
	file and make a similar change to the patched version.
	For example, if the user has modified /etc/inet/inetd.conf
	and /etc/inet/inetd.conf is to be replaced by the patch,
	the user can save the locally modified /etc/inet/inetd.conf
	file and make the same modification to the new file
	after the patch is applied.  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.

    Error message:  
	Insufficient space in /var/sadm/patch to save old files.

      Explanation and recommended action:  There is insufficient
        space in the /var/sadm/patch directory to save old files. 
	The user has two options for handling this problem: 
	(1) generate additional disk space by deleting unneeded
	files, or (2) 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.

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

    Error 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.  Any previously installed packages
	in the patch should have been removed.  See the log file
	for the reason for failure.  Correct the problem and
	re-apply the patch.


    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.
 
 
    Patch Backout Errors:
    ---------------------

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

      Explanation and recommended action:  The user has attempted to back
	out a patch that was never applied to this system.  It is
	possible that the patch was applied, but that the patch
	directory /var/sadm/patch/<patch-id> was deleted somehow.
	If this is the case, the patch cannot be backed out.  The
	user may have to restore the original files from the
	initial installation CD.

    Error message:  
	This patch was obsoleted by patch $1.
        Patches must be backed out in the order in
        which they were installed. Patch backout aborted.
 
      Explanation and recommended action:  The obsoleted contents of an
	older patch rev that apparently still exists under /var/sadm/patch
	should never be restored out of sequence.  This could undermine
	the integrity of the more current patch rev installed and the 
	restoration of the files it has saved. 

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

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

    Error 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
