Previous section.

Systems Management: Distributed Software Administration
Copyright © 1997 The Open Group


swinstall - Install software


No additional rationale is required under this heading.


This utility may be used to perform the following tasks:

The install software task can have different connotations depending upon the life cycle stage of the software package. Installation State Changes illustrates the various state transitions that can occur during an installation of software.

Figure: Installation State Changes

These transitions comprise the set of install software tasks supported by this Software Administration specification.

The facilities provided by swinstall and swcopy are basic building blocks on which other function may be built. A few examples are shown below simply for the purpose of illustration. In the course of the illustration, various network sizes are given, but they are fictitious and supplied solely for illustration.


No additional rationale is required under this heading.


No additional rationale is required under this heading.


No additional rationale is required under this heading.


No additional rationale is required under this heading.


The operations of the execution phase involve actual modification of the target file system and environment, and so from this point the utility is committed to the installation (in the sense that restoration to the state prior to load may not be possible).

Initially, swinstall, as well as swremove, would not act upon files in remote file systems. Although this was viewed as a good idea, it was removed. A vendor could check for local vs. remote file systems as a value-added feature, although it would require use of non-POSIX functionality. It should be noted that such a file system check involves policy, and thus should be overridable.

The normal use model is to install the latest revision of the product that matches the machine attributes of the targets. The default options fit this use model even when the targets specified have different uname attributes. As an example, assume the following command was issued:

swinstall -s source product1 @ host1 host2

Further, assume that host1 and host2 have different uname attributes and that the source contains instances of product1 that match the uname attributes of the two targets. The resulting install places the instance of product1 that matches the uname attributes of host1 onto host1, and the instance of product1 that matches the uname attributes of host2 onto host2.

The use of allow_incompatible=true is not the normal use model, and thus it is difficult to build in automatic filtering of selections. Thus, the user is required to uniquely specify which version is to be installed.

During disk space analysis, an implementation need only process paths with positive sizes in the space file to generate a maximum transient disk space requirement. Both space freed after successfully installing products when autorecover=true and negative size records can be used to generate a second and final disk space requirement.

How disk space analysis is implemented is undefined by 1387.2. When updating, each file size should be checked against any existing file at that location, on a per file system basis, unless rollback is enabled. In that case, the size of the existing files should be measured on the file system where they will reside until the install is committed.

Configuration occurs on hosts where the software is to be used, as opposed to the hosts that are serving software. For example, a host of one OS or architecture may be a file server of software for another OS or architecture. Configuration is where the software is configured specifically for or by the host, or vice versa, where the host is configured for or by the software. Examples are any compilation, modifying the host default PATHNAME for the software, or configuring the software for host-specific parameters. Contrast this to preinstall and postinstall scripts that should be written in a portable and relative (to the root directory) way since they may be executed in proxy. They are appropriate for operations that manage the files in the software that are to be served as an installation as opposed to being use as a configuration. Because the root directory is /, this is not an alternate root or proxy install, that is, the software is intended to be used on this host. When the root directory is not /, then a proxy install situation should be assumed, and the client of this installation instead should be rebooted and run the configuration. These client steps are undefined within this Software Administration specification. Since reboot is done only in non-proxy installations, the implementation of the "target role" that runs on the target architecture can execute the implementation-defined reboot process and then execute swconfig.

Reboot is executed after all filesets, kernel or otherwise, have been installed in order to avoid multiple reboots. This rationale is similar to a situation in kernel building. In that case, kernel building is only done after all filesets with the is_kernel attribute set to true are loaded in order to avoid multiple kernel builds.

The operating system underlying an implementation may require additional support for rebooting. For example, some systems may require intermediate reboots (reboot during the install process, with the install process continued after reboot). This, in turn, may require additional script return codes, or additional semantics for the is_reboot attribute. Clearly such additions are peculiar to the requirements of particular operating systems. Such additions should be documented by the implementation.

Figure: Order of Install Operations

A file that is defined as

/<>/<file> is (by default) installed in the same location as follows:

If a location was specified in the software selections, then the file is instead installed to the location as follows:


Additionally, if both an alternate root and a location was specified, the file is installed to the location as follows:


An example use for a preinstall script might be saving existing files before loading new ones. An example use for a postinstall script might be to clean up previously installed versions of a product, or to move a default file into place. These scripts are supplied by the vendor and are executed by the target role on each target. Note that the target role is not necessarily the system that will be using the software (the client role), and that multiple client roles may share the software from the same target role.

