.TH "pca" "8" "Nov 28, 2006" "" ""
.SH NAME
pca - analyze, download and install patches for Sun Solaris
.SH SYNOPSIS
pca [OPTION] .. [OPERAND] ..
.SH DESCRIPTION
pca is a perl script which generates lists of installed and missing
patches for Sun 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.
.PP
The output of the pkginfo, showrev and uname commands is used to gather
information about the system. Sun 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/.
If the file
exists and is not writable, pca uses it and won't try to update it.
.SH SAMPLE OUTPUT
.PP
Here's some sample output from \fIpca -l all\fR, which shows a list
of all installed and missing patches:
.PP
.nf
.ft CO
Host: myhost (SunOS 5.9/Generic_117171-09/sparc/sun4u)

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
.ft
.fi
.PP
The first column (\fIPatch\fR) contains the patch number, followed by the
installed revision (\fIIR\fR) and the current revision 
(\fICR\fR), 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 \fIRSB\fR column lists
the Recommended/Security/Bad state of the patch. \fIAge\fR shows the
number of days since the patch was released, and
\fISynopsis\fR shows a short description of the patch.
.PP
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.
.PP
Patches 113039, 113040 and 117114 are not installed
at all, and 113040 is marked Recommended.
.PP
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. 
.PP
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.
.SH OPTIONS
.TP
.B -l, --list
List patches. See OPERANDS on how to specify which patches
are listed.
.TP
.B -L, --listhtml
Like \fI-l\fR, but generates output in HTML format, including
links to patch READMEs and downloads.
.TP
.B -d, --download
Download patches. See OPERANDS on how to specify which patches
are downloaded. Patches are placed in the current directory or
in \fIpatchdir\fR, if set.
.TP
.B -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 \fI--download\fR
is used, too.
.TP
.B -I, --pretend
Like \fI-i\fR, but only pretend to install patches. Can be used
to find out if any of the patches require a reboot.
.TP
.B -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 Sun.
.TP
.B -x, --getxref
Download most recent patch cross-reference file.
If the file does not exist or is older than 24 hours, pca tries to
download it on its own before anything else.
.TP
.B -X, --xrefdir=DIR
Set location of the cross-reference file. The default is
\fI/var/tmp\fR. 
By default, patchdiag.xref is writable for all users. If the \fIxrefown\fR
option is set, or the \fIxrefdir\fR option contains \fI/home\fR,
the cross reference file will be
writable by the current user only.
.TP
.B -y, --nocheckxref
Do not check for updated patch cross-reference file. Use this option
to maintain a global baseline patch set.
.TP
.B --xrefown
If set, patchdiag.xref will be writable for the current
user only.
.TP
.B --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.
.TP
.B -P, --patchdir=DIR
Set directory to which patches are downloaded. Only use
absolute path names. The default is
the current working directory.
.TP
.B -a, --askauth
Ask for Sun Online Account data interactively.
.TP
.B --user=USER
Login name for Sun Online Account authentication.
.TP
.B --passwd=PASS
Password for Sun Online Account authentication.
.TP
.B --localurl=URL
If set, pca tries to download patches and READMEs from
this URL first. Any URL starting with file:/, ftp://, http:// or
https:// can be used. See LOCAL PATCH SERVER for more information.
.TP
.B -p, --pattern=REGEX
List only patches whose synopsis matches the search pattern
REGEX. This can be a simple string like \fImail\fR or a regular
expression like \fI"[kK]ernel"\fR.
.TP
.B -n, --noreboot
Install only patches that don't require a reboot after 
installation.
.TP
.B --syslog=TYPE
Syslog facility (eg. user or local0) to log successful patch
installs to.
.TP
.B -k, --nobackup
Make patchadd not back up files when installing patches. This
works by running patchadd with its \fI-d\fR option. Patches can not be
backed out if this option is used.
.TP
.B -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.
.TP
.B -G, --currentzone
Make patchadd modify packages in the current zone only. This
works by running patchadd with its \fI-G\fR option. This option works
on Solaris 10 or newer only.
.TP
.B --patchadd=FILE
Path to an alternative patchadd command.
.TP
.B -H, --noheader
Don't display descriptive headers. Useful if re-using
pca's output in own scripts.
.TP
.B -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.
.TP
.B -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. This option works on 
Solaris 9 or newer only.
.TP
.B --wget=FILE
Path to the wget command.
.TP
.B -V, --debug
Show debug output. This includes output generated by patchadd.
.TP
.B -h, --help
Print help on command line options.
.TP
.B -v, --version
Print version information.
.PP
If no option is specified, the \fI-l\fR option to list patches is used.
.SH OPERANDS
The operands determine which patches are listed (\fI-l\fR),
downloaded (\fI-d\fR), installed (\fI-i\fR) or whose READMEs
are displayed (\fI-r\fR). Multiple operands
can be specified. Supported operands
are \fIpatch group\fR (missing, installed, all, total, unbundled, bad),
\fIpatch ID\fR with or without revision
(123456-78 or 123456), \fIpatch file\fR (123456-78.zip) and
\fIfile name\fR (patchlist.txt).
.PP
The patch groups can be used to specify all missing patches (\fImissing\fR),
all installed patches (\fIinstalled\fR), both installed and missing patches
(\fIall\fR), all patches listed in patchdiag.xref (\fItotal\fR),
patches not associated with a software package (\fIunbundled\fR)
or installed patches which are marked Bad (\fIbad\fR).
By adding \fIr\fR, \fIs\fR or \fIrs\fR 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 \fImissings\fR for all missing Security patches, or
\fIallrs\fR for all Recommended/Security patches.
Patch groups can be shortened as long as they are
unique (e.g. \fIms\fR for missings or \fIars\fR for allrs).
.PP
Patch IDs like \fI123456-78\fR or \fI123456\fR are used to specify
single patches. If the name of a patch file like
\fI123456-78.zip\fR is specified, it has the same effect as using
\fI123456-78\fR. This can be useful to install a list of already
downloaded patches with \fIpca -i *.zip\fR.
.PP
If a \fIfile name\fR is specified, the file is read and its
contents are added to the list of operands line-by-line.
.PP
The patch list can be limited to patches whose synopsis line contains
a search pattern by using any patch group in combination with the
\fI--pattern=REGEX\fR option.
A command like \fIpca -p mail\fR shows any missing patch containing
the \fImail\fR keyword in its description.
If the search pattern contains whitespace or special characters, enclose
it in quotation marks:
\fIpca -p "Sun Studio" -l total\fR shows patches for all versions of
Sun Studio.
.PP
If no operands are specified, the \fImissing\fR operand is used.
.SH CONFIGURATION
The behaviour of pca can be configured by setting any option either
in a configuration file, as an environment variable with the \fIPCA_\fR
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.
.PP
At first, the configuration files are read. pca reads \fIpca.conf\fR
in the directory where pca is installed, \fI../etc/pca.conf\fR of the
directory where it is installed, \fI/etc/pca.conf\fR, \fI$HOME/.pca\fR
and \fIpca.conf\fR in the current
directory, in this order.
Options are set by specifying 
\fIoption=value\fR in the file. Example: To set the path of the wget command,
use \fIwget=/opt/bin/wget\fR. To enable debug output, use
\fIdebug=1\fR.
.PP
Then, all environment variables matching \fIPCA_OPTION\fR are
read. Example:
To set the patch download directory, set \fIPCA_PATCHDIR\fR to 
\fI/some/dir/\fR. To set the \fInoheader\fR option, set \fIPCA_NOHEADER\fR
to \fI1\fR.
.PP
At last, the command line options are read. Example: To set the location
of the patch xref file, use \fI-X /tmp\fR or \fI--xrefdir=/tmp\fR.
To set the option for safe patch installation, use \fI-s\fR or \fI--safe\fR.
.PP
The \fIoperands\fR option can only be used in configuration files and as
an environment variable. It sets the default OPERANDS.
.PP
The configuration files can be used to modify pca's behaviour for
certain patches. A line like \fI123456 ignore\fR instructs pca to ignore
any revision of patch 123456, while \fI123456-78 ignore\fR tells pca to
ignore
only revision 78 of patch 123456; newer revisions will not be ignored.
Ignored patches are excluded from pca's output. A patch can be
marked as Recommended or Security by specifying \fI123456 +rec\fR or
\fI123456 +sec\fR. It will be marked with a lowercase \fIr\fR or
\fIs\fR in pca's output.
.PP
In a configuration file, everything after a \fI#\fR character is
regarded as a comment and ignored.
.PP
.SH PATCH DOWNLOAD AND INSTALLATION
The \fI-d\fR option downloads patches to the current directory, \fI-i\fR
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 \fIwget\fR option to contain the path to the
wget command.
The install option
requires pca to be run as root. It uses \fIpatchadd\fR to
install the patches.
Using \fI-I\fR instead of \fI-i\fR
pretends to install patches, but does not actually install any patch.
.PP
The install options can be combined with the \fInoreboot\fR option,
to install only patches which do not require a reboot or reconfiguration
after patch installation. As this requires looking
at the patch README, the patches are downloaded anyway; only the
installation is skipped.
\fIpatchadd\fR normally keeps a backup of all files it modifies.
Using the \fI--nobackup\fR option with pca instructs
\fIpatchadd\fR
to not keep backup copies of replaced files (see the -d option in
patchadd's man page).
.PP
The patches are downloaded from Sun's 
patch download server. While all patches for Solaris versions up to Solaris 9
can be downloaded freely, you need a Sun Online Account to 
get access to all Solaris 10 patches.
Set the two options \fIuser\fR and \fIpasswd\fR to contain
the Sun Online Account user name and password. If \fIuser\fR is set, but
\fIpasswd\fR is not, pca will ask for the password.
Alternatively, when run with the \fIaskauth\fR option, pca
asks for Sun Online Account data interactively.
.PP
pca analyzes the information in the cross-reference file to resolve 
patch dependencies, and lists and installs patches in the correct order.
.PP
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 displayed and the patch is skipped.
Safe mode is off by default, and can be turned on by using \fI-s\fR or
\fI--safe\fR in
combination with \fI-i\fR (install patches) or \fI-I\fR (pretend to install
patches). You must be root to use \fI-s\fR. Running \fIpca -s -I\fR is a
safe way of identifying problematic patches without actually installing them.
.PP
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 \fIsafe\fR option.
.PP
Running \fIpca -si missingrs\fR 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 \fI-L\fR option for HTML output and the
\fI--readme\fR option to display patch READMEs are handy for that. 
.PP
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 
\fINotes\fR section on the pca web site, where some problematic
patches are listed.
.SH 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 
\fIlocalurl\fR option. The local URL is always accessed first when
downloading patches or patch READMEs. Only if a file can't be found 
there, pca falls back to Sun's patch server. Like this, patches
are downloaded from Sun's patch server only once when installing
patches on multiple machines. If the patchdiag.xref file exists
on the local patch server, it will be downloaded from localurl, too.
It will only be downloaded from Sun's patch server if it doesn't
exist on localurl.
.PP
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 \fIlocalurl\fR option to the URL
(e.g. file:/patches/ or http://www.my.org/patches/).
.PP
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 \fIpca-proxy.cgi\fR. The directory
must be owned by the user under which CGI scripts run, as patches,
patch READMEs and patchdiag.xref will be stored there. If necessary,
create a pca.conf
file in the same directory to specify Sun Online Account data. Point
pca at the caching proxy by setting the \fIlocalurl\fR option to e.g.
http://www.my.org/patches/pca-proxy.cgi.
.PP
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 Sun's
patch server, put into the cache, and delivered. For patchdiag.xref,
pca-proxy.cgi will always make sure that it has the most recent
version of this file and deliver it from its cache.
.PP
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.
.PP
.SH 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.
.PP
The \fIunbundled\fR operand specifies these type of patches.
At first, \fIpca -l unbundled\fR will show a long list of patches.
To reduce this list
to the interesting ones, unnecessary patches can be ignored by putting
them into a pca configuration file.
For patches you are absolutely not interested in, use an
entry like \fI123456 ignore\fR 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. \fI123456-78 ignore\fR).
The patch will show up again when a newer revision is released.
.PP
Example: Patch 106121-18 contains the most recent PROM firmware for
Ultra 5/10 workstations. As it's installed on all systems, I put
\fI106121-18 ignore\fR into the configuration file.
When a new revision of the patch
is released, it will show up in \fIpca -l unbundled\fR again.
Patch 118324 is the PROM firmware patch for the Sun Fire V440. As I 
don't have such a machine, I put \fI118324 ignore\fR into the 
configuration file to ignore this patch completely.
.PP
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.
.SH 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:
.PP
.nf
.ft CO
  uname -a > uname.out
  showrev -p > showrev.out
  pkginfo -x > pkginfo.out
.ft
.fi
.PP
On systems with a minimal core installation of Solaris, the \fIshowrev\fR
command might not be available. Use \fIpatchadd -p > showrev.out\fR
in that case.
.PP
Copy the resulting \fI*.out\fR files to a system where pca is 
installed. Use the \fI-f DIR\fR or \fI--fromfiles=DIR\fR option to
point pca at the location of the input files.
The argument to \fI-f\fR can be a directory
or a file name prefix like \fImyhost_\fR.
This allows collecting \fI*.out\fR files for multiple systems
and telling pca which ones to read.
.PP
If Sun Explorer is used to collect information about Sun systems, a
directory containing Sun Explorer output can be used as the argument
to \fI-f\fR as well.
.PP
Other options can be used in combination
with \fI-f\fR. Example: \fIpca -f . -d missing\fR downloads all missing
patches for the remote system.
.SH 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.
.PP
When pca is run with the \fI-G\fR 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.
.SH EXAMPLES
List all missing patches. This is
the same as running pca without any arguments:
.PP
.nf
.ft CO
  pca -l missing
.ft
.fi
.PP
List all installed security patches:
.PP
.nf
.ft CO
  pca -l installeds
.ft
.fi
.PP
Display the README for the current revision of patch 116532:
.PP
.nf
.ft CO
  pca --readme 116532
.ft
.fi
.PP
Show all installed patches which are marked Bad. You should read the
patch README to find out how to handle a specific bad patch:
.PP
.nf
.ft CO
  pca -l bad
.ft
.fi
.PP
Download multiple explicitly specified patches:
.PP
.nf
.ft CO
  pca -d 121308-02 122032
.ft
.fi
.PP
Download and install all missing patches which do not require to reboot
the system in safe mode:
.PP
.nf
.ft CO
  pca --noreboot --safe --install
.ft
.fi
.PP
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:
.PP
.nf
.ft CO
  pca -f /tmp/myhost_ -d missing
.ft
.fi
.PP
A sample configuration file:
.PP
.nf
.ft CO
  # Sun Online Account
  user=myuser
  passwd=secret
  # Other
  localurl=http://www.my.org/patches/pca-proxy.cgi
  syslog=user
  safe=1
.ft
.fi
.PP
.SH ENVIRONMENT VARIABLES
All environment variables with the \fIPCA_\fR prefix are evaluated
as options; see CONFIGURATION for details. Furthermore, these environment
variables are used by pca:
.TP
.B PAGER
Path to the command which is used to display patch README
files
.TP
.B TMPDIR
During patch installation, patches are extracted under this
directory

.SH AUTHORS
Martin Paul <martin@par.univie.ac.at>
.PP
Thanks to everybody who contributed code or provided feedback:
.PP
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.
.SH MAILING LIST
There is a mailing list which is used solely for announcements about
pca. To be added to the list, send a short note to
<martin@par.univie.ac.at>.
.SH SEE ALSO
.TP
.B pca web site:
http://www.par.univie.ac.at/solaris/pca/