swinstall(8)swinstall(8)NAMEswinstall - install and configure software products
swcopy - copy software products for subsequent installation or distri‐
bution
SYNOPSISswinstall [-p] [-r] [-v] [-c catalog] [-C session_file] [-f soft‐
ware_file] [-s source] [-S session_file] [-t target_file] [-x
option=value] [-X option_file] [software_selections] [@ tar‐
get_selections]
swcopy [-p] [-v] [-C session_file] [-f software_file] [-s source] [-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 swinstall command installs the software_selections from a software
source to either the local host. By default, the software is config‐
ured for use on the target after it is installed. (The software is not
configured when installed into an alternate root directory.)
The swcopy command copies or merges software_selections from a software
source to one or more software depot target_selections These depots can
then be accessed as a software source by the swinstall command.
Features and Differences between swinstall and swcopy
The key difference between swinstall and swcopy is that swinstall
installs software for actual (or eventual) use, while swcopy copies
software into a depot, making it available as a source for installation
by swinstall.
NOTE: To copy to a tape, see the swpackage(8) manpage.
Other features (differences) include:
· The swinstall command executes several vendor-supplied
scripts during the installation and configuration of the
software_selections. The swcopy command does not execute
these scripts. The swinstall command supports the following
scripts:
request a script that asks the user questions and
stores responses in a file. The response file
can then be used by configuration or other
scripts.
checkinstall a script executed during the analysis of a
target_selection, it checks that the instal‐
lation can be attempted. If this check
fails, the software product is not installed.
preinstall a script executed immediately before the
software's files are installed.
postinstall a script executed immediately after the soft‐
ware's files are installed.
configure a script executed during the configuration of
a target_selection, it configures the target
for the software (and the software for the
target). The preinstall and postinstall
scripts are not intended to be used for con‐
figuration tasks. They are to be used for
simple file management needs such as removing
obsolete files from the previous revision
(which was just updated).
unpreinstall a script executed immediately after the soft‐
ware's actual files are restored if the soft‐
ware install will fail and the autore‐
cover_product option is set to true. The
script undoes the steps performed by prein‐
stall script.
unpostinstall a script executed immediately before the
software's actual files are restored if the
software install failed and the autore‐
cover_product option is set to true. The
script undoes the steps performed by postin‐
stall script.
· When a depot is created or modified using swcopy, are built
that describe the depot (as opposed to the (IPD) files that
are built by the swinstall command).
· By default, the swinstall command only allows the selection
of compatible software from the source. This constraint
ensures that the architecture of the software matches that of
the target_selections. No compatibility checks are performed
by the swcopy command. (A depot can be a repository of soft‐
ware targeted for a variety of architectures and operating
systems.)
· By default, swinstall supports updates to higher revisions of
software. If a software_selection of the same revision is
already installed, swinstall will not reinstall it. If a
software_selection has a lower revision than the same soft‐
ware which is already installed, swinstall will not reinstall
it. (The user can override these behaviors with control
options.)
· The swinstall command creates hard links and symbolic links
as specified for the software. If it encounters a symbolic
link where it expected a regular file, swinstall follows the
symbolic link and updates the file to which it points.
· The swinstall command does not remove a product's current
files before installing the new ones. A fileset's install
scripts can do that, if necessary. Files being replaced are
overwritten unless they are in use. If in use, they are
unlinked or moved to #<file>. If the autorecover_product
option is set to true; all files are saved to #<file>, and
restored if the install fails.
· The swinstall command supports kernel building scripts and
rebooting. Before or after software that modifies the kernel
is installed or updated, swinstall executes system-specific
scripts to prepare for or build the new version of the ker‐
nel. The remaining software_selections are then installed.
These scripts are defined in swagent options and include:
install_setup_cmd, system_prep_cmd, kernel_build_cmd, and
install_cleanup_cmd.
After software that requires a system reboot is installed or
updated, swinstall automatically reboots the system. The
reboot command is defined by the swagent option: reboot_cmd.
When updating the operating system, you must use first use
the setld command to get the newest version of swinstall.
(See setld(8) for more information.) Then you should install
kernel software first to ensure that a new kernel can be gen‐
erated before the rest of the operating system is updated.
After all the software_selections are updated or installed,
swinstall reboots using the new kernel, then executes the
configure scripts for each software_selection. After these
scripts complete, it reboots the system again to restore it
to its normal state.
· No kernel building or system reboots are performed by swcopy.
· Both the swinstall and swcopy commands perform various checks
prior to installing or copying the software_selections, for
example disk space analysis.
Options
swinstall and swcopy support the following options:
private root (Tru64 UNIX only).
When run in the linkinstall mode,
swinstall:
· Creates NFS mounts to the soft‐
ware to make it accessible from
the target. This may involve
delayed mounting for alternate
roots.
· Modifies the target's fstab
file.
· Modifies the source's exports
file to add mount permission for
the target.
Mounts are created by examining the
share_link product attribute. Not
all products support linkinstall.
Some products may be visible with‐
out creating a new mount if they
reside under an old one.
-p Previews an install task by running
the session through the analysis
phase only.
-r (Optional) Causes the command to
operate on target_selections that
are alternate root directories
(root filesystems other than /).
Note that you cannot use this
option to relocate software during
installation. You must use the
l=location syntax in the software
selection component.
-v Turns on verbose output to stdout.
(The swinstall or swcopy logfile is
not affected by this option.) Ver‐
bose output is enabled by default;
see the verbose option below.
-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). The response files
are also stored in the after the
installation process is complete.
-C session_file
Save the current options and oper‐
ands to session_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_selec‐
tions from software_file instead of
(or in addition to) the command
line.
-s source Specifies the source depot (or
tape) from which software is
installed or copied. (SWMGR can
read both tar and cpio tape
depots.) The default source type
is directory. The syntax is:
[host][:][/directory] A host may be
specified by its host name, domain
name, or internet address. A
directory must be specified by an
absolute path.
-S session_file
Execute swinstall or swcopy based
on the options and operands saved
from a previous session, as defined
in session_file. You can save ses‐
sion information from a command-
line session with the -C ses‐
sion_file 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 speci‐
fied.
-X option_file Read the session options and behav‐
iors from option_file.
Operands
The swinstall and swcopy 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 selections operands consist of
swinstall and swcopy support the following syntax for
each software_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:
[ ], *, ?
For example, the following expression
installs all bundles and products with tags
that end with "man":
swinstall-s sw_server *man
· Bundles and subproducts are recursive.
Bundles can contain other bundles and sub‐
products can contain other subproducts.
For example:
swinstall
bun1.bun2.prod.sub1.sub2.fset,r=1.0
or (using expressions):
swinstall bun[12].bun?.prod.sub*,a=Tru64
UNIX
· The * software specification selects all
products. Use this specification with cau‐
tion.
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 loca‐
tion other than the default product direc‐
tory.
· 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 revi‐
sions 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 ver‐
sion 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 com‐
ponents.
· 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 can take the place of the ver‐
sion component. It has the form:
[instance_id]
within the context of an exported catalog,
where is an integer that distinguishes ver‐
sions of products and bundles with the same
tag.
The \* software specification selects all products. It is
not allowed when removing software from the root direc‐
tory /.
Target Selection
The swinstall and swcopy commands support the following
syntax for each target_selection. The : (colon) is
required if both a host and directory are specified.
[host][:][/directory]
A host may be specified by its host name, domain name, or
internet address. A directory must be specified by an
absolute path.
EXTERNAL INFLUENCES
Default Options
In addition to the standard options, several SWMGR behav‐
iors 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 swinstall and swcopy commands. If a default value
exists, it is listed after the "=".
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 automatically exits
when appropriate. If set to false, the
target agent will not exit until the
controller ends the session.
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 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. The default of 10000 is
slightly less than 7 days.
allow_downdate=false
(Applies only to swinstall.) Prevents
the installation of an older revision of
fileset that already exists at the tar‐
get(s). (Many software products do not
support "downdating".) If set to true,
the older revision can be installed.
allow_incompatible=false
(Applies only to swinstall.) Requires
that the software products which are
being installed be "compatible" with the
target selections. (All of the target
selections must match the list of sup‐
ported systems defined for each selected
product.) If set to true, target com‐
patibility is not enforced.
allow_multiple_versions=false
(Applies only to swinstall.) Prevents
the installation of another, independent
version of a product when a version
already is already installed at the tar‐
get.
If set to true, another version of an
existing product can be installed into a
new location. Multiple versions can
only be installed if a product is locat‐
able. Multiple configured versions will
not work unless the product supports it.
ask=false (Applies only to swinstall.) When
ask=true, executes a request script
which asks for a user response. If
ask=as_needed, the swinstall command
first determines if a response file
already exists in the catalog specified
in the -c option or source depot and
executes the request 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 request script.
See swask(8) for more information on
request scripts.
autoreboot=false
(Applies only to swinstall.) Prevents
the installation of software requiring a
reboot from the non-interactive inter‐
face. If set to true, this software can
be installed and the target system(s)
will be automatically rebooted.
An interactive session always asks for
confirmation before software requiring a
reboot is installed.
autorecover=false
This option permits automatic recovery
of original filesets if an installation
error occurs. The cost is a temporary
increase in disk space and slower per‐
formance. The default value of true
causes swinstall to remove the original
files as a fileset is updated. If an
error occurs during the installation
(e.g. network failure), then the origi‐
nal files are lost, and you must rein‐
stall the fileset.
If set to true, all files are saved as
backup copies until the current fileset
finishes loading. If an error occurs
during installation, the fileset's orig‐
inal files are replaced, and swinstall
continues to the next fileset in the
product or the product postinstall
script.
When set to true, this option also
affects scripts. For example, if a pre‐
install script fails, this option causes
the corresponding unpreinstall script to
execute. See Managing Tru64 UNIX Soft‐
ware With the SysMan Software Manager
for complete information.
autorecover_product=false
(Applies only to swinstall.) Causes
swinstall to remove the original files
as they are updated. If an error occurs
during the installation (e.g. network
failure), then the original files are
lost, and the installation must be re-
tried.
If set to true, all files are saved as
backup copies until all filesets in the
current product loading are complete;
then they are removed. At the cost of a
temporary increase in disk space and
slower performance, this allows for
automatic recovery of the original file‐
sets in that product if the load fails.
When set to true, this option also
affects scripts. For example, if a pre‐
install script fails, this option causes
the corresponding unpreinstall script to
execute. See Managing Tru64 UNIX Soft‐
ware With the SysMan Software Manager
for complete information.
autoselect_dependencies=true
Automatically select dependencies when
software is being selected. When set to
true, and any software which has depen‐
dencies is selected for install, swin‐
stall or swcopy makes sure that the
dependencies are met. If they are not
already met, they are automatically
selected for you. If set to false,
automatic selections are not made to
resolve requisites. When set to
as_needed, autoselected dependencies are
operated only if the dependency is not
already met on the target.
autoselect_patches=true
Automatically selects the latest patches
(based on superseding and ancestor
attributes) for a software object that a
user selects for a swinstall or swcopy
operation. When set to false, the
patches corresponding to the selected
object are not automatically selected.
The patch_filter= option can be used in
conjunction with autoselect_patches.
autoselect_reference_bundles=true
If true, bundles that are are automati‐
cally installed or copied, along with
the software it is made up of. If
false, the software can be installed, or
copied, without automatically including
sticky bundles that contain it.
controller_source=
Specifies the location of a depot for
the controller to access to resolve
selections. Setting this option can
reduce network traffic between the con‐
troller and the target. Use the target
selection syntax to specify the loca‐
tion: [host][:][/directory]
The controller_source_option supports
the same syntax as the -s source option.
This option has no effect on which
sources the target uses and is ignored
when used with the Interactive User
Interface.
create_target_path=true
Causes the agent to create the target
directory if it does not already exist.
If set to false, a new target directory
is not created. This option can prevent
the erroneous creation of new target
depots or new alternate root directo‐
ries.
compress_files=false
(Applies only to swcopy.) If set to
true, files not already compressed are
compressed before transfer from a
source. This enhances performance on
slower networks for swinstall and
swcopy, and results in smaller depots
for swcopy, unless uncompress_files is
also set to true.
defer_configure=false
(Applies only to swinstall.) Causes
swinstall to automatically configure the
software_selections after they are
installed. When an alternate root
directory is specified, swinstall never
performs the configuration task, since
only hosts using the software should be
configured. If set to true, this option
allows configuration to be deferred even
when the root directory is /.
An additional version of a product will
not be configured if another version is
already configured. The swconfig com‐
mand must be run separately.
distribution_source_directory=/var/spool/sw
Defines the default location of the
source depot. This syntax can be The -s
option overrides this value.
distribution_target_directory=/var/spool/sw
(Applies only to swcopy.) Defines the
default location of the target depot.
enforce_dependencies=true
Requires that all dependencies specified
by the software_selections be resolved
either in the specified source, or at
the target_selections themselves.
The swinstall and swcopy commands will
not proceed unless the dependencies have
also been selected or already exist at
the target in the correct state
(INSTALLED or AVAILABLE). This prevents
unusable software from being installed
on the system. It also ensures that
depots contain usable sets of software.
If set to false, dependencies are still
checked, but not enforced. Corequisite
dependencies, if not enforced, may keep
the selected software from working prop‐
erly. Prerequisite dependencies, if not
enforced, may cause the installation or
configuration to fail.
enforce_dsa=true
Prevents the command from proceeding
past the analysis phase if the disk
space required is beyond the available
free space of the impacted filesys‐
tem(s). If set to false, the install or
copy operation uses the filesystems'
minfree space and may fail because it
reaches the filesystem's absolute limit.
enforce_kernbld_failure=true
(Applies only to swinstall.) Prevents
swinstall from proceeding past the ker‐
nel build phase if the kernel build pro‐
cesses fail. If set to false, the
install operation continues (without
suspension if in the interactive mode)
despite failure or warnings from either
the system preparation process or the
kernel build process.
When set to the default value of
true, this option generates an error if
a command tries to relocate a non-relo‐
catable fileset. (Relocatable filesets
are packaged with the is_relocatable
attribute set to true). When set to
false, the usual error handling process
is overridden, and SWMGR permits the
command to relocate the fileset.
enforce_scripts=true
Controls the handling of errors gener‐
ated by scripts. If true, and a script
returns an error, an error message
appears reporting that the execution
phase failed. If false, swinstall
attempts to continue operation. A warn‐
ing message appears saying that the
analysis or execution phase succeeded.
The message identifies the specific
swinstall phase (checkinstall, prein‐
stall, postinstall, or configure).
fix_explicit_directories=false
Controls the swinstall response to
explicitly packaged software (software
packaged with explicit file specifica‐
tions). The default value of false
causes swinstall to set permissions (as
specified in the product specification
file) on new directories but never on
pre-existing directories. When set to
true, also sets the permissions on pre-
existing directories.
installed_software_catalog=products
Defines the directory path where the
Installed Products Database (IPD) is
stored. When set to an absolute path,
this option defines the location of the
IPD. When this option contains a rela‐
tive path, the SWMGR controller appends
the value to /var/adm/sw to determine
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 soft‐
ware is installed, only the IPD loca‐
tion.
layout_version=1.0
Specifies the POSIX layout_version to
which the SWMGR commands conform when
writing distributions and swlist output.
Supported values are "1.0" (default) and
"0.8".
SWMGR object and attribute syntax con‐
forms to the specification of the stan‐
dard. SWMGR commands still accept the
keyword names associated with the older
layout version, but you should use lay‐
out_version=0.8 only to create distribu‐
tions readable by older versions of
SWMGR.
See the description of the layout_ver‐
sion option in sd(5) for more informa‐
tion.
logdetail=false
Controls the amount of detail written to
the logfile. When set to true, this
option adds detailed task information
(such as options specified, progress
statements and additional summary infor‐
mation) to the logfile. This information
is in addition to log information con‐
trolled by the loglevel option.
See loglevel=1 and the sd(5) manual page
by typing man 5 sd for more information.
logfile=/var/adm/sw/swremove.log
This is the default command log file for
the swinstall command.
loglevel=1
Controls the log level for the events
logged to the command logfile, the tar‐
get agent logfile, and the source agent
logfile. This information is in addition
to the detail controlled by the logde‐
tail option. (See logdetail=false and
the sd(5) manual page for more informa‐
tion.) A value of:
0 provides no information to the log‐
file.
1 enables verbose logging to the log‐
files.
2 enables very verbose logging,
including per-file messages, to the
logfiles.
log_msgid=0
Controls whether numeric identification
numbers are prepended to logfile mes‐
sages produced by SWMGR:
0 (default) No identifiers are
attached to messages.
1 Applies to ERROR messages only.
2 Applies to ERROR and WARNING mes‐
sages.
3 Applies to ERROR, WARNING, and NOTE
messages.
4 Applies to ERROR, WARNING, NOTE, and
certain other logfile messages.
match_target=false
(Applies only to swinstall.) If set to
true, software selection is done by
locating filesets on the source that
match the target system's installed
filesets. If multiple targets are spec‐
ified, the first in the list is used as
the basis for selections.
max_targets=25
When set to a positive integer, SWMGR
limits the number of concurrent install
or copy operations to the number speci‐
fied. As each copy or install operation
completes, another target is selected
and started until all targets have been
completed.
Server and network performance deter‐
mines the optimal setting; a recommended
starting point is 25 (the default
value). If you set this option to a
value of less than one, SWMGR attempts
to install or copy to all targets at
once.
mount_all_filesystems=true
Attempt to 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 direc‐
tory that may be below a future mount
point.
If set to false, the mount operation is
not attempted, and no check of the cur‐
rent mounts is performed.
os_name (Applies only to swinstall.) This
option can be used in conjunction with
os_release to specify the desired OS
name during an Tru64 UNIX update. The
os_name option should only be specified
from the command line. Refer to the
SWMGR readme file for correct syntax.
You can display the readme file by
entering:
swlist -a readme -l product SW-DIST
os_release
(Applies only to swinstall.) This
option can be used in conjunction with
os_name to specify the desired OS
release during an Tru64 UNIX update. The
os_release option should only be speci‐
fied from the command line. Refer to
the SWMGR readme file for correct syn‐
tax. You can display the readme file by
entering:
swlist -a readme -l product SW-DIST
patch_filter=software_specification
This option can be used in conjunction
with the autoselect_patches or
patch_match_target options to filter the
selected patches to meet the criteria
specified by software_specification.
The default value of this option is *.*.
patch_match_target=false
If set to true, this option selects the
latest patches (software identified by
the is_patch=true attribute) that corre‐
spond to software on the target root or
depot.
The patch_filter= option can be used in
conjunction with patch_match_target.
patch_save_files=true
Saves the original versions of files
modified by patches, which permits the
future rollback of a patch. Patched
files are saved to /var/adm/sw/save.
When set to false, patches cannot be
rolled back (removed) unless the base
software modified by the patch is
removed at the same time.
To commit a patch by removing the corre‐
sponding saved files, use the swmodify
command's patch_commit option.
recopy=false
(Applies only to swcopy.) Do not copy a
fileset that is already available on the
target at the same version. If
recopy=true, copy the fileset in any
case.
register_new_depot=true
(Applies only to swcopy.) Causes swcopy
to register a newly created depot with
the local swagentd. This action allows
other SWMGR commands to automatically
"see" this depot. If set to false, a
new depot is not automatically regis‐
tered. It can be registered later with
the swreg command.
register_new_root=true
(Applies only to swinstall.) Causes
alternate roots to be registered during
swinstall. These can be listed with
swlist.
reinstall=false
When re-installing an existing revision
of a fileset, this option causes that
fileset to be skipped, i.e. not re-
installed. If set to true, the fileset
is re-installed. See also recopy=false.
reinstall_files=true
Causes all the files in a fileset to
always be reinstalled or recopied, even
when the file already exists at the tar‐
get and is identical to the new file.
If set to false, files that have the
same checksum (see next option), size
and timestamp are not re-installed.
This check enhances performance on slow
networks or slow disks.
reinstall_files_use_cksum=true
This option affects the operation when
the reinstall_files option is set to
false. It causes the checksums of the
new and old file to be computed and com‐
pared to determine if the new file
should replace the old one. (The check‐
sum is slower, but is a more robust way
to check for files being equivalent.)
If set to false, the checksums are not
computed, and files are reinstalled or
not based only on their size and time‐
stamp.
remove_obsolete_filesets=false
(Applies to swcopyonly Controls whether
swcopy automatically removes obsolete
filesets from target products in the
target depot. If set to true, swcopy
removes obsolete filesets from the tar‐
get products that were written to during
the copy process. Removal occurs after
the copy is complete. Filesets are
defined as obsolete if they were not
part of the most recent packaging of the
product residing on the source depot.
retry_rpc=1
Defines the number of times a lost
source connection is retried during file
transfers in swinstall or swcopy. A
lost connection is one that has timed
out. When used in conjunction with the
rpc_timeout option, the success of
installing over slow or busy networks
can be increased. If set to zero, any
rpc_timeout to the source causes the
task to abort. If set from 1 to 9, the
install of each fileset is attempted
that number of times. The rein‐
stall_files option should also be set to
false to avoid installing files within
the fileset that were successfully
installed.
This option also applies to the con‐
troller contacting the agent. If the
agent session fails to start for any
reason, the controller tries to recon‐
tact that agent for the number of times
specified in retry_rpc, using the values
from the retry_rpc_interval option to
determine how long to wait between each
attempt to recontact the agent.
retry_rpc_interval={1 2 4 8 15}
Specifies in minutes the length of the
interval for repeated attempts to make a
connection to a target after an initial
failure. Used in conjunction with the
retry_rpc option. If the number of val‐
ues in this option equals the value of
retry_rpc, SWMGR tries reestablishing a
source connection for the number of
times specified in retry_rpc. If the
number of values in retry_rpc_interval
is less than the value in retry_rpc,
SWMGR repeats the final interval value
until the number of retries matches
retry_rpc. For example, if an agent
session failed to start and retry_rpc
was set to 10 and retry_rpc_interval was
set to the default values, the SWMGR
controller would attempt to re-contact
the agent after 1 minute for the first
retry, then 2 minutes for the second
retry, 4 for the third, then 8, then 15
for all additional retries until ten
retries were attempted. If both options
were set to five, the controller would
try to contact the target five times
over a 30 minute period.
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 dae‐
mon. 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. See the sd(5) man
page by typing man 5 sd for more infor‐
mation.
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 give
faster recognition on attempts to con‐
tact hosts that are not up or not run‐
ning swagentd. Each value is approxi‐
mately 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 pro‐
tocol sequence.
select_local=true
If no target_selections are specified,
select the default root directory /
(swinstall), or the default tar‐
get_directory (swcopy), at 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.
source_cdrom=/SWMGR_CDROM
Defines the default location of the
source CD-ROM using the syntax
source_tape=/dev/ntape/tape0
Defines the default location of the
source tape, usually the character-spe‐
cial file of a local tape device. If
the host:path syntax is used, the host
must match the local host. The -s
option overrides this value. (SWMGR can
read both tar and cpio tape depots.)
source_type=directory
Defines the default source type: cdrom,
directory, or tape. The source type
derived from the -s option overrides
this value. (SWMGR can read both tar and
cpio tape depots.)
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.
uncompress_files=false
(Applies only to swcopy.) If set to
true, files being transferred from a
source are uncompressed before swcopy
store them on the target depot.
use_alternate_source=false
Empowers each target agent to use its
own, configured alternate source,
instead of the one specified by the
user. If false, each target agent uses
the same source (the source specified by
the user and validated by the command).
If true, each target agent uses its own
configured value for the source.
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 installation or copying of
files to a target which exists on a
remote filesystem. All files destined
for a remote filesystem are skipped.
If set to true and if the superuser has
write permission on the remote filesys‐
tem, the remote files are installed or
copied.
Session File
Each invocation of the swinstall or swcopy command
defines an installation or copy session. The invocation
options, source information, software selections, and
target hosts are saved before the installation or copy
task actually commences. This lets you re-execute the
command even if the session ends before proper comple‐
tion.
Each session is saved to the file $HOME/.sw/ses‐
sions/swinstall{swcopy}.last. This file is overwritten
by each invocation of swinstall or swcopy.
You can also save session information from interactive or
command-line sessions. 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 swinstall or swcopy with
the -C session__file option.
A session file uses the same syntax as the defaults
files. You can specify an absolute path for a session
file. If you do not specify a directory, the default
location for a session file is $HOME/.sw/sessions/.
To re-execute a saved session from an interactive ses‐
sion, 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 session__file
option of swinstall or swcopy.
Note that 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
or parameters that you specify when you invoke swinstall
or swcopy take precedence over the values in the session
file.
Software and Target Lists
Most SWMGR commands support software and target selec‐
tions from separate input files (see the -f and -t com‐
mand-line options). Software and targets specified in
these files will be selected for operation. swinstall
and swcopy also support an interactive read and save of
target and software groups. Target and software groups
can be saved in files (default location $HOME/.sw/tar‐
gets/and and then selected in subsequent swinstall and
swcopy operations.
Additionally, the swinstall and swcopy interactive user
interfaces read a default list of hosts on which to oper‐
ate. The list is stored in:
/var/adm/sw/defaults.hosts the sys‐
tem-wide
default
list of
hosts
$HOME/.swdefaults.hosts the user-
specific
default
list of
hosts
For each interactive command, target hosts containing
roots, depots, and hosts serving as PC controllers are
specified in separate lists ( hosts, hosts_with_depots,
and pc_controllers respectively). The list of hosts are
enclosed in {} braces and separated by white space
(blank, tab and newline). For example:
swinstall.hosts={hostA hostB hostC hostD hostE hostF}
swinstall.pc_controllers={pc1 pc2} swcopy.hosts_with_depots={hostS}
swcopy.pc_controllers={pc1 pc2}
The swinstall and swcopy interactive user interfaces read
a default list of patch filters that you can use as
selection criteria for patch software. The list is stored
in:
/var/adm/sw/defaults.patchfilters the sys‐
tem-wide
default
list of
patch fil‐
ters.
$HOME/.sw/defaults.patchfilters the user-
specific
default
list of
patch fil‐
ters.
The list of patch filters is enclosed in braces {} and
separated by white space (blank, tab, or newline). For
example:
swinstall.patch_filter_choices={
*.*,c=enhancement
*.*,c=critical
}
swcopy.patch_filter_choices={
Product.Fileset,c=halts_system
}
Environment Variables
The environment variable that affects the swinstall com‐
mand is:
LANG Determines the language in which mes‐
sages are displayed. If LANG is not
specified or is set to the empty string,
a default value of C is used. See the
lang(5) man page by typing man 5 sd for
more information.
NOTE: The language in which the SWMGR
agent and daemon log messages are dis‐
played is set by the system configura‐
tion variable script, /etc/rc.con‐
fig.d/LANG. For example, /etc/rc.con‐
fig.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 values for locale cate‐
gories 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 char‐
acters (e.g., single-versus multibyte
characters in values for vendor-defined
attributes).
LC_MESSAGES
Determines the language in which mes‐
sages should be written.
LC_TIME Determines the format of dates (cre‐
ate_date and mod_date) when displayed by
swlist. Used by all utilities when dis‐
playing dates and times in stdout, log‐
ging.
TZ Determines the time zone for use when
displaying dates and times.
Environment variables that affect scripts:
SW_CATALOG
Holds the path to the Installed Products
Database (IPD), relative to the path in
the SW_ROOT_DIRECTORY environment vari‐
able. Note that you can specify a path
for the IPD using the installed_soft‐
ware_catalog default option.
SW_CONTROL_DIRECTORY
Defines the current directory of the
script being executed, either a tempo‐
rary catalog directory, or a directory
within in the Installed Products Data‐
base (IPD). This variable tells scripts
where other control scripts for the
software are located (e.g. subscripts).
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 mul‐
tiple control file definitions to point
to the same file. A control_file can
query the
SW_LOCATION
Defines the location of the product,
which may have been changed from the
default product directory. When com‐
bined 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 commands available to 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 pre‐
fix to SW_LOCATION to locate the prod‐
uct's installed files. The configure
script is only run when SW_ROOT_DIREC‐
TORY is "/".
SW_SESSION_OPTIONS
Contains the pathname of a file contain‐
ing the value of every option for a par‐
ticular command, including software and
target selections. This lets scripts
retrieve any command options and values
other than the ones provided explicitly
by other environment variables. For
example, when the file pointed to by
SW_SESSIONS_OPTIONS is made available to
a request 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 con‐
tains the single software_collec‐
tion_spec for the targets on which the
script is being executed.
SW_SOFTWARE_SPEC
This variable contains the fully quali‐
fied software specification of the cur‐
rent product or fileset. The software
specification allows the product or
fileset to be uniquely identified.
Additional environment variables that affect scripts for
swinstall:
SW_DEFERRED_KERNBLD
This variable is normally unset. If it
is set, the actions necessary for pre‐
paring the system file /vmunix cannot be
accomplished from within the postinstall
scripts, but instead must be accom‐
plished by the configurescripts. This
occurs whenever software is installed to
a directory other than /, such as for a
cluster client system. This variable
should be read only by the configure and
postinstall scripts of a kernel fileset.
The swinstall command sets these envi‐
ronment variables for use by the kernel
preparation and build scripts.
SW_INITIAL_INSTALL
This variable is normally unset. If it
is set, the swinstall session is being
run as the back end of an initial system
software installation (full install).
SW_KERNEL_PATH
The path to the kernel. The default
value is /stand/vmunix, defined by the
swagent option or kernel_path.
SW_SESSION_IS_KERNEL
Indicates whether a kernel build is
scheduled for the current install/remove
session. A TRUE value indicates that the
selected kernel fileset is scheduled for
a kernel build and that changes to
/stand/system are required. A null
value indicates that a kernel build is
not scheduled and that changes to
/stand/system are not required.
The value of this variable is always
equal to the value of SW_SES‐
SION_IS_REBOOT.
SW_SESSION_IS_REBOOT
Indicates whether a reboot is scheduled
for a fileset selected for removal.
Because all Tru64 UNIX kernel filesets
are also reboot filesets, the values of
this variables is always equal to the
value of SW_SESSION_IS_KERNEL.
SW_SYSTEM_FILE_PATH
The path to the kernel's system file.
The default value is /stand/system.
Signals
The swinstall and swcopy commands catch the signals
SIGQUIT, SIGINT, and SIGUSR1. If these signals are
received, the command prints a message, sends a Remote
Procedure Call (RPC) to the agents to wrap up after com‐
pletion, and then exits.
The agent ignores SIGHUP, SIGINT, and SIGQUIT. It imme‐
diately 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 imme‐
diately exits gracefully after receiving SIGTERM and
SIGUSR2. After receiving SIGUSR1, it waits for comple‐
tion of a copy or remove from a depot session before
exiting, so that it can register or unregister depots if
necessary. Requests to start new sessions are refused
during this wait.
Locking
SWMGR commands use a common locking mechanism for reading
and modifying the Installed Products Database (IPD) and
software depots. This mechanism allows multiple readers
but only one writer on an IPD or depot: swinstall com‐
mands that modify the IPD are restricted from simultane‐
ous modification using fcntl(2) locking on the file (e.g.
/var/adm/sw/products/swlock).
swcopy commands that modify a software depot are
restricted from simultaneous modification using fcntl(2)
locking on the file (e.g. /var/spool/sw/catalog/swlock).
Both swinstall and swcopy commands set fcntl(2) read
locks on source depots using the swlock file mentioned
above. When a read lock is set, it prevents all SWMGR
commands from performing modifications (i.e. from setting
write locks).
Terminal Support
For in-depth information about terminal support refer to:
· The Managing Tru64 UNIX Software With the Sys‐
Man Software Manager manual
RETURN VALUES
An interactive swinstall or swcopy session always returns
0. A non-interactive swinstall or swcopy session
returns:
0 The software_selections were successfully
installed/copied.
1 The install/copy operation failed on all tar‐
get_selections.
2 The install/copy operation failed on some tar‐
get_selections.
DIAGNOSTICS
The swinstall and swcopy commands write to stdout,
stderr, and to specific logfiles.
Standard Output
An interactive swinstall or swcopy session does not write
to stdout. A non-interactive swinstall or swcopy session
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
An interactive swinstall or swcopy session does not write
to stderr. A non-interactive swinstall or swcopy session
writes messages for all WARNING and ERROR conditions to
stderr.
Logging
Both interactive and non-interactive swinstall and swcopy
sessions log summary events at the host where the command
was invoked. They log detailed events to the swagent
logfile associated with each target_selection.
Command Log
The swinstall and swcopy commands log all stdout
and stderr messages to the the logfile
/var/adm/sw/swinstall.log
(/var/adm/sw/swcopy.log). Similar messages are
logged by an interactive swinstall and swcopy
session. The user can specify a different logfile
by modifying the logfile option.
Target Log
A swagent process performs the actual install or
copy operation at each target_selection. For
install tasks, the swagent logs messages to the
file var/adm/sw/swagent.log beneath the root
directory (e.g. / or an alternate root direc‐
tory). For copy tasks, the swagent logs messages
to the file swagent.log beneath the depot direc‐
tory (e.g. /var/spool/sw).
EXAMPLESswinstall
To invoke an interactive session of swinstall:
swinstall
Select the C and Pascal products from the network source
software server (sw_server) and start an interactive ses‐
sion:
swinstall-i -s sw_server cc pascal
Install the C and Pascal products to a set of remote
hosts:
swinstall-s sw_server cc pascal @ hostA hostB
hostC
Update the OSPXV product from a CD-ROM mounted at /cd :
swinstall-s /cd/swmedia OSPXV
Install an incompatible version of OSPXV into the direc‐
tory /exports:
swinstall-x allow_incompatible=true -s/products OSPXV,a=arch \
@ /exports
Install all products from the cartridge tape
/dev/tape/tape0:
swinstall-s /dev/tape/tape0 \*
Reinstall the software_selections listed in the file
/tmp/install.products on the hosts listed in the file
tmp/install.hosts:
swinstall-x reinstall=true -f/tmp/install.products \
-t/tmp/install.hosts
Execute swinstall interactively using the session file
/tmp/case.selections as a basis:
swinstall-i -S /tmp/case.selections
Install all the software from local depot /tmp/sam‐
ple.depot.1, using any response files generated by
request scripts:
swinstall-s /tmp/sample.depot.1 -x ask=true \*
Install Product1 from remote depot /tmp/sample.depot.1 on
host swposix and use an existing response file (previ‐
ously generated by the swask command) located in
/tmp/bar.depot:
swinstall-s swposix:/tmp/sample.depot.1 -c
/tmp/bar.depot Product1
Install all products in remote depot /tmp/sample.depot.1
on host swposix , use any response files generated by
request scripts, create catalog /tmp/bar.depot and copy
all response files to the new catalog:
swinstall-s swposix:/tmp/sample.depot.1 -c /tmp/bar.depot \
-x ask=true \*
Install all products in remote depot /tmp/sample.depot.1
on host swposix , use response files, run request scripts
only when a response file is absent, create catalog
/tmp/bar.depot and copy all response files to the new
catalog:
swinstall-s swposix:/tmp/sample.depot.1 -c swposix:/tmp/bar.depot \
-x ask=as_needed \*
Install all patches in the depot that correspond to cur‐
rently installed software and are of the critical cate‐
gory:
swinstall-s /tmp/sample.depot.1 -x patch_match_target=true \
-x patch_filter=\"*.*, c=critical\"
To linkinstall the product TEST to the clients clientA,
clientB from the server:
swinstall-l -r -s :OS_700 TEST @ clientA clientB
To linkinstall product TEST2 to your own "/" directory
from an application server on "serve":
swinstall-l -s serve TEST2
swcopy
Invoke an interactive session of swcopy:
swcopy
Invoke an interactive session, using default depot at
hostX as the source:
swcopy -i -s hostX
Copy all products from the cartridge tape
/dev/ntape/tape0 to the default depot on the local host:
swcopy -s /dev/ntape/tape0 \*
Load the software_selections listed in the file
/tmp/load.products using the default source/depot:
swcopy -f /tmp/load.products
Copy the C and Pascal products to some local and remote
depots:
swcopy -s sw_server cc pascal @ /var/spool/sw
hostA:/tmp/sw hostB
FILES
$HOME/.swdefaults
Contains the user-specific default values for
some or all SWMGR options. If this file does not
exist, SWMGR looks for user-specific defaults in
$HOME/.swdefaults.hosts.
$HOME/.sw/defaults.hosts
Contains the user-specific default list of hosts
to manage.
$HOME/.sw/defaults.patchfilters
Contains the user-specific default list of patch
filters.
$HOME/.sw/sessions/
Contains session files automatically saved by the
SWMGR 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 of the config‐
urable and non-configurable data for SWMGR. This
directory is also the default location of log‐
files.
/var/adm/sw/defaults
Contains the active system-wide default values
for some or all SWMGR options.
/var/adm/sw/defaults.hosts
Contains the system-wide default list of hosts to
manage.
/var/adm/sw/defaults.patchfilters
Contains the system-wide default list of patch
filters.
/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 products installed on a system.
/var/adm/sw/queue/
The directory which contains the information
about all active and complete install jobs, copy
jobs, and other jobs initiated by the SWMGR com‐
mands.
/var/spool/sw/
The default location of a source and target soft‐
ware depot.
SEE ALSOsd(4), sd(5), setld(8), swacl(8), swagentd(8), swask(8),
swconfig(8), swlist(8), swmodify(8), swpackage(8),
swpackage(4), swreg(8), swremove(8), swverify(8), and the
Managing Tru64 UNIX Software With the SysMan Software
Manager manual.
Compaq Computer Corporation swinstall(8)
