openSolaris 2008 - Specifying the Base Directory - Application Packaging Developer's Guide

Specifying the Base Directory

You can use several methods to specify where a package will be installed, and it is important to be able to change the installation base dynamically at install time. If this is accomplished correctly, an administrator can install multiple versions and multiple architectures without complications.

This section discusses common methods first, followed by approaches that enhance installations to heterogeneous systems.

The Administrative Defaults File

Administrators responsible for installing packages can use administration files to control package installation. However, as a package designer, you need to know about administration files and how an administrator can alter your intended package installation.

An administration file tells the pkgadd command whether to perform any of the checks or prompts that it normally does. Consequently, administrators should fully understand a package's installation process and the scripts involved before using administration files.

A basic administrative defaults file is shipped with the SunOS operating system in /var/sadm/install/admin/default. This is the file that establishes the most basic level of administrative policy as regards the installation of software products. The file looks like this as shipped:

#ident "@(#)default
1.4 92/12/23 SMI"    /* SVr4.0 1.5.2.1    */ 
mail=
instance=unique
partial=ask
runlevel=ask
idepend=ask
rdepend=ask
space=ask
setuid=ask
conflict=ask
action=ask
basedir=default

The administrator may edit this file to establish new default behaviors, or create a different administration file and specify its existence by using the -a option to the pkgadd command.

Eleven parameters can be defined in an administration file, but not all need to be defined. For more information, see admin(4).

The basedir parameter specifies how the base directory will be derived when a package is installed. Most administrators leave this as default, but basedir can be set to one of the following:

ask, which means always ask the administrator for a base directory
An absolute path name
An absolute path name containing the $PKGINST construction, which means always install to a base directory derived from the package instance

Note - If the pkgadd command is called with the argument -a none, it always asks the administrator for a base directory. Unfortunately, this also sets all parameters in the file to the default value of quit, which can result in additional problems.

Becoming Comfortable With Uncertainty

An administrator has control over all packages being installed on a system by using an administration file. Unfortunately, an alternate administrative defaults file is often provided by the package designer, bypassing the wishes of the administrator.

Package designers sometimes include an alternate administration file so that they, not the administrator, control a package's installation. Because the basedir entry in the administrative defaults file overrides all other base directories, it provides a simple method for selecting the appropriate base directory at install time. In all versions of the Solaris operating environment prior to the Solaris 2.5 release, this was considered the simplest method for controlling the base directory.

However, it is necessary for you to accept the administrator's desires regarding the installation of the product. Providing a temporary administrative defaults file for the purpose of controlling the installation leads to mistrust on the part of administrators. You should use a request script and checkinstall script to control these installations under the supervision of the administrator. If the request script faithfully involves the administrator in the process, System V packaging will serve both administrators and package designers.

Using the `BASEDIR` Parameter

The pkginfo file for any relocatable package must include a default base directory in the form of an entry like this:

BASEDIR=absolute_path

This is only the default base directory; it can be changed by the administrator during installation.

While some packages require more than one base directory, the advantage to using this parameter to position the package is because the base directory is guaranteed to be in place and writable as a valid directory by the time installation begins. The correct path to the base directory for the server and client is available to all procedure scripts in the form of reserved environment variables, and the pkginfo -r SUNWstuf command displays the current installation base for the package.

In the checkinstall script, BASEDIR is the parameter exactly as defined in the pkginfo file (it has not been conditioned yet). In order to inspect the target base directory, the ${PKG_INSTALL_ROOT}$BASEDIR construction is required. This means that the request or checkinstall script can change the value of BASEDIR in the installation environment with predictable results. By the time the preinstall script is called, the BASEDIR parameter is the fully conditioned pointer to the actual base directory on the target system, even if the system is a client.

Note - The request script utilizes the BASEDIR parameter differently for different releases of the SunOS operating system. In order to test a BASEDIR parameter in a request script, the following code should be used to determine the actual base directory in use.

# request script
constructs base directory
if [ ${CLIENT_BASEDIR} ]; then
      LOCAL_BASE=$BASEDIR
else
      LOCAL_BASE=${PKG_INSTALL_ROOT}$BASEDIR
fi

Using Parametric Base Directories

If a package requires multiple base directories, you can establish them with parametric path names. This method has become quite popular, although it has the following drawbacks.

A package with parametric path names usually behaves like an absolute package but is treated by the pkgadd command like a relocatable package. The BASEDIR parameter must be defined even if it is not used.
The administrator cannot ascertain the installation base for the package using the System V utilities (the pkginfo -r command will not work).
The administrator cannot use the established method to relocate the package (it is called relocatable but it acts absolute).
Multiple architecture or multiple version installations require contingency planning for each of the target base directories which often means multiple complex class action scripts.

While the parameters that determine the base directories are defined in the pkginfo file, they may be modified by the request script. That is one of the primary reasons for the popularity of this approach. The drawbacks, however are chronic and you should consider this configuration a last resort.

Examples—Using Parametric Base Directories

The `pkginfo` File

# pkginfo file
PKG=SUNWstuf
NAME=software stuff 
ARCH=sparc
VERSION=1.0.0,REV=1.0.5
CATEGORY=application
DESC=a set of utilities that do stuff
BASEDIR=/
EZDIR=/usr/stuf/EZstuf
HRDDIR=/opt/SUNWstuf/HRDstuf
VENDOR=Sun Microsystems, Inc.
HOTLINE=Please contact your local service provider
EMAIL=
MAXINST=1000
CLASSES=none
PSTAMP=hubert980707141632

The `pkgmap` File

: 1 1758
1 d none $EZDIR 0775 root bin
1 f none $EZDIR/dirdel 0555 bin bin 40 773 751310229
1 f none $EZDIR/usrdel 0555 bin bin 40 773 751310229
1 f none $EZDIR/filedel 0555 bin bin 40 773 751310229
1 d none $HRDDIR 0775 root bin
1 f none $HRDDIR/mksmart 0555 bin bin 40 773 751310229
1 f none $HRDDIR/mktall 0555 bin bin 40 773 751310229
1 f none $HRDDIR/mkcute 0555 bin bin 40 773 751310229
1 f none $HRDDIR/mkeasy 0555 bin bin 40 773 751310229
1 d none /etc    ? ? ?
1 d none /etc/rc2.d ? ? ?
1 f none /etc/rc2.d/S70dostuf 0744 root sys 450 223443
1 i pkginfo 348 28411 760740163
1 i postinstall 323 26475 751309908
1 i postremove 402 33179 751309945
1 i preinstall 321 26254 751310019
1 i preremove 320 26114 751309865

Managing the Base Directory

Any package that is available in multiple versions or for multiple architectures should be designed to walk the base directory, if needed. Walking a base directory means that if a previous version or a different architecture of the package being installed already exists in the base directory, the package being installed resolves this issue, perhaps by creating a new base directory with a slightly different name. The request and checkinstall scripts in the Solaris 2.5 and compatible releases have the ability to modify the BASEDIR environment variable. This is not true for any prior version of the Solaris operating environment.

Even in older versions of the Solaris operating environment, the request script had the authority to redefine directories within the installation base. The request script can do this in a way that still supports most administrative preferences.