swconfig(8)swconfig(8)NAMEswconfig - configure, unconfigure, or reconfigure installed software
SYNOPSISswconfig [-p] [-u] [-v] [-c catalog] [-C session_file] [-f soft‐
ware_file] [-S session_file] [-t target_file] [-x option=value]
[-X option_file] [software_selections] [@ target_selections]
STANDARDS
Interfaces documented on this reference page conform to industry stan‐
dards as follows:
POSIX 1387.2, XDSA
Refer to the standards(5) reference page for more information about
industry standards and associated tags.
DESCRIPTION
The swconfig command configures, unconfigures, and reconfigures
installed and linkinstalled software products for execution on the
specified targets. 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 con‐
figure 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 configura‐
tion 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_con‐
figure option with swinstall
Other features of swconfig include:
· The swconfig command supports only configuration of compati‐
ble 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.
· The ability to ask for a user response by running a script.
See the ask default option for more information.
Options
swconfig supports the following options:
-c catalog Specifies the pathname of an exported catalog
which stores copies of the response file or files
created by a request script (if -x ask=true or -x
ask=as_needed Response files are also stored in
the
-C session_file
Save the current options and operands to ses‐
sion_file. You can enter a relative or absolute
path with the file name. The default directory
for session files is $HOME/.sw/sessions/ You can
recall a session file with the -S option.
-f software_file
Read the list of software_selections from soft‐
ware_file instead of (or in addition to) the com‐
mand line.
-p Previews a configuration task by running the ses‐
sion through the analysis phase only.
-S session_file
Execute swconfig based on the options and oper‐
ands saved from a previous session, as defined in
session_file. You can save session information
to a file with the -C option.
-t target_file Read the list of target_selections from tar‐
get_file instead of (or in addition to) the com‐
mand line.
-u Causes swconfig to unconfigure the software
instead of configuring it.
-v Turns on verbose output to stdout. (The swconfig
logfile is not affected by this option.) Verbose
output is enabled by default; see the verbose
option below.
-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). Mul‐
tiple -x options can be specified.
-X option_file Read the session options and behaviors from
option_file.
Operands
Most SWMGR commands support two types of operands: followed by These
operands are separated by the "@" (at) character. This syntax implies
that the command operates on "software selections at targets".
Software Selections
The swconfig command supports the following syntax for each soft‐
ware_selection:
bundle[.product[.subproduct][.fileset]][,version]
product[.subproduct][.fileset][,version]
· The = (equals) relational operator lets you specify
selections with the following shell wildcard and pattern-
matching notations:
[ ] * ?
· Bundles and subproducts are recursive. Bundles can con‐
tain other bundles and subproducts can contain other sub‐
products.
· The * software specification selects all products. Use
this specification with caution.
The version component has the form:
[,r <op> revision][,a <op> arch][,v <op> vendor]
[,c <op> category][,q=qualifier][,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 revi‐
sion 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 compo‐
nents 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.
· No space or tab characters are allowed in a software
selection.
· The software can take the place of the version component.
It has the form:
[instance_id]
within the context of an exported catalog, where is an
integer that distinguishes versions of products and bun‐
dles with the same tag.
The \* software specification selects all products. It is not allowed
when removing software from the root directory /
Target Selections
swconfig
supports this syntax for each target_selection.
[host][:][/directory]
The : (colon) is required if both a host and directory are specified.
EXTERNAL INFLUENCES
Default Options
In addition to the standard options, several SWMGR 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 prefix denotes one of the SWMGR 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:
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 swconfig are:
agent_auto_exit=true
Causes the target agent to automatically exit after
Execute phase, or after a failed Analysis phase. This
is forced to false when the controller is using an
interactive UI, or when -p (preview) is used. This
enhances network reliability and performance. The
default is true - the target agent will automatically
exit when appropriate. If set to false the target
agent will not exit until the controller ends the ses‐
sion.
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 tar‐
get agents more quickly detect lost network connec‐
tions 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 environ‐
ment. For command line invocation, a value between 10
minutes and 60 minutes is suitable. A value of 60 min‐
utes or more is recommended when the GUI will be used.
The default of 10000 is slightly less than 7 days.
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.
allow_multiple_versions=false
Prevents the configuration of another, independent
version of a product when a version already is con‐
figured at the target.
If set to true another version of an existing product
can be configured in its new location. Multiple ver‐
sions can only be installed if a product is locatable.
Multiple configured versions will not work unless the
product supports it.
ask=false When ask=true executes a which asks for a user
response. If ask=as_needed the swask command first
determines if a response file already exists in the
control directory and executes the script only when a
response file is absent.
If set to ask=true or ask=as_needed you can use the -c
option to specify the pathname of an exported catalog
to store copies of the response file or files created
by the script.
See swask(8) for more information on scripts.
autoselect_dependencies=true
Controls the automatic selection of prerequisite,
corequisite, and exrequisite software that is not
explicitly selected by the user. This option does not
apply to swconfig-u The default is: true. The requi‐
site software will be automatically selected for con‐
figuration. Specifying false causes requisite soft‐
ware, which is not explicitly selected, to not be
automatically selected for configuration.
autoselect_dependents=false
Controls the automatic selection of dependent software
that is not explicitly selected by the user. A depen‐
dent is the opposite of a requisite. A dependent
fileset has established either a prerequisite or a
corequisite on the fileset under discussion. Specify‐
ing true causes dependent software to be automatically
selected for unconfiguration. The default, false
causes dependent software, which is not explicitly
selected, to not be automatically selected for uncon‐
figuration.
controller_source
Location of a depot for the controller to access to
resolve selections. This has no effect on which
sources the target uses. Specify this as host, /path,
or host:/path. Useful for reducing network traffic
between controller and target.
enforce_dependencies=true
Requires that all dependencies specified by the soft‐
ware_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 CON‐
FIGURED). 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 and exrequisite dependencies,
if not enforced, may cause the configuration to fail.
enforce_scripts=true
Controls the handling of errors generated by scripts.
If true, and the vendor-supplied script returns an
error, the configure or unconfigure operation stops.
An error message appears reporting that the execution
phase failed. If false, swconfig attempts to continue
operation. A warning message appears reporting that
the execution succeeded.
installed_software_catalog=products
Defines the directory path where the Installed Prod‐
ucts Database (IPD) is stored. When set to an absolute
path, this option defines the location of the IPD.
When this option contains a relative path, the SWMGR
controller appends the value to /var/adm/sw to deter‐
mine the path to the IPD. For alternate roots, this
path is resolved relative to the location of the
alternate root. This option does not affect where
software is installed, only the IPD location.
log_msgid=0
Controls whether numeric identification numbers are
prepended to logfile messages produced by SWMGR. A
value of 0 (default) indicates no such identifiers are
attached. Values of 1-4 indicate that identifiers are
attached to messages:
1 applies to ERROR messages only
2 applies to ERROR and WARNING messages
3 applies to ERROR, WARNING, and NOTE messages
4 applies to ERROR, WARNING, NOTE, and certain other
logfile messages.
logdetail=false
Controls the amount of detail written to the logfile.
When set to true this option adds detailed task infor‐
mation (such as options specified, progress state‐
ments, and additional summary information) to the log‐
file. This information is in addition to log informa‐
tion controlled by the loglevel option.
See loglevel below and the sd(5) manual page, by typ‐
ing man 5 sd , for more information.
logfile=/var/adm/sw/swconfig.log
This is the default command log file for the swconfig
command.
loglevel=1
Controls the log level for the events logged to the
command logfile, the target agent logfile, and the
source agent logfile. This information is in addition
to the detail controlled by the logdetail option. (See
logdetail above and the sd(5) manual page, by typing
man 5 sd , for more information.) A value of
0 provides no information to the logfile.
1 enables verbose logging to the logfiles.
2 enables very verbose logging to the logfiles.
mount_all_filesystems=true
By default, the swconfig command attempts to automati‐
cally mount all filesystems in the /etc/fstab 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.
reconfigure=false
Prevents software which is already in the CONFIGURED
state from being reconfigured. If set to true CONFIG‐
URED software can be reconfigured.
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 on which the other com‐
mands use to contact the daemon. If the connection
fails for one protocol sequence, the next is
attempted. SWMGR supports both the tcp
(ncacn_ip_tcp:[2121]) and udp (ncadg_ip_udp:[2121])
protocol sequence on most platforms.
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 are not running the
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.
select_local=true
If no target_selections are specified, select the
local host as the target of 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.
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 sepa‐
rated by spaces.
verbose=1 Controls the verbosity of the output (stdout). A value
of
0 disables output to stdout. (Error and warning
messages are always written to stderr).
1 enables verbose messaging to stdout.
write_remote_files=false
Prevents the configuring of files on a target which
exists on a remote (NFS) filesystem. All files on a
remote filesystem will be skipped.
If set to true and if the superuser has write permis‐
sion on the remote filesystem, the remote files will
not be skipped, but will be configured.
Session File
Each invocation of the swconfig command defines a configuration ses‐
sion. The invocation options, source information, software selections,
and target hosts are saved before the installation or copy task actu‐
ally commences. This lets you re-execute the command even if the ses‐
sion ends before proper completion.
Each session is automatically saved to the file $HOME/.sw/ses‐
sions/swremove.last This file is overwritten by each invocation of
swconfig
You can also save session information to a specific file by executing
swconfig with the -C session__file option.
A session file uses the same syntax as the defaults files. If you do
not specify a specific path for the session file, the default location
is $HOME/.sw/sessions/
To re-execute a session file, specify the session file as the argument
for the -S session__file option of swconfig
Note that when you re-execute a session file, the values in the session
file take precedence over values in the system defaults file. Like‐
wise, any command line options or parameters that you specify when you
invoke swconfig take precedence over the values in the session file.
Environment Variables
The environment variable that affects the swconfig command is:
LANG Determines the language in which messages are dis‐
played. 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 SWMGR agent and daemon
log messages are displayed is set by the system con‐
figuration 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.
LC_ALL Determines the locale to be used to override any val‐
ues for locale categories specified by the settings of
LANG or any environment variables beginning with LC_
LC_CTYPE Determines the interpretation of sequences of bytes of
text data as characters (e.g., single-versus multibyte
characters in values for vendor-defined attributes).
LC_MESSAGES
Determines the language in which messages should be
written.
LC_TIME Determines the format of dates (create_date and
mod_date) when displayed by swlist Used by all utili‐
ties when displaying dates and times in stdout logging
TZ Determines the time zone for use when displaying dates
and times.
Environment variables that affect scripts are:
SW_CATALOG
Holds the path to the Installed Products Database
(IPD), relative to the path in the SW_ROOT_DIRECTORY
environment variable. Note that you can specify a path
for the IPD using the installed_software_catalog
default option.
SW_CONTROL_DIRECTORY
Defines the current directory of the script being exe‐
cuted, either a temporary catalog directory, or a
directory within in the Installed Products Database
(IPD). This variable tells scripts where other con‐
trol scripts for the software are located (e.g. sub‐
scripts).
SW_CONTROL_TAG
Holds the tag name of the control_file being executed.
When packaging software, you can define a physical
name and path for a control file in a depot. This lets
you define the control_file with a name other than its
tag and lets you use multiple control file definitions
to point to the same file. A control_file can query
the SW_CONTROL_TAG variable to determine which tag is
being executed.
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_PATH A PATH variable which defines a minimum set of com‐
mands available for use in a control script (e.g.
/sbin:/usr/bin
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_SESSION_OPTIONS
Contains the pathname of a file containing the value
of every option for a particular command, including
software and target selections. This lets scripts
retrieve any command options and values other than the
ones provided explicitly by other environment vari‐
ables. For example, when the file pointed to by
SW_SESSIONS_OPTIONS is made available to a script, the
targets option contains a list of software_collec‐
tion_specs for all targets specified for the command.
When the file pointed to by SW_SESSIONS_OPTIONS is
made available to other scripts, the targets option
contains the single software_collection_spec for the
targets on which the script is being executed.
SW_SOFTWARE_SPEC
This variable contains the fully qualified software
specification of the current product or fileset. The
software specification allows the product or fileset
to be uniquely identified.
Signals
The swconfig command catches the signals SIGQUIT and SIGINT, and
SIGUSR1. If these signals are received, swconfig prints a message,
sends a Remote Procedure Call (RPC) to the agents to wrap up, and then
exits.
The agent ignores SIGHUP, SIGINT, and SIGQUIT. It immediately exits
gracefully after receiving SIGTERM, SIGUSR1, or SIGUSR2. Killing the
agent may leave corrupt software on the system, and thus should only be
done if absolutely necessary. Note that when an SWMGR command is
killed, the agent does not terminate until completing the task in
progress.
The daemon ignores SIGHUP, SIGINT and SIGQUIT. It immediately exits
gracefully after receiving SIGTERM and SIGUSR2. After receiving
SIGUSR1, it waits for completion of a copy or remove from a depot ses‐
sion before exiting, so that it can register or unregister depots if
necessary. Requests to start new sessions are refused during this wait.
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 log‐
files.
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 tar‐
get_selection.
Standard Error
The swconfig command also writes messages for all WARNING and ERROR
conditions to stderr.
Logging
The swconfig command logs summary events at 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 use any associated response files generated by a request
script, and save response files under /tmp/resp1
swconfig-x ask=true -c /tmp/resp1 Product1
Reconfigure the Compaq XYZ product:
swconfig-x reconfigure=true XYZ
Configure the version of Compaq XYZ that was installed at /opt/XYZ_v2.0
swconfig XYZ,l=/opt/XYZ_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
Configure the C and Pascal products on remote hosts:
swconfig cc pascal @ hostA hostB hostC
LIMITATIONS
The SWMGR version of swconfig does not support the configuration,
unconfiguration, or reconfiguration of installed software on remote
targets.
FILES
$HOME/.swdefaults
Contains the user-specific default values for some or all SWMGR
software management command options.
$HOME/.sw/sessions/
Contains session files automatically saved by the SWMGR soft‐
ware management commands, or explicitly saved by the user.
/usr/lib/sw/sys.defaults
Contains the master list of current SWMGR options with their
default values.
/var/adm/sw/
The directory which contains all configurable and non-config‐
urable data for SWMGR software management commands. This
directory is also the default location of logfiles.
/var/adm/sw/defaults
Contains the active system-wide default values for some or all
SWMGR software management command options.
/var/adm/sw/getdate.templ
Contains the set of date/time templates used when scheduling
jobs.
/var/adm/sw/products/
The Installed Products Database (IPD), a catalog of all prod‐
ucts installed on a system.
SEE ALSOsd(4), sd(5), swacl(8), swagentd(8), swask(8), swconfig(8), swget‐
tools(8), swinstall(8), swlist(8), swmodify(8), swpackage(8), swpack‐
age(4), swreg(8), swremove(8), swverify(8), and the Managing Tru64 UNIX
Software With the SysMan Software Manager reference manual.
swconfig(8)
