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

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.

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:

   • Sample Script for Adding Packages to an Image

   • Sample Script for Testing Alternate Packages

   • Sample Script for Adding an SVR4 Package to an Image

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/boot_archive_archive.py">
   <checkpoint name="ba-arch" message="Boot archive archiving"/>
   </script>

   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:

• Scripts can be Python programs, shell scripts, or binaries.

• Scripts are executed in the order that they are listed in the manifest file.

• Standard output (stdout) and error output (stderr) of commands executed within finalizer scripts (both shell and python modules) are captured in the log files. stderr is captured in the simple log. Both stdout and stderr are captured in the detail log.

• The distribution constructor passes five initial arguments to all scripts that are executed. These five arguments are not included as entries in the manifest file. The manifest file specifies additional arguments passed in after these five arguments. The initial arguments are as follows.

Table 2-4 Finalizer Script Arguments

PKG_IMG_PATH=$2
/usr/bin/grep jack $PKG_IMG_PATH/etc/passwd >/dev/null
if [[ $? == "0" ]] ; then
   print "Found Jack"
fi 

TMP_DIR=$3
/usr/sbin/mkfile $TMP_DIR/boot_archive_archive
/usr/sbin/lofiadm -a $TMP_DIR/boot_archive_archive 

BR_BUILD=$4      # Boot archive build area

# Set nodename to solaris
echo "solaris" > $BR_BUILD/etc/nodename

MEDIA_DIR=$5
...
DIST_ISO=${MEDIA_DIR}/${DISTRO_NAME}.iso
... 

<argslist>
     "/usr/share/distro_const/slim_cd/slimcd_generic_live.xml"
     ".livecd"
</argslist>

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.

MFEST_SOCKET=$1

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

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,
   "img_params/output_image/boot_archive/compression/type")
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.

...
  MFEST_SOCKET=$1
  ...
  /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,....)