[ Previous | Next | Contents | Glossary | Home | Search ]
AIX Version 4.3 General Programming Concepts: Writing and Debugging Programs

Chapter 20. Packaging Software for Installation

This article provides information about preparing applications to be installed using the AIX 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 are part of a software installation or update package.

An AIX software product installation package is an AIX backup-format file containing 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 containing modifications to an existing fileset.

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

This article contains the following main sections:

Note: Starting in AIX 4.3, a new service is available to application developers. If your online documentation is written in HTML, you can use the AIX Documentation Search Service to provide search functions within your documents. For information on how to build your install package to use this service, see "Documentation Search Service" before you build your install package.

Installation Procedure Requirements

Package Control Information Requirements

Package Partitioning Requirements

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 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.
share Contains the part of the product that can be shared among several machines, even if the machines have a different hardware architecture. The share part of the product can include non-executable files, such as documentation and data files. For a standard system, files are stored in the /usr/share file tree. A share part fileset package must be separately packaged from usr and root parts, and the fileset name cannot be the same as a fileset which has usr or root parts.

Sample File System Guide for Package Partitioning

Following is a brief description of some AIX 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:

/usr/bin User commands and scripts
/usr/sbin System administration commands
/usr/include Include files
/usr/lib Libraries, non-user commands, and architecture-dependent data

Some share-part directories and their contents:

/usr/share/dict Dictionary files
/usr/share/man Manual pages

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. See Format of Distribution Media for information about the format used for product packages on each type of media.

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. All package names must be unique.

A fileset name has the form:

PackageName[[.SubProduct].Option]

If a package has only one installable fileset, the fileset name may be the same as the PackageName.

SubProduct identifies the set of filesets within the package.

Option further describes the fileset and may contain a fileset extension.

A fileset name contains more than one character and begins with a letter or an underline (_). Subsequent characters can be letters, digits, underlines, dots (.), plus signs (+), minus signs (-), exclamations (!), tildes (~ ), percent signs (%), and carets (^). A fileset name cannot end with a dot. All characters in a fileset name are ASCII characters. The maximum length for a fileset name is 144 bytes. All fileset names must be unique within the package.

Fileset Extension Naming Conventions

The following list provides some 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
.data Share portion of a package
.diag Diagnostics support
.fnt Fonts
.info. Language InfoExplorer databases for a particular language
.help. Language Common Desktop Environment (CDE) help files for a particular language
.loc Locale
.mp Multiprocessor-specific code
.msg. Language Message files for a particular language
.rte Run-time environment or minimum set for a product
.ucode Microcode
.up Uniprocessor-specific code

Special Naming Considerations for Device Driver Packaging

The cfgmgr (configuration manager command) automatically installs software support for detectable devices that are available on the installation media and packaged with the following naming convention:

devices.BusTypeID.CardID

BusTypeID Specifies the type of bus to which the card attaches (for example, mca for Micro Channel Adapter
CardID Specifies the unique hexadecimal identifier associated with the card type

For example, a token-ring device attaches to the Micro Channel and is identified by the configuration manager as having a unique card identifier of 8fc8. The package of filesets associated with this token-ring device is named devices.mca.8fc8. A microcode fileset within this package is named devices.mca.8fc8.ucode.

Special Naming Considerations for Message Catalog Packaging

A user installing a package can request 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 U.S. 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 U.S. 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 on another fileset in the product in order to avoid accidental 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.

Fileset Revision Level Identification

Fileset Level Overview

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.ModificationLevel.FixLevel[.FixID]
Version A numeric field of 1 to 2 digits that identifies the version number.
Release A numeric field of 1 to 2 digits that identifies the release number.
ModificationLevel A numeric field of 1 to 4 digits that identifies the modification level.
FixLevel A numeric field of 1 to 4 digits that identifies the fix level.
FixID A character field of 1 to 9 characters identifying the fix identifier. The FixID is used by Version 3.2-formatted fileset updates only.

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 Version 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, 3.2.0.0 is a newer level than 2.3.0.0).

Fileset Level Rules and Conventions for AIX Version 4.1-Formatted Filesets

