JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Solaris 11 Express Distribution Constructor Guide     Oracle Solaris 11 Express 11/10
search filter icon
search icon

Document Information

1.  Introduction to the Distribution Constructor

2.  Design and Build Oracle Solaris Images

System Requirements

Customize Your Image by Editing the Manifests

Modifying Manifest Contents

Further Customize an Image Using Finalizer Scripts

Creating Custom Finalizer Scripts

Characteristics of Finalizer Scripts

Using the Manifest Reader

Specifying Key-Value Pairs

Building an Image

Building an Image in One Step

Building an Image in Stages

Building an Image in Stages by Using Checkpoint Options

Troubleshooting the Distribution Constructor

I Get Error Messages When I Download a Package

How to Debug Manifests With Validation Errors

Debugging Semantic Validation Errors

Checking Data

Additional Installation Information

3.  x86: Design and Build a Virtual Machine

A.  Custom Finalizer Scripts, Examples

Further Customize an Image Using Finalizer Scripts

The distribution constructor enables you to specify scripts that can be used to make installation customizations based on the type of image you are building. These scripts are called finalizer scripts. The manifest files point to the finalizer scripts, and the finalizer scripts transform the generic image into a media-specific distribution. A set of default scripts are provided in the application packages.

The distribution constructor application includes default scripts in the /usr/share/distro_const directory and subdirectories. These scripts are referenced in the finalizer section of the manifest files.

For example, some of the default finalizer scripts that are used to create an x86 live CD, or “slim CD,” are listed in the following table.

Table 2-3 x86 Live CD Finalizer Scripts

Finalizer Script
Modifies image area for all types of images
Modifies image area, specifically for live CD image
Generates the list of files that are part of the live CD image
Initializes the boot archive
Configures the boot archive, specifically for the live CD image
Configures the boot archive
Archives the boot archive
Makes post-build modifications to the boot archive image area, specifically for live CD image
Initializes the Grub menu
Makes post-build modifications to the boot archive image area
Creates an ISO image
Creates a USB image

Creating Custom Finalizer Scripts

It is recommended that you use the supplied finalizer scripts without editing them. You do, however, have the option to write and add your own scripts to perform additional operations as described below. If you do create new scripts, edit the manifest files to point to these new scripts.

Note - Support for scripts is limited to the unmodified, default scripts that are supplied with the application packages. If you choose to customize these scripts, back up the original scripts first.

  1. Plan your new scripts. Use the existing scripts as models for new scripts. Review the Characteristics of Finalizer Scripts.

    See, also, the following sample custom scripts:

  2. Create your new scripts.

  3. Add your new scripts to either the /usr/local/ directory, your home directory, or elsewhere on the system or network. Make sure that the root role can execute these scripts.

  4. Add the new script names in the finalizer section of the appropriate manifest file. Be sure to specify the full path to your scripts in the manifest file, even if they are in the /usr/share/distro_const directory.

  5. When you add a reference for a new script in the finalizer section of a manifest file, you must specify a checkpoint name that is used to pause the image build before or after this script performs its task. Optionally, you can include a custom message associated with the checkpoint name. If this message is omitted, the path of the script is used as the default checkpoint message.

    Note - Use meaningful names for checkpoint names instead of using numbers. If new scripts are added, the new steps for those new scripts will disrupt a numbered checkpoint order.

    For example, the following reference in a manifest file specifies the checkpoint name of “ba-arch” for a boot archive archiving script, and the associated message is “Boot archive archiving.”

    <script name="/usr/share/distro_const/">
    <checkpoint name="ba-arch" message="Boot archive archiving"/>

    This example allows you to specify a distro_const command to build your image, pausing or resuming from the “ba-arch” checkpoint. The build will pause just before the boot archive archiving script performs its task.

    For instructions about how to refer to checkpoints in the distro_const command, see Building an Image in Stages.

Characteristics of Finalizer Scripts

When you create your own finalizer scripts, note the following:

Table 2-4 Finalizer Script Arguments

