Most of the default values in the sample manifests would work on any environment. However, some sections might require specific configurations appropriate to your setup.
In certain sections of the manifests, elements are defined twice to provide you with alternative attribute configurations. The alternative definitions are inside comment marks. To use the alternative option, you remove the comment marks and set the correct values to the attributes. See the example in Providing the Image Title.
The distro name element enables you to provide a custom name for the image. For example:
<distro name="Oracle_Solaris_Text_X86" add_timestamp="false">
<!-- Uncomment if http_proxy needs to be set
<distro name="Oracle_Solaris_Text_X86" add_timestamp="false"
http_proxy="http://example.com">
-->
The add_timestamp attribute determines whether a time stamp is appended to the image name. It enables you to retain a series of builds of the same image.
A second distro name definition inside comment marks enables you to specify an HTTP proxy. To use, remove the comment marks and then provide the proxy location. Then, remove the first option.
In Oracle Solaris 11.4, long image names are truncated to 32 characters at the end of the process.
The boot_mods element specifies boot menu modifications associated with the image.
In the following example, a specialized boot menu with the title boot1 is applied to the image. Based on timeout, the default boot entry is automatically activated within 5 seconds.
<boot_mods title="boot1" timeout="5">
You can add individual boot menu entries by using boot_entry sub-elements. For boot entry attributes, title_suffix is required, while the following are optional:
default_entry – sets the boot entry to be the default entry. This attribute is normally set to false.
insert_at – determines the entry's position on the menu list: at the beginning if set to start or at the end if set to end. By default, a new entry is added at the end of the list.
The following example shows a boot_entry configuration. The entry will be inserted at the end of the menu list. Also, the entry is not designated to be the default entry.
The arguments variable refers to kernel settings that are passed to the kernel by the boot loader.
<boot_entry default_entry="false" insert_at="end"> <title_suffix>title</title_suffix> <kernel_args>arguments</kernel_args> </boot_entry>
The target element defines the ZFS build dataset where the image is created. You must provide a valid dataset location. Check the default build area to make sure that the build does not destroy content that you need to keep on your system. The path to the dataset is relative to the pool name defined. In the following example, the dataset would be installed as rpool/dc/sample-dataset-location.
<target>
<logical>
<zpool action="use_existing" name="rpool">
<dataset>
<filesystem name="dc/sample-dataset-location"
action="preserve"/>
</dataset>
</zpool>
</logical>
</target>
The software section of the manifest contains software node names under which elements and attributes enable you to define additional settings.
Software and package parameters are defined under the following heading:
<software name="transfer-ips-install" type="IPS">
To specify publisher information such as name, origin, and mirror settings, look for the source element. You can specify multiple publishers, as shown in the example.
The source element is followed by software_data where you add the names of packages to form the installed image. You can add multiple packages as needed.
By default, the most current package version available in the specified repository is installed. If you want to install a different version, append the version number to the package reference.
The following example shows how publishers and packages are defined in the manifest:
<source>for specifying publishers <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"> <origin name="file:///net/myserver/publisher4/repo"/> </publisher> </source> <software_data action="install">for specifying packages <name>pkg:/group/system/solaris-large-server</name> <name>pkg:/group/system/solaris-desktop@0.5.11-0.build#</name> </software_data>
To specify the default publisher to be set on the system after it has been installed, configure the elements under the following heading:
<software name="set-ips-attributes" type="IPS">
Here you can add not only the name of the default publisher, but also any mirror information. Note that other than publisher information, you would rarely configure other elements under this heading.
The execution element lists a series of checkpoints for the image construction process. Checkpoints identify moments in the building process where the tool performs actions as defined in corresponding software node names in the manifest. For example, at the transfer-ips-install checkpoint, the tool processes all the definitions under <software name="transfer-ips-install" type="IPS">.
Checkpoints are executed in the order in which they are listed under the execution element. During the image construction process, the checkpoints modify the contents of the build area that is specified in the manifest.
The build area consists of a pkg_image directory and a boot_archive directory. The contents of the final image are 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 then added to the pkg_image directory.
By default, the following checkpoinst are predefined in the sample manifests:
Each checkpoint element includes the mod-path attribute that specifies where the checkpoint script is located.
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 build the image. It 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. 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 kwargs list item is enclosed in double quotes. If 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.
Example 1 Adding SVR4 Packages to An Installation ImageIn 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. This new checkpoint then 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 command with the path to the build area for the package image and the boot archive, respectively. In this example, the SVR4 packages will be installed into the package image directory.
Finally, the new checkpoint is referenced in the execution section. The checkpoint name can be any string, but for this example, the checkpoint_class value 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 Creating Hashes of the Media in an Installation ImageThe checksums checkpoint enables users to automatically generate hashes of the media generated by the distro_const command.
<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 element 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 the /usr/bindigest -l command. 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.