Intro

News

Installation

Usage

Changes

Lists

Notes

Contrib

Links

Donation

NAME

PCA - analyze, download and install patches for Oracle Solaris

SYNOPSIS

pca [OPTION] .. [OPERAND] ..

DESCRIPTION

PCA is a perl script which generates lists of installed and missing patches for Oracle Solaris systems and optionally downloads and installs patches. By default, if run without any option or operand, PCA shows a list of all patches which are not installed in their most recent revision.

The output of the pkginfo, showrev and uname commands is used to gather information about the system. Oracle offers a patch cross-reference file called patchdiag.xref which contains information about all available patches. This file is downloaded by PCA automatically to /var/tmp/ and kept up-to-date. If the file exists and is not writable, PCA uses it and won't try to update it.

SAMPLE OUTPUT

Here's some sample output from pca -l all, which shows a list of all installed and missing patches:

  Using /var/tmp/patchdiag.xref from Feb/29/04
  Host: myhost (SunOS 5.9/Generic_117171-09/sparc/sun4u)
  List: all (7/2182)

  Patch  IR   CR RSB Age Synopsis
  ------ -- - -- --- --- --------------------------------------------------
  112785 42 < 43 RS-  18 X11 6.6.1: Xsun patch
  112787 01 = 01 --- 999 X11 6.6.1: twm patch
  112807 10 = 10 RS-   9 CDE 1.5: dtlogin patch
  113039 -- < 06 ---  76 SAN 4.4.1: Sun StorEdge Traffic Manager patch
  113040 -- < 08 R--  77 SAN 4.4.1: fctl/fp/fcp driver patch
  113477 02 > -- --- 999 NOT FOUND IN CROSS REFERENCE FILE!
  117114 -- < 02 ---   4 CDE 1.5: sdtwebclient patch

The header includes some general information about the patchdiag.xref file, the host (Host:) and the listed patches (List:). The numbers in parantheses are the number of listed patches and the sum of their ages in days; when listing missing patches, this is a rough indicator of the current patch state.

The first column (Patch) contains the patch number, followed by the installed revision (IR) and the current revision (CR), with one of <, >, or = between them, which tells whether the installed patch revision is lower, equal or higher than the current revision of the patch. The RSB column lists the Recommended/Security/Bad flag of the patch. Age shows the number of days since the patch was released, and Synopsis shows a short description of the patch.

On this system, revision 42 of patch 112785 is installed, but a newer revision (43) is available. This patch is marked Recommended/Security. Patch 112787 is installed in revision 01, which is the most recent revision of the patch. 112807 is marked Recommended/Security, and it's up-to-date.

Patches 113039, 113040 and 117114 are not installed at all, and 113040 is marked Recommended.

113477 is installed, but not listed in the cross-reference file. New Solaris update releases often have patches pre-installed which are not yet listed in patchdiag.xref.

Often one patch requires other patches to be installed before it can be installed. PCA resolves these dependencies, and lists patches in their correct order. This can be seen in the patch list when a greater patch number is shown before a lower one, or when a patch which is not marked R/S is shown on the list of missing R/S patches.

OPTIONS

-l, --list

List patches. See OPERANDS on how to specify which patches are listed.

-L, --listhtml

Like -l, but generates output in HTML format, including links to patch READMEs and downloads. If patchurl is set and points at a local patch proxy, the links in HTML output will point there, too.

-d, --download

Download patches. See OPERANDS on how to specify which patches are downloaded. Patches are placed in the current directory or in patchdir, if set. A My Oracle Support Account and a wget binary with SSL/HTTPS support are required.

-i, --install

Download and install patches. See OPERANDS on how to specify which patches are installed. Requires PCA to be run as root. Downloaded patches are removed after successful installation, unless --download is used, too.

-I, --pretend

Like -i, but only pretend to install patches. Can be used to find out if any of the patches require a reboot.

-r, --readme

Display patch READMEs. See OPERANDS on how to specify which READMEs are displayed. The patch README is extracted from a previously downloaded patch file or downloaded directly from Oracle, which requires a My Oracle Support Account and a wget binary with SSL/HTTPS support.

-u, --unzip

Download and unzip patches. See OPERANDS on how to specify which patches are unzipped. Unzipped patch directories are placed in the current directory or in patchdir, if set. Downloaded patches are removed after successful unzip operation, unless --download is used, too. It is not necessary to unzip patches with this option before installing them. Instead, this can be used to peek into the contents of a patch zip file.

-x, --getxref

Download most recent patch cross-reference file. If the file does not exist or is older than 3 hours, PCA tries to download it on its own before anything else.

-X, --xrefdir=DIR

