swlist(1M)

NAME

swlist — display information about software products

SYNOPSIS

swlist [-d|-r] [-i] [-R] [-v] [-a attribute] [-C session_file] [-f software_file] [-l level] [-s source] [-S session_file] [-t target_file] [-x option=value] [-X option_file] [software_selections] [@ target_selections]

Remarks

swlist has an interactive user interface that you can invoke by typing swlist -i.
SD-UX commands are included with the HP-UX Operating System and manage software on the local host only.
To install and manage software simultaneously on multiple remote hosts (including HP-UX, other UNIX® platforms, Windows NT®, and PCs) from a central controller, you must purchase the HP OpenView Software Distributor which provides extended software management capabilities. Information specific only to the OpenView product is marked with a heading similar to the following:
- The following information applies to HP OpenView Software Distributor only

DESCRIPTION

The swlist command displays information about software products installed at or available from the specified target_selections. It supports these features:

Specify bundles, products, subproducts, and/or filesets to list.
Display the files contained in each fileset.
Display a table of contents from a software source.
Specify the attributes to display for each software object.
Display all attributes for bundles, products, subproducts, filesets and/or files.
Display the full software_spec to be used with software selections.
Display the readme file for products.
Display the depots on a specified host.
Create a list of products, subproducts, and/or filesets to use as input to the other commands.
List the categories of available or applied patches.
List applied patches and their state (applied or committed).

Previewing Product and OS Update Information

To preview information about new software in the depot, you can use swlist to view the readme file for each product, including OS update information contained in the SD (SW-DIST product) readme. For example, to display the latest OS update information:

swlist -d -a readme -l product SW-DIST @ hostA:/depot11 

Options

When no options or operands are specified, swlist lists the software bundles (and products which are not part of a bundle) that are installed at the local host. swlist supports the following options:

-d

List software available from a depot (instead of software installed on a root filesystem).

-i

Invoke the swlist interactive user interface. The interactive interface lets you browse SD software objects. Invoking swlist -i -d lets you browse depot software.

-r

List products installed on an alternate root filesystem (instead of software installed on /). Use of -r is optional.

-R

Shorthand for -l bundle -l product -l subproduct -l fileset.

-v

If no -a options are specified, then list all the attributes for an object, one attribute per line. The attributes are listed in the format:

keyword value

If one or more -a options are specified, then list the selected attributes in the above format.

-a attribute

Each object has its own set of attributes. These attributes include such things as revision, description, vendor information, size, and many others. The -a option selects a specific attribute to display. You can specify multiple -a options to display multiple attributes.

Note that the tag attribute (i.e. the identifier) is always displayed for product, subproduct, and fileset objects. The path attribute (i.e. the filename) is always displayed for file objects.

The full set of attributes for a given software object can be obtained using the -v option. See also the sd(4) man page for details on these attributes.

-C session_file

Save the current options and operands to session_file. You can enter a relative or absolute path with the file name. The default directory for session files is /.sw/sessions/. You can recall a session file with the -S option. (Note that session management does not apply to the swlist interactive user interface invoked by the -i option.)

-f software_file

Read the list of software_selections from software_file instead of (or in addition to) the command line.

-l level

List all objects down to the specified level. Both the specified level(s) and the depth of the specified software_selections control the depth of the swlist output.

-s source

Specifies the software source to list. This is an alternate way to list a source depot. Sources can also be specified as target depots and listed using the -d option.

-S session_file

Execute swlist based on the options and operands saved from a previous session, as defined in session_file. You can save session information to a file with the -C option. (Note that session management does not apply to the swlist interactive user interface invoked by the -i option.)

-t target_file

Read the list of target_selections from target_file instead of (or in addition to) the command line.

-x option=value

Set the session option to value and override the default value (or a value in an alternate option_file specified with the -X option). Multiple -x options can be specified.

-X option_file

Read the session options and behaviors from option_file.

Operands

swlist supports two types of operands: software selections followed by target selections. These operands are separated by the "@" (at) character. This syntax implies that the command operates on "selections at targets".

Software Selections

The selections operands consist of software_selections.

swlist supports the following syntax for each software_selection:

bundle[.product[.subproduct][.fileset]][,version] 