Server socket file name
The first argument is the manifest reader socket. This argument specifies the socket that is used with /usr/bin/ManifestRead for accessing the manifest data. See the section about Using the Manifest Reader.
Package image area path
The second argument is the PKG_IMG_PATH, which specifies the path to the area where the package image is created. Use this argument to locate a file in the package image area. The following example checks whether the user, “jack,” is in the package image area's password file.
/usr/bin/grep jack $PKG_IMG_PATH/etc/passwd >/dev/null
if [[ $? == "0" ]] ; then
   print "Found Jack"
Temp directory
The third argument specifies a directory that is used when creating temporary files needed during the build process. In the following example, you create a file in the temporary directory for building the boot archive.
/usr/sbin/mkfile $TMP_DIR/boot_archive_archive
/usr/sbin/lofiadm -a $TMP_DIR/boot_archive_archive 
Boot archive build area
The fourth argument is the boot archive build area, where the boot archive files are gathered. See the following example from the boot_archive_configure module, which adds the file, /etc/nodename, to the boot archive. This file gives the system the hostname, “solaris.”
BR_BUILD=$4      # Boot archive build area

# Set nodename to solaris
echo "solaris" > $BR_BUILD/etc/nodename
Media area
The fifth argument specifies where the finished media is deposited. In the following example, the create_iso script uses this argument to place the resultant ISO image.
Additional arguments
A list of additional arguments to be passed into a script is tagged in the manifest with the <argslist> tag. The first of these arguments is passed in as arg6. Enclose each list item in double-quotes. When no double-quotes are used, or if one set of double-quotes encloses the entire string, the entire string including spaces and newlines is interpreted as one argument. Do not use commas between arguments.

In the following example from the slim_cd_x86.xml manifest file, two additional arguments are passed to the boot_archive_configure script, as arg6 and arg7:


Another method for specifying additional arguments is to use key-value pairs. See the following section.

Using the Manifest Reader

The distribution constructor passes the manifest reader socket as the first argument into finalizer scripts. In a finalizer shell script, pass this argument as the first argument to /usr/bin/ManifestRead for accessing the manifest data. In a python module, pass this argument to instantiate a ManifestRead() object.

The following Shell script example calls ManifestRead to request the name item from the manifest file. ManifestRead returns zero or more items, each on its own line. If ManifestRead is given multiple items to search for, the lines returned contain both the item being searched for and a result.


VOLNAME=`/usr/bin/ManifestRead ${MFEST_SOCKET} "name"`
if [ "XX${VOLNAME}" == "XX" ] ; then
       print -u2 "$0: Error retrieving volume ID"
       exit 1

The following example shows how to make use of ManifestRead from a Python script:

from osol_install.ManifestRead import ManifestRead

# get the manifest reader object from the socket
manifest_reader_obj = ManifestRead(MFEST_SOCKET)

# get boot_archive compression type

BR_COMPR_TYPE = get_manifest_value(manifest_reader_obj,
if (BR_COMPR_TYPE == None):
       raise Exception, (sys.argv[0] +
           ": boot_archive compression type missing from manifest")
Specifying Key-Value Pairs

Another method for passing arguments into scripts is to specify a key-value pair. This method is useful for passing the same argument into multiple scripts without duplication. A script can access a keyed value by specifying the key to /usr/bin/ManifestRead from within the script. Provide the server socket as the first argument and then provide the node paths to the items whose values are needed, as in the following examples.

Example 2-1 Shell Script

The following example calls ManifestRead from a shell script to obtain a keyed value.

  /usr/bin/ManifestRead -k $MFEST_SOCKET iso_sort
  iso_sort_file=`/usr/bin/ManifestRead $MFEST_SOCKET iso_sort`

Example 2-2 Python Script

The following example calls ManifestRead from Python to obtain the same keyed value.

from osol_install.ManifestRead import ManifestRead

  IS_KEY = True

  iso_sort_file = manifest_reader_obj.get_values("iso_sort", IS_KEY)
  fd = open(iso_sort_file,....)