Set location of the cross-reference file. The default is /var/tmp (in proxy mode, the default is the current directory). By default, patchdiag.xref is writable for all users. If the xrefown option is set, or the xrefdir option contains /home, the cross reference file will be writable by the current user only.

-y, --nocheckxref

Do not check for updated patch cross-reference file. Use this option to maintain a global baseline patch set.

--xrefown

If set, patchdiag.xref will be writable for the current user only.

--nocache

If a proxy is used to access the Internet, this option advises it to not cache patchdiag.xref. Useful if the proxy can't be trusted to always return an up-to-date version of the file.

-P, --patchdir=DIR

Set directory to which patches are downloaded. The default is the current working directory.

-a, --askauth

Deprecated.

--user=USER

Login name for My Oracle Support Account authentication.

--passwd=PASS

Password for My Oracle Support Account authentication.

--supplevel

Deprecated. Oracle broke the interface to query this information.

--patchurl=URL

PCA will download patches and READMEs from this URL. Multiple URLs separated by whitespace can be specified. Any URL starting with file:/, ftp://, http:// or https://, and absolute paths can be used. The default is the special keyword oracle, meaning the Oracle patch server. See LOCAL PATCH SERVER for more information.

--xrefurl=URL

PCA will download patchdiag.xref from this URL. Multiple URLs separated by whitespace can be specified. Any URL starting with file:/, ftp://, http:// or https://, and absolute paths can be used. The default is the special keyword oracle, meaning the Oracle patch server. See LOCAL PATCH SERVER for more information.

--stop=ID

Stop after patch ID. When the specified patch ID is reached during listing, downloading or installing patches all operations are stopped. The option will be ignored if the same patch ID is explicitly included in the OPERANDS.

--ignore=WHAT

Ignore certain patches. The patch will not be listed, downloaded or installed. Specify a patch ID without revision (123456) to ignore any revision of patch 123456. Specify 123456-78 to ignore only revision 78 of patch 123456; newer revisions will not be ignored. Specify a search pattern like JavaSE to ignore patches whose synopsis matches the pattern. If an ignored patch is required by another patch, this patch might fail to install due to the missing patch dependency.

--rec=ID

Set Recommended flag on patch ID. Useful to add single patches to the set of recommended patches. The patch will be marked with a lowercase r in PCA's output.

--sec=ID

Set Security flag on patch ID. Useful to add single patches to the set of security patches. The patch will be marked with a lowercase s in PCA's output.

-p, --pattern=REGEX

List only patches whose synopsis matches the search pattern REGEX. This can be a simple string like mail or a regular expression like [kK]ernel. If the pattern starts with a !, only patches which do not match the pattern are shown.

-n, --noreboot

Install only patches that don't require a reboot after installation.

--minage=DAYS

List only patches which are at least DAYS old.

--maxage=DAYS

List only patches which are at most DAYS old.

--nodep

Do not resolve patch dependencies.

--minimal

Use minimal (instead of latest) revision for recommended patches. In combination with the missingr patch group this can be used to check a system against the same set of patches as included in the Recommended Patchset for Solaris, containing the minimal revisions of all critical patches recommended to be installed proactively. In short, "pca --minimal --install missingr" should give the same result as installing the Recommended Patchset for Solaris. Use of --minimal with any other patch group than missingr might give unexpected results.

--syslog=TYPE

Syslog priority to log patch installs to. The default is daemon.notice which gets logged to /var/adm/messages. Specify facility and severity (e.g. local7.info) or a facility only (e.g. local7, the default severity is notice). Use none to disable logging to syslog.

-k, --nobackup=ID

Do not back up files to be patched for patch ID. This works by running patchadd with its -d option. Patches can not be backed out if this option is used. Specify a patch ID with or without a revision or the special ID all to not back up files for any patch.

-B, --backdir=DIR

Saves patch backout data to DIR. This works by running patchadd with its -B option.

-s, --safe

Safe patch installation. Checks all files for local modifications before installing a patch. A patch will not be installed if files with local modifications would be overwritten.

-G, --currentzone

Make patchadd modify packages in the current zone only. This works by running patchadd with its -G option. This option works on Solaris 10 or newer only.

--patchadd=FILE

Path to an alternative patchadd command.

-H, --noheader

Don't display descriptive headers and other information, just one line per patch. Useful if re-using PCA's output in own scripts.

--format=FORMAT

Set output format to FORMAT. The default format is %p %i %e %c %r%s%b %a %y. Use %p for the patch number, %i for the installed revision, %e for information whether the installed revision is lower, equal or higher than the current revision (%c). Use %r, %s and %b for the Recommended, Security and Bad flag, %a for the age, %d for the release date, %o for OS and %y for the Synopsis. Use %n as a patch counter and %t for the total number of patches. Example: With the format string %p-%c %y PCA shows patches in the same format as smpatch. Use of this option in combination with --listhtml is unsupported.

