Export

View

Flag Day: AI Manifest Changes

Changes To AI Manifest for AI

Overview

In a recent push to Caiman we have changed the Auto Install Manifest format to provide better support for selection of targets. This is an update from the Solaris 11 Express release's format.

We have updated the Target specification significantly, making it simpler, yet more functional if you wish to do more than the basic install.

We also made a minor change to the Software nodes to more correctly reflect its expected behaviour.

This document tries to outline these changes.

Actions

As a result of this change there are several task that people will need to perform to be able to use this update:

Ensure you are running your AI server on a very recent build - this should not prevent you from serving older AI client configurations.

Update your AI XML manifest to reflect the changes in the format, details on this are documented below.

If using the default.xml, because of some changes in that file, please ensure you are using the current version for snv_167 onwards. The file is located at:
- /usr/share/auto_install/default.xml

Changes in Target Nodes

The <target> section of the manifest changed in the following ways:

The <target_spec> tag has been removed since it was felt it provided no real function.

The <swap> and <dump> tags have been removed in favour of specifying attributes on a <zvol>

<zpool> tags have been moved into a new <logical> section.

On X86, slices can only be specified within a <partition> tag.

You can influence the automatic creation of a swap or dump device via attributes of the <logical> tag.

A zpool consists of several <vdev> groups, each with its own redundancy type.

To specify what disk, partition or slice is included in a <vdev> group you specify the attributes in_zpool and/or in_vdev. The values of these need to be able to uniquely identify the vdev in a zpool.

It’s no longer possible to specify that a slice is_root, to achieve this you now add that slice to zpool that has the attribute is_root by specifying that zpools name and/or vdev name in the in_zpool and in_vdev attributes of the slice.

Filesystems (ZFS datasets) may be created as being contained within a BE, so that each BE has a separate version of that dataset. This is done by specifying the in_be attribute on a <filesystem> tag.

The <partition> action use_existing is now changed to use_existing_solaris2 to more accurately reflect its meaning.

It is now possible to set the name of the new Boot Environment using the <be name="be_name"> tag within the root pool definition.

In all cases when specifying partitions or slices, if there are prior existing if either, these will be merged into what is specified in the manifest - the aim being to cause "least damage".
- If you wish to really delete existing slices or paritions, you will need to specify these.
- Order does tend to be important, best to delete first, create partitions with specific sizes next, and finally if you want to allocate rest of disk to another, put it last.
- There is no need to delete a partition you're creating - the assumption is to delete it if it's the same name and you want to create it.

Removal of DTDs in /usr/share/auto_install

For Solaris 11 Express an AI Manifest would have referenced the DTDs in the directory:

/usr/share/auto_install

Part of the change in the format of the AI manifest is to switch to using an XML DTD schema that shares elements with Distro Constructor.

In doing this, the new DTDs have been placed in a common directory:

/usr/share/install

For example:

<!DOCTYPE auto_install SYSTEM "file:///usr/share/auto_install/ai.dtd">

You should change these references at the top of your AI XML files, to read more like:

<!DOCTYPE auto_install SYSTEM "file:///usr/share/install/ai.dtd">

Conversion Utility

To help people migrate pre-167 versions of their AI manifests, a utility is provided that transforms the existing AI manifest to the newer format using XSLT.

The utility is provided in the install sources (slim_source) in the directory:

usr/src/cmd/auto-install/xslt

If you don't know how to access the sources, you can also down load the files from:

http://src.opensolaris.org/source/xref/caiman/slim_source/usr/src/cmd/auto-install/xslt/

or by right-clicking on the files:

and saving them.

The aim with the script is to lessen the load when migrating existing AI manifests, some manual editing may still be required, depending on your use of the manifest.

To convert a 151a up to 166 version of the AI manifest to the new version in 167, please run the new_to_newer.py script, the usage of this command is:

new-to-newer.py - Convert old-style XML AI Manifests to the new schema.

For convenience, the command-line interface has similar semantics to cp(1).

Usage:
        new-to-newer.py [options] infile outfile
        new-to-newer.py [options] infile... outdir
        new-to-newer.py -r [options] indir... outdir

Options:
       -f        : force overwrite if output already exists
       -r        : recursively transform .xml files in named sub-directory
       -h --help : print this help page and exit

After converting your manifests you should run the command:

xmllint -valid <file>

to see if the file you are using validates before using it to install your client.

Examples

Some examples of what this now looks like are:

Example 1: Specify to use the whole of a specific disk and no swap or dump

Example 2: Specify to delete existing slices on SPARC

Example 3: Specify to delete existing partitions, preserving 1 on X86

Example 4: Specify two whole disks for inclusion in the root pool

Example 5: Specify two disks in a root pool with a hot-spare and a cache disk

<target>
  
  <disk whole_disk="true" in_zpool="myroot" in_vdev="mymirrored">
    <disk_name name="c7d0" name_type="ctd"/>
  </disk>
  <disk whole_disk="true" in_zpool="myroot" in_vdev="mymirrored">
    <disk_name name="c7d1" name_type="ctd"/>
  </disk>
  <disk whole_disk="true" in_zpool="myroot" in_vdev="myspare">
    <disk_name name="c8d0" name_type="ctd"/>
  </disk>
  <disk whole_disk="true" in_zpool="myroot" in_vdev="mycache">
    <disk_name name="c8d1" name_type="ctd"/>
  </disk>
  <logical>
    <zpool name="myroot" is_root="true" action="create">
      <vdev name="mymirrored" redundancy="mirror"/>
      <vdev name="myspare" redundancy="spare"/>
      <vdev name="mycache" redundancy="cache"/>
    </zpool>
  </logical>
</target>

Example 6: Specify a root pool with one disk, and a data pool with two disks

Example 7: Specify a root pool with 1 disk, and a data pool with two mirrored disks and 2 mirrored logs

Example 8: Automatic selection of disk, but layout the root pool, adding some datasets.

Example 9: Define a root pool, with one whole-disk, and one slice on a disk, and define specific swap and dump zvols rather than automatic creation

Changes in Software Node

In the <software> node, it was possible to specify different install types on the <software_data> node, but this would later fail since its not a supported configuration and you can only specify one type of install per <software> node.

So the change made here was to move the type attribute from the <software_data> node to the <software> node since it more accurately reflects what is possible. To perform multiple install types, you need to repeat the <software> section.

An example of this would be:

<software type="IPS">
<source>
   <publisher name="solaris">
     <origin name="http://pkg.oracle.com/solaris/release"/>
   </publisher>
</source>

<software_data action="install">
   <name>pkg:/entire</name>
   <name>pkg:/babel_install</name>
</software_data>

<software_data action="uninstall">
   <name>pkg:/babel_install</name>
   <name>pkg:/slim_install</name>
</software_data>
</software>
<software type="IPS">
   
</software>

Tags:

Created by Darren Kenny on 2011/05/26 11:59

Last modified by Ethan Quach on 2011/06/16 22:43