This article provides information about preparing applications to be installed using the installp command.
This section describes the format and contents of the software product installation package that must be supplied by the product developer. It gives a description of the required and optional files that are part of a software installation or update package.
A software product installation package is a 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 file sets. Each file set in a package must belong to the same product.
A file set update or update package is a package containing modifications to an existing file set.
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:
Package control information must:
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.
In order to support diskless or dataless client workstations, machine-specific portions of the package (the root part) must be separated from the machine-shareable portions of the package (the usr part). The usr part of the package contains files that reside in the /usr file system.
Installation of the root part of the package must not modify any files in the /usr file system. The /usr file system is not writable during installation of the root part of a diskless or dataless client system.
Information about a software product and its installable options is maintained in the Software Vital Product Data (SWVPD) database. The SWVPD consists of a set of commands and the Object Data Manager (ODM) object classes for the maintenance of software product information. The SWVPD commands are provided for the user to query (lslpp) and verify (lppchk) installed software products. The ODM object classes define the scope and format of the software product information that is maintained.
The installp command uses the Object Data Manager to maintain the following information in the SWVPD database:
In order to support installation in the client/server environment, the installation packaging is divided in the following parts:
Following is a brief description of file systems and directories. You can use this as a guide for splitting a product package into root, usr, and share parts.
Some root-part directories and their contents:
| /dev | Local machine device files |
| /etc | Machine configuration files such as hosts and passwd |
| /sbin | System utilities needed to boot the system |
| /var | System-specific data files and log files |
Some usr-part directories and their contents include:
| /usr/bin | Commands and scripts (ordinary executables) |
| /usr/sbin | System administration commands |
| /usr/include | Include files |
| /usr/lib | Libraries, non-user commands, and architecture-dependent data |
Some share-part directories and their contents include:
| /usr/share/dict | Dictionary files |
| /usr/share/man | Manual pages |
Use the following conventions when naming a software package and its file sets:
PackageName.SubProduct.Optionwhere:
The following list provides some file set extension naming conventions:
The configuration manager command (cfgmgr) automatically installs software support for detectable devices that are available on the installation media and packaged with the following naming convention:
devices.BusTypeID.CardID
where:
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 file sets associated with this token-ring device is named devices.mca.8fc8. A microcode file set within this package is named devices.mca.8fc8.ucode.
A user installing a package can request the message catalogs be installed automatically. When this request is made, the system automatically installs message file sets for the primary language if the message file sets 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 file sets for the same language, each message catalog file set applying to a different SubProduct. You can choose to have one message file set for an entire product.
For example, the Super.Widget product has a plastic and a metal set of file set options. All Super.Widget English U.S. message catalogs can be packaged in a single file set named Super.Widget.msg.en_US. If separate message catalog file sets are needed for the plastic and metal options, the English U.S. message catalog file sets would be named Super.Widget.msg.en_US.plastic and Super.Widget.msg.en_US.metal.
Files delivered with the software package cannot have names containing commas or colons. Commas and colons are used as delimiters in the control files used during the software installation process. File names can contain non-ASCII characters.
The file set level is referred to as the level or alternatively as the v.r.m.f or VRMF and has the form:
Version.Release.ModificationLevel.FixLevelwhere:
A base file set installation level is the full initial installation level of a file set. This level contains all files in the file set, as opposed to a file set update, which may contain a subset of files from the full file set.
All file sets in a software package should have the same file set level, though it is not required for AIX 4.1-formatted packages.
For all new levels of a file set, the file set level must increase. The installp command uses the file set level to check for a later level of the product on subsequent installations.
File set level precedence reads from left to right (for example, 5.2.0.0 is a newer level than 4.3.0.0).
This section describes the files contained in an installation or update package. File path names are given for installation package types. For update packages, wherever PackageName is part of the path name, it is replaced by PackageName/FilesetName/FilesetLevel.
The usr part of an installation or update package contains the following installation control files:
If the installation or update package contains a root part, the root part contains the following files:
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:
The farm.apps package contains the farm.apps.hog 4.1.0.0 file set. The farm.apps.hog 4.1.0.0 file set 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
File set update farm.apps.hog 4.1.0.3 delivers updates to the following files:
/usr/sbin/sellhog /etc/hog
The file set 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
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 file set in the package. Refer to the figure for an example lpp_name file for a file set 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.
| 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:
|
| 2. Platform | Character | White space | Indicates the platform for which this package was built. The values
are:
|
| 3. Package Type | Character | White space | Indicates whether this is an installation or update package and what
type. The values are:
|
| 4. Package Name | Character | White space | The name of the software package (PackageName). |
|
|
{ | New line | Indicates the beginning of the repeatable sections of file set-specific data. |
| 5.File set name | Character | White space | The complete name of the file set. This field begins the heading information for the file set or file set update. |
| 6. Level | Shown in Description column | White space | The level of the file set to be installed. The format is: Version.Release.ModificationLevel.FixLevel |
| 7. Diskette Volume | Integer | White space | Indicates the diskette volume number where the file set is located, if shipped on diskette. |
| 8. Bosboot | Character | White space | Indicates whether a bosboot is needed following the installation. The
values are:
|
| 9. Content | Character | White space | Indicates the parts included in the file set or file set update. The
values are:
|
| 10. Language | Character | White space | Not used. |
| 11. Description | Character | # or new line | File set description. |
| 12. Comments | Character | New line | (Optional) Additional comments. |
|
|
[ | New line | Indicates the beginning of the body of the file set information. |
| 13. Requisite information | Described following table | New line | (Optional) Installation dependencies the file set has on other file sets and file set updates. See the section following this table for detailed description. |
|
|
% | New line | Indicates the separation between requisite and size information. |
| 14. Size and License Agreement information | Described later in this chapter | New line | Size requirements by directory and license agreement information. See Size and License Agreement Information Section later in this article for detailed description. |
|
|
% | New line | Indicates the separation between size and supersede information. |
|
|
% | New line | Indicates the separation between supersede and licensing information. |
| 15. Fix information | Described later in article | New line | Information regarding the fixes contained in the file set update. See Fix Information Section later in this article for detailed description. |
|
|
] | New line | Indicates the end of the body of the file set information. |
|
|
} | New line | Indicates the end of the repeatable sections of file set-specific information. |
1 2 3 4 | | | | 6 7 89 10 11 12 4 R S farm.apps { | | || | | | 5 --> farm.apps.hog 04.01.0000.0003 1 N U en_US Hog Utilities # ... [ 13--> *ifreq bos.farming.rte (4.2.0.0) 4.2.0.15 % 14--> /usr/sbin 48 14--> /usr/lpp/farm.apps/farm.apps.hog/4.1.0.3 280 14--> /usr/lpp/farm.apps/farm.apps.hog/inst_root/4.1.0.3.96 14--> /usr/lpp/SAVESPACE 48 14--> /lpp/SAVESPACE 32 14--> /usr/lpp/bos.hos/farm.apps.hog/inst_root/4.1.0.3/ etc 32 % % % 15--> IX51366 Hogs producing eggs. 15--> IX81360 Piglets have too many ears. ] } |
The requisite information section contains information about installation dependencies on other file sets or file set updates. Each requisite listed in the requisite section must be satisfied according to the requisite rules in order to apply the file set or file set update.
Before any installing or updating occurs, the installp command compares the current state of the file sets 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 file sets to be installed. The file sets are ordered for installation according to any prerequisites. Immediately before a file set is installed, the installp command again checks requisites for that file set. 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 file set level that satisfies the requirements. Except when explicitly blocked by mechanisms described in Supersede Information Section, newer levels of a file set satisfy requisites on an earlier level. For example, a requisite on the plum.tree 2.2.0.0 file set is satisfied by the plum.tree 3.1.0.0 file set.
A prerequisite indicates that the specified file set must be installed at the specified file set level or at a higher level for the current file set to install successfully. If a prerequisite file set is scheduled to be installed, the installp command orders the list of file sets to install to make sure the prerequisite is met.
Syntax
*prereq Fileset RequiredFilesetLevel
Alternate Syntax
Fileset RequiredFilesetLevel
A file set update contains an implicit prerequisite to its base-level file set. 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.
A corequisite indicates that the specified file set must be installed for the current file set to function successfully. At the end of the installation process, the installp command issues warning messages for any unmet corequisites. A corequisite is most commonly used for a file set within the same package. A prerequisite on a file set within the same package is not guaranteed.
Syntax
*coreq Fileset RequiredFilesetLevel
An if requisite indicates that the specified file set is required to be at RequiredFilesetLevel only if the file set is installed at InstalledFilesetLevel. This is most commonly used to coordinate dependencies between file set updates. The following example shows an if requisite:
*ifreq A.obj (1.1.0.0) 1.1.2.3
Syntax
*ifreq Fileset [(InstalledFilesetLevel)] RequiredFilesetLevel
If the A.obj file set is not already installed, this example does not cause it to be installed. If the A.obj file set 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 file set level. |
| 1.1.3.0 | This level supersedes the RequiredFilesetLevel. |
If the A.obj file set 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.
An installed requisite indicates that the specified file set should be installed automatically only if its corresponding file set is already installed or is on the list of file sets to install. An installed requisite also is installed if the user explicitly requests that it be installed. A file set update can not have an installed requisite. Because a file set containing the message files for a particular package should not be installed automatically without some other part of the package being installed, a message file set should contain an installed requisite for another file set in its package.
Syntax
*instreq Fileset RequiredFilesetLevel
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.
Syntax
>Number { RequisiteExpressionList }
*coreq layout.text 1.1.0.0 *coreq index.generate 2.3.0.0
The index.generate 3.1.0.0 file set satisfies the index.generate requisite, because 3.1.0.0 is a newer level than the required 2.3.0.0 level.
*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 file set must be installed at level 1.2.0.0 or higher before the new.fileset.rte file set can be installed. If database and new.fileset.rte are installed in the same installation session, the installation program will install the database file set before the new.fileset.rte file set.
The spreadsheet file set must be installed at level 1.3.1.0 or higher for the new.fileset.rte file set to function properly. The spreadsheet file set does not need to be installed before the new.fileset.rte file set is installed, provided both are installed in the same installation session. If an adequate level of the spreadsheet file set 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 file set is installed (or being installed with new.fileset.rte) at level 4.1.0.0, then the wordprocessorA file set update must be installed at level 4.1.1.1 or higher.
If the wordprocessorB file set is installed (or being installed with new.fileset.rte) at level 4.1.1.0, then the wordprocessorB file set update must be installed at level 4.1.1.1 or higher.
Super.Widget 2.1.0.0
The Super.msg.fr_FR.Widget file set can not be installed automatically when the Super.Widget file set is not installed. The Super.msg.fr_FR.Widget file set can be installed explicitly when the Super.Widget file set is not installed.
>0 {
*prereq spreadsheet_1 1.2.0.0
*prereq spreadsheet_2 1.3.0.0
}The size and license agreement information section contains information about the disk space and license agreement requirements for the file set.
This information is used by the installation process to ensure that enough disk space is available for the installation or update to succeed. Size information has the form:Directory PermanentSpace [TemporarySpace]
Additionally, the product developer can specify PAGESPACE or INSTWORK in the full-path name field to indicate disk space requirements for paging space and work space needed in the package directory during the installation process.
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.
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:
Products which require users to agree to software license terms before the product can be installed must provide special entries in the size and license agreement information section. There are two forms of license agreement information: license agreement requirement entries indicating that a file set is governed by a license agreement and license agreement file entries indicating that a package contains a license agreement file.
License agreement files are indicated by a size section entry which begins with LAF%locale_spec/, where LAF stands for License Agreement File, and locale_spec specifies the locale for which the file is encoded. If the locale_spec is not specified, then the agreement file will be assumed to be nontranslated and encoded as ASCII. If the license agreement file is translated, the locale name must be part of the path so that the requirement entry may be associated with the file. The remainder of the string is a path designation which uniquely identifies a particular license file which is included in the package. Each time that the license text changes, the fullpath of the license must also change. Licenses are not modifiable once they have been delivered, since the terms associated with preexisting products cannot be modified. Only one file set in the package is required to carry the license agreement file information, though it may appear in the size and license information section of more than one. It is desirable to only carry the license agreement file information for one file set since the information would otherwise be redundant.
The second field in the license agreememt file indicator is the size in 512-byte blocks of the license agreement file, rounded up to multiples of 8 to reflect a 4096-byte block size for a standard JFS filesystem.
License agreement requirements are indicated by a size and license information section entry which begins with LAR/, where LAR stands for License Agreement Requirement. The remainder of the string is the filepath which uniquely identifies the particular license. The license agreement requirement entry will have an additional second field of 0 to indicate that no additional size requirements exist. The actual size information will be derived from the license agreement file size indication.
Each available translated license agreement file must be listed in the size and license information section of one of the file sets in the package. Translated license agreement files must include a locale designation as part of the full pathname.
License agreement requirement entries indicate the base pattern of the license files associated with license agreement file entries. A %L pattern will designate the locale substitution string which will be applied to identify which particular license agreement file to use.
In the following example, product IcedTea contains a license information file which has been translated into English, Japanese, and German. The file set IcedTea.rte both requires and provides a license agreement. The basic form of the license file provided for IcedTea is /usr/opt/IcedTea/license/LANG/license.txt. The size and license information section for IcedTea.rte would include the following entries:
LAF%en_US/usr/opt/IcedTea/license/en_US/license.txt 8 LAF%ja_JP/usr/opt/IcedTea/license/ja_JP/license.txt 8 LAF%de_DE/usr/opt/IcedTea/license/de_DE/license.txt 8 LAR/usr/opt/IcedTea/license/%L/license.txt 0
The following files would be included in the package containing IcedTea.rte:
./usr/opt/IcedTea/license/en_US/license.txt ./usr/opt/IcedTea/license/ja_JP/license.txt ./usr/opt/IcedTea/license/de_DE/license.txt
The license agreement files may be carried in separate packages from the packages containing the license agreement requirements. This enables shipping translations separately and also allows for a product consisting of multiple packages to only ship the license agreement files in a single package. It is preferable to limit the number of file sets in a product as much as possible. If there is a common file set which is a prerequisite for the other file sets in a product, the license agreement requirement should just be associated with that one file set.
The supersede information section indicates the levels of a file set or file set update for which this file set or file set update may (or may not) be used as a replacement. Supersede information is optional and is only applicable to AIX 4.1-formatted file set base installation packages and AIX 3.2-formatted file set update packages.
A newer file set supersedes any older version of that file set unless the supersedes section of the lpp_name file identifies the latest level of that file set it supersedes. In the rare cases where a file set does not supersede all earlier levels of that file set, the installp command does not use the file set to satisfy requisites on levels older than the level of the file set listed in the supersedes section.
A file set update supersedes an older update for that file set only if it contains all of the files, configuration processing, and requisite information contained in the older file set update. The installp command determines that a file set update supersedes another update for that file set in the following conditions:
For example, the file set update farm.apps.hog 4.1.0.1 delivers an update of /usr/sbin/sellhog. File set update farm.apps.hog 4.1.0.3 delivers updates to the /usr/sbin/sellhog file and the /etc/hog file. File set 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.
An AIX 4.1-formatted file set installation package can contain the following supersede entries:
The lpp_name file can contain at most one barrier and one compatibility entry for a file set.
A barrier entry consists of the file set name and the file set level when the incompatibility was introduced. A barrier entry is necessary for a file set only in the rare case that a level of the file set has introduced an incompatibility such that functionality required by dependent file sets has been modified or removed to such an extent that requisites on previous levels of the file set are not met. A barrier entry must exist in all subsequent versions of the file set indicating the latest level of the file set that satisfies requisites by dependent file sets.
For example, if a major incompatibility was introduced in file set Bad.Idea 6.5.6.0, the supersede information section for each Bad.Idea file set installation package from file set 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 file set name (different from the file set in the package) and a file set level. The file set level identifies the level at which requisites to the specified file set (and earlier levels of that file set) are met by the file set in the installation package. The compatibility is useful when the specified file set is obsolete or has been renamed, and the function from the specified file set is contained in the current file set. The file set level in the compatibility entry should be higher than any level expected to exist for the specified file set.
For example, the Year.Full 19.91.0.0 file set is no longer delivered as a unit and is instead broken into several smaller, individual file sets. Only one of the smaller resulting file sets, 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 file set to satisfy the requisites of file sets dependent on Year.Full at levels 19.94.0.0 and earlier.
The installp command provides the following special features for installing file sets and file set updates which supersede other file sets or file set 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 file set. If the installation media contains the farm.apps.hog 4.1.0.4 file set only, the installp command will install the farm.apps.hog 4.1.0.4 file set 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 this case, if a user wishes to apply a certain update and its superseding update from the installation media, the user must do separate installp operations for each update level. Note that this kind of operation is meaningless if the two updates are applied and committed (-ac). Committing the second update removes the first update from the system.
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 operating system manufacturer.
A maintenance level is a fix that is a major update level. 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 file is an archive file that contains the files required to control the package installation. You can create a liblpp.a file for your package using the ar command. 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 file set 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 file set or file set update. Unless stated, a file pertains to both full installation packages and file set update packages.
| Fileset.al | Apply list. This file lists all files to be restored for this file set. 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 file set or file set update. |
| Fileset.cfginfo | Special instructions file. This file lists one keyword per line, each keyword indicating special characteristics of the file set or file set 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 file set 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 file set. 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 file set or file set update. |
| Fileset.inventory | The inventory file. This file contains required software vital product data for the files in the file set or file set 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 file sets and current file set (if applicable) that once contained files now existing in the file set 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 file set is not a direct replacement for an obsolete file set. This stanza-format file contains names of files that need to be removed from obsolete file sets. |
| Fileset.size | |
| 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). |
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 file set 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.
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.
To ensure compatibility with the installp command, the instal or update executable provided with a software package must:
The Fileset.cfgfiles file lists configuration files that need to be saved in order to migrate to a new version of the file set 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:
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 file set, 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 file set (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 file set (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 file set 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 (Installation 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 file set must recover user configuration data from three configuration files located in the root part of the file set. 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
| Fileset.fixdata | A stanza-format file that describes the fixes contained in the file set update (or in a file set 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 file set 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 file sets and file set levels. FilesetLevel is the initial level in which the file set 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 file sets.
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.
| Fileset.inventory | File that contains specific information about each file that is to be installed or updated for the file set |
| 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 file set that installs or update files. If the package has a root part that does not contain files to be installed (it does configuration only), the root part does not require the Fileset.inventory file.
Note: The Fileset.inventory file does not support files which are greater than 2 GB in size. If you ship a file that is greater than 2 GB, include it in your fileset.al file, but not in your Fileset.inventory file. sysck has not been updated to handle files larger than 2GB, and the /usr file system on most machines will not be created with capability for files greater than 2GB (by default).
The inventory file consists of ASCII text in stanza format. The name of a stanza is the full path name of the file to be installed. The stanza name ends with a colon (:) and is followed by a new-line character. The file attributes follow the stanza name and have the format Attribute=Value. Each attribute is described on a separate line. The following list describes the valid attributes of a file:
| 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: |
| 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. |
| 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. |
| Fileset.installed_list | File created by the installp command when installing the file set from a package if it is found that the file set (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 file sets listed in the file Fileset.namelist (if it exists) are already installed on the system. If so, the file set 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 file set that was installed. Each entry contains the file set name and the file set level.
For example, while the storm.rain 1.2.0.0 file set 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 file set 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 file set, 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
| Fileset.namelist | This file is necessary when the file set name has changed or the file set contains files previously packaged in obsolete file sets. It contains names of all file sets that previously contained files currently included in the file set to be installed. Each file set 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 file set or any file set listed in the Fileset.namelist file is already installed on the system. The installp command writes to the Fileset.installed_list file the file set names and file set 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 file set replaces an earlier file set 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 file set is divided into a client file set and a server file set. The LawPractice.client and LawPractice.server file sets replace the earlier lawoffice.mgr file set. The LawPractice.server file set also contains a few files from the obsolete BusinessOffice.mgr file set. 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 file set is not a direct replacement for the file set 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 file set is a direct replacement for another file set. If the Fileset.namelist file contains only one entry and there is no Fileset.rm_inv file, the installation process assumes the new file set is a direct replacement for the old file set. When the new (replacement) file set is installed, the installation process removes from the system all files from the old (replaced) file set, even files not included in the new file set.
In the previous examples, the small.business file set is a direct replacement for the family.business file set, so a small.business.rm_inv file should not exist. The LawPractice.client file set is not a direct replacement for the lawoffice.mgr file set, so a LawPractice.client.rm_inv file must exist, even if it is empty.
Example 3:
File sets bagel.shop.rte and bread.shop.rte have been shipping seperately for years. Now, bagel.shop.rte is going to ship as a part of bread.shop.rte. For this to happen, the bread.shop.rte.namelist file would look like:
bread.shop.rte bagel.shop.rte
You must also ship an empty bread.shop.rte.rm_inv file to indicate that all files from the bagel.shop.rte file set should be removed from the system.
| 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 file set is packaged differently from a previous level of the file set and the installation process should not remove previously installed files based on the file set's entries in the inventory database.
A simple name change for a file set is not sufficient to require a Fileset.rm_inv file. The Fileset.rm_inv file is necessary when a new file set is either a subset of a previous file set or a mixture of parts of previous file sets. If a Fileset.namelist file exists and contains entries for more than one file set, 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:
For example, the U.S.S.R 19.91.0.0 file set 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 file set into two file sets: Ukraine.lib 19.94.0.0 and Russia.lib 19.94.0.0. The Ukraine.lib file set contains the kiev and odessa files. The Russia.lib file set contains the moscow file. The leningrad file no longer exists and is replaced by the st.petersburg file in the Russia.lib file set.
The Ukraine.lib.rm_inv file must exist because the Ukraine.lib file set is not a direct replacement for the U.S.S.R file set. The Ukraine.lib.rm_inv file should be empty because no files need to be removed when the Ukraine.lib file set is installed to clean up the migrating U.S.S.R file set.
The Russia.lib.rm_inv file must exist because the Russia.lib file set is not a direct replacement for the U.S.S.R file set. If the Russia.lib.rm_inv file is used to remove the leningrad file when the Russia.lib file set is installed, the Russia.lib.rm_inv file would contain the following stanza:
/usr/lib/leningrad:
symlinks = /usr/lib/petrograd
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.
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.
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:
A CD-ROM that is to contain multiple product package images must be compliant with the Rock Ridge Group Protocol. Product packages should be stored in the installation directory, which must contain the following:
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:
AIX 5.2 Example:
File set A is in file A.bff on volume 1. File set B is in file B.bff on volume 2. The field in the table of contents file in /installp/mvCD containing the location of the product package images for A and B are vol%1/A.bff and vol%2.bff, respectively. The field in the table of contents file in /installp/ppc of volume 1 contains the location of A as A.bff. The field in the table of contents file in /installp/ppc of volume 2 contains the location of B as B.bff.
The CD-ROM directory stucture for AIX 5.1 and later allows for specification of other installers, as well as multiple platforms.
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 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. |
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.
The location has the format of vvv:bbbbb:sssssss where each letter represents a digit and has the following meaning:
For tape
For diskette
The major actions that can be taken with the installp command are:
Executables provided within a product package can tailor processing for the apply, reject, and remove operations.
Reinstalling a file set does not perform the same actions that removing and installing the same file set 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 file set, the config script adds a line to root's crontab file. Reinstalling the ras.berry.rte file set 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.
This section describes the steps taken by the installp command when a file set or file set update is applied.
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 file sets 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 Further Description of Installation Control Files.
The flow within the default instal and update script is as follows:
Save off the library archive members being updated.
This section describes the steps taken by the installp command when a file set update is rejected or when a file set or file set 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 file sets or file set updates, the root part is processed before the usr part.
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 file sets (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 Further Description of Installation Control Files.
The flow within the default cleanup and reject script is as follows:
If rejecting an update, invoke Fileset.unconfig_u if it exists. Otherwise, invoke Fileset.unconfig if it exists.
If this is an update, invoke Fileset.unpost_u if it exists. Otherwise, invoke Fileset.unpost_i if it exists.
This section describes the steps taken by the installp command when a file set is removed. For usr/root file sets or file set updates, the root part is processed before the usr part.
The deinstal executable is invoked from installp with the first parameter being the full path name to the file containing the list of file sets to be removed, referred to below as $FILESETLIST.
The flow within the default deinstal script is as follows:
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.
| $INUTEMPDIR/status | File that contains a one-line entry for each file set 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 file sets of bos.net package were successful and the installation for the nfs.client file set was not successful.
s bos.net.tcp.client s bos.net.tcp.server f bos.net.nfs.client
For examples of their use, refer to the default installation script, /usr/lib/instl/instal.