This chapter describes how to create optional information files and installation scripts for a package. While Chapter 2, Building a Package discussed the minimum requirements for making a package, this chapter discusses additional functionality that you can build into a package, based on the criteria you considered when planning how to design your package (for more information, see Things to Think About Before Building a Package).
This is a list of the overview information in this chapter.
The table below lists and describes the optional features you can build into a package.
Table 3–1 Creating Information Files and Installation Scripts Task Map
Task |
Description |
For Instructions, Go To ... |
---|---|---|
1. Create Information Files |
Define Package Dependencies A definition of package dependencies allows you to specify whether your package is compatible with previous versions, dependent on other packages, or whether other packages are dependent on yours. | |
Provide a Copyright Message A copyright file provides legal protection for your software application. | How to Write a Copyright Message | |
Create Additional Space on the Target System. A space file sets aside blocks on the target system, which enables you to create files during installation that are not defined in the pkgmap file. | How to Reserve Additional Space on a Target System | |
2. Create Installation Scripts |
Obtain Information From the Installer A request script enables you to obtain information from the person installing your package. | |
Gather File System Data Needed For Installation A checkinstall script enables you to perform an analysis of the target system and set up the correct environment for, or cleanly halt, the installation. | ||
Write Procedure Scripts Enables you to provide customized installation instructions during specific phases of the installation or removal process. | ||
Write Class Action Scripts Enables you to specify a set of instructions to be executed during package installation and removal on specific groups of package objects. |
This section discusses optional package information files. With these files you can define package dependencies, provide a copyright message, and reserve additional space on a target system.
You need to determine whether your package has dependencies on other packages and if any other packages depend on yours. Package dependencies and incompatibilities can be defined with two of the optional package information files, compver and depend. Delivering a compver file lets you name previous versions of your package that are compatible with the one being installed. Delivering a depend file lets you define three types of dependencies associated with your package. These dependency types are:
A prerequisite package – meaning your package depends on the existence of another package
A reverse dependency – meaning another package depends on the existence of your package
Use the reverse dependency type only when a package that cannot deliver a depend file relies on your package.
An incompatible package – meaning your package is incompatible with the named package
The depend file resolves only very basic dependencies. If your package depends upon a specific file or its contents or behavior, the depend file does not supply adequate precision. In this case, a request script or the checkinstall script should be used for detailed dependency checking. The checkinstall script is also the only script capable of cleanly halting the package installation process.
Be certain that your depend and compver files have entries in the prototype file. The file type should be i (for package information file).
Refer to depend(4) and compver(4) for more information.
Make the directory containing your information files the current working directory.
If previous versions of your package exist and you need to specify that your new package is compatible with them, create a file named compver with your favorite text editor.
List the versions with which your package is compatible, using this format:
string string . . . |
string |
Is identical to the value assigned
to the |
Save your changes and quit the editor.
If your package depends on the existence of other packages, other packages depend on the existence of your package, or your package is incompatible with another package, create a file named depend with your favorite text editor.
Add an entry for each dependency, using this format:
type pkg-abbrev pkg-name (arch) version (arch) version . . . |
type |
Defines the dependency type. Must be one of the following characters: P (prerequisite package), I (incompatible package), or R (reverse dependency). |
pkg-abbrev |
Specifies the package abbreviation, such as SUNWcadap. |
pkg-name |
Specifies the full package name, such as Chip designers need CAD application software to design abc chips. Runs only on xyz hardware and is installed in the usr partition. |
(arch) |
Optional. Specifies the type of hardware on which the package runs. For example, sparc or x86. If you specify an architecture, you must use the parentheses as delimiters. |
version |
Optional. Specifies the value assigned
to the |
For more information, see depend(4).
Save your changes and quit the editor.
Complete one of the following tasks:
If you want to create additional information files and installation scripts, skip to the next task, How to Write a Copyright Message.
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 7.
If you have already created your prototype file, edit it and add an entry for each file you just created.
Build your package.
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.
In this example, there are four versions of a package: 1.0, 1.1, 2.0, and the new package, 3.0, which is compatible with all the three previous versions. The compver file for the newest version might look like:
release 3.0 release 2.0 version 1.1 1.0 |
The entries do not have to be in sequential order. However, they
should exactly match the definition of the VERSION
parameter in each package's pkginfo
file. In this example, the package designers used different formats in the
first three versions.
This example assumes that the sample package, SUNWcadap, requires that the SUNWcsr and SUNWcsu packages already be installed on a target system. The depend file for SUNWcadap looks like:
P SUNWcsr Core Solaris, (Root) P SUNWcsu Core Solaris, (Usr) |
You need to decide whether your package should display a copyright message while it is being installed. If so, create the copyright file.
You should include a copyright file to provide legal protection for your software application. It might be a good idea to check with the legal department of your company for the exact wording of the message.
To deliver a copyright message, you must create a file named copyright. During installation, the message is displayed exactly as it appears in the file (with no formatting). See copyright(4) for more information.
Be certain that your copyright file has an entry in the prototype file. Its file type should be i (for package information file).
Make the directory containing your information files the current working directory.
Create a file named copyright with your favorite text editor.
Enter the text of the copyright message exactly as you want it to appear as your package is installed.
Save your changes and quit the editor.
Complete one of the following tasks.
If you want to create additional information files and installation scripts, skip to the next task, How to Reserve Additional Space on a Target System.
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 information file you just created.
Build your package.
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.
For example, a partial copyright message might look like:
Copyright (c) 1999 Company Name All Rights Reserved This product is protected by copyright and distributed under licenses restricting copying, distribution and decompilation. |
You need to determine whether your package needs additional disk space on the target system (space in addition to that required by the package objects). If so, create the space information file. This is different than creating empty files and directories at installation time as discussed in Defining Additional Objects to Be Created at Install Time.
While the pkgadd command ensures that there is enough disk space to install your package based on the object definitions in the pkgmap file, a package may require additional disk space beyond that needed by the objects defined in the pkgmap file. For example, your package might create a file after installation, which may contain a database, log files, or some other growing file that consumes disk space. To be sure that there is space set aside for it, you should include a space file specifying the disk space requirements. The pkgadd command checks for the additional space specified in a space file. Refer to space(4) for more information.
Be certain that your space file has an entry in the prototype file. Its file type should be i (for package information file).
Make the directory containing your information files the current working directory.
Create a file named space with your favorite text editor.
Enter any additional disk space requirements needed by your package, using this format:
pathname blocks inodes |
pathname |
Specifies a directory name, which may or may not be the mount point for a file system. |
blocks |
Specifies the number of 512-byte blocks that you want reserved. |
inodes |
Specifies the number of required inodes. |
For more information, see space(4).
Save your changes and quit the editor.
Complete one of the following tasks.
If you want to create installation scripts, skip to the next task, How to Write a request Script.
If you have not created your prototype file, complete the procedure in 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 information file you just created.
Build your package.
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.
This example space file specifies that 1000 512-byte blocks and 1 inode be set aside in /opt on the target system.
/opt 1000 1 |
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 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 or not the installation proceeds.
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 or 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 is the only point at which your package can solicit input from the administrator 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 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 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, its output (a list of environment variables) is retained in the installed package and made available to removal scripts.
The following groups of environment variables are available to all installation scripts. Some of the environment variables can be modified by a request or checkinstall script.
The request or 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 pkginfo(4).
The BASEDIR
parameter
can only be modified starting with the Solaris 2.5 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 or 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 table below lists environment variables that are available to all installation scripts through the environment. None of these can be modified by a script.
Table 3–2 Package Environment Variables Available to Scripts
Environment Variable |
Description |
---|---|
|
The base directory with respect to the target system. While |
|
The directory where the package now being read is located. If the package is being read from a tape, this will be the location of a temporary directory where the package has been transferred into directory format. In other words, assuming there is no extension to the package name (for example, SUNWstuff.d), the request script for the current package would be found at $INST_DATADIR/$PKG/install. |
|
The
search list used by sh to find commands on script invocation. |
|
The instance identifier of the package being installed. If another instance of the package is not already installed, the value is the package abbreviation (for example, SUNWcadap). Otherwise, it is the package abbreviation followed by a suffix, such as SUNWcadap.4. |
|
The directory where files can be saved for use by removal scripts or where previously saved files can be found. Available only in the Solaris 2.5 and compatible releases. |
|
The root file system on the target system where the package is being installed. It exists only if the pkgadd and pkgrm commands were invoked with the -R option. This conditional existence facilitates its use in procedure scripts in the form ${PKG_INSTALL_ROOT}/somepath. |
|
Is an environment variable that gets set if the pkgadd and pkgrm commands were invoked with the -M and -R options. This environment variable is passed to any package installation script or package command that is part of the package environment. |
|
This environment variable does not exist under most installation environments. If it does exist (with the value yes), it means that a package with the same name, version, and architecture is already installed on the system or that this package is overwriting an installed package of the same name at the direction of the administrator. In these events, the original base directory is always used. |
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 pkginfo(1), pkgparam(1), 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–3 Installation Script Exit Codes
Code |
Meaning |
---|---|
0 |
Successful completion of script. |
1 |
Fatal error. Installation process is terminated at this point. |
2 |
Warning or possible error condition. Installation continues. A warning message is displayed at the time of completion. |
3 |
The pkgadd command is cleanly halted. Only the checkinstall script returns this code. |
10 |
System should be rebooted when installation of all selected packages is completed. (This value should be added to one of the single-digit exit codes described above.) |
20 |
System should be rebooted immediately upon completing installation of the current package. (This value should be added to one of the single-digit exit codes described above.) |
See Chapter 5, Package Creation Case Studies for examples of exit codes returned by installation scripts.
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 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.
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.
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.
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.
If it is possible that the administrators who will be installing your package will be using the JumpStartTM 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).
Make the directory containing your information files the current working directory.
Create a file named request with your favorite text editor.
Save your changes and quit the editor when you are done.
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.
Build your package.
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.
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 ! |
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.
The checkinstall script is available starting with the Solaris 2.5 and compatible releases.
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.
There can be only one checkinstall script per package and it 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 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.
Make the directory containing your information files the current working directory.
Create a file named checkinstall with your favorite text editor.
Save your changes and quit the editor when you are done.
Complete one of the following tasks.
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 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.
Build your package.
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.
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 |
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, and 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 since 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 postinstall and postremove scripts may install package objects in this way. See installf(1M) and Chapter 5, Package Creation Case Studies 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 removef(1M) and Chapter 5, Package Creation Case Studies for details and examples.
The installf and removef commands must be used because procedure scripts are not automatically associated with any path names listed in the pkgmap file.
Make the directory containing your information files the current working directory.
Create one or more procedure scripts with your favorite text editor.
A procedure script must be named one of the predefined names: preinstall, postinstall, preremove, or postremove.
Save your changes and quit the editor.
Complete one of the following tasks.
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 Using the pkgproto Command, and 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.
Build your package.
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.
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).
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. The reason for this is
to ensure that the directories are created before the objects they will contain
and also to ensure that no attempt is made to delete a directory before it
has been emptied.
The following list 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 will operate. 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 and 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 belonging to the associated class.
If the attempt to create the package object fails, 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 they will be 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.
If there is a class action script, the script is executed.
The class action script is invoked with standard input containing the list generated in item 1. If this is the last volume of the package, or there are no more objects in this class, the script is executed with the single argument of ENDOFCLASS.
Even if there are no regular files of this class anywhere in the package, the class action script will be 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 that 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 list 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 (meaning the file should be edited upon installation or removal).
If the package being removed modified any files of type e during installation, it should remove just the lines it added. Do not delete a non-empty editable file; just remove the lines the package added.
If there is no class action script, 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.
Files with a file type of e (editable), which are not assigned to a class and an associated class action script, will be removed at this point, even if the path name is shared with other packages.
If there is a class action script, the script is executed.
The pkgrm command invokes the class action script with standard input for the script containing the list generated in item 1.
The pkgrm command performs an audit.
After successfully executing the class action script, the pkgrm command removes knowledge of 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, Package Creation Case Studies 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 removal. The two name formats are as follows:
Name Format |
Description |
---|---|
i.class |
Operates on path names in the indicated class during package installation. |
r.class |
Operates on path names in the indicated class during package removal. |
For example, the name of the installation script for a class named manpage would be i.manpage and the removal script would be named r.manpage.
This file name format is not used for files belonging 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 (for example, floppy disk).
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 are found belonging to that class), the class action script will be 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 belonging 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 Installation.
When your script sees the ENDOFCLASS argument, put post-processing actions (like clean up) into your script.
All administrator interaction is restricted to the request script. Do not try to obtain information from the administrator using a class action script.
The system provides four special classes. They are:
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 using Bourne shell commands.
The preserve class
Provides a method to preserve files that should not be overwritten by future package installations.
If there are several files in a package that require special processing that can be fully defined through sed, awk, or sh commands, installation will be 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 belonging 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 will be executed.
A sed class action script delivers sed instructions in the format shown in the figure below.
# comment, which may appear on any line in the file !install # sed(1) instructions which will be invoked during # installation of the object [address [,address]] function [arguments] . . . !remove # sed(1) instructions to be invoked during the removal process [address [,address]] function [arguments] |
Two commands indicate when instructions should be executed. The sed instructions that follow the !install command are executed during package installation and those that follow the !remove command are executed during package removal. It does not matter which order these commands are used in the file.
For more information on sed instructions, see sed(1). For examples of sed class action scripts, see Chapter 5, Package Creation Case Studies.
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 belonging to class awk exists. Such a file contains instructions for the awk class script in the format shown in the figure below.
# comment, which may appear on any line in the file !install # awk(1) program to install changes . . . (awk program) !remove # awk1(1) program to remove changes . . . (awk program) |
Two commands indicate when instructions should be executed. The awk instructions that follow the !install command are executed during package installation, and those that follow the !remove command are executed during package removal. It does not matter in which order these commands are used in the file.
The name of the awk class action script should be the same as the name of the file on which the instructions will be executed.
The file to be modified is used as input to awk 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 awk(1).
The build class creates or modifies a package object file by executing Bourne shell instructions. These instructions are delivered as the package object, which runs automatically at installation if it 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 will be executed, and must 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 will not be 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:
e build /etc/randomtable ? ? ? |
and the package object, /etc/randomtable, might look like this:
!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, Package Creation Case Studies 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 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, when in the second scenario, 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.
Make the directory containing your information files the current working directory.
Assign the package objects in the prototype file the desired class names. For example, assigning objects to an application and manpage class would look like:
f manpage /usr/share/man/manl/myappl.1l f application /usr/bin/myappl |
Modify the CLASSES
parameter
in the pkginfo file to contain the class names you want
to use in your package. For example, entries for the application and manpage classes would look like:
CLASSES=manpage application none |
The none class is always installed first and
removed last, regardless of where it appears in the definition of the CLASSES
parameter.
If you are a creating class action script for a file belonging to the sed, awk, or build class, make the directory containing the package object your current working directory.
Create the class action scripts or package objects (for files belonging to the sed, awk, or build class). 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).
Complete one of the following tasks.
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 7.
If you have already created your prototype file, edit it and add an entry for each installation script you just created.
Build your package.
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.
The process of creating signed packages involves a number of steps and requires some comprehension of new concepts and terminology. This section provides information about signed packages, its terminology, and information about certificate management. This section also provides step-by-step procedures about how to create a signed package.
A signed package is a normal stream-format package that has a digital signature (PEM-encoded PKCS7 digital signature which is defined below) that verifies the following:
The package came from the entity who signed it
The entity indeed signed it
The package has not been modified since the entity signed it
The entity who signed it is a trusted entity
A signed package is identical to an unsigned package, except for the signature. A signed package is binary-compatible with an unsigned package. Therefore, a signed package can be used with older versions of the packaging tools. However, the signature is ignored in this case.
The signed packaging technology introduces some new terminology and abbreviations, which are described in the following table.
Before creating a signed package, you must have a package keystore. This package keystore contains certificates in the form of objects. Two types of objects exist in a package keystore:
A trusted certificate contains a single public key certificate that belongs to another entity. The trusted certificate is named as such because the keystore owner trusts that the public key in the certificate indeed belongs to the identity indicated by the “subject” (owner) of the certificate. The issuer of the certificate vouches for this trust by signing the certificate.
Trusted certficates are used when verifying signatures and when initiating a connection to a secure (SSL) server.
A user key holds sensitive cryptographic key information. This information is stored in a protected format to prevent unauthorized access. A user key consists of both the user's private key and the public key certificate that corresponds to the private key.
User keys are used when creating a signed package.
By default, the package keystore is stored in the /var/sadm/security directory. Individual users can also have their own keystore stored by default in the $HOME/.pkg/security directory.
On disk, a package keystore can be in two formats: a multiple-file format and a single-file format. A multiple-file format stores its objects in multiple files. Each type of object is stored in a separate file. All of these files must be encrypted using the same passphrase. A single-file keystore stores all of its objects in a single file on the file system.
The primary utility used to manage the certificates and the package keystore is the pkgadm command. The following subsections describe the more common tasks used for managing the package keystore.
A trusted certficate can be added to the package keystore using the pkgadm command. The certificate can be in PEM or DER format. For example:
$ pkgadm addcert -t /tmp/mytrustedcert.pem |
In this example, the PEM format certificate called mytrustedcert.pem is added to the package keystore.
The pkgadm command does not generate user certificates or private keys. User certificates and private keys are normally obtained from a Certificate Authority, such as Verisign. Or, they are generated locally as a self-signed certificate. Once the key and certificate are obtained, they can be imported into the package keystore using the pkgadm command. For example:
pkgadm addcert -n myname -e /tmp/myprivkey.pem /tmp/mypubcert.pem |
In this example, the following options are used:
-n myname |
Identifies the entity (myname) in the package keystore on which you wish to operate. The myname entity becomes the alias under which the objects are stored. |
-e /tmp/myprivkey.pem |
Specifies the file that contains the private key. In this case, the file is myprivkey.pem, which is located in the /tmp directory. |
/tmp/mypubcert.pem |
Specifies the PEM format certificate file called mypubcert.pem. |
The pkgadm command is also used to view the contents of the package keystore. For example:
$ pkgadm listcert |
This command displays the trusted certificates and private keys in the package keystore.
The pkgadm command can be used to delete trusted certificates and private keys from the package keystore.
When you delete user certificates, the alias of the certificate/key pair must be specified. For example:
$ pkgadm removecert -n myname |
The alias of the certificate is the common name of the certificate, which can be identified using the pkgadm listcert command. For example, this command deletes a trusted certificate entitled Trusted CA Cert 1:
$ pkgadm removecert -n "Trusted CA Cert 1" |
If you have both a trusted certificate and a user certificate stored using the same alias, they are both deleted when you specify the -n option.
The process of creating signed packages involves three basic steps:
Creating an unsigned, directory-format package.
Importing the signing certificate, CA certificates, and private key into the package keystore.
Signing the package from Step 1 with the certificates from Step 2.
The packaging tools do not create certificates. These certificates must be obtained from a Certificate Authority, such as Verisign or Thawte.
Each step for creating signed packages is described in the following procedures.
The procedure for creating an unsigned, directory-format package is the same as the procedure for creating a normal package, as previously described in this manual. The following procedure describes the process of creating this unsigned, directory-format package. If you need more information, refer to the previous sections about building packages.
The pkginfo file should have the following basic content:
PKG=SUNWfoo BASEDIR=/ NAME=My Test Package ARCH=sparc VERSION=1.0.0 CATEGORY=application |
The prototye file should have the following basic content:
$cat prototype i pkginfo d none usr 0755 root sys d none usr/bin 0755 root bin f none usr/bin/myapp=/tmp/myroot/usr/bin/myapp 0644 root bin |
List the contents of the object source directory.
For example:
$ ls -lR /tmp/myroot |
The output would appear similar to the following:
/tmp/myroot: total 16 drwxr-xr-x 3 abc other 177 Jun 2 16:19 usr /tmp/myroot/usr: total 16 drwxr-xr-x 2 abc other 179 Jun 2 16:19 bin /tmp/myroot/usr/bin: total 16 -rw------- 1 abc other 1024 Jun 2 16:19 myapp |
Create the unsigned package.
pkgmk -d `pwd` |
The output would appear similar to the following:
## Building pkgmap from package prototype file. ## Processing pkginfo file. WARNING: parameter <PSTAMP> set to "syrinx20030605115507" WARNING: parameter <CLASSES> set to "none" ## Attempting to volumize 3 entries in pkgmap. part 1 -- 84 blocks, 7 entries ## Packaging one part. /tmp/SUNWfoo/pkgmap /tmp/SUNWfoo/pkginfo /tmp/SUNWfoo/reloc/usr/bin/myapp ## Validating control scripts. ## Packaging complete. |
The package now exists in the current directory.
The certificate and private key to be imported must exist as a PEM- or DER-encoded X.509 certificate and private key. In addition, any intermediate or “chain” certificates linking your signing certificate to the Certificate Authority certificate must be imported into the package keystore before a package can be signed.
Each Certificate Authority can issue certificates in various formats. To extract the certificates and private key out of the PKCS12 file and into a PEM-encoded X.509 file (suitable for importing into the package keystore), use a freeware conversion utility such as OpenSSL.
If your private key is encrypted (which should usually be the case), you are prompted for the passphrase. Also, you are prompted for a password to protect the resulting package keystore. You can optionally not supply any password, but doing so results in an unencrypted package keystore.
The following procedure describes how to import the certificates using the pkgadm command once the certificate is in the proper format.
Import all the Certificate Authority certificates found in your PEM- or DER-encoded X.509 certificate file.
For example, to import all the Certificate Authority certificates found in the file ca.pem, you would type the following:
$ pkgadm addcert -k ~/mykeystore -ty ca.pem |
The output would appear similar to the following:
Trusting certificate <VeriSign Class 1 CA Individual \ Subscriber-Persona Not Validated> Trusting certificate </C=US/O=VeriSign, Inc./OU=Class 1 Public \ Primary Certification Authority Type a Keystore protection Password. Press ENTER for no protection password (not recommended): For Verification: Type a Keystore protection Password. Press ENTER for no protection password (not recommended): Certificate(s) from <ca.pem> are now trusted |
In order to import your signing key into the package keystore, you must supply an alias that is used later when signing the package. This alias can also be used if you want to delete the key from the package keystore.
For example, to import your signing key from the file sign.pem, you would type the following:
$ pkgadm addcert -k ~/mykeystore -n mycert sign.pem |
The output would appear similar to the following:
Enter PEM passphrase: Enter Keystore Password: Successfully added Certificate <sign.pem> with alias <mycert> |
Verify that the certificates are in the package keystore.
For example, to view the certificates in the keystore created in the previous step, you would type the following:
$ pkgadm listcert -k ~/mykeystore |
Once the certificates are imported into the package keystore, you can now sign the package. The actual signing of the package is done using the pkgtrans command.
Sign the package using the pkgtrans command. Supply the location of the unsigned package and the alias of the key to sign the package.
For example, using the examples from the previous procedures, you would type the following to create a signed package called SUNWfoo.signed:
$ pkgtrans -g -k ~/mykeystore -n mycert . ./SUNWfoo.signed SUNWfoo |
The output of this command would appear similar to the following:
Retrieving signing certificates from keystore </home/user/mykeystore> Enter keystore password: Generating digital signature for signer <Test User> Transferring <SUNWfoot> package instance |
The signed package is created in the file SUNWfoo.signed and is in the package-stream format. This signed package is suitable for copying to a web site and being installed using the pkgadd command and a URL.