Creating an AI Manifest at Client Installation Time

An alternative to creating custom AI manifests prior to client installation is to write a script that dynamically creates an AI manifest for each client at client installation time. The script can query environment variables and other client configuration information to create a custom AI manifest for each client. Because the manifest is based on attributes of each client discovered at installation time, the manifest is called a derived manifest.

A derived manifest is especially useful if you have a large number of systems that can be installed almost identically so that the AI manifests for these systems have relatively small differences. Create an AI manifest that specifies the installation parameters that are common to this group of systems. Using this common manifest as a base, create a derived manifests script that adds the parameters that are different for each client to the common manifest when each client is installed. For example, a derived manifests script can detect the number and size of disks attached to each client system and modify the AI manifest at client installation time to specify a custom disk layout for each client.

How to Create and Apply a Derived Manifests Script

Select a manifest to modify.
Identify an existing AI manifest to use as a base manifest to modify.
To develop and test your script, you can work with a local copy. At installation time, the base manifest must be accessible by each client that uses this derived manifests script.
Write a script to modify the manifest.
Write a script to dynamically modify the base manifest at installation time based on attributes of the client being installed.
Add the script to the install service.
Add the derived manifests script to the appropriate AI install service, specifying criteria that define which clients should use this script to create their installation instructions at installation time. If you do not want to specify client selection criteria, you can add this script as the default AI manifest for the service.
AI executes the script at client installation time to produce an instance of an AI manifest. AI syntactically validates the resultant manifest.

Note - If a manifest is not created or the derived manifest does not validate, the client installation aborts. To investigate the cause of the validation failure, see the /system/volatile/install_log on the client.

If the client installation is successful, the derived manifest is copied to /var/log/install/derived/manifest.xml on the client, and the script used to derive the manifest is copied to /var/log/install/derived/manifest_script.

Creating a Derived Manifests Script

In general, a derived manifests 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 manifests script can also combine multiple partial AI manifests. The final derived manifest must be complete and must pass validation.

A derived manifests 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 manifests 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 Part III, Roles, Rights Profiles, and Privileges, in Oracle Solaris 11.1 Administration: Security Services.

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

Table 10-1 Client Attribute Environment Variables

Environment Variable Name	Description
`SI_ARCH`	The architecture of the client to be installed. Equivalent to the output of `uname -p`.
`SI_CPU`	The ISA or processor type of the client to be installed. Equivalent of the output of `uname -p`.
`SI_NUMDISKS`	The number of disks on the client.
`SI_DISKNAME_#`	A flat set of variables representing the names of the disks found on the client. There will exist `SI_NUMDISKS` number of `SI_DISKNAME_#` variables, where the `#` is replaced by an integer starting at 1, up to `SI_NUMDISKS`. This set of variables correlates with the set of variables described by `SI_DISKSIZE_#`.
`SI_DISKSIZE_#`	A flat set of variables representing the disk sizes of the disks found on the client. There will exist `SI_NUMDISKS` number of `SI_DISKSIZE_#`variables, where the `#` is replaced by an integer starting at 1, up to `SI_NUMDISKS`. This set of variables correlates with the set of variables described by `SI_DISKNAME_#`. The sizes are integer numbers of megabytes.
`SI_HOSTADDRESS`	The IP address of the client as set in the install environment.
`SI_HOSTNAME`	The host name of the client as set in the install environment.
`SI_KARCH`	The kernel architecture of the client. Equivalent to the output of `uname -m`.
`SI_INSTALL_SERVICE`	The name of the install service used to obtain the manifest script. This environment variable has a value only for network boots, not for media boots.
`SI_MANIFEST_SCRIPT`	The URL of the manifest script.
`SI_MEMSIZE`	The amount of physical memory on the client. The size is an integer number of megabytes.
`SI_NATISA`	The native instruction set architecture of the client. Equivalent to the output of `isainfo -n`.
`SI_NETWORK`	The network number of the client. The network number is (`IP_ADDR` & `netmask`).
`SI_PLATFORM (or SI_MODEL)`	The platform of the client. Equivalent to the output of `uname -i` for x86 systems and `prtconf -b` for SPARC systems.

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 manifests script will be added:

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