-f, --fromfiles=DIR

Read uname/showrev/pkginfo output from files in the specified directory, where DIR can also be a file name prefix. See CREATING PATCH REPORTS FOR REMOTE MACHINES for details.

--dltries=NUM

Try downloads from Oracle's download server NUM times. The default is 1. Can be raised to reduce failed patch downloads when Oracle's patch download server is unresponsive.

-F, --force

Force local caching proxy to download patchdiag.xref, patches and patch READMEs from Oracle's download server, even if the file is already in the cache. Useful to download updated patch READMEs for bad patches.

-R, --root=DIR

Set alternative root directory. This can be useful for Live Upgrade, to analyze patches in an alternate root environment or to point PCA at the mini-root of a jumpstart install server.

--wget=PATH

Path to the wget command. Specify the name of the wget binary or the directory containing the wget binary. When multiple wget binaries are found, the newest with the best protocol support is used.

--wgetproxy=URL

Default proxy for wget.

--wgetopt=OPT

Feed option OPT directly to wget as-is. Usually only needed for debug reasons and to work around local configuration issues. Leading -/-- must be included and OPT must be quoted!

--logger=FILE

Path to (alternative) logger command.

-t, --threads=NUM

Number of concurrent download threads. See THREADS for details.

--update=TYPE

Check for available updates for PCA itself. TYPE can be never, check, now or auto. See UPDATE PCA for more information.

--pcaurl=URL

Set the URL which is used by update to check for new versions of PCA. See UPDATE PCA for more information.

--ssprot=PROT

Deprecated.

--sshost=HOST

Deprecated.

--ohost=HOST

Use HOST as the hostname or IP address of the Oracle download server. The default is updates.oracle.com.

--norootchk

When using the safe or the install option, root permission is required to run pkgchk or patchadd. Use this option to skip the check, e.g. when using sudo or RBAC.

--cffile=FILE

Read FILE as additional configuration file. Use cffile=FILE in a configuration file to include FILE.

-V, --debug

Show debug output on stderr. This includes output generated by patchadd. When running in proxy mode, debug output will be written to the file /var/tmp/pca-proxy-debug.txt.

-h, --help

Print help on command line options.

-m, --man

Print manual page. This requires the Pod::Usage module.

-v, --version

Print version information.

If no option is specified, the -l option to list patches is used.

OPERANDS

The operands determine which patches are listed (-l), downloaded (-d), installed (-i) or whose READMEs are displayed (-r). Multiple operands can be specified. Supported operands are patch group (missing, installed, all, total, unbundled, bad), patch ID with or without revision (123456-78 or 123456), patch file (123456-78.zip) and file name (patchlist.txt).

The patch groups can be used to specify all missing patches (missing), all installed patches (installed), both installed and missing patches (all), all patches listed in patchdiag.xref (total), patches not associated with a software package (unbundled) or installed patches which are marked Bad (bad). By adding r, s or rs to any of the patch groups, only patches from the patch group which are marked Recommended, Security or either Recommended or Security are specified. Examples are missings for all missing Security patches, or allrs for all Recommended/Security patches. Patch groups can be shortened by using the first letter of the patch group plus optional r/s/rs (e.g. ms for missings or ars for allrs).

Patch IDs like 123456-78 or 123456 are used to specify single patches. If no revision (-78) is specified, patch dependencies will be resolved. If the name of a patch file like 123456-78.zip is specified, it has the same effect as using 123456-78. This can be useful to install a list of already downloaded patches with pca -i *.zip.

If a file name is specified, the file is read and its contents are added to the list of operands line-by-line. A file can contain other file names. If the file name is equal to a valid patch group name it will not be read.

The patch list can be limited to patches whose synopsis line contains a search pattern by using any patch group in combination with the --pattern=REGEX option. A command like pca -p mail shows any missing patch containing the mail keyword in its description. If the search pattern contains whitespace or special characters, enclose it in quotation marks: pca -p Studio -l total shows patches for all versions of Sun Studio. If the pattern starts with !, the patch list is limited to patches which do not match the pattern.

If no operands are specified, the missing operand is used.

CONFIGURATION

The behaviour of PCA can be configured by setting any option either in a configuration file, as an environment variable with the PCA_ prefix or on the command line. See OPTIONS for a complete list; only the long names can be used in configuration files and for environment variables.