product[.subproduct][.fileset][,version] 

The version component has the form:

[,r <op> revision][,a <op> arch][,v <op> vendor] 
[,c <op> category][,l=location][,fr <op> revision] 
[,fa <op> arch] 

location applies only to installed software and refers to software installed to a location other than the default product directory.
fr and fa apply only to filesets.
The <op> (relational operator) component can be of the form:
- ==, >=, <=, <, >, or !=
which performs individual comparisons on dot-separated fields.
For example, r>=B.10.00 chooses all revisions greater than or equal to B.10.00. The system compares each dot-separated field to find matches.
The = (equals) relational operator lets you specify selections with the shell wildcard and pattern-matching notations:
- [ ], *, ?, !
For example, the expression r=1[01].* returns any revision in version 10 or version 11.
All version components are repeatable within a single specification (e.g. r>=A.12, r<A.20). If multiple components are used, the selection must match all components.
Fully qualified software specs include the r=, a=, and v= version components even if they contain empty strings. For installed software, l= is also included.
No space or tab characters are allowed in a software selection.
The software instance_id can take the place of the version component. It has the form:
- [instance_id]
within the context of an exported catalog, where instance_id is an integer that distinguishes versions of products and bundles with the same tag.

The \* software specification selects all products. It is not allowed when removing software from the root directory /.

Target Selections

swlist supports this syntax for each target_selection.

[host][:][/directory]

The : (colon) is required if both a host and directory are specified.

The following PC information applies only to HP OpenView Software Distributor

The command also supports the syntax:

[pc_controller] 

This syntax only applies to the PC controllers and PC depots on PC controllers.

Valid targets for a PC controller can be listed using:

swlist -l machine|user|group 

EXTERNAL INFLUENCES

Default Options

In addition to the standard options, several SD behaviors and policy options can be changed by editing the default values found in:

/var/adm/sw/defaults: the system-wide default values.
$HOME/.swdefaults: the user-specific default values.

Values must be specified in the defaults file using this syntax:

[command_name.]option=value 

The optional command_name prefix denotes one of the SD commands. Using the prefix limits the change in the default value to that command. If you leave the prefix off, the change applies to all commands.

You can also override default values from the command line with the -x or -X options:

command -x option=value

command -X option_file

The following section lists all of the keywords supported by the swlist commands. If a default value exists, it is listed after the "=".

The policy options that apply to swlist are:

agent_timeout_minutes=10000

Causes a target agent to exit if it has been inactive for the specified time. This can be used to make target agents more quickly detect lost network connections since RPC can take as long as 130 minutes to detect a lost connection. The recommended value is the longest period of inactivity expected in your environment. For command line invocation, a value between 10 minutes and 60 minutes is suitable. A value of 60 minutes or more is recommended when the GUI will be used. The default of 10000 is slightly less than 7 days.

codeword=

Provides the "codeword" needed to unlock protected HP CD-ROM software.

Some HP software products are shipped on CD-ROM as "protected" products. That is, they cannot be installed or copied unless a "codeword" and "customer ID" are provided. The codeword is found on the CD-ROM certificate which you received from HP. You may use this default specification on the command line or the SD-UX interactive user interface to enter the codeword.

This default stores the codeword for future reference; it needs to be entered only once. If a new HP product is purchased and a previous codeword has already been entered for that CD-ROM, just enter the new codeword as usual and the codewords will be merged internally.

NOTE: For HP-UX B.10.10 and later systems, SD searches the .codewords file on the server that is providing protected software to other hosts. It looks for valid customer_id/codeword pairs. In doing so, SD eliminates the need to enter codewords and customer_ids on every host that is "pulling" the software.

To properly store the customer_id/codeword for a CD-ROM, run swinstall -p or swcopy -p on the host serving the CD-ROM. After the codeword has been stored, clients installing or copying software using that host and CD-ROM as a source will no longer require a codeword or customer_id.

customer_id=

This number, also printed on the Software Certificate, is used to "unlock" protected software and restrict its installation to a specific site or owner. It is entered using the -x customer_id= option or by using the interactive user interface. The customer_id can be used on any HP-UX 10.0X compatible HP9000 system.

distribution_target_directory=/var/spool/sw

Defines the default location of the target depot.

