patchadd(1M)															      patchadd(1M)

NAME

       patchadd - apply a patch package to a system running the Solaris operating environment

SYNOPSIS

       patchadd [-dun] [-G] [-B backout_dir] [-k keystore] [-P passwd] [-t] [-x proxy] source [destination]

       patchadd -p [destination]

       patchadd  applies  a patch package to a system running the Solaris 2.x operating environment or later Solaris environments (such as Solaris
       10) that are compatible with Solaris 2.x. This patch installation utility cannot be used to apply Solaris 1 patches. patchadd must  be  run
       as root.

       The patchadd command has the following forms:

	 o  The first form of patchadd installs one or more patches to a system, client, service, or to the miniroot of a Net Install Image.

	 o  The second form of patchadd displays installed patches on the client, service, or to the miniroot of a Net Install Image.

       With  respect  to  zones(5),  when invoked in the global zone, by default, patchadd patches all appropriate packages in all zones. Patching
       behavior on system with zones installed varies according to the following factors:

	 o  use of the -G option (described below)

	 o  setting of the SUNW_PKG_ALLZONES variable in the pkginfo file (see pkginfo(4))

	 o  type of zone, global or local (non-global) in patchadd which is invoked

       The interaction of the factors above is specified in "Interaction of -G and pkginfo Variable in Zones," below.

       When you add patches to packages on a Solaris system with zones installed, you will see numerous zones-related messages, the frequency  and
       content	of  which depend on whether you invoke patchadd in a global or local zone, the setting of SUNW_PKG_ALLZONES, and the use of the -G
       option.

       The following options are supported:

       -B backout_dir

	   Saves backout data to a directory other than the package database. Specify backout_dir as an absolute path name.

       -d

	   Does not back up the files to be patched. The patch cannot be removed.

       -G

	   Add patch(es) to packages in the current zone only. When used in the global zone, the patch is added to packages  in  the  global  zone
	   only  and is not propagated to packages in any existing or yet-to-be-created non-global zone. When used in a non-global zone, the patch
	   is added to packages in the non-global zone only. See "Interaction of -G and pkginfo Variable in Zones,", below.

       -k keystore

	   Use keystore as the location to get trusted certificate authority certificates when verifying digital signatures found in  each  patch.
	   If  no  keystore is specified, then the default keystore locations are searched for valid trusted certificates. See KEY STORE LOCATIONS
	   in pkgadd(1M) for more information.

       -n

	   Tells patchadd to ignore the signature and not to validate it. This should be used only when the content of	the  patch  is	known  and
	   trusted,  and  is  primarily  included to allow patchadd to apply a patch on systems without the ability to verify the patch signature,
	   such as Solaris 8.

       -p

	   In the second form, displays a list of the patches currently applied.

       -P passwd

	   Password to use to decrypt the keystore specified with -k, if required. See PASS PHRASE ARGUMENTS in pkgadd(1M)  for  more  information
	   about the format of this option's argument.

       -t

	   Maintains the patchadd return codes from the Solaris release prior to Solaris 10. On a system with zones(5) installed, a return code of
	   0 indicates success. Any other return code indicates failure.

       -u

	   Turns off file validation. Applies the patch even if some of the files to be patched have been modified since their original  installa-
	   tion.

       -x proxy

	   Specify  a  HTTP[S]	proxy to use when downloading packages The format of proxy is host:port, where host is the hostname of the HTTP[S]
	   proxy, and port is the port number associated with the proxy. This switch overrides all other methods of specifying a  proxy.  See	in
	   pkgadd(1M) for more information on alternate methods of specifying a default proxy.

       The following operands are supported:

   Sources
       patchadd must be supplied a source for retrieving the patch. The following sources and their syntax are acceptable:

       patch

	   The	absolute  path	name  to  patch_id  or a URI pointing to a signed patch. /var/sadm/spool/patch/104945-02 is an example of a patch.
	   https://syrinx.eng:8887/patches/104945-02 is an example of a URI pointing to a signed patch.

       -M patch_dir patch_id [patch_id...]

	   Specifies the patches to be installed by directory location or URL, and patch number.

	   To use the directory location or URL and the patch number, specify patch_dir as the absolute path name of the directory  that  contains
	   spooled patches. Specify a URL as the server and path name that contains the spooled patches. Specify patch_id as the patch number of a
	   given patch. Specifying multiple patch_id's is recommended. patch_id is the patch number of a given patch. 104945-02 is an example of a
	   patch_id.

       -M patch_dir patch_list

	   Specifies the patches to be installed by directory location or URL and the name of a file containing a patch list.

	   To  use  the directory location or URL and a file containing a patch list, specify patch_dir as the absolute path name of the directory
	   that contains spooled patches. Specify URL as the server and path name that contains the spooled patches.  Specify  patch_list  as  the
	   name of the file containing the patches to be installed.

   Destinations
       By  default,  patchadd  applies a patch to the specified destination. If no destination is specified, then the current system (the one with
       its root filesystem mounted at /) is assumed to be the destination for the patch. You can specify a destination in the following ways:

       -C net_install_image

	   Patches the files located on the miniroot on a Net Install Image created by	setup_install_server.  Specify	net_install_image  as  the
	   absolute path name to a Solaris 8 or compatible version boot directory. See EXAMPLES.

	   You	should	use  the  -C option only to install patches that are recommended for installation to the miniroot. Patches that are recom-
	   mended for installation to the miniroot usually include install-related patches such as package commands, and  Sun  install	and  patch
	   installation  tools.   If you apply too many patches to the miniroot it can grow too large to fit into memory during a net installation
	   of Solaris. Use the -B option and the -C option together so the miniroot does not get too large. See -B, above.

       -R client_root_path

	   Locates all patch files generated by patchadd under the directory client_root_path. client_root_path is the directory that contains the
	   bootable  root  of  a  client from the server's perspective. Specify client_root_path as the absolute path name to the beginning of the
	   directory tree under which all patch files generated by patchadd are to be located. -R cannot be specified  with  the  -S  option.  See
	   NOTES.

	   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 security of the global zone,  and	might  damage  the  non-global	zone's	file  system.  See
		   zones(5).

       -S service

	   Specifies an alternate service (for example, Solaris_8). This service is part of the server and client model, and can only be used from
	   the server's console. Servers can contain shared /usr file systems that are created by smosservice(1M). These service areas can then be
	   made available to the clients they serve. -S cannot be specified with the -R option. See NOTES.

   Interaction of -G and pkginfo Variable in Zones
       The  following list specifies the interaction between the -G option and the SUNW_PKG_ALLZONES variable (see pkginfo(4)) when adding a patch
       in global and local (non-global) zones.

       global zone, -G specified

	   If any packages have SUNW_PKG_ALLZONES set to true: Error; nothing changes.

	   If no packages have SUNW_PKG_ALLZONES set to true: Apply patch to package(s) in global zone only.

       global zone, -G not specified

	   If any packages have SUNW_PKG_ALLZONES set to true: Apply patch to appropriate package(s) in all zones.

	   If no packages have SUNW_PKG_ALLZONES set to true: Apply patch to appropriate package(s) in all zones.

       local zone, -G specified or not specified

	   If any packages have SUNW_PKG_ALLZONES set to true: Error; nothing changes.

	   If no packages have SUNW_PKG_ALLZONES set to true: Apply patch package(s) in local zone only.