The following conventions and rules have been put in place in order to simplify the software maintenance for product developers and customers:

Compatibility Information For Version 3.2-Formatted Fileset Updates

The fix identifier is required for all 3.2-formatted update packages. It is not allowable in any other types of software packages.

The fix identifier is not allowed as part of the product level for a base fileset installation level.

The fix identifier contains ASCII characters only. The first character must be a letter. Subsequent characters can be letters or digits. All fix identifiers must be unique within a product.

Fix identifiers beginning with U4 are reserved for the AIX operating system manufacturer.

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 (or for the obsolete 3.2->formatted updates, PackageName/inst_FixID where FixID is the fix ID of the update).

The usr part of an installation or update package contains the following installation control files:

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. See The lpp_name Package Information File for more information.

This archive file contains control files used by the installation process for installing or updating the usr part of the software package. See The liblpp.a Installation Control File for information about files contained in this archive library.

If the installation or update package contains a root part, the root part contains the following files:

This library file contains control files used by the installation process for installing or updating the root part of the software package.

If the software product has a share part, it must be packaged in a separate installation package from the usr and root parts. The backup format file that makes up an installation or update package for the share part of a software product must contain the following files:

This file provides information about the share part of the software package to be installed or updated.

This library file contains control files used by the installation process for installing or updating the share part of the software package.

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 that 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 Example lpp_name File 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.

The following table defines the fields in the lpp_name file.

Fields in the lpp_name File
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 Version 3.1
  • 3 - Version 3.2
  • 4 - AIX Version 4.1
2. Platform Character White space Indicates the platform for which this package was built. The only available value is R.
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 - Maintenance level update
The following types are valid for Version 3.2-formatted update packages only:
  • G -Single update required
  • M -Maintenance packaging update
  • MC -Cumulative packaging update
  • ME -Enhancement packaging update
4. Package Name 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.ModificationLevel.FixLevel .FixID should be appended for Version 3.2-formatted updates only.
7. Diskette Volume Integer White space Indicates the diskette volume number where the fileset is located, if shipped on diskette.
8. Bosboot Character White space Indicates whether a bosboot is needed following the installation. The values are:
  • N - Do not invoke bosboot
  • b - Invoke bosboot
9. Content Character White space Indicates the parts included in the fileset or fileset update. The values are:
  • B -usr and root part
  • H -share part
  • U -usr part only
10. Language Character White space Not used.
11. Description Character # or new line Fileset description.
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 information Described later in this chapter New line Size requirements for the fileset by directory. See Size Information Section later in this article for detailed description.

% New line Indicates the separation between size and supersede information.
15. Supersede information Described later in this chapter New line (Optional) Information on what the fileset replaces. This field should exist in Version 3.2-formatted updates only. See Supersede Information Section later in this article for detailed description.

% New line Indicates the separation between supersede and licensing information.
16. Fix information Described later in article New line Information regarding the fixes contained in the fileset update. See Fix Information Section later in this article 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.

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 by mechanisms 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
Syntax *prereq Fileset RequiredFilesetLevel
Alternate Syntax Fileset RequiredFilesetLevel
Description A prerequisite indicates that the specified fileset must be installed at the specified fileset level or at a higher level for the current fileset to 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 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.

Co-requisite
Syntax *coreq Fileset RequiredFilesetLevel
Description A co-requisite 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 unmet co-requisites. A co-requisite is most commonly used for a fileset within the same package. A prerequisite on a fileset within the same package is not guaranteed.
If-requisite
Syntax *ifreq Fileset [(InstalledFilesetLevel)] RequiredFilesetLevel
Description 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 A.obj (1.1.0.0) 1.1.2.3

If the A.obj fileset is not already installed, this example does not cause it to be installed. If the A.obj 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 A.obj 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 the InstalledFilesetLevel 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
Syntax *instreq Fileset RequiredFilesetLevel
Description 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 contain an installed-requisite for another fileset in its package.
Group Requisite
Syntax >Number { RequisiteExpressionList }
Description A group requisite indicates that different requisite conditions can satisfy the requisite. A group requisite can contain prerequisites, co-requisites, 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.
Alternate Requisite Syntax for AIX Versions 3.1 and 3.2 Compatibility