It is not sufficient to only state that the postkernel script is implementation defined. The name of the script, and also its location in the file system on each target host, should be known. Since kernel filesets can be loaded for alien architectures (e.g., in diskless workstations), this script should also be aware of the effective root directory through the SW_ROOT_DIRECTORY environment variable. In general, all products with kernel filesets for a particular architecture should have the same productpostkernel attribute defined. This script is contained within the product that contains the core operating system filesets. The implementation-defined default path value for postkernel permits operating system implementation agreements that simplify the need for each product to define this attribute. A side effect of this product level attribute is that different products in the same distribution and same installation could conceivably have different values for the name of the script. In that case, multiple (probably redundant) kernel builds would occur and the order of fileset loads and kernel rebuilds would have to be specified.

The postkernel step after kernel filesets have been loaded is based on the HP-UX model for kernel building. This model supports both rebuilding of the kernel for OS updates, and insertion of an appropriate default kernel for new installations or installation in proxy. It also supports ensuring that a working kernel is in place before committing to the bulk of the install. For example, updating the HP-UX operating system to a new revision requires installing kernel related filesets and rebuilding the kernel successfully before loading the rest of the filesets. This ensures that the new kernel is operational (noted by the success of the postkernel script) before loading filesets whose executables will not run on the previous kernel. If the kernel build step was not insured to be successful, then you could have an unusable or even unbootable system.

When the installation is being done in proxy, the kernel build step should move a default new kernel into place instead of building a new kernel, since the architecture of the installed software may be different from the architecture of the server (the target role performing the installation). The script may check if it is an alternate root install by checking the SW_ROOT_DIRECTORY environment variable, and for the purpose of kernel building, it should take actions appropriate to a proxy install. Then, a new kernel containing the appropriate configuration (e.g., drivers) for the software installed may be built after or during the implementation specific configuration step (configuration occurs in the context of the system using the software).

Since the postkernel script is part of the target installed_software object, there is flexibility as to what actual steps are performed. For example, if a "cross-compiler" kernel building functionality existed in the target role, a new kernel could actually be built even in proxy.

There have been requests for removal of the required postkernel script return codes in swinstall , so making them undefined. It was concluded that it is important to keep them.

Update Capabilities
If there are multiple versions of software available in a depot (distribution), swinstall will choose the highest compatible revision of software if a revision, architecture or vendor_tag is not explicitly specified.

When installing a revision of a fileset, if there is currently a revision installed at the target location, then the install is considered an update, reinstal or downdate. In general, only updates proceed to execution phase; reinstalls and downdates are skipped.

During execution phase when updating, reinstalling or downdating a fileset, the catalog information for the existing fileset has its state set to "transient" during the course of an install, and then is removed or set to the "removed" state when the execution of that fileset completes.

By default, a file is installed into the location defined by its path attribute unless the product has been relocated. The only way to change the location of a file is change the root directory or the product location. This implies that any existing file at that location will be overwritten during the installation of the new fileset.

If the exact file (based on path, size, mtime and cksum attributes) is already installed, it is not reinstalled unless the user has specified that the filesets are being reinstalled. But, reinstall is defined as only applying to whether to reinstall a fileset with the same revision, not a file. This is vague when updates are considered (see below).


swinstall -x reinstall=true PRODUCT,r=1

When applying the POSIX defined recovery to update, if the autorecover option is set to true, then, if a fileset control script or file loading fails, then that fileset is removed, leaving the existing fileset in the state where it was previously. The next fileset is then attempted. If a product control script fails, then all filesets in the product that are being updated will be returned to their previous state.


swinstall -x autorecover=true PRODUCT,r=1

Downdate (or downgrade) is similarly defined, and behaves in much the same way as update. In general, software packages do not handle downdating very well (since the higher revisions of software have not been developed yet, the requirements for downgrading are not known). For this reason, the user must override the default behavior by setting the "allow_downdate" option to true.


swinstall -x allow_downdate=true PRODUCT,r=lower_revision

The administrator can also choose to install multiple versions of the same product (i.e. multiple revisions), by choosing different locations. The product is_locatable option must be true (the default). If a multiple version is being installed, swinstall will not Configure the new version. This is because the user needs to decide which version is the "current" version to be configured into the system, and then manually unconfigure one and configure the other.

