Additional SvR4 Packaging Requirements (Reference)

This appendix is for system administrators that need to use the custom JumpStart program or Solaris Live Upgrade to install or remove packages, especially third-party packages. Following these packaging requirements keeps a custom JumpStart installation non-interactive and keeps from modifying the currently running system so you can upgrade with Solaris Live Upgrade.

Note - An alternate root (/) is a copy of the operating environment, not the currently running system.

Packaging Requirements Overview

For the custom JumpStart program and Solaris Live Upgrade to work properly, packages must comply with the SvR4 packaging requirements. The Application Packaging Developer's Guide provides more specific information on packaging requirements and definitions of terminology, see especially this chapter: "Advanced Package Creation Techniques" in Application Packaging Developer's Guide.

For basic information on adding and removing packages and the installation administration file, see "Managing Software (Overview)" in the System Administration Guide: Basic Administration. Also see the specific man pages.

For detailed information on the commands referenced in this appendix, see the man pages, dircmp(1), fssnap(1M), ps(1), or truss(1).

Table C-1 lists information that applies to either Solaris Live Upgrade or the custom JumpStart program.

Table C-1 Requirements Information

Custom JumpStart Program and Solaris Live Upgrade Alternate Root (/) Requirements

An alternate root (/) is a copy of the operating environment, not the currently running system. A package to be used by Live Upgrade or the custom JumpStart program must follow these requirements:

• Enable a custom JumpStart installation or upgrade with no user interaction

• No modification of the current running system, which is necessary when using Solaris Live Upgrade

The following list explains the requirements for alternate root (/) compliance.

• For an installation of an operating system to be successful, packages must recognize and correctly respect alternate root (/) specifiers.

  Packages can include absolute paths in their pkgmap file (package map). If these files exist they are written relative to the -R option of the pkgadd command. Packages that contain both absolute and relative (relocatable) paths can be installed to an alternative root (/) as well. $PKG_INSTALL_ROOT is prepended to both absolute and relocatable files so all paths are resolved properly when being installed by pkgadd.

• Packages being installed using the pkgadd -R option or being removed using the pkgrm -R option, must not alter the currently running system.

  Any procedure scripts that come with the packages being installed with the pkgadd command -R option or being removed using the pkgrm command -R option, must not alter the currently running system. Any installation scripts that you provide, must reference any directory or file prefixed with the $PKG_INSTALL_ROOT variable. The package must write all directories and files with the $PKG_INSTALL_ROOT prefix. The package must not remove directories without a $PKG_INSTALL_ROOT prefix. Table C-2 provides examples of correct scripting syntax.

  Table C-2 Examples of Installation Script Syntax

  Script Type	Correct Syntax	Incorrect Syntax
  Borne shell "if" statement fragments	if [ -f ${PKG_INSTALL_ROOT}\ /etc/ myproduct.conf ] ; then	if [ -f /etc/myproduct.conf ]\ ; \ then
  Removing a file	/bin/rm -f ${PKG_INSTALL_ROOT}\ /etc/myproduct.conf	/bin/rm -f /etc/myproduct.conf
  Changing a file	echo "test=no" ${PKG_INSTALL_ROOT}\ /etc/myproduct.conf	echo "test=no"\ /etc/myproduct.conf

Differences Between $PKG_INSTALL_ROOT and $BASEDIR Overview

$PKG_INSTALL_ROOT is the location of the root (/) file system of the machine to which you are adding the package. This is set to the -R argument to the pkgadd command. For example, if the following command is invoked:

# pkgadd -R /a SUNWvxvm

Then $PKG_INSTALL_ROOT is prepended to /a during the installation of the package.

$BASEDIR points to the relocatable base directory into which relocatable package objects are installed. Only relocatable objects are installed here. Non-relocatable objects (those that have absolute paths in the pkgmap file) are always installed relative to the alternate root (/), but not relative to the $BASEDIR in effect. If a package has no relocatable objects, then the package is said to be an absolute package (or non-relocatable), and $BASEDIR is undefined and not available to package procedure scripts.

For example, suppose a package's pkgmap file has two entries:

1 f none sbin/ls 0555 root sys 3541 12322 1002918510
1 f none /sbin/ls2 0555 root sys 3541 12322 2342423332

And the pkginfo file has a specification for $BASEDIR:

BASEDIR=/opt

If this package is installed with the following command:

# pkgadd -R /a SUNWtest

Then ls is installed in /a/opt/sbin/ls, but ls2 is installed as /a/sbin/ls2.

Solaris Live Upgrade Alternate Boot Environment Compliance

When using Solaris Live Upgrade and creating a new boot environment, avoid problems by following these guidelines.

• Your package procedure scripts must be independent of the current active operating environment. Procedure scripts define actions that occur at particular points during package installation and removal. There are four procedure scripts that can be created with these predefined names: preinstall, postinstall, preremove, and postremove. Package procedure scripts must be independent of the currently active operating environment because an alternate boot environment could be switched by using Solaris Live Upgrade.

  • These scripts must not start or stop any processes or depend on the output of commands such as ps or truss, which are operating system dependent and report information about the currently running system.

  • Procedure scripts are free to use other standard UNIX commands such as expr, cp, and ls and other commands that facilitate shell scripting. But, the current alternate root (/) must not be modified except within the rules outlined in the section, "Custom JumpStart Program and Solaris Live Upgrade Alternate Root (/) Requirements".

  • All scripts must be written in bourne shell (/bin/sh). Bourne shell is the interpreter used by the pkgadd command to execute the procedure scripts.

  • Package procedure scripts must not invoke commands that do not exist in releases previous to the 2.6 release. For example, package procedure scripts cannot invoke the pgrep command. Since the 2.6 release, many commands have had additional features added. Package procedure scripts must not use any command options that did not exist in the 2.6 release. For example, the -f option is new to the umount command.

• All packages must pass pkgchk validation. Once a package is created and before it is installed, it must be checked with the following command.

  # pkgchk -d dir_name pkg_name

  dir_name	Specifies the name of the directory where the package resides
  pkg_name	Specifies the name of the package

  For example, if a package exists at /export/SUNWvxvm, then you would issue the following command.

  # pkgchk -d /export SUNWvxvm

  No errors should be displayed.

  After a package is created, it must be tested by installing it to an alternate root (/) location using the -R dir_name option to pkgadd. Once this is accomplished, the package must be checked for correctness using pkgchk, as in this example.

  # pkgadd -d . -R /a SUNWvxvm # pkgchk -R /a SUNWvxvm

  No errors should be displayed.

• Also, packages must not execute commands delivered by the package itself. This is to maintain diskless compatibility and avoids running commands that might require shared libraries that are not installed yet.

These requirements for creating, modifying and deleting files can be verified using a variety of commands. For example, the dircmp or fssnap commands can be used to verify that packages behave properly. Also, the ps command can be used for testing daemon compliance by making sure daemons are not stopped or started by the package. The truss and pkgadd commands can test runtime package installation compliance, but might not work in all situations. In the following example, the truss command strips out all read-only, non-$BASEDIR access and shows only non-read-only access to paths that do not lie within the specified alternate root (/).

# BASEDIR=/a; export BASEDIR
# truss -t open /usr/sbin/pkgadd -R ${BASEDIR} SUNWvxvm \
2>&1 > /dev/null | grep -v O_RDONLY | grep -v \
'open("'${BASEDIR}

For detailed information on the commands referenced in this section, see the man pages, dircmp(1), fssnap(1M), ps(1), or truss(1).