| Skip Navigation Links | |
| Exit Print View | |
|
Application Packaging Developer's Guide |
3. Enhancing the Functionality of a Package (Tasks)
Creating Information Files and Installation Scripts (Task Map)
How to Define Package Dependencies
How to Write a Copyright Message
Reserving Additional Space on a Target System
How to Reserve Additional Space on a Target System
Script Processing During Package Installation
Script Processing During Package Removal
Package Environment Variables Available to Scripts
Obtaining Package Information for a Script
Design Rules for request Scripts
Gathering File System Data With the checkinstall Script
Design Rules for checkinstall Scripts
How to Gather File System Data
Design Rules for Procedure Scripts
How to Write Procedure Scripts
How Classes Are Processed During Package Installation
How Classes Are Processed During Package Removal
Adding Trusted Certificates to the Package Keystore
Adding a User Certificate and Private Key to the Package Keystore
Verifying the Contents in the Package Keystore
Deleting Trusted Certificates and Private Keys From the Package Keystore
How to Create an Unsigned, Directory-Format Package
How to Import the Certificates Into the Package Keystore
4. Verifying and Transferring a Package
5. Case Studies of Package Creation
This section discusses optional package installation scripts. The pkgadd command automatically performs all the actions necessary to install a package using the package information files as input. You do not have to supply any package installation scripts. However, if you want to create customized installation procedures for your package, you can do so with installation scripts. Installation scripts:
Must be executable by the Bourne shell (sh)
Must contain Bourne shell commands and text
Do not need to contain the #!/bin/sh shell identifier
Need not be an executable file
There are four types of installation scripts with which you can perform customized actions:
The request script solicits data from the administrator who is installing a package for assigning or redefining environment variables.
The checkinstall script examines the target system for needed data, can set or modify package environment variables, and determines whether the installation proceeds.
Note - The checkinstall script is available starting with the Solaris 2.5 and compatible releases.
Procedure scripts identify a procedure to be invoked before or after the installation or removal of a package. The four procedure scripts are preinstall, postinstall, preremove, and postremove.
Class action scripts define an action or set of actions that should be applied to a class of files during installation or removal. You can define your own classes. Alternatively, you can use one of the four standard classes (sed, awk, build, and preserve).
The type of scripts you use depends on when the action of the script is needed during the installation process. As a package is installed, the pkgadd command performs the following steps:
Executes the request script.
This step is the only point at which your package can solicit input from the administrator who is installing the package.
Executes the checkinstall script.
The checkinstall script gathers file system data and can create or alter environment variable definitions to control the subsequent installation. For more information on package environment variables, see Package Environment Variables.
Installs package objects, for each class to be installed.
Installation of these files occurs class by class, and class action scripts are executed accordingly. The list of classes operated on and the order in which they should be installed is initially defined with the CLASSES parameter in your pkginfo file. However, your request script or checkinstall script can change the value of the CLASSES parameter. For more information on how classes are processed during installation, see How Classes Are Processed During Package Installation.
Creates symbolic links, devices, named pipes, and required directories.
Installs the regular files (file types e, v, f), based on their class
The class action script is passed only regular files to install. All other package objects are created automatically from information in the pkgmap file.
Creates all hard links.
When a package is being removed, the pkgrm command performs these steps:
Removes the package objects, for each class
Removal also occurs class by class. Removal scripts are processed in the reverse order of installation, based on the sequence defined in the CLASSES parameter. For more information on how classes are processed during installation, see How Classes Are Processed During Package Installation.
Removes hard links.
Removes regular files.
Removes symbolic links, devices, and named pipes.
The request script is not processed at the time of package removal. However, the script's output is retained in the installed package and made available to removal scripts. The request script's output is a list of environment variables.
The following groups of environment variables are available to all installation scripts. Some of the environment variables can be modified by a request script or a checkinstall script.
The request script or the checkinstall script can set or modify any of the standard parameters in the pkginfo file, except for the required parameters. The standard installation parameters are described in detail in the pkginfo(4) man page.
Note - The BASEDIR parameter can only be modified starting with the Solaris 2.5 release and compatible releases.
You can define your own installation environment variables by assigning values to them in the pkginfo file. Such environment variables must be alphanumeric with initial capital letters. Any of these environment variables can be changed by a request script or a checkinstall script.
Both a request script and a checkinstall script can define new environment variables by assigning values to them and putting them in the installation environment.
The following table lists environment variables that are available to all installation scripts through the environment. None of these environment variables can be modified by a script.
|
Two commands can be used from scripts to solicit information about a package:
The pkginfo command returns information about software packages, such as the instance identifier and package name.
The pkgparam command returns values for requested environment variables.
See the pkginfo(1) man page, the pkgparam(1) man page, and Chapter 4, Verifying and Transferring a Package for more information.
Each script must exit with one of the exit codes shown in the following table.
Table 3-2 Installation Script Exit Codes
|
See Chapter 5, Case Studies of Package Creation for examples of exit codes that are 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).
The request script is the only way your package can interact directly with the administrator who is installing it. This script 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 that 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. However, 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 an environment variable, it must then make those values available to the pkgadd command and other package scripts.
The request script cannot modify any files. This script only interacts with administrators who are installing the package and creates a list of environment variable assignments based upon that interaction. The request script runs as the non privileged user install if that user exists. Otherwise, the script is executed as root.
The pkgadd command calls the request script with one argument that names the script's response file. The response file 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 package removal.
There can be only one request script per package. The script 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 that 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 to set environment variables based upon that analysis. There is no guarantee that the request script will actually be executed at install time. The administrator who is 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 the administrators who will be installing your package might use the JumpStart product, then the installation of your package must not be interactive. Either you should not provide a request script with your package, or you need to communicate to the administrators that they should use the pkgask command prior to installation. The pkgask command stores their responses to the request script. For more information on the pkgask command, see the pkgask(1M) man page.
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 by Using the pkgproto Command. 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.
See How to Build a Package, if needed.
Example 3-5 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. Assume that these variables 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=$NCMPBIN EMACS=$EMACS NCMPMAN=$NCMPMAN !
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 these tasks and provides step-by-step instructions on how to transfer your verified package to a distribution medium.
The checkinstall script is executed shortly after the optional request script. The checkinstall script runs as the user install, if such a user exists, or as the user nobody. The checkinstall script does not have the authority to change file system data. However, based on the information the script gathers, it can create or modify environment variables in order to control the course of the resulting installation. The script 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, this script 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. The script's presence does not brand the package as interactive. 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.
The checkinstall script cannot modify any files. This script 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, this script 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 script's response file is 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 package removal.
There can be only one checkinstall script per package. The script must be named checkinstall.
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 checkinstall script. Any of the other environment variables that you created can be changed.
Every environment variable that the checkinstall 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
Administrator interaction is not permitted during execution of a checkinstall script. All administrator interaction is restricted to the request script.
If you want to create additional installation scripts, skip to the next task, How to Write Procedure Scripts.
If you have not created your prototype file, complete the procedure How to Create a prototype File by Using the pkgproto Command. 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.
See How to Build a Package, if needed.
Example 3-6 Writing a checkinstall Script
This example checkinstall script checks to see if database software needed by the SUNWcadap package is installed.
# checkinstall script for SUNWcadap
#
# This confirms the existence of the required specU database
# First find which database package has been installed.
pkginfo -q SUNWspcdA # try the older one
if [ $? -ne 0 ]; then
pkginfo -q SUNWspcdB # now the latest
if [ $? -ne 0 ]; then # oops
echo "No database package can be found. Please install the"
echo "SpecU database package and try this installation again."
exit 3 # Suspend
else
DBBASE="`pkgparam SUNWsbcdB BASEDIR`/db" # new DB software
fi
else
DBBASE="`pkgparam SUNWspcdA BASEDIR`/db" # old DB software
fi
# Now look for the database file we will need for this installation
if [ $DBBASE/specUlatte ]; then
exit 0 # all OK
else
echo "No database file can be found. Please create the database"
echo "using your installed specU software and try this"
echo "installation again."
exit 3 # Suspend
fi
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 these tasks and provides step-by-step instructions on how to transfer your verified package to a distribution medium.
The procedure scripts provide a set of instructions to be performed at particular points in package installation or removal. The four procedure scripts must be named one of the predefined names, depending on when the instructions are to be executed. The scripts are executed without arguments.
Runs before class installation begins. No files should be installed by this script.
Runs after all volumes have been installed.
Runs before class removal begins. No files should be removed by this script.
Runs after all classes have been removed.
Procedure scripts are executed as uid=root and gid=other.
Each script should be able to be executed more than once because it is executed once for each volume in a package. This means that executing a script any number of times with the same input produces the same results as executing the script only once.
Each procedure script that installs a package object not in the pkgmap file must use the installf command to notify the package database that it is adding or modifying a path name. After all additions or modifications are complete, this command should be invoked with the -f option. Only the postinstall and postremove scripts may install package objects in this way. See the installf(1M) man page and Chapter 5, Case Studies of Package Creation for more information.
Administrator interaction is not permitted during execution of a procedure script. All administrator interaction is restricted to the request script.
Each procedure script that removes files not installed from the pkgmap file must use the removef command to notify the package database that it is removing a path name. After removal is complete, this command should be invoked with the -f option. See the removef(1M) man page and Chapter 5, Case Studies of Package Creation for details and examples.
Note - The installf and removef commands must be used because procedure scripts are not automatically associated with any path names listed in the pkgmap file.
A procedure script must be named one of the predefined names: preinstall, postinstall, preremove, or postremove.
If you want to create class action scripts, skip to the next task, How to Write Class Action Scripts.
If you have not created your prototype file, complete the procedure How to Create a prototype File by Using the pkgproto Command. Skip to Step 5.
If you have already created your prototype file, edit it and add an entry for each installation script you just created.
See How to Build a Package, if needed.
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 these tasks and provides step-by-step instructions on how to transfer your verified package to a distribution medium.
Object classes allow a series of actions to be performed on a group of package objects at installation or removal. You assign objects to a class in the prototype file. All package objects must be given a class, although the class of none is used by default for objects that require no special action.
The installation parameter CLASSES, defined in the pkginfo file, is a list of classes to be installed (including the none class).
Note - Objects defined in the pkgmap file that belong to a class not listed in this parameter in the pkginfo file will not be installed.
The CLASSES list determines the order of installation. Class none is always installed first, if present, and removed last. Since directories are the fundamental support structure for all other file system objects, they should all be assigned to the none class. Exceptions can be made, but as a general rule, the none class is safest. This strategy ensures that the directories are created before the objects they will contain. In addition, no attempt is made to delete a directory before it has been emptied.
The following describes the system actions that occur when a class is installed. The actions are repeated once for each volume of a package, as that volume is being installed.
The pkgadd command creates a path name list.
The pkgadd command creates a list of path names upon which the action script operates. Each line of this list contains source and destination path names, separated by a space. The source path name indicates where the object to be installed resides on the installation volume. The destination path name indicates the location on the target system where the object should be installed. The contents of the list are restricted by the following criteria:
The list contains only path names that belong to the associated class.
If the attempt to create the package object fails, then directories, named pipes, character devices, block devices, and symbolic links are included in the list with the source path name set to /dev/null. Normally, these items are automatically created by the pkgadd command (if not already in existence) and given proper attributes (mode, owner, group) as defined in the pkgmap file.
Linked files where the file type is l are not included in the list under any circumstances. Hard links in the given class are created in item 4.
If no class action script is provided for installation of a particular class, the path names in the generated list are copied from the volume to the appropriate target location.
A class action script is executed if one exists.
The class action script is invoked with standard input that contains the list generated in item 1. If this volume is the last volume of the package, or no more objects exist in this class, the script is executed with the single argument of ENDOFCLASS.
Note - Even if no regular files of this class exist in the package, the class action script is called at least once with an empty list and the ENDOFCLASS argument.
The pkgadd command performs a content and attribute audit, and creates hard links.
After successfully executing items 2 or 3, the pkgadd command audits both content and attribute information for the list of path names. The pkgadd command creates the links associated with the class automatically. Detected attribute inconsistencies are corrected for all path names in the generated list.
Objects are removed class by class. Classes that exist for a package but are not listed in the CLASSES parameter are removed first (for example, an object installed with the installf command). Classes listed in the CLASSES parameter are removed in reverse order. The none class is always removed last. The following describes the system actions that occur when a class is removed:
The pkgrm command creates a path name list.
The pkgrm command creates a list of installed path names that belong to the indicated class. Path names referenced by another package are excluded from the list unless their file type is e. A file type of e means the file should be edited upon installation or removal.
If the package being removed had modified any files of type e during installation, it should remove just the lines it added. Do not delete a non-empty editable file. Remove the lines that the package added.
If no class action script exists, the path names are deleted.
If your package has no removal class action script for the class, all the path names in the list generated by the pkgrm command are deleted.
Note - Files with a file type of e (editable) are not assigned to a class and an associated class action script. These files are removed at this point, even if the path name is shared with other packages.
If a class action script exists, the script is executed.
The pkgrm command invokes the class action script with standard input for the script that contains the list generated in item 1.
The pkgrm command performs an audit.
After successfully executing the class action script, the pkgrm command removes references to the path names from the package database unless a path name is referenced by another package.
The class action script defines a set of actions to be executed during installation or removal of a package. The actions are performed on a group of path names based on their class definition. See Chapter 5, Case Studies of Package Creation for examples of class action scripts.
The name of a class action script is based on the class on which it should operate and whether those operations should occur during package installation or package removal. The two name formats are shown in the following table:
|
For example, the name of the installation script for a class named manpage would be i.manpage. The removal script would be named r.manpage.
Note - This file name format is not used for files that belong to the sed, awk, or build system classes. For more information on these special classes, see The Special System Classes.
Class action scripts are executed as uid=root and gid=other.
A script is executed for all files in the given class on the current volume.
The pkgadd and pkgrm commands create a list of all objects listed in the pkgmap file that belong to the class. As a result, a class action script can act only upon path names defined in the pkgmap that belong to a particular class.
When a class action script is executed for the last time (that is, no more files belong to that class), the class action script is executed once with the keyword argument ENDOFCLASS.
Administrator interaction is not permitted during execution of a class action script.
If a package spans more than one volume, the class action script is executed once for each volume that contains at least one file that belongs to a class. Consequently, each script must be able to be executed more than once. This means that executing a script any number of times with the same input must produce the same results as executing the script only once.
When a file is part of a class that has a class action script, the script must install the file. The pkgadd command does not install files for which a class action script exists, although it does verify the installation.
A class action script should never add, remove, or modify a path name or system attribute that does not appear in the list generated by the pkgadd command. For more information on this list, see item 1 in How Classes Are Processed During Package Installation.
When your script sees the ENDOFCLASS argument, put post-processing actions such as clean up into your script.
All administrator interaction is restricted to the request script. Do not try to obtain information from the administrator by using a class action script.
The system provides four special classes:
Provides a method for using sed instructions to edit files upon package installation and removal.
Provides a method for using awk instructions to edit files upon package installation and removal.
Provides a method to dynamically construct or modify a file by using Bourne shell commands.
Provides a method to preserve files that should not be overwritten by future package installations.
Provides automated installation and uninstallation of SMF (Service Management Facility) services associated with a manifest. The manifest class should be used for all SMF manifests in a package.
If several files in a package require special processing that can be fully defined through sed, awk, or sh commands, installation is faster by using the system classes rather than multiple classes and their corresponding class action scripts.
The sed class provides a method to modify an existing object on the target system. The sed class action script executes automatically at installation if a file that belongs to class sed exists. The name of the sed class action script should be the same as the name of the file on which the instructions are executed.
A sed class action script delivers sed instructions in the following format:
Two commands indicate when instructions should be executed. The sed instructions that follow the !install command are executed during package installation. The sed instructions that follow the !remove command are executed during package removal. The order in which these commands are used in the file does not matter.
For more information on sed instructions, see the sed(1) man page. For examples of sed class action scripts, see Chapter 5, Case Studies of Package Creation.
The awk class provides a method to modify an existing object on the target system. Modifications are delivered as awk instructions in an awk class action script.
The awk class action script is executed automatically at installation if a file that belongs to class awk exists. Such a file contains instructions for the awk class script in the following format:
Two commands indicate when instructions should be executed. The awk instructions that follow the !install command are executed during package installation. The instructions that follow the !remove command are executed during package removal. These commands may be used in any order.
The name of the awk class action script should be the same as the name of the file on which the instructions are executed.
The file to be modified is used as input to the awk command and the output of the script ultimately replaces the original object. Environment variables may not be passed to the awk command with this syntax.
For more information on awk instructions, see the awk(1) man page.
The build class creates or modifies a package object file by executing Bourne shell instructions. These instructions are delivered as the package object. The instructions run automatically at installation if the package object belongs to the build class.
The name of the build class action script should be the same as the name of the file on which the instructions are executed. The name must also be executable by the sh command. The script's output becomes the new version of the file as it is built or modified. If the script produces no output, the file is not created or modified. Therefore, the script can modify or create the file itself.
For example, if a package delivers a default file, /etc/randomtable, and if the file does not already exist on the target system, the prototype file entry might be as follows:
e build /etc/randomtable ? ? ?
The package object, /etc/randomtable, might look like the following:
!install
# randomtable builder
if [ -f $PKG_INSTALL_ROOT/etc/randomtable ]; then
echo "/etc/randomtable is already in place.";
else
echo "# /etc/randomtable" > $PKG_INSTALL_ROOT/etc/randomtable
echo "1121554 # first random number" >> $PKG_INSTALL_ROOT/etc/randomtable
fi
!remove
# randomtable deconstructor
if [ -f $PKG_INSTALL_ROOT/etc/randomtable ]; then
# the file can be removed if it's unchanged
if [ egrep "first random number" $PKG_INSTALL_ROOT/etc/randomtable ]; then
rm $PKG_INSTALL_ROOT/etc/randomtable;
fi
fi
See Chapter 5, Case Studies of Package Creation for another example using the build class.
The preserve class preserves a package object file by determining whether or not an existing file should be overwritten when the package is installed. Two possible scenarios when using a preserve class script are:
If the file to be installed does not already exist in the target directory, the file will be installed normally.
If the file to be installed exists in the target directory, a message describing that the file exists is displayed, and the file is not installed.
Both scenario outcomes are considered successful by the preserve script. A failure occurs only in the second scenario when the file is unable to be copied to the target directory.
Starting with the Solaris 7 release, the i.preserve script and a copy of this script, i.CONFIG.prsv, can be found in the /usr/sadm/install/scripts directory with the other class action scripts.
Modify the script to include the filename or filenames you would like to preserve.
The manifest class automatically installs and uninstalls SMF (Service Management Facility) services associated with an SMF manifest. If you are not familiar with SMF, see Chapter 18, Managing Services (Overview), in System Administration Guide: Basic Administration for information about how to use SMF to manage services.
All service manifests within packages should be identified with the class manifest. Class action scripts that install and remove service manifests are included in the packaging subsystem. When pkgadd(1M) is invoked, the service manifest is imported. When pkgrm(1M) is invoked, instances in the service manifest that are disabled are deleted. Any services in the manifest that have no remaining instances are also deleted. If the -R option is supplied to pkgadd(1M) or pkgrm(1M), these service manifest actions will be done when the system is next rebooted with that alternate root path.
The following portion of code from a package information file shows the use of the manifest class.
# packaging files i pkginfo i copyright i depend i preinstall i postinstall i i.manifest i r.manifest # # source locations relative to the prototype file # d none var 0755 root sys d none var/svc 0755 root sys d none var/svc/manifest 0755 root sys d none var/svc/manifest/network 0755 root sys d none var/svc/manifest/network/rpc 0755 root sys f manifest var/svc/manifest/network/rpc/smserver.xml 0444 root sys
For example, assigning objects to an application and manpage class would look like the following:
f manpage /usr/share/man/manl/myappl.1l f application /usr/bin/myappl
For example, entries for the application and manpage classes would look like the following:
CLASSES=manpage application none
Note - The none class is always installed first and removed last, regardless of where it appears in the definition of the CLASSES parameter.
For example, an installation script for a class named application would be named i.application and a removal script would be named r.application.
Remember, when a file is part of a class that has a class action script, the script must install the file. The pkgadd command does not install files for which a class action script exists, although it does verify the installation. And, if you define a class but do not deliver a class action script, the only action taken for that class is to copy components from the installation medium to the target system (the default pkgadd behavior).
If you have not created your prototype file, complete the procedure How to Create a prototype File by Using the pkgproto Command, and skip to Step 7.
If you have already created your prototype file, edit it and add an entry for each installation script you just created.
See How to Build a Package, if needed.
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.
|