AI Schemas and Manifests

h1. AI manifests and schema

+What is a Schema+

A Schema is XML document that describes, in a formal way, the syntax elements and parameters of a web language.

+What is a Manifest+

A Manifest is a file that contains metadata describing a set of actions to be taken and it conforms to the schema definition

h2. Automated Installer Schemas and Manifests

Automated Installer uses 3 kinds of schemas and manifests. They define an installation, a configuration and a criteria. As a user, you need to worry about only Manifests. If you are a developer, you may have to add new definitions in the schema. For now, let us talk about only manifests

h2. AI Manifest

AI manifest is an XML document that defines the installation. Some of the parameters defined are disk target, disk partitions and IPS repository. The AI manifest schema is based on relax NG syntax and is installed on the install server as part of the SUNWinstalladm package. A copy of the AI schema is available at /usr/share/lib/xml/rng/auto_install/ai_schema.rng (if SUNWinstalladm is installed on the system).

h2. SC Manifest

System Configuration manifest or SC manifest contains the information needed to configure system after installation is completed. Some of the configuration parameters supported are timezone, root password and adding a user/password to the installed system. The SC manifest will be handled eventually by SMF Enhanced profiles, which use a DTD syntax. However, the install code handles the above parameters in the 2008.11 release. A copy of the DTD schema is available at /usr/share/lib/xml/dtd/service_bundle.dtd.1

h2. Criteria manifest

The criteria manifest is the bridge that connects the AI manifest (and SC manifest) with a client. The administrator uses criteria manifest to add an AI manifest to a service. The client send its hardware characteristics to the install service and get a manifest that was assigned by the administrator. The criteria manifest schema can be found at /usr/share/lib/xml/rng/auto_install/criteria_schema.rng (if SUNWinstalladm is installed on the system).

h1. AI manifest Examples

* Simple example with disk target and IPS repository defined

For many users a simple configurations like this one is sufficient. In this example, only the target disk name and the IPS repository with authority is defined. The Automated Installer will choose the disk c0t0d0 and perform installation using the default set of packages from pkg.opensolaris.org. If your diskname is different, edit this file using your favorite editor and change c0t0d0 to your disk name. This also accepts MPXIO name such as c0t0000002037CD9F72d0. The same thing applies for the IPS repository and authorization. If your IPS repository is pkg.mycompany.com and authorization is mycompany.com then replace pkg.opensolaris.org to pkg.mycompany.com and opensolaris.org to mycompany.com.

{noformat}
<ai_manifest name="example1">
<ai_target_device>
<target_device_name>c0t0d0</target_device_name>
</ai_target_device>
<ai_pkg_repo_default_authority>
<main url="http://pkg.opensolaris.org" authname="opensolaris.org"/>
</ai_pkg_repo_default_authority>
<ai_packages>
</ai_packages>
</ai_manifest>
{noformat}

* An example with all the fields defined. Please note that not all the fields are implemented in the 2008.11 release.

In this example all fields of the AI manifest are defined. The values are given as an example, please change them to suit your environment.

ai_target_device defines the disk where the installation is performed. You can either define the target_device_name or one or more from target_device_type, target_device_vendor,and target_device_size. If you define target_device_name and other fields, only target_device_name is taken in to consideration and rest of the parameters are ignored. target_device_use_solaris_partition is used to indicate that whether to find a disk with solaris partition defined or find a disk with Solaris partition not defined. This is useful when you don't specify the disk by name and allow the installer to find a disk based on other parameters. target_device_overwrite_root_zfs_pool is for future use (I.e. Unimplemented for 2008.11)

