swa-report(1M)swa-report(1M)NAME
- Report software and security issues, and resolutions.
SYNOPSIS
analyzer] stdout_report_type] inventory_source]
DESCRIPTION
The command inventories and analyzes a host system or some types of
depots against a catalog of HP software and known issues (security and
other defects). HP-UX Software Assistant (SWA) then generates three
results:
· a comprehensive HTML report saved in a file
· a text report printed to stdout (report types include "action",
"issue", or "detail")
· an analysis results file that the command uses
Each of these results indicates the issues found and/or new software
and fixes that Hewlett Packard recommends.
NOTE: The format of these results is subject to change in a subsequent
release of SWA.
The analysis that performs relies on the integrity of the inventory to
determine the appropriate patches to install on the system. It is
important that all protocols used to transmit the inventory data are
integrity protected and that the host used to generate the inventory
data is accurately represented. For example, use of for gathering an
inventory of a remote system uses a clear-text, unauthenticated proto‐
col that does not protect the integrity of the data. Using Secure
Shell to gather an inventory of a remote system uses an integrity pro‐
tected (and encrypted) protocol. Even when using Secure Shell, the
analysis still relies on the source of the data (the remote host) to
accurately represent the software contents installed on that system.
recognizes the following options:
Specifies an analyzer to use. Each analyzer represents a dif‐
ferent type of
analysis that can perform. You may specify multiple
options. The supported analyzers follow:
- patches that fix critical problems
- patches with critical warnings
- patches with warnings (a superset of PCW)
- latest quality pack
- security bulletins that may apply
- include patch or recommended successor
- include specific patch. (Note: use of CHAIN is gen‐
erally preferred.)
If this option is not specified, the "QPK", "SEC", and
"PCW" analyzers are used.
Specifies the type of report to display to stdout. Legal values
are:
- (Default) Summary of recommended actions
- Summary of identified issues
- Recommended actions with issue justification
- Comprehensive report in html format
- No report is generated on stdout
Specify one system or depot
to be inventoried, or an
existing local inventory file
to be
analyzed and reported on. If this option is not
specified, the local system is inventoried, ana‐
lyzed and reported on. Supports Secure Shell
(recommended for remote connections) and swlist
(legacy) protocols for gathering inventory infor‐
mation. See the extended option for more details.
The verbosity level is decreased by one for each instance
is specified. (See also the option.)
The verbosity level is increased by one for each instance
is specified. (See also the option.)
Displays general usage.
Describes the legal values for this option. If <option>
is
all possible extended options are listed for the
specified major mode. If no mode is given, all
extended options are listed.
Sets the extended option to a value. See Extended
Options definitions below.
Describe the legal values for this option.
Gets the extended options from
option_file. (See the file for a description and
examples of syntax for this file).
The extended options may be specified in different ways: on the
command line using the option, in an option file specified using
the option, or in one of the configuration files (system wide)
or (user-specific). The file provides example syntax for a con‐
figuration or file. If the same option is given in multiple
locations, the following order is prioritized from highest to
lowest:
1. Options specified on the command line
2. Options specified within an option file
3. Proxy environment variables (See Environment Vari‐
able section.)
4. Options specified within the $HOME/.swa.conf file
5. Options specified within the /etc/opt/swa/swa.conf
file
6. Default value, specified in the descriptions of
each option below in format
Note: If the same option or extended option is given multiple
times in the same location, the last takes effect. If the
option has a single letter equivalent (e.g., and ) and both are
used on the command line, the single letter option generally
takes precedence. If the single letter option affects an
extended option that takes a list of arguments, specifying the
single letter option multiple times will append to the list.
recognizes the following (extended) options, which are shown
with their default values:
Usage: Basic
The file containing the raw analysis results, including a
list of software that should be downloaded from Hewlett-
Packard in order to address the issues found by the anal‐
ysis. Use this option to save the results from a spe‐
cific analysis, and later reuse those results in order to
download the corresponding software from HP. If you do
not use the default location when the analysis file is
created (e.g., creates this file), be sure to specify
that location when the analysis file is later used (e.g.,
uses this file).
Possible values include any absolute or relative pathname
with appropriate permissions.
The use of ${user_dir} at the beginning of this option
value is substituted with the value of the option (which
defaults to $HOME.swa).
Usage: Basic
Specifies a space-separated list (appropriately quoted
for your shell if applicable) of analyzers to be used.
Each analyzer represents a different type of analysis
that SWA can perform. The supported analyzers follow in
two lists (generic and specific).
Generic analyzers:
- patches that fix critical problems
- patches with critical warnings
- patches with warnings (a superset of PCW)
- latest quality pack
- security bulletins that may apply
Specific analyzers:
- Include patch or recommended successor.
- Include specific patch. Using CHAIN is generally pre‐
ferred.
- Include specific issue.
Note: This option is equivalent to -a but is suitable for use
within an extended options file (-X) or configuration file.
Usage: Intermediate
Specifies the age, in hours, of the locally-cached copy
of the HP software catalog before a new local copy should
be obtained. If the local file becomes too old (based on
the timestamp in the file), SWA tries to obtain a copy of
the catalog from the 'catalog_source' location. It is
possible that the remote catalog is also too old (as
determined by the timestamp in the file), for example if
'catalog_max_age=2' and 'catalog_source' specifies a
location that gets updated daily from HP's website. In
this case, the downloaded catalog is used, but will be
updated every time SWA checks the catalog's age.
Note: There are two special values, 0 and -1. The value
of 0 signifies to always update the file, and the value
of -1 signifies to never update the file, regardless of
age.
Usage: Intermediate
The file containing a locally-cached copy of the catalog
of available HP software and published security bul‐
letins.
Possible values include any absolute or relative pathname
with appropriate permissions.
The use of ${user_dir} at the beginning of this option
value is substituted with the value of the option (which
defaults to $HOME.swa).
Usage: Intermediate
A space-separated list of URLs (appropriately quoted for
your shell if applicable) that controls the location and
service to obtain the SWA catalog. The catalog must be
internal to your data center; you may not use this option
to access the official HP site. The catalog contains a
list of all potential issues, relevant software product
updates and patches that address many issues, along with
descriptions of manual actions that address some issues.
HP frequently updates the official catalog as new issues
become known and as new actions are recommended.
The following format is used to specify URLs:
<service>:[user:password@]<hostname.domainname>:<port>
Where '<service>' is one of the following methods for
obtaining the remote catalog:
- Secure\/authenticated HTTP
- Unauthenticated HTTP
- Unauthenticated FTP
Usage: Advanced
When set to true, swa will require the certificate revo‐
cation list (CRL) to be updated and checked for the
trusted certificate authority (CA) certificate being used
to validate the remote server.
In the unlikely event that the private certificate of the
server pointed to by the option is suspected of being
compromised, its certificate will be revoked, and added
to a list of revoked certificates by the CA.
The CRL must be signed by the same certificate chain that
signed the host certificate being checked. Checking the
CRL requires regular downloads from the CA, which can
lengthen the swa run time. If you do not wish to vali‐
date a revocation list, set this to false.
Usage: Advanced
The download_cmd extended option can be used to override
the default swa download commands, and therefore the pro‐
tocols swa uses to download the catalog and patch files.
The command is enclosed in single quotes ('). This option
is useful in cases where a system does not have a direct
connection to the Internet, but can execute a command
that can download a URL from the Internet (for example,
by using a gateway machine).
Using this option overrides many options which are used
by the internal swa download functionality, including
proxy and CRL configuration.
This command should take one option that is supplied by
swa (the URL of a file to download), and outputs that
file to its stdout. If the actual command in your envi‐
ronment behaves differently, it can be wrapped by a shell
script in order to provide the interface that swa needs.
Note: Programs like wget, curl, and Perl's GET can be
used to pass the contents of a URL to standard output.
These commands may provide support for different types of
proxies or can be used with ssh to work with a gateway
server. The GET command provides basic functionality. The
wget and curl commands provide extended functionality and
are provided with HP-UX 11i Internet Express (see
http:www.hp.comgointernetexpress). All three of these
commands are available for operating systems other than
HP-UX, such as Linux and Windows. For example, some
external commands can authenticate using Windows
NT.-based domain passwords to a Microsoft. web proxy,
which is not directly supported by swa.
The following command is an example:
-x download_cmd='usrlocalbinmyScript.sh'
The URL passed to download_cmd may contain characters
with special meanings to shells or other command inter‐
preters. By using a custom script as shown above any
requirement for nested quotes can be handled.
The download command also allows URL target substitution.
The actual URL used will be substituted in place of the
URL target string of the download command. The URL target
string default is %url. The above example download com‐
mand does not use the URL target string, SWA appends the
URL destination to the end of the command, which becomes
the script argument. The URL target string can be custom‐
ized, see the option.
The following command is an example:
-x download_cmd='usrbincurl %url'
The URL passed to download_cmd may be defined in the cat‐
alog_source option. Otherwise the default URL will be
used.
Usage: Advanced
Proxy host and port (with optional http basic authentica‐
tion username and password) for accessing content via the
FTP protocol. No proxy information is specified by
default.
The following format is used:
<service>:[user:password@]<proxy-server>:<port>
For example: ftp_proxy=http:web-proxy.mycompany.com:8088
The use of ${proxy} for this option value is substituted
with the value of the option (which is not set by
default).
Usage: Basic
Use this option to specify the HP user ID to gain access
to the HPSC patch database. If SWA determines that the HP
user ID is not set in a config file or on the command
line, the user will be prompted for it. Prompting for HP
user ID can be turned off using '-x prompt=false'.
Usage: Basic
Use this option in conjunction with hp_id to specify the
HP password to gain access to the HPSC patch database. If
SWA determines that the HP password is not set in a con‐
fig file or on the command line, the user will be
prompted for it. Prompting for HP password can be turned
off using '-x prompt=false'.
Usage: Basic
The file containing the HTML-formatted report that is
generated by the command. This is a single file with
internal hyperlinks. The html report may be printed to
stdout using the option.
The use of ${user_dir} at the beginning of this option
value is substituted with the value of the option (which
defaults to $HOME.swa).
Usage: Advanced
Proxy host and port (with optional http basic authentica‐
tion username and password) for accessing content via the
HTTPS protocol. No proxy information is specified by
default.
The following format is used:
<service>:[user:password@]<proxy-server>:<port>
For example: https_proxy=http:web-
proxy.mycompany.com:8088
If usernamepassword are specified as authentication cre‐
dentials to your proxy server, http basic authentication
is used, which is a clear-text protocol, (i.e., your
password may be visible to others on your network).
Also, credentials specified on the command-line are visi‐
ble to other local users, and access to credentials
stored in extended option files are determined by their
permissions. If your proxy server requires another type
of authentication, see the option.
The use of ${proxy} for this option value is substituted
with the value of the option (which is not set by
default).
Usage: Advanced
Proxy host and port (with optional http basic authentica‐
tion username and password) for accessing content via the
HTTP protocol. No proxy information is specified by
default.
The following format is used:
<service>:[user:password@]<proxy-server>:<port>
For example: http_proxy=http:web-proxy.mycompany.com:8088
The HTTP protocol is the default protocol used to down‐
load certificate revocation lists.
The use of ${proxy} for this option value is substituted
with the value of the option (which is not set by
default).
Usage: Basic
Files containing regular expressions, indicating which
issues to ignore. Each issue is matched by a regular
expression (see regexp(5)), and is ignored by the analy‐
sis. That is, whether or not the host or depot being
analyzed have the identified issue, that issue will not
appear on the report. In addition, software will not be
selected for download to address the issue. The software
may still be selected to address a different issue.
When a user first runs swa, if this file does not exist,
a template file is created, which contains instructions
on how to use this file. Upon creation, if a
~.spc_ignore file exists, it is translated into the swa
format and appended to the template.
The use of ${user_dir} at the beginning of this option
value is substituted with the value of the option (which
defaults to $HOME.swa).
Usage: Intermediate
Specifies the age, in hours, of the cached copy of the
inventory contents of a given system. If the inventory
becomes too old (based on the timestamp stored in the
file), SWA will inventory the host systemdepot again.
Note: There are two special values, 0 and -1. The value
of 0 signifies to always update the file, and the value
of -1 signifies to never update the file, regardless of
age.
Usage: Basic
Note: This release supports only one system, depot (lim‐
ited use cases) or inventory file for analysis per invo‐
cation of SWA. This option is useful for analyzing a
remote system without installing swa on that system.
Specify one host system or depot to be inventoried, or an
existing inventory file to be analyzed, and reported on.
Specify source as a URL using one of the following for‐
mats:
- System specification, uses
unauthenticated swlist protocol to gather the host
inventory.
- Depot
specification, also uses swlist protocol (limited
use cases).
- SSH specification to system or depot, uses SSH to
contact host and local swlist of the system or
depot.
- Inventory file specification, must be a local
file.
If an argument is specified in such a way that it
could be interpreted as either a system name or a
file name, it will be assumed to be a system name.
For example if 'foo' is the argument, then it will
be interpreted as a system named 'foo'. Alterna‐
tively if '.foo' is the argument, then it will be
interpreted as an inventory file named 'foo'
residing in the current directory.
If an inventory file name is not specified, the
inventory information is cached for later access
in a cache directory within the 'user_dir'. Nam‐
ing of these cached inventory files is based on
the hostname and path-to-depot as specified (e.g.,
using the fully qualified domain name of a host
will be cached separately from using the nodename,
even for the same machine). Refresh of the cached
inventory for each inventory_source is determined
by the option.
The following option specifications are examples:
System specification:
Depot specification:
Inventory file specification:
Note: This option is equivalent to -s but is
suitable for use within an extended options file
(-X) or configuration file.
Usage: Basic
This is the path to the log file for this command. Each
time SWA is run, this file will grow larger. This can be
changed, for example, to a month-specific location for
easier archiving, off-host backup, and rotation.
Usage: Basic
Specifies the level of message verbosity in the log file
(See also -x verbosity). Legal values are:
Only ERROR messages and the startingending BANNER mes‐
sages.
Adds WARNING messages.
Adds NOTE messages.
Adds INFO messages (informational messages preceded by
the '*' character).
Adds verbose INFO messages.
Adds very-verbose INFO messages.
Usage: Basic
Use this option to turn off prompting for HP user ID and
password if SWA determines the values are not set. See
the and '-x hp_pw' options.
Usage: Basic
Proxy host and port (with optional http basic authentica‐
tion username and password) for accessing content via the
relevant protocol. No proxy information is specified by
default.
The following format is used:
<service>:[user:password@]<proxy-server>:<port>
For example: proxy=http:web-proxy.mycompany.com:8088
If usernamepassword are specified as authentication cre‐
dentials to your proxy server, http basic authentication
is used, which is a clear-text protocol, (i.e., your
password may be visible to others on your network).
Also, credentials specified on the command-line are visi‐
ble to other local users, and access to credentials
stored in extended option files are determined by their
permissions. If your proxy server requires another type
of authentication, see the option. This option is used
as the default for the other proxy settings.
This option controls the default for all three proxies.
See the option, the option, and the option for more
details.
Usage: Intermediate
Controls whether swa will produce a report to stdout when
there are no issues andor actions. This is useful, for
example, in a cron job where you want email sent to you
only if there is an issue found.
A stdout report is always produced.
A stdout report is only produced if there are issues
andor actions.
Hint: To check for error status use the exit code
of the command and check the logfile for details.
Usage: Intermediate
Options to be passed to ssh. Multiple options may be
included as a space-delimited list. For example, if you
are using SWA in a cronjob, you may wish to specify '-o
BatchMode=yes' to return immediately upon failure, rather
than prompting for a password.
See ssh_config(5) for additional options.
Usage: Basic
Type of report to display on stdout. This is useful for
controlling what type of output you would like to see.
Legal values are:
- (Default) Summary of recommended actions
- Summary of identified issues
- Recommended actions with issue justification
- Comprehensive report in html format
- No report is generated on stdout
Usage: Advanced
This option is used in conjunction with the download_cmd
option to override the default url_target string(%url),
for specific environment needs. The url_target string
will be substituted in the download command with the
actual URL for completing any downloads.
The following command is an example:
-x url_target='myUrlTargetString1' -x download_cmd='opt‐
perlbinGET myUrlTargetString1'
See the option.
Usage: Basic
The directory where swa stores catalog, inventory, analy‐
sis, ignore, and report files. The default location is a
subdirectory (.swa) of the user's home directory. This
can be changed, for example, to allow archival of previ‐
ous interim artifacts in a date-specific directory or
off-host. Several other options default to a directory
relative to this directory, so changing this option
allows all of those locations to stay in synch relative
to a common root.
Usage: Basic
Specifies the level of stderr verboseness:
Only ERROR messages and the startingending BANNER mes‐
sages.
Adds WARNING messages.
Adds NOTE messages.
Adds INFO messages (informational messages preceded by
the '*' character).
Adds verbose INFO messages.
Adds very-verbose INFO messages.
Note: The '-v' option is equivalent to increasing
verbosity by 1 (e.g., from 3 to 4) and the '-q'
option is equivalent to decreasing verbosity by 1.
The '-v' and '-q' options can be used more than
once.
For compatibility with other applications, several environment
variables can be used to configure how SWA connects to the
Internet to retrieve catalogs, certificate revocation lists, and
software. These environment variables include and
These environment variables have the same effect as the corre‐
sponding extended options of the same names. The Extended
Options section describes the usage and meaning of each option
and the behavior if the same option is specified in multiple
places.
The extended option cannot be specified as an environment vari‐
able, but may be a useful alternative if all protocols use the
same proxy server at your site.
The environment variable is also honored for local operations,
if set. If this value is not set, the default of is used. This
directory does not allow write operations for non-privileged
users, so TMPDIR must be set by non-root users if a temporary
directory is required for that operation. An example operation
that uses this directory is unsharing of patch files. For
older-style patches which do not honor TMPDIR, SWA rewrites the
shar file so that TMPDIR will be honored before unpacking the
patch.
Return Values
returns the following values:
Success
Error
Warning
Examples
These example commands assume your default configuration file contains
your ITRC login information. The syntax will be:
To display usage information:
To display usage and list all extended options:
To run using the options specified in the file "./myconfig":
To inventory the local system, analyze it against an HP-supplied cata‐
log (of known software and issues) for newer Quality Pack patch bun‐
dles, security issues, and critical patch warnings, and then generate a
default stdout "action" report:
To create a report for security issues (SEC) for a remote system inven‐
tory gathered with Secure Shell, and running in to avoid being prompted
for user input:
To create a detailed report for remotesystem, limited in scope to Qual‐
ity Pack patch bundle analysis (QPK) and patches with critical warnings
(PCW). This example uses the networking protocol, which is not
integrity protected:
To do the same task as the previous example, using the extended option
equivalents (which can be specified on the command line, in a user or
system configuration file, or in an extended options file):
To generate a report and place the analysis results in the ~/firstanal‐
ysis.xml file (for later use by
To generate a report, updating the catalog of HP software if it is more
than 48 hours old:
To generate a report using a specified catalog of HP software without
updating that catalog:
To generate a report always updating the catalog of HP software:
AUTHOR
was developed by Hewlett-Packard Development Company, L.P.
FILES
The per-user Software Assistant configuration file. This file takes
precedence over the system-wide SWA configuration file.
An HP-supplied catalog file from the ITRC website that
contains known security issues and other defects along with
their solutions. This file is downloaded with the command swa
report or swa step catalog.
The analysis of the inventory file and the catalog file
created with swa report or swa step analyze.
The inventory of installed software created by swa
inventory or swa step inventory.
Use this file to specify issues for analyzers to ignore. It is
possible to use more than one ignore file by using the extended
option ignore_file.
The comprehensive report written by swa report and
swa step report.
Default alternative log file if you don't have permissions
to write to /var/opt/swa/swa.log.
The system-wide SWA configuration file.
An example configuration file outlining the usage of each
extended option.
Script to configure HP SIM 5.2 and later for SWA. Only
required if SWA is installed when HP SIM is installed but not
running. HP SIM must be running when configHPSIM is run.
Manpages.
The default directory for downloading software before it
is packaged in a depot. This directory can be set with the
extended option swcache. Note that this directory can consume a
significant amount of disk space.
Directory that holds all clients' files generated from SWA
within HP SIM. Files are kept in user and job-specific subdirec‐
tories. This directory might require significant space to sup‐
port clients' analysis, catalog, inventory, and report files.
User-specific directory used by SWA when running under
HP SIM.
Default log file.
Lists all files downloaded from HP to the swcache. It is
located in the swcache directory.
Lists special installation instructions and dependencies
for the patches in the depot. It is located in the depot direc‐
tory.
Lists issue IDs to be ignored (e.g., they are completed or not
applicable). Supports comments
and regular expressions. See regexp(5).
SEE ALSOswa(1M), swa-get(1M), swa-step(1M), swa-clean(1M), and secu‐
rity_patch_check(1M).
swa-report(1M)