At first, the configuration files are read. PCA reads pca.conf in the directory where PCA is installed, ../etc/pca.conf of the directory where it is installed, /etc/pca.conf, $HOME/.pca and pca.conf in the current directory, in this order. In proxy mode the files ../etc/pca-proxy.conf, /etc/pca-proxy.conf and pca-proxy.conf in the current directory are read instead. Options are set by specifying option=value in the file. Example: To set the path of the wget command, use wget=/opt/bin/wget. To enable debug output, use debug=1.

Then, all environment variables matching PCA_OPTION are read. Example: To set the patch download directory, set PCA_PATCHDIR to /some/dir/. To set the noheader option, set PCA_NOHEADER to 1.

At last, the command line options are read. Example: To set the location of the patch xref file, use -X /tmp or --xrefdir=/tmp. To set the option for safe patch installation, use -s or --safe.

All boolean options (i.e. those which do not take an argument) can be negated on the command line by specifying --no-option to override settings from configuration files. Version 2.32 or newer of the Getopt::Long module is required. Example: If noreboot=1 is set in pca.conf it can be overridden with --no-noreboot.

The operands option can only be used in configuration files and as an environment variable. It sets the default OPERANDS.

In a configuration file, everything after a # character is regarded as a comment and ignored.

PATCH DOWNLOAD AND INSTALLATION

The -d option downloads patches to the current directory, -i downloads and installs them. The download option can be used as a regular user. The external command wget is used for the actual download. If it can't be found in the default paths, set the wget option to contain the path to the wget command. The install option requires PCA to be run as root. It uses patchadd to install the patches. Using -I instead of -i pretends to install patches, but does not actually install any patch.

After the installation of each patch, a status line shows the current time, the time used to install the patch and the total run time. It also includes the current/total number of patches and counts for successful, skipped and failed patch installs.

The patches are downloaded from Oracle's patch download server. To download patches from Oracle, a My Oracle Support (MOS) Account is required. For most patches a Support Contract is required, too (see SUPPORT LEVELS for more information). Set the two options user and passwd to contain the MOS user name and password. If unset, PCA asks for MOS Account data interactively. If user is set, but passwd is not, PCA will ask for the password.

As PCA analyzes the information in the cross-reference file to resolve patch dependencies, it lists and installs patches in the correct order. Patches for the patch installation utilities will always be installed first to avoid issues with subsequent patches.

For some patches, a (reconfiguration) reboot is recommended or required after installation. The /reconfigure file is created as needed and a message is shown in the summary. When the install or pretend option is combined with the noreboot option, only patches which do not require a reboot are installed. This information is contained in the patch distribution file. Therefore, even if noreboot is specified, the patches are downloaded anyway; only the installation is skipped.

