Packaging software for installation

This topic provides information about preparing applications to be installed with the installp command.

This section describes the format and contents of the software product installation package that must be supplied by the product developer. It gives a description of the required and optional files that is part of a software installation or update package.

A software product installation package is a backup-format file which contains the files of the software product, required installation control files, and optional installation customization files. The installp command is used to install and update software products.

An installation package contains one or more separately installable, logically grouped units called filesets. Each fileset in a package must belong to the same product.

A fileset update or update package is a package which contains modifications to an existing fileset.

Throughout this topic, the term standard system is used to refer to a system that is not configured as a diskless system.

Installation procedure requirements

  • Installation must not require user interaction. Product configuration that requires user interaction must occur before or after installation.
  • All installations of independent filesets or updates to interdependent filesets must be able to be performed during a single installation.
  • No system restart should be required for installation. The installation will stop portions of the system related to the installation, and a system restart is required after installation in order for the installation to take full effect.

Package control information requirements

Package control information must:

  • Specify all installation requirements the filesets have on other filesets.
  • Specify all file system size requirements for the fileset installation.

Format of a software package

An installation or update package must be a single file in backup format that can be restored by the installp command during installation. This file can be distributed on tape, diskette, or CD-ROM.

Package partitioning requirements

In order to support diskless or dataless client workstations, machine-specific portions of the package (the root part) must be separated from the machine-shareable portions of the package (the usr part). The usr part of the package contains files that reside in the /usr or /opt file system.

Installation of the root part of the package must not modify any files in the /usr file system. The /usr file system is not writable during installation of the root part of a diskless or dataless client system. The machine–specific (root) part should include everything that is not in the /usr or /opt file systems.

Packaging for workload partitions

Some software products require special consideration when being packaged for workload partitioning (WPAR). For a software product to successfully deploy in a WPAR, it must be packaged such that it does not attempt to write into the /usr or /opt file systems during the root part of the processing, because a WPAR mounts those file systems in read-only mode. Similarly, any configuration that is to be performed in each system where the product is installed must be performed from the root part of the package.

If a fileset is not intended to ever be installed into a workload partition, it must be designated with the PRIVATE attribute in the lpp_name file of the package.

If a fileset needs to be configured differently when it is installed within a WPAR, a packaging script checks the INUWPAR environment variable to determine whether the fileset is being installed within a WPAR.

If a fileset is configured differently when installed into a WPAR, it will be reconfigured when a WPAR is created from a system copy, because the fileset was not installed into a WPAR originally. Fileset owners can create programs in the /usr/lib/wpars/wparconvert.d/usr and /usr/lib/wpars/wparconvert.d/root directories, which are to be run when converting the usr and root parts from their fileset to be run within a system copy WPAR. All executable files within those directories are executed in alphabetical order (C locale) when a system copy WPAR is first started.

Software vital product data

Information about a software product and its installable options is maintained in the Software Vital Product Data (SWVPD) database. The SWVPD consists of a set of commands and the Object Data Manager (ODM) object classes for the maintenance of software product information. The SWVPD commands are provided for the user to query (lslpp) and verify (lppchk) installed software products. The ODM object classes define the scope and format of the software product information that is maintained.

The installp command uses the Object Data Manager to maintain the following information in the SWVPD database:

  • The name of the software product (for example, bos.adt)
  • The version of the software product
  • The release level of the software product, which indicates changes to the external programming interface of the software product
  • The modification level of the software product, which indicates changes that do not affect the software product's external interface
  • The fix level of the software product, which indicates small updates that are to be built into a regular modification level at a later time
  • The name, checksum, and size of the files that make up the software product or option
  • The state of the software product: available, applying, applied, committing, committed, rejecting, or broken
  • Technology level and APAR information
  • The destination directory and installer for non-installp packaged software, where applicable.

Software product packaging parts

In order to support installation in the client/server environment, the installation packaging is divided in the following parts:
usr
Contains the part of the product that can be shared among several machines with compatible hardware architectures. For a standard system, these files are stored in the /usr or /opt file tree.
root
Contains the part of the product that cannot be shared among machines. Each client must have its own copy. Most of this software requiring a separate copy for each machine is associated with the configuration of the machine or product. For a standard system, files in the root part are stored in the root (/) file tree. The root part of a fileset must be in the same package as the usr part of the fileset. If a fileset contains a root part, it must also contain a usr part.

Sample file system guide for package partitioning

Following is a brief description of file systems and directories. You can use this as a guide for splitting a product package into root, usr, and share parts.

Some root-part directories and their contents:

/dev
Local machine device files
/etc
Machine configuration files such as hosts and passwd
/sbin
System utilities needed to boot the system
/var
System-specific data files and log files

Some usr-part directories and their contents include:

/usr/bin
Commands and scripts (ordinary executables)
/usr/sbin
System administration commands
/usr/include
Include files
/usr/lib
Libraries, non-user commands, and architecture-dependent data
/opt
Libraries, non-user commands, and scripts normally associated with non-operating system products.

Package and fileset naming conventions

Use the following conventions when naming a software package and its filesets:
  • A package name (PackageName) should begin with the product name. If a package has only one installable fileset, the fileset name can be the same as the PackageName. All package names must be unique.
  • A fileset name has the form:
    ProductName.PackageName.FilesetName.extension
    where:
    • ProductName identifies the product or solution group.
    • PackageName identifies a functional group within the product.
    • FilesetName (optional) identifies a specific functional set of files and libraries to be installed.
    • Extension (optional) further describes the contents.
  • A fileset name contains more than one character and begins with a letter.
  • All characters in the fileset name must be ASCII characters. Valid characters are upper and lowercase letters, digits, underscores ( _ ), plus signs ( + ), and minus signs. The period ( . ) is used as a separator in the fileset name.
  • A fileset name cannot end with a period or dot.
  • The maximum length for a fileset name is 144 bytes.
  • All fileset names must be unique within the package.

Fileset extension naming conventions

Extension Fileset Description
.adt Application development toolkit
.com Common code required by similar filesets
.compat Compatibility code that may be removed in a future release
.diag Diagnostics support
.fnt Fonts
.help. Language Common Desktop Environment (CDE) help files for a particular language
.loc.language Locale
.msg. Language Message files for a particular language
.rte Runtime environment or minimum set for a product
.ucode Microcode

Special naming considerations for device driver packaging

The configuration manager command (cfgmgr) automatically installs software support for detectable devices that are available on the installation media and packaged with the following naming convention:
devices.BusTypeID.CardID.Extension
where:
  • BusTypeID specifies the type of bus to which the card attaches (for example, pci for PCI
  • CardID specifies the unique hexadecimal identifier associated with the card type
  • Extension specifies the part of the driver that is included (for example, rte could be the extension for runtime and diag is the extension for diagnostics.)

For example, assume that an ethernet device attaches to the PCI bus and is identified by the configuration manager as having a unique card identifier of 1410bb02. The package of filesets associated with this ethernet device would be named devices.pci.1410bb02. The runtime environment fileset within this package would be named devices.pci.1410bb02.rte.

Special naming considerations for message catalog packaging

A user installing a package can request that the message catalogs be installed automatically. When this request is made, the system automatically installs message filesets for the primary language if the message filesets are available on the installation media and packaged with the following naming convention:
Product.msg.Language.SubProduct

The optional.SubProduct suffix is used when a product has multiple message catalog filesets for the same language, each message catalog fileset applying to a different SubProduct. You can choose to have one message fileset for an entire product.

For example, the Super_Widget product has a plastic and a metal set of fileset options. All Super_Widget English US message catalogs can be packaged in a single fileset named Super_Widget.msg.en_US. If separate message catalog filesets are needed for the plastic and metal options, the English US message catalog filesets would be named Super_Widget.msg.en_US.plastic and Super_Widget.msg.en_US.metal.

Note: A message fileset that conforms to this naming convention must contain an installed-requisite (instreq) on another fileset in the product in order to ensure automatic installation of the message fileset.

File names

Files delivered with the software package cannot have names containing commas or colons. Commas and colons are used as delimiters in the control files used during the software installation process. File names can contain non-ASCII characters. The full path for the file name cannot be more than 128 characters.

Fileset revision level identification

The fileset level is referred to as the level or alternatively as the v.r.m.f or VRMF and has the form:
Version.Release.Modification.FixLevel
where:
  • Version is a numeric field of 1 to 2 digits that identifies the version number.
  • Release is a numeric field of 1 to 2 digits that identifies the release number.
  • Modification is a numeric field of 1 to 4 digits that identifies the modification level.
  • FixLevel is a numeric field of 1 to 4 digits that identifies the fix level.

A base fileset installation level is the full initial installation level of a fileset. This level contains all files in the fileset, as opposed to a fileset update, which may contain a subset of files from the full fileset.

All filesets in a software package should have the same fileset level, though it is not required for AIX® 4.1-formatted packages.

For all new levels of a fileset, the fileset level must increase. The installp command uses the fileset level to check for a later level of the product on subsequent installations.

fileset level precedence reads from left to right (for example, 5.2.0.0 is a newer level than 4.3.0.0).

Contents of a software package

This section describes the files contained in an installation or update package. File path names are given for installation package types. For update packages, wherever PackageName is part of the path name, it is replaced by PackageName/FilesetName/FilesetLevel.

The usr part of an installation or update package contains the following installation control files:
  • ./lpp_name: This file provides information about the software package to be installed or updated. For performance reasons, the lpp_name file should be the first file in the backup-format file that makes up a software installation package.
  • ./usr/lpp/PackageName/liblpp.a: This archive file contains control files used by the installation process for installing or updating the usr part of the software package.
  • All files, backed up relative to root, that are to be restored for the installation or update of the usr part of the software product.
If the installation or update package contains a root part, the root part contains the following files:
  • ./usr/lpp/PackageName/inst_root/liblpp.a: This library file contains control files used by the installation process for installing or updating the root part of the software package.
  • All files that are to be restored for the installation or update of the root part of the software package. For a base fileset installation level these files must be backed up relative to ./usr/lpp/PackageName/inst_root.

Example contents of a software package

The farm.apps package contains the farm.apps.hog 4.1.0.0 fileset. The farm.apps.hog 4.1.0.0 fileset delivers the following files:
/usr/bin/raisehog (in the usr part of the package)
/usr/sbin/sellhog
 (in the usr part of the package)

/etc/hog
 (in the root part of the package)
The farm.apps package contains at least the following files:
./lpp_name
./usr/lpp/farm.apps/liblpp.a
./usr/lpp/farm.apps/inst_root/liblpp.a
./usr/bin/raisehog
./usr/sbin/sellhog
./usr/lpp/farm.apps/inst_root/etc/hog
Fileset update farm.apps.hog 4.1.0.3 delivers updates to the following files:
/usr/sbin/sellhog
/etc/hog
The fileset update package contains the following files:
./lpp_name
./usr/lpp/farm.apps/farm.apps.hog/4.1.0.3/liblpp.a
./usr/lpp/farm.apps/farm.apps.hog/4.1.0.3/inst_root/liblpp.a
./usr/sbin/sellhog
./usr/lpp/farm.apps/farm.apps.hog/4.1.0.3/inst_root/etc/hog
Note: The file from the root part of the package was restored under an inst_root directory. Files installed for the machine-dependent root part of a package are restored relative to an inst_root directory. This facilitates installation of machine-specific files in the root file systems of multiple systems. The root part files are installed into the root portions of systems by copying the files from the inst_root directory. This allows multiple machines to share a common machine-independent usr part.

The lpp_name package information file

Each software package must contain the lpp_name package information file. The lpp_name file gives the installp command information about the package and each fileset in the package. Refer to the figure for an example lpp_name file for a fileset update package. The numbers and arrows in the figure refer to fields that are described in the table that follows.

Field Name Format Separator Description
1. Format Integer White space Indicates the release level of installp for which this package was built. The values are:
  • 1 - AIX 3.1
  • 3 - AIX 3.2
  • 4 - AIX 4.1 and later
2. Platform Character White space Indicates the platform for which this package was built. The values are:
  • R - RISC
  • I - Intel
  • N - Neutral
3. Package Type Character White space Indicates whether this is an installation or update package and what type. The values are:
  • I - Installation
  • S - Single update
  • SR - Single update required
  • ML - Technology level update
4. PackageName Character White space The name of the software package (PackageName).
  { New line Indicates the beginning of the repeatable sections of fileset-specific data.
5.Fileset name Character White space The complete name of the fileset. This field begins the heading information for the fileset or fileset update.
6. Level Shown in Description column White space The level of the fileset to be installed. The format is: Version.Release.Modification.FixLevel
Note: The level can be defined additionally with syntax of <, >, and = combinations. For example, *prereq bos.rte v<5 or *prereq bos.rte v=5 r=3.
7. Volume Integer White space Indicates the volume number where the fileset is located if shipped on multivolume media.
8. Bosboot Character White space Indicates whether a bosboot is needed following the installation. The values are:
  • N - Do not start bosboot
  • b - start bosboot
9. Content Character White space Indicates that the parts included in the fileset or fileset update. The values are:
  • B -usr and root part
  • U -usr part only
10. Language Character White space Should be set to the language displayed if the C locale is selected. Generally set to en_US.
11. Description Character # or new line Fileset description. The description is limited to 60 characters.
12. Comments Character New line (Optional) Additional comments.
  [ New line Indicates the beginning of the body of the fileset information.
13. Requisite information Described following table New line (Optional) Installation dependencies the fileset has on other filesets and fileset updates. See the section following this table for detailed description.
  % New line Indicates the separation between requisite and size information.
14. Size and License Agreement information Described later in this topic New line Size requirements by directory and license agreement information. See Size and License Agreement Information Section later in this topic for detailed description.
  % New line Indicates the separation between size and licensing information.
  % New line Indicates the separation between licensing and supersede information.
15. Supersede Information Described later in topic New line Information regarding a prior fileset that this fileset replaces.
  % New line Indicates the separation between licensing and fix information.
16. Fix information Described later in topic New line Information regarding the fixes contained in the fileset update. See Fix Information Section later in this topic for detailed description.
  ] New line Indicates the end of the body of the fileset information.
  } New line Indicates the end of the repeatable sections of fileset-specific information.
1 23    4
| ||    |                6         7 8 9  10       11
4 RSfarm.apps {  |       |         | | |   |        |
 5--> farm.apps.hog04.01.0000.0003 1 N U en_US Hog Utilities 
12--># ...      
[
13--> *ifreq bos.farming.rte (4.2.0.0) 4.2.0.15
%
14--> /usr/sbin 48
14--> /usr/lpp/farm.apps/farm.apps.hog/4.1.0.3 280
14--> /usr/lpp/farm.apps/farm.apps.hog/inst_root/4.1.0.3.96
14--> /usr/lpp/SAVESPACE 48
14--> /lpp/SAVESPACE 32
14--> /usr/lpp/bos.hos/farm.apps.hog/inst_root/4.1.0.3/ etc 32
%
%
15--> ranch.hog 4.1.0.0
%
16--> IX51366 Hogs producing eggs.
16--> IX81360 Piglets have too many ears.
]
}

Requisite information section

The requisite information section contains information about installation dependencies on other filesets or fileset updates. Each requisite listed in the requisite section must be satisfied according to the requisite rules in order to apply the fileset or fileset update.

Before any installing or updating occurs, the installp command compares the current state of the filesets to be installed with the requirements listed in the lpp_name file. If the -g flag was specified with the installp command, any missing requisites are added to the list of filesets to be installed. The filesets are ordered for installation according to any prerequisites. Immediately before a fileset is installed, the installp command again checks requisites for that fileset. This check verifies that all requisites installed earlier in the installation process were installed successfully and that all requisites are satisfied.

In the following descriptions of the different types of requisites, RequiredFilesetLevel represents the minimum fileset level that satisfies the requirements. Except when explicitly blocked for reasons described in Supersede Information Section, newer levels of a fileset satisfy requisites on an earlier level. For example, a requisite on the plum.tree 2.2.0.0 fileset is satisfied by the plum.tree 3.1.0.0 fileset.

Prerequisite

A prerequisite indicates that the specified fileset must be installed at the specified fileset level or at a higher level before the current fileset can install successfully. If a prerequisite fileset is scheduled to be installed, the installp command orders the list of filesets to install to make sure the prerequisite is met. A prerequisite on a fileset within the same package is not guaranteed.

Syntax
*prereq Fileset RequiredFilesetLevel
Alternate syntax
Fileset RequiredFilesetLevel

A fileset update contains an implicit prerequisite to its base-level fileset. If this implicit prerequisite is not adequate, you must specify explicitly a different prerequisite. The Version and Release of the update and the implicit prerequisite are the same. If the FixLevel of the update is 0, the ModificationLevel and the FixLevel of the implicit prerequisite are both 0. Otherwise, the implicit prerequisite has a ModificationLevel that is the same as the ModificationLevel of the update and a FixLevel of 0. For example, a 4.1.3.2 level update requires its 4.1.3.0 level to be installed before the update installation. A 4.1.3.0 level update requires its 4.1.0.0 level to be installed before the update installation.

Corequisite

A corequisite indicates that the specified fileset must be installed for the current fileset to function successfully. At the end of the installation process, the installp command issues warning messages for any corequisites that are not met. A corequisite can be used to indicate requisites between filesets within the same package.

Syntax
*coreq Fileset RequiredFilesetLevel

If requisite

An if requisite indicates that the specified fileset is required to be at RequiredFilesetLevel only if the fileset is installed at InstalledFilesetLevel. This is most commonly used to coordinate dependencies between fileset updates. The following example shows an if requisite:
*ifreq plum.tree (1.1.0.0) 1.1.2.3
Syntax
*ifreq Fileset [(InstalledFilesetLevel)] RequiredFilesetLevel

If the plum.tree fileset is not already installed, this example does not cause it to be installed. If the plum.tree fileset is already installed at any of the following levels, this example does not cause the 1.1.2.3 level to be installed:

1.1.2.3
This level matches the RequiredFilesetLevel.
1.2.0.0
This level is a different base fileset level.
1.1.3.0
This level supersedes the RequiredFilesetLevel.

If the plum.tree fileset is already installed at any of the following levels, this example causes the 1.1.2.3 level to be installed:

1.1.0.0
This level matches the InstalledFilesetLevel.
1.1.2.0
This level is the same base level as the InstalledFilesetLevel and a lower level than the RequiredFilesetLevel.

The (InstalledFilesetLevel) parameter is optional. If it is omitted, the Version and Release of theInstalledFilesetLevel and the RequiredFilesetLevel are assumed to be the same. If the FixLevel of the RequiredFilesetLevel is 0, the ModificationLevel and the FixLevel of the InstalledFilesetLevel are both 0. Otherwise, the InstalledFilesetLevel has a ModificationLevel that is the same as the ModificationLevel of the RequiredFilesetLevel and a FixLevel of 0. For example, if the RequiredFilesetLevel is 4.1.1.1 and no InstalledFilesetLevel parameter is supplied, the InstalledFilesetLevel is 4.1.1.0. If the RequiredFilesetLevel is 4.1.1.0 and no InstalledFilesetLevel parameter is supplied, the InstalledFilesetLevel is 4.1.0.0.

Installed requisite

An installed requisite indicates that the specified fileset should be installed automatically only if its corresponding fileset is already installed or is on the list of filesets to install. An installed requisite also is installed if the user explicitly requests that it be installed. A fileset update can not have an installed requisite. Because a fileset containing the message files for a particular package should not be installed automatically without some other part of the package being installed, a message fileset should always contain an installed requisite for another fileset in its product.

Syntax
*instreq Fileset RequiredFilesetLevel

Group requisite

A group requisite indicates that different requisite conditions can satisfy the requisite. A group requisite can contain prerequisites, corequisites, if-requisites, and nested group requisites. The Number preceding the { RequisiteExpressionList } identifies how many of the items in the RequisiteExpressionList are required. For example, >2 states that at least three items in the RequisiteExpressionList are required.

Syntax
>Number { RequisiteExpressionList }

Requisite information section examples

  1. The following example illustrates the use of corequisites. The book.create 12.30.0.0 fileset cannot function without the layout.text 1.1.0.0 and index.generate 2.3.0.0 filesets installed, so the requisite section for book.create 12.30.0.0 contains:
    *coreq layout.text 1.1.0.0
    *coreq index.generate 2.3.0.0
    The index.generate 3.1.0.0 fileset satisfies the index.generate requisite, because 3.1.0.0 is a newer level than the required 2.3.0.0 level.
  2. The following example illustrates the use of the more common requisite types. Fileset new.fileset.rte 1.1.0.0 contains the following requisites:
    *prereq database.rte 1.2.0.0
    *coreq spreadsheet.rte 1.3.1.0
    *ifreq wordprocessorA.rte (4.1.0.0) 4.1.1.1
    *ifreq wordprocessorB.rte 4.1.1.1

    The database.rte fileset must be installed at level 1.2.0.0 or higher before the new.fileset.rte fileset can be installed. If database.rte and new.fileset.rte are installed in the same installation session, the installation program installs the database fileset before the new.fileset.rte fileset.

    The spreadsheet.rte fileset must be installed at level 1.3.1.0 or higher for the new.fileset.rte fileset to function properly. The spreadsheet.rte fileset does not need to be installed before the new.fileset.rte fileset is installed, provided both are installed in the same installation session. If an adequate level of the spreadsheet.rte fileset is not installed by the end of the installation session, a warning message will be issued stating that the corequisite is not met.

    If the wordprocessorA.rte fileset is installed (or being installed with new.fileset.rte) at level 4.1.0.0, then the wordprocessorA.rte fileset update must be installed at level 4.1.1.1 or higher.

    If the wordprocessorB.rte fileset is installed (or being installed with new.fileset.rte) at level 4.1.1.0, then the wordprocessorB.rte fileset update must be installed at level 4.1.1.1 or higher.

  3. The following example illustrates an installed requisite. Fileset Super.msg.fr_FR.Widget at level 2.1.0.0 contains the following install requisite:
    *instreq Super.Widget 2.1.0.0

    The Super.msg.fr_FR.Widget fileset cannot be installed automatically when the Super.Widget fileset is not installed. The Super.msg.fr_FR.Widget fileset can be installed when the Super.Widget fileset is not installed if the fileset is listed explicitly on the list of filesets to be installed..

  4. The following example illustrates a group requisite. At least one of the prerequisite filesets listed must be installed (both can be installed). If installed, the spreadsheet_1.rte fileset must be at level 1.2.0.0 or higher or the spreadsheet_2.rte fileset must be at level 1.3.0.0 or higher.
    >0 {
    *prereq spreadsheet_1.rte 1.2.0.0
    *prereq spreadsheet_2.rte 1.3.0.0
    }

Size and license agreement information

The size and license agreement information section contains information about the disk space and license agreement requirements for the fileset.

Size Information

This information is used by the installation process to ensure that enough disk space is available for the installation or update to succeed. Size information has the form:
Directory PermanentSpace [TemporarySpace]

Additionally, the product developer can specify PAGESPACE or INSTWORK in the full-path name field to indicate disk space requirements for paging space and workspace needed in the package directory during the installation process.

Directory
The full path name of the directory that has size requirements.
PermanentSpace

The size (in 512-byte blocks) of the permanent space needed for the installation or update. Permanent space is space that is needed after the installation completes. This field has a different meaning in the following cases:

If Directory is PAGESPACE, PermanentSpace represents the size of page space needed (in 512-byte blocks) to perform the installation.

If Directory is INSTWORK, PermanentSpace represents the number of 512-byte blocks needed for extracting control files used during the installation. These control files are the files that are archived to the liblpp.a file.

TemporarySpace

The size (in 512-byte blocks) of the temporary space needed for the installation only. Temporary space is released after the installation completes. The TemporarySpace value is optional. An example of temporary space is the space needed to re-link an executable object file. Another example is the space needed to archive an object file into a library. To archive into a library, the installp command makes a copy of the library, archives the object file into the copied library, and moves the copied library over the original library. The space for the copy of the library is considered temporary space.

When Directory is INSTWORK, TemporarySpace represents the number of 512-byte blocks needed for the unextracted liblpp.a file.

The following example shows a size information section:
/usr/bin          30
/lib              40  20
PAGESPACE         10
INSTWORK          10    6

Because it is difficult to predict how disk file systems are mounted in the file tree, the directory path name entries in the size information section should be as specific as possible. For example, it is better to have an entry for /usr/bin and one for /usr/lib than to have a combined entry for /usr, because /usr/bin and /usr/lib can exist on different file systems that are both mounted under /usr. In general, it is best to include entries for each directory into which files are installed.

For an update package only, the size information must include any old files (to be replaced) that will move into the save directories. These old files will be restored if the update is later rejected. In order to indicate these size requirements, an update package must specify the following special directories:

/usr/lpp/SAVESPACE
The save directory for usr part files. By default, the usr part files are saved in the /usr/lpp/PackageName/FilesetName/FilesetLevel.save directory.
/lpp/SAVESPACE
The save directory for root part files. By default, the root part files are saved in the /lpp/PackageName/FilesetName/FilesetLevel.save directory.

License agreement information

A recent addition to the AIX install process allows product owners to require that a customer sign a license agreement before the install of the product. The installp command reads a fileset's lpp_name file as usual for any image. If there are LAF or LAR entries in the size section of the lpp_name file, the installp command calls the inulag command which displays the license in a window and records the customer acceptance of the license. If the customer refuses to accept the license, the installation is halted for that product.

Where to place the license file

Placement of the license files is up to the product owner. However, it is strongly suggested that the license be placed in /usr/swlag/LANG. The suggested name for the License Agreement file is given as ProductName_VersionRelease.la. There is no requirement to use this name or location. The installp command and this packaging is simply suppling a method to deliver the information to customers. All tools and file content must be provided by the product.

Translation requirements for the license file

If there is a requirement that the License Agreement files be translated into the supported languages, it is recommended that the files be separated into different files by language. This translation can require that several files be created.

How to ship the license file

A product can ship the license file as part of its main product or in a separate fileset for the product. Many products are choosing to create a separate fileset for shipping just the license files. This enables a product with many different features to create one license file and fileset that can ship on all the media required for each feature instead of having to include the files in several different features. The current suggestions for the fileset name are lpp.license or lpp.loc.license. Most products are currently using the first suggestion. If you want the license fileset to be hidden from the customer in standard installs, use lpp.loc.license because the license fileset does not need to be selected for installation.

How to package the license file

The file itself is never listed in the fileset.al or the fileset.inventory files for the fileset. The installp command finds the license because of the entry in the size section of the ProductName file. The types of entries are:
LAF

License Agreement File tells the installp command that this particular license file is shipped in this fileset.

License agreement files are indicated by a size section entry with:
LAF<lang>license_file size
Term
Meaning
LAF
stands for License Agreement File
<lang>
language to which the file is translated. These are typically entries like en_US, fr_FR, Ja_JP, and zh_TW. If <lang> is not specified, then the agreement file is assumed to be non-translated and encoded as ASCII. If the license agreement file is translated, <lang> must be part of the path so that the requirement entry can be associated with the file.
license_file
is the fullpath to the license file as it will be found in the image and placed on the system. The suggested path takes the form /usr/swlag/en_US/ProductName_VersionRelease.la
size
This is the real size in 512-byte blocks of the license file so as to ensure that installp has allowed enough space to place the license file on the system.
LAR

The License Agreement Requisite tells the installp command that this fileset requires the installation of the listed license agreement file. This is not the same as a prerequisite because it is in the file and not in a fileset. Files and filesets have different formats and different purposes. They should not be confused.

Term
Meaning
LAR
stands for License Agreement Requisite
req_license_file
The full path to the license file required to install this fileset. Typically these entries use %L in the path instead of the actual language name to allow for the appropriate file to be viewed without forcing the customer to view all of the languages.
Generally one fileset ships the files, and contains all of the LAF entries. The other filesets in the product which require this license only ship the LAR entry. The fileset which ships the LAF entries also contains the files listed at their full path location in the BFF image, but the files are not listed in the fileset.al or the fileset.inventory files for the fileset. The design used for electronic licenses does not require that the files be registered to the SWVPD. The installp command:
  1. Finds a requirement on the file.
  2. Checks the system to see if it was accepted.
  3. If the file was not accepted
    1. Finds the fileset that ships the file.
    2. Extracts (restores) only that file from the BFF image.
    3. Display the file to the customer.

LAF fileset example

The following is an example of a fileset that ships the license file:
iced.tea.loc.license 03.01.0000.0000 1 N U en_US IcedTea Recipe License Information
[
%
INSTWORK 16 160
LAF/usr/swlag/de_DE/iced.tea.la 24
LAF/usr/swlag/DE_DE/iced.tea.la 24
LAF/usr/swlag/en_US/iced.tea.la 24
LAF/usr/swlag/EN_US/iced.tea.la 24
LAF/usr/swlag/es_ES/iced.tea.la 24
LAF/usr/swlag/ES_ES/iced.tea.la 24
LAF/usr/swlag/fr_FR/iced.tea.la 24
LAF/usr/swlag/FR_FR/iced.tea.la 24
LAF/usr/swlag/it_IT/iced.tea.la 24
LAF/usr/swlag/IT_IT/iced.tea.la 24
LAF/usr/swlag/ja_JP/iced.tea.la 24
LAF/usr/swlag/JA_JP/iced.tea.la 32
LAF/usr/swlag/Ja_JP/iced.tea.la 24
LAF/usr/swlag/ko_KR/iced.tea.la 24
LAF/usr/swlag/KO_KR/iced.tea.la 24
LAF/usr/swlag/pt_BR/iced.tea.la 24
LAF/usr/swlag/PT_BR/iced.tea.la 24
LAF/usr/swlag/ru_RU/iced.tea.la 24
LAF/usr/swlag/RU_RU/iced.tea.la 48
LAF/usr/swlag/zh_CN/iced.tea.la 16
LAF/usr/swlag/zh_TW/iced.tea.la 16
LAF/usr/swlag/Zh_TW/iced.tea.la 16
LAF/usr/swlag/ZH_TW/iced.tea.la 24
%
%
%
]

LAR Fileset example

The following is an example of a fileset which ships the license requirement to the license file:
iced.tea.server 03.01.0000.0010 1 N B en_US Iced Tea Recipe Group
[
*prereq bos.net.tcp.client 5.1.0.10
*coreq iced.tea.tools 5.1.0.10
*coreq Java14.sdk 1.4.0.1
%
/usr/bin 624
/usr/lib/objrepos 24
/usr/include 16
/usr/include/sys 56
/usr/lpp/iced.tea 22
/usr/samples/iced.tea 8
/usr/samples/iced.tea/server 504
/usr/lpp/iced.tea/inst_root/etc/tea 8
/usr/iced.tea 8
/usr/lpp/iced.tea/inst_root/etc/tea/Top 8
INSTWORK 208 96
/lpp/iced.tea 104
/etc/tea 8
/etc/objrepos 8
/etc/tea/Top 8
/tmp 0 6
LAR/usr/swlag/%L/iced.tea.la 0
%
%
%
]

Supersede information section

The supersede information section indicates the levels of a fileset or fileset update for which this fileset or fileset update may (or may not) be used as a replacement. Supersede information is optional and is only applicable to AIX 4.1-formatted fileset base installation packages and AIX 3.2-formatted fileset update packages.

A newer fileset supersedes any older version of that fileset unless the supersedes section of the lpp_name file identifies the latest level of that fileset it supersedes. In the rare cases where a fileset does not supersede all earlier levels of that fileset, the installp command does not use the fileset to satisfy requisites on levels older than the level of the fileset listed in the supersedes section.

A fileset update supersedes an older update for that fileset only if it contains all of the files, configuration processing, and requisite information contained in the older fileset update. The installp command determines that a fileset update supersedes another update for that fileset in the following conditions:

  • The version, release, and modification levels for the updates are equal, the fix levels are both non-zero, and the update with the higher fix level does not contain a prerequisite on a level of the fileset greater than or equal to the level of the update with the lower fix level.
  • The version and release levels for the updates are equal, and the update with the higher modification level does not contain a prerequisite on a level of the fileset greater than or equal to the level of the update with the lower modification level.

For example, the fileset update farm.apps.hog 4.1.0.1 delivers an update of /usr/sbin/sellhog. Fileset update farm.apps.hog 4.1.0.3 delivers updates to the/usr/sbin/sellhog file and the /etc/hog file. Fileset update farm.apps.hog 4.1.1.2 delivers an update to the /usr/bin/raisehog file.

Update farm.apps.hog 4.1.0.3 supersedes farm.apps.hog 4.1.0.1 because it delivers the same files and applies to the same level, farm.apps.hog 4.1.0.0.

Update farm.apps.hog 4.1.1.2 does not supersede either farm.apps.hog 4.1.0.3 or farm.apps.hog 4.1.0.1 because it does not contain the same files and applies to a different level, farm.apps.hog 4.1.1.0. Update farm.apps.hog 4.1.1.0 supersedesfarm.apps.hog 4.1.0.1 and farm.apps.hog 4.1.0.3.

Supersede section for fileset installation levels (base levels)

An AIX 4.1-formatted fileset installation package can contain the following supersede entries:

Barrier Entry
Identifies the fileset level where a major incompatibility was introduced. Such an incompatibility keeps the current fileset from satisfying requisites to levels of the fileset earlier than the specified level.
Compatibility Entry
Indicates the fileset can be used to satisfy the requisites of another fileset. A compatibility entry is used when a fileset has been renamed or made obsolete. Only one fileset can supersede a given fileset. You may specify only one compatibility entry for each fileset.

The lpp_name file can contain at most one barrier and one compatibility entry for a fileset.

A barrier entry consists of the fileset name and the fileset level when the incompatibility was introduced. A barrier entry is necessary for a fileset only in the rare case that a level of the fileset has introduced an incompatibility such that functionality required by dependent filesets has been modified or removed to such an extent that requisites on previous levels of the fileset are not met. A barrier entry must exist in all subsequent versions of the fileset indicating the latest level of the fileset that satisfies requisites by dependent filesets.

For example, if a major incompatibility was introduced in fileset Bad.Idea 6.5.6.0, the supersede information section for each Bad.Idea fileset installation package from fileset level 6.5.6.0 onward would contain a Bad.Idea 6.5.6.0 barrier entry. This barrier entry would prevent a requisite of Bad.Idea 6.5.4.0 from being satisfied by any levels of Bad.Idea greater than or equal to 6.5.6.0.

A compatibility entry consists of a fileset name (different from the fileset in the package) and a fileset level. The fileset level identifies the level at which requisites to the specified fileset (and earlier levels of that fileset) are met by the fileset in the installation package. The compatibility is useful when the specified fileset is obsolete or has been renamed, and the function from the specified fileset is contained in the current fileset. The fileset level in the compatibility entry should be higher than any level expected to exist for the specified fileset.

As an example, assume the Year.Full 19.91.0.0 fileset is no longer delivered as a unit but is instead broken into several smaller, individual filesets. Only one of the smaller resulting filesets, perhaps Winter 19.94.0.0, should contain a compatibility entry of Year.Full 19.94.0.0. This compatibility entry allows the Winter 19.94.0.0 fileset to satisfy the requisites of filesets dependent on Year.Full at levels 19.94.0.0 and earlier.

Supersedes processing

The installp command provides the following special features for installing filesets and fileset updates which supersede other filesets or fileset updates:

  • If the installation media does not contain a fileset or fileset update that the user requested to install, a superseding fileset or fileset update on the installation media can be installed.

    For example, asume a user invokes the installp command with the -g flag (automatically install requisites) to install the farm.apps.hog 4.1.0.2 fileset. If the installation media contains the farm.apps.hog 4.1.0.4 fileset only, then the installp command will install the farm.apps.hog 4.1.0.4 fileset because it supersedes the requested level.

  • If the system and the installation media do not contain a requisite fileset or fileset update, the requisite can be satisfied by a superseding fileset or fileset update.
  • If an update is requested for installation and the -g flag is specified, the request is satisfied by the newest superseding update on the installation media.

    When the -g flag is specified with the installp command, any update requested for installation (either explicitly or implicitly) is satisfied by the newest superseding update on the installation media. If the user wants to install a particular level of an update, not necessarily the latest level, the user can invoke theinstallp command without the -g flag.

  • If an update and a superseding update (both on the installation media) are requested for installation, the installp command installs the newer update only.

    In this case, if a user wishes to apply a certain update and its superseding update from the installation media, the user must do separate installp operations for each update level. Note that this kind of operation is meaningless if the two updates are applied and committed (-ac). Committing the second update removes the first update from the system.

Fix information section

The fix information section is optional. The fix information section entries contain a fix keyword and a 60 characters or less description of the problem fixed. A fix keyword is a 16 characters or less identifier corresponding to the fix. Fix keywords beginning with ix, iy, IY andIX are reserved for use by the operating system manufacturer.

A technology level is a fix that is a major update level. Periodic preventive maintenance packages are technology levels. A technology level identifier begins with the name of the software product (not the package), followed by a single dot (.) and an identifying level, such as farm.4.1.1.0.

The liblpp.a installation control library file

The liblpp.a file is an archive file that contains the files required to control the package installation. You can create a liblpp.a file for your package using the ar command with the -g flag on systems later than AIX 4.3 to ensure that a 32 bit archive is created. This section describes many of the files you can put in a liblpp.a archive.

Throughout this section, Fileset appears in the names of the control files. Fileset represents the name of the separate fileset to be installed within the software package. For example, assume the apply list file is described as Fileset.al. The apply list file for the bos.net.tcp.client option of the bos.net software product would then be bos.net.tcp.client.al.

For any files you include in the liblpp.a archive file other than the files listed in this section, you should use the following naming conventions:
  • If the file is used in the installation of a specific fileset, the file name should begin with the Fileset. prefix.
  • If the file is used as a common file for several filesets in the same package, the file name should begin with the lpp. prefix.

Many files described in this section are optional. An optional file is necessary only if the function the file provides is required for the fileset or fileset update. Unless stated, a file pertains to both full installation packages and fileset update packages.

Data files contained in the liblpp.a file

Fileset.al
Apply list. This file lists all files to be restored for this fileset. Files are listed one per line with a path relative to root, as in ./usr/bin/pickle. An apply list file is required if any files are delivered with the fileset or fileset update.
Fileset.cfginfo
Special instructions file. This file lists one keyword per line, each keyword indicating special characteristics of the fileset or fileset update. The only currently recognized keyword is BOOT, which causes a message to be generated after installation is complete indicating that the system needs to be restarted.
Fileset.cfgfiles
List of user-configurable files and processing instructions for use when applying a newer or equal installation level of a fileset that is already installed. Before restoring the files listed in the Fileset.al file, the system saves the files listed in Fileset.cfgfiles file. Later, these saved files are processed according to the handling methods specified in the Fileset.cfgfiles file.
Fileset.copyright
Required copyright information file for the fileset. This file consists of the full name of the software product followed by the copyright notices.
Fileset.err
Error template file used as input to the errupdate command to add or delete entries in the Error Record Template Repository. This file is commonly used by device support software. The errupdate command creates a Fileset.undo.err file for cleanup purposes. See the errupdate command for information about the format of the Fileset.err file. This file can only be included in the root part of a fileset.
Fileset.fixdata
Stanza format file. This file contains information about the fixes contained in a fileset or fileset update.
Fileset.inventory
The inventory file. This file contains required software vital product data for the files in the fileset or fileset update. The inventory file is a stanza-format file containing an entry for each file to be installed or updated.
Fileset.namelist
List of obsolete filesets and current fileset (if applicable) that once contained files now existing in the fileset to be installed. This file is used for installation of repackaged software products only.
Fileset.odmadd or Fileset.*.odmadd
Stanzas to be added to ODM (Object Data Manager) databases.
Fileset.rm_inv
Remove inventory file. This file is for installation of repackaged software products only and must exist if the fileset is not a direct replacement for an obsolete fileset. This stanza-format file contains names of files that need to be removed from obsolete filesets.
Fileset.size
This file contains the space requirements for the files included in this fileset as described earlier in this section.
Fileset.trc
Trace report template file. The trcupdate command uses this file to add, replace, or delete trace report entries in the /etc/trcfmt file. The trcupdate command creates a Fileset.undo.trc file for cleanup purposes. Only the root part of a package can contain Fileset.trc files.
lpp.acf
Archive control file for the entire package. This file is needed only when adding or replacing an archive member file to an archive file that already exists on the system. The archive control file consists of lines containing pairs of the member file in the temporary directory as listed in the Fileset.al file and the archive file that the member belongs to, both listed relative to root as in:
./usr/ccs/lib/libc/member.o ./usr/ccs/lib/libc.a
lpp.README
Readme file. This file contains information the user should read before using the software. This file is optional and can also be named README, lpp.doc, lpp.instr, or lpp.lps.
productid
Product identification file. This file consists of a single line indicating the product name, the product identifier (20-character limit), and the optional feature number (10-character limit).

Optional executable files contained in the liblpp.a file

The product-specific executable files described in this section are called during the installation process. Unless otherwise noted, file names that end in _i are used during installation processing only, and file names that end in _u are used in fileset update processing only. All files described in this section are optional and can be either shell scripts or executable object modules. Each program should have a return value of 0 (zero), unless the program is intended to cause the installation or update to fail.

Fileset.config or Fileset.config_u
Modifies configuration near the end of the default installation or update process. Fileset.config is used during installation processing only.
Fileset.odmdel orFileset.*.odmdel
Updates ODM database information for the fileset prior to adding new ODM entries for the fileset. The odmdel file naming conventions enables a fileset to have multiple odmdel files.
Fileset.pre_d
Indicates whether a fileset may be removed during deinstall. The program must return a value of 0 (zero) if the fileset can be removed. Filesets are removable by default. The program should generate error messages indicating why the fileset is not removable.
Fileset.pre_i or Fileset.pre_u
Runs prior to restoring or saving the files from the apply list in the package, but after removing the files from a previously installed version of the fileset.
Fileset.pre_rej
Runs prior to the reject operation or prior to the preview of a reject operation of the fileset. Use the script to determine whether the fileset can be rejected. Do not use this script to run any commands which change anything on the system. If the script exits with a non-zero return code, the reject operation is not allowed.
Fileset.pre_rm
Runs during a fileset installation prior to removing the files from a previously installed version of the fileset.
Fileset.post_i or Fileset.post_u
Runs after restoring the files from the apply list of the fileset installation or update.
Fileset.unconfig Fileset.unconfig_u
Undoes configuration processing performed in the installation or update during a deinstall or a reject of a fileset. Fileset.unconfig is used during deinstallation processing only.
Fileset.unodmadd
Deletes entries that were added to ODM databases during the installation or update.
Fileset.unpost_i orFileset.unpost_u
Undoes processing performed following restoring the files from the apply list in the installation or update during a deinstall or a reject of a fileset.
Fileset.unpre_i or Fileset.unpre_u
Undoes processing performed prior to restoring the files from the apply list in the installation or update during a deinstall or a reject of a fileset.

If any of these executable files runs a command that may change the device configuration on a machine, that executable file should check the INUCLIENTS environment variable before running the command. If the INUCLIENTS environment variable is set, the command should not be run. The Network Installation Management (NIM) environment uses the installp command for many purposes, some of which require the installp command to bypass some of its normal processing. NIM sets the INUCLIENTS environment variable when this normal processing must be bypassed.

If the default installation processing is insufficient for your package, you can provide the following executable files in the liblpp.a file. If these files are provided in your package, the installp command uses your package-provided files in place of the system default files. Your package-provided files must contain the same functionality as the default files or unexpected results can occur. You can use the default files as models for creating your own files. Use of the default files in place of package-provided files is strongly recommended.

instal
Used in place of the default installation script /usr/lib/instl/instal. The installp command calls this executable file if a fileset in an installation package is applied.
lpp.cleanup
Used in place of the default installation cleanup script /usr/lib/instl/cleanup. The installp command calls this executable file if a fileset in an installation or update package has been partially applied and must be cleaned up to put the fileset back into a consistent state.
lpp.deinstal
Used in place of the default fileset removal script /usr/lib/instl/deinstal. This executable file must be placed in the /usr/lpp/PackageName directory. The installp command calls this executable file if a fileset in an installation package is removed.
lpp.reject
Used in place of the default installation rejection script /usr/lib/instl/reject. The installp command calls this executable if a fileset update in an update package is rejected. (The default /usr/lib/instl/reject script is a link to the /usr/lib/instl/cleanup script.)
update
Used in place of the default fileset update script /usr/lib/instl/update. The installp command calls this executable file if a fileset in an update package is applied. (The default /usr/lib/instl/update script is a link to the /usr/lib/instl/instal script.)
To ensure compatibility with the installp command, the instal or update executable provided with a software package must:
  • Process all of the filesets in the software package. It can either process the installation for all the filesets or invoke other executables for each fileset.
  • Use the inusave command to save the current level of any files to be installed.
  • Use inurest command to restore all required files for the usr part from the distribution media.
  • Use the inucp command to copy all required files for the root part from the /usr/lpp/Package_Name/inst_root directory.
  • Create an $INUTEMPDIR/status file indicating success or failure for each fileset being installed or updated.
  • Return an exit code indicating the status of the installation. If the instal or update executable file returns a nonzero return code and no status file is found, the installation process assumes all filesets failed.

Optional executable file contained in the Fileset.al file

Fileset.unconfig_d
Undoes fileset-specific configuration operations performed during the installation and updates of the fileset. The Fileset.unconfig_d file is used when the -u flag is specified with the installp command. If this file is not provided and the -u flag is specified, the Fileset.unconfig, Fileset.unpost_i, and Fileset.unpre_i operations are performed.

Further description of installation control fileseThe Fileset.cfgfiles file

The Fileset.cfgfiles file lists configuration files that need to be saved in order to migrate to a new version of the fileset without losing user-configured data. To preserve user-configuration data, a Fileset.cfgfiles file must be provided in the proper liblpp.a file (usr or root).

The Fileset.cfgfiles contains a one-line entry for each file to be saved. Each entry contains the file name (a path name relative to root), a white-space separator, and a keyword describing the handling method for the migration of the file. The handling method keywords are:

preserve
Replaces the installed new version of the file with the saved version from the save directory. After replacing the new file with the saved version, the saved file from the configuration save directory is deleted.
auto_merge
During the Fileset.post_i processing, the product-provided executables merge necessary data from the installed new version of the file into the previous version of the file saved in the configuration save directory. After the Fileset.post_i processing, the installp command replaces the installed new version of the file with the merged version in the configuration save directory (if it exists) and then removes the saved file.
hold_new
Replaces the installed new version of the file with the saved version from the save directory. The new version of the file is placed in the configuration save directory in place of the old version. The user will be able to reference the new version.
user_merge
Leaves the installed new version of the file on the system and keeps the old version of the file in the configuration save directory. The user will be able to reference the old version to perform any merge that may be necessary. This keyword should be avoided if possible.
other
Used in any case where none of the other defined handling methods are sufficient. The installp command saves the file in the configuration save directory and provides no further support. Any other manipulation and handling of the configuration file must be done by the product-provided executables. The product developer has the responsibility of documenting the handling of the file.

The Fileset.post_i executable can be used to do specific manipulating or merging of configuration data that cannot be done through the default installation processing.

Configuration files listed in the Fileset.cfgfiles file are saved in the configuration save directory with the same relative path name given in the Fileset.cfgfiles file. The name of the configuration save directory is stored in the MIGSAVE environment variable. The save directory corresponds to the part of the package being installed. The following directories are the configuration save directories:

/usr/lpp/save.config
For the usr part
/lpp/save.config
For the root part

If the list of files that you need to save varies depending on the currently installed level of the fileset, the Fileset.cfgfiles file must contain the entire list of configuration files that might be found. If necessary, the Fileset.post_i executable (or executables provided by other products) must handle the difference.

For example, assume you have a fileset (change.rte) that has one file that can be configured. So, in the root change.rte.cfgfiles, there is one file listed:

/etc/change_user   user_merge

When migrating from your old fileset (change.obj) to change.rte, you cannot preserve this file because the format has changed. However, when migrating from an older level change.rte to a newer level change.rte, the file can be preserved. In this case, you might want to create a change.rte.post_i script that checks to see what fileset you are migrating from and acts appropriately. This way, if a user had made changes to the /etc/change_user file, they are saved.

The root change.bar.post_i script could be as follows:
#! /bin/ksh
rc=0
grep -q change.rte $INSTALLED_LIST
if [$? = 0]
then
mv $MIGSAVE/etc/change_user/ /etc/change_user
rc=1
fi
exit $rc

$INSTALLED_LIST is created and exported by installp. See Installation for Control Files Specifically for Repackaged Products for more information about theFileset.installed_list configuration file. The $MIGSAVE variable contains the name of the directory in which the root part configuration files are saved.

The installp command does not produce a warning or error message if a file listed in the Fileset.cfgfiles file is not found. The installp command also does not produce a message for a file that is not found during the phase following Fileset.post_i processing when saved configuration files are processed according to their handling methods. If any warning or error messages are desired, the product-provided executables must generate the messages.

As an example of the Fileset.cfgfiles file, the Product_X.option1 fileset must recover user configuration data from three configuration files located in the root part of the fileset. The Product_X.option1.cfgfiles is included in the root part of the liblpp.a file and contains the following:
./etc/cfg_leafpreserve
./etc/cfg_pudding hold_new
./etc/cfg_newtonpreserve

The Fileset.fixdata file

Fileset.fixdata
A stanza-format file that describes the fixes contained in the fileset update (or in a fileset installation, if used in place of an update)

The information in this file is added to a fix database. The instfix command uses this database to identify fixes installed on the system. If the Fileset.fixdata exists in a package, the fix information in the fix database is updated when the package is applied.

Each fix in the fileset should have its own stanza in the Fileset.fixdata file. A Fileset.fixdata stanza has the following format:

fix:
name = FixKeyword
abstract = Abstract
type = {f | p}
filesets = FilesetName FilesetLevel
[FilesetName FilesetLevel ...]
[symptom = [Symptom]]
  • FixKeyword cannot exceed 16 characters.
  • Abstract describes the fix and can not exceed 60 characters.
  • In the type field, f represents a fix, and p represents a preventive maintenance update.
  • The filesets field contains a new-line separated list of filesets and fileset levels.
  • FilesetLevel is the initial level in which the fileset delivered all or part of the fix.
  • Symptom is an optional description of the problem corrected by the fix. Symptom does not have a character limit.

The following example shows aFileset.fixdata stanza for problem MS21235. The fix for this problem is contained in two filesets.

fix:
name = MS21235
abstract = 82 gigabyte diskette drive unusable on Mars
type = f
filesets = devices.mca.8d77.rte 12.3.6.13
devices.mca.8efc.rte 12.1.0.2
symptom = The 82 gigabyte subatomic diskettes fail to operate in a Martian environment.

The Fileset.inventory file

Fileset.inventory
File that contains specific information about each file that is to be installed or updated for the fileset
sysck
Command that uses the Fileset.inventory file to enter the file name, product name, type, checksum, size, link, and symlink information into the software information database

The Fileset.inventory file is required for each part of a fileset that installs or update files. If the package has a root part that does not contain files to be installed (it does configuration only), the root part does not require the Fileset.inventory file.

Note: The Fileset.inventory file does not support files which are greater than 2 GB in size. If you ship a file that is greater than 2 GB, include it in your fileset.al file, but not in your Fileset.inventory file. sysck has not been updated to handle files larger than 2GB, and the /usr file system on most machines will not be created with capability for files greater than 2GB (by default).

The inventory file consists of ASCII text in stanza format. The name of a stanza is the full path name of the file to be installed. The stanza name ends with a colon (:) and is followed by a new-line character. The file attributes follow the stanza name and have the format Attribute=Value. Each attribute is described on a separate line.

A Fileset.inventory stanza has the following format:
inventory:
type     = type
class    = inventory,apply,C2_exclude,fileset
owner    = owner_name
group    = group_name
mode     = TCB | SUID | SGID,permissions
target   = fullpath_filename
link     = fullpath_to_hardlink [additional_hardlinks]
size     =<blank> | VOLATILE |size
checksum =<blank> | VOLATILE |"checksum"
Attribute Description
file_name The full path to the file or link relative to root (./) followed immediately by a colon (:) and then a new line. The maximum length for this full pathname is 255 characters.
type Type of the file_name entry where a valid type is one of the following:
Keywords
Meaning
FILE
Standard file
DIRECTORY
Directory
SYMLINK
The fullpath to a symbolic link
class Specifies how the file_name is to be referenced during installation. This field must have at least two of the following keywords:
Type Items
Meaning
inventory
Indicates that the file remains after the installation is complete. The file is added to the inventory SWVPD database. This should not be used with an A type file in the fileset.il file.
apply
Indicates that the file is to be restored from the install media. The file_name field is listed in the apply list (fileset.al). This should not be used for an I type file in the fileset.il file.
C2_exclude
Indicates that this file should be excluded from execution on a C2 Secure system. If this flag is used, the file should also be listed in the fileset.tcb file.
owner Specifies the file owner after installation. Do not use the uid for this field. The attribute value must be the owner name and must be no more than 8 characters.
group Specifies the file group. Do not use the gid for this field. The attribute value must be the group name and must be no more than 8 characters.
mode Specifies the file mode. The value must contain the permissions of the file in octal format. Any of the following keywords can precede the permissions value. Items in the list are separated by commas.
Mode Items
Meaning
TCB
Part of the "Trusted Computing Base". If the file is SUID root or SGID system, then the file must be TCB.
SUID
This file has the set user ID bit set. This has no meaning on a DIRECTORY entry.
SGID
This file has the set group ID bit set. If set on a DIRECTORY entry, this forces all files created in that directory to have the same group as the directory.
permissions
Must be a three-digit octal number, for example, 644.
Note: If the type is SYMLINK, the mode must be 777. No other entries are valid.
link Lists any hard links to this file. If multiple hard links exist, each fullpath to a hard link is separated by a comma. The hardlinks must reside in the same directory as the source file. If the type of the entry is SYMLINK, link is not valid. The maximum length of the full path name is 255 characters.
target Valid only for type=SYMLINK. This is the full path filename to the target of the link. If the link being created is from /usr/bin to /bin, the filename would be /bin and the target would be /usr/bin. The maximum length of the full path name is 255 characters.
size
Mode Items
Meaning
blank
If this field is blank, the size of the filename is determined at the time of installation. The drawback to using this option is that if a file was corrupted during installation, the customer is not informed.
VOLATILE
If the file size is expected to change through normal operation, the value for this attribute must be VOLATILE.
size
The exact size of the file.
Note: Do not include the size field for DIRECTORY or SYMLINK entries.
checksum
Mode Items
Meaning
blank
If this field is blank, the value returned from the sum -r command to be placed in the inventory SWVPD database when the file is installed.
VOLATILE
Specifies the size of the file in blocks. If the file size is expected to change through normal operation, the value for this attribute must be VOLATILE.
checksum
The exact sum of the file as returned by the sum -r command. This should be placed in double quotes.
Note: Do not include the checksum field for DIRECTORY or SYMLINK entries.

fileset

Indicates the fileset to which the file belongs.
Note: The sysck command creates hard links and symbolic links during installation if those links do not exist. The root part symbolic links should be packaged in the root part Fileset.inventory file.

fileset.inventory example

The following fileset.inventory example demonstrates the use of type.

/usr/bin:
        owner = bin
        group = bin
        mode = 755
        type = directory
        class = apply,inventory,bos.rte


/usr/bin/tcbck:
        owner = root
        group = security
        mode = TCB,SUID,550
        type = file
        class = apply,inventory,bos.rte.security
        size = 99770
        checksum = "17077     98 "


/usr/sbin/tsm:
        owner = root
        group = security
        mode = TCB,SUID,555
        links = /usr/sbin/getty,/usr/sbin/login
        class = apply,inventory,bos.rte,security
        size = 55086
        checksum = "57960     54 "

Installation control files specifically for repackaged products

Fileset.installed_list
File created by the installp command when installing the fileset from a package if it is found that the fileset (or some form of it) is already installed on the system at some level

The software information database is searched to determine if either Fileset or any filesets listed in the file Fileset.namelist (if it exists) are already installed on the system. If so, the fileset and the installation level are written to the Fileset.installed_list file.

If it is created, the Fileset.installed_list is available at the time of the calls to the rminstal and instal executables. The Fileset.installed_list file can be located in the following directories, the packaging working directories, or PackageWorkDirectory:
/usr/lpp/
PackageName for the usr part
/lpp/
PackageName for the root part

The Fileset.installed_list file contains a one-line entry for each fileset that was installed. Each entry contains the fileset name and the fileset level.

As an example, assume that while the storm.rain 1.2.0.0 fileset is being installed, the installp command discovers that storm.rain 1.1.0.0 is already installed. The installp command would then create the PackageWorkDirectory/storm.rain.installed_list file with the following contents:
storm.rain 1.1.0.0
As another example, asume the Baytown.com fileset contains a Baytown.com.namelist file with the following entries:
Pelly.com
GooseCreek.rte
CedarBayou.stream 
While installing the Baytown.com 2.3.0.0 fileset, the installp command finds that Pelly.com 1.2.3.0 and CedarBayou.stream 4.1.3.2 are installed. The installp command creates the PackageWorkDirectory/Baytown.com.installed_list file with the following contents:
Pelly.obj 1.2.3.0
CedarBayou.stream 4.1.3.2

The Fileset.namelist file

Attribute Description
Fileset.namelist This file is necessary when the fileset name has changed or the fileset contains files previously packaged in obsolete filesets. It contains names of all filesets that previously contained files currently included in the fileset to be installed. Each fileset name must appear on a separate line.

The Fileset.namelist file must be provided in the usr or root part of theliblpp.a file. The Fileset.namelist file is only valid for installation packages; it is not valid for update packages.

At the beginning of installation, the installp command searches the Software Vital Product Data (SWVPD) to determine if the fileset or any fileset listed in the Fileset.namelist file is already installed on the system. The installp command writes to the Fileset.installed_list file the fileset names and fileset levels that are found installed, making this information available to product-provided executables.

As a simple example of a Fileset.namelist file, assume the small.business fileset replaces an earlier fileset named family.business. The small.business product package contains the small.business.namelist file in its usr part liblpp.a file. The small.business.namelist file contains the following entry:
family.business
As a more complex example of a Fileset.namelist file would be where a fileset is divided into a client fileset and a server fileset. The LawPractice.client and LawPractice.server filesets replace the earlier lawoffice.mgr fileset. The LawPractice.server fileset also contains a few files from the obsolete BusinessOffice.mgr fileset. TheLawPractice.client.namelist file in the liblpp.a file for the LawPractice package contains the following entry:
lawoffice.mgr
The LawPractice.server.namelist file in the liblpp.a file for the LawPractice package contains the following entries:
lawoffice.mgr
BusinessOffice.mgr

If the Fileset.namelist file contains only one entry and the current fileset is not a direct replacement for the fileset listed in the Fileset.namelist file, you must include a Fileset.rm_inv file in the liblpp.a file. The installation process uses the Fileset.namelist file and the Fileset.rm_inv file to determine if a fileset is a direct replacement for another fileset. If the Fileset.namelist file contains only one entry and there is no Fileset.rm_inv file, the installation process assumes the new fileset is a direct replacement for the old fileset. When the new (replacement) fileset is installed, the installation process removes from the system all files from the old (replaced) fileset, even files not included in the new fileset.

In the previous examples, the small.business fileset is a direct replacement for the family.business fileset, so a small.business.rm_inv file should not exist. The LawPractice.client fileset is not a direct replacement for the lawoffice.mgr fileset, so a LawPractice.client.rm_inv file must exist, even if it is empty.

Example 3:

Filesets bagel.shop.rte and bread.shop.rte have been shipping separately for years. Now, bagel.shop.rte is going to ship as a part of bread.shop.rte. For this to happen, the bread.shop.rte.namelist file would look like:
bread.shop.rte
bagel.shop.rte

You must also ship an empty bread.shop.rte.rm_inv file to indicate that all files from the bagel.shop.rte fileset should be removed from the system.

The Fileset.rm_inv file

Attribute Description
Fileset.rm_inv File that contains a list of files, links, and directories to be removed from the system if they are found installed

This file is used when the current fileset is packaged differently from a previous level of the fileset and the installation process should not remove previously installed files based on the fileset's entries in the inventory database.

A simple name change for a fileset is not sufficient to require a Fileset.rm_inv file. The Fileset.rm_inv file is necessary when a new fileset is either a subset of a previous fileset or a mixture of parts of previous filesets. If a Fileset.namelist file exists and contains entries for more than one fileset, you must use the Fileset.rm_inv file to remove previously installed levels of the files from the system.

The Fileset.rm_inv file consists of ASCII text in stanza format. The name of a stanza is the full path name of the file or directory to be removed if found on the system. The stanza name ends with a colon (:) and is followed by a new-line character. If attributes follow the stanza name, the attributes have the format Attribute=Value. Attributes are used to identify hard links and symbolic links that need to be removed. Each attribute is described on a separate line. The following list describes the valid attributes associated with the listed file:

Attribute Description
links One or more hard links to the file. The full path names of the links are delimited by commas.
symlinks One or more symbolic links to the file. The full path names of the links are delimited by commas.
Note: Links need to be listed twice, once as a standalone stanza and once as an attribute to the file that is linked to.

For example, assume the U.S.S.R 19.91.0.0 fileset contains the following files in the /usr/lib directory: moscow, leningrad, kiev, odessa, and petrograd (a symbolic link to leningrad). The product developers decide to split the U.S.S.R 19.91.0.0 fileset into two filesets: Ukraine.lib 19.94.0.0 and Russia.lib 19.94.0.0. The Ukraine.lib fileset contains the kiev and odessa files. TheRussia.lib fileset contains the moscow file. The leningrad file no longer exists and is replaced by the st.petersburg file in the Russia.lib fileset.

The Ukraine.lib.rm_inv file must exist because the Ukraine.lib fileset is not a direct replacement for the U.S.S.R fileset. The Ukraine.lib.rm_inv file should be empty because no files need to be removed when the Ukraine.lib fileset is installed to clean up the migrating U.S.S.R fileset.

The Russia.lib.rm_inv file must exist because the Russia.lib fileset is not a direct replacement for the U.S.S.R fileset. If the Russia.lib.rm_inv file is used to remove the leningrad file when the Russia.lib fileset is installed, the Russia.lib.rm_inv file would contain the following stanza:
/usr/lib/leningrad:
 symlinks = /usr/lib/petrograd
/usr/lib/petrograd:

Installation files for supplemental disk subsystems

A disk subsystem that will not configure with the provided SCSI or bus-attached device driver requires its own device driver and configuration methods. These installation files are provided on a supplemental diskette (which accompanies the device) and must be in backup format with a ./signature file and a ./startup file. The signature file must contain the string target. The startup file must use restore by name to extract the needed files from the supplemental diskette and to run the commands necessary to bring the device to the available state.

Format of distribution media

The following types of media can be used to distribute software product installation packages.

The following sections describe the formats that must be used to distribute multiple product packages on each of these media.

Tape

In order to stack multiple product package images onto either a single tape or a set of tapes, the files on each tape in the set must conform to the following format:

  • File 1 is empty. (Reserved for bootable tapes.)
  • File 2 is empty. (Reserved for bootable tapes.)
  • File 3 contains a table of contents file that describes product package images on the set of tapes. Therefore, each tape in the set contains a copy of the same table of contents file, except for the difference of the tape volume number in a multi-volume set.
  • Files 4 through (N+3) contain the backup-format file images for product packages 1 through N.
  • A product package image file cannot span across two tapes.
  • Each file is followed by an end-of-file tape mark.

CD-ROM

A CD-ROM that is to contain multiple product package images must be compliant with the Rock Ridge Group Protocol. Product packages should be stored in the installation directory, which must contain the following:

  • The backup-format file images of the product packages.
  • A table of contents file named .toc that describes the product package images in the directory.

A multiple volume CD-ROM is a CD-ROM that has an additional directory structure to define a set of CD-ROMs as a single installable unit.

A multiple volume CD-ROM must conform to the following rules:
  • A /installp/mvCD directory exists with the following contents:
    1. A table of contents file (.toc) that describes the product package images on all of the CD-ROMs of the set. Each volume of the CD-ROM must have the same .toc in /installp/mvCD.
    2. An ASCII file named volume_id in which the first line consists of the decimal volume number of the CD in the set1.
    3. A symbolic link named vol% n, where n is the decimal volume number of the of the CD in the set. The target of the symbolic link must be a relative path to the directory of product packages on that particular volume of the CD. The standard value for the symbol link is ../ppc.
  • The table of contents file (.toc) in the /installp/mvCD conforms to the standard table of contents format. The special characteristic of the multiple volume .toc is that the location of each product package image begins with the directory entry vol% n, where n indicates the volume which contains that particular product package.

AIX 5.2 Example:

fileset A is in file A.bff on volume 1. fileset B is in file B.bff on volume 2. The field in the table of contents file in /installp/mvCD containing the location of the product package images for A and B are vol%1/A.bff and vol%2/B.bff, respectively. The field in the table of contents file in /installp/ppc of volume 1 contains the location of A as A.bff. The field in the table of contents file in /installp/ppc of volume 2 contains the location of B as B.bff.

The CD-ROM directory structure for AIX 5.1 and later allows for specification of other installers, as well as multiple platforms.

Diskette

In order to stack multiple product package images onto a set of diskettes, the following files must be written to the set of diskettes:

  • A table of contents file that describes product package images to be included in the set.
  • Each product package image file that is to be included in the set.

The files are written to the set of diskettes using the following rules:

  • Write the data as a stream to the diskette set with a volume ID sector inserted in block 0 of each diskette in the set. The data from the last block of one volume is treated as logically adjacent to the data from block 1 of the next volume (the volume ID sector is verified and discarded when read).
  • Each file begins on a 512-byte block boundary.
  • Write the table of contents file first. Pad this file to fill its last sector with null characters (x'00'). At least one null character is required to mark the end of the table of contents file. Thus, a full sector of null characters may be required.
  • Following the table of contents file, write each of the product package image files to successive sectors. Pad each file to fill its last sector using null characters. A null character is not required if the file ends on the block boundary.
  • Block 0 of each diskette in the set contains a volume ID sector. The format of this sector is:
    Position Description
    Bytes 0:3 A magic number for identification. This is a binary integer with a value of decimal 3609823513=x'D7298918'.
    Bytes 4:15 A date and time stamp (in ASCII) that serves as the identification for the set of diskettes. The format is MonthDayHourMinuteSecondYear. The Hour should be a value from 00 to 23. All date and time fields contain two digits. Thus, Month should be represented as 03 instead of 3, and Year should be represented as 94 instead of 1994.
    Bytes 16:19 A binary integer volume number within this set of diskettes. The first diskette in the set is x'00000001'.
    Bytes 20:511 Binary zeroes.

The table of contents file

Field Name Format Separator Description
1. Volume Character White space For the tape and diskette table of contents file, this is the number of the volume containing this data. For the fixed disk or CD-ROM table of contents file, the volume number is 0.
2. Date and time stamp mmddhhMMssyy White space For tape or diskette, this is the time stamp when volume 1 was created. For fixed disk or CD-ROM, this is the time stamp when the .toc file was created. See Date and Time Stamp Format later in this article for detailed description.
3. Header format Character New line A number indicating the format of the table of contents file. Valid entries are:
  • 1 -AIX Version 3.1
  • 2 -Version 3.2
  • 3 -AIX Version 4.1 or later
  • B -mksysb tape (invalid for use by installp)
4. Location of product package image Character White space For tape or diskette, this is a character string in the form: vvv:bbbbb:sssssssSee Location Format for Tape and Diskette later in this article for detailed description. For fixed disk or CD-ROM, this is the file name of the product package image file. Note that this is the file name only and must not be preceded by any part of the path name.
5. Package specific information lpp_name file format New line The contents of the lpp_name file contained in this product package image. See The lpp_name Package Information File for detailed description.
Note: Items 4 and 5 described in the preceding table are repeated for each product package image contained on the media.

Date and time stamp format

A date and time stamp format is an ASCII string that has the following format:

MonthDayHourMinuteSecondYear

The Hour should be a value from 00 to 23. All date and time fields contain two digits. Thus, Month should be represented as 03 instead of 3, and Year should be represented as 94 instead of 1994.

Location format for tape and diskette

The location has the format of vvv:bbbbb:sssssss where each letter represents a digit and has the following meaning:

For tape

vvv
is the volume number of the tape.
bbbbb
is the file number on the tape of the product package image.
ssssssss
is the size of the file in bytes.

For diskette

vvv
is the volume number of the diskette.
bbbbb
is the block number on diskette where the product package image file begins.
ssssssss
is the size of the file in bytes (including padding to the end of the block boundary).

AIX Relocatable Install

While AIX relocatable installation is now supported with the native AIX installation utilities (such as installp, instfix, lslpp, and lppchk), the use of relocation is of particular interest to applications that need to be installed within a Workload Partition. This is because default System WPAR configurations do not include a writeable /usr or /opt filesystem. Therefore, application installation may need to be retargeted to locations other than the traditional /usr or /opt location.

In addition to being able to install filesets in the default install location (that is, “/”), an administrator can now install relocatable packages into alternate root install locations. This enables the administrator to do the following:
  • Install and maintain multiple installations of the same installp package in a single instance of the AIX operating system
  • Install and maintain multiples versions of the same installp package in a single instance of the AIX operating system
  • Use native installp tracking tools (such as lppchk, lslpp, instfix, and inulag) to verify and report installation data on all relocated installation instances
  • Attach and detach pre-installed software locations on a given system (application hosting).

Terminology

root install path
The base directory where an application is installed. The installp default install path is "/".
default install path
The default root install path (that is, "/").
relocated install path
Any root install path that is not the default install path. The path location may be any valid path that is not "/" and that has a size no greater than 512 characters.
relocatable application
An application that can be installed in a non-default root install path.
USIL (User Specified Install Location)
A relocated install path instance set up by the user.

USIL

A User Specified Install Location, or USIL, is a tracked relocated install path that is created by the administrator. This location is tracked by the system and can be used as an alternate install path for packages that support relocation. Multiple instances and/or versions of the same software package can be installed on a single system by delegating each installation to a separate USIL. An existing USIL instance may be attached or detached from any given system.

Each USIL instance maintains its own set of Software Vital Product Data (SWVPD) in all three current installp parts:
  • <InstallRoot>/etc/objrepos
  • <InstallRoot>/usr/lib/objrepos
  • <InstallRoot>/usr/share/lib/objrepos
Notes:
  1. The current SWVPD object classes include the following:
    • product
    • lpp
    • inventory
    • history
    • fix
    • vendor
    • lag
  2. Each USIL instance will mirror the default SWVPD structure within the relocated path.

USIL management commands

/usr/sbin/mkusil

Creates or attaches a new USIL instance.

mkusil -R RelocatePath -c Comments [XFa]

-a
Attach an existing installation as a USIL instance
-c
Comments to include in the USIL definition (visible with the lsusil command)
-R
Path to new USIL location. Must be a valid directory.
-X
Automatically expand of space needed

/usr/sbin/lsusil

Lists existing USIL instances.

lsusil [-R RelocatePath | "ALL"]

-R
Path to existing USIL location.

/usr/sbin/rmusil

Removes an existing USIL instance.

rmusil -R RelocatePath

-R
Path to existing USIL location.
Note: The rmusil command only removes the USIL reference in the SWVPD. No files are removed in the USIL install path.

/usr/sbin/chusil

Changes an attribute of an existing USIL instance.

chusil -R RelocatePath -c NewComments [X]

-c
New comments to include in the USIL definition (visible with the lsusil command).
-R
Path to existing USIL location.
-X
Automatically expand if space needed

Relocatable installation utilities

To preserve code isolation, all USIL changes are isolated to separately compiled modules. The relocated installation utilities include the following user level modules:
  • /usr/sbin/mkusil
  • /usr/sbin/rmusil
  • /usr/sbin/lsusil
  • /usr/sbin/chusil
Note:
  1. Each utility takes the -R RelocatePath flag.
  2. When working with relocatable installp packages, the above utilities must be used.

Requirements for relocatable applications packaging

The application packaging must support relocatable installation. The following are the recommended guidelines:
  • A relocatable application package may not deliver (write) inventory objects outside of its root install location.
  • A relocatable application package may not deliver (write) data using packaging customization outside of its root install location.
  • The relocatable application package must contain the RELOCATABLE extended packaging attribute for each relocatable fileset. The fileset is the smallest installable unit that may be relocated.
  • The relocatable application package may not have requisites that are located in external relocated paths. It may have requisites to filesets installed in the default install path or in its own install path.

Requirements for relocatable application execution

The application design must support execution from an installation environment. The following are the recommended guidelines:
  • The application must have a method to determine its root install location or function such that it has no dependency on the install location.
  • The application must reference all application specific executable components relative to its root install location.
  • The application must reference all application specific data components relative to its root install location or it must be designed to share the data with other application instances.
  • The application should not make any persistent changes outside of its root install location.

USIL connector ODM class object

The USIL connector ODM Class Object resides in the /etc/objrepos/usilc file and contains data that links the default SWVPD with all USIL instances.

The following is the entry for this object class that will be contained in swvpd.cre:
/*  User Install Location Connector                                    */
/*  Connects the default install path to all relocated install paths.  */
class   usilc {
        vchar   path[1024];             /* USIL path */
        vchar   comments[2048];   /* USIL Comments */
        long    flags;                       /* USIL flags */
        };     

Listing all install paths with the -R "ALL" or -R "all" option

The lslpp and lppchk commands can perform listing operations on all install locations if the -R "ALL" syntax is used.

Attach/Detach Operations

The attach operation allows the user to integrate an existing detached USIL path into the SWVPD.

For example, if the administrator creates a master USIL instance with various relocatable applications installed for the purposes of application hosting. The administrator then copies or NFS mounts this USIL instance to various systems and uses the attach feature to integrate the USIL instance into the SWVPD. The detach operation removes reference to the USIL instance.

installp licensing

A new USIL instance starts out with an empty LAG (installp license agreement ODM object class). Any installation of filesets or LPPs that require a license will require a license acceptance according to normal installp conventions. The license acceptance does not span USIL instances.

|Trusted Computing Base (TCB)

Installing USIL instances is currently not supported on TCB enabled systems.

Relocatable requisites

A new packaging semantic indicates the relocatable requisite location. A packager can specify that a given requisite should be found in the default install path or in the relocated install path.

The following new requisite semantic applies:
  • prereq_ r = prereq in relocated install path
  • ifreq_r = ifreq in relocated install path
  • coreq_r = coreq in relocated install path
  • instreq_r = instreq in relocated install path

The currently defined requisites types (prereq, ifreq, coreq, and instreq) are all default requisites (requisites that apply to the default install location).

TOC changes for relocatable packages

The following is a sample of the new requisite sections in the TOC file:
sscp.rte.1.0.0.5.U.PRIVATE.bff 4 R S sscp {
sscp.rte 01.00.0000.0005 1 N B En_US Sscp
[
*coreq bos.games 1.1.1.1  <-- default requisite in default requisite section
*prereq bos.rte 1.1.1.1   <-- default requisite in default requisite section
%
/usr/bin 20
/etc 20
INSTWORK 72 40
%
%
%
IY99999  1 APAR text here.
%
RELOCATABLE <-- attribute tag to denote relocatable package
%
*prereq bos.rte 1.1.1.1 <-- default requisite in relocated requisite section
*coreq_r bos.games 1.1.1.1 <-- relocated requisite in relocated requisite section
]
}
Notes:
  1. If the relocatable requisite section is present during a relocated installation, it is used as the requisite section for the installation.
  2. If the relocatable requisite section is not present during a relocated installation, the default requisite section is used. This means all requisites will be default requisites.
  3. A default installation (non-relocated) does not use the relocatable requisite section.

The installp processing of product packages

Command Description
Apply When a fileset in a product installation package is applied, it is installed on the system and it overwrites any preexisting version of that fileset, therefore committing that version of the fileset on the system. The fileset may be removed if the user decides the fileset is no longer required.

When a fileset update is applied, the update is installed and information is saved (unless otherwise requested) so that the update can be removed later. Fileset updates that were applied can be committed or rejected later.

Commit When a fileset update is committed, the information saved during the apply is removed from the system. Committing already applied software does not change the currently active version of a fileset.
Reject When an update is rejected, information saved during the apply is used to change the active version of the fileset to the version previous to the rejected update. The saved information is then removed from the system. The reject operation is valid only for updates. Many of the same steps in the reject operation are performed in a cleanup operation when a fileset or fileset update fails to complete installation.
Remove When a fileset is removed, the fileset and its updates are removed from the system independent of their state (applied, committed, or broken). The remove operation is valid only for the installation level of a fileset.

Executables provided within a product package can tailor processing for the apply, reject, and remove operations.

Reinstalling a fileset does not perform the same actions that removing and installing the same fileset do. The reinstall action (see /usr/lib/instl/rminstal) cleans up the current files from the previous or the same version, but does not run any of the unconfig or unpre* scripts. Therefore, do not assume that the unconfig script was run. The .config script should check the environment before assuming that the unconfig was completed.

For example, for a ras.berry.rte fileset, the config script adds a line to root's crontab file. Reinstalling the ras.berry.rte fileset results in two crontab entries, because the unconfig script was not run on reinstall (which removed the crontab entry). The config script should always remove the entry and then add it again.

Processing for the Apply Operation

This section describes the steps taken by the installp command when a fileset or fileset update is applied.

  1. Restore the lpp_name product package information file for the package from the specified device.
  2. Verify that the requested filesets exist on the installation media.
  3. Check the level of the requested filesets to ensure that they may be installed on the system.
  4. Restore control files from the liblpp.a archive library file into the package directory (/usr/lpp/Package_Name for usr or usr/root packages. The control files specifically for the root portion of a usr/root package reside in /usr/lpp/Package_Name/inst_root/liblpp.a).
  5. Check disk space requirements.
  6. Check that necessary requisites (filesets required to be at certain levels to use or install another fileset) are already installed or are on the list to be installed.
  7. Determine if there are license agreement requirements which must be satisfied in order to proceed with the installation.
  8. If this is an installation package rather than a fileset update package, search the software vital product data (SWVPD) to see if Fileset (the fileset being installed) or any filesets listed in the Fileset.namelist file are already installed on the system at any level. If Fileset is already installed, write the fileset name and installed level to the Work_Directory/Fileset.installed_list file.

    If no level of Fileset is installed, then if any filesets listed in the Fileset.namelist file are installed, list all those filesets and levels in theWork_Directory/Fileset.installed_list file. Work_Directory is the same as the package directory with the exception of root parts, which use/lpp/Package_Name.

  9. If this is an installation package rather than a fileset update package, run the /usr/lib/instl/rminstal script to do the following for each fileset being installed.
    Note: Unless otherwise specified, files checked for existence must have been restored from the liblpp.a control file library.
    1. If Fileset.pre_rm exists, run Fileset.pre_rm to perform required steps before removing any files from this version or an existing version of Fileset.
    2. If Work_Directory/Fileset.installed_list exists, move the existing files listed in Fileset.cfgfiles to the configuration file save directory (indicated by the MIGSAVE environment variable).
    3. If a version of Fileset is already installed, remove the files and SWVPD information (except history) for Fileset.
    4. If Work_Directory/Fileset.installed_list exists, and Fileset.rm_inv exists or Fileset.namelist contains more than one fileset or the only fileset listed in Fileset.namelist is bos.obj, then do the following:
      1. Remove files and SWVPD inventory information for files listed in the file Fileset.rm_inv.
      2. Remove files and SWVPD inventory information for files listed in the file Fileset.inventory.
      3. Remove other SWVPD information for any filesets listed in Fileset.namelist which no longer have any SWVPD inventory information.
    5. If Work_Directory/Fileset.installed_list exists and contains only one fileset and Fileset.namelist contained only one fileset, Remove files and SWVPD information (except history) for that fileset.
    6. For each part of a product package (usr part only or usr followed by root)
      1. Set INUTREE (U for usr and M for root) and INUTEMPDIR (name of created temporary working directory environment variables.
      2. If an instal control program exists in the package directory (not recommended), run ./instal, otherwise, run the default script /usr/lib/instl/instal. If an instal control program does not exist in the package directory, set INUSAVEDIR environment variable.
      3. If an update control program exists in the package directory (not recommended), run ./update. If an update control program does not exist in the package directory, run the default script /usr/lib/instl/update.
      4. If a status file has been successfully created by instal or update, Use status file to determine the success or failure of each fileset. If a status file has not been created, assume all requested filesets in package failed to apply.
      5. If the apply operation for a fileset was successful, update the Software Vital Product Data (SWVPD), then register any associated license agreement requirements. If the apply operation for a fileset was not successful, run /usr/lib/instl/cleanup or the package-supplied lpp.cleanup from package directory to clean up the failed filesets.

Processing of the default install or update script

The instal or update executable is invoked from installp with the first parameter being the device being used for the installation or update. The second parameter is the full path name to the file containing the list of filesets to be installed or updated, referred to below as $FILESETLIST. The default instal and update scripts are linked together; processing varies based on whether it is invoked as instal or update.The current directory is the package directory. A temporary directory INUTEMPDIR is created in /tmp to hold working files.

The flow within the default instal and update script is as follows:

  1. Do the following for each fileset listed in the $FILESETLIST:
    1. If the fileset is an update, Execute Fileset.pre_u (pre_update) if it exists. If the fileset is not an update, execute Fileset.pre_i (pre_installation) if it exists.
    2. Build a master list of files to be restored from the package by appending Fileset.al to the new file INUTEMPDIR/master.al.
    3. If this is an update, the files are specified to be saved, and the lpp.acf archive control file exists.

      Save off the library archive members being updated.

    4. If the processing is successful, append this fileset to the list to be installed in the $FILESETLIST.new file.
  2. If this is an update and file saving is specified, run inusave to save current versions of the files.
  3. If you are processing the root part, run inucp to copy files from the apply list to root part. If you are not processing root part, run inurest to restore files from apply list for the usr part.
  4. Do the following for each fileset listed in $FILESETLIST.new file:
    Note: Failure in any step is recorded in the status file and processing for that fileset ends
    1. Determine if this fileset is installed at the same or older level, or if filesets listed in the Fileset.namelist are installed. If so, export the INSTALLED_LIST and MIGSAVE environment variables. This is called a migration.
    2. If you are processing an update, invoke Fileset.post_u if it exists. If Fileset.post_u does not exist, invoke Fileset.post_i if it exists.
    3. If Fileset.cfgfiles exists, run /usr/lib/instl/migrate_cfg to handle processing of configuration files according to their specified handling method.
    4. Invoke sysck to add the information in the Fileset.inventory file to the Software Vital Product Database (SWVPD).
    5. Invoke the tcbck command to add the trusted computing base information to the system if the Fileset.tcb file exists and the trusted computing base tcb_enabled attribute is set in the /usr/lib/objrepos/PdAt ODM database.
    6. Invoke errupdate to add error templates if Fileset.err exists.
    7. Invoke trcupdate to add trace report format templates if Fileset.trc exists.
    8. If update or if Work_Directory/Fileset.installed_list exists, invoke each Fileset.odmdel and Fileset.*.odmdel script to process ODM database deletion commands.
    9. Invoke odmadd on each existing Fileset.odmadd and Fileset.*.odmadd to add information to ODM databases.
    10. If this is an update, invoke Fileset.config_u (fileset configuration update) if it exists. Otherwise, invoke Fileset.config (fileset configuration) if it exists.
    11. Update the status file indicating successful processing for the fileset.
  5. Link control files for needed for fileset removal into the package's deinstl directory for future use. These files include the following files that might be present in the package directory:
    • lpp.deinstal
    • Fileset. al
    • Fileset. inventory
    • Fileset. pre_d
    • Fileset. unpre_i
    • Fileset. unpre_u
    • Fileset. unpost_i
    • Fileset. unpost_u
    • Fileset. unodmadd
    • Fileset. unconfig
    • Fileset. unconfig_u
    • $SAVEDIR/Fileset. *.rodmadd
    • SAVEDIR/Fileset. *.unodmadd

Processing for the reject and cleanup operations

This section describes the steps taken by the installp command when a fileset update is rejected or when a fileset or fileset update fails to complete installation. The default cleanup and reject scripts located in /usr/lib/instl are linked together. Their logic differs slightly depending on whether the script was invoked as reject or cleanup. For usr/root filesets or fileset updates, the root part is processed before the usr part.

  1. If rejecting, check requisites to ensure that all dependent product updates are also rejected.
  2. For each part of a package (for example, usr and root):
    1. Set INUTREE (U for usr and M for root.) and INUTEMPDIR environment variables.
    2. If reject control file exists in current directory (INULIBDIR), invoke ./lpp.reject. Otherwise, invoke the default script /usr/lib/instl/reject.
  3. Update the Software Vital Product Data.

The reject executable is invoked from installp with the first parameter being undefined and the second parameter being the full path name to the file containing the list of filesets (referred to below as $FILESETLIST) to be rejected for the update.

The following files are referenced by the default cleanup and reject script.

The flow within the default cleanup and reject script is as follows:

  1. Do the following for each fileset listed in $FILESETLIST:
    1. If invoked as cleanup, then read the line in the Package_Name.s status file to determine which step the installation failed on and skip ahead to the undo action for that step. A cleanup operation will only begin at the step where the installation failed. For example, if the installation of a fileset failed in the Fileset.post_i script, then the cleanup operation for that fileset would begin at i, because there are no actions to undo from subsequent steps in the installation.
    2. Undo any configuration processing performed during the installation:

      If rejecting an update, invoke Fileset.unconfig_u if it exists. Otherwise, invoke Fileset.unconfig if it exists.

    3. Run any Fileset.*.unodmaddand/or Fileset.unodmadd files to remove Object Data Manager (ODM) entries added during the installation.
    4. Run any Fileset.*.rodmadd and/or Fileset.rodmadd exist to replace ODM entries deleted during the installation.
    5. Invoketrcupdate if Fileset.undo.trc exists to undo any trace format template changes made during the installation.
    6. Invoke errupdate if Fileset.undo.err exists to undo any error format template changes made during the installation.
    7. Invoke tcbck to delete the trusted computing base information to the system if the Fileset.tcb file exists and the trusted computing base attribute tcb_enabled is set in the /usr/lib/objrepos/PdAt ODM database.
    8. Invoke sysck if Fileset.inventory exists to undo changes to the software information database.
    9. Undo any post_installation processing performed during the installation:

      If this is an update, invoke Fileset.unpost_u if it exists. Otherwise, invoke Fileset.unpost_i if it exists.

    10. Build a master apply list (called master.al) from Fileset.al files.
    11. Add Fileset to $FILESETLIST.new.
  2. Do the following if $INUTEMPDIR/master.al exists.
    1. Change directories to / (root).
    2. Remove all files in master.al.
  3. Do the following while reading $FILESETLIST.new.
    1. Call inurecv to recover all saved files.
    2. If this is an update, invoke Fileset.unpre_u if it exists. Otherwise, invoke Fileset.unpre_i if it exists.
    3. Delete the install/update control files.
  4. Remove the Package_Name.s status file.

Processing for the remove operation

This section describes the steps taken by the installp command when a fileset is removed. For usr/root filesets or fileset updates, the root part is processed before the usr part.

  1. Check requisites to ensure that all dependent filesets are also removed.
  2. For each part of a product package (for example, usr or root):
    1. Set INUTREE (U for usr, M for root, and S for share) and INUTEMPDIR (installp working directory generated in /tmp) environment variables.
    2. Change directory to INULIBDIR.
    3. If the deinstal control file exists in current directory, run the ./lpp.deinstalscript. If the deinstal control file does not exist in current directory, run the /usr/lib/instl/deinstal default script.
  3. Remove files belonging to the fileset from the file system.
  4. Remove fileset entries from the SWVPD except for history data.
  5. Deactivate license agreement requirement registration for the fileset.

The deinstal executable is invoked from installp with the first parameter being the full path name to the file containing the list of filesets to be removed, referred to below as $FILESETLIST.

The flow within the default deinstal script is as follows:

  1. Do the following for each fileset listed in input file $FILESETLIST:
  2. If Fileset.unconfig_d exists

    Execute Fileset.unconfig_d to remove all configuration changes, Object Data Manager (ODM) changes, and error and trace format changes, and to undo all operations performed in the post-installation and pre-installation scripts for all updates and the base level installation. Use of this file is not recommended.

  3. If Fileset.unconfig_d does not exist,
    1. For each update for that fileset, do the following:
      • Run all Fileset.unconfig_u scripts to undo any update configuration processing.
      • Run all Fileset.*.unodmadd and Fileset.unodmadd to delete Object Data Manager (ODM) entries added during the update.
      • Run all Fileset.*.rodmadd and Fileset.rodmadd to add Object Data Manager (ODM) entries deleted during the update.
      • Run errupdate if Fileset.undo.err exists to undo error log template changes.
      • Run trcupdate if Fileset.undo.trc exists to undo trace report template changes.
      • Run any Fileset.unpost_u to undo any post-installation customization.
    2. For the fileset base installation level, do the following:
      • Run any Fileset.*.unodmaddand/or Fileset.unodmadd to delete Object Data Manager (ODM) entries added during the installation.
      • Run any Fileset.*.rodmadd and/or Fileset.rodmadd to add Object Data Manager (ODM) entries deleted during the installation.
      • Run errupdate if Fileset.undo.err exists to undo error log template changes.
      • Run trcupdate if Fileset.undo.trc exists to undo trace report template changes.
      • Run Fileset.unconfig_i to undo any installation configuration processing.
      • Run Fileset.unpost_i to undo any post-file installation customization.
  4. Remove the files and software data information installed with the fileset.
  5. If Fileset.unconfig_d does not exist,
    1. For each update for that fileset, run any Fileset.unpre_u to undo any pre-file installation customization.
    2. For the fileset base installation level, run any Fileset.unpre_i to undo any pre-file installation customization.
  6. Delete any empty directories associated with the fileset.
    Note: If an error is returned from some call during the execution of the deinstal executable, the error will be logged, but execution will continue. This is different from the other scripts because execution for that fileset is normally canceled once an error is encountered. However, once the removal of a fileset has begun, there is no recovery; therefore, removal becomes a best effort once an error is found.

The installation status file

$INUTEMPDIR/status
File that contains a one-line entry for each fileset that was to be installed or updated

The installp command uses this status file to determine appropriate processing. If you create installation scripts, your scripts should produce a status file that has the correct format. Each line in the status file has the format:

StatusCode Fileset
Status code Meaning
s Success, update SWVPD
f Failure, perform cleanup procedure
b Bypass, failed, cleanup not needed
i Requisite failure, cleanup not needed
v sysck verification failed

The following example of a status file indicates to the installp command that the installations for the tcp.client and tcp.server filesets of bos.net package were successful and the installation for the nfs.client fileset was not successful.

s bos.net.tcp.client
s bos.net.tcp.server
f bos.net.nfs.client
Installation commands used during installation and update processing
inucp
Copies files from the /usr/lpp/Package_Name/inst_root directory to the / (root) file tree when installing the root part.
inulag
Acts as the front end to the subroutines to manage license agreements.
inurecv
Recovers saved files for installation failure or software rejection (installp -r).
inurest
Restores files from the distribution medium onto the system using an apply list as input.
inusave
Saves all files specified by an apply list into the save directory belonging to the software product.
inuumsg
Issues messages from the inuumsg.cat message catalog file for the software product being installed.
ckprereq
Verifies compatibility of the software product with any dependencies using requisite information supplied in the lpp_name file and information about already installed products found in the SWVPD.
sysck
Checks the inventory information during installation and update procedures.
The sysck command is in the /usr/bin directory. Other commands listed previously are in the /usr/sbin directory.

For examples of their use, refer to the default installation script, /usr/lib/instl/instal.