epkg Command

Purpose

Creates interim fix packages that can be installed by the interim fix manager, emgr.

Syntax

epkg [ -w WorkDirectory ] [ -a APARrefFile ] [ -p PrerequisiteFile ] [ -d DescriptionFile ] [ -e interimfixControlFile ] [ -g PrerequisiteFile ] [ -l LockFile ] [ -S SupersedeFile ] [ -u {y|n} ] ] [ -r {y|n|o} ] [ -s ] [ -T {y|n} ] [ -X ] [ -v ] interimfixLabel

Description

The epkg tool can be run in two different modes: interactive and template-based. The interactive mode prompts you with several questions and constructs the interim fix package based on the answers. The template-based mode uses an interim fix control file that is provided with the answers to questions that are asked in interactive mode. The interim fix package is installed by the interim fix manager, which is started with the emgr command.

Interactive mode

The epkg command runs in interactive mode by default. The only required parameter is the interim fix label. If you interrupt an epkg session, the interim fix control file will be saved. If you start a new session with the same interim fix label, you will be asked whether you want to keep working with the previous interim fix control file. To provide this information before you start the interactive epkg session, run epkg with the -u flag.

The epkg command maintains a record of the question order and allows you to navigate between questions by using subcommands. Also, the epkg command remembers the previous answer you provided and sets that answer as the default answer. The epkg subcommands are described in the Subcommands section.

After you answer all the questions, the epkg command verifies the interim fix control file and creates a compressed tar package that can be installed with the emgr command.

Using the control file template

You can create interim fix packages noninteractively by using an interim fix control file as a template. The following is an example of a completed interim fix control file:

# interim fix control file complete example 
ABSTRACT=This is a test of epkg. 
PRE_INSTALL=/tmp/pre_install 
POST_INSTALL=. 
PRE_REMOVE=/tmp/pre_remove
POST_REMOVE=.
REBOOT=yes 
PREREQ=. 
DESCRIPTION=/tmp/description 
EFIX_FILES=2
APARREF=/tmp/aparref
LKU_CAPABLE=no

EFIX_FILE:
        EFIX_FILE_NUM=1
        SHIP_FILE=/home/test/ls 
        TARGET_FILE=/usr/bin/ls
        TYPE= 1 
        INSTALLER= 1  
        ACL= DEFAULT
        AR_MEM=.

EFIX_FILE:
        EFIX_FILE_NUM=2
        SHIP_FILE=/home/test/mystrcat.o 
        TARGET_FILE=/usr/ccs/lib/libc.a
        TYPE= 2
        INSTALLER= 1  
        ACL= root:system:555
        AR_MEM=strcat.o

The interim fix control file values, are as follows:

ABSTRACT

Briefly describes the interim fix package. The abstract is limited to 38 bytes.

PRE_INSTALL

Specifies the location of a script that is run after the installation preview and before any interim fix files are installed. Failure in the PRE_INSTALL script will cause the interim fix package installation to be aborted. This component is optional.

POST_INSTALL

Specifies the location of a script that is run after all interim fix files have been successfully installed. This component is optional.

PRE_REMOVE

Specifies the location of a script that is run after the removal preview and before any interim fix files are removed during a remove operation. This component is optional.

POST_REMOVE

Specifies the location of a script that is run after interim fix files are removed during a remove operation. This component is optional.

REBOOT

Specifies whether a reboot is required for this interim fix. Allowable values are yes or no. If this value is set to yes, the emgr command will make changes as necessary to the boot image and issue a message instructing the user to reboot after installation.

PREREQ

Specifies the location of a file that contains installp prerequisites. This component is optional.

APARREF

Specifies the location of a file that contains the APAR reference numbers and abstracts associated with this interim fix. Each line of the file contains an APAR reference number, an APAR number, and an APAR abstract. The format of the file is as follows:

APAR reference|:|APAR number|:|APAR abstract

Not all fields are required to make a valid APARREF file. If a particular field is unknown or not required, simply specify NONE or leave the field blank. Some examples of valid APARREF files follow:

Example 1

123456|:|IV12345|:|This is the APAR abstract
789012|:|IV67890|:|This is another APAR abstract

Example 2

123456|:|NONE|:|NONE
789012|:|NONE
345678

Example 3

