Olympus - ConfigXML Syntax README

Mount Linux Olympus - ConfigXML Syntax README

Andy Kopciuch <akopciuch@mountlinux.com>

2000-11-22 v1.0


This document describes the design of the ConfigXML syntax for the Olympus open source administration system sponsored by Mount Linux.

1. Example XML

2. Mandatory XML tags

3. Optional XML tags

4. Reserved type names


1. Example XML


<xml version="1.0">
<def>
    <type name="device"       begin="DEVICE=([a-zA-Z0-9]+)"     end="\n" />
    <type name="userctl"      begin="USERCTL=(yes|no)"          end="\n" />
    <type name="onboot"       begin="ONBOOT=(yes|no)"           end="\n" />
    <type name="bootproto"    begin="BOOTPROTO=(dhcp|none)"     end="\n" />
    <type name="broadcast"    begin="BROADCAST=([0-9{1,3}\.]+)" end="\n" />
    <type name="network"      begin="NETWORK=([0-9{1,3}\.]+)"   end="\n" />
    <type name="netmask"      begin="NETMASK=([0-9{1,3}\.]+)"   end="\n" />
    <type name="ipaddr"       begin="IPADDR=([0-9{1,3}\.]+)"    end="\n" />
    <type name="name"         begin="NAME=([a-zA-Z0-9]+)"       end="\n" />
    <type name="linecomment"  begin="(\#[^\n]*)"                end="\n" />
</def>

<file key1="network" key2="interfaces">
    <element name="device"       typeref="device"       multi="false" opt="true" strict = "false"/>
    <element name="userctl"      typeref="userctl"      multi="false" opt="true" strict = "false"/>
    <element name="onboot"       typeref="onboot"       multi="false" opt="true" strict = "false"/>
    <element name="bootproto"    typeref="bootproto"    multi="false" opt="true" strict = "false"/>
    <element name="broadcast"    typeref="broadcast"    multi="false" opt="true" strict = "false"/>
    <element name="network"      typeref="network"      multi="false" opt="true" strict = "false"/>
    <element name="netmask"      typeref="netmask"      multi="false" opt="true" strict = "false"/>
    <element name="ipaddr"       typeref="ipaddr"       multi="false" opt="true" strict = "false"/>
    <element name="name"         typeref="name"         multi="false" opt="true" strict = "false"/>
    <element name="linecomment"  typeref="linecomment"  multi="true"  opt="true" strict = "false"/>
</file>
</xml>


2. Mandatory XML Tags

The current XML definition contains three mandatory tags: the "xml", "def", and "file" tags.

2.1 The <xml> tag

The XML templates are only valid if started with the "xml" tag:


<xml version="1.0">

The version number describes the version of XML used in the template (the major number) and the revision of the actual template (the minor number). In this example we are using XML version 1 and the template has never been revised (i.e. 0)

All versions of XML are supported up to and including the current version in the Olympus client. If the XML used is at version 3, any XML template with version 4 or higher would not supported, while lower versions such as 1 or 2 will be supported.

2.2 The <def> tag

The "def" section contains the definitions of the types of information that may be in the system file.

The "def" section will describe all information that we want from a particular system file. At the definition level we maintain all types that will be reckognized. Any element of the file must have a type defined in the XML template "def" tag.

2.3 The <file> tag

The "file" section describes the types of the information found in the system file, including which files this template is for.

The "file" section can only contain elements. Types cannot be defined at the file section. Elements state exactly what information is found in the system file.

The <file> tag has 2 mandatory attributes:

  1. The key1 in the olympus database.
  2. The key2 in the olympus database.

These keys are string values and will be used to identify which system file(s) this template describes.


3. Optional XML Tags

3.1 The <element> tag

An element tag is used to define what information is found in the system file.

Each element tag has four attributes:

  1. The name of the element.
  2. The type of the element. (a reference to a "type" defined in the "def" section)
  3. Whether there are multiple instances of the element.
  4. Whether the existence of the element is optional.
  5. Whether the existence of the element must stricly match the type definition.

The "typeref" attribute is a string value matching a name of a type previously defined in the "def" section of the template. Elements cannot be created without a reference to a valid type.

