How to Create a Customized Oracle Solaris 11 Image Using the Distribution Constructor

by Isaac Rozenfeld

Learn how to create and distribute customized Oracle Solaris 11 images by following an example that shows the process from beginning to end.

Published September 2011 (updated January 2014)

Table of Contents
Overview of the Distribution Constructor
Using the Distribution Constructor: An Example
   Obtaining the Distribution Constructor
   Preparing to Create an Image Using the Distribution Constructor
   Making Final Adjustments with the Distribution Constructor
   Creating an Image Using the Distribution Constructor
Creating an Installation Service to Distribute the Image
See Also
About the Author


This article describes how to create customized Oracle Solaris 11 images that contain customized software.

Want to comment on this article? Post the link on Facebook's OTN Garage page.  Have a similar article to share? Bring it up on Facebook or Twitter and let's discuss.

A brief overview of the reasons for creating a customized Oracle Solaris 11 image is provided. Relevant concepts are introduced, followed by a real example of using the Distribution Constructor to create custom ("golden") images. The example concludes with an illustration of taking the created image and making it available for consumption by systems as part of the provisioning process. When using the Distribution Constructor, you can only create SPARC images on a SPARC system and x86 images on an x86 system.

Note: This article was written for Oracle Solaris 11, which is the culmination of multiple development releases known as "Oracle Solaris 11 Express." For pointers to information regarding specific features referenced in this article, go to

Overview of the Distribution Constructor

The Distribution Constructor is a command-line tool for building preconfigured, bootable Oracle Solaris 11 images. It was developed as an open source project by Oracle Solaris engineers and the community, and it is available in Oracle Solaris 11 to provide value to the larger Oracle Solaris ecosystem. For example, large enterprises and OEMs can use it to build deployable images to support large, cloud-like server farms.

Currently, this tool takes as input a XML manifest file, and it produces an ISO image that is based on the parameters specified in the manifest file. Optionally, a USB image can be created that is based on the generated ISO image.

The image created by using the default manifest file is comparable to the LiveCD image that is distributed as part of the Oracle Solaris 11 release. You can modify the content of the ISO image prior to creating the image, for example, by adding additional packages to the image. Therefore, you can create minimized and ruggedized custom images. When these images are subsequently deployed into the enterprise, additional functionality can be layered on top, as required. The real value, therefore, is in the ability to revise the default settings for the resulting booted environment to create a custom, redistributable ISO (or USB) image.

Using the Distribution Constructor: An Example

The following sections describe the process for using the Distribution Constructor to build an image.

Obtaining the Distribution Constructor

To use Distribution Constructor, you need to have Oracle Solaris 11 installed and running on your system. Alternatively, you can use a hypervisor to host an image of Oracle Solaris 11. The recommended minimum size of available disk space for working with the Distribution Constructor is 8 GB.

Running the Distribution Constructor requires root privileges because of the administrative tasks that take place.

To obtain the Distribution Constructor, you install the distribution-constructor package, which is hosted by an Image Packaging System (IPS) repository that should already be configured on your system. To verify that the IPS repository is configured, run the pkg publisher command.

If the IPS repository is not already configured, configure it before you attempt to add the distribution-constructor package. Otherwise, the package addition will fail.

The system should either be configured with network access (if the IPS repository is to be accessed over the network) or with a locally configured IPS repository that is served from the same system.

A locally configured IPS repository was used for the example in this article, as shown in the following output from the pkg publisher command, which indicates that the IPS repository is hosted over HTTP on localhost.

root@solarix:/usr/share/distro_const# pkg publisher
solaris                              origin   online   http://localhost/

After you have verified that the repository is configured, as root, add the Distribution Constructor package by running the pkg install distribution-constructor command.

The distribution-constructor package is then downloaded from the IPS repository and immediately installed. The pkg install distribution-constructor command displays status of the process, as shown in Listing 1, which makes it easy to observe the progress.

root@solarix:~# pkg install distribution-constructor

	 Packages to install:  2
     Variants/Facets to change: 20
       Create boot environment: No
Create backup boot environment: No

Completed				 2/2	  62/62 0.1/0.1

Install Phase			   117/117 

Package State Update Phase		       2/2 
Image State Update Phase		       2/2 

Listing 1: Output of the pkg install distribution-constructor Command

Preparing to Create an Image Using the Distribution Constructor

There are two approaches for using the Distribution Constructor:

  • Using a supplied manifest file, which is great for becoming familiar with how the Distribution Constructor works
  • Adding packages to or removing packages from an image (customizing the image)

When you install the distribution-constructor package, a /usr/share/distro_const directory is created and a number of sample XML manifest files for use with x86 and SPARC images are installed into the directory, for example:

boot_archive_contents_sparc.xml  dc_ai_x86.original.xml dc_text_x86.xml
boot_archive_contents_x86.xml    dc_ai_x86.xml	 lang_facets.xml
dc_ai_sparc.original.xml         dc_livecd.xml	 profile
dc_ai_sparc.xm                   dc_text_sparc.xml	 sort

