Creating a Custom Oracle® Solaris 11.2 Installation Image

Exit Print View

Updated: July 2014
 
 

Modifying the Manifest Content

All the fields in each manifest file provide preset, default values that will create the type of ISO image you need. You can manually edit these preset fields in a manifest file to further customize the resulting image.

The following table describes the primary elements in the sample manifest files.

Table 2-3  Manifest Elements
Element
Description
<distro name="Oracle_Solaris_Text_X86"
add_timestamp="false">
Specifies the image name with optional timestamp
<boot_mods>
Specifies GRUB menu modifications for the image
<target>
Defines the ZFS build dataset where the image is built
<software name="transfer-ips-install" type="IPS">
Specifies the source for the software packages to be installed
<software_data action="install">
Lists the packages to be installed
<software_data action="uninstall">
Lists the packages to be uninstalled
<software name="set-ips-attributes">
Sets different attributes for the IPS after the installation has finished
<software name="ba-init">
Specifies the boot archive contents

Caution  -  Modify with care. If the boot archive is incorrect, the installed system will fail to boot.

<execution stop_on_error="true">
<checkpoint name="transfer-ips-install"/>
Lists build checkpoints
<configuration name="pre-pkg-img-mod" type="sysconf"
 
source="/etc/svc/profile/generic_limited_net.xml">
Specifies SMF services to be applied to the media during the build

Caution  -  Rarely modify.

Provide the Image Title

Use the following element to provide a custom or default name for the image you are going to build:

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

If you intend to perform a series of builds of an image and retain the incremental images, you can change the timestamp variable to “true” and a timestamp will be automatically appended to the name for each image.

If you need to specify an HTTP proxy, uncomment the distro name element that includes the proxy variable, and provide the proxy location.

Modify the Boot Menu

This boot menu element specifies boot menu modifications to be applied to the image.

In the following example, a specialized boot menu with the title “boot1” will be applied to the image. The timeout attribute specifics the time before the default boot entry is automatically activated.

<boot_mods title="boot1" timeout="5">

Within the boot menu element, you can add individual boot menu entries by adding a new boot_entry element for each new entry. Entries are added sequentially to the boot menu in the order based on the insert_at attribute value of “start” or “end” for each boot entry.


Note - Add new entries before the existing “with magnifier” entry.

See the following example of an individual boot_entry element.

<boot_entry>
   <title_suffix>with screen reader</title_suffix>
   <kernel_args>-B assistive_tech=reader</kernel_args>
</boot_entry>

For detailed information, see the dc_manifest (4) man page.

Specify the Build Area

You can customize the target element. This element defines the ZFS build dataset to be used for the build. This dataset is the area where the image will be created. You must provide a valid dataset location. You should check the default build area to ensure that the build will not destroy content you need to keep on your system. Modify the build area if necessary.


Note - The file system name should not include the name of the zpool.

The following example shows a sample target element.

 <target>
   <logical>
     <zpool action="use_existing" name="rpool">
       <dataset>
         <filesystem name="dc/sample-dataset-location" 
         action="preserve"/>
       </dataset>
     </zpool>
   </logical>
 </target>

Specify the Publisher

The following element specifies a publisher where the distribution constructor can get packages to download and use to build the image.

<software name="transfer-ips-install">

In the source element nested within this software name section, edit the publisher name and origin name elements to specify which publisher to use and where the package repository is located. The repository location could be an NFS path or a local directory. Multiple publishers can be listed. When the distribution constructor attempts to locate packages to install, publishers are searched in the order they are listed here.

If mirrors for a publisher need to be specified, uncomment and edit the mirror name element.

The following example shows a sample source element found within the software name element.

<source>
   <publisher name="publisher1">
      <origin name="http://example.oracle.com/primary-pub"/>
      <mirror name="mirror.example.com"/>
   </publisher>
   <publisher name="publisher2">
       <origin name="http://example2.com/dev/solaris"/>
   </publisher>
   <publisher name="publisher3.org">
       <origin name="http://example3.com/dev"/>
   </publisher>
   <publisher name="publisher4">
       <origin name="file:///net/myserver/publisher4/repo"/>
   </publisher>
