Creating a Derived Manifest Script

In general, a derived manifest script retrieves information from the client and uses that information to modify a base AI manifest to create a custom AI manifest just for this client. A derived manifest script can also combine multiple partial AI manifests. The final derived manifest must be complete and must pass validation.

A derived manifest script can be any kind of script that is supported in the image. For example, ksh93 and python are in the image by default. If you want to use another kind of script, make sure the required support is in the image.

Retrieving Client Attributes

The derived manifest script can run commands to read system attributes. AI runs the script as role aiuser. The aiuser role has all the privileges of a non-privileged user plus the following additional privileges:

solaris.network.autoconf.read
solaris.smf.read.*

The aiuser role is non-privileged except that it can read more information from the system than other non-privileged users. The aiuser role cannot change the system.

For information about roles, profiles, and privileges, see Securing Users and Processes in Oracle Solaris 11.2 .

In addition to using commands to read system attributes, attributes of the client are available through the environment variables shown in the following table.

Customizing the AI Manifest

To add or modify XML elements in an AI manifest, use the /usr/bin/aimanifest command.

A file to be modified by aimanifest must contain at least the following pieces:

• A !DOCTYPE reference to a DTD that is valid for the XML manifest being developed.

• The root element for this DTD.

The following example shows the minimum base manifest file for an AI manifest, including specifying the AI DTD file for the install service where this derived manifest script will be added:

<!DOCTYPE auto_install SYSTEM "file:///imagepath/auto_install/ai.dtd.1">
<auto_install/>

The value of the imagepath argument is the path returned by the following command, where svcname is the name of the install service where this derived manifest script will be added:

$ installadm list -v -n svcname

Use the load subcommand of the aimanifest command to load a base manifest before any other aimanifest call in the derived manifest script. Any files that you load must be accessible by the client at client installation time. For example, you could load a manifest from imagepath/auto_install/manifest/ in the target install service.

The examples in this chapter load the file /usr/share/auto_install/manifest/default.xml. The sample manifests in /usr/share/auto_install/manifest/ could be different from the manifests in the target install service. In production work, you should not load manifests from /usr/share/auto_install/manifest/.

The load subcommand can also be used to load or insert partial manifests.

Use the add subcommand to add new elements. Use the set subcommand to add element attributes or change element or attribute values. See the aimanifest(1M) man page for details. The man page and the example scripts that follow provide examples of using the aimanifest command.

/'"@[]=

The following example returns the action of the software_data element that contains the package name pkg:/entire. In this example, quotation marks are needed around pkg:/entire because the forward slash character is a special character. The backslash characters are needed to escape the quotation marks if this command is invoked in a shell script such as a ksh93 script.

# /usr/bin/aimanifest get software_data[name=\"pkg:/entire\"]@action

The following partial script is a good model for a derived manifest script:

#!/bin/ksh93

SCRIPT_SUCCESS=0
SCRIPT_FAILURE=1

function handler
{
    exit $SCRIPT_FAILURE
}

trap handler ERR

/usr/bin/aimanifest load baseAImanifest.xml

# Customize AI manifest. For example:
/usr/bin/aimanifest load -i manifest_fragment.xml
/usr/bin/aimanifest set origin@name file:///net/myserver/myrepo/repo.redist

exit $SCRIPT_SUCCESS

Examples of Derived Manifest Scripts

This section shows how to write derived manifest scripts to determine client attributes and use that information to customize the AI manifest. These examples do not necessarily include all the information required to produce a valid AI manifest.

To try these examples, perform the following setup steps:

1. Set the AIM_MANIFEST environment variable to a location where the script will develop the AI manifest.

   The $AIM_MANIFEST file is rewritten for each aimanifest command that modifies the file. Each invocation of aimanifest with the load, add, delete, or set subcommand opens, modifies, and saves the AIM_MANIFEST file. If AIM_MANIFEST is not set, aimanifest commands fail.

2. Set the AIM_LOGFILE environment variable to a location where the script can write verbose information and error messages.

   The aimanifest command logs the name of the subcommand, argument values, and return status of each aimanifest call to the screen and to the $AIM_LOGFILE file if set.