NONE|:|IV12345|:|This is the APAR abstract

Example 4

NONE

If you provide an APAR reference file with the APAR reference numbers, the automatic removal feature by the installp command is enabled for the interim fix. The automatic removal by the installp command means the capability to automatically remove an interim fix if the fix is present in the Technology Level, Service Pack, or PTF that the installp command is applying. If NONE is listed in the APAR reference field, the automatic removal feature is not enabled for the interim fix.

DESCRIPTION

Specifies the location of a file that contains a detailed description of the interim fix package that is being installed.

EFIX_FILES

Specifies the total number of files in the interim fix.

EFIX_FILE_NUM

Specifies the number of the file in the interim fix. Each file in the interim fix must have a unique number, from 1 to 400. The epkg command can support a maximum of 400 files per interim fix.

SHIP_FILE

Specifies the location of a file that epkg will archive into the interim fix package. You can specify either an absolute path or a relative path to this file.

TARGET_FILE

Specifies the location where the SHIP_FILE will be installed. This location is on the system where the interim fix package will be installed. You must specify an absolute path to this file. If this file is part of a registered package, such as an RPM Package Manager (RPM) or installp package, you must specify the tracked location.

TYPE

Specifies the type of file that is being installed. The valid choices are as follows:

1: File (standard or executable)
2: Library or archive member

INSTALLER

Specifies the type of installer, if any, that will track the interim fix package. The valid choices are as follows:

1: Currently tracked by installp
2: Currently tracked by RPM
3: Currently tracked by ISMP
4: Currently tracked by another installer
5: This is a new file that will be tracked by installp
6: New file that will be tracked by RPM
7: New file that will be tracked by ISMP
8: New file that will be tracked by another installer
9: Not tracked by any installer

ACL

Specifies the access attributes (mode and ownership) for the file. If this attribute is set to DEFAULT, the emgr command maintains the current permissions of the file to be replaced. However, if the target file is a new file or if the user wants to specify permissions with the -v flag, the ACL attribute can be entered with the syntax Owner:Group:OctalModes, similar to the following:

ACL= root:system:555

AR_MEM

Specifies the name of the archive member. This option is only valid if TYPE=2. In this case, SHIP_FILE is the local location of the archive member that is being shipped, TARGET_FILE is the target archive, and ACL applies to the archive member. For example, the following value settings would make the local file myshr.o the member shr.o in the target archive /usr/ccs/lib/libc.a:

TYPE=2
SHIP_FILE=/home/myshr.o
TARGET_FILE=/usr/ccs/lib/libc.a
AR_MEM=shr.o

BUILD_BOOT_IMAGE

Specifies whether the boot image needs to be rebuilt. Allowable values are yes or no. A reboot is required if this field is set to yes. If this field is set to yes and the REBOOT field is set to no, epkg returns an error.

E2E_PREREQ

Specifies the location of the interim fix prerequisite file in the interim fix control file.

PKGLOCKS

Specifies the local file location of the package lock file in the interim fix control file.

SUPERSEDE

Specifies the local file location of the superseded file in the interim fix control file.

FIXTESTED

Specifies whether this interim fix has been tested. Allowable values are yes or no.

LKU_CAPABLE

Specifies whether this interim fix is compatible with the Live Update operation. This attribute can have a value of yes or no. Ideally, all interim fixes must be marked as Live Update capable. This compatibility is needed to install interim fixes as a group. If an interim fix is not suitable for a Live Update operation, the LKU_CAPABLE attribute is set to the value of no, however most of the interim fixes have this attribute set to the value of yes.

Support for Superseding

The packager can specify a file containing the interim fix label names that are to be superseded when an epkg is installed. This will cause the emgr command to remove any interim fix labels that are specified in this file (if they are installed) before installing the interim fix package. Failure to remove an installed superseded interim fix will abort the installation of the interim fix package. The maximum supported number of superseded labels is 32. The packager can specify the supersede file with the epkg command in the following ways:

Specify the file location with the -S supersede_file flag. For example:
```
epkg -S /tmp/superseded.epkg myefix
```
The epkg command will prompt for the superseded file if the extended options flag (-v) is used in interactive mode. For example:
```
Enter the location for the supersede file or "." to skip.
-> /tmp/superseded.epkg
```
Set the SUPERSEDE attribute to the local file location of the superseded file in the interim fix control file. For example:
```
SUPERSEDE=/tmp/superseded.epkg
```