</source>

For further information about using publishers, see Adding and Updating Software in Oracle Solaris 11.2 .

List the Packages to Install

The software_data element with the install attribute lists the set of packages to be installed in order to build a particular type of image, depending on which manifest you are using. For example, the dc_livecd.xml manifest lists the packages needed to build a Live Media image. Each name tag lists one package name or the name of a group package that contains many packages.

<software_data action="install">
   <name>pkg:/group/system/solaris-desktop</name>
   <name>pkg:/system/install/gui-install</name>
   <name>pkg:/system/install/media/internal</name>
</software_data>

If you have packages that you want to add to the image, append the package names by adding a name tag for each package.

By default, the most current package version available in the specified repository is installed. If another version is required, append the version number to the package reference using the following format:

<name>pkg:/group/system/solaris-desktop@0.5.11-0.build#</name>

Note - The Oracle Solaris release version on your system must be the same as the release version of the image that you intend to create with the distribution constructor.

In addition, packages with a particular version specified might not be installed if other packages with a conflicting version are being installed as specified by an automated install service's manifest file. See Chapter 9, Customizing Installations, in Installing Oracle Solaris 11.2 Systems .


Example 2-1  Adding Packages and Additional Publishers

In this example, a second publisher, mypublisher, is specified. Additional packages, mypackage1 and mypackage2, are specified.

During the build process, the publishers are checked in the order they are listed. If packages are not found at the first publisher, the next publisher is searched for the specified packages.

<software name="transfer-ips-install" type="IPS">
   <destination>
      <xi:include xmlns:xi="http://www.w3.org/2003/XInclude"
            href="/usr/share/distro_const/lang_facets.xml"/>
   </destination>
   <source>
      <publisher name="solaris">
          <origin name="http://pkg.oracle.com/solaris/release"/>
      </publisher>
      <publisher name="mypublisher">
         <origin name="http://mypublisher.company.com"/>
      </publisher>
   </source>
   <software_data action="install">
        <name>pkg:/group/system/solaris-large-server</name>
        <name>pkg:/system/install/text-install</name>
        <name>pkg:/system/install/media/internal</name>
        <name>pkg:/mypackage1</name>
        <name>pkg:/mypackage2</name>
   </software_data>
</software>

List the Packages to Uninstall

The software_data element with the uninstall attribute can be used to uninstall an individual package or to uninstall a group package definition.


Note - A group package definition binds all the individual packages within that group together into one unit that can only be acted upon as a group.

The uninstall attribute is particularly useful if you want to install a full group package, but you want to omit one or more individual packages from that group. You can use the uninstall attribute to, first, remove the group package definition. Then, you can uninstall individual packages that were installed as part of a group package.

For example, you might have chosen to build a Live Media installation image. The default Live Media installation image includes a Firefox brower in the desktop group package.

    If you want to omit the Firefox browser from the image you want to build, you would do the following:

  1. Install the solaris-desktop group package that includes all the software for the usual Live Media desktop. See List the Packages to Install.

  2. Uninstall the solaris-desktop group package definition by using the uninstall attribute as follows:

    <software_data action="uninstall">
       <name>pkg:/group/system/solaris-desktop</name>
    </software_data>

    Note - The uninstall action on the group package uninstalls only the group package definition. All the individual packages within that group are still installed as per the first step.
  3. Now that the individual packages are not bound into a group definition, you can use the uninstall attribute again to uninstall the Firefox package.

    <software_data action="uninstall">
       <name>pkg:/web/browser/firefox</name>
    </software_data>

    Alternately, you can combine steps 2 and 3 in one entry as follows:

    <software_data action="uninstall">
    		<name>pkg:/group/system/solaris-desktop</name>
    		<name>pkg:/web/browser/firefox</name>
    </software_data>

Append additional packages to be uninstalled at the end of the uninstall section.

Specify the Publisher for an Installed System

The software name element affects a system after that system has been installed with the image created using the distribution constructor.

<software name="set-ips-attributes">

Provide the publisher name and optional mirror name tags to specify where the installed system can access additional packages to download and install.