The value of the "multi" and "opt" attributes are either "true" or "false". These state whether multiple instances of the element can be found, and whether it is optional for the element to exist in the file.

The value of the "strict" attribute is either "true" or "false". This means the parsed information must exactly match the XML definition of the type. For example is unparsed information is discovered while parsing an element, the entire element will become marked as "unparsed" if strict="true."

3.2 The <type> tag

A type tag is used to define what a piece of information from the system file looks like.

Each type tag has three attributes:

  1. The name of the type. (to identify the elements)
  2. The beginning point of the type.
  3. The ending point of the type.

The begin and end attributes are regular expressions that can be matched to the information in the system file. Between the braces, is regular expression syntax describing the value of the type. A value can be stated in the begin or end attribute, but not both.

From the exmaple XML:


    <type name="device"    begin="DEVICE=([a-zA-Z0-9]+)"    end="\n" />

In this example we are saying that in the system file there will be information about a "device". The information can be recognized as "DEVICE=" then the information followed by a newline character.

This XML could also be written as:


    <type name="device"    begin="DEVICE="    end="([a-zA-Z0-9]+)\n" />

3.3 Complex Types

Types can be defined to be simple like this. Types can also be complex, meaning a type contains other elements.


<type name="device"       begin="DEVICE=([a-zA-Z0-9]+)"     end="\n" />
<type name="userctl"      begin="USERCTL=(yes|no)"          end="\n" />
<type name="onboot"       begin="ONBOOT=(yes|no)"           end="\n" />
<type name="bootproto"    begin="BOOTPROTO=(dhcp|none)"     end="\n" />

This next type is like a C structure. The type is referred to as the deviceDesc. Each "deviceDesc" contains one element of type userctl, and one element of bootproto.


<type name="deviceDesc" begin="^." end=".$">
    <element name="control" typeref="userctl" multi="false" opt="false" strict="false" />
    <element name="protocol" typeref="bootproto" multi="false" opt="false" strict="false" />
</type>

This next type again has elements contained with it. Each "devices" has a name of type device, a description of type deviceDesc ( which was just defined in the previous type), and a startup of type onboot.


<type name="devices" begin="^." end=".$">
    <element name="name" typeref="device" multi="false" opt="false" strict="false" />
    <element name="description" typeref="deviceDesc" multi="false" opt="false" strict="false" />
    <element name="startup" typeref="onboot" multi="false" opt="false" strict="false" />
</type>

The file has 0 to many devices which are of type devices.


<file key1="network" key2="devices">
    <element name="devices" typeref="devices" multi="true" opt="false" strict="false" />
</file>

This nesting of elements into types is used to group elements together. The type used in the typeref attribute of an element must already have been defined.


4. Reserved type names

In system files, there are two special types that can be defined. A simple line comment and a block comment. The ConfigXML sysntax has reserved names for these special types. If a line comment will exist in the file, it's type name must be "linecomment". If a block comment exists in the file, it's type name must be "blockcomment".

4.1 Line Comments

Line comments may exist in a system file. Line comments are usually specified as one or two characters that mark a line as a comment. For example:

# This is a line comment!

Because we have no way of telling how many comments exist in a file, or where they will exist (ie. possibly at the end of a valid line:

DEVICE=eth0 #ethernet device

When the XML is parsed for the description of the file. If a "linecomment" type is defined in the <def> section, all elements will automatically (and magically) be given 1 extra element of type "linecomment". When the system file is read for it's informatiom, all comments are maintained regardless of where they appear.

4.2 Block Comments

Block comments may exist in a system file. Line comments are usually specified as one or two characters that mark a beginning and ending of a comment block. For example:


/*
This is a block comment!
This is a block comment!
*/

Because we have no way of telling how many comments exist in a file, or where they will exist (ie. possibly at the end of a valid line:

DEVICE=eth0 /*ethernet device*/

When the XML is parsed for the description of the file. If a "blockcomment" type is defined in the <def> section, all elements will automatically (and magically) be given 1 extra element of type "blockcomment". When the system file is read for it's informatiom, all comments are maintained regardless of where they appear.