layout_version=1.0

Specifies the POSIX layout_version to which the SD commands conform when writing distributions and swlist output. Supported values are "1.0" (default) and "0.8".

SD object and attribute syntax conforms to the layout_version 1.0 specification of the IEEE POSIX 1387.2 Software Administration standard. SD commands still accept the keyword names associated with the older layout version, but you should use layout_version=0.8 only to create distributions readable by older versions of SD.

See the description of the layout_version option in sd(5) for more information.

level=

Specify the level of the object to list.

The supported software levels are:

bundle: Show all objects down to the bundle level.
product: Show all objects down to the product level. Also use -l bundle -l product to show bundles.
subproduct: Show all objects down to the subproduct level.
fileset: Show all objects down to the fileset level. Also use -l fileset -l subproduct to show subproducts.
file: Show all objects down to the file level (i.e. depots, products, filesets, and files).
category: Show all categories of available patches.
patch: Show all applied patches.

The supported depot and root levels are:

depot: Show only the depot level (i.e. depots which exist at the specified target hosts).
root: List all alternate roots.
shroot: List all registered shared roots (HP-UX 10.X only).
prroot: List all registered private roots (HP-UX 10.X only).

The machine, user, and group levels apply only to HP OpenView Software Distributor PC targets:

machine: Show the machines known to a PC controller.
user: Show the users known to a PC controller.
group: Show the groups known to a PC controller.

one_liner=revision title

Defines the attributes which will be listed for each object when no -a or -v options are specified. Each attribute included in the one_liner definition is separated by <tab> or <space>. Any attributes may be included in the one_liner definition. If a particular attribute does not exist for an object, that attribute is silently ignored. For example, the description attribute is valid for products, subproducts, and filesets, but the architecture attribute is only valid for products.

patch_one_liner=title patch_state

Specifies the attributes displayed for each object listed when the -l patch option is invoked and when no -a or -v option is specified. The default display attributes are title and patch_state.

rpc_binding_info=ncacn_ip_tcp:[2121] ncadg_ip_udp:[2121]

Defines the protocol sequence(s) and endpoint(s) on which the daemon listens and the other commands contact the daemon. If the connection fails for one protocol sequence, the next is attempted. SD supports both the tcp (ncacn_ip_tcp:[2121]) and udp (ncadg_ip_udp:[2121]) protocol sequence on most platforms. See the sd.5 man page by typing man 5 sd for more information.

rpc_timeout=5.

Relative length of the communications timeout. This is a value in the range from 0 to 9 and is interpreted by the DCE RPC. Higher values mean longer times; you may need a higher value for a slow or busy network. Lower values will give faster recognition on attempts to contact hosts that are not up or not running swagentd. Each value is approximately twice as long as the preceding value. A value of 5 is about 30 seconds for the ncadg_ip_udp protocol sequence. This option may not have any noticeable impact when using the ncacn_ip_tcp protocol sequence.

select_local=true

If no target_selections are specified, select the default target_directory of the local host as the target_selection for the command.

software=

Defines the default software_selections. There is no supplied default. If there is more than one software selection, they must be separated by spaces.

software_view=all_bundles

Indicates the software view to be used as the default level for the software listing in the GUI. It can be set to all_bundles, products, or a bundle category tag (to indicate to show only bundles of that category). For HP OpenView Software Distributor the default value is products.

targets=

Defines the default target_selections. There is no supplied default (see select_local above). If there is more than one target selection, they must be separated by spaces.

verbose=0

Controls how attribute values are displayed. A value of

0: displays only the attribute value.
1: displays both the attribute keyword and value. (See the -v option above.)

Session File

Each invocation of swlist defines a task session. The command automatically saves options, source information, software selections, and target selections before the task actually commences. This lets you re-execute the command even if the session ends before the task is complete. You can also save session information from interactive or command-line sessions.

Session information is saved to the file $HOME/.sw/sessions/swlist.last. This file is overwritten by each invocation of the command. The file uses the same syntax as the defaults files.

From an interactive session, you can save session information into a file at any time by selecting the Save Session or Save Session As option from the File menu.

From a command-line session, you can save session information by executing the command with the -Csession__file option. You can specify an absolute path for a session file. If you do not specify a directory, the default location is $HOME/.sw/sessions/.

