System Administration Commands ���������dc_manifest(4)
NAME
dc_manifest - Customizing fields in the manifests
for the distribution constructor
SYNOPSIS
� The following manifest files can be used to build
various Oracle Solaris images. These manifests
are included in the distribution-constructor
package.
�To build an x86 virtual machine image with
Oracle Solaris:
� /usr/share/distro_const/vmc/vmc_image.xml
� To build x86 Oracle Solaris OS images:
� /usr/share/distro_const/slim_cd/
all_lang_slim_cd_x86.xml
To build an x86 Oracle Solaris OS image with
limited languages:
/usr/share/distro_const/slim_cd/slim_cd_x86.xml
To build a SPARC text installer image:
/usr/share/distro_const/text_install/
text_mode_sparc.xml
To build an x86 text installer image:
/usr/share/distro_const/text_install/
text_mode_x86.xml
�To build SPARC automated installation images:
� /usr/share/distro_const/auto_install/
ai_sparc_image.xml
�To build x86 automated installations images:
� /usr/share/distro_const/auto_install/
ai_x86_image.xml
DESCRIPTION
You can use the distribution constructor to build
preconfigured Oracle Solaris images.
XML manifest files are used as input to the
distribution constructor. These manifests define the
image that the distribution constructor builds. Per the
list above, you can use different manifests to
build different kinds of images.
��
Use the distro_const command to build images,
referencing a manifest file in the command.
� If you want customize the image specifications,
copy a manifest file, customize the copy, and use
the copy as input for the distro_const command
when you build the image.
�Some of the more common fields to change in a
manifest include:
� * Names of the packages to be included in the image
� * Network location of the repository where packages
are stored
� * Name and location of scripts used to finalize the
��� the new image
�Note: When using the distribution constructor, you
can only create SPARC images on a SPARC system.
And, you can only create x86 images on an x86
system. And, the operating system release version
on your system must be the same release version
as the image that you are building.
�
PRIMARY MANIFEST FIELDS
� All the manifests include the following editable
fields.
�<distribution name="Oracle_Solaris">
����
�This field provides the name of Oracle_Solaris
����for the distribution, that is, the image, that you plan to
����build. You can leave this name or type a unique
����name for your distribution.
�
<build_area>
This field specifies the area where the image will
����be created. You must check that the path specified
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.
����If you do not want to use checkpointing, you can use
����either a regular mount point or a ZFS or UFS file system.
����Note - After an image has been created, the build area
����for that image has the following structure.
������<build_area>/build_data/pkg_image
�����������Package image area.
������<build_area>/build_data/boot_archive
�����������boot archive build area.
�����<build_area>/build_data/tmp
�����������Temporary directory used by the distribution
�����������constructor and by 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 (stderr). The "detail" log,
named detail-log-YYYY-MM-DD-HH-Mi-SS,
�����������contains informational output (stdout) and
errors. The console echos information in the
�����������"simple" log file.
�<distro_constr_flags>
������<stop_on_error>true</stop_on_error>
�� <checkpoint_enable>
��������������true
������</checkpoint_enable>
�</distro_constr_flags> �
������The <stop_on_error> field controls whether the build
������should stop if there is an error. The value is set at
true.
������Use checkpointing to insert optional pauses between
the steps of building an image.The value, true, in the
<checkpoint_enable> field enables checkpointing.
������Note: Checkpointing requires ZFS file systems.
������The <resume_from> attribute subfield for
������the <checkpoint_enable> field lets you specify
the step to resume the build from. This value would
be overridden by the distro_const command with
the -r option.
�����
Valid values for the <resume_from> field are the step
�����names. Use the distro_const command with the -l
�����option to list available step names.
ADDITIONAL MANIFEST FIELDS
All the manifests, except for the virtual machine
manifest, include the following editable fields.
�<pkg_repo_default_authority>
������<main url="http://pkg.openindiana.org/dev"
��� authname="openindiana.org"/>
�</pkg_repo_default_authority>
������This field specifies the location of an IPS repository.
The repository is made available by an IPS publisher,
also called an authority. The distribution constructor
retrieves packages from the repository when it builds
an image.
�����The repository location above is set at:
�����http://pkg.opensolaris.org/release
�����And, the authority (publisher) is set as opensolaris.org.
������Modify the URL and authname fields to point to a
different repository, if needed.
������If you want to use one or more mirrors for an authority,
������or publisher, uncomment the mirror subfield, and specify
������the mirror urls in this field: �����
������<mirror url="" />
�<pkg_repo_addl_authority>
������This field specifies a repository to be used when the
main repository is unavailable. This field uses the
same format as the main repository field.
�<packages>
�� <pkg name="pkg:/entire"/>
�� <pkg name="pkg:/slim_install"/>
�� <pkg name="pkg:/system/install/media/internal"/>
�</packages>
������This field lists the packages to be included in the
������image. The packages listed above will build the
Oracle Solaris Live CD image. If you have packages
that you want to add to the image, list your packages
in this field, one package per line.
Note: "entire" is an incorporation. "slim_install" is
a group package that contains many packages.
������The latest build available in the specified IPS
repository will be installed. If another build is
required, the build number has to be appended
to 'entire' in following form:
�����������<pkg_name="[email protected]#/>
�<post_install_remove_packages>
������<pkg name="babel_install"/>
<pkg name="slim_install"/>
�</post_install_remove_packages>
������
If you want to remove individual packages from a
cluster, list the individual packages in this field,
one package per line.
Note - The default manifest first installs the
babel_install package, then uninstalls it. babel_install
is a group package consisting of set of packages. When the
babel_install group package is installed, all the packages in
the group are installed. However, you cannot uninstall
individual packages that belong to a group package. By
uninstalling the group package definition, the individual
packages can be deleted later. babel_install is
used for convenience to install all the required
packages, but the package definition is not needed
once installation of packages is completed. The
default manifest removes the package definition,
so that further customization of the packages can
be done. slim_install is another group package. And,
slim_install is part of babel_install which is installed
by the default manifest. The default manifest then
uninstalls slim_install, in order to permit customization.
�<live_img_compression type="lzma"/>
������Use this field to specify how the solarismisc.zlib
archive will be compressed. Valid compression
types are lzma, gzip, and none.
�<grub_menu_modifications>
������You can edit the GRUB menu contents here
������and add a custom title to the menu. See the
comments in the manifest file for details.
�<boot_archive_contents>
������This section lists the files and directories that
������will be included in the boot archive for the image that
is built. See the comments in the manifest file for
information.
������Files or directories that need to be excluded from
the image are specified with the base_exclude
tag.
������Caution - Modifying the boot archive contents could
render the system unbootable. If you do add files or
directories, use the base_include tag as show in
the manifest and these examples:
<base_include type="file">
var/yp/nickname
</base_include>
<base_include type="dir">
kernel
</base_include>
������The boot archive for x86 images differs from the boot
������archive for SPARC images. The whole boot archive
for x86 images is a UFS filesystem,
������compressed by using gzip. The SPARC platform does
������not support the compression of the whole boot archive
������in this way. Instead, SPARC boot archives use DCFS,
������which compress each file individually. These
������individually compressed files might require specific
������handling in the manifest.
������During boot time, some of the files in the boot archive
������need to be modified. But, compressed files cannot be
������modified. Therefore, for SPARC images, you need to
������specify in the manifest which files should not be
������compressed. See the boot_archive_archive.py script,
referenced in the finalizer section of the manifest,
for the default list of boot_archive files which are not
compressed. You must explicitly list any file that needs
to be stored in the boot_archive in an uncompressed
state, and you must set that file's fiocompress attribute
to false.
FINALIZER SECTION
In all manifests, the <finalizer> section lists the
� finalizer scripts that the distribution constructor
� invokes when building an image, and the order in
� which the distribution constructor invokes them.
�Finalizer scripts transform the image into a
� media-specific distribution. A set of finalizer
� scripts are provided in the distribution-constructor
� package.
�All finalizer scripts are passed a standard set of five
arguments as their first arguments. See a finalizer
script header for more information. Some scripts,
such as those used to build virtual machine images,
require additional arguments. The are defined in the
<argslist> field within the <script_name> field, as
shown in the sample below. These arguments are
passed to the scripts beginning as the sixth argument.
You do have the option to write and add your own
scripts. If you do create new scripts, modify the
manifest to point to them.
� You do not need to edit the <finalizer> section
unless you add new finalizer scripts, or you
change the name or the argslist of existing scripts.
� The basic format for each script reference in the
� <finalizer> section is as follows:
� <finalizer>
...
<script name="/usr/share/distro_const/vmc/create_vm">
<checkpoint
name="create-vm"
message="create and configure a
virtual machine"/>
<argslist>
"16000"
"1536"
"opensolaris"
</argslist>
</script>�����
...
� </finalizer>
����������
The <script name> field provides the name and
� the location of a script.
The <checkpoint> field specifies a checkpoint
name and is required. This field is used to specify
a checkpoint when pausing and resuming a build.
The checkpoint name corresponds to the point in
the build just before the script associated with that
checkpoint is run. See the distro_const(1M) man
page.������
� The checkpoint message attribute is optional. The
� checkpoint message is displayed when the step is
run.
The <argslist> field provides arguments that are
required for that particular script to run. You can
edit these arguments.
�For information about the existing finalizer scripts,
creating and using custom finalizer scripts, and
� editing script arguments, see the Oracle Solaris
Distribution Constructor Guide at http://docs.sun.com
KEY VALUE PAIRS FIELD
�<key_value_pairs>
...
������<pair key="iso_sort"
�����������value="/usr/share/distro_const/slim_cd/
�����������slimcd_iso.sort"/>
�</key_value_pairs>
�������
This field provides additional specifications that
� are needed by the distribution constructor or by
�� finalizer scripts.
������You do not need to edit the key-value pairs
except to add new ones that will be recognized by
new or customized finalizer scripts.
������For information about using key-value pairs, see
the Oracle Solaris Distribution Constructor Guide
at http://docs.sun.com
ATTRIBUTES
��/usr/share/man/man4/dc_manifest4
��ATTRIBUTE TYPE �������ATTRIBUTE VALUE
��Availability ���������distribution-constructor
package
��Interface Stability ��In Development
SEE ALSO
�distro_const(1M) man page
� Oracle Solaris Distribution Constructor
Guide at http://docs.sun.com
Oracle Solaris �Last Changed September 27, 2010