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 July 12, 1991 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 July 12, 1991 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 July 12, 1991 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 July 12, 1991 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 July 12, 1991 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 July 12, 1991 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 July 12, 1991 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 July 12, 1991 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 July 12, 1991 INSTALLP(8,C) 9