A manifest file provides the Distribution Constructor with a blueprint that specifies the contents and parameters of the desired image.

It is recommended that beginners take advantage of an existing XML manifest file by treating it as a template. To do this, copy the manifest to another location (your home directory, for example), giving it another name. Then edit the copy so it contains the desired contents.

Note: Always remember to make a backup copy of a manifest before editing it.

In the following example, we make a copy of a manifest and then edit the copy.

root@solarix:/# cp /usr/share/distro_const/dc_text_sparc.xml ~/my_golden_image.xml
root@solarix:/# vi ~/my_golden_image.xml

Looking through the manifest, we observe that there are a number of important sections that illustrate possible areas of interest.

One important editable section is the section where you can optionally change the name of the customized image:

<distro name="MyGoldenImage_Solaris_AI_X86" add_timestamp="false">

Additionally, there is a section where the location of the IPS repository is defined, as shown in the following example. The Distribution Constructor accesses the repository and retrieves packages for the image.

If you do not want to use the default repository, modify the location to point to the repository of your choice. In the example here, we use localhost as the location because a locally configured IPS repository is being used.

  <publisher name="solaris">
	 <origin name="http://localhost"/>

Once the image has been built and deployed, any future software that might need to be added to it would likely come from the IPS repository. You can preconfigure the address of the default IPS repository, and then that address will be used later when you search for software.

Listing 2 shows the section of the manifest where the address is specified. In this example, we specify as the IP address for the IPS repository.

<!-- The default publisher to be set on the system after it has been installed.
    <software name="set-ips-attributes" type="IPS">
        <image img_root="{PKG_IMAGE_PATH}" action="use_existing"/>
        <publisher name="solaris">
          <origin name=""/>
            If mirrors for this publisher are desired, they can be set here
          <!-- Uncomment before using
          <mirror name=""></mirror>

Listing 2: Specifying the Address of the IPS Repository in the Manifest

The next important section lists the packages to be included in the image. If you have packages that you want to add to the basic image, add your packages in this section using one package per line, as shown in Listing 3.

	List of packages used to form the installed image

        By default the latest build available in the specified IPS repository
        is installed. If another build is required, the build number has to be
        appended to the 'entire' package in the following form:

      <software_data action="install">

Listing 3: Specifying Additional Packages in the Manifest

One of the last sections in the manifest is the section in which the Distribution Constructor workspace area is defined. You must confirm that the package image area is valid for your system and, if it is not, you must revise the manifest.

If the desired location, which is hosted on a ZFS data set, does not exist, it will be created. The zpool that you specify, however, must already exist. By default, it is in a file system named dc created in ZFS pool /rpool, and it is defined in the section of the manifest labeled "Target Section," as shown in Listing 4:

      Target Section: defines zfs build dataset to be used for the build
      Filesystem name should not include the name of the zpool.
    <target name="desired">
        <zpool name="rpool" action="use_existing">
          <filesystem name="dc/ai" action="preserve"/>

Listing 4: Specifying the Location of the Distribution Constructor Workspace

The information specified in the Target Section is used with the file system name to create the directory structure in the ZFS data set, as follows:

  • <ZFS data set>/build_data/pkg_image: Package image area.
  • <ZFS data set>/build_data/boot_archive: Boot root build area.
  • <ZFS data set>/build_data/tmp: Temporary directory used as part of the building process.
  • <ZFS data set>/media: Area where the output image (or images) is placed
  • <ZFS data set>/logs: Area that holds log files that record the steps executed by the Distribution Constructor and the output from all commands. The "simple" log, named simple-log-YYYY-MM-DD-HH-Mi, contains only errors. The "detail" log, named detail-log-YYYY-MM-DD-HH-Mi, contains informational output and errors. The console echoes information in the simple log file.

Making Final Adjustments with the Distribution Constructor

Once you have come up with the ideal manifest contents, the next step is generating the image.

The command line interface to the Distribution Constructor is the distro_const command, which gets installed in the /usr/bin directory. This directory is added to $PATH when you add the distribution-constructor package.

One of the unique features of the Distribution Constructor is the ability to take advantage of checkpointing, that is, the ability to leverage a modular approach to building images. Checkpointing helps save time in the process of developing an ideal customized image. Developing an ideal customized image often requires that certain adjustments be made while narrowing down the specific software packages, proper labeling, naming, and other behavior and configuration preferences.

Checkpointing adds modularity to the build process and prevents you from having to repeat build steps that have been completed successfully and are marked as such. During image development, if a particular step needs to be corrected and image generation needs to be tried again, the process needs to be continued only from that step forward, leveraging previously successfully completed steps.

To see what all the checkpoints are, simply issue the build -l subcommand, as shown below. Any checkpoints that are resumable are marked in the Resumable column. Listing 5 shows no resumable checkpoints.

