Appendix G Additional SVR4 Packaging Requirements (Reference)

This appendix is for system administrators who 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 avoids modifying the currently running system so you can upgrade with Solaris Live Upgrade.

Packaging Requirements Overview

The following documentation references provide background information on packaging requirements.

• 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 the 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 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 G–1 lists information that applies to either Solaris Live Upgrade or the custom JumpStart program in this document.

Custom JumpStart Program and Solaris Live Upgrade Inactive Boot Environment Requirements

An inactive boot environment 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

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

The following list explains the requirements for inactive boot environment compliance.

• For an installation of an operating system to be successful, packages must recognize and correctly respect inactive boot environment 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 are included in 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 G–2 provides examples of correct scripting syntax.

  Table G–2 Examples of Installation Script Syntax

  Script Type	Correct Syntax	Incorrect Syntax
  Bourne 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. The location is set to the -R argument of the pkgadd command. For example, if the following command is invoked, then $PKG_INSTALL_ROOT becomes /a during the installation of the package.

# pkgadd -R /a SUNWvxvm

$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 inactive boot environment, 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

The pkginfo file has a specification for $BASEDIR:

BASEDIR=/opt

If this package is installed with the following command, then ls is installed in /a/opt/sbin/ls, but ls2 is installed as /a/sbin/ls2.

# pkgadd -R /a SUNWtest

Solaris Live Upgrade Inactive 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. Four procedure scripts 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 inactive 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 inactive boot environment must not be modified except within the rules outlined in the section, Custom JumpStart Program and Solaris Live Upgrade Inactive Boot Environment 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 were added in the 2.6 and later releases. 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 of the umount command was added in the Solaris 7 release. To verify that a specific command or option is supported in the Solaris 2.6 release, see the Solaris 2.6 Reference Manual AnswerBook on http://docs.sun.com.

• All packages must pass pkgchk validation. After 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 in an inactive boot environment location using the -R dir_name option to pkgadd. After the package is installed, it 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, pkgadd -v, and pkgrm 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-$TEMPDIR access and shows only non-read-only access to paths that do not lie within the specified inactive boot environment.

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

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

Upgrade Compliance With the Custom JumpStart Program

Custom JumpStart program compliance ensures that packages can be added and removed while being part of the traditional Solaris installation utilities, which are the following:

• The custom JumpStart program

• Solaris suninstall program

• Solaris Web Start installation method

The custom JumpStart program compliance also ensures that the package can participate in Solaris upgrades. To be custom JumpStart program-compliant, a package also must follow inactive boot environment requirements that are outlined in Custom JumpStart Program and Solaris Live Upgrade Inactive Boot Environment Requirements.

To be able to use the custom JumpStart program effectively, packages must be added or removed without the user being prompted for information. To prevent user interaction, set up a new administration file with the pkgadd command -a option. The -a option defines an installation administration file to be used in place of the default administration file. Using the default file might result in the user being prompted for more information. You can create an administration file that indicates to pkgadd that it should bypass these checks and install the package without user confirmation. For details, see the man pages, admin(4) or pkgadd(1M).

The following examples show how to use the pkgadd administration file.

• If no administration file is provided, pkgadd uses /var/sadm/install/admin/default. Using this file might result in user interaction.

  # pkgadd

• If a relative administration file is provided on the command line, pkgadd looks in /var/sadm/install/admin for the file name and uses it. In this example, the relative administration file is named nocheck and pkgadd looks for /var/sadm/install/admin/nocheck.

  # pkgadd -a nocheck

• If an absolute file is provided pkgadd uses it. In this example, pkgadd looks in /tmp for the nocheck administration file.

  # pkgadd -a /tmp/nocheck

The following is an example of an installation administration file that requires very little user interaction with the pkgadd utility. Unless the package requires more space than is available on the system, the pkgadd utility uses this file and installs the package without prompting the user for more information.

mail=
instance=overwrite
partial=nocheck
runlevel=nocheck
idepend=nocheck
space=ask
setuid=nocheck
confiict=nocheck
action=nocheck
basedir=default