The format of the superseded file is one interim fix label to be superseded per line. Comments beginning with a # sign and leading white space are ignored. For example:

# Requisites for efix myefix3
myefix1
myefix2

Support for prereqs and xreqs

The packager can specify a file containing the interim fix label names of interim fixes that are requisites to the interim fix package being installed. This will cause the emgr command to check if the interim fix label is installed (PREREQ). If the requisite is not installed, the emgr command will abort installation of the interim fix package. The user can also specify an XREQ interim fix label. This will cause the emgr command not to install the interim fix if the named xreq interim fix is installed.

The packager can specify the interim fix prerequisite file with the epkg command in the following ways:

Specify the file location with the -g efix_prereq_file flag. For example:
```
epkg -g /tmp/efixprereq.epkg myefix
```
The epkg command will prompt for the interim fix prereq file if the extended options flag (-v) is used in interactive mode. For example:
```
Enter the location for the efix prerequisite file or "." to skip.
-> /tmp/efixprereq.epkg
```
Set the E2E_PREREQ attribute to the local file location of the interim fix prerequisite file in the interim fix control file. For example:
```
E2E_PREREQ=/tmp/efixprereq.epkg
```

The format of the interim fix prerequisite file entries is as follows:

EfixLabel  RequisiteType: PREREQ/XREQ

For example:

oldefix1 PREREQ  # Make sure oldefix1 is already installed

oldefix4 XREQ    # Make sure oldefix4 is NOT installed

The maximum number of supported interim fix prerequisites is 32.

Support for enabling automatic interim fix removal by installp

The packager can specify an APAR reference file containing APAR reference numbers. An APAR reference number will allow installp to map an interim fix back to the APARs for all the Technology Levels where the fix was shipped. If installp determines that the interim fix is contained in the Technology Level, Service Pack, or PTF being applied, installp will automatically remove the interim fix prior to applying the updates.

Output and Topology

The emgr -d flag displays the contents and topology of the interim fix package. The -d option will work with the -v verbose option. Valid levels of verbosity are 1-3.

Verbosity level 1 (default) will display:

LABEL
EFIX FILES
TARGET LOCATION

Verbosity level 2 will display:

All level 1 output
ABSTRACT
REBOOT
PRE-REQUISITES
PRE_INSTALL
POST_INSTALL
PRE_REMOVE
POST_REMOVE
FILE TYPE

Verbosity level 3 will display:

All level 2 output
PACKAGING DATE
VUID
SIZE
ACL
CKSUM
PACKAGE
EFIX DESCRIPTION
CONTENTS OF INSTALL SCRIPTS (if text files)

For example:

To get level 1 verbosity output on interim fix package test.102403.epkg.Z, type:
```
emgr -d test.102403.epkg.Z
```
To get level 3 verbosity output on interim fix package test.102403.epkg.Z, type:
```
emgr -v3 -d test.102403.epkg.Z
```

Support for Additional Package Locking

The packager can specify a file containing package names that should be locked by the emgr command in addition to those that are automatically locked based on file ownership. The packager must specify the name of the package, the installer, and the type of package lock action (ALWAYS/IFINST). The packager can specify the package lock file using the epkg command in the following ways:

Specify the file location with the -l pkg_locks_file flag. For example:
```
epkg -l /tmp/pkglock.epkg myefix
```
The epkg command will prompt for the package locks file if the extended options flag (-v) is used. For example:
```
Enter the location for the package locks file or "." to skip.
-> /tmp/pkglock.epkg
```
Set the PKGLOCKS attribute to the local file location of the package lock file in the interim fix control file. For example:
```
PKGLOCKS=/tmp/pkglock.epkg
```

The format of the package locks file is as follows:

PackageName PackageAction PackageType

where PackageName is the name of the package to be locked and PackageAction is one of the following:

Item	Description
`ALWAYS`	Always attempt to lock this package. Failure to lock the package results in installation failure.
`IFINST`	Attempt to lock this package only if the package is installed. Failure to lock an installed package results in installation failure.

PackageType is installp (default), rpm, ISMP, other.

Note: Only installp locking is supported.

The maximum number of supported package lock entries is 32.