KEYSTORE LOCATIONS

       See KEYSTORE LOCATIONS in pkgadd(1M) for details.

KEYSTORE AND CERTIFICATE FORMATS

       See KEYSTORE AND CERTIFICATE FORMATS in pkgadd(1M) for details.

       The examples in this section are all relative to the /usr/sbin directory.

       Example 1: Installing a Patch to a Standalone Machine

       The following example installs a patch to a standalone machine:

       example# patchadd /var/sadm/spool/104945-02

       Example 2: Installing a Patch to a Client From the Server's Console

       The following example installs a patch to a client from the server's console:

       example# patchadd -R /export/root/client1  /var/sadm/spool/104945-02

       Example 3: Installing a Patch to a Service From the Server's Console

       The following example installs a patch to a service from the server's console:

       example# patchadd -S Solaris_8 /var/sadm/spool/104945-02

       Example 4: Installing Multiple Patches in a Single Invocation

       The following example installs multiple patches in a single patchadd invocation:

       example# patchadd -M /var/sadm/spool 104945-02 104946-02 102345-02

       Example 5: Installing Multiple Patches Specifying List of Patches to Install

       The following example installs multiple patches specifying a file with the list of patches to install:

       example# patchadd -M /var/sadm/spool patchlist

       Example 6: Installing Multiple Patches to a Client and Saving the Backout Data

       The following example installs multiple patches to a client and saves the backout data to a directory other than the default:

       example# patchadd -M /var/sadm/spool -R /export/root/client1 
	    -B /export/backoutrepository 104945-02 104946-02 102345-02

       Example 7: Installing a Patch to a Solaris 8 or Compatible Version Net Install Image

       The following example installs a patch to a Solaris 8 or compatible version Net Install Image:

       example# patchadd -C /export/Solaris_8/Tools/Boot 
	   /var/sadm/spool/104945-02

       Example 8: Displaying the Patches Installed on a Client

       The following example displays the patches installed on a client:

       example# patchadd -R /export/root/client1 -p

       Note the caveat on the use of the -R option in the description of that option, above.

       Example 9: Installing a Digitally Signed Set of Patches

       The following example installs multiple patches, some of which have been signed, using the supplied keystore, password, and HTTP proxy.

       example# patchadd -k /etc/mycerts -P pass:abcd -x webcache.eng:8080 
       -M http://www.sun.com/solaris/patches/latest 101223-02 102323-02

       The following exit values are returned:

       0	Successful completion.

       >0	An error occurred.

       See attributes(5) for descriptions of the following attributes:

       +-----------------------------+-----------------------------+
       |      ATTRIBUTE TYPE	     |	    ATTRIBUTE VALUE	   |
       +-----------------------------+-----------------------------+
       |Availability		     |SUNWswmt, SUNWcsu 	   |
       +-----------------------------+-----------------------------+
       |Interface Stability	     |Evolving			   |
       +-----------------------------+-----------------------------+

       cpio(1), pkginfo(1), patchrm(1M), pkgadd(1M), pkgadm(1M),  pkgchk(1M),  pkgrm(1M),  smpatch(1M),  showrev(1M),  pkginfo(4),  attributes(5),
       zones(5)