The # is an integer such as 1. 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 manifests script will be added:

$ installadm list -n svcname

Use the load subcommand of the aimanifest command to load a base manifest before any other aimanifest call in the derived manifests 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.

Note - If a value specified in an aimanifest command contains one of the following characters, then that value must be enclosed in single or double quotation marks to prevent the character from being interpreted as part of the XML path name:

/'"@[]=

The quotation marks might need to be escaped with a preceding backslash character (\) according to the rules of the shell used, so that the shell does not remove or interpret the quotation marks.

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

Tip - As a best practice, set up a trap to stop on error.

The following partial script is a good model for a derived manifests 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 Manifests Scripts

This section shows how to write derived manifests 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:

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, or set subcommand opens, modifies, and saves the AIM_MANIFEST file. If AIM_MANIFEST is not set, aimanifest commands fail.
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_MANIFEST_LOG file if set.
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.
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 manifests script to use.

Example 10-1 Specifying Disk Partitioning Based on Disk Size

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>

Example 10-2 Specifying the Root Pool Layout Based on the Existence of Additional Disks

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 manifests 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>

Example 10-3 Specifying a Mirrored Configuration If at Least Two Disks of a Specified Size Are Present

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 manifests 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()

Example 10-4 Specifying Packages to Install Based on IP Address

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 manifests 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

Example 10-5 Specifying that the Target Disk Must Be At Least a Certain Size

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 manifests 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

Example 10-6 Script With Incorrect Manifest Specifications

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.

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.
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.
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 Manifests Scripts

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

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 manifests script will be added:
```
<!DOCTYPE auto_install SYSTEM "file:///imagepath/auto_install/ai.dtd.#">
<auto_install/>
```
  The # is an integer such as 1. 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 manifests script will be added:
```
$ installadm list -n svcname
```
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.
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.
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.
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 manifests 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.
Set environment variables in the test environment with values that represent the client systems that will be installed using this derived manifests 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 manifests script to use.

The intended client system might be very different from the install server or other system where you might test the derived manifests 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 Manifests Script

This procedure describes how to test the derived manifests script on one of the intended client systems.

Boot an AI image on that client system.
Boot an AI image on that client system in “Text Installer and command line” mode.
Select Shell from the installer initial menu.
Copy your script from the AI install server.
Use wget or sftp to copy your script from the AI install server.
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
```
Copy the script back to the install server.
Copy the script back to the install server, if changes have been made.

Adding a Derived Manifests Script to an Install Service

Add a script to an AI install service in the same way that you add an XML manifest to the install service. Use the same options to specify criteria to select which clients will use this script to create a manifest for their installation. You can update a script just as you can update an XML manifest. A script can be set to be the default manifest for the service. Scripts are shown when you list manifests associated with a service. The contents of a script can be exported just as an XML manifest can be exported.

When you add an XML manifest to an install service, the manifest is validated. When you add a script to an install service, the script is not validated.

Validate a derived AI manifest before adding the script to an install service.

Run the script in an environment similar to the intended client system.
Use the validate subcommand on the resulting manifest.
```
$ /usr/bin/aimanifest validate
```
Messages are displayed only if the validation fails.

Add the script to the appropriate AI install service, specifying criteria that define which clients should use these installation instructions. If you do not want to specify client selection criteria, you can use the -d option to add this script as the default AI manifest for the service.

$ pfexec installadm create-manifest -n solaris11_1-i386 -f ./mac1.ksh -m mac1 \
-c mac=BB:AA:AA:AA:AA:AA

You can specify multiple -c options or one -C file. See also the set-criteria subcommand. See Chapter 9, Customizing Installations for information about specifying client criteria.

See Maintaining an Install Server for information about the installadm list, export, create-manifest, set-criteria, update-manifest, and set-service subcommands.

Skip Navigation Links
Exit Print View
	Installing Oracle Solaris 11.1 Systems Oracle Solaris 11.1 Information Library