To re-execute a saved session from an interactive session, use the Recall Session option from the File menu.

To re-execute a session from a command-line, specify the session file as the argument for the -S option.

When you re-execute a session file, the values in the session file take precedence over values in the system defaults file. Likewise, any command-line options and parameters take precedence over the values in the session file.

Environment Variables

The environment variable that affects the swlist command is:

LANG

Determines the language in which messages are displayed. If LANG is not specified or is set to the empty string, a default value of C is used. See lang(5) for more information.

NOTE: The language in which the SD agent and daemon log messages are displayed is set by the system configuration variable script, /etc/rc.config.d/LANG. For example, /etc/rc.config.d/LANG, must be set to LANG=ja_JP.SJIS or LANG=ja_JP.eucJP to make the agent and daemon log messages display in Japanese.

Signals

The swlist command catches the signals SIGQUIT and SIGINT. If these signals are received, swlist prints a message, sends a Remote Procedure Call (RPC) to the agents to wrap up, and then exits.

Each agent will complete the list task (if the execution phase has already started) before it wraps up.

OPERATION

The output from swlist follows this rule with all options: only the lowest level listed (product, subproduct, fileset or file) will be uncommented. Among other things, this allows the output from swlist to be used as input to other commands. The one exception is the list that contains files; file-level output is not accepted by other commands.

The types of listings that can be selected are given below. Some of these listings are not exclusive choices, but rather ways to view the objects while controlling the amount of output.

Default Listing
Software Listing
Root Listing
Depot Listing
Multiple Targets Listing
Verbose Listing
Fanout Listing (HP OpenView Software Distributor only)

Default Listing

If swlist is invoked with no software_selections and no target_selections, a listing of all installed products on the local host is produced. This listing contains one line for each product. The line includes the product tag attributes and all other attributes selected via the one_liner option.

If target_selections (i.e. target hosts) are specified, this same format listing is produced for the installed software at each of the specified hosts.

Software Listing

A listing of software objects is controlled by the specified software_selections, and also by the -l option ( swlist.level=). swlist lists the contents of each software object specified in the software_selections. For example, if you specify product selections, the subproducts and/or filesets contained immediately below each product will be listed. If you specify fileset selections, the files contained in each fileset will be listed.

The depth of objects listed is controlled with the -l option. This option can expand or restrict the depth in concert with the specified software selections. By default, the contents of a specified software selection are always listed (as described above). The -l option can defeat this listing by specifying a level equivalent to the level of objects in the software_selections. For example, if you want to list specific product selections but not their contents, use -l product. If you want to list specific fileset selections but not their contained files, use -l fileset. The software_selection options only apply if the level is bundle, product, subproduct, fileset, file, or patch.

Depot Listing

Another class of objects that swlist can display are software depots. For example, the user can list all registered depots on a given host. A combination of the -l depot option and target_selections operands can produce a variety of depot listings.

Multiple Targets Listing

Multiple target_selections (i.e. root filesystems, alternate roots, or depots) are listed sequentially: list all the requested objects and attributes from the first target_selection, followed by the second target_selection, etc.

Verbose Listing

The -v option causes a verbose listing to be generated. A verbose listing includes all attributes defined for an object. The swlist command prints the keyword and value for each attribute. The attributes are listed one per line. The user can post-process (filter) the output with grep(1), awk(1), and/or sed(1) to get the fields of interest.

The depot's attributes are displayed if swlist is called with the -v and -l depot options, and a specific depot target_selection.

Attributes for a particular software level (product/subproduct/fileset/file) are displayed based on the depth of the specified software_selections. For example, swlist -v product1.fileset1 will give all fileset attributes for fileset1. If the -v option is used with the -l option, the different listing are:

To display attributes for all products, use swlist -v -l product
To display attributes for all products and subproducts, use swlist -v -l subproduct
To display attributes for all products and filesets, use swlist -v -l fileset
swlist -v -l file

Fanout Listing

The following applies only to HP OpenView Software Distributor

The swlist command can also list the users, groups, or machines associated with a PC controller; i.e. the valid PC targets which are available for installation through the PC controller. To list these PC targets, use the -l user, -l group, or -l machine options.