DIAGNOSTICS

       The following messages might help in determining some of the most common problems associated with installing a patch.

   Patch Installation errors
       Message

	   The prepatch script exited with return code retcode.
	   patchadd 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 prepatch script and
	       find out why the prepatch had a bad return code. Add the -x option to the first line of the prepatch script to fix the problem  and
	       run patchadd again.

       Message

	   The signature on patch patch_id was unable to be verified.
	   patchadd is terminating.

	   Explanation and Recommended Action

	       The digital signature on a patch was unable to be verified given the keystore in use and the signature on the patch. Check the key-
	       store to make sure it has the requisite trust anchor(s) required to validate the signature on the package and that the package  has
	       not been tampered with.

       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
	       (that is, when a package is known to have ownership or permission problems) attributes that do not correspond to  the  patch  pack-
	       age's objects. After the user has noted all validation errors and taken the appropriate action for each one, the user should re-run
	       patchadd using the -u (unconditional) option. This time, the patch installation will ignore validation errors and install the patch
	       anyway.

       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 prob-
	       lem: Use the -B option while invoking patchadd.	This option will direct patchadd to: save the backout data to the  user  specified
	       file system, generate additional disk space by deleting unneeded files, or override the saving of the old files by using the -d (do
	       not save) option when running patchadd.

	       If the user elects not to save the old versions of the files to be patched, patchrm 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 patchadd. The following commands should be executed to  remove  the
	       saved files for patchpatch_id:

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

	       After these commands have been executed, patch patch_id 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 patchadd. This option will direct patchadd to save the backout data to the user spec-
	       ified  file system. (See synopsis above.) (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 patchadd. However, if the user elects not to save the  old  ver-
	       sions of the files to be patched, patchrm cannot be used. One way to regain space on a system is to remove the save area for previ-
	       ously 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 patchadd. The following commands should be executed to remove the saved files for patch patch_id:

	       cd /var/sadm/pkg/pkgabbrev/save
	       rm -r patch_id

	       After these commands have been executed, patch patch_id can no longer be backed out.

       Message

	   Save of old files failed.
	   (For 2.4 systems and previous)

	   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  appro-
	       priate  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 patchadd. 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 the patch packages failed. patchadd 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 reapply 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. patchadd will not backout the patch. You may manually backout the patch using
	       patchrm, 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

	   patchadd is unable to find the INST_RELEASE file. This file
	   must be present for patchadd to function correctly.

	   Explanation and Recommended Action

	       The INST_RELEASE file is missing from the system. This file is created during either initial installation or during an update.

       Message

	   A previous installation of patch patch_id was invoked
	   that saved files that were to be patched. Since files
	   were saved, you must run this instance of patchadd
	   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 patchadd without the -d option.

       Message

	   A previous installation of patch patch_id was invoked
	   with the -d option. (i.e. Do not save files that would
	   be patched) Therefore, this invocation of patchadd
	   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 patchadd with the -d' option.

   Diagnostic Reference
       The  patch installation 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 and Recommended Action

	       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.

	       For 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  neces-
	       sary 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 and Recommended Action

	       One  of the components of the patch would have patched a package for an architecture different from your system. This is not neces-
	       sarily an error. Any patch to one of the architecture-specific packages might contain one element for each of the  possible  archi-
	       tectures. For example, assume you are running on a sun4u. If you were to install a patch to package SUNWcar, you would see the fol-
	       lowing (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.sun4u
	       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

	       Package not patched:
	       PKG=SUNWcar
	       ARCH=sparc.sun4
	       VERSION=11.5.0,REV=2.0.18
	       Architecture mismatch

	       These messages indicate an error condition only if patchadd does not correctly recognize your architecture.

       Message

	   Package not patched:
	   PKG=SUNxxxx
	   ARCH=xxxx
	   VERSION=xxxxxxx
	   Version mismatch

	   Explanation and Recommended Action

	       The version of software to which the patch is applied is not installed on your system. For example, if you were running Solaris	8,
	       and you tried to install a patch against Solaris 9, 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 reapply.

       Message

	   Re-installing Patch.

	   Explanation and Recommended Action

	       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

	   patchadd Interrupted.
	   patchadd is terminating.

	   Explanation and Recommended Action

	       patchadd was interrupted during execution (usually through pressing <CTRL-c>). patchadd will clean up its working files and exit.

       Message

	   patchadd Interrupted.
	   Backing out Patch...

	   Explanation and Recommended Action

	       patchadd  was  interrupted  during execution (usually through pressing <CTRL-c>). patchadd will clean up its working files, backout
	       the patch, and exit.

       To successfully install a patch to a client or server, patchadd must be issued twice, once with the -R option and once with the -S  option.
       This  guarantees  that the patch is installed to both the /usr and root partitions. This is necessary if there are both /usr and root pack-
       ages in the patch.

       pkgadd is invoked by patchadd 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 noaccess. 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 installa-
       tion to abort with the following error:

       pkgadd: ERROR: checkinstall script did not complete successfully.

       The permission for the checkinstall script should not be changed. Contents of log file for a successfull installation:  patchadd  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.
       This message does not indicate a failure, it represents the correct behavior by pkgadd when a patch installs correctly.

       On client server machines the patch package is not applied to existing clients or to the client root template space. Therefore, when appro-
       priate,	all client machines will need the patch applied directly using this same patchadd method on the client. See instructions above for
       applying patches to a client. A bug affecting a package utility (for example, pkgadd,  pkgrm,  pkgchk)  could  affect  the  reliability	of
       patchadd  or  patchrm,  which  use  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. Existing patches are:

       Solaris 2.5.1 Sparc Platform Edition:

	   104578

       Solaris 2.5.1 Intel Platform Edition:

	   104579

       Solaris 2.6 Sparc Platform Edition:

	   106292

       Solaris 2.6 Intel Platform Edition:

	   106293

								    3 Oct 2005							      patchadd(1M)