You can also set IPS attributes in this element. See the IPS property information on the pkg (1) man page.

Set Up Build Checkpoints

The execution element in the manifest lists a series of checkpoints that are executed during the image construction process. Checkpoints are executed in the order they are listed in this section. The default checkpoints needed to build the default installation image are included in each manifest.

During the image construction process, the checkpoints modify the contents of the build area that is specified in the manifest.

    The build area contains the following directories:

  • ZFS dataset/build_data/pkg_image

  • ZFS dataset/build_data/boot_archive

where the ZFS dataset variable is specified by the target element in the manifest.

During the build process, everything that will be included in the final image is added to the pkg_image directory. The files in the separate boot_archive directory are used during the build process to create a boot archive file which is also added to the pkg_image directory.

    The following list provides a brief description of each default checkpoint in the order the checkpoints are executed in most manifests.

  • transfer-ips-install – At this checkpoint, the distribution constructor contacts the IPS publishers and adds to the image the packages that are listed in the software_data element of the manifest.

  • set-ips-attributes – At this checkpoint, the constructor sets the publisher to be used by the installed system. The values set by this checkpoint are not relevant if you are building an automated installation image.

  • pre-pkg-img-mod – At this checkpoint, the constructor imports into the image the SMF service files that were specified in the configuration element of the manifest. Also, the constructor modifies some files to optimize the image.

    All changes up through this checkpoint are included in both the image being built and the root archive. You should add new checkpoints for custom scripts before or immediately after this pre-pkg-img-mod checkpoint if you want to ensure that changes from the custom scripts are incorporated in both the root archive and in the image.

  • ba-init – At this checkpoint, the constructor populates the root archive with the files listed in the ba-init section of the manifest. These files are copied from the pkg_image area into the root_archive area.

  • ba-config – At this checkpoint, the constructor performs further modifications to the files that were copied into the root archive. The constructor creates symbolic links to other files that are not needed until later in the boot process in order to minimize the size of the root archive.

  • ba-arch – At this checkpoint, the constructor packs the root archive and creates the root archive as a file within the pkg_image directory. The constructor also applies any optimizations to the root archive specific to the type of system being built. After this checkpoint, changes to the boot archive specifications by custom scripts would not be integrated into the root archive because the root archive has already been packed.

  • boot-setup – At this checkpoint, the constructor sets up the GRUB2 menu based on the entries specified in the boot_entry section of the manifest. This checkpoint applies only to images for x86 systems.

  • pkg-img-mod – At this checkpoint, the constructor creates the main archives for the image being built and optimizes the pkg_image area. The constructor moves files in the pkg_image directory, creating the archive for the image. Everything included in the pkg_image directory is included in the image. Any additions after this checkpoint would not be included in the image.

  • create-iso – This checkpoint builds the .iso files, including everything in the pkg_image directory.

  • create-usb – This checkpoint builds the .usb file from the generated .iso file.

Looking at the specific fields included in each checkpoint section, each checkpoint name tag includes the mod-path attribute which specifies where the checkpoint script is located.

Some of the default checkpoint tags include arguments with default values provided. The following checkpoint example from the dc_ai_sparc.xml sample manifest creates the boot archive for the image build and points to a script that will accomplish that task. The example checkpoint also includes argument fields with specific values provided for each argument.

<checkpoint name="ba-arch"
    desc="Boot Archive Archival"
    mod_path="solaris_install/distro_const/checkpoints/
    boot_archive_archive"
    checkpoint_class="BootArchiveArchive">
    <kwargs>
        <arg name="size_pad">0</arg>
        <arg name="bytes_per_inode">0</arg>
        <arglist name="uncompressed_files">
             <argitem>etc/svc/repository.db</argitem>
             <argitem>etc/name_to_major</argitem>
             <argitem>etc/minor_perm</argitem>
             <argitem>etc/driver_aliases</argitem>
             <argitem>etc/driver_classes</argitem>
             <argitem>etc/path_to_inst</argitem>
             <argitem>etc/default/init</argitem>
             <argitem>etc/nsswitch.conf</argitem>
             <argitem>etc/passwd</argitem>
             <argitem>etc/shadow</argitem>
             <argitem>etc/inet/hosts</argitem>
        </arglist>
    </kwargs>