root@solarix:/# distro_const build -l  my_golden_image.xml 
Checkpoint           Resumable Description
----------           --------- -----------
transfer-ips-install           Transfer pkg contents from IPS
set-ips-attributes             Set post-install IPS attributes
pre-pkg-img-mod                Pre package image modification
ba-init                        Boot Archive Initialization
ba-config                      Boot Archive Configuration
ba-arch                        Boot Archive Archival
boot-setup                     Setup boot menu     
pkg-img-mod                    Pkg image area modification
create-iso                     ISO media creation  
create-usb                     USB media creation  
ai-publish-package             Publish pkg(5) repository

Listing 5: Listing the Checkpoints

The sample XML manifests that are supplied in the /usr/share/distro_const directory are generally one of three types:

  • Automated Installer: This type is flexible and feature-rich, and it used in the example in this article. It is used for installing a customized image noninteractively (that is, programmatically in a hands-off fashion) onto a large number of systems.
  • Text Installer: This type is used for installing a customized image interactively onto a "headless" server.
  • LiveCD/USB Installer: This type is used for installing a customized image interactively onto a server using a GUI.

Depending on which of the three manifest types you choose to work with, certain checkpoints might not be present. For example, when working with a LiveCD-based manifest, the description for the boot-setup checkpoint will read Setup LiveCD boot menu, whereas if you work with a Text Installer-based manifest, you will see a description that reads Setup boot menu. With an Automated Installer-based manifest, there is no direct interactive booting and, thus, there is no boot-setup checkpoint at all.

In fact, with Automated Installer-based manifests, the number of checkpoints is distinctly smaller due to the fact that Automated Installer-based images are deployed across the enterprise in modular and scalable ways via the installation service (which is discussed in the last section). These differences in the number and types of checkpoints should not be a point of concern.

As you work through the image building process, you will see that most of the checkpoints are resumable, due to the tight integration of the Distribution Constructor with the unique capabilities of the underlying ZFS file system technologies. Eventually, your output will look similar to Listing 6:

Checkpoint           Resumable Description
----------           --------- -----------
transfer-ips-install     X     Transfer pkg contents from IPS
set-ips-attributes       X     Set post-install IPS attributes
pre-pkg-img-mod          X     Pre package image modification
ba-init                  X     Boot Archive Initialization
ba-config                X     Boot Archive Configuration
ba-arch                  X     Boot Archive Archival
boot-setup               X     Setup boot menu     
pkg-img-mod              X     Pkg image area modification
create-iso               X     ISO media creation  
create-usb               X     USB media creation  
ai-publish-package       X     Publish pkg(5) repository  

Listing 6: Resumable Checkpoints

Creating an Image Using the Distribution Constructor

To create an image, issue the build command without any switches. This starts the build creation process, which could take anywhere from 30 to 45 minutes, depending on the configuration, disk performance, network access speeds, and the size of image being created.

Logging is provided to display status and progress. As previously mentioned, two log files are available: a simple log and a detailed log. You might want to monitor the log files through a separate terminal window. Figure 1 shows an example of what the command and some of the resulting early output look like:

Figure 1

Figure 1. Output of the build Command

After a few more minutes, the output is appended with additional status updates, as shown in Figure 2:

Figure 2

Figure 2. More Output of the build Command

The process continues with additional information printed to the screen until the process is complete.

The last line of the output shows the date and a time stamp indicating when the build was completed. This line is useful if you need to refer back to the build after you have executed multiple builds with the Distribution Constructor.

Creating an Installation Service to Distribute the Image

After you have successfully created an image, you need to create an installation service to distribute (install) the image on other systems.

Installation services in Oracle Solaris 11 are handled through the installadm command and they are significantly simpler than with previous versions of Oracle Solaris.

As mentioned earlier, images produced by the Distribution Constructor can be one of three flavors, based on the XML manifest being used as input:

  • Automated Installer-based
  • Text Installer-based
  • LiveCD/USB-based

For example, if you are using an Automated Installer image, you can use the installadm create-service command to create an installation service and publish the image into the service so the image is made available to clients.

The following is a simple example of creating an installation service on an Automated Install server that might already have a few preconfigured services.

root@solarix:~# installadm create-service -n x86snv173 -s \  /home/isaac/MyGoldenImage_Solaris_AI_X86.iso 
OK to use default image path: /export/auto_install/x86snv173? [y/N]: y

Creating service: x86snv173

Setting up the target image at /export/auto_install/x86snv173 ...
Refreshing install services

That's it! You can verify that the service you just created is listed, as follows:

root@solarix:~# installadm list

Service Name  Alias Of  Status  Arch   Image Path 
------------  --------  ------  ----   ---------- 
x86snv173     -         on      x86    /export/auto_install/x86snv173

See Also

For more information and next steps, please consult these resources:

And here are some additional resources:

About the Author

Isaac Rozenfeld is a Principal Product Manager for Oracle Solaris. Isaac joined Oracle in 2010 as part of the Sun Microsystems acquisition.

Revision 1.0, 09/20/2011
Revision 1.1, 01/30/2014:
Added "See Also" and "About the Author" sections