patchadd normally keeps a backup of all files it modifies. Using the --nobackup=ID option with PCA instructs patchadd to not keep backup copies of replaced files (see the -d option in patchadd's man page).

Sometimes a patch re-delivers and silently overwrites files which have been modified locally. PCA tries to overcome this issue with its safe patch installation mode. Before installing a patch, PCA checks all files listed in the patch README for local modifications. If any modified file is in danger of being overwritten, a warning is shown and the patch is skipped. Safe mode is off by default, and can be turned on by using -s or --safe in combination with -i (install patches) or -I (pretend to install patches). You must be root to use -s. Running pca -s -I is a safe way of identifying problematic patches without actually installing them.

In rare cases, patches modify or replace files without updating the checksum in the package database used by PCA. Installing a more recent revision of the same patch will fail although no local modifications have been made to a file. Patch installation can be forced by not using the safe option.

Running pca -si missingrs on a regular basis is enough to keep the system at the recommended patch level. This is quite comfortable and works without problems in many cases. As some patches require special handling, it's recommended to read the README of every patch before installation. PCA's -L option for HTML output and the --readme option to display patch READMEs are handy for that.

Sometimes installing a patch might fail because of inconsistencies in the patchdiag.xref file, the patch README and the information contained inside the patch. Often this gets fixed in a new version of patchdiag.xref or in a new revision of the patch. Either try again a few days later or take a look at the Notes section on the PCA web site, where some problematic patches are listed.

SUPPORT LEVELS

In order for a user to download a patch, the user must have a Support Level on their My Oracle Support (MOS) Account that matches the Support Level on the patch. A certain type of Support Contract includes one or more Support Levels.

To find out which Support Levels a User and a Patch have, follow the instructions in Knowledge Article ID 1269292.1 on MOS.

Possible Support Levels and Support Contract Coverage:

OS (Operating System)

Solaris patches and updates. Requires Premier Support for Operating Systems or Premier Support for Systems.

PUB (Public Patches)

Oracle Open Office/StarOffice and patch utilities. No Support Contract required.

SW (Software)

Existing Oracle software and Sun middleware. Requires Premier Support for Software.

FMW (Firmware)

Firmware, drivers, bios, system controller software, ALOM/ILOM, diagnostics. Requires Hardware Warranty or Premier Support for Systems.

VIN (Vintage Solaris)

Solaris 8. Requires Oracle Solaris Extended Support.

EXS (Extended Support)

EOL Oracle Software. Requires Lifetime Support.

LOCAL PATCH SERVER

On a local network, it might be useful to have a local patch server. There are two ways to set up a local patch server for PCA, using the patchurl and xrefurl options. With these options, alternative locations for patches, patch READMEs or patchdiag.xref can be specified. Multiple URLs and the special keyword oracle can be used to make PCA check various local or remote resources and Oracle's server. Like this, you can create patch repositories with already downloaded patches and let PCA always look there before trying to access the Oracle server.

Create the local patch repository by copying downloaded patch files (e.g. 123456-78.zip), patch READMEs (e.g. README.123456-78) and/or patchdiag.xref to a directory which is available via NFS or on a local web server. Point PCA at it by setting the patchurl and/or xrefurl options to the URL (e.g. "file:/pca/ oracle" or "http://www.my.org/patches/").

The more advanced method uses PCA to work as a local caching proxy for itself. Create a directory in the document root of the local web server, and link or copy pca there under the name pca-proxy.cgi. Make sure that the directory (or the directories specified with the xrefdir and patchdir options) are owned and writable by the user under which CGI scripts run, as patches, patch READMEs and patchdiag.xref will be stored there. Verify that the web server is configured to run CGI scripts (for apache, check the ExecCGI and AddHandler options in httpd.conf). Create a pca.conf file in the same directory to specify My Oracle Support Account data. On the client, point PCA at the caching proxy by setting the patchurl and xrefurl options to e.g. http://www.my.org/patches/pca-proxy.cgi.

In proxy mode, if a patch or patch README exists in the local cache directory, it is delivered immediately. If it doesn't, the file is downloaded from Oracle's patch server, put into the cache, and delivered. For patchdiag.xref, pca-proxy.cgi will always make sure that it has a recent version of this file and deliver it from its cache.

With a local caching proxy in place, client systems running PCA and using this proxy do not need direct access to the Internet at all.

Example setup of a local caching proxy on a vanilla Solaris 10 system:

  # mkdir /var/tmp/pca
  # chown webservd:webservd /var/tmp/pca

This is where patches, READMEs and patchdiag.xref will be stored by the proxy. Now put the CGI script in place and create a configuration file:

  # cd /var/apache2/cgi-bin
  # cp /usr/local/bin/pca pca-proxy.cgi
  # chmod 555 pca-proxy.cgi
  # cat > /etc/pca-proxy.conf
  xrefdir=/var/tmp/pca
  patchdir=/var/tmp/pca
  user=XXXXXX
  passwd=YYYYYY
  ^D
  # chown webservd:webservd /etc/pca-proxy.conf
  # chmod 600 /etc/pca-proxy.conf

If the apache2 server is not running yet, create /etc/apache2/httpd.conf and enable the server with svcadm:

  # cp /etc/apache2/httpd.conf-example /etc/apache2/httpd.conf
  # svcadm enable svc:/network/http:apache2

Test the caching proxy on a client:

  ./pca -X . --xrefurl=http://server.domain/cgi-bin/pca-proxy.cgi
  --patchurl=http://server.domain/cgi-bin/pca-proxy.cgi -d 126306-01

The patchdiag.xref and 126301-01.zip will be downloaded by the proxy and stored in /var/tmp/pca/ on the server, and both files will be delivered to the client. If it doesn't work, add debug=1 to the pca.conf file and look at /var/tmp/pca-proxy-debug.txt and /var/apache2/logs/ for details.

When downloading large patches through the proxy, you must ensure that the web server does not kill pca-proxy.cgi before it has completed the download from Oracle's patch server. Apache has a Timeout option with a default value of 300 seconds. Raise that to 1800 seconds to avoid problems.

For large setups, you can build a cascade of local caching proxies by pointing one proxy at another proxy by setting xrefurl and patchurl to point at the master proxy in the slave proxies' pca.conf.

As PCA uses the wget command to download patches from the patch server, make sure that any specially required option is set in /etc/wgetrc or $HOME/.wgetrc. Example: When running the local patch server on a HTTPS server with a self-signed certificate, check-certificate=off should be specified in wgetrc on the client.

UNBUNDLED PATCHES

Usually a patch is related to one or more software packages installed on a system. Apart from that, there are unbundled patches. They provide firmware updates for machines, disks, or tape drives and fixes for software which doesn't come in package format. Currently there is no way to automatically determine if such patches actually apply to a system.

The unbundled operand specifies this type of patches. At first, pca -l unbundled will show a long list of patches. To reduce this list to the interesting ones, unnecessary patches can be ignored by using the ignore option in a PCA configuration file. For patches you are absolutely not interested in, use an entry like ignore=123456 in the configuration file; this patch will never be shown again, even if a newer revision of the patch appears. Patches that are installed in their current revision should be put with this revision into the configuration file (e.g. ignore=123456-78). The patch will show up again when a newer revision is released.

Example: Patch 106121-18 contains the most recent PROM firmware for Ultra 5/10 workstations. As it's installed on all systems, I put ignore=106121-18 into the configuration file. When a new revision of the patch is released, it will show up in pca -l unbundled again. Patch 118324 is the PROM firmware patch for the Sun Fire V440. As I don't have such a machine, I put ignore=118324 into the configuration file to ignore this patch completely.

All that PCA can do is to notify of new unbundled patches or patch revisions. It's on you to decide whether a patch is needed by checking its README file, and to install it by following the instructions in the README. Unbundled patches cannot be installed by patchadd or PCA.

CREATING PATCH REPORTS FOR REMOTE MACHINES

PCA can create a patch report or download patches for a system which cannot run PCA directly, like stripped-down systems without perl or an Internet connection. On such systems, run:

  uname -a > uname.out
  showrev -p > showrev.out
  pkginfo -x > pkginfo.out

On systems with a minimal core installation of Solaris, the showrev command might not be available. Use patchadd -p > showrev.out instead.

Copy the resulting *.out files to a system where PCA is installed. Use the -f DIR or --fromfiles=DIR option to point PCA at the location of the input files. The argument to -f can be a directory or a file name prefix like myhost_. This allows collecting *.out files for multiple systems and telling PCA which ones to read.

If Sun Explorer is used to collect information about Sun systems, a directory containing Sun Explorer output can be used as the argument to -f as well.

Other options can be used in combination with -f. Example: pca -f . -d missing downloads all missing patches for the remote system.

LIVE UPGRADE

PCA can be used in combination with Live Upgrade to analyze or install patches in an inactive boot environment. Use lumount to mount the BE and PCA's --root=DIR option to set the alternative root directory:

  lumount BE_name
  pca --root=/.alt.BE_name --install
  luumount BE_name

When you're done patching, activate the new BE and reboot with init 6.

PCA always installs the patch for the patch installation utilities first to avoid possible bugs in patchadd. When patching an inactive BE, this patch should be installed manually to the active BE, as its patch installation utilities are used even when root=DIR is set.

ZONES

PCA can be run both in the global zone or any non-global zone. Patches installed in the global zone are usually installed in all non-global zones, too. It's recommended to install patches in the global zone first, and then run PCA in all non-global zones to check for additionally needed patches. This is necessary if packages have been added to or removed from just the global or any non-global zone.

When PCA is run with the -G option, this option is handed through to patchadd, which will install patches in the current zone only. See the man page for patchadd for further details.

THREADS

If PCA is run with the --threads=NUM option, in conjunction with the download -d or install -i options, PCA will begin downloading multiple patches in parallel, up to NUM patches at once. Patches will still be installed one at a time, in the appropriate order.

The perl version used to run PCA must support threading, otherwise requests to use threading will be silently ignored. The /usr/bin/perl which comes with Solaris and perl binaries compiled with the default settings do not support threading. In that case, the output of --help will indicate that threads have been disabled.

UPDATE PCA

Changes to the patch infrastructure by Oracle and problems with single patches often make updates to PCA necessary. To ease that procedure, the update=TYPE option can be used. The default is type never - PCA will never check for updates. Use the check type to contact the PCA webpage and check for available updates. Using now will not only check, but also download and install the updated version of PCA.

With auto, PCA will check for updates automatically once per day, keeping itself up to date without user intervention. Unlike check and now which are for interactive usage, this type is best used in a configuration file.

The default URL to check for updates is http://www.par.univie.ac.at/solaris/pca/stable/ (official release). It can be set with the pcaurl=URL option. Set it to http://www.par.univie.ac.at/solaris/pca/develop/ to check for and update to new development versions of PCA. You can set pcaurl to point at a local URL to distribute whatever version in your local network. If set to point at a local caching proxy, the proxy will check for updates automatically, keep a local copy of the pca script in patchdir and deliver it to the client.

Set update=auto in the configuration file for PCA in proxy mode (pca-proxy.cgi) to make it keep itself up-to-date.

JUMPSTART

You can use PCA to install patches in the finish script of a jumpstart install server. Perl is included in the OS image which is booted over the network for installation starting with Solaris 8. As the machine will probably not have an Internet connection during installation, you can either pre-download all necessary patches into a directory accessible via NFS, or set up a local caching proxy. If you use any http or ftp url for xrefurl or patchurl, you must put a copy of wget into the directory that contains your finish script and PCA, and use the wget option to point PCA at it.

Set patchdir and xrefdir (unless you use nocheckxref) to /tmp to avoid problems with non-writable directories. As the OS which gets installed during jumpstart is mounted at /a, use the root option to instruct PCA to install patches there.

EXAMPLES

List all missing patches. This is the same as running pca without any arguments:

  pca -l missing

List all installed security patches:

  pca -l installeds

Display the README for the current revision of patch 116532:

  pca --readme 116532

Show all installed patches which are marked Bad. You should read the patch README to find out how to handle a specific bad patch:

  pca -l bad

Download multiple explicitly specified patches, asking for My Oracle Support Account data when needed:

  pca -d 121308-02 122032

Download and install all missing patches which do not require to reboot the system in safe mode:

  pca --noreboot --safe --install

Download all missing patches for a remote system. Output from uname -a, showrev -p and pkginfo -x has been saved to /tmp/myhost_uname.out etc. before:

  pca -f /tmp/myhost_ -d missing

Check for a new version of PCA and install it:

  pca --update now

A sample configuration file:

  # My Oracle Support Account
  user=myuser@mydomain.org
  passwd=secret
  # Try local patch repositories before the Oracle server
  patchurl=file:/patches http://www.my.org/patches/ oracle
  syslog=user
  safe=1

A sample configuration file for a client of a PCA proxy:

  # Get everything from the proxy
  patchurl=http://www.my.org/patches/pca-proxy.cgi
  xrefurl=http://www.my.org/patches/pca-proxy.cgi

ENVIRONMENT VARIABLES

All environment variables with the PCA_ prefix are evaluated as options; see CONFIGURATION for details. Furthermore, these environment variables are used by PCA:

PAGER

Path to the command which is used to display patch README files

TMPDIR

During patch installation, patches are extracted under this directory

DOWNLOAD ERRORS

If downloads of patches, patch READMEs or the patchdiag.xref file fail, the displayed error might help to diagnose the problem:

Service Error (403)

The user/passwd combination you provided is not correct.

You are not entitled to retrieve this content (403)

The user/passwd combination is correct, but the MOS Account does not have the Support Level required for the requested file. See SUPPORT LEVELS for more information.

Not Found (404)

The requested file does not exist on Oracle's patch server.

Server Error, Service Unavailable, Gateway Timeout (5xx)

The Oracle patch server is in a bad state. Retry later.

EXIT STATUS

The following exit values are returned:

  0  No error

  1  Unknown error

  2  Usage error

  3  Reboot required to continue patch installation

  4  Reboot required

  5  Reboot recommended

AUTHORS

Martin Paul <martin.paul@univie.ac.at>

Thanks to everybody who contributed code or provided feedback:

Andrew Brooks, Bruce Riddle, Damian Hole, Peter Van Eynde, Richard Whelan, Eugene MacDougal, Peter Schmitz, Fredrik Lundholm, Dan W. Early, Markus Reger, Constantijn Sikkel, Stephen P. Potter, Fletcher Cocquyt, Timothy J. Howard, Thomas Bluhm, Frank Doeschner, Loris Serena, Marion Biallowons, Ricky Chew, Martin R. Korczak, Imad Soltani, Scott Lucas, Anders Grund, Bernd Senf, Chris Zappala, Ashley Krelle, Mike Patnode, Mats Larsson, Thomas Maier-Komor, Willi Burmeister, Stefaan A. Eeckels, Ian Collins, Leptonux, Joseph Millman, Guenter Zaehle, Frank Fejes, Mark Jeffery, Alberto da Silva, Mauricio Tavares, Kurt Rabitsch, Jeff Wieland, Frank Bertels, Steve Meier, Dan Lorenzini, Gerard Henry, Laurent Blume, Sean Berry, George Moberly, Erik Nordenberg, Mark Ashley, Jim Prescott, Christian Pelissier, Hugues Sapin, Colin A. White, Dale T. Long, Christophe Kalt, Bruno Delbono, Nan Liu, Frank Cusack, Marlon Sanchez-Nunez, Jois Diwakar, Toni Viemero, Jens Larsson, Gordon D. Gregory, Luis Catacora, Erik Larson, Tim Longo, Mike Borkowski, Nicolas Goy, William Bonnet, Dave Love, Thomas Brandstetter, Daniel Kunkel, Gregor Longariva, Miroslav Zubcic, Tim Bradshaw, Chris Quenelle, Christopher Odenbach, Andy Fiddaman, Peter Sundstrom, Andreas F. Borchert, Jonah Simandjuntak, Damian Lilley, Chris Ridd, Albert Lee, James Lick, John Douglass, Andres A. Flores Concepcion, Chris Reece, Toni Viemero, Timothy Meader, John D. Groenveld, Ceri Davies, Martin Wismer, Laszlo Kiss, Mike Moya, Leon Koll, Shawn Boots, Mike Wallace, Robert P. McGraw, Peter Arnold, Matt Kolb, Mike Shackelford, John Dzubera, Donald Teed, Asif Iqbal, Stephen Nash, Jason Loretz, Bryan Howard, Roman, Jonathan Hoefker, Daniel Trinkle, Ron Halstead, Rob Fisher, Chris Coffey, Travis Freeland, Hans-Werner Jouy, Gary Mills, Craig Bell, Mick Russom, Brian King, Ashley Rowland, Guillermo Castellini, Bryan D. Moorehead, Mark Scheufele, Corey Becker, David Robson, Kevin Maguire, Mike Wallace, Marcos Della, Frank Sperber, Horst Scheuermann, Adrian Ulrich, Steve Fox, David Collodel, Jeremiah Johnson, Erik Schubert, David Sullivan, Tom Francen, Matthew Scala, Richard Mayebo, Gerald Sinkiewicz, David Montag, Steve Forman, Jeffrey King, Gerry Van Trieste, Chris Denneen, Greg Barry, Paul Armstrong, Andreas Fineske, Eric Kissinger, Torsten Peter, Yevgeniy Averin, Sean Walmsley, Alexander Skwar, Jeffrey King, Jones Olatunji, Richard Skelton, Kjetil Torgrim Homme, Brian McNamara, Gerry Sinkiewicz, Kazuyuki Sato, Mayuresh Kshirsagar, Mauro Mozzarelli, Judy Illeman Gaukel, Petri Kunnari, William Pool, Steven Faulconer, Rono Jacob, Will Green, Martial Rioux, Zafar Pravaiz, Romeo Theriault, Fredrich Maney, Ben Szoko, Pietari Hyvarinen, Roman Pestka, Juergen Mengeling, David S. Bryant, Maciek S., Alexander Sverdlov, David Coronel, David Groce, Jeff Woolsey, Thomas Marshall, Allen Eastwood, Mike Busse, Martin Bellenberg, Dennis Clarke, Dominique Frise, Mark Hopkins, Enda O'Connor, Victor Feng, Peter Englmaier, Paul B. Henson, Gerry Haskins, Jeff A. Earickson, Stuart Anderson, Dagobert Michelsen, Simon Bellwood, Ateeq Altaf, Andrew Berry, Julian Davies, Con Petsoglou, Uwe Wolfram, Micah Cowan, Dan Shaw, Paul Moore, Neal A. Lucier, Eric Bourgi, Sergiusz Pawlowicz, Paul Van Bommel, Matt Banks, Ray Cromwell, Jan Holzhueter, Liam Carey, Alex Docauer, Christopher S. Chan, Philip Kime, Michael Schmarck, Kevin L. Bliss, Thomas Bleek, Albert White, Ron Helzer, Sergei Haramundanis, Steven M. Christensen, Felix Schattschneider, Rajiv G Gunja, Jeremy Simpson, Jesse Caldwell, Amy Rich, Jens Elkner, Stephen Matich, Justus J. Addiss, Fred Chagnon, David French, Don O'Malley, Stuart F. Biggar, Diana Stockdale, Randal T. Rioux, Todd Koeckeritz, Matthew Braun, Shaimon Luke, Norman Lyon, Sebastian Kayser, Paul A. Zakas, Glenn Satchell, Ben Taylor, Brian Geary, Drazen Kacar, Edwin Schwab, Shahab Khan, Thots Soppannavar, Beth Lancaster, Michael Jackson, Daniel Pecka, Dirk Lemoisne, Scott L Nishimura, Mike Brown, Michele Vecchiato, Eugene Olshenbaum, Benny Kleykens, Colin Daly, Rod Holmes, Jeff Blaine, Tim Frost, Steven M. Falconer, Thomas Gouverneur, Marcel Hofstetter, Jeremy Daniel.

MAILING LISTS

Two mailing lists are available:

pca-news

This is a one-way list for announcements of new versions and news. To join, send an empty message to <pca-news-join@lists.univie.ac.at>.

pca

This is a discussion and support list. Messages from pca-news will be posted to this list as well. Only members are allowed to post to the list. To join, send an empty message to <pca-join@lists.univie.ac.at>. To post to the list, send your message to <pca@lists.univie.ac.at>.

SEE ALSO

PCA web site:

http://www.par.univie.ac.at/solaris/pca/