3. Make sure the aimanifest command is available on the system where you run the script. If the aimanifest command is not available, install the auto-install-common package.

4. Set environment variables. These examples demonstrate using environment variables to retrieve information about the client. To try these examples, you must set values for these environment variables.

   When you install a system using AI, the environment variables shown in Table 10–1 have values and are available for a derived manifest script to use.

This example customizes the AI manifest to use only half of the target disk on an Oracle Solaris fdisk partition if the size of the disk is greater than 1 TB. Try setting SI_DISKSIZE_1 to less than 1 TB and then greater than 1 TB for different runs of this script. Also set SI_NUMDISKS and SI_DISKNAME_1 before you run the script. Note that this script is only for use with x86 clients because the specified partitioning only applies to x86 clients.

#!/bin/ksh93

SCRIPT_SUCCESS=0
SCRIPT_FAILURE=1

function handler
{
    exit $SCRIPT_FAILURE
}

trap handler ERR

/usr/bin/aimanifest load /usr/share/auto_install/manifest/default.xml

# Check that there is only one disk on the system.
if [[ $SI_NUMDISKS -gt "1" ]] ; then
    print -u2 "System has too many disks for this script."
    exit $SCRIPT_FAILURE
fi

/usr/bin/aimanifest add \
    /auto_install/ai_instance/target/disk/disk_name@name $SI_DISKNAME_1