</checkpoint>

As shown in this example, the kwargs element contains keyword arguments that need to be passed into the checkpoint during the build. Within the kwargs element are arg name elements that can be used to specify individual keywords to be passed into the checkpoint. And, the arglist element contains a list of multiple argitem values to be passed into the checkpoint. This example includes a list of uncompressed files in the arglist element.

Each kargs list item is enclosed in double quotes. When no double quotes are used, or if one set of double quotes encloses the entire string, the entire string including spaces and new lines is interpreted as one argument. Do not use commas between arguments.

If you create a custom script to be used during the building of an image, you must add a checkpoint element pointing to the script location. The checkpoint for a custom script needs only an args element that points to the custom script location. For further information and examples, see Creating and Using Custom Scripts.

Use the distro_const command options to control pausing and restarting the build process at particular checkpoints. See How to Build an Image in Stages.

Example 2-2  Adding SVR4 Packages

In this example, a new checkpoint is added to the manifest. This new checkpoint lists SVR4 packages to be added to the image and their location. Then, this new checkpoint is referenced in the execution section.

First, the new checkpoint is created by adding a new software element. This checkpoint specifies SVR4 as the software type, where to find the packages, and where to install the packages.

In addition, the specific SVR4 packages to be installed are listed in the software_data element.

<software name="transfer-svr4-install" type="SVR4">
   <destination>
       <dir path="{PKG_IMAGE_PATH}"/>
   </destination>
   <source>
    <publisher/>
      <origin name="/path/to/packages"/>
    </publisher>
   </source>
   <software_data action="install">
      <name>SUNWpackage1</name>
      <name>SUNWpackage2</name>
   </software_data>
</software>

If included in the checkpoint, the values of {PKG_IMAGE_PATH} and {BOOT_ARCHIVE} are replaced by the distro_const utility with ZFS dataset/build_data/pkg_image and ZFS dataset/build_data/boot_archive, respectively. In this example, the SVR4 packages will be installed into ZFS dataset/build_data/pkg_image.

Finally, the new checkpoint is referenced in the execution section. The checkpoint name can be any string, but for this example the checkpoint_class must be TransferSVR4.

<execution stop_on_error="true">
   <checkpoint name="transfer-ips-install"
       desc="Transfer pkg contents from IPS"
       mod_path="solaris_install/transfer/ips"
       checkpoint_class="TransferIPS"/>
   <checkpoint name="set-ips-attributes"
       desc="Set post-install IPS attributes"
       mod_path="solaris_install/transfer/ips"
       checkpoint_class="TransferIPS"/>
   <checkpoint name="transfer-svr4-install"
      desc="Transfer pkg contents from SVR4 packages"
      mod_path="solaris_install/transfer/svr4"
      checkpoint_class="TransferSVR4"/>

Note that the software name must match the checkpoint name. In this example, both are “transfer-svr4–install.”

Example 2-3  Creating Hashes of the Media

This checkpoint enables users to autogenerate hashes of the media generated by distro_const by using the checksums checkpoint in the DC manifest.

    <checkpoint name="checksums" 
      desc="Checksum calculation for media" 
      mod_path="solaris_install/distro_const/checkpoints/checksums"
      checkpoint_class="Checksums"> 
      <kwargs> 
        <arglist name="algorithms"> 
          <argitem file_path="/tmp/md5sums.txt">md5</argitem> 
          <argitem>sha1</argitem> 
          <argitem>sha224</argitem> 
          <argitem>sha256</argitem> 
          <argitem>sha384</argitem> 
          <argitem>sha512</argitem> 
        </arglist> 
      </kwargs> 
    </checkpoint>
  

The arglist includes all of the algorithms that are used to generate hashes for the generated media. Each argitem specifies an algorithm. The valid algorithms can be determined by running /usr/bindigest -l. Each argitem can have a path attribute that specifies the absolute path of an additional file that will be appended with the hashes produced by that algorithm. If no algorithms are specified, the default is md5.

While the image is built, files will be generated for each algorithm containing checksums for each media.