Provided by: libconfig-model-perl_2.153-3_all bug

NAME

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

VERSION

       version 2.153

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:

           •   A leaf to represent one configuration parameter

           •   A list of hash of leaves to represent several parameter

           •   A node to hold a node of a configuration tree

           •   A list or hash of nodes

       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

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

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

perl v5.36.0                                       2023-08-Config::Model::Manual::ModelCreationIntroduction(3pm)