patchadd(1M)
NAME
patchadd - apply a patch package to a system running the
Solaris operating environment
SYNOPSIS
patchadd [-dun] [-B backout_dir] [-k keystore] [-P passwd]
[-x proxy] [target] source [dest]
patchadd -p [target]
DESCRIPTION
patchadd applies a patch package to a system running the
Solaris 2.x operating environment or later Solaris environ-
ments (such as Solaris 9) 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.
OPTIONS
The following options are supported:
-B backout_dir
Saves backout data to a directory other than the pack-
age database. Specify backout_dir as an absolute path
name.
-d Does not back up the files to be patched. The patch
cannot be removed.
-k keystore
Use keystore as the location to get trusted certifi-
cate 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.
-u Turns off file validation. Applies the patch even if
some of the files to be patched have been modified
since their original installation.
-x proxy
Specify a HTTP[S] proxy to use when downloading pack-
ages 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
ENVIRONMENT VARIABLES in pkgadd(1M) for more informa-
tion on alternate methods of specifying a default
proxy.
OPERANDS
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 exam-
ple 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 con-
taining a patch list, specify patch_dir as the abso-
lute 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 desti-
nation. 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 also
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 recommended for installation to the
miniroot usually include install-related patches such
as package commands, and Sun install and patch instal-
lation tools. If you apply too many patches to the
miniroot it can grow too large to fit into memory dur-
ing 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 can-
not be specified with the -S option. See NOTES.
-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 Host Manager. These service areas
can then be made available to the clients they serve.
-S cannot be specified with the -R option. See NOTES.
KEYSTORE LOCATIONS
See KEYSTORE LOCATIONS in pkgadd(1M) for details.
KEYSTORE AND CERTIFICATE FORMATS
See KEYSTORE AND CERTIFICATE FORMATS in pkgadd(1M) for
details.
EXAMPLES
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 Invoca-
tion
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 Sav-
ing 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
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, pass-
word, 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
EXIT STATUS
The following exit values are returned:
0 Successful completion.
>0 An error occurred.
ATTRIBUTES
See attributes(5) for descriptions of the following attri-
butes:
____________________________________________________________
| ATTRIBUTE TYPE | ATTRIBUTE VALUE |
|_____________________________|_____________________________|
| Availability | SUNWswmt, SUNWcsu |
|_____________________________|_____________________________|
| Interface Stability | Evolving |
|_____________________________|_____________________________|
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 keystore to
make sure it has the requisite trust anchor(s)
required to validate the signature on the pack-
age 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 package'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 (uncon-
ditional) option. This time, the patch installa-
tion 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 exe-
cuted 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 invok-
ing patchadd. This option will direct patchadd
to save the backout data to the user specified
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 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 fol-
lowing 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 mes-
sage. 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 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 sys-
tem. 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 neces-
sarily 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 pack-
ages.
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 sys-
tem. 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 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 necessarily an
error. Any patch to one of the architecture-
specific packages might contain one element for
each of the possible architectures. For example,
assume you are running on a sun4u. 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.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 re-
apply.
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 (usu-
ally 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 (usu-
ally through pressing <CTRL-c>). patchadd will
clean up its working files, backout the patch,
and exit.
SEE ALSO
cpio(1), pkginfo(1), patchrm(1M), pkgadd(1M), pkgadm(1M),
pkgchk(1M), pkgrm(1M), smpatch(1M), showrev(1M), attri-
butes(5)
NOTES
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 packages 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 chec-
kinstall script as 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. Contents of log file for a successfull installa-
tion: patchadd redirects pkgadd's output to the patch ins-
tallation 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 appropriate, 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
Man(1) output converted with
man2html