Example:

bos.rte.lvm ALWAYS installp
bos.games   IFINST installp

In the above example, the emgr command will always attempt to lock bos.rte.lvm during installation and will unlock it on removal. The emgr command will lock bos.games if, and only if, it is installed, and will unlock it on removal (if locked).

Support for the bosboot Option

The epkg command reboot options include rebooting without rebuilding the boot image.

The user can specify a reboot without bosboot in the following ways:

The o argument for the epkg -r flag indicates that reboot ("only") is required, but the emgr command should not call bosboot (that is, rebuild the boot image).

The reboot prompt in interactive mode indicates the following choices:

Select reboot policy for this efix package:
1) Reboot is NOT required.
2) Reboot is required. The boot image will be rebuilt.
3) Reboot is required. The boot image will NOT be rebuilt.

Set the BUILD_BOOT_IMAGE and REBOOT attribute to "yes" or "no" in the interim fix control file. The following REBOOT and BUILD_BOOT_IMAGE options are supported:

Item	Description
REBOOT=no & BUILD_BOOT_IMAGE=no	Reboot is NOT required.
REBOOT=yes & BUILD_BOOT_IMAGE=yes	Reboot is required. The boot image will be rebuilt.
REBOOT=yes & BUILD_BOOT_IMAGE=no	Reboot is required. The boot image will not be rebuilt.

Note: REBOOT=no & BUILD_BOOT_IMAGE=yes will result in an error from the epkg command.

Flags

Item	Description
-a APARrefFile	Specifies the file containing APAR reference number(s).
-d DescriptionFile	Specifies the file containing the interim fix description.
-e interimfixControlFile	Specifies the interim fix control file that controls how the interim fix is constructed.
-g PrerequisiteFile	Specifies the location of the interim fix prerequisite file that contains the interim fix label names. These labels are required before an interim fix package is installed.
-l LockFile	Specifies the location of the locked file that contains the package names. These packages are locked by the emgr command or automatically based on file ownership.
-p PrerequisiteFile	Specifies the file containing installp prerequisites.
-r {y\|n\|o}	Sets the epkg REBOOT attribute. This causes the emgr command to make changes as necessary to the boot image and issue a message instructing the user to reboot after installation. The y argument specifies that a reboot and a bosboot are required. The n argument specifies that a reboot is not required. The o argument indicates that a reboot is required, but emgr should not call bosboot.
-S SupersedeFile	Specifies the location of the interim fix supersede file that contains the interim fix label names. These labels are to be superseded when an epkg is installed.
-s	Causes the epkg command to skip questions regarding scripts and the prerequisite file.
-T	Specifies whether this interim fix was tested. Allowable values are yes or no. The default is no.
-u {yes\|no}	Specifies whether you will use an existing interim fix control file.
-v	Causes the epkg command to ask more questions for extended options. This includes asking you to specify permissions on all interim fix files.
-w WorkDirectory	Specifies the alternate work directory that the epkg command will use. The default work directory is $HOME/epkgwork.
-X	Causes the emgr command to automatically expand file systems when the interim fix is installed, if space is required and expansion is possible.

Parameters

interim fixLabel: Specifies a string that uniquely identifies this interim fix package. The maximum length of an interim fix label is 10 bytes.
Note: The interim fix manager requires each interim fix label on the system to be unique.

Subcommands

b!: Returns to the previous question.
s!: Shows the status of the current interim fix control file
q!: Quits without saving the interim fix control file. (Using the Ctrl+C key sequence causes the epkg command to ask you whether you want to save the interim fix control file.)
h!: Displays help information for the current question.

Exit Status

0: The epkg command operations completed successfully.
>0: An error occurred.

Examples

To run the epkg command in interactive mode and create an interim fix package with the interim fix label of myfix, type:
```
epkg myfix
```
To create an interim fix package with the interim fix label of myfix using an existing interim fix control file named /tmp/ecfile, type:
```
epkg -e /tmp/ecfile myfix
```
To create an interim fix package with the interim fix label of myfix and specify prerequisite file /tmp/prereq, description /tmp/description, and extended options, type:
```
epkg -v -p /tmp/prereq -d /tmp/description myfix
```

Files

Item	Description
/usr/sbin/epkg	Contains the epkg command.