CML primer

This section introduces the Configuration Modeling Language, CML. For complete details on CML see CML Reference. See also CML Tutorial 1 - Creating an Application Configuration for a simple web app server and CML Tutorial 2 - Creating a template of a web server configuration file.

SA manages configuration files by creating a configuration template that it uses to:

• Model the syntax of the configuration file.
• Extract the values from the configuration file and store them as a value set in the SA database. Once those values are stored, you can use the SA Client to manage those values.
• Create a new configuration file from the value set.
• Push the new configuration file to your servers.
• Audit the configuration files on your servers to ensure compliance.

Terminology

• Configuration File - The file to be managed by SA.
• Value Set - The data values from configuration files that can vary from server to server. Values in a value set are stored in the SA database in “key = value” format.
• Name Space - The structure of how value sets are stored in the SA database.
• Configuration Template - A model of your configuration file written in CML.
• Configuration Modeling Language (CML) - The set of instruction tags that are used to model a configuration file in a configuration template.
• Instruction or Tag - The key words and characters that define the action to be taken. All instructions start and end with the “@” character. The terms “instruction” and “tag” can be used interchangeably.
• Application Configuration Object - A container of configuration templates that, when combined with a value set, generates a configuration file that is then “pushed” to your managed servers. This can also contain scripts that are executed as part of the push operation.

CML basic concepts

CML, Configuration Modeling Language, models the syntax of a configuration file. You use CML to create a configuration template, which is a model of the target configuration file. To do this, it is usually best to obtain the documentation for the target configuration file so you can understand the valid values and ranges in the configuration file and determine the best way to model it.

Configuration templates work best when the entire configuration file is modeled by CML. However, it is possible to only write CML for some of the lines in a configuration file. This is called a partial template and is discussed at Partial templates.

Required CML instruction tags

The following three CML instructions (also called CML tags) are required in any configuration template.

• namespace defines the key where the value set data is stored in the SA database. See Namespace tag.
• filename-key defines the key where the target configuration file name is stored in the SA database. See Filename-key tag.
• filename-default specifies the default name of the target configuration file. See Filename-default tag.

All other tags are optional and are used to model the contents of the specific configuration file. For complete details on CML, see CML Reference. For details on these three required tags, see CML global option attributes.

Namespace tag

The namespace instruction defines the key where value sets are stored in the SA database.

Syntax:

@!namespace=<path>@

where <path> is a string similar to a directory path that defines the key where value sets are stored in the SA database.

Example:

@!namespace=/example/namespace/@

This example sets the base name space for all other instructions in this template to “/example/namespace/”. That is, all values in the value set will be stored at the key “/example/namespace/” unless specified otherwise.

Description:

The namespace instruction specifies the key in the key/value mapping for the values in the value set. It is an arbitrary string and can be anything except a number. This instruction determines the key where the values in the value set are stored in the SA database. The Replace tag (and other tags) in the configuration file use the name space key to obtain values from the SA database.

The namespace value must be absolute. Subsequent values can have relative or absolute path names.

• Absolute names are the full path name starting with a “/” character. These names do not use the value specified in the namespace instruction. For example, any value matching the following tag:

  @/testval@

  would get stored in the value set under the key “/testval”.

• Relative names get appended to the value specified in the namespace instruction tag. For example, any value matching the following tag:

  @testval@

  would get stored in the value set under the key “/example/namespace/testval”.

Note that any named tag that is part of a loop requires a dot “.” in front of the name, and that tags name space gets appended to the current loop's name space. For example: @.testval@

Filename-key tag

The filename-key instruction specifies the key where the target configuration file name gets stored in the SA database.

Syntax:

@!filename-key=<path>@’

where <path> is an arbitrary string similar to a directory path that defines the key where configuration file name is stored in the SA database.

Examples:

@!filename-key=/files/example@

This example specifies that the file name will be stored in the SA database with the key “/files/example”. Note that because the <path> value starts with a “/” character, it is an absolute path.

@!filename-key=files/example@

This example specifies a relative path because the value does not start with a “/” character. If it were combined with the previous namespace example, the configuration file name would be stored at /example/namespace/files/example”.

Description:

The filename-key instruction specifies the key that will be used to store the target configuration file name in the SA database. For example, when you set the “Filename” field for a template in the SA Client, that file name will be stored under the key “/files/example” in the value set. Note that the filename-key is not a file system path, but just a key that can be written similar to a path.

This can be very handy for pre and post scripts that need to know the name of the configuration file before or after it has been pushed to the target servers. For example, if you have a post script that needs to add a line to the end of the configuration file after it has been pushed, it might look something like this:

echo “#end of the file” >> @/files/example@

Filename-default tag

Syntax:

@!filename-default=<file>@

where <file> is the directory path and file name of the target configuration file in the file system of your managed servers. This is where the generated configuration file will be pushed on to your managed servers.

Example:

@!filename-default=/etc/hosts@

This example specifies that the target configuration file is /etc/hosts. This value is stored in the SA database with the key specified in the Filename-key instruction.

Description:

The filename-default instruction specifies the standard file system path of the target configuration file. This value is the default file name and directory and is stored under the key specified by the filename-key instruction. It is the default value in the "Filename" field in the SA Client.

Combining tags on one line

You can combine multiple instruction tags into one instruction by separating the instructions by semicolons and only using a single exclamation point at the beginning as follows:

@!namespace=/example/namespace/;filename-key=/files/example;
filename-default=/etc/example@

This can be handy, since this one line included in any file makes it a valid CML template, assuming of course, that all other CML tags are correctly formed.