Configuration class declaration¶

Since writing the data structure shown below is not fun (even with Perl), you are encouraged to use the model editor provided by cme using "cme meta edit" command (provided by Config::Model::Itself). This commands provides a GUI to create or update your model.

When saving, "cme" writes the data structure in the correct directory.

Configuration class declaration (the hard way)¶

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.
• include: Include element description from another class.

For more details, see "Configuration_Model" in Config::Model.

For instance:

 $ cat lib/Config/Model/models/Xorg.pl
 [
   {
     name => 'Xorg',
     class_description => 'Top level Xorg configuration.',
     include => [ 'Xorg::ConfigDir'],
     element => [
                 Files => {
                           type => 'node',
                           description => 'File pathnames',
                           config_class_name => 'Xorg::Files'
                          },
                 # snip
                ]
   },
   {
     name => 'Xorg::DRI',
     element => [
                 Mode => {
                          type => 'leaf',
                          value_type => 'uniline',
                          description => 'DRI mode, usually set to 0666'
                         }
                ]
   }
 ];

Common attributes for all elements¶

This first set of attributes helps 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 are shown to the user no matter what. hidden elements are explained with the warp notion.
• "status": is "obsolete", "deprecated" or "standard" (default). Warnings are shown when using a deprecated element and an exception is raised when an obsolete element is used.

See "Configuration_class" in Config::Model for details.

Leaf elements¶

Leaf element is the most common type to represent configuration data. A leaf element represents a specific configuration parameter.

In more details, a leaf element have the following attributes (See "Value_model_declaration" in Config::Model::Value doc):

type

Set to "leaf" (mandatory)

value_type

Either "boolean", "integer", "number", "enum", "string", "uniline" (i.e. a string without "\n") (mandatory)

min

Minimum value (for "integer" or "number")

max

Maximum value (for "integer" or "number")

choice

Possible values for an enum

mandatory

Whether the value is mandatory or not

default

Default value that must be written in the configuration file

upstream_default

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 should 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 falls back to "any" if this parameter is left blank in "sshd_config" file.

Thus the model of this element is :

 AddressFamily => {
   type             => 'leaf',
   value_type       => 'enum',
   upstream_default => 'any',
   description      => 'Specifies which address family should be used by sshd(8).',
   choice           => [ 'any', 'inet', 'inet6' ]
 }

Simple list or hash element¶

Some configuration parameters are in fact a list or a hash of parameters. For instance, "approx.conf" can feature a list of remote repositories:

 # remote repositories
 debian     http://ftp.fr.debian.org/debian
 multimedia http://www.debian-multimedia.org

These repositorie URLs must be stored as a hash where the key is debian or multimedia and the associated value is 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.

The example is stored this way in the configuration tree:

 root
 |--distribution(debian)=http://ftp.fr.debian.org/debian
 `--distribution(multimedia)=http://www.debian-multimedia.org

The model needs to declare that "distribution" is:

• a type "hash" parameter
• the hash key is a string
• the values of the hash are of type "leaf" and value_type "uniline"

 distribution => {
                   type => 'hash',
                   index_type => 'string',
                   cargo => {
                              type => 'leaf',
                              value_type => 'uniline',
                            },
                   summary => 'remote repositories',
                   description => 'The other name/value pairs are ...',
                 }

For more details on list and hash elements, see hash or list model declaration man page.

node element¶

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:

 Screen(Screen0)
   `--Option
      |--AllowGLXWithComposite=True
      `--DynamicTwinView=True

For this, a new dedicated class is necessary>Xorg::Screen::Option> (see its declaration above). This new class must be tied to the Screen class with a node element.

A node element has the following parameters:

• type (set to "node")
• the name of the configuration class name (>config_class_name>)

So the "Option" node element is declared with:

 Option => {
             type => 'node',
             config_class_name => 'Xorg::Screen::Option'
           },

Hash or list of nodes¶

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:

 Section "Device"
   Identifier     "Device0"
   Driver         "nvidia"
   BusID          "PCI:3:0:1"
 EndSection
 
 Section "Screen"
   Identifier     "Screen0"
   Device         "Device0"
   DefaultDepth    24
 EndSection

The Xorg configuration tree features 2 elements (Screen and Device) that use the Identifier parameters as hash keys:

 root
 |--Device(Device0)
 |  |--Driver=nvidia
 |  `--BusId=PCI:3:0:1
 `--Screen(Screen0)
    |--Device=Device0
    `--DefaultDepth=24

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

 {
 name => 'Xorg',
 element => [
             Device => {
                        type => 'hash',
                        index_type => 'string'
                        cargo => {
                                   type => 'node',
                                   config_class_name => 'Xorg::Device'
                                 },
                       },
             Screen => {
                        type => 'hash',
                        index_type => 'string'
                        cargo => {
                                  type => 'node',
                                  config_class_name => 'Xorg::Screen'
                                 },
                       },
          ]
 }