For compatibility with AIX Versions 3.1- and 3.2-formatted packages, you can specify RequiredFilesetLevel using an alternate syntax. This alternate syntax cannot be used for an AIX Version 4.1-formatted fileset update that contains a prerequisite on another level of the same fileset.

The alternate syntax consists of logical expressions using the letters v (version number), r (release number), m (modification level), f (fix level), and p ( Version 3.2-format update fix ID) and the symbols <, =, and >. If multiple conditions apply to a field, an o (or symbol) is used to identify an alternate acceptable condition for the previously mentioned field. The following example specifies a prerequisite on the old.syntax fileset with the version number 3 and the release level greater than or equal to 2.

*prereq old.syntax v=3 r=2 o>2

Because the installp command interprets the specified requisite as the minimum fileset level that will satisfy the requisite, o>2 can not be specified the following example. The following example is equivalent to the preceding example:

*prereq old.syntax 3.2.0.0

Alternate syntax containing a fix ID is handled differently than in Version 3.2. If the RequiredFilesetLevel expression contains more information than just a fix ID, either a newer base level of the fileset or the fix (defined by the fix ID) satisfies the requisite. (A supersede entry can still block a newer base level from satisfying the requisite. See Supersede Information Section for more information about supersede entries.) For example, the old.syntax 1.3.0.0 fileset satisfies the following requisite:

*prereq old.syntax v=1 r=2 p=U412345

The alternate syntax also can be used to define a requisite that is lower than a certain level. For example, the old.syntax fileset at a lower level than 1.3.0.0 satisfies the following requisite:

*prereq old.syntax v=1 r<3
Requisite Information Section Examples
  1. The following example illustrates the use of co-requisites. 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 1.2.0.0
    *coreq spreadsheet 1.3.1.0
    *ifreq wordprocessorA (4.1.0.0) 4.1.1.1
    *ifreq wordprocessorB 4.1.1.1
    The database fileset must be installed at level 1.2.0.0 or higher before the new.fileset.rte fileset can be installed. If database and new.fileset.rte are installed in the same installation session, the installation program will install the database fileset before the new.fileset.rte fileset.

    The spreadsheet fileset must be installed at level 1.3.1.0 or higher for the new.fileset.rte fileset to function properly. The spreadsheet 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 fileset is not installed by the end of the installation session, a warning message will be issued stating that the co-requisite is not met.

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

    If the wordprocessorB fileset is installed (or being installed with new.fileset.rte) at level 4.1.1.0, the wordprocessorB 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:
    Super.Widget 2.1.0.0
    The Super.msg.fr_FR.Widget fileset can not be installed automatically when the Super.Widget fileset is not installed. The Super.msg.fr_FR.Widget fileset can be installed explicitly when the Super.Widget fileset is not 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 fileset must be at least at level 1.2.0.0 and the spreadsheet_2 fileset must be at least at level 1.3.0.0.
    >0 {
    *prereq spreadsheet_1 1.2.0.0
    *prereq spreadsheet_2 1.3.0.0
    }
  5. The following example illustrates use of the alternate requisite syntax for compatibility with AIX Versions 3.1- and 3.2-formatted packages. The following requisite expressions are all equivalent to the expression *prereq database 1.2.0.0 and will be satisfied as described in Example 2.
    *prereq database v=1 r=2
    *prereq database v=1 r=2 o=3
    *prereq database v=1 r=2 o>2
    *prereq database v=1 r=2 m=0 f=0
    Note: The preceding examples stated that levels higher than the level specified in the requisite expression satisfy the requisite. This is not true when the required fileset indicates it has broken compatibility by including a barrier entry in the supersede information section of the lpp_name file. See Supersede Information Section for more information.

Size Information Section

The size information section contains information about the disk space requirements for the fileset. This information is used by the installation process to ensure that enough disk space is available for the installation or update to succeed. The size information section 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 work space 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 relink 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.
/usr/share/lpp/SAVESPACE The save directory for share part files. By default, the share part files are saved in the /usr/share/lpp/PackageName/inst_FixID.save directory.

