| Skip Navigation Links | |
| Exit Print View | |
|
Creating a Custom Oracle Solaris 11 Installation Image Oracle Solaris 11 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
|
|
Creating a Custom Oracle Solaris 11 Installation Image Oracle Solaris 11 Information Library |
1. Introduction to Creating a Custom Installation Image
2. Design a Custom Installation Image
The distribution constructor creates images based on settings specified in XML files, called manifest files. The manifest files contain specifications for the contents and parameters for the ISO images that you create using the distribution constructor. The distribution-constructor package provides sample manifests that can be used to create a custom LiveCD, an x86 or SPARC AI ISO image, or an x86 or SPARC text installation image.
The elements in each manifest file provide preset, default values that will create the type of ISO image you need. You can manually edit these preset elements in a manifest file to customize the resulting image. In addition, you can create custom scripts to further modify your image. Then, reference the new scripts in the manifest file.
The distribution-constructor package provides the following sample manifest files.
Table 2-2 Sample Manifests
|
You can use the Package Manager tool to install the required package. The Package Manager is available on the menu bar on the desktop of the Oracle Solaris operating system. On the menu bar, go to System>Administration>Package Manager.
Alternately, use IPS commands such as the following to install this package:
# pkg install distribution-constructor
You will reference the manifest file by name when you use the distro_const command to create an image.
Note - Always back up the original manifest file and the default scripts before copying them.
For example, you can edit the target element in the manifest to specify a different location of the build area where the image can be constructed. And, you can check the publisher to ensure your system can contact that publisher to download the packages needed to build the image. If necessary, you can edit the software name element to specify a different publisher and repository location.
For information, see Modifying the Manifest Content and the dc_manifest(4) man page.
If you do create new scripts, update the script references in the execution section of the manifest file.
For instructions, see Creating and Using Custom Scripts.
For instructions, see Chapter 3, Building an Image.
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.
Depending on which sample manifest you select, the primary elements are as follows.
Table 2-3 Manifest Elements
|
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 enter the proxy location.
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 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.
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 enter a valid dataset location. You should check the default build area to ensure the build will not destroy content you need to keep on your system. Modify the build area if necessary.
Note - The filesystem name should not include the name of the zpool.
See the following example.
<target>
<logical>
<zpool action="use_existing" name="rpool">
<dataset>
<filesystem name="dc/sample-dataset-location"
action="preserve"/>
</dataset>
</zpool>
</logical>
</target>
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 in this section, edit the publisher name and origin name elements to specify which publisher to use and where the package repository is located. 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.
See the following example.
<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"></origin>
</publisher>
<publisher name="publisher3.org">
<origin name="http://example3.com/dev"></origin>
</publisher>
</source>
For further information about using publishers, see Adding and Updating Oracle Solaris 11 Software Packages.
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 LiveCD 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 - Packages with a particular version specified might not installed if there are other packages with a conflicting version being installed. For further information, see the pkg(5) man page.
Example 2-1 Adding Packages and Additional Publishers
In this example, a second publisher, mypublisher, is specified. And, 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>
The software_data element with the uninstall attribute can be used to uninstall an individual package or to uninstall a group package definition.
In the following example, solaris-desktop is the name of a group package that contains numerous individual packages.
<software_data action="uninstall"> <name>pkg:/group/system/solaris-desktop</name> </software_data>
You could uninstall a group package. Uninstalling a group package means that only the group definition is actually uninstalled. The individual packages that were previously installed as part of that group are not uninstalled. However, you can uninstall those individual packages without uninstalling the group package. Retaining the group package can be useful for ongoing reference. You can also use the name tag to uninstall an individual package. Append additional packages to be uninstalled at the end of the uninstall section.
The following 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 pkg(1) man page IPS property information.
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.
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 key word 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 key words 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>
<dir path="/path/to/packages"/>
</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.
<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.”
The distribution constructor enables you to specify additional scripts that can be used to make customizations based on the type of image you are building. The manifest files point to the scripts, and the scripts transform the generic image into a media-specific distribution. These scripts are referenced in the execution section of the manifest files. Any number of custom-script checkpoints may be specified.
Note - Support for scripts is limited to any unmodified, default scripts that are supplied with the application packages. If you choose to customize these scripts, back up the original scripts first.
Before You Begin
When you create your own custom scripts, note the following:
Scripts can be Python programs, shell scripts, or binaries.
Scripts are executed in the order that they are listed in the execution section of the manifest file.
Standard output (stdout) and error output (stderr) of commands executed within the scripts (both shell and python modules) are captured in log files that report on the completed or attempted build.
Make sure that a user assuming the root role can execute these scripts.
Be sure to specify the full path to your scripts. Checkpoints are executed in the order they are listed in the execution section of the manifest.
When you add a reference for a new script in the execution section of a manifest file, you must specify a checkpoint name that can be used to pause the image build before or after this script performs its task. Optionally, you can include a custom message associated with the checkpoint name. If this message is omitted, the path of the script is used as the default checkpoint message. The checkpoint message displays when the checkpoint is run during the build process.
Note - Use meaningful names for checkpoint names instead of using numbers. If new scripts are added, the new checkpoints for those new scripts will disrupt a numbered checkpoint order.
The following example checkpoint references a custom script named “my-script.”
<checkpoint name="my-script"
desc="my new script"
mod_path="solaris_install/distro_const/checkpoints/custom_script"
checkpoint_class="CustomScript">
<args>/tmp/myscript.sh</args>
</checkpoint>Here {PKG_IMAGE_PATH} is specified as the build parameter in the arguments section.
<checkpoint name="my-script"
desc="my new script"
mod_path="solaris_install/distro_const/checkpoints/my_script"
checkpoint_class="CustomScript">
<args>/tmp/myscript.sh {PKG_IMAGE_PATH}</args>
</checkpoint>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.
You can build the image in one step. Or, to check the status of the build, you can stop and restart the build at various checkpoints.
For instructions, see Chapter 3, Building an Image.
The build output displays the location of log files.
|