Using built-in read mechanism¶

"Config::Model" comes with 3 read/write built in mechanisms:

perl_file

A perl data structure (like the ones produced by Data::Dumper). See Config::Model::DumpAsData for details.

ini_file

Windows INI file (note that only simple tree structure can use this backend)

cds_file

Config::Model own serialization format (a bit like YAML). See Config::Model::Dumper for details.

With the backend name, the following parameters must be defined:

config_dir

The configuration directory

file

Config file name (optional). defaults to "<config_class_name>.[pl|ini|cds]"

   read_config  => [ { backend    => 'cds_file' , 
                       config_dir => '/etc/cfg_dir',
                       file       => 'cfg_file.cds', # optional
                   } ],

See "Built-in_backend" in Config::Model::BackendMgr.pm for details

Note that these parameters can also be set with the graphical configuration model editor.

Using a plugin read mechanism¶

A plugin backend class can also be specified with:

  read_config  => [ { backend    => 'foo' , 
                      config_dir => '/etc/cfg_dir'
                  } ]

In this case, Config::Model tries to load "Config::Model::Backend::Foo". (The class name is constructed with "ucfirst($backend_name)")

"read_config" can also have custom parameters that are passed verbatim to "Config::Model::Backend::Foo" methods:

  read_config  => [ { backend    => 'foo' , 
                      config_dir => '/etc/cfg_dir',
                      my_param   => 'my_value',
                  } ]

This "Config::Model::Backend::Foo" class is expected to provide the following methods:

new

read

write

Their signatures are explained in Config::Model::BackendMgr doc on plugin backends

Using a custom class¶

In case the plugin mechanism is not possible, a class with an arbitrary name can be specified:

    read_config  => [ { backend => 'custom' , 
                        class => 'MyRead',
                        config_dir => '/etc/foo', # optional
                        file => 'foo.conf',       # optional
                    } ]

Even the read method can have an arbitrary name by specifying a "function" parameters.

For more details on available parameters on custom backends, see Config::Model::BackendMgr doc on custom backends

Using several read mechanisms¶

Several read mechanism can be specified to enable:

• Migration from one syntax to another
• Usage of different libraries (e.g. Augeas <http://augeas.net> or pure Perl backend)

For instance, to try Augeas and fall back on a custom class in case of problem, specify:

  read_config => [ {
                     save => 'backup',
                     file => 'sshd_config',
                     backend => 'augeas',
                     config_dir => '/etc/ssh'
                   },
                   {
                     function => 'sshd_read',
                     backend => 'custom',
                     class => 'Config::Model::OpenSsh',
                     config_dir => '/etc/ssh'
                 } ],

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

An exception is 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 should also specify the "auto_create" parameter:

 read_config => [ { backend => 'custom' , 
                    class => 'ProcessRead' ,
                    config_dir => '/etc/foo',
                    file  => 'foo.conf',
                    auto_create => 1,
                } ],