NAME¶

Config::Model::Manual::ModelCreationIntroduction - Introduction to model creation with Config::Model

VERSION¶

version 2.152

Introduction¶

This page describes how to write a simple configuration model. Creation of more complex models are described in Creating a model with advanced features.

Note that this document shows a lot of Perl data structure to highlight the content of a model. A Perl data structure is very similar to a JSON structure. The only thing you need to know are:

• Curly braces "{ ... }" contain a dictionary of key, value pairs (a "hash" in Perl land))
• Square brackets "[ ... ]" contain a list of items ("array" or "list" in Perl land)

Some definitions¶

configuration file

Text file where configuration data are stored. This configuration file is used by an application -- the target application

configuration tree

The semantic content of the configuration file stored in a tree representation

configuration model

Structure and constraints of the configuration tree. Like a schema for the configuration tree

target application

The application that uses the configuration file. The application can be of type "system" (i.e. the configuration file is located in "/etc"), "user" (i.e. the configuration file is located in a user directory like "~/.config") or "application" (the configuration file is in or below the current directory)

end user

User of the target application

application developer

Target application developer

model developer

People developing the configuration model. Not necessarily the application developer

What is a configuration tree?¶

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.

For instance, this "approx.conf":

 $pdiffs     1
 $max_wait   14
 debian     http://ftp.fr.debian.org/debian

can have this tree representation:

 root
 |--pdiff=1
 |--max_wait=14
 `--distrib(debian)=http://ftp.fr.debian.org/debian

Other configuration files like "apache2.conf" or "xorg.conf" have a structure that look more like a tree.

For instance, consider this "xorg.conf" snippet:

 Section "Device"
    Identifier     "Device0"
    Driver         "nvidia"
 EndSection
 
 Section "Screen"
    Identifier     "Screen0"
    Device         "Device0"
    Option         "AllowGLXWithComposite" "True"
    Option         "DynamicTwinView" "True"
    SubSection     "Display"
        Depth       24
    EndSubSection
 EndSection

Knowing that Xorg.conf can have several Device or Screen sections identified by their "Identifiers", the configuration can be represented in this tree as:

 root
 |--Device(Device0)
 |  `--Driver=nvidia
 `--Screen(Screen0)
    |--Device=Device0
    |--Option
    |  |--AllowGLXWithComposite=True
    |  `--DynamicTwinView=True
    `--Display
       `--Depth=24

One may 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).

What is a model?¶

A configuration model defines the configuration tree structure:

• A model defines one or more configuration class
• At least one class is required to define the configuration tree root
• Each class contains several elements. An element can be:

These basic relations enable to define the main parts of a configuration tree.

If we refer to the "approx.conf" example mentioned above, one only class is required (let's say the "Approx" class). This class must contain (see approx.conf man page):

• A boolean leaf for "pdiff" (1 if not specified)
• An integer leaf for "max_wait" (10 seconds unless specified otherwise)
• A hash of string leaves for "distrib" (no default).

A configuration model is stored this way by Config::Model:

 {
  name => 'Approx',
  element => [
      pdiffs => {
          type => 'leaf',
          value_type => 'boolean',
          upstream_default => '1'
      },
      max_wait => {
          type => 'leaf',
          value_type => 'integer',
          upstream_default => '10'
      },
      distributions'=> {
          type => 'hash',
          index_type => 'string' ,
          cargo => {
              value_type => 'uniline',
              type => 'leaf',
          },
      }
   ]
 }

The "Xorg" example leads to a slightly more complex model with several classes:

• "Xorg" (root class)
• "Xorg::Device"
• "Xorg::Screen"
• "Xorg::Screen::Option" for the Screen options
• "Xorg::Screen::Display" for the"Display" subsection

The root class is declared this way:

 {
  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'
                                  },
                        },
           ]
 }

The"Xorg::Screen" class is:

 {
  name => 'Xorg::Screen',
  element => [
               Device => {
                           type' => 'leaf',
                           value_type => 'uniline',
                         },
               Display => {
                            type => 'hash',
                            index_type => 'integer'
                            cargo => {
                                       type => 'node',
                                       config_class_name => 'Xorg::Screen::Display'
                                     },
                          }
              Option => {
                          type => 'node',
                          config_class_name => 'Xorg::Screen::Option'
                        },
              ]
  }

It's now time to detail how the elements of a class are constructed.

Model analysis¶

To define the required configuration classes, you should read the documentation of the target application to :

• Find the structure of the configuration tree
• Identify configuration parameters, their constraints and relations

Last but not least, you should also find several valid examples of your application configuration. These examples can be used as non-regression tests and to verify that the application documentation was understood.

Model declaration¶

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

 $ 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'
                         }
                ]
   }
 ];

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

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

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

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

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

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

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

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

 {
 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'
                                 },
                       },
          ]
 }

Configuration wizard¶

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 have to ponder for 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 are shown in the wizard. hidden elements are explained with the warp notion in Creating a model with advanced features.

Reading configuration files¶

Once the model is specified, Config::Model can generate a nice user interface, but there's still no way to load or write the configuration file.

For Config::Model to read the file, the model designer must declare in the model how to read and write the file (the read/write backend).

The read/write functionality is provided by a class inheriting "Config::Model::Backend::Any" class like "Config::Model::Backend::IniFile"

The name of the backend parameter must match the backend class name without "Config::Model::Backend". As syntactic sugar, lower case backend name are transformed into upper case to match the backend class name.

E.g.

 Yaml -> Config::Model::Backend::Yaml
 plain_file -> Config::Model::Backend::PlainFile
 ini_file -> Config::Model::Backend::IniFile

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]"

   rw_config  => { backend    => 'ini_file' ,
                   config_dir => '/etc/cfg_dir',
                   file       => 'cfg_file.ini',
                 },

See Config::Model::Backend::IniFile for details

Note that these parameters can also be set with the graphical configuration model editor ("cme meta edit").

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

  rw_config  => {
     backend    => 'my_backend',
     config_dir => '/etc/cfg_dir',
     my_param   => 'my_value',
  }

This "Config::Model::Backend::MyBackend" class is expected to inherit Config::Model::Backend::Any and provide the following methods:

new

read

write

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

SEE ALSO¶

• More complex models: Config::Model::Manual::ModelCreationAdvanced
• Config::Model::Manual::ModelForUpgrade: Writing a model for configuration upgrades
• Configuration upgrades within Debian packages <http://wiki.debian.org/PackageConfigUpgrade>

Feedback welcome¶

Feel free to send comments and suggestion about this page at

 config-model-users at lists dot sourceforge dot net.

AUTHORS¶

Dominique Dumont <ddumont at cpan.org>

AUTHOR¶

Dominique Dumont

COPYRIGHT AND LICENSE¶

This software is Copyright (c) 2005-2022 by Dominique Dumont.

This is free software, licensed under:

  The GNU Lesser General Public License, Version 2.1, February 1999