INSTALLP(8,C) AIX Commands Reference INSTALLP(8,C)
-------------------------------------------------------------------------------
installp
PURPOSE
Installs a Licensed Program Product (LPP).
SYNTAX
+- -d /dev/rfd0 -+ +- -n $LOGNAME -+ +--------+
installp ---| |---| |---| +----+ |---|
+-- -d device ---+ +--- -n name ---+ +-| -q |-+
^| -t ||
|+----+|
+------+
DESCRIPTION
Warning: Under no circumstances attempt to run more than one installation or
update process at the time. The primary site must be up when executing
installp.
Failure to perform these steps may result in a failure in the installation or
update of the active files being serviced.
The installp command installs an LPP. You must be operating with superuser
authority to run this command.
Because more than one LPP may be on a set of diskettes, installp asks whether
you want to install each LPP. If you do, installp checks to see if it is an
older version than the one currently installed. If the version to be installed
is older than the version on the system, installp informs you and asks if you
want to continue.
The installp command makes a backup copy of the LPP history file before
installation begins. If installation is not successful, it sets the Version,
Release, and Level, and Fix fields of the last record of the history file to
00.00.0000.0000 and logs the exit value in the program history file. The
history file remains on the system as /usr/lpp/lpp-idd/lpp.hist, where lpp-idd
is the LPP name.
ERROR-RECOVERY
Running the service tools, may change certain key files and directories mainly:
1) The global history file /etc/lpp/ghf
2) The LPP's individual history file, /usr/lpp/lpp-idd/lpp.hist
Processed November 8, 1990 INSTALLP(8,C) 1
INSTALLP(8,C) AIX Commands Reference INSTALLP(8,C)
3) /usr/lpp.save/*
4) /usr/lib/qproc.queue/*
If a fatal error such as a system crash occurs, these files and directories may
be left in a corrupted form. An error recovery system is provided.
As the service tools proceed, they log their actions in a file:
/etc/lpp/config.log
If all goes well, the above file is removed upon completion of the service.
When a detectable error occurs (or the system crashes), this file remains, and
is used by the error-recovery tool /etc/lpp/inuconfig to set the system back to
before the service command was run.
When installp is run, it checks for the existence of this file, if it exists
installp will know an error had previously occurred in a service tool, installp
will then ask the user to run /etc/lpp/inuconfig before running installp. The
inuconfig command will then recover uncorrupted versions of history files and
cleanup corrupted directories when it is done, it will remove the file:
/etc/lpp/config.log
thus enabling installp to proceed.
Note: All installs and updates of LPPs are recorded in the global history file
/etc/lpp/ghf.
You cannot use INTERRUPT to stop the installp command. To stop installp, press
QUIT WITH DUMP. This should be used only in extreme circumstances since the
state of the system cannot be predicted and one of the following may occur:
o The write-verify feature may be left on for all minidisks
o All terminals other than the console may be disabled
o Some install control files may need to be deleted.
Notes:
1. Only ordinary files with the prefix lpp. remain in /usr/lpp/lpp-idd after
completion of installp. All other ordinary files are removed.
2. Installing a complete program on a client where a program subset already
exists will cause the history file information for the program subset to be
destroyed.
FLAGS
Processed November 8, 1990 INSTALLP(8,C) 2
INSTALLP(8,C) AIX Commands Reference INSTALLP(8,C)
-d device Installs the LPP from the specified device. The default
device is /dev/rfd0. If a tape device is specified, the
rewind device must be specified (/dev/rmt0rh). The
installp command does not support the no rewind device.
-n name Logs the first eight nonblank characters of name in the
LPP history file. The default name is the value of the
environment variable $LOGNAME.
-q Runs in quiet mode suppressing most of the interactive
queries.
-t Prevents installp from rebooting after installing on
LPPs.
When the installation of an LPP completes, it is sometimes necessary for the
installation tools to take special actions, such as build the kernel. In these
cases, a special code must be returned to the installation tools via the
installation scripts instal or inst_updt.loc. described in the AIX Operating
System Programming Tools and Interfaces, Chapter 13. This allows several LPPs
to be installed before rebooting. Codes that have local implications (2, 3, 4,
and 5) are returned by inst_updt.loc. Code 5 is returned by instal. Code 0
and error codes may be returned by either. This return code signals the end of
the install LPP, and determines what actions the installation tools will
perform next.
Use one of the following values from a return code.
Code Description
0 Successful completion. No additional action is needed.
2 Successful completion. The service tools update superblocks, the inode
list, and flush the buffers (sync). Then they instruct the user to
reboot the operating system.
3 Successful completion. The service tools build a new kernel. Then
they update superblocks, the inode list, and flush the buffers. They
then instruct the user to reboot the system.
4 Successful completion. The service tools build a new kernel. Then
they update superblocks, the inode list, and flush the buffers. The
service tools instruct the user to reboot the operating system.
5 Installation cancelled by the instal procedure without errors.
6 Successful completion. The service tools update superblocks and the
inode list, and flushes the buffers (sync). Then they instruct the
user to reboot the system.
Processed November 8, 1990 INSTALLP(8,C) 3
INSTALLP(8,C) AIX Commands Reference INSTALLP(8,C)
other Error. If returned by instal, the service tools set the "Version",
"Release Level" and fix fields of the last information record in
lpp.hist to all zeros, and write the return code value in lpp.hist as
an error code.
INTERNAL COMMANDS
Install procedures can use the internal install commands. These commands
provide common code for the save and recovery functions frequently needed by
most LPP-provided procedures. They do a minimum validation of input parameters
and return exit values like subcommands. You can, however, receive messages
from system commands that they call. Procedures that call these commands can
use the /usr/include/inu21.h file to define return codes.
inusave
The inusave command saves some or all of the files and archive files that will
be changed during a LPP install or update procedure. It uses the following
syntax:
inusave listfile lpp-idd
The lpp-idd parameter specifies the LPP to be installed or updated. lpp-idd
can be a maximum of 8 characters. listfile, which must be a full path name,
contains a list of relative path names (relative to the root) for all of the
files that need to be saved. listfile must be in the format of an apply list
(see AIX Operating System Programming Tools and Interfaces, Chapter 13, for a
discussion of the format of an apply list).
The inusave command creates the save directory
(/usr/lpp/lpp-idd/inst_updt.save). This is the directory in which the install
and update procedures store saved files and the control list that correlates
the local file names with their full path names. inusave uses listfile as a
basis to determine which files need to be temporarily saved.
NEW METHOD
Simple copying, however, could not handle non-regular files (for example,
pipes and devices), textbusy files, and the TCF attributes of regular files
such as fstores. Therefore, inusave has been modified to use the backup
utility to save the contents of the apply list. A backup-by-name format
file directory called /usr/lpp-idd/inst_updt.save/lpp.name stores the files
from the apply list which are to be used in rejecting an update. Then
inurecv checks to see which method was used for rejecting the update and
uses copy for the old method, or restore for the new method. inurecv is
fully compatible with the old method.
An archived constituent file is saved if there is a valid archive control file,
/usr/lpp/lpp-idd/lpp.acf, for the LPP. If this file exists, inusave compares
each of the file names in listfile to the constituent file names in
/usr/lpp/lpp-idd/lpp.acf. When it finds a match, inusave uses the ar command
to extract the constituent file from its associated archive file.
Processed November 8, 1990 INSTALLP(8,C) 4
INSTALLP(8,C) AIX Commands Reference INSTALLP(8,C)
It then moves it to /usr/lpp/lpp-idd/inst_updt.save/archive.n, where n is an
integer selected by inusave. inusave maintains a list of the extracted files
that have been saved in the file /usr/lpp/lpp-idd/inst_updt.save/archive.list.
The format of each entry in the list is:
archive.n cfile afile
where archive.n is the name of the saved file and cfile and afile are the
constituent and archive files defined in the archive control file.
The inusave command returns the following exit values:
0 No error conditions occurred.
105 Failure occurred trying to create a save directory.
107 Copy of a file from one directory to another failed. This implies that the
update apply has not yet begun and that the old level of the program is
still usable.
202 One or more parameters missing.
204 Too many parameters were entered.
207 Could not access the apply list.
inurecv
The inurecv command recovers all files and archive-constituent files saved from
the previous inusave. inurecv uses the following syntax:
inurecv lpp-idd reject-flag
It uses the control lists from the /usr/lpp/lpp-idd/inst_updt.save directory to
recover the files. inusave creates the /usr/lpp/lpp-idd/inst_updt.save
directory and control lists. inurecv also recovers files that may have been
saved by the program-provided install or update procedure (see AIX Operating
System Programming Tools and Interfaces for details).
The inurecv command has to distinguish between an immediate recovery that
occurs because of an error condition during an install or update and an update
rejection that occurs because a user rejects an update ("updatep -r"). If the
reject-flag argument is yes, inurecv assumes that it is being run because of an
update rejection. If the argument is no or if no flag is specified, inurecv
assumes that it is being run because of an immediate recovery.
The inurecv command returns the following exit status values:
0 No error conditions occurred.
101 The save directory does not exist.
102 A copy of a file from one directory to another failed. This implies that
the LPP could not be recovered and that it must be reinstalled and any
updates reapplied.
104 A file that was saved in the save directory was not found.
Processed November 8, 1990 INSTALLP(8,C) 5
INSTALLP(8,C) AIX Commands Reference INSTALLP(8,C)
205 Replacement of a constituent file in an archive file failed while
attempting to recover a LPP. This implies that the LPP is no longer
useable and should be reinstalled and any updates reapplied.
inurest
The inurest command does simple restores and archives. It does not do any
additional processing or user interaction. inurest uses the following syntax:
inurest [-ddevice] [-q] listfile lpp-idd
The listfile is the full path name of a file containing the relative directory
target path name (relative to the root), of files that a LPP needs to restore.
It must be in the format of an apply list. inurest restores all files in the
list relative to the root directory. lpp-idd specifies the name of the LPP to
be installed or updated. It can be a maximum of 8 characters.
To archive a file, there must be an archive control file,
/usr/lpp/lpp-idd/lpp.acf. If it exists, inurest compares each of the target
names in listfile to the component files listed in there. Whenever inurest
finds a match, it archives the restored file into the corresponding archive
file and deletes the restored file.
The following flags modify the action of inurest:
-d device
Specifies the input device. The default device is /dev/rfd0.
-q Prohibits restore from displaying the "insert volume 1" prompt.
The inurest command returns the following exit status values:
0 No error conditions occurred.
106 Failed trying to restore an updated version of files.
201 An invalid flag was specified.
202 One or more parameters missing.
204 Too many parameters were entered.
206 Failed trying to replace file in an archive file.
208 Could not access the apply list.
ckprereq
The ckprereq command determines whether the system level is compatible with the
LPP to be installed or updated. It uses the following syntax:
ckprereq [-v] [-f + prerequisites]
You can run ckprereq only if you are operating with superuser authority.
prerequisites is a LPP prerequisite list file. Each record in this file
contains the name of a prerequisite LPP and describes the version, release, and
level requirements. There is one record for each prerequisite LPP. The
Processed November 8, 1990 INSTALLP(8,C) 6
INSTALLP(8,C) AIX Commands Reference INSTALLP(8,C)
default prerequisites file is prereq. See AIX Operating System Programming
Tools & Interfaces for details on the format of ckprereq file entries.
The ckprereq command tests the current version, release, and level found in the
global history file /etc/lpp/ghf and marks each "prereq state" field of the
prereq file with one of the following codes if the test fails:
l The test is false for level.
f The history file format is not fixed 80.
n The history file was not found.
r The test is false for release.
s There is a syntax error in the prereq file.
u The history file is in an unknown state.
v The test is false for version.
A blank "prereq state" field indicates that the test was true. The exit value
of ckprereq is the number of records that did not test true. If all records
test true, the exit value is 0.
The following flags modify the action of ckprereq.:
-f prerequisites Specifies the prerequisites file to use in place of
prereq.
-v Sends a descriptive message to standard error for
each failure in the prerequisite LPP test. The
messages give the same information as the prereq
state field of the prereq file.
Other Internal Commands
The following extra internal service commands may also be used.
/etc/lpp/insvl listfile lpp-idd
The local equivalent to inusave, this routine works on target directory
in /local/lpp vs /usr/lpp in case of inusave.
/etc/lpp/inrcvl lpp-idd
The local equivalent to inurecv, this routine works on target directory
in /local/lpp/ vs /usr/lpp in case of inurecv.
/etc/lpp/qapp
Append a new local action to the system queue.
qapp [-c|-r|-u|-i|-a] lpp-iddvv.rr.llll.ffff...
qapp accepts similar flags as updatep (-a, -c, -r, -u or -i), indicating
the action to be taken. lpp-iddvv.rr.llll.ffff are an LPP name and the
version, release, level, and fix numbers. It creates an entry in the
system queue which, upon being processed (see qproc below), causes the
appropriate action (apply-commit-reject-uncommit) to be done on an
individuals site's local file system.
Processed November 8, 1990 INSTALLP(8,C) 7
INSTALLP(8,C) AIX Commands Reference INSTALLP(8,C)
/etc/lpp/qproc
Program to trigger the processing of all pending queue entries on an
individual site.
onsite sitenumber qproc
qproc runs on each individual site and processes all pending updatep or
installp actions for that site. qproc first compares the local queue
pointer to the global queue pointer. If local queue pointer file is not
found, it is assumed that the local queue pointer value is null, meaning
the site is new and all queue entries are to be processed. If local
queue pointer is less than global queue pointer, a "local" action is
pending. qproc processes the entries one by one beginning with entry
after the one pointed to by the local pointer and ending with the last
queue entry.
Options:
-i The -i option of qproc is used to install the local portion of
an LPP on a secondary site in a cluster. Normally this function
is only used by installp. During installp you are asked to
select the desired installation sites of the LPP. These sites
are passed to qproc for the LPPs that have local actions so that
the LPP may be serviced later on those sites.
If you decide at a later date to install an LPP with local
actions on some other site in the cluster, run:
""qproc -i lpp_name"" on that site.
The LPP will be installed in the local of the site, and brought
up to date with the current level of service for that LPP.
NOTE: ALL LEVELS OF SERVICE FOR THE LPP MUST REMAIN AVAILABLE
ON THE CLUSTER AT THE TIME THAT QPROC IS CALLED. qproc does not
need to be run for LPPs that do not have local action.
/etc/lpp/qinvoke
Program to coordinate when qproc is to run on each site of the multisite
cluster. On the multisite systems, this program uses the command at to
set up jobs for each site's qproc to run.
On the single site systems, qproc is run as a part of installp/Updatep
because time synchronization is required for a one-site system. In such
cases, qinvoke simply calls qproc.
/etc/lpp/ckstack
ckstack lpp-idd vv.rr.llll.ffff
ckstack looks into the backout stack to find the frame containing the
desired backout. If there are other frames (containing other LPPs
which, due to prerequisites, must be backed out before the desired LPP),
Processed November 8, 1990 INSTALLP(8,C) 8
INSTALLP(8,C) AIX Commands Reference INSTALLP(8,C)
it creates a file containing a list of these other frames. This file is
called /usr/lpp.save/list.
If there are any relevant cleaned-up stack frames, it also warns the
user to restore them using cleanup -r command.
FILES
/usr/lpp.save/... Backout information.
/usr/lib/qproc.queue/... System queues directory.
/local/qproc.queue/... Local queue directory.
/usr/lpp/prm_name/lpp.loc/... Files needed for local installations.
/usr/include/inu21.h Defines error codes for internal commands.
/usr/lpp/lpp-idd/instal Program installation procedure.
/usr/lpp/lpp-idd/inst_updt.save
Directory for saved files.
/usr/lpp/lpp-idd/inst_updt/inuPIDtempn
Temporary files.
/usr/lpp/lpp-idd/liblpp.a Central archive file.
/usr/lpp/lpp-idd/lpp.acf Archive control file.
/usr/lpp/lpp-idd/lpp.hist Program history file.
/usr/lpp/lpp-idd/prereq Program prerequisite list file.
/etc/lpp/ghf The global history file.
/etc/lpp/config.log The error-recovery log file.
/etc/lpp/inconfig The error-recovery utility.
RELATED INFORMATION
See the following command: "updatep" and "cleanup."
See the fork and exec system calls and the lpp.hist file in AIX Operating
System Technical Reference.
See the discussion of installing programs in AIX Operating System Programming
Tools and Interfaces.
See the section on "Licensed Program Product (LPP) Service Process" in the AIX
Administration Guide for System 370.
Processed November 8, 1990 INSTALLP(8,C) 9