{noformat}
<ai_manifest name="example_with_all_defined">
<ai_target_device>
<target_device_name>c0t0d0</target_device_name>
<target_device_type>SCSI</target_device_type>
<target_device_vendor>toshiba</target_device_vendor>
<target_device_size>20480</target_device_size>
<target_device_use_solaris_partition>true</target_device_use_solaris_partition>
<target_device_overwrite_root_zfs_pool>true</target_device_overwrite_root_zfs_pool>
</ai_target_device>
<ai_device_partitioning>
<partition_action>create</partition_action>
<partition_number>1</partition_number>
<partition_start_sector>200</partition_start_sector>
<partition_size>20480</partition_size>
<partition_type>191</partition_type>
</ai_device_partitioning>
<ai_device_vtoc_slices>
<slice_action>create</slice_action>
<slice_number>4</slice_number>
<slice_size>20480</slice_size>
</ai_device_vtoc_slices>
<ai_device_zfs_root_pool>
<enable_mirrored_root>true</enable_mirrored_root>
<zfs_options>xyz</zfs_options>
</ai_device_zfs_root_pool>
<ai_device_swap>
<ai_swap_size>2048</ai_swap_size>
</ai_device_swap>
<ai_pkg_repo_default_authority>
<main url="http://pkg.opensolaris.org" authname="opensolaris.org"/>
<mirror url=""/>
</ai_pkg_repo_default_authority>
<ai_packages>
<package_name>SUNWcsd</package_name>
</ai_packages>
<ai_packages>
<package_name>SUNWcs</package_name>
</ai_packages>
<ai_packages>
<package_name>slim_install</package_name>
</ai_packages>
</ai_manifest>
{noformat}

h1. SC manifest Example

As explained earlier, the SC manifest defines the configuration parameters of the system. For 2008.11 release, the only configuration supported are given in the following example. Just copy the file and make changes to the attributes to add different user/password, root password, and timezone. For 2008.11, use plain-text passwords in the manifest (encrypted passwords will come later).

{noformat}
<?xml version='1.0'?>
<!DOCTYPE service_bundle SYSTEM '/usr/share/lib/xml/dtd/service_bundle.dtd.1'>
<service_bundle type='profile' name='name'>

<service name='ai_properties' version='1' type='service'>
<instance name='default' enabled='false'>
<property_group name='ai' type='application'>
<propval name='username' type='astring' value='jack' />
<propval name='description' type='astring' value='default user' />
<propval name='userpass' type='astring' value='jack' />
<propval name='rootpass' type='astring' value='opensolaris' />
<propval name='timezone' type='astring' value='US/Pacific' />
</property_group>
</instance>
</service>
</service_bundle>
{noformat}

h1. Criteria Manifest Examples

Now we have AI manifest and SC manifest. How do you assign an AI manifest and a SC manifest to a a client? This requires:

# Creating an AI manifest
# Creating a SC manifest
# Creating a criteria manifest based on criteria of the client and with the location of AI and SC manifest inside the criteria manifest
# Add the criteria manifest to the install service by executing 'installadm add -m <manifest.xml> -n <service name>"

The steps of creating AI manifest and SC manifest is already discussed. The following section explores the creation of criteria manifest and how to tie a criteria with a set of manifests

<ai_criteria_manifest>

<ai_manifest_file URI="./ai_manifest1.xml"/>
<sc_manifest_file name="AI" URI="./sc_manifest1.xml"/>
</ai_criteria_manifest>
{noformat}

There are more examples in http://www.opensolaris.org/os/project/caiman/auto_install/AI_manifest_setup.html

h1. Customizing the installation using manifests

The client installations can be customized by assigning different manifests to different clients. The commands 'installadm add' will allow you to assign a specific manifest to a client. Only the AI manifest name from the XML ai_manifest tag, is registered with the AI database. The SC manifest will be part of the AI manifest and criteria manifest's name is not stored in the AI database. Following examples will show how this is done.

Create a criteria manifest along the lines of example a) and use the following commands.

{noformat}
# installadm list (will show the services running on a system)

The install services running on the system are:

service_102508

# installadm add -m criteria_mac.xml -n service_102508 (Will add the manifests and the criteria defined by criteria_mac.xml)

# installadm list -n service_102508 (Will show that the AI manifest and not the criteria added to the service)

Manifest
--------
ai_manifest1.xml

# installadm remove -m ai_manifest1 -n service_102508 (Will remove AI manifest ai_manifest.xml)
{noformat}