CML overview

A configuration template consists of a series of CML tags. Each tag represents either an instruction to the CML parser how to interpret the text in the configuration file or a placeholder that identifies the location of a value in the configuration file and how to map it into a value set.

Keep in mind that the configuration template contains no values. It only defines how values are moved between the value set in the SA database and the configuration file instances on the managed servers. For more information, see Value sets.

Template files containing CML are typically named with “.tpl” as the file extension, but this file extension is not required.

Structure of CML tags

The basic building blocks of a CML tag is as follows:

@{level}{tagtype}{source};{type};{range};{option};...;{option}@

The following rules apply to all CML tag:

• All CML tags start and ends with the @ symbol.
• Semicolons (;) mark placeholders for omitted attributes. For example, the following shows two omitted attributes between the @name attribute and the optional@ attribute:
  
  @name;;;optional@
• If attributes to the right of a semicolon are empty, then semicolons are optional. For example:
  @name@
• {level} - The block level is an integer that specifies the nesting level of the block. The level also determines whether the block spans multiple lines or is part of a single line. If the level is between 1 and 99 it is a multi-line block. If it is above 101, it is a block within a line. Each block open tag closes all previous blocks that have an equal or greater level.
  
  Do not use level 100 because level 100 is reserved.
• {tagtype} - CML defines the tag types listed below. Each type is an instruction to the CML parser. For complete details, see CML tag types.
  • Comment Tags: @# and @## ... #@ - Define comments in the template.
  • Replace Tag: @ - Defines how to replace a variable with a value from the value set.
  • Instruction Tag: @! - Gives an instruction to the CML parser.
  • Block Tags: @[@...@]@ - Create a new scope.
  • Loop Tag: @* - Creates a loop over multiple similar values.
  • Loop Target Tag: @. - Ends a loop.
  • Conditional Tag: @?
  • DTD Tag: @~ - Defines
• {source} - Defines a key where the value is stored in the value set. Absolute path names start with a “/” character. Relative path names do not start with a “/” and are concatenated to the name space key value defined by the @!namespace instruction.
• {type} - Defines the data type of the value required by the configuration file and the corresponding value in the value set. For example, int for integer, string, boolean, IP-address, and so forth. You can also specify ordered and unordered lists and sets.
• {range} - Defines additional restrictions on data values for better error checking.
• {option} - Defines additional parameters you can specify to modify the behavior of the CML tag.

Required CML tags

Every CML file must define its name space and the default file name of the configuration file the template models using the following CML tags:

• @!namespace defines the name space for the template. All values in the value set used by the template will be stored in the SA database at the key defined by the @!namespace tag. For more information, see Define the Namespace with the @!namespace CML Tag.
• @!filename-key defines a specific key where the default file name will be stored in the SA database. This key can either be a separate name space or it can be appended to the name space defined by the @!namespace tag. For more information, see Defining the default configuration file name with the @!filename-key and @!filename-default CML tags.
• @!filename-default defines the directory and name of the configuration file being modeled by the template. This value can be modified by the value set. For more information, see Defining the default configuration file name with the @!filename-key and @!filename-default CML tags.

Define the Namespace with the @!namespace CML Tag

The name space in a CML template file defines a unique key value where data is stored in the database. The name space value is represented as a path name and looks like a directory path name in a file system, or a URI in a web browser’s location bar. Use the namespace tag to define the name space.

The path names for individual values can be either absolute or relative. An absolute path name start with “/” and is the complete representation of the location of the value in the value set. A path name that does not start with a “/” is a relative path name; its value will be appended to the current value of the name space.

The namespace tag is required.

All key names in CML templates must be ASCII. Other fields and text can be either ASCII or non-ASCII text.

Below is an example of a namespace tag in a CML template:

@!namespace=/security/@

Defining the default configuration file name with the @!filename-key and @!filename-default CML tags

Each template must define the default configuration file name that will be used when pushing the generated configuration file to a server. This file name can be overridden by the value sets. Use the filename-default tag to define the default file name.

You must also specify a unique key where the default file name will be stored in the SA database. This key can be combined with the name space to generate a unique storage location for the default file name. The key defines a name space is represented as a path name. Use the filename-key tag to define the key value.

The filename-default and filename-key tags are required.

All key names in CML templates must be ASCII. Other fields and text can be either ASCII or non-ASCII text.

The following example CML specifies that they key value “/files/hosts” will be used to store the default file name in the SA database. It also specifies that the default file name for the generated configuration file will be “/etc/hosts”.

@!filename-key="/files/hosts"@
@!filename-default="/etc/hosts"@

You can also combine CML tags on one line as follows:

@!filename-key="/files/hosts";filename-default="/etc/hosts"@