NAME

swconfig − Configure, unconfigure, or reconfigure installed software

SYNOPSIS

swconfig [-p] [-v] [-u] [-x option=value] [-X option_file] [-f file] [-t target_file] [-S session_file] [software_selections] [ @  target_selections]

DESCRIPTION

The swconfig command configures, unconfigures, and reconfigures installed software products for execution on the specified target hosts.  The swconfig command transitions software between INSTALLED and CONFIGURED states. 

Software is automatically configured and unconfigured as part of the swinstall and swremove commands (respectively).  The user can defer configuration when software is installed.  The swconfig command can (un)configure software independent of swinstall and swremove, e.g. to configure (unconfigure) hosts that share software from a server host where the software is actually installed.  The swconfig command must also be executed when the initial configuration by swinstall failed, was deferred, or needs to be changed. 

Configuration primarily involves the execution of vendor-supplied configure scripts.  These scripts perform configuration tasks which enable the use of the software on the target hosts.  The swconfig command also allows software to unconfigure the hosts on which it no longer will be run.  A vendor can supply unconfigure scripts to "undo" the configuration performed by the configure script. 

The configure scripts are not run by swinstall and swremove when an alternate root directory is specified.  Instead, the swconfig command must be run after that software has been made available to client hosts, to configure those hosts.  Similarly, swconfig must be used on client hosts to unconfigure those hosts.  Configuration can also be deferred on software installed to the root directory /, for example when multiple configured versions have been allowed, by using the defer_configure option with swinstall. 

Other features of swconfig include:

• The swconfig command supports only configuration of compatible software by default, controllable through the allow_incompatible option. 

• If a fileset specifies a prerequisite on other software, that software must be in a "configured" state before the software specifying the dependency will be configured. 

• The swconfig command will configure multiple versions of a product if the user has set allow_multiple_versions=true.  The vendor must therefore detect and prevent multiple configured versions in their configure scripts, if that is necessary. 

• A vendor’s configure script is as useful for operations required for software updates as for new installs.  The scripts must also be designed to handle reinstall. 

Options

swconfig supports the following options:

-p Previews a configuration task by running the session through the analysis phase only. 

-v Turns on verbose output to stdout.  (The swconfig logfile is not affected by this option.)  Verbose output is enable by default, see the verbose option below. 

-u Causes swconfig to unconfigure the software instead of configuring it. 

-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.

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

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

-S session_file Execute swconfig based on the options and operands saved from a previous session, as defined in session_file.

Operands

The swconfig command supports the following syntax for each software_selection:

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

The version component supports either of these syntaxes:

[r=revision][,a=arch][,v=vendor][,vid=vendor_uuid][,l=location]

[instance_id]

The swconfig command supports the following syntax for each target_selection:

[host][:][/]

(For swconfig, the directory component of a target_selection must be /.) 

EXTERNAL INFLUENCES

Defaults File

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

/var/adm/sw/defaults - the system-wide default values,

$HOME/.sw/defaults - the user-specific default values. 

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

swconfig.option=value

The default values can be overridden by specifying an options file with the -X option, or by specifying -x option=value on the command line. 

Command Options
The following defaults are used to modify the default behavior of the swconfig command:

swconfig.select_local=true
If no target_selections are specified, select the local host as the target of the command. 

swconfig.logfile=/var/adm/sw/swconfig.log

This is the default command log file for the swconfig command. 

swconfig.verbose=1
Controls the verbosity of the swconfig output (stdout).  A value of 0 disables output to stdout.  (Error and warning messages are always written to stderr).  A value of 1 enables verbose messaging to stdout. 

swconfig.loglevel=1
Controls the log level for the events logged to the command logfile, and the target agent logfile. A value of 1 enables verbose logging to the logfiles.  A value of 2 enables very verbose logging to the logfiles. 

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

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

Target Task Options
These defaults are used to affect target behaviors. The are organized by when they are used in the process:

swconfig.mount_all_filesystems=true
By default, the swconfig command attempts to automatically mount all filesystems in the /etc/checklist file at the beginning of the analysis phase, to ensure that all listed filesystems are mounted before proceeding.  This policy helps to ensure that files are not loaded into a directory that may be below a future mount point. 

If set to false, the mount operation is not attempted, and no check of the current mounts is performed. 

swconfig.allow_incompatible=false
Requires that the software products which are being configured be "compatible" with the target selections.  (All of the target selections must match the list of supported systems defined for each selected product.)  If set to true, target compatibility is not enforced. 

swconfig.reconfigure=false
Prevents software which is already in the CONFIGURED state from being reconfigured. If set to true, CONFIGURED software can be reconfigured. 

swconfig.enforce_dependencies=true
Requires that all dependencies specified by the software_selections be resolved at the target_selections.