The following save directories are used for obsolete 3.2-formatted fileset updates only:

/usr/lpp/PackageName/inst_FixID.save Directory for usr part files.
/lpp/PackageName/inst_FixID.save Directory for root part files.
/usr/share/lpp/PackageName/inst_FixID.save Directory for share part files.

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 Version 4.1-formatted fileset base installation packages and Version 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:

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 supersedes farm.apps.hog 4.1.0.1 and farm.apps.hog 4.1.0.3.

Supersede Section for Fileset Installation Levels (Base Levels)

An AIX Version 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.

For example, the Year.Full 19.91.0.0 fileset is no longer delivered as a unit and 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.

Supersede Section for Version 3.2-Formatted Updates

A Version 3.2-formatted fileset update can supersede another update for that fileset if each file and configuration action contained in the older update are contained in the newer update and if each of those filesets can be applied to the same fileset installation level. The installp command does not use the fileset level and prerequisite information to determine if a Version 3.2-formatted fileset update supersedes another. Instead, the Version 3.2-formatted fileset update must explicitly list each fix identifier that the update supersedes. The supersedes section for a Version 3.2-formatted fileset update consists of a newline-separated list of entries. Each entry contains the fileset name and the fix identifier of the superseded fileset.

Supersedes Processing

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

For example, the 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, the installp command will install the farm.apps.hog 4.1.0.4 fileset because it supersedes the requested level.

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 the installp command without the -g flag.

In the last 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 and is only applicable to update packages. The fix information section entries contain a fix keyword and a 60-character or less description of the problem fixed. A fix keyword is a 16-character or less identifier corresponding to the fix. Fix keywords beginning with ix and IX are reserved for use by the AIX operating system manufacturer.

A maintenance level is a fix that is a major update level. AIX periodic preventive maintenance packages are maintenance levels. A maintenance 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 AIX 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. 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, 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 is 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:

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.
Fileset.fixdata Optional 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 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
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.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 optional 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
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
Fileset.*.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. The program must return a value of 0 (zero) if the fileset may be removed. Filesets are removable by default. The program should generate error messages indicating why the fileset is not removable.
Fileset.pre_i
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_rm Runs during a fileset installation prior to removing the files from a previously installed version of the fileset.
Fileset.post_i
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. Fileset.unconfig is used during installation processing only.
Fileset.unodmadd Deletes entries that were added to ODM databases during the installation or update.
Fileset.unpost_i_0
Fileset.unpost_u Undoes processing performed following restoring the files from the apply list in the installation or update.
Fileset.unpre_i
Fileset.unpre_u Undoes processing performed prior to restoring the files from the apply list in the installation or update.

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:

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 Files

The 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, root, or share).

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.
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.
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.
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 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
/usr/share/lpp/save.config For the share 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, you have a fileset (foo.rte) that has one file that can be configured. So, in the root foo.rte.cfgfiles, there is one file listed:

/etc/foo_user   user_merge

When migrating from your old fileset (foo.obj) to foo.rte, you cannot preserve this file because the format has changed. However, when migrating from an older level foo.rte to a newer level foo.rte, the file can be preserved. In this case, you might want to create a foo.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/foo_user file, they are saved.

The root foo.bar.post_i script could be as follows:

#! /bin/ksh
grep -q foo.rte $INSTALLED_LIST
if [$? = 0]
then
  mv $MIGSAVE/etc/foo_user/ /etc/foo_user
fi

$INSTALLED_LIST is created and exported by installp. See "Installation for Control Files Specifically for Repackaged Products" for more information about the Fileset.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_leaf    preserve
./etc/cfg_pudding user_merge
./etc/cfg_newton  preserve

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 can not 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 a Fileset.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 gigabytes (>2GB) in size. If you ship a file that is greater than 2GB, 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. The following list describes the valid attributes of a file:

