Exit Codes for Scripts

Each script must exit with one of the exit codes shown in the following table.

Table 3-3 Installation Script Exit Codes

See Chapter 5, Package Creation Case Studies for examples of exit codes returned by installation scripts.

Note - All installation scripts delivered with your package should have an entry in the prototype file. The file type should be i (for package installation script).

Writing a request Script

The request script is the only way your package can interact directly with the administrator installing it. It can be used, for example, to ask the administrator if optional pieces of a package should be installed.

The output of a request script must be a list of environment variables and their values. This list can include any of the parameters you created in the pkginfo file and the CLASSES and BASEDIR parameters. The list can also introduce environment variables that have not been defined elsewhere (although the pkginfo file should always provide default values, when practical). For more information on package environment variables, see "Package Environment Variables".

When your request script assigns values to a environment variable, it must then make those values available to the pkgadd command and other package scripts.

request Script Behaviors

• The request script cannot modify any files. It only interacts with administrators installing the package and creates a list of environment variable assignments based upon that interaction. To enforce this restriction, the request script is executed as the non-privileged user install if that user exists; otherwise it is executed as the non-privileged user nobody. The request script does not have superuser authority.

• The pkgadd command calls the request script with one argument that names the script's response file (the file that stores the administrator's responses).

• The request script is not executed during package removal. However, the environment variables assigned by the script are saved and are available during removal.

Design Rules for request Scripts

• There can be only one request script per package and it must be named request.

• The environment variable assignments should be added to the installation environment for use by the pkgadd command and other packaging scripts by writing them to the response file (known to the script as $1).

• System environment variables and standard installation environment variables, except for the CLASSES and BASEDIR parameters, cannot be modified by a request script. Any of the other environment variables you created can be changed.

  ---

  Note - A request script can only modify the BASEDIR parameter starting with the Solaris 2.5 and compatible releases.

  ---

• Every environment variable that the request script may manipulate should be assigned a default value in the pkginfo file.

• The format of the output list should be PARAM=value. For example:

  CLASSES=none class1

• The administrator's terminal is defined as standard input to the request script.

• Do not perform any special analysis of the target system in a request script. It is risky to test the system for the presence of certain binaries or behaviors, and set environment variables based upon that analysis, because there is no guarantee that the request script will actually be executed at install time. The administrator installing the package may provide a response file that will insert the environment variables without ever calling the request script. If the request script is also evaluating the target file system, that evaluation may not happen. An analysis of the target system for special treatment is best left to the checkinstall script.

Note - If it is possible that the administrators who will be installing your package will be using the JumpStart™ product, then the installation of your package must not be interactive. This implies that either you should not provide a request script with your package, or you need to communicate to the administrator that they should use the pkgask command, prior to installation, to store their responses to the request script. For more information on the pkgask command, see pkgask(1M).

How to Write a request Script

1. Make the directory containing your information files the current working directory.

2. Create a file named request with your favorite text editor.

3. Save your changes and quit the editor when you are done.

4. Complete one of the following tasks.

   • If you want to create additional installation scripts, skip to the next task, "How to Gather File System Data".

   • If you have not created your prototype file, complete the procedure "How to Create a prototype File Using the pkgproto Command", and skip to Step 5.

   • If you have already created your prototype file, edit it and add an entry for the installation script you just created.

5. Build your package.

   See "How to Build a Package", if needed.

Where to Go Next

After you build the package, install it to confirm that it installs correctly and verify its integrity. Chapter 4, Verifying and Transferring a Package explains how to do this and provides step-by-step instructions on how to transfer your verified package to a distribution medium.

Example--Writing a request Script

When a request script assigns values to environment variables, it must make those values available to the pkgadd command. This example shows a request script segment that performs this task for the four environment variables CLASSES, NCMPBIN, EMACS, and NCMPMAN. (These were defined in an interactive session with the administrator earlier in the script.)

# make environment variables available to installation
# service and any other packaging script we might have
 
cat >$1 <<!
CLASSES=$CLASSES
NCMPBIN=$NCMPBI
EMACS=$EMACS
NCMPMAN=$NCMPMAN
!

Gathering Data With the checkinstall Script

The checkinstall script is executed shortly after the optional request script. It runs as the user install, if such a user exists, or the user nobody. The checkinstall script does not have the authority to change file system data; it is strictly a data gatherer. However, based on the information it gathers, it can create or modify environment variables in order to control the course of the resulting installation. It is also capable of cleanly halting the installation process.

The checkinstall script is intended to perform basic checks on a file system that would not be normal for the pkgadd command. For example, it can be used to check ahead to determine if any files from the current package are going to overwrite existing files, or manage general software dependencies (the depend file only manages package-level dependencies).

Unlike the request script, the checkinstall script is executed whether or not a response file is provided; and, its presence does not brand the package as "interactive." This means that the checkinstall script can be used in situations where a request script is forbidden or administrative interaction is not practical.

Note - The checkinstall script is available starting with the Solaris 2.5 and compatible releases.

checkinstall Script Behaviors

• The checkinstall script cannot modify any files. It only analyzes the state of the system and creates a list of environment variable assignments based upon that interaction. To enforce this restriction, the checkinstall script is executed as the non-privileged user install if that user exists; otherwise it is executed as the non-privileged user nobody. The checkinstall script does not have superuser authority.

• The pkgadd command calls the checkinstall script with one argument that names the script's response file (the file that stores the administrator's responses).

• The checkinstall script is not executed during package removal. However, the environment variables assigned by the script are saved and are available during removal.