The swconfig, command will not proceed unless the dependencies have also been selected or already exist at the target in the correct state (INSTALLED or CONFIGURED).  This prevents unusable software from being configured on the system. 

If set to false, dependencies will still be checked, but not enforced.  Corequisite dependencies, if not enforced, may keep the selected software from working properly. Prerequisite dependencies, if not enforced, may cause the configuration to fail. 

swconfig.allow_multiple_versions=false
Prevents the configuration of another, independent version of a product when a version already is already configured at the target.

If set to true, another version of an existing product can be configured in its new location.  Multiple versions can only be installed if a product is locatable.  Multiple configured versions will not work unless the product supports it. 

Remote Procedure Call Options
These options apply to the DCE Remote Procedure Call used by swconfig:

swconfig.rpc_binding_info=ncadg_ip_udp:[2121]
Defines the protocol sequence(s) and endpoint(s) which will be used to contact swagentd.  This value should be consistent among all hosts that work together.  See sd(5) for details on specifying this option. 

swconfig.rpc_timeout=5
Relative length of the communications timout. 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 are not running the swagentd. 

Session File

Each invocation of the swconfig command defines a configuration session.  The invocation options, source information, software selections, and target hosts are saved before the configuration task actually commences.  This session is saved to the file $HOME/.sw/sessions/swconfig.last.  This session can be re-executed by using the file as input to swconfig (with the -S option.) 

The session file uses the same syntax as the defaults file.  Values in the defaults file are overridden by values from a session file, if specified.  These are in turn overidden by the corresponding command line option or parameter(s), if specified. 

Environment Variables

The swconfig program sets these environment variables for use by the configure scripts being executed:

SW_PATH

A PATH variable which defines a minimum set of commands available to for use in a control script. 

SW_ROOT_DIRECTORY

Defines the root directory in which the session is operating, either "/" or an alternate root directory.  This variable tells control scripts the root directory in which the products are installed.  A script must use this directory as a prefix to SW_LOCATION to locate the product’s installed files.  The configure script is only run when SW_ROOT_DIRECTORY is "/". 

SW_LOCATION

Defines the location of the product, which may have been changed from the default product directory.  When combined with the SW_ROOT_DIRECTORY, this variable tells scripts where the product files are located. 

SW_CONTROL_DIRECTORY

Defines the current directory of the script being executed, either a temporary catalog directory, or a directory within the Installed Products Database (IPD).  This variable tells scripts where other control scripts for the software are located (e.g. subscripts). 

Signals

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

Each agent will complete the configuration task (if the execution phase has already started) before it wraps up.  This avoids leaving software in a corrupt state. 

RETURN VALUES

The swconfig command returns:

0 The software_selections were successfully configured. 

1 The configure operation failed on all target_selections.

2 The configure operation failed on some target_selections.

DIAGNOSTICS

The swconfig command writes to stdout, stderr, and to specific logfiles. 

Standard Output

The swconfig command writes messages for significant events.  These include:

• a begin and end session message,

• selection, analysis, and execution task messages for each target_selection.

Standard Error

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

Logging

The swconfig command logs summary events the host where the command was invoked.  It logs detailed events to the swagent logfile associated with each target_selection.

Command Log
The swconfig command logs all stdout and stderr messages to the the logfile /var/adm/sw/swconfig.log.  (The user can specify a different logfile by modifying the logfile option.) 

Target Log
A swagent process performs the actual configure operation at each target_selection. The swagent logs events to the file /var/adm/sw/swagent.log. 

EXAMPLES

Configure the C and Pascal products on the local host:

swconfig cc pascal

Configure the C and Pascal products on remote hosts:

swconfig cc pascal @  hostA hostB hostC

Reconfigure the HP Omniback product:

swconfig -x reconfigure=true omniback

Configure the version of HP Omniback that was installed at /opt/omniback_v2.0:

swconfig omniback,l=/opt/omniback_v2.0

Unconfigure the software_selections listed in the file /tmp/install.products on the hosts listed in the file /tmp/install.hosts:

swconfig -u -f /tmp/install.products -t /tmp/install.hosts

FILES

/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 system-wide default values for some or all SD options. 

$HOME/.sw/defaults

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. 

/var/adm/sw/products/

The Installed Products Database (IPD), a catalog of all products installed on a system. 

AUTHOR

swconfig was developed by the Hewlett-Packard Company. 

SEE ALSO

swacl(8), swagentd(8), swcopy(8), swdepot(8), swinstall(8), swpackage(8), swremove(8), swverify(8), swpackage(4), sd(4), sd(5), and the HP OpenView Software Distributor Administrator’s Guide.

Hewlett-Packard Company  —  Software Distributor 2.0