| Skip Navigation Links | |
| Exit Print View | |
|
man pages section 1M: System Administration Commands Oracle Solaris 11.1 Information Library |
| Skip Navigation Links | |
| Exit Print View | |
|
|
man pages section 1M: System Administration Commands Oracle Solaris 11.1 Information Library |
- Modify an XML file used by Automated Installer (AI)
/usr/bin/aimanifest [-h]
aimanifest add [-r] path value
aimanifest get [-r] path
aimanifest set [-r] path value
aimanifest load [-i] filename
aimanifest validate
The aimanifest command creates a new XML manifest or modifies an existing one. While aimanifest can be used with any XML file that contains a valid !DOCTYPE reference to a DTD definition, it is intended for creating derived manifests used by the Automated Installer (AI). See Installing Oracle Solaris 11 Systems for information about AI derived manifests.
The aimanifest command can be invoked multiple times to develop a manifest. The AIM_MANIFEST environment variable specifies the location of the manifest for aimanifest to modify. AIM_MANIFEST must be set. Each invocation of the aimanifest command with the load, add, or set subcommand opens, modifies, and saves the AIM_MANIFEST file.
The minimum AIM_MANIFEST file that the aimanifest command can modify must contain both of the following pieces:
A !DOCTYPE reference to a DTD that is valid for the XML manifest being developed.
The root element for this manifest.
If you start with an empty AIM_MANIFEST file, as when AI is executing a derived manifests script, then the first aimanifest command must specify the load subcommand to load at least the minimum required AIM_MANIFEST file. Subsequent aimanifest commands that modify the manifest use the DTD to determine where to add elements in the developing manifest.
To save error and informational messages to a file in addition to displaying messages to stdout and stderr, set the AIM_LOGFILE environment variable to a log file location. Information is appended to the log file. The log file is not cleared.
The aimanifest command has the following option:
Show the usage help message.
The add, get, and set subcommands of the aimanifest command have the following option:
Return the path of the XML element that this aimanifest command creates or operates on. This returned path is a chain of node IDs. You can save this returned path value to use in subsequent calls to aimanifest. Using the path returned by the -r option is more reliable than specifying the path using XML element and attribute values, since the values can change as the AI manifest is being built. See the “Return Paths” section for more information about the path returned by the -r option.
The load subcommand of the aimanifest command has the following option:
Do not clear the AIM_MANIFEST data before adding new data.
The following subcommands are supported:
Add a new element to an XML manifest. Add the new element at path and with value value. See the “Operands” section for more information about path. If path ends in an attribute (@attr), then the new element has the attr attribute, and value is the value of the attribute.
No validation is performed except to examine parent/child relationships in path.
The -r option returns a path to the newly-added node. See the “Return Paths” section for more information.
If the parent path matches an element in the AIM_MANIFEST file, it must match only one element. The new element is created as a child of the matching parent element. The path can specify element and attribute values to match a unique parent element, as shown in “Example 2: Path With a Value” in this section.
If the parent path does not match an element in the AIM_MANIFEST file, new elements are created as necessary, and the new child element is added to the new parent. The path to an added element is split off from the preexisting elements according to the following rules:
The split occurs after all parts of the path that specify a value.
The split occurs at the first place where multiple relevant same-tagged elements are allowed by the DTD, after all parts of the path that specify a value.
Use this XML manifest schema to analyze the following examples:
The manifest begins with a single A node.
The A node can have only one B node child.
The B node can have multiple C node children.
A C node can have multiple D node children.
Example 1: Simple Path. The AI manifest has one A node, one B node, and one C node: /A/B/C. An add subcommand is issued with a path of /A/B/C/D. In this case, a new C node is created because C nodes are the first nodes along the path that can have same-tagged siblings. A new D node is added as a child to the new C node. The resulting manifest has the structure /A/B/{C,C/D}. Issuing the same command for a different value of D results in three C nodes: /A/B/{C,C/D,C/D}.
Example 2: Path With a Value. The AI manifest has one A node, one B node, and two C nodes. Only one of the C nodes has a value of 1 so that the manifest has the structure /A/B/{C,C=1}. An add subcommand is issued with a path of /A/B/C=1/D and a value of 10. In this case, no new C node is added because specifying the value of 1 for C identifies a unique node, and the path cannot be split at or before a branch where a value is specified. The first place where this path can be split is at D. A new D node with a value of 10 is added as a child of the C node that has a value of 1. The resulting manifest has the structure /A/B/{C,C=1/D=10}. Issuing the same command with a value of 20 for D results in /A/B/{C,C=1/{D=10,D=20}}.
Retrieve an element or attribute value. An empty string ("") is displayed for empty element or attribute values. The path must match a unique existing element or attribute. See the “Operands” section for more information about path.
The -r option returns a path to the accessed node as a second returned string. See the “Return Paths” section for more information.
Change the value of an existing element or attribute, or create a new attribute of an existing element. No validation is performed.
When changing the value of an existing element, path must match a unique existing element. If the element has same-tagged siblings, use an element value or attribute, or a child element of the target element to make the path unique. See “The Path Operand” section.
When setting the value of an attribute, the attribute does not need to exist, but the element to which the attribute belongs must exist.
The -r option returns a path to the changed element. See the “Return Paths” section for more information.
Load an XML manifest or partial XML manifest from the file filename. No validation is performed except to examine parent/child relationships of elements.
When the -i option is not specified, overwrite any existing XML data. All data in the AIM_MANIFEST file is replaced with the contents of the filename file. The filename file must include a !DOCTYPE reference to a DTD so that subsequent aimanifest commands can modify the file.
When the -i option is specified, do not clear the AIM_MANIFEST data before adding new data. Instead, incrementally insert or merge the new data with the existing XML data. The DTD given by the !DOCTYPE reference in AIM_MANIFEST is used to determine how and where to merge the filename data. If the !DOCTYPE reference is missing, the AI manifest DTD at /usr/share/install/ai.dtd is used. If the data in filename cannot be reconciled with the DTD, a non-zero error status is returned.
The following considerations affect where new data is inserted into the AIM_MANIFEST manifest:
To what extent the tags of elements near the beginning of the AIM_MANIFEST data paths and filename data paths match
What child elements are allowed under those AIM_MANIFEST data elements
Where same-tagged sibling elements are allowed
Where childless AIM_MANIFEST data nodes are located
As each element of filename data is processed, if all of the following conditions are true, then in general a new node is not created for this element in the AIM_MANIFEST data. Instead, an existing node is replaced with the new data.
Both sets of data contain a node with the same tag and same location.
The DTD given by the !DOCTYPE reference in AIM_MANIFEST does not allow both of these nodes to exist together as same-tagged sibling elements.
The filename data element has children.
When an element from filename is inserted, the split where new nodes start to be created is done as close as possible to the AIM_MANIFEST data root. The first new node of the split is created at the earliest point where same-tagged sibling elements are allowed, or at the earliest appropriate point when no same-tagged element exists in AIM_MANIFEST.
Use this XML manifest schema to analyze the following examples:
The manifest begins with a single A node.
The A node can have only one B node child.
The B node can have multiple C node children.
The B node can have only one E node child.
Example 1: Inserting Same-Tagged Elements. If the content of AIM_MANIFEST is /A/B/C1/D1 and the content of filename is /A/B/C2/D2, then after the load -i command, the content of the AIM_MANIFEST file is /A/B/{C1/D1,C2/D2}. The C node is the first place where new nodes can be added. The C node from the filename data is added after the existing C node in the AIM_MANIFEST data. If the two A elements have different values or if the two B elements have different values, the value of the filename element replaces the value of the AIM_MANIFEST element. If the two A elements have different attributes, or if the two B elements have different attributes, the attribute values are merged.
Attributes of A and B that exist in both the AIM_MANIFEST file and the filename file have the values from the filename file in the merged file.
Attributes of A and B that exist in either the AIM_MANIFEST file or the filename file but not in both files are all retained in the merged file.
Example 2: Inserting Differently Tagged Elements. If the content of AIM_MANIFEST is /A/B/C/D and the content of filename is /A/B/E/F, then after the load -i command, the content of the AIM_MANIFEST file is /A/B/{E/F,C/D}. The E node is added at the first location where it is allowed by the DTD. The values of elements A and B are the values from filename, and the attributes of A and B are merged from filename to AIM_MANIFEST as described in Example 1 above.
Sometimes the correct merge location cannot be determined. This can happen if a sibling that is required to follow a node to be merged has not yet been added. To avoid this issue, add multiple nodes or subtrees to a common parent node in the order mandated by the DTD. A node is placed at the end of its list of new siblings if its proper place among them cannot be determined.
Validates the AIM_MANIFEST manifest against the DTD referenced in the !DOCTYPE statement. Errors are printed to stderr. A non-zero status is returned if validation fails.
The following operands are required.
The load subcommand requires the filename operand, which is the name of a full or partial manifest to load to the AIM_MANIFEST manifest.
The add and set subcommands require the value operand. The value operand is a valid value of the element or attribute specified by the path operand.
The add, get, and set subcommands of the aimanifest command require the path operand. The path defines a node in an XML hierarchy of elements and attributes.
The XML element hierarchy structure is also called an XML tree. In the following partial AI manifest, the auto_install element is the root of the tree, and the ai_instance and software elements are branches or the roots of subtrees.
<auto_install>
<ai_instance>
<software type="IPS"/>
</ai_instance>
</auto_install>In aimanifest path syntax, use forward slash characters (/) to indicate branches in the tree structure. In the current example, the path to the software element is /auto_install/ai_instance/software.
Attributes are bound to an element. In aimanifest path syntax, use an at symbol (@) to identify an attribute name. The path to the type attribute of the software element is /auto_install/ai_instance/software@type.
An aimanifest path operand must correspond to a single element. Include element and attribute values as necessary to make the path unique. For example, to specify a size for the second slice defined in the following partial AI manifest, you could use the path /auto_install/ai_instance/target/disk/slice[@name="4"]/size@val to identify which slice you are specifying the size for.
<auto_install>
<ai_instance>
<target>
<disk>
<slice name="0"/>
<slice name="4"/>
</disk>
</target>
</ai_instance>
</auto_install>Relative paths are permitted. The slice path shown in the previous paragraph could be specified starting at ai_instance, target, disk, or slice , since there is only one slice with a name attribute value of 4. For example, you could use the path slice[@name="4"]/size@val.
If a value within a path contains forward slash characters, then that value must be enclosed in single or double quotation marks, as in /name="pkg:/entire".
When the aimanifest call is in a shell script, values that contain quotation marks might require additional special treatment. Within a shell script, quotation marks in aimanifest path values might need to be escaped with a preceding backslash character (\) so that the shell does not remove or interpret the quotation marks. Check the rules of the shell you are using. The following example shows a value with a forward slash character in a ksh93 script:
/usr/bin/aimanifest get software_data[name=\"pkg:/entire\"]@action
Most examples in this man page omit backslash escape characters because this man page does not assume that aimanifest is being called in a script or in a particular shell. See Installing Oracle Solaris 11 Systems for information about AI derived manifests scripts.
The following forms of branches show how to construct a path to an element or element attribute.
A is the tag name of an element, as in /auto_install. This branch specification is also called a simple branch. Paths with only simple branches are called simple paths.
A is the tag name of an element, and value is the value of that element, as in /name="pkg:/entire".
A is an element, B is an element that is a child of A, C is an element that is a child of B, and value is the value of the C element. This path form specifies the A element that has a grandchild element C that has value value. For example, if your AI manifest has more than one software section, you could use this form to operate on the software section that installs package pkg:/entire, as in the following path:
software[software_data/name="pkg:/entire"]
A is an element, Aattr is an attribute of A, and value is the value of the Aattr attribute. This path form specifies the A element that has attribute Aattr with value value. For example, if your AI manifest defines more than one slice, you could use this form to operate on the slice that has a name value of 4, as in slice[@name="4"]
A is an element, B is a child of A, C is a child of B, Cattr is an attribute of C, and value is the value of the Cattr attribute. This path form specifies the A element that has a grandchild element C that has attribute Cattr with value value. For example, if your AI manifest has more than one software section, you could use this form to operate on the software section that has a publisher section with a name value of solaris, as in the path software[source/publisher@name="solaris"].
/A[1] specifies the first instance of an A element in the manifest. For example, if your AI manifest has more than one software section, you could use this form to operate on the second software section, as in /auto_install[1]/ai_instance[1]/software[2].
This is the form of path that is returned by the -r option. See the “Return Paths” section.
This path specifies the Aattr attribute of the A element. This path does not specify the A element but rather the Aattr attribute. Use this form to set or get the Aattr attribute.
This path specifies the Aattr attribute of the A element that has a grandchild element C that has value value.
This path specifies the Aattr attribute of the A element that has a grandchild element C that has attribute Cattr with value value.
This path specifies the Battr attribute of the B element with value value. The B element is a child of the A element.
With the -r option, the add, get, and set subcommands return the address of the element that was created or accessed by the subcommand. This returned address is in the form of a chain of node IDs. This returned address can be used to access the same element again, even if values associated with that element have changed.
The following examples show that the address returned by the -r option can be much easier to use than a path that specifies element and attribute values. Start with the following node tree:
auto_install
|
ai_instance
|
target
|
disk
attribute: whole_disk=true
|
disk_name
attribute: name=data1
attribute: name_type=volidAdd a new disk node with name attribute value data2 and name_type attribute value volid:
auto_install
|
ai_instance
|
target
|
|----------|----------|
disk disk
whole_disk=true whole_disk=true
| |
disk_name disk_name
name=data1 name=data2
name_type=volid name_type=volidA new disk_name element with one attribute can be added easily with a single command. To add the second and third attributes, you must specify which disk_name element to change. Compare the following two methods for accessing the same node multiple times.
The commands in this example specify paths using values. Note that you must assign a unique value in the first command so that you can use that value to specify a unique path in the subsequent commands. This method could yield an incorrect result if the values are changed.
$ aimanifest add target/disk/disk_name@name data2 $ aimanifest set \ > target/disk/disk_name[@name=data2]@name_type volid $ aimanifest set \ > target/disk[disk_name@name=data2]@whole_disk true
The most reliable way to access the same node multiple times is to save the path to the new disk_name element, and then use that saved path for subsequent accesses.
$ NewDisk=$(aimanifest add -r target/disk@whole_disk true)
$ aimanifest add ${NewDisk}/disk_name@name data2
$ aimanifest add ${NewDisk}/disk_name@name_type volidThe path that is returned to $NewDisk through the -r option expresses the node in terms of IDs and is free of values:
$ aimanifest add -r target/disk/@whole_disk true /auto_install[1]/ai_instance[1]/target[1]/disk[2]
To try these examples, you need to set AIM_MANIFEST.
$ export AIM_MANIFEST=/tmp/aimtest.xml
The minimum AIM_MANIFEST file that the aimanifest command can modify must contain both of the following pieces:
A !DOCTYPE reference to a DTD that is valid for the XML manifest being developed.
The root element for this manifest.
The following example shows the minimum AIM_MANIFEST manifest file for an AI manifest:
<!DOCTYPE auto_install SYSTEM "file:///usr/share/install/ai.dtd"> <auto_install/>
Usually, you will use the aimanifest command in a derived manifests script that operates on an existing valid AI manifest. To try these examples, you can copy /usr/share/auto_install/manifest/default.xml and then define AIM_MANIFEST to refer to this copy. Make sure the copy is writable.
Example 1 Set the auto_reboot Attribute
$ aimanifest set /auto_install/ai_instance@auto_reboot false
Example 2 Get the auto_reboot Value
$ aimanifest get /auto_install/ai_instance@auto_reboot false
Example 3 Add a Publisher by Using Values Paths
The package repository in this example is a file repository at file:///net/host2/export/extras_repo. The publisher is extras. Since a software element can have only one source element, this example adds the new publisher element to the source element that contains the solaris publisher.
$ aimanifest add \ > software[@type=IPS]/source[publisher@name=solaris]/publisher@name \ extras $ aimanifest add \ > publisher[@name=extras]/origin@name \ > file:///net/host2/export/extras_repo
These aimanifest commands result in the following AI manifest entries if you started with the default.xml AI manifest. The destination and software_data elements are omitted for brevity.
<software type="IPS">
<source>
<publisher name="solaris">
<origin name="http://pkg.oracle.com/solaris/release"/>
</publisher>
<publisher name="extras">
<origin name="file:///net/host2/export/extras_repo"/>
</publisher>
</source>
</software>Example 4 Add a Publisher by Using Returned Paths
This example is the same as the previous example but uses a different method to achieve the same result.
$ NEW_PUB=$(aimanifest add -r \
> software[@type=IPS]/source[publisher@name=solaris]/publisher@name \
extras)
$ echo $NEW_PUB
/auto_install[1]/ai_instance[1]/software[1]/source[1]/publisher[2]
$ aimanifest add ${NEW_PUB}/origin@name \
file:///net/host2/export/extras_repoExample 5 Add a Publisher By Adding a Manifest Fragment
This example adds the extras publisher by loading a file that contains a partial AI manifest. In this case, the result is a separate, additional software element of type IPS with the extras publisher defined. This new software element is inserted after the original IPS software element that defines the solaris publisher. Packages named in software_data elements within this new software element are only searched for from the extras publisher or other publishers defined in this new software element. This manifest fragment also defines a package to install, since a software element with no software to install is not useful.
Create a file named extras.xml with the following content:
<auto_install>
<ai_instance>
<software type="IPS">
<source>
<publisher name="extras">
<origin name="file:///net/host2/export/extras_repo"/>
</publisher>
</source>
<software_data action="install">
<name>pkg:/package/from/extras_repo</name>
</software_data>
</software>
</ai_instance>
</auto_install>Even though you only want the software section, you must include the auto_install and ai_instance elements as well. If the loaded file specifies attributes for the auto_install or ai_instance elements, then those attribute values replace existing values or are added.
Use the following command to add this software section to the AIM_MANIFEST manifest:
$ aimanifest load -i extras.xml
Example 6 Add a Package by Using a Values Path
This example adds a package to the software element that has a publisher element with name solaris by specifying the publisher name as a value in the path.
$ aimanifest add \ > software[source/publisher@name=solaris]/software_data/name \ > pkg:/system/utils
This aimanifest command adds the second software_data element shown below if you started with the default.xml AI manifest.
<software_data action="install"> <name>pkg:/entire@latest</name> <name>pkg:/group/system/solaris-large-server</name> </software_data> <software_data> <name>pkg:/system/utils</name> </software_data>
Example 7 Add a Package by Using a Returned Path
This example is the same as the previous example but uses a different method to achieve the same result. This example uses the get subcommand with the returned path option to add the package to the software element where the solaris publisher is defined.
$ NEW_PKG=$(aimanifest get -r \
software[source/publisher@name=solaris] | awk '{print $2 }')
$ echo $NEW_PKG
/auto_install[1]/ai_instance[1]/software[1]
$ aimanifest add ${NEW_PKG}/software_data/name \
pkg:/system/utilsExample 8 Add a Package By Adding a Manifest Fragment
This example adds the package by loading a file that contains a partial AI manifest. In this case, the result is a separate, additional software element of type IPS inserted after the original IPS software element. This new software element contains only a software_data element; no source element is specified. Packages named in software_data elements within this new software element are searched for from publishers defined in the preceding software element.
Create a file named newpkg.xml with the following content:
<auto_install>
<ai_instance>
<software type="IPS">
<software_data>
<name>pkg:/system/utils</name>
</software_data>
</software>
</ai_instance>
</auto_install>Even though you only want the software section, you must include the auto_install and ai_instance elements as well. If the loaded file specifies attributes for the auto_install or ai_instance elements, then those attribute values replace existing values or are added.
Use the following command to add this software section to the AIM_MANIFEST manifest:
$ aimanifest load -i newpkg.xml
Example 9 Validate a Manifest
Validate the AIM_MANIFEST manifest.
$ aimanifest validate
The following exit values are returned:
The command was processed successfully.
An error occurred.
The value of this environment variable is the location of the AI manifest that is being built.
The value of this environment variable is the location of the log file of aimanifest operations.
See attributes(5) for descriptions of the following attributes:
|
Part III, Installing Using an Install Server, in Installing Oracle Solaris 11.1 Systems
|