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

3.  x86: Design and Build a Virtual Machine

A.  Custom Finalizer Scripts, Examples

Sample Script for Adding Packages to an Image

Using Custom Scripts

Adding Script to Manifest

Running the Script

Sample Script for Testing Alternate Packages

Sample Script for Adding an SVR4 Package to an Image

Sample Script for Adding Packages to an Image

When putting together an image, you can experiment with how an image works when packages are added or removed from a working set. This type of experimentation is supported by the distribution constructor. Additional packages can be added to the existing list in the package section of a manifest file. And, packages that you want to remove can be added to the post_install_remove_package section. After you have made your modifications to the manifest file to add or remove packages, you need to restart the build process from the beginning, and download all the packages again. That can take time. You can make these modifications more rapidly by using finalizer scripts.

The following custom script adds an IPS package to the image from an alternate repository specified in the manifest file. The package is added to the package image area. The name of the package to add is included in the script. This example also demonstrates how to use the ManifestRead program to obtain values from the manifest file.

Example A-1 Sample Script for Adding Packages

# Name:
# add_my_pkg
# Description:
# This script will add the package SUNWcdrw from
# the alternate repository specified in the manifest
# at pkg_repo_addl_authority.
# Args:
#   5 arguments are passed in by default from the DC.
#   MFEST_SOCKET: Socket needed to get manifest data via ManifestRead object
#   PKG_IMG_PATH: Package image area
#   TMP_DIR: Temporary directory 
#   BR_BUILD: Area where boot archive is put together (not used in this example)
#   MEDIA_DIR: Area where the media is put (not used)
# ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

if [ "$#" != "5" ] ; then
        print -u2 "Usage: $0: Requires 5 args:"
        print -u2 "    Reader socket, pkg_image area, tmp dir,"

        print -u2 "    boot archive build area, media area"
        exit 1


if [ ! -d $PKG_IMG_PATH ] ; then
        print -u2 "$0: Image package area $PKG_IMG_PATH is not valid"
        exit 1


#Install this package 

# You would have specified the additional repository like this in the manifest
#   <pkg_repo_addl_authority>
#        <main url="http://localhost:10000" authname="localtest"/>
#   </pkg_repo_addl_authority>

# Get the alternate repository URL from the manifest
add_url=/usr/bin/ManifestRead ${MFEST_SOCKET} \

# Get the alternate repository authority from the manifest
add_auth=/usr/bin/ManifestRead ${MFEST_SOCKET} \


# Check if authority is already set in the package image area
# if not, add it in
${PKGCMD} -R $PKG_IMG_PATH authority $add_auth > /dev/null 2>& 1
if [ $? != 0 ] ; then
        ${PKGCMD} -R $PKG_IMG_PATH  set-authority -O ${add_url} ${add_auth}

if [ $? != "0" ] ; then
        print -u2 "$0: Unable to set additional authority"
        exit 1

for t in ${TEST_PKGS} ; do
        ${PKGCMD} -R $PKG_IMG_PATH install ${pkg_name}
        if [ $? != "0" ] ; then
                print -u2 "$0: Unable to install ${pkg_name}"

                exit 1

# if we have added the additional authority, unset it so it doesn't pollute what's
# originally there
if [ $added_authority == 1 ] ; then
         ${PKGCMD} -R $PKG_IMG_PATH  unset-authority ${add_auth}

exit 0

Using Custom Scripts

Once you have prepared your custom script, you must add the script reference to the manifest. Then, you're ready to use the script when building the image.

Adding Script to Manifest

You must update the manifest to point to any custom scripts that you want to use. For example, if you have created a script, /export/home/user1/test_my_pkg, to test your custom package, you would reference the script as follows in the finalizer section of the manifest file. The checkpoint, my_test, indicates where the build will restart.

      <script name="/export/home/user1/test_my_pkg">
           <checkpoint name="my_test" message="Running my test package"/>
      <script name="/usr/share/distro_const/pre_boot_archive_pkg_image_mod">
           <checkpoint name="im-mod" message="Image area modifications"/>

The custom script above is designed to add or remove packages from the package image area, so you must reference this script as the first finalizer script in the <finalizer> section of the manifest file. Include in this reference a checkpoint name that indicates the point in the image-building process where you want to restart the build to test your added package.

Note - This particular sample script above assumes that an alternate repository was specified in the manifest, by using the pkg_repo_addl_authority field. The default manifest is provided with the pkg_repo_addl_authority field commented out, and, thus, unused. So, remove the comment tag from this field, and update the field values to provide a valid URL and authname.

For example, if the additional authority is available on the localhost at port 10000, with the name, localtest, you would modify the pkg_repo_addl_authority field in the manifest as follows:

<mirror url="" />

Running the Script

After you finish the changes to the manifest file to reference your new script, you can start building your image from the beginning once. Subsequently, if you make any changes to your package, you do not need to restart from the beginning. You can generate an image with your modified package by starting at the checkpoint that runs your script.

Note - This option assumes that the build area is in a ZFS file system. Without ZFS, you cannot use checkpointing.

The following is the sequence of commands a user would execute to repeatedly test their modifications to packages.

  1. Run the build from the beginning after modifying the manifest. Perform this step just once.

    distro_const build my_updated_manifest.xml
  2. Check steps that are resumable.

    distro_const build -l my_updated_manifest.xml
  3. Restart from the step of your package modification. You can restart from this step as many times as you need while you are debugging your modified contents.

    distro_const build -r my_test my_updated_manifest.xml

For further information about using the distro_const command with checkpointing options, as demonstrated in this example, see Building an Image in Stages.