The developers of this specification found autorecover_product preferrable to the POSIX autorecover that can result in a partially updated product.

The developers of this specification considered sparse upgrades good for marketing purposes (that is, publically available free upgrades for those that have the base, without having to give out the whole thing)

This specification provides capabilities for "recovery" to the previous state if an install fails (for example, due to a lost connection to the source or a failed preinstall or postinstall script). Since it is common practice for a new release (update or upgrade) of a product to be of better quality than a patch (or fix), functionality supporting manual rollback of an update is not included at this time. The administrator can manually rollback to a previous release by installing and managing multiple installed versions instead of performing an update, or by reinstalling the lower version (downdate or downgrade).

swinstall -x reinstall=true -x reinstall_files=false
This reinstalls the fileset, but does not retransfer or reinstall any files that are already up to date.
swinstall -x reinstall_files=false PRODUCT,r=<newer>
This updates the product, but still checks each file before retransfer or reinstall.
Patch Operations
Several new attributes and options are used to implement these capabilities.

The following are examples of patch installation in same session as base product:

swinstall -x autoselect_patches=true X11

This is the default behavior for patch installation. All patches applying to software being installed (in this case X11) are selected.

swinstall -x autoselect_patches=true \ -x patch_filter="*,c=critical" X11

These settings would cause all applicable patches that include the category "critical" to be selected and installed along with the selected software.

swinstall -x autoselect_patches=true \ -x patch_filter="X11,c=critical" BaseOS X11 Networking

These settings would cause only applicable patches for the product X11 that include the category "critical" to be selected and installed along with the other selected non-patch software "BaseOS" and "Networking".

swinstall -x autoselect_patches=false X11 \ X11.Runtime,r=1.0.1 PH02-3425

This installs a product and two explicitly defined patches (showing different patch naming schemes). Note that the "autoselect_patches" defaults to true.

The following are examples of patch installation after base product is installed:

swinstall -x patch_match_target=true

These options will select the highest superseding patches in the depot that correspond to currently installed software.

swinstall -x patch_match_target=true -x patch_filter="X11"

These options will select the highest superseding patches in the depot that have an ancestor on system, and that have a product tag of "X11".

swinstall -x patch_match_target=true \ -x patch_filter="X11,c=critical" Networking.TCP,r=1.0.1

These options will select all critical patches with product tag X11 if their ancestors are installed and also will install an explicitly specified patch.

swinstall -x patch_match_target=true \ -x patch_filter="*,c=critical"

These options will select all patches in the depot that correspond to currently installed software and that contain the category "critical".

The following is an example of Multiple criteria with patch filtering:

swinstall -x patch_match_target=true \ -x patch_filter="X11,c=critical,c=test_level_4|hand_certified"

This will bring down any patches for X11 that have the category "critical" and either the category "test_level_4" OR the category "hand_certified".

The following is an example of Explicitly loading patches:

swinstall fix12312 Networking.TCP,r=1.0.1

This shows identification of a specific patch product (using one naming convention of naming the product for the defect it fixes) as well as explicitly identifying a patch fileset (using the other naming convention of naming patches after the filesets they patch).

The following is an example of saving patch files:

swinstall -x patch_save_files=true -x patch_match_target=true


Install the C and Pascal products from the network source, sw_server as follows:
swinstall -s sw_server cc pascal

Install the C and Pascal products on some remote hosts as follows:

swinstall -s sw_server cc pascal @ hostA hostB hostC

Update the Omniback product from a CD-ROM mounted at /cd as follows:

swinstall -s /cd omniback

Install an incompatible version of Omniback as follows:

swinstall -x allow_incompatible=true omniback,a=foreign

Install all products from the cartridge tape /dev/rct0 as follows:

swinstall -s /dev/rct0 \*

Install the software_selections listed in /tmp/install.products on the hosts listed in /tmp/install.hosts as follows:

swinstall -f /tmp/install.products -h /tmp/install.hosts

Example of match_target:

swinstall -s new_media -x match_target=true

Example of reinstall_files:

swinstall -x reinstall_files=false reinstall_files_use_cksum=false

Example of autorecover_product:

swinstall -x autorecover_product=true PRODUCT


No additional rationale is required under this heading.


No additional rationale is required under this heading.

Why not acquire a nicely bound hard copy?
Click here to return to the publication details or order a copy of this publication.

Contents Next section Index