Distribution Constructor

This guide provides instructions for installing the Distribution Constructor and using this application to build ISO and USB images.


Overview of the Distribution Constructor


The Distribution Constructor is a command-line tool for building preconfigured, bootable OpenSolaris images. In the OpenSolaris 2008.11 release, this tool takes an XML manifest file as input, and builds an ISO image that is based on the parameters specified in the manifest file. Optionally, a USB image can be created, based on the generated ISO image.

The image created by the Distribution Constructor by using the default configuration file is comparable to the Live CD image that is distributed as the OpenSolaris 2008.11 release. However, you can modify the content of the ISO image, selecting and adding additional packages to the image. You can also revise the default settings for the resulting booted environment to create a custom, redistributable ISO image or USB image.

The simplest scenario is as follows:

This guide provides instructions for this basic scenario plus instructions for optional customizations.

System Requirements

The distribution constructor requires the following setup:

  • OpenSolaris 2008.11

Install the OpenSolaris 2008.11 release on your system. For installation instructions, see  Getting Started With OpenSolaris 2008.11

  • Disk Space

The recommended minimum size for your distribution constructor work space is 8 Gbytes

  • Required packages

These packages need to be installed before starting with the Distribution Constructor

  • SUNWipkg
  • SUNWgnome-common-devel
  • sunstudioexpress
  • SUNWdistro-const

You can use the Package Manager tool to install these required packages. For an introduction to the Package Manager, see this  screencast.

Alternately, you can use IPS commands such as the following to install this packages:

$ pfexec pkg install SUNWdistro-const 
.
.
.

 Note - These packages need to be installed from official repository, which is: http://pkg.opensolaris.org:80

To display Authority information, type in terminal:

$ pkg authority

If opensolaris.org repository is not set as a preferred repository, run in terminal:

$ pkg set-authority -O http://pkg.opensolaris.org:80  opensolaris.org

To verify if opensolaris.org repository is set as a preferred  repository, run in terminal:

$ pkg authority -P

The output should be:

AUTHORITY                           URL
opensolaris.org                     http://pkg.opensolaris.org:80/
  • Network access

Your installed system must have network access.

Specifically, the distribution constructor accesses IPS repositories that are available on the network to retrieve packages for the ISO image. You must have network access to the repositories that you specify in the manifest file

  • Root access

You must run the distribution constructor as root

Editing the Manifest File or How to use the Distribution Constructor

There are four basic options to using the Distribution Constructor:

    1.  Without changing the Manifest File - Create an Image in One Step

    2.  Adding/Removing packages

    3.  Using Finalizer Scripts

    4.  Running Distribution Constructor - Creating an Image


1.   Without changing the Manifest File - Create an Image in One Step

If the Manifest File is not changed, the Distribution Constructor uses the default configuration and created image is comparable to the Live CD image that is distributed as the OpenSolaris 2008.11 release.

The Distribution Constructor comes with two Manifest Files: slim_cd.xml and all_lang_slim_cd.xml

Slim_cd.xml Manifest creates Primary Languages Live CD contains just core languages.

All_lang_slim_cd.xml Manifest creates Global Live CD contains all languages.

For example, if I want to create Live CD with all language support, type in console:

pfexec distro_const build /usr/share/distro_const/all_lang_slim_cd.xml

This command will create OpenSolaris.iso and OpenSolaris.usb images. The images can be found in /rpool/dc/media/


2.  Adding/Removing packages

The XML Manifest File provides the distribution constructor with a blueprint that specifies the contents and parameters of the new ISO image. To view a complete manifest file, see Manifest File

After you have installed the distribution constructor application, the default manifest file is located at /usr/share/distro_const/slim_cd.xml and /usr/share/distro_const/all_lang_slim_cd.xml

You can either use the default manifest file, or you can copy it and create a custom manifest with a new file name. You will reference the manifest by name when you use the distro_const command to create an image.

Note - Always backup the original Manifest File before editing it. 

Coping the original Manifest File e.g. into home directory:

cp /usr/share/distro_const/all_lang_slim_cd.xml /export/home
cp /usr/share/distro_const/slim_cd.xml /export/home

The Manifest File is protected - only for reading. It need to allowed for writing and executing:

pfexec chmod +rx /export/home/all_lang_slim_cd.xml

Open the Manifest File with any editor, e.g.:

gedit /export/home/all_lang_slim_cd.xml

Primary Manifest Sections, which can be edited:

<distribution name="OpenSolaris">

Provides a name for the distribution.

Optionally, you can type a unique name for your distribution.

<checkpoint_enable>

The default setting enables checkpointing when you create the image.

<pkg_repo_default_authority>

Specifies the location of the IPS repository. The constructor accesses the repository and retrieves packages for the image. The default repository location is http://pkg.opensolaris.org/release.

If you do not want to use the opensolaris.org repository, modify this location to point to the repository of your choice.

<packages>

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 field, one package per line.

<post_install_remove_packages>

Packages to be removed from the pkg_image area before bootroot construction

<bootroot_contents>

Lists the files and directories to be included in the boot root for this image. Files or directories that need to be excluded are specified with the base_exclude tag.


Note - Modifying the boot root contents might cause the system to fail to boot!

<build_area>

Specifies the area where the image will be created. You must confirm that the package image area is valid for your system and revise as needed.

If you want to use checkpointing, you must specify a ZFS dataset, or a mount point that correlates to a ZFS dataset, as your build area. If the ZFS dataset does not exist, it will be created. The zpool that you specify, however, must already exist.

