swa-get(1M)

NAME

swa-get: swa — download software from HP to resolve issues and make a depot

SYNOPSIS

swa get [-p] -t target_depot 
 [-q [q[q]]] [-v[v]] [[-option] -?] [-x option=[value|-?]] [-X option_file]

DESCRIPTION

The swa get command downloads software from HP to resolve issues identified by swa report; see swa-report(1M). By default, a new depot is created. While swa get can update an existing depot, it does not analyze that depot for issues and the original contents of that depot are the responsibility of the system administrator. Currently, only patches can be downloaded from HP (for example, Application Release software is excluded), and some security issues require manual action (that is, cannot be resolved by HP-supplied patches).

The swa get command determines which software to download based on the analysis file from a previous swa report command. If a preexisting depot is being updated, swa get determines if the needed software is already in the depot or in the swcache directory. swa get will not download patches that already exist in either location.

Security Considerations

Software download (swa get) relies on the integrity of the analysis file to ensure the integrity of patches before unpacking them. The analysis file gets MD5 checksum information directly from the catalog. Therefore it is important that all transmissions of the catalog and/or analysis file are integrity protected and that file permissions do not allow unnecessary modification.

Depot creation (swa get) relies on the integrity of the patches within the swcache directory. Therefore, after unpacking the patches, it is important that all subsequent transmissions of the patches are integrity protected and that file permissions do not allow unauthorized modification. Deploying software using Software Distributor (using the swinstall command) has security properties that are documented in the Software Distributor Administration Guide.

Options

swa get recognizes the following options:

-p: Runs this command in preview mode.
-t target_depot: The depot that software is copied into as specified by target_depot. This is where patches from HP are copied into. Normally, the target_depot should be empty and a new depot will be created. If the depot already exists, you must specify the advanced option -x allow_existing_depot=true and understand its implications. (See also the -x allow_existing_depot option in Extended Options).
-q: The verbosity level is decreased by one for each instance -q is specified. (See also the -x verbosity option.)
-v: The verbosity level is increased by one for each instance -v is specified. (See also the -x verbosity option.)
-?: Displays general usage.
-option -?: Describes the legal values for this option. If option is -x, all possible extended options are listed for the specified major mode (swa command). If no major mode is given, all extended options are listed for all the major modes.
-x option=value: Sets the extended option to a value. See the Extended Options definitions below.
-x option=-?: Describes the legal values for this option.
-X option_file: Gets the extended options from option_file. For a description and examples of syntax for this file, see the /etc/opt/swa/swa.conf.template file.

Extended Options

The extended options may be specified in different ways: on the command line using the -x option, in an option file specified using the -X option, or in one of the configuration files /etc/opt/swa/swa.conf (system wide) or $HOME/.swa.conf (user-specific). The /etc/opt/swa/swa.conf.template file provides example syntax for a configuration or -X file.

If the same option is given in multiple locations, the following order is prioritized from highest to lowest:

Options specified on the command line
Options specified within an option file (-X option_file)
Proxy environment variables (See the Environment Variable section.)
Options specified within the $HOME/.swa.conf file
Options specified within the /etc/opt/swa/swa.conf file
Default value, specified in the descriptions of each option below in option_name=default_value format.

Note: If the same option or extended option is given multiple times in the same location, the last option takes effect. If the option has a single letter equivalent (for example, -v and -x verbosity) 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.

swa get recognizes the following -x (extended) options, which are shown with their default values:

-x allow_existing_depot=false

Usage: Advanced

Determines whether the target depot must be empty at the start of the command, or can be an existing depot. SWA does not perform any analysis of the depot contents. By specifying this option, you accept responsibility for the contents of this depot.

true: Target depot can exist (it is non-empty).
false: Target depot must be empty at the start of the command.

-x analysis_file=${user_dir}/cache/swa_analysis.xml

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 analysis. Use this option to save the results from a specific 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 (swa report creates this file), be sure to specify that location when the analysis file is later used (swa get uses this file).

Possible values include any absolute or relative path name with appropriate permissions.

The use of ${user_dir} at the beginning of this option value is substituted with the value of the user_dir option (which defaults to $HOME/.swa).

-x crl_check=true

Usage: Advanced

When set to true, SWA will require the Certificate Revocation 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 catalog_source option is suspected of being compromised, its certificate will be revoked, and added to a list of revoked certificates by the CA. See swa-report(1M) for information about the catalog_source option.

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 validate a revocation list, set this to false.

-x crl_url=http://crl.verisign.com/RSASecureServer.crl

Usage: Advanced

The URL of the CRL. See the crl_check option for more information. If you are behind a proxy server, then you will need to configure the proxy information for the protocol being used to download the CRL.

-x download_cmd=

Usage: Intermediate

Specifies a command that can download a URL from the Internet. 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 standard output. If the actual command in your environment behaves differently, it can be wrapped by a shell script in order to provide the interface that SWA needs.

The command needs to support the protocol specified by the catalog_source option (default HTTPS) for catalog retrieval and FTP for patch retrieval. See swa-report(1M) for information about the catalog_source option.

Note: Externally used commands are not necessarily supported by HP, but can give considerable flexibility for your environment. 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:

swa report -x download_cmd='ssh user@system curl'

This command uses SSH (see ssh(1)) to run the curl command on a gateway system. The curl command is an open source tool that ships with several Linux distributions. curl may be configured, either using a configuration file on the gateway system or by command-line parameters specified as part of the download_cmd option.

