How to Edit an Automated Installer Manifest with NetBeans

Editing XML

Editing XML is something system administrators seem to really hate; understandably, XML can employ a soup of standards! (Click to see Ken Sall‘s awesome image-map of XML related standards.) However, XML is awesome in providing a structured format for configuration and data files. In the OpenSolaris Automated Installer, XML is used as the manifest to select the system for install and how to install the system once selected. The Automated Installer uses a schema to verify the XML is acceptable to the installer engine and to provide a vocabulary of acceptable tags. However, if using a traditional text editor the process to author a manifest is rather painful since this data is not easily available to the author.

Using NetBeans for XML authoring

NetBeans, being a modern, integrated, developer environment provides a comprehensive XML authoring environment. One can provide a reference to an XML schema and then get: auto-completion of XML tags, the ability to validate the XML file under development against the schema and, if documented, tool-tips for each tag. However, the one issue for someone authoring Automated Installer manifests is NetBeans only supports XML Schema type schemas and the Automated Installer uses a RelaxNG schema. The answer is to convert the schema to XML Schema and for that, enter the Trang multi-format schema converter which can convert RelaxNG (.rng) to XML Schema (.xsd). Or download my annotated version below.

How to use schemas with NetBeans

To use NetBeans’ context sensitive code completion, one needs an AI schema in XSD format. An annotated schema can be downloaded: AI Schema, Criteria Schema.

Lastly, you simply need to add a reference for NetBeans to find your schema. This can be done by using touch(1) to create a new file in the same directory as your two .xsd schemas (end the file with .xml). Then open the file in NetBeans and paste the following line in NetBeans to create an Automated Installer manifest:

<ai_manifest name="default"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="./ai_manifest_annotated.xsd">
</ai_manifest>

Now, if you begin typing a tag (start a tag with <) between the <ai_manifest> tags, you should get a pop-up window with context acceptable tags and documentation on each one. Further, you can go to the Run menu and use the Validate XML option to use NetBeans for help on any typos in the file.

You can do the same for criteria manifests using the provided schema for them as well. However, you will not be able to use the <ai_embedded_manifest> or <sc_embedded_manifest> tags, instead use the <ai_manifest> and <sc_manifest> tags to specify a file URI and keep your manifests in separate files for ease of manipulation.

Notice the context sensitive editor here. It shows that the <ai_http_proxy> tag has a url attribute and provides documentation on the <ai_http_proxy> tag. Lastly, check out the XML navigator provided on the right side showing the hierarchal breakdown of the document.
Screenshot of the NetBeans context sensitive editor.

What’s it all look like in the end?

When you’re done crafting your criteria and AI manifests. you should have two files; plus you will need a system configuration manifest based on the SMF group’s DTD. It should look something like:

<ai_criteria_manifest
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:noNamespaceSchemaLocation="./criteria_schema_annotated.xsd">
<ai_criteria name="MEM">
<value>
1024 2048
</value>
</ai_criteria>
<ai_manifest_file URI="/tmp/ai_manifest.xml"/>
<sc_manifest_file name="bogus" URI="/tmp/sc_manifest.xml"/>
</ai_criteria_manifest>

They will all be linked in your criteria manifest using the <ai_manifest> and <sc_manifest> tags. Then to publish your manifest, simply run installadm add -m path to your criteria manifest -n your AI service name!

How to use Trang to get an XSD from the Automated Installer RelaxNG schemas

To create the above XSD schemas, I used an open source tool, Trang. Trang is capable of converting schemas from various schema languages. For example, it can deal with cross-converting:

  • RELAX NG (XML syntax)
  • RELAX NG compact syntax
  • XML 1.0 DTDs
  • W3C XML Schema (output only)

To use Trang, one simply provides a schema’s current type and the desired output type, and an input and output filename. For the AI Manifest Schema, one simply downloads Trang and runs, java -jar trang.jar -I RNG -O XSD /usr/share/auto_install/ai_manifest.rng ai_manifest.xsd.

To convert the AI Criteria Schema tickles one feature of RelaxNG which Trang does not yet support, however. The externalRef directive which simply nests one schema inside another is unsupported, however, it is easy to overcome. It is possible to modify the schema to remove this requirement and easily generate an XSD; the difference for removing support for “embedded” AI and SC manifests for the current schema revision are:

--- /usr/share/auto_install/criteria_schema.rng
+++ modified_criteria_schema.rng
@@ -60,7 +60,6 @@
</start>
<define name="nm_ai_manifest_src">
-		<choice>
<!--
Either embed or point to an A/I manifest
-->
@@ -69,14 +68,9 @@
<data type="anyURI"/>
</attribute>
</element>
-			<element name="ai_embedded_manifest">
-				<externalRef href="ai_manifest.rng"/>
-			</element>
-		</choice>
</define>
<define name="nm_sc_manifest_src">
-		<choice>
<!--
Either embed or point to an SC manifest
-->
@@ -88,17 +82,6 @@
<data type="anyURI"/>
</attribute>
</element>
-			<element name="sc_embedded_manifest">
-				<attribute name="name">
-					<text/>
-				</attribute>
-				<!--
-				    Note: the embedded manifest being DTD
-				    based can not be verified and as such
-				    should be included inside comment tags
-				-->
-			</element>
-		</choice>
</define>
<!--

Leave a Reply