video on demandHow 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.
September 2011
Contents:
Introduction
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
Introduction
This article describes how to create customized Oracle Solaris 11 images that contain customized software.
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.
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 http://www.oracle.com/technetwork/server-storage/solaris11/documentation/index.html.
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
PUBLISHER TYPE STATUS URI
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.
Listing 1: Output of the pkg install distribution-constructor Command
root@solarix:~# pkg install distribution-constructor
Packages to install: 2
Variants/Facets to change: 20
Create boot environment: No
Create backup boot environment: No
DOWNLOAD PKGS FILES XFER (MB)
Completed 2/2 62/62 0.1/0.1
PHASE ACTIONS
Install Phase 117/117
PHASE ITEMS
Package State Update Phase 2/2
Image State Update Phase 2/2
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:
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 pkg.oracle.com/solaris/release 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.
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 http://192.168.1.222 as the IP address for the IPS repository.
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.
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:
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:
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.
Listing 5: Listing the 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
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:
Listing 6: Resumable Checkpoints
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
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. 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. 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
Revision 1.0, 09/20/2011