-x ftp_proxy=${proxy}

Usage: Advanced

Proxy host and port (with optional HTTP basic authentication username and password) for accessing content using 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 FTP protocol is used for patch download. Integrity of the patches is checked using MD5 secure hashes in the catalog, for which the HTTPS protocol is recommended. See the https_proxy option and the catalog_source option for details. See swa-report(1M) for information about the catalog_source option.

The use of ${proxy} for this option value is substituted with the value of the proxy option (which is not set by default).

-x https_proxy=${proxy}

Usage: Advanced

Proxy host and port (with optional HTTP basic authentication username and password) for accessing content using 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 username and password are specified as authentication credentials to your proxy server, HTTP basic authentication is used, which is a clear-text protocol, (that is, your password may be visible to others on your network). Also, credentials specified on the command-line are visible 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 -x download_cmd option.

The use of ${proxy} for this option value is substituted with the value of the proxy option (which is not set by default).

-x http_proxy=${proxy}

Usage: Advanced

Proxy host and port (with optional HTTP basic authentication username and password) for accessing content using 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 download certificate revocation lists. See the crl_url option for more details.

The use of ${proxy} for this option value is substituted with the value of the proxy option (which is not set by default).

-x logfile=/var/opt/swa/swa.log

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.

-x log_verbosity=4

Usage: Basic

Specifies the level of message verbosity in the log file (See also -x verbosity). Legal values are:

0: Only ERROR messages and the starting and ending BANNER messages.
1: Adds WARNING messages.
2: Adds NOTE messages.
3: Adds INFO messages (informational messages preceded by the '*' character).
4: Adds verbose INFO messages; this is the default.
5: Adds very verbose INFO messages.

-x preview=false

Usage: Basic

Specifies if swa get should be run in preview mode or not. If preview is set to false, do not run in preview mode. If preview is set to true, run this command in preview mode only (that is, complete the analysis phase and exit; no changes are committed to disk). Setting this option to true has the same effect as specifying -p on the command line.

-x proxy=

Usage: Basic

Proxy host and port (with optional HTTP basic authentication username and password) for accessing content using 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

The HTTPS protocol is used for catalog download, the HTTP protocol is used to download the CRL, and the FTP protocol is used for patch download. The proxy= option controls the default for all three proxies. See the https_proxy option, the http_proxy option, and the ftp_proxy option for more details.

-x swcache=/var/opt/swa/cache

Usage: Basic

This is the directory where SWA stores downloaded patches before putting them into a depot. The default location is only writable by root, so this value needs to be changed for a non-root user to be able to download software. Opening up permissions on the default location is not recommended.

-x user_dir=~/.swa

Usage: Basic

The directory where SWA stores catalog, inventory, analysis, 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 previous 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.

-x verbosity=3

Usage: Basic

Specifies the level of standard error verboseness:

0: Only ERROR messages and the starting and ending BANNER messages.
1: Adds WARNING messages.
2: Adds NOTE messages.
3: Adds INFO messages (informational messages preceded by the '*' character); this is the default.
4: Adds verbose INFO messages.
5: Adds very verbose INFO messages.

Note: The -v option is equivalent to increasing verbosity by 1 (for example, 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.

EXTERNAL INFLUENCES

Environment Variables

For compatibility with other applications (including security_patch_check), 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 ftp_proxy, http_proxy, and https_proxy.

These environment variables have the same effect as the corresponding 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 proxy extended option cannot be specified as an environment variable, but may be a useful alternative if all protocols use the same proxy server at your site.

The TMPDIR environment variable is also honored for local operations, if set. If this value is not set, the default of /var/opt/swa/tmp 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 VALUE

swa get returns the following values:

0: Success
1: Error
2: Warning

EXAMPLES

To display swa get usage information:

swa get -?

To display usage and list all swa get extended options:

swa get -x -?

To run swa get using the options specified in the file ./myconfig:

swa get -X ./myconfig

To get patches from HP that are recommended in the default analysis file (from the previous swa report command) and place the results into the new depot mydepot:

swa get -t mydepot 

To add newly recommended patches into the existing depot mydepot, only downloading patches from HP that are neither in mydepot nor previously downloaded:

swa get -t mydepot -x allow_existing_depot=true 

To preview which patches need to be downloaded from HP and added to an existing depot without actually doing the work, and with increased verbosity:

swa get -p -v -t mydepot -x allow_existing_depot=true 

AUTHOR

swa was developed by HP.

FILES

/etc/opt/swa/swa.conf: System-wide Software Assistant configuration file.
/etc/opt/swa/swa.conf.template: Template file that documents each -x option.
$HOME/.swa.conf: Per-user Software Assistant configuration file.
/var/opt/swa/swa.log: Default log file location for root users. For users without write permissions to the default log location, a swa.log file is created under the directory specified by the -x user_dir extended option.
download.contents: Lists all files downloaded from HP stored within the swcache, a directory specified by the swcache extended option.
readBeforeInstall.txt: Lists special installation instructions and other dependencies for the patches in the depot. Located in the root directory of the target depot.

swa-get(1M)

Technical documentation

» Table of Contents

» Glossary

» Index

NAME

SYNOPSIS

DESCRIPTION

Security Considerations

Options

Extended Options

EXTERNAL INFLUENCES

Environment Variables

RETURN VALUE

EXAMPLES

AUTHOR

FILES

SEE ALSO