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.
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 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 |
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.
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.
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.
The following list provides some fileset extension naming conventions:
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.
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:
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.
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 fileset level is referred to as the level or alternatively as the v.r.m.f or VRMF and has the form:
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).
The following conventions and rules have been put in place in order to simplify the software maintenance for product developers and customers:
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.
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.
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.
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.
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.
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.
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.
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
*coreq layout.text 1.1.0.0 *coreq index.generate 2.3.0.0The 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.
*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.1The 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.
Super.Widget 2.1.0.0The 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.
>0 { *prereq spreadsheet_1 1.2.0.0 *prereq spreadsheet_2 1.3.0.0 }
*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.
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:
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:
The following save directories are used for obsolete 3.2-formatted fileset updates only:
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.
An AIX Version 4.1-formatted fileset installation package can contain the following supersede entries:
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.
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.
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.
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 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.
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). |
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.
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 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:
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
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."
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: |
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. |
Note: The sysck command creates hard links and symbolic links during installation if those links do not exist. The root part symbolic links should be packaged in the root part Fileset.inventory file.
Fileset.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
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.
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:
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
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 /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.
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.
Note: Items 4 and 5 described in the preceding table are repeated for each product package image contained on the media.
A date and time stamp format is an ASCII string that has the following format:
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:
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 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.
This section describes the steps taken by the installp command when a fileset or fileset update is applied.
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. |
Use status file to determine success/failure of each fileset. |
ELSE |
Assume all requested filesets in package failed to apply. |
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. |
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:
If update |
Execute Fileset.pre_u (pre_update) if it exists. |
ELSE |
Execute Fileset.pre_i (pre_installation) if it exists. |
Save off the library archive members being updated.
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. |
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. |
Invoke Fileset.config_u (fileset configuration update) if it exists. |
ELSE |
Invoke Fileset.config (fileset configuration) if it exists. |
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
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.
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:
Invoke Fileset.unconfig_u if it exists |
ELSE |
Invoke Fileset.unconfig if it exists. |
Invoke Fileset.unpost_u if it exists |
ELSE |
Invoke Fileset.unpost_i if it exists. |
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.
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:
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.
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.
$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:
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
For examples of their use, refer to the default installation script, /usr/lib/instl/instal.