Most configuration files are actually organized mostly as a tree structure.
Depending on the syntax of the file,
this structure may be obvious to see (e.g.
for XML,
Apache) or not so obvious (Xorg syntax,
INI syntax).

For some files like approx.conf or adduser.conf,
this tree structure is quite flat.
It looks much like a rake than a tree,
but still,
it's a tree.

Some will argue that some Xorg parameter refer to others (i.e.Device and Monitor value in Screen section) and so they cannot be represented as a tree. That's right, there are some more complex relations that are added to the tree structure. This will be covered in more details when dealing with complex models.

In some other case, the structure of a tree is not fixed. For instance, Device options in Xorg.conf are different depending on the value of the Device Driver. In this case, the structure of the configuration tree must be adapted (morphed) depending on a parameter value.

Just like XML data can have Schema to validate their content, the configuration tree structure needs to have its own schema to validate its content. Since the tree structure cannot be represented as a static tree without reference, XML like schema are not enough to validate configuration data.

Config::Model provides a kind of schema for configuration data that takes care of the cross references mentioned above and of the dynamic nature of the configuration tree required for Xorg (and others).

In summary, configuration documentation is translated in a format usable by Config::Model:

The structure is translated into configuration classes

Configuration parameters are translated into elements

Constraints are translated into element attributes

All models files must be written in a specific directory. For instance, for model Xorg, you must create ./lib/Config/Model/models/Xorg.pl. Other classes like Xorg::Screen can be stored in their own file ./lib/Config/Model/models/Xorg/Screen.pl or included in Xorg.pl

A model file is a Perl file containing an array for hash ref. Each Hash ref contains a class declaration:

[ { name => 'Xorg', ... } , { name => 'Xorg::Screen', ... } ] ;

A class can have the following parameters:

name: mandatory name of the class

class_description: Description of the configuration class.

generated_by: Mention with a descriptive string if this class was generated by a program. This parameter is currently reserved for Config::Model::Itself model editor.

Since writing a data structure is not fun (even with Perl), you are encouraged to use the model editor provided by config-model-edit from Config::Model::Itself module. You will get this type of GUI shown on the right with the command config-model-edit -model Xorg

This first set of attributes will help the user by providing guidance (with level and status) and documentation (summary and description).

All elements (simple or complex) can have the following attributes:

description: full length description of the attribute

summary: one line summary of the above description

level: is important, normal or hidden. The level is used to set how configuration data is presented to the user in browsing mode. Important elements will be shown to the user no matter what. hidden elements will be explained with the warp notion.

status: is obsolete, deprecated or standard (default). Using a deprecated element will issue a warning. Using an obsolete element will raise an exception.

Default value that is known by the target application and thus does not need to be written in the configuration file.

To know which attributes to use, you will have to read the documentation of the target application.

For instance, AddressFamily parameter (sshd_config(5)) is specified with: Specifies which address family should be used by sshd(8). Valid arguments are "any", "inet" (use IPv4 only), or "inet6" (use IPv6 only). The default is "any".

For Config::Model, AddressFamily is a type leaf element, value_type enum and the application will use any if this parameter is left blank in sshd_config file.

These repositories must be stored as a hash where the key will be debian or multimedia and the associated value will a URL. But this hash must have something which is not explicit in approx.conf file: a parameter name. Approx man page mentions that: The name/value pairs [not beginning with '$' are used to map distribution names to remote repositories.. So let's use distribution as a parameter name.

A node element is necessary if the configuration file has more than a list of variable. In this case, the tree is deeper than a rake and a node element if necessary to provide a new node within the tree.

In the Xorg example above, the options of Xorg::Screen need their own sub-branch in the tree:

Some configuration files can feature a set of rather complex configuration entities. For instance Xorg.pl can feature several Screen or Device definitions. These definitions are identified by the Identifier parameter:

And the Xorg model must define these 2 parameters as hash. The cargo of this hash will of type node and will refer to 2 different configuration classes, one for Device (Xorg::Device) and one for Screen (Xorg::Screen):

Both Perl/Tk and Curses interfaces feature a configuration wizard generated from a configuration model.

The wizard works by exploring the configuration tree and stopping on each important element and on each error (mostly missing mandatory parameter).

When designing a model, you will have to think about each element:

The importance level of the parameter (important, normal or hidden). level is used to set how configuration data is presented to the user in wizard and browsing mode. Important elements will be shown in the wizard. hidden elements will be explained with the warp notion in Creating a model with advanced features.

Both specifications are tried in order. If Augeas backend fails (e.g. Augeas is not installed), the custom backend will be used.

An exception will be raised if both methods fails. This behavior is correct for OpenSsh, but it can be a problem if you want to use Config::Model to create a configuration file from scratch. In this case you will also have to specify the auto_create parameter:

Read and write specifications were designed to be very similar. Most of the times, the read and write specification will be identical. In this case, there's no need to enter them: the data specified in the read specification will be used to write the configuration file.

By combining multiple read specification with 'one' write specification, a configuration file can be migrated from old to new syntax. The following example will migrate a configuration file from a custom syntax to a perl data file: