swcopy(8)

NAME

swinstall − Install and configure software products

swcopy − Copy software products for subsequent installation or distribution

SYNOPSIS

swinstall [XToolkit Options] [-i] [-p] [-v] [-r] [-s source] [-x option=value] [-X option_file] [-f file] [-t target_file] [-S session_file] [software_selections] [ @  target_selections]

swcopy [XToolkit Options] [-i] [-p] [-v] [-s source] [-x option=value] [-X option_file] [-f file] [-t target_file] [-S session_file] [software_selections] [ @  target_selections]

DESCRIPTION

The swinstall command installs the software_selections from a software source to one or more target_selections (root filesystems).  By default, the software is configured for use on each 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 target_selections (software depots).  These depots can then be accessed as a software source by the swinstall command. 

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 them available as a source for installation by swinstall.  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:

checkinstall
a script executed during the analysis of each target_selection, it checks that the installation can be attempted.  If this check fails, the software product will not be installed. 

preinstall
a script executed immediately before the software’s actual files are installed.

postinstall
a script executed immediately after the software’s actual files are installed.

configure
a script executed during the configuration of each target_selection, it configures the host for the software (and the software for the host). The preinstall and postinstall scripts are not intended to be used for configuration tasks.  They are to be used for simple file management needs such as removing obsolete files from the previous revision (which was just updated). 

• 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, unless explicitly requested by the user.  (A depot can be a repository of software 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 software which is already installed, swinstall will not reinstall it.  (The user can override these behaviors.) 

• 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 perform this operation (if necessary).  Files being replaced are overwritten where possible; those that can not be overwitten are moved aside (to #<file> ). 

• The swinstall command supports kernel building and rebooting.  After software which modifies the kernel is installed (or updated), swinstall will execute a system-specific command to create the new version of the kernel.  The remaining software_selections are then installed. 

After software which requires a system reboot is installed (or updated), swinstall will automatically reboot the system. 

When updating the operating system to a new revision, installing kernel software first ensures that a new kernel can be generated 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. 

Options

swinstall and swcopy support the following options:

XToolKit Options
The swremove command supports a subset of the standard X Toolkit options to control the appearance of the GUI.  The supported options are: -bg, -background, -fg, -foreground, -display, -name, and -xrm.  See the X(1) manual page for a definition of these options. 

-p Previews an install task by running the session through the analysis phase only. 

-i Runs the command in interactive mode (invokes the Graphical User Interface). 

-r Causes swinstall to install software into alternate root directories (e.g. root filesystems other than /). 

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

-s source Specifies the source depot (or tape) from which software will be installed or copied. 

-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 target_file instead of (or in addition to) the command line. 

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

Operands

The swinstall and swcopy commands support support the following syntax for each software_selection:

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

The location component specifies the location in which to install the product, and is only supported by swinstall. 

The version component supports either of these syntaxes:

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

[instance_id]

The swinstall and swcopy commands support the following syntax for each target_selection:

[host][:][/directory]

EXTERNAL INFLUENCES

Defaults File

In addition to the standard options, several swinstall and swcopy 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:

swinstall.option=value
swcopy.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 swinstall command:

swinstall.source_type=directory

swcopy.source_type=directory
Defines the default source type, either directory or tape.  The source type derived from the -s option overrides this value. 

swinstall.source_directory=/var/spool/sw

swcopy.source_directory=/var/spool/sw
Defines the default location of the source depot.  This syntax can be host:path.  The -s option overrides this value. 

swinstall.source_tape=/dev/swtape

swcopy.source_tape=/dev/swtape
Defines the default location of the source tape, usually the character-special 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. 

swinstall.use_alternate_source=false

swcopy.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 will use the same source, namely the source specified by the user and validated by the command.  If true, each target agent will instead use its own configured value for the source. 

swcopy.target_directory=/var/spool/sw
Defines the default location of the target depot.

swinstall.verbose=1

swcopy.verbose=1
Controls the verbosity of the swinstall or swcopy 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. 

swinstall.loglevel=1

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

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

swcopy.logfile=/var/adm/sw/swcopy.log
This is the default command log file for the swinstall and swcopy commands. 

swinstall.select_local=true

swcopy.select_local=true
If no target_selections are specified, select the default root directory / (swinstall), or the default target_directory (swcopy), at the local host as the target of the command. 

swinstall.targets=

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

swinstall.software=

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

swinstall.polling_interval=2

swcopy.polling_interval=2
Defines the polling interval used by interactive (GUI) sessions.  It specifies how often each target agent will be polled to obtain status information about the task being performed.  When operating across wide-area networks, the polling interval can be increased to reduce network overhead.

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

swinstall.create_target_path=true

swcopy.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 will not be created.  This option can prevent the erroneous creation of new target depots or new alternate root directories. 

swinstall.mount_all_filesystems=true

swcopy.mount_all_filesystems=true
Attempt to 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. 

swinstall.allow_incompatible=false
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 supported systems defined for each selected product.)  If set to true, target compatibility is not enforced. 

swinstall.enforce_dependencies=true

swcopy.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 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 installation or configuration to fail. 

swinstall.autoreboot=false
Prevents the installation of software requiring a reboot from the non-interactive interface. If set to true, then 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. 

swinstall.reinstall=false

swcopy.reinstall=false
When re-installing (or re-copying) an existing version of a fileset, this option causes that fileset to be skipped, i.e. not re-installed. If set to true, the fileset will be re-installed (re-copied). 

swinstall.allow_downdate=false
Prevents the installation of an older revision of fileset that already exists at the target(s).  (Many software products do not support "downdating".)  If set to true, the older revision can be installed. 

swinstall.allow_multiple_versions=false
Prevents the installation of another, independent version of a product when a version already is already installed at the target.

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 locatable.  Multiple configured versions will not work unless the product supports it. 

swinstall.autorecover_product=false
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 of the original filesets in that product if the load fails. 

swinstall.enforce_dsa=true

swcopy.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 filesystem(s).  If set to false, then the install or copy operation will use the filesystems’ minfree space and may fail because it reaches the filesystem’s absolute limit. 

swinstall.enforce_scripts=true
If a fileset/product checkinstall script fails (i.e. returns with exit code 1), none of the filesets in that product will be installed.  If set to false, the install operation will proceed even when a checkinstall script fails. 

swinstall.defer_configure=false
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 /. 

When installing a second (third, ...) version of a product, it will not be configured if another version is already configured.  The swconfig command must be run separately. 

swinstall.reinstall_files=true

swcopy.reinstall_files=true
Causes all the files in a fileset to always be re-installed or re-copied, even when the file already exists at the target and is identical to the new file.  If set to false, files that have the same checksum (see next option), size and timestamp will not be re-installed or re-copied.  This check enhances performance on slow networks or slow discs. 

swinstall.reinstall_files_use_cksum=true

swcopy.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 compared to determine if the new file should replace the old one.  (The checksum 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 (not) reinstalled based only on their size and timestamp. 

swinstall.compress_files=false

swcopy.compress_files=false
If set to true, files will be compressed before transfer from a remote source and uncompressed after transfer.  This will enhance performance on slower networks. 

swinstall.write_remote_files=false

swcopy.write_remote_files=false
Prevents the installation or copying of files to a target which exists on a remote (NFS) filesystem.  All files destined for a remote filesystem will be skipped.

If set to true and if the superuser has write permission on the remote filesystem, the remote files will not be skipped, but will be installed or copied. 

swcopy.register_new_depot=true
Causes swcopy to register a newly created depot with the local swagentd.  This action allows other SD commands to automatically "see" this depot.  If set to false, a new depot will not be automatically registered.  (It can be registered later with the swdepot command.) 

Remote Procedure Call Options
These options apply to the DCE Remote Procedure Call used by swinstall and swcopy:

swinstall.rpc_binding_info=ncadg_ip_udp:[2121]

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

swinstall.rpc_timeout=5

swcopy.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 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 session is saved to the file $HOME/.sw/sessions/swinstall{swcopy}.last.  This session can be re-executed by using the file as input to swinstall or swcopy (with the -S option.) 

In an interactive session, session information can be saved into a file at any time for reuse in a subsequent session. 

The session file uses the same syntax as the defaults files.  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 swinstall program sets these environment variables for use by the control scripts being executed:

SW_PATH

A PATH variable which defines a minimum set of commands available to for use in a control script (e.g.  /bin:/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_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 in the Installed Products Database (IPD).  This variable tells scripts where other control scripts for the software are located (e.g. subscripts). 

Signals

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

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

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

2 The install/copy operation failed on some target_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 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/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 directory).  For copy tasks, the swagent logs messages to the file swagent.log beneath the depot directory (e.g.  /var/spool/sw). 

EXAMPLES

swinstall

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 session:

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 HP Omniback product from a CD-ROM mounted at /cd :

swinstall -s /cd/swmedia omniback

Install an incompatible version of HP Omniback into the directory /exports:

swinstall -x allow_incompatible=true -s/products -d/exports omniback,a=arch

Install all products from the cartridge tape /dev/rmt/0:

swinstall -s /dev/rmt/0 \*

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 using the session file /tmp/case.selections as a basis:

swinstall -i -S /tmp/case.selections

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/rmt/0tothedefaultdepoton

swcopy -s /dev/rmt/0 \*

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

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

/var/spool/sw/

The default location of a source and target software depot. 

AUTHOR

swinstall and swcopy were developed by the Hewlett-Packard Company. 

SEE ALSO

swacl(8), swagentd(8), swconfig(8), swdepot(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