RETURN VALUE

The swlist command returns:

0: The software_selections and/or target_selections were successfully listed.
1: The list operation failed on all target_selections.
2: The list operation failed on some target_selections.

DIAGNOSTICS

The swlist command writes to stdout, stderr, and to the agent logfile.

Standard Output

All listings are printed to stdout.

Standard Error

The swlist command writes messages for all WARNING and ERROR conditions to stderr.

Logging

The swlist command does not log summary events. It logs events about each read task to the swagent logfile associated with each target_selection.

You can use the swlist interactive interface (swlist -i -d) to view the swaudit.log file.

EXAMPLES

Run the swlist interactive interface:

swlist -i @ host1 

Use interactive swlist to view a depot:

swlist -i -d @ /tmp/depot 

List all of the products installed on the local host:

swlist 

Generate a comprehensive listing that includes all filesets for the product NETWORKING:

swlist -v -l fileset NETWORKING 

List all the attributes for the ARPA-RUN fileset:

swlist -v NETWORKING.ARPA.ARPA-RUN 

List the C product installed on several remote hosts:

swlist cc @ hostA hostB hostC 

List the FRAME product relocated to directory /opt on host1:

swlist FRAME,1=/opt @ host1 

List all the versions of the FRAME product installed on the toolserver host:

swlist FRAME @ toolserver 

List all products in a shared root (HP-UX 10.X only):

swlist -r @ /export/shared_roots/OS_700 

List products in a client's private root (HP-UX 10.X only):

swlist -r @  /export/private_roots/client 

List the contents of the local tape, /dev/rmt/0m:

swlist -d @ /dev/rmt/0m 

or, alternatively:

swlist -s /dev/rmt/0m 

List the tag and revision attributes for all products on the local tape /dev/rmt/0m:

swlist -d -a revision @ /dev/rmt/0m 

or, alternatively:

swlist -a revision -s /dev/rmt/0m @ 

Display the README file for the FRAME product:

swlist -a readme FRAME 

List the products stored in a remote depot:

swlist -d @ hostA:/depot 

List all depots on a host:

swlist -l depot @ hostA 

List the categories defined in the depot mounted at /CD.

swlist -d -l category @ /CD 

Output:
critical_patch 1.0 Patches to fix system hangs or data corruption S747_upgrade 2.0 Patches needed to upgrade to an S747 security_patch 2.0 Patches affecting system security

List a particular attribute of a category object identified by the tag critical_patch.

swlist -a description -l category critical_patch 

Use the swlist -l option and patch level to display the values of a fileset's applied_patches attribute.

swlist -l patch BogusProduct 

Output:
BogusProduct 1.0 This is a Bogus Product BogusProduct.FakeFS Fake fileset PHZX-0004.FakeFS Patch for defect X superseded PHZX-3452.FakeFS Patch for defect Y applied

Another example showing just the patch:

swlist -l patch PHZX-0004 

Output:
PHZX-0004 1.0 Patch product PHZX-0004.FakeFS Patch for defect X superseded

The next two examples apply only to HP OpenView Software Distributor

List all machines known to a PC controller:

swlist -l machine @ server 

List all users known to a PC controller:

swlist -l user @ server 

LIMITATIONS

The following applies only to HP OpenView Software Distributor

For PCs, the swlist command only applies to the PC controller and the PC depot on the PC controller.

FILES

$HOME/.swdefaults: Contains the user-specific default values for some or all SD options.
$HOME/.sw/sessions/: Contains session files automatically saved by the SD commands, or explicitly saved by the user.
/usr/lib/sw/sys.defaults: Contains the master list of current SD options (with their default values).
/var/adm/sw/: The directory which contains all of the configurable (and non-configurable) data for SD. This directory is also the default location of logfiles.
/var/adm/sw/defaults: Contains the active system-wide default values for some or all SD options.
/var/adm/sw/host_object: The file which stores the list of depots registered at the local host.
/var/adm/sw/products/: The Installed Products Database (IPD), a catalog of all products installed on a system.
/var/spool/sw/: The default location of a source and target software depot.

AUTHOR

swlist was developed by the Hewlett-Packard Company and Mark H. Colburn (see pax(1)).