Note - After an image is created, you have the following structure.

  • <build_area>/build_data/pkg_image – Package image area.

  • <build_area>/build_data/bootroot – Boot root build area.

  • <build_area>/build_data/tmp – Temporary directory used by constructor and finalizer scripts.

  • <build_area>/media – Area where the output images are placed.

  • <build_area>/logs – Area that holds log files which record the steps executed by the application and the output from all commands.

    The “simple” log, named simple-log-YYYY-MM-DD-HH-Mi-SS, contains only errors. The "detail” log, named detail-log-YYYY-MM-DD-HH-Mi-SS, contains informational output and errors. The console echos information in the “simple” log file.

Useful links:

How to create and publish an IPS and SVR4 Packages to your repository

How to create your own OpenSolaris Repository (only for Sun employee)

3.  Using Finalizer Scripts

Use the default scripts without editing them. You can also create custom scripts to perform additional tasks. Use the existing scripts as models for creating new scripts.

You can locate your scripts in the /usr/share/distro_const directory or anywhere on the system or network. Make sure that root can execute these scripts.

Reference the script names in the finalizer section of the 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.

For more information about Using the Finalizer Scripts click here.

Running the Distribution Constrution - Creating an Image


After you have set up the manifest file and, optionally, customized the finalizer scripts, you are ready to create an image by running the distro_const command.

Syntax: distro_const build [-R] [-r step] [-p step] [-l] manifest

The distribution constructor provides the ability to pause, or “checkpoint,” and resume at certain stages of the image-generation process. This checkpointing feature is enabled by default.

If you want to use checkpointing, you must specify a ZFS dataset, or a mount point that correlates to a ZFS dataset, as your build area. Then use the checkpointing options in the distro_const command.

The following list summarizes the distro_const command options:


distro_const build manifest

Creates a full image, using the specified manifest file as the blueprint for that image. The subcommand build is required. The manifest field is required.

distro_const build -l manifest

Lists valid steps at which the user can choose to pause or resume building an image if checkpointing is active. This command option queries the manifest file for valid steps. Use the step names provided by this command as valid values for the other checkpointing command options. The build subcommand is required. The manifest field is required.

The default manifest file includes the following steps:

  • im-pop – Populate the image with packages

  • slim-im-mod – Slim CD image area modifications

  • br-init – Boot-root initialization

  • slim-br-config – Slim CD boot-root configuration

  • br-config – Boot-root configuration

  • br-arch – Boot-root archiving

  • slim-post-mod – Slim CD post-boot-root image area modifications

  • grub-setup – GRUB menu setup

  • post-mod – Post-boot-root image area modification

  • iso – ISO image creation

  • usb – USB image creation

When additional scripts are added, additional steps are added.

distro_const build -p step manifest

Builds an image and pauses building the image at the specified step if checkpointing is active. The step and manifest fields are required. The build subcommand is required.

distro_const build -r step manifest

Resumes building the image from the specified step if checkpointing is active. The specified step must be either the step at which the previous build stopped executing, or an earlier step. A later step is not valid. The step and manifest fields are required. The build subcommand is required.

distro_const build -R manifest

Resumes building the image from the last step executed if checkpointing is active. The manifest field is required. The build subcommand is required.

Using Checkpointing to Create an Image

You can use the checkpointing options in the distro_const command to debug your selection of files, packages, and scripts for creating an image.

Use the checkpointing options that are available in the distro_const command as described in the following basic instructions.

Creating an Image Using Checkpoint Options

  1. Check the valid steps at which you can choose to pause or resume by using the following command:
    $ pfexec distro_const build -l manifest

    This command displays the valid steps at which you can pause or resume building an image. Use the step names provided by this command as valid values for the other checkpointing command options. The build subcommand is required.

    The valid steps are displayed as follows:

    Step           Resumable Description
    -------------- --------- -------------
    im-pop             X     Populate the image with packages
    pkg-add            X     Auto install pkgs
    im-mod             X     Image area modifications
    br-init            X     Boot root initialization
    br-config          X     Boot root configuration
    ai-br-config       X     Auto install boot root configuration
    ai-post-br-config  X     Auto install post boot root configuration
    br-arch            X     Boot root archiving
    ai-post-br-arch    X     Auto install post boot root archiving
    grub-setup         X     Grub menu setup
    post-mod                 Post bootroot image area modification
    iso                      ISO image creation 

  2. Use the following command to build an image, and to pause building the image at the specified step.
    $ pfexec distro_const build -p step manifest
    Resume the build by using one of the following alternatives:
    • Use the following command to resume building the image from the specified step.
      $ pfexec distro_const build -r step manifest

      The specified step must be either the step at which the previous build stopped executing, or an earlier step. A later step is not valid. The step and manifest fields are required. The build subcommand is required.

    • Use the following command to resume building the image from the last step executed.
      $ pfexec distro_const build -R manifest 

For example How to use Checkpoints look at: Hebrew OpenSolaris 2008.11


Related Blogs:

How to create and publish an IPS and SVR4 Packages to your repository

How to create your own OpenSolaris Repository (only for Sun employee)

Hebrew OpenSolaris 2008.11

Comments:

Post a Comment:
  • HTML Syntax: NOT allowed
About

Solaris l10n & i18n, locales, keyboards, fonts and related topics.

Search

Archives
« April 2014
SunMonTueWedThuFriSat
  
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
   
       
Today