if [[ $SI_DISKSIZE_1 -gt "1048576" ]] ; then
    typeset -i PARTN_SIZE=$SI_DISKSIZE_1/2

    # Default action is to create.
    /usr/bin/aimanifest add \
        /auto_install/ai_instance/target/disk[disk_name@name=\"$SI_DISKNAME_1\"]/partition@name 1
    /usr/bin/aimanifest add \
        /auto_install/ai_instance/target/disk/partition[@name=1]/size@val \
        ${PARTN_SIZE}mb
else
    /usr/bin/aimanifest add \
        /auto_install/ai_instance/target/disk[disk_name@name=\"$SI_DISKNAME_1\"]/partition@action \
        use_existing_solaris2
fi
exit $SCRIPT_SUCCESS

For clients where the value of SI_DISKSIZE_1 is less than or equal to 1048576, the following elements are added to $AIM_MANIFEST:

<target>
  <disk>
    <disk_name name="/dev/dsk/c0t0d0s0"/>
    <partition action="use_existing_solaris2"/>
  </disk>
  <!-- <logical> section -->
</target>

For clients where the value of SI_DISKSIZE_1 is greater than 1048576, elements similar to the following are added to $AIM_MANIFEST, depending on the value of SI_DISKSIZE_1:

<target>
  <disk>
    <disk_name name="/dev/dsk/c0t0d0s0"/>
    <partition name="1">
      <size val="524288mb"/>
    </partition>
  </disk>
  <!-- <logical> section -->
</target>

The disk_name is specified in the command to add the partition to avoid creating a separate disk specification for the partition. The script in this example specifies that the partition is on the $SI_DISKNAME_1 disk, not on a different disk. If the appropriate lines in this example are replaced by the following lines, you do not get the result you intend:

    /usr/bin/aimanifest add \
        /auto_install/ai_instance/target/disk/partition@name 1
    /usr/bin/aimanifest add \
        /auto_install/ai_instance/target/disk/partition[@name=1]/size@val \
        ${PARTN_SIZE}mb
else
    /usr/bin/aimanifest add \
        /auto_install/ai_instance/target/disk/partition@action \
        use_existing_solaris2

Instead of the output shown above, this script would give you the following incorrect output:

<target>
  <disk>
    <disk_name name="c0t0d0s0"/>
  </disk>
  <disk>
    <partition name="1">
      <size val="524288mb"/>
    </partition>
  </disk>
</target>

This example customizes the AI manifest to configure a mirror of the root pool if a second disk exists, and configure a three-way mirror if a third disk exists. Set SI_NUMDISKS and SI_DISKNAME_1 before you run the script. Set SI_DISKNAME_2, SI_DISKNAME_3, and any others as necessary, depending on the value you set for SI_NUMDISKS. These environment variables will be set and available to derived manifest scripts during AI installations.

This example demonstrates using the aimanifest return path (–r option). See the aimanifest(1M) man page for more information about the return path.

#!/bin/ksh93

SCRIPT_SUCCESS=0
SCRIPT_FAILURE=1

function handler
{
    exit $SCRIPT_FAILURE
}

trap handler ERR

/usr/bin/aimanifest load /usr/share/auto_install/manifest/default.xml

# Use the default if there is only one disk.
if [[ $SI_NUMDISKS -ge 2 ]] ; then
    typeset -i disk_num

    # Turn on mirroring. Assumes a root zpool is already set up.
    vdev=$(/usr/bin/aimanifest add -r \
        target/logical/zpool[@name=rpool]/vdev@name mirror_vdev)
    /usr/bin/aimanifest set ${vdev}@redundancy mirror

    for ((disk_num = 1; disk_num <= $SI_NUMDISKS; disk_num++)) ; do
        eval curr_disk="$"SI_DISKNAME_${disk_num}
        disk=$(/usr/bin/aimanifest add -r target/disk@in_vdev mirror_vdev)
        /usr/bin/aimanifest set ${disk}@in_zpool rpool
        /usr/bin/aimanifest set ${disk}@whole_disk true
        disk_name=$(/usr/bin/aimanifest add -r \
            ${disk}/disk_name@name $curr_disk)
        /usr/bin/aimanifest set ${disk_name}@name_type ctd
    done
fi
exit $SCRIPT_SUCCESS

For a system with two disks named c0t0d0 and c0t1d0, the output of this example is the following XML element:

<target>
  <disk in_vdev="mirror_vdev" in_zpool="rpool" whole_disk="true">
    <disk_name name="c0t0d0" name_type="ctd"/>
  </disk>
  <disk in_vdev="mirror_vdev" in_zpool="rpool" whole_disk="true">
    <disk_name name="c0t1d0" name_type="ctd"/>
  </disk>
  <logical>
    <zpool name="rpool" is_root="true">
      <vdev name="mirror_vdev" redundancy="mirror"/>
      <filesystem name="export" mountpoint="/export"/>
      <filesystem name="export/home"/>
      <be name="solaris"/>
    </zpool>
  </logical>
</target>

This example customizes the AI manifest to specify a mirrored configuration if the system has at least two 200 GB disks. Use the first two disks found that are at least 200 GB. Set SI_NUMDISKS, SI_DISKNAME_1, and SI_DISKSIZE_1 in your test environment before you run the script. Also set SI_DISKNAME_2, SI_DISKSIZE_2, and any others as necessary, depending on the value you set for SI_NUMDISKS. These environment variables will be set and available to derived manifest scripts during AI installations.

This example shows how to modify a node when more than one node with the same path is present. The shell implementation uses the return path (–r) option of aimanifest to return the path to a specific node, and uses that path to make additional modifications to the same node. The Python implementation demonstrates the use of subpathing (using [] inside a node path) to make additional modifications to the same node.

#!/bin/ksh93

SCRIPT_SUCCESS=0
SCRIPT_FAILURE=1

function handler
{
    exit $SCRIPT_FAILURE
}

trap handler ERR

# Find the disks first.
typeset found_1
typeset found_2
typeset -i disk_num

for ((disk_num = 1; disk_num <= $SI_NUMDISKS; disk_num++)) ; do
    eval curr_disk="$"SI_DISKNAME_${disk_num}
    eval curr_disk_size="$"SI_DISKSIZE_${disk_num}
    if [[ $curr_disk_size -ge "204800" ]] ; then
        if [ -z $found_1 ] ; then
            found_1=$curr_disk
        else
            found_2=$curr_disk
            break
        fi
    fi
done

# Now, install them into the manifest.
# Let the installer take the default action if two large disks are not found.

/usr/bin/aimanifest load /usr/share/auto_install/manifest/default.xml

if [[ -n $found_2 ]] ; then
    # Turn on mirroring.
    vdev=$(/usr/bin/aimanifest add -r \
        /auto_install/ai_instance/target/logical/zpool/vdev@redundancy mirror)
    /usr/bin/aimanifest set ${vdev}@name mirror_vdev

    disk=$(/usr/bin/aimanifest add -r \
        /auto_install/ai_instance/target/disk@in_vdev mirror_vdev)
    disk_name=$(/usr/bin/aimanifest add -r ${disk}/disk_name@name $found_1)
    /usr/bin/aimanifest set ${disk_name}@name_type ctd

    disk=$(/usr/bin/aimanifest add -r \
        /auto_install/ai_instance/target/disk@in_vdev mirror_vdev)
    disk_name=$(/usr/bin/aimanifest add -r ${disk}/disk_name@name $found_2)
    /usr/bin/aimanifest set ${disk_name}@name_type ctd
fi

exit $SCRIPT_SUCCESS

The following script is a Python version of the preceding Korn shell version.

#!/usr/bin/python2.6

import os
import sys

from subprocess import check_call, CalledProcessError

SCRIPT_SUCCESS = 0
SCRIPT_FAILURE = 1

def main():

    # Find the disks first.
    found_1 = ""
    found_2 = ""

    si_numdisks = int(os.environ["SI_NUMDISKS"])
    for disk_num in range(1, si_numdisks + 1):
        curr_disk_var = "SI_DISKNAME_" + str(disk_num)
        curr_disk = os.environ[curr_disk_var]
        curr_disk_size_var = "SI_DISKSIZE_" + str(disk_num)
        curr_disk_size = os.environ[curr_disk_size_var]
        if curr_disk_size >= "204800":
            if not len(found_1):
                found_1 = curr_disk
            else:
                found_2 = curr_disk
                break

    # Now, write the disk specifications into the manifest.
    # Let the installer take the default action if two large disks are not found.

    try:
        check_call(["/usr/bin/aimanifest", "load",
            "/usr/share/auto_install/manifest/default.xml"])
    except CalledProcessError as err:
        sys.exit(err.returncode)

    if len(found_2):
        try:
            check_call(["/usr/bin/aimanifest", "add",
               "target/logical/zpool[@name=rpool]/vdev@redundancy", "mirror"])
            check_call(["/usr/bin/aimanifest", "set",
               "target/logical/zpool/vdev[@redundancy='mirror']@name", "mirror_vdev"])

            check_call(["/usr/bin/aimanifest", "add",
                "target/disk/disk_name@name", found_1])
            check_call(["/usr/bin/aimanifest", "set",
                "target/disk/disk_name[@name='" + found_1 + "']" + "@name_type", "ctd"])
            check_call(["/usr/bin/aimanifest", "set",
                "target/disk[disk_name@name='" + found_1 + "']" + "@in_vdev", "mirror_vdev"])

            check_call(["/usr/bin/aimanifest", "add",
                "target/disk/disk_name@name", found_2])
            check_call(["/usr/bin/aimanifest", "set",
                "target/disk/disk_name[@name='" + found_2 + "']" + "@name_type", "ctd"])
            check_call(["/usr/bin/aimanifest", "set",
                "target/disk[disk_name@name='" + found_2 + "']" + "@in_vdev", "mirror_vdev"])
        except CalledProcessError as err:
            sys.exit(err.returncode)

    sys.exit(SCRIPT_SUCCESS)

if __name__ == "__main__":
    main()

This example customizes the AI manifest to install one package if the IP address of the client is in a specified range, and install a different package if the IP address of the client is in a different range. Set SI_HOSTADDRESS in your test environment before you run the script. This environment variable will be set and available to derived manifest scripts during AI installations.

#!/bin/ksh93

SCRIPT_SUCCESS=0
SCRIPT_FAILURE=1

function handler
{
    exit $SCRIPT_FAILURE
}

trap handler ERR

/usr/bin/aimanifest load /usr/share/auto_install/manifest/default.xml

# First determine which range the host IP address of the client is in.
echo $SI_HOSTADDRESS | sed 's/\./ /g' | read a b c d

# Assume all systems are on the same class A and B subnets.

# If the system is on class C subnet = 100, then install the /pkg100 package.
# If the system is on class C subnet = 101, then install the /pkg101 package.
# Otherwise, do not install any other additional package.

if ((c == 100)) ; then
    /usr/bin/aimanifest add \
    software/software_data[@action='install']/name pkg:/pkg100
fi
if ((c == 101)) ; then
    /usr/bin/aimanifest add \
    software/software_data[@action='install']/name pkg:/pkg101
fi

exit $SCRIPT_SUCCESS

This example customizes the AI manifest to install only on a disk that is at least 50 GB. Ignore smaller disks. Set SI_NUMDISKS, SI_DISKNAME_1, and SI_DISKSIZE_1 in your test environment before you run the script. Also set SI_DISKNAME_2, SI_DISKSIZE_2, and any others as necessary, depending on the value you set for SI_NUMDISKS. These environment variables will be set and available to derived manifest scripts during AI installations.

#!/bin/ksh93

SCRIPT_SUCCESS=0
SCRIPT_FAILURE=1

function handler
{
    exit $SCRIPT_FAILURE
}

trap handler ERR

/usr/bin/aimanifest load /usr/share/auto_install/manifest/default.xml

typeset found
typeset -i disk_num
for ((disk_num = 1; disk_num <= $SI_NUMDISKS; disk_num++)) ; do
    eval curr_disk="$"SI_DISKNAME_${disk_num}
    eval curr_disk_size="$"SI_DISKSIZE_${disk_num}
    if [[ $curr_disk_size -ge "512000" ]] ; then
        found=$curr_disk
        /usr/bin/aimanifest add \
            /auto_install/ai_instance/target/disk/disk_name@name $found
        break
    fi
done

if [[ -z $found ]] ; then
    exit $SCRIPT_FAILURE
fi

exit $SCRIPT_SUCCESS

Sometimes a system configuration change is needed for each client. Rather than having to create an individual system configuration profile on the AI server for each client, you could configure a derived manifest script to create the profile for you. The profile must be stored in /system/volatile/profile in order for the install service to be able to use it. In this example the settings for the local default router are used when the client is reconfigured.

ROUTER-CONFIG=/system/volatile/profile/router-config.xml
ROUTER=`netstat -rn | grep "^default" | awk '{print $2}'`

cat<<EOF>${ROUTER-CONFIG}
<!DOCTYPE service_bundle SYSTEM "/usr/share/lib/xml/dtd/service_bundle.dtd.1">
 <service_bundle type="profile" name="router">
   <service name="network/install" version="1" type="service">
     <instance name="default" enabled="true">
       <property_group name="install_ipv4_interface" type="application">
         <propval name="default_route" type="net_address_v4" value="${ROUTER}"/>
       </property_group>
     </instance>
   </service>
 </service_bundle>
EOF

The script in this example contains errors.

#!/bin/ksh93

SCRIPT_SUCCESS=0
SCRIPT_FAILURE=1

function handler
{
    exit $SCRIPT_FAILURE
}

trap handler ERR

/usr/bin/aimanifest load /usr/share/auto_install/manifest/default.xml

/usr/bin/aimanifest set \
    software[@type="IPS"]/software_data/name pkg:/driver/pcmcia
/usr/bin/aimanifest set \
    software/software_data[@name=pkg:/driver/pcmcia]@action uninstall

return $SCRIPT_SUCCESS

This example has three problems with writing to $AIM_MANIFEST.

1. The set subcommand of aimanifest can change the value of an existing element or attribute or create a new attribute. The set subcommand cannot create a new element. The first set subcommand attempts to modify an existing package name in the manifest instead of creating a new package name. If more than one package name already exists in the manifest, an ambiguity error results because the package to be modified cannot be determined. The first set subcommand in this example should have been an add subcommand.

2. In the second set subcommand in this example, an element name with value pkg:/driver/pcmcia is specified with a preceding @ sign. Although attribute values are specified with a preceding @ sign, element values are not.

3. The value pkg:/driver/pcmcia should be enclosed in quotation marks. Values with slashes or other special characters must be quoted.

The following lines should replace the two set lines in this example:

/usr/bin/aimanifest add \
    software[@type="IPS"]/software_data@action uninstall
/usr/bin/aimanifest add \
    software/software_data[@action=uninstall]/name pkg:/driver/pcmcia

These two add subcommands add the following lines to the end of the software section of the manifest that is being written:

<software_data action="uninstall">
  <name>pkg:/driver/pcmcia</name>
</software_data>

Testing Derived Manifest Scripts

To test your derived manifest script, run the script in an environment similar to the AI installation environment.

1. Set up a base AI manifest for the script to modify.

   1. Make sure the first aimanifest command in your script is an aimanifest load command. Make sure the file being loaded contains a <!DOCTYPE> definition that specifies the appropriate DTD to use for AI manifest validation for the target install service. The following example shows the minimum base manifest file for an AI manifest, including specifying the AI DTD file for the install service where this derived manifest script will be added:

      <!DOCTYPE auto_install SYSTEM "file:///imagepath/auto_install/ai.dtd.1">
      <auto_install/>

      The value of the imagepath argument is the path returned by the following command, where svcname is the name of the install service where this derived manifest script will be added:

      ---

      Note -  Make sure to reset the imagepath to the default path, ///usr/share, before trying to use the script on a client.

      ---

      $ installadm list -v -n svcname| grep Image

   2. Set AIM_MANIFEST to a location where the script will develop the AI manifest. This location must be writable by the non-privileged user aiuser.

      ---

      Note - When AI is doing the installation, AIM_MANIFEST does not need to be set. AI sets a default value.

      ---

2. Set AIM_LOGFILE to a location where the script can write verbose information and error messages. This location must be writable by the non-privileged user aiuser.

   ---

   Note - When AI is doing the installation, AIM_LOGFILE does not need to be set. This log information is part of the larger installation log, /system/volatile/install_log.

   ---

3. Make sure the aimanifest command is available on the system where you test the script. If the aimanifest command is not available, install the auto-install-common package.

4. Set environment variables in the test environment with values that represent the client systems that will be installed using this derived manifest script. The sample file /usr/share/auto_install/derived_manifest_test_env.sh can be used as a template. Change the values as applicable.

   When AI is doing the installation, the environment variables shown in Table 10–1 have values and are available for a derived manifest script to use.

5. Make sure you are able to assume the root role. From the root role, you can assume the aiuser role without specifying a password.

   $ su
   Password: 
   # su aiuser -c ./script
   # 

   AI executes the derived manifest script as role aiuser. To approximate the AI installation environment, assume the aiuser role to run the script. If you run the script as a user with different privileges than the aiuser role has, some operations in the script might have different results.

6. Use the validate subcommand on the resulting manifest.

   $ /usr/bin/aimanifest validate

   Messages are displayed only if the validation fails.

The intended client system might be very different from the AI server or other system where you might test the derived manifest script. Commands that you call in the script might be unavailable or might be a different version with different behavior. The systems might be different architectures or have different number and sizes of disks. Setting environment variables in the test environment as described addresses some of these differences.

How to Test the Derived Manifest Script in an Install Environment

This procedure describes how to test the derived manifest script on one of the intended client systems without running the full installation process.

1. Boot an AI image on that client system.

   Boot an AI image on that client system in “Text Installer and command line” mode.

2. Select Shell from the installer initial menu.
3. Copy your script from the AI server.

   Use wget or sftp to copy your script from the AI server.

4. Debug the script.

   Use one of the following methods to debug the script:

   • Run the script manually.
   • Run AI in a test mode.

     Use the following command to run AI in a test mode:

     $ auto-install -m script -i

   Inspect the AI log file /system/volatile/install_log. The log file should contain the following line to indicate that the script validates:

   Derived Manifest Module: XML validation completed successfully

5. Copy the script back to the AI server.

   Copy the script back to the AI server, if changes have been made.