Attribute Description
class The logical group of the file. A value must be specified because it cannot be computed. The value is ClassName [ClassName].
type Specifies the file type. The type attribute can have the following values:
Type Meaning
FILE Ordinary file.
DIRECTORY Directory.
SYMLINK A symbolic link to a file.
FIFO First-in-first-out file.
BLK_DEV Block device special file.
CHAR_DEV Character device special file.
MPX_DEV Multiplexed device special file.
owner Specifies the file owner. The attribute value can be in the owner name or owner ID format.
group Specifies the file group. The attribute value can be in the group name or group ID format.
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.
tp Part of the Trusted Process.
svtx Text will be saved on swap for this file.
suid File has the set user ID bit set.
sgid File has the set group ID bit set.
target Valid only for type=SYMLINK. The attribute value is the path name of the file to which the link points.
program Specifies the software product to use to verify the file. This attribute is not usually used.
source Specifies the location of the original copy of the file.
size 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 Specifies the checksum values of the file. The attribute value is a string containing the checksum value and number of 1024-byte blocks in the file as generated by the sum command. If the files size is expected to change through normal operation, the value for this attribute must be VOLATILE.
link Specifies any hard links. If multiple hard links exist, each link is separated by a comma.
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.

Installation Control Files Specifically for Repackaged Products

The Fileset.installed_list File

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
/usr/share/lpp/ PackageName for the share 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.

For example, 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 creates the PackageWorkDirectory/storm.rain.installed_list file with the following contents:

storm.rain 1.1.0.0

As another example, the Baytown.com fileset contains a Baytown.com.namelist file with the following entries:

Pelly.obj
GooseCreek.rte
CedarBayou.stream 

While installing the Baytown.com 2.3.0.0 fileset, the installp command finds that Pelly.obj 1.2.3.0 and CedarBayou.stream 4.1.3.2 are installed. The installp command creates thePackageWorkDirectory/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

Fileset.namelist File 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, root, or share part of the liblpp.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, 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, 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. The LawPractice.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.

The Fileset.rm_inv File

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:

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.

For example, 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. The Russia.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

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:

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 /usr/sys/inst.images directory, which must contain the following:

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:

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 /usr/sys/mvCD containing the location of the product package images for A and B are vol%1/A.bff and vol%2.bff, respectively. The field in the table of contents file in /usr/sys/inst.images of volume 1 contains the location of A as A.bff. The field in the table of contents file in /usr/sys/inst.images of volume 2 contains the location of B as B.bff.

Note: Multiple volume CD-ROMs are not recognized on AIX systems prior to AIX 4.3. Each volume of the CD-ROM will be processed separately. The CD-ROMs should be produced whenever possible so that each volume may be processed separately, since there can be situations where a volume of the CD-ROM is unmountable and only the single volume may be accessible.

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:

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

The Table of Contents File

The following table describes the table of contents file. Note that some fields are different for the different types of media.

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

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

The installp Processing of Product Packages

The major actions that can be taken with the installp command are:

Apply When a fileset in a product installation package is applied, it is installed on the system and it overwrites any pre-existing 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 have been 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 the 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 medium.
  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 and /usr/share/lpp/Package_Name for share 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. 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 the Work_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.
  8. If this is an installation package rather than a fileset update package, call the /usr/lib/instl/rminstal script to do the following for each fileset being installed (unless otherwise specified, files checked for existence must have been restored from the liblpp.a control file library):
    1. If Fileset.pre_rm exists, execute 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 files and SWVPD information (except history) for Fileset.
      ELSE
      If Work_Directory/Fileset.installed_list exists,
      If Fileset.rm_inv exists or Fileset.namelist contains more than one fileset or the only fileset listed in Fileset.namelist is bos.obj,
      Remove files and SWVPD inventory information for files listed in the file Fileset.rm_inv.
      Remove files and SWVPD inventory information for files listed in the file Fileset.inventory.
      Remove other SWVPD information for any filesets listed in Fileset.namelist which no longer have any SWVPD inventory information.
      ELSE
      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.
    4. For each part of a product package (usr part only, share part only, or usr followed by root)
      1. Set INUTREE (U for usr, M for root, and S for share) and INUTEMPDIR (name of created temporary working directory) environment variables.
      2. If an installation package:
        If an instal control program exists in the package directory (not recommended)
        Execute ./instal.
        ELSE
        Execute the default script /usr/lib/instl/instal.
        ELSE /* update package */
        Set INUSAVEDIR environment variable.
        If an update control program exists in the package directory (not recommended)
        Execute ./update.
        ELSE
        Execute the default script /usr/lib/instl/update.
      3. If a status file has been successfully created by instal or update
        Use status file to determine success/failure of each fileset.
        ELSE
        Assume all requested filesets in package failed to apply.
      4. If apply operation was successful for a fileset
        Update the Software Vital Product Data (SWVPD).
        ELSE
        Run cleanup (the recommended default /usr/lib/instl/cleanup or the package-supplied lpp.cleanup from package directory) to clean up the failed filesets.
Processing of the Default install/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 referenced files are described in Description of Installation Control 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 update
      Execute Fileset.pre_u (pre_update) if it exists.
      ELSE
      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 update and files specified to be saved and lpp.acf (archive control file) exists,
      Save off the library archive members being updated.
    4. If processing is successful, append this fileset to the list to be installed in file $FILESETLIST.new.
  2. If update and file saving specified, call inusave to save current versions of the files.
  3. If processing root part,
    Call inucp to copy files from apply list to root part.
    ELSE
    Call inurest to restore files from apply list for usr or share parts.
  4. Do the following for each fileset listed in $FILESETLIST.new (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. Export environment variables INSTALLED_LIST and MIGSAVE if such a condition (called a migration).
    2. If processing an update,
      Invoke Fileset.post_u if it exists.
      ELSE
      Invoke Fileset.post_i if it exists.
      If Fileset.cfgfiles exists, then call /usr/lib/instl/migrate_cfg to handle processing of configuration files according to their specified handling method.
    3. Invoke sysck to add the information in the Fileset.inventory file to the software vital product database (SWVPD).
    4. 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 attribute tcb_enabled is set in the /usr/lib/objrepos/PdAt ODM database.
    5. Invoke errupdate to add error templates if Fileset.err exists.
    6. Invoke trcupdate to add trace report format templates if Fileset.trc exists.
    7. If update or if Work_Directory/Fileset.installed_list exists, invoke each Fileset.odmdel and Fileset.*.odmdel script to process ODM database deletion commands.
    8. Invoke odmadd on each existing Fileset.odmadd and Fileset.*.odmadd to add information to ODM databases.
    9. If update,
      Invoke Fileset.config_u (fileset configuration update) if it exists.
      ELSE
      Invoke Fileset.config (fileset configuration) if it exists.
    10. 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, and 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 (i.e., usr, root, or share)
    1. Set INUTREE (U for usr, M for root, and S for share) and INUTEMPDIR environment variables.
    2. If reject control file exists in current directory (INULIBDIR)
      Invoke ./lpp.reject
      ELSE
      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. They are described in detail in Description of Installation Control Files.

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 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 step (i) below, since 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
      ELSE
      Invoke Fileset.unconfig if it exists.
    3. Run any Fileset.*.unodmadd and/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. Invoke trcupdate 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 update,
      Invoke Fileset.unpost_u if it exists
      ELSE
      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 update,
      Invoke Fileset.unpre_u if it exists
      ELSE
      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 (i.e., usr, root, or share)
    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 deinstal control file exists in current directory
      Invoke ./lpp.deinstal
      ELSE
      Invoke the default script /usr/lib/instl/deinstal.
  3. Remove files belonging to the fileset from the file system.
  4. Remove fileset entries from the SWVPD except for history data.

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 preinstallation scripts for all updates and the base level installation.

  3. If Fileset.unconfig_d does not exist,
    1. For each update for that fileset
      Run any Fileset.unconfig_u to undo any update configuration processing.
      Run any Fileset.*.unodmadd and/or Fileset.unodmadd to delete Object DataManager (ODM) entries added during the update.
      Run any Fileset.*.rodmadd and/or 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,
      Run any Fileset.*.unodmadd and/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

The following list describes the valid StatusCode values:

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


[ Previous | Next | Contents | Glossary | Home | Search ]