Config...uction(3pm)

✨ Config::Model::Manual::ModelCreationIntroduction ✨

okay bestie, welcome to the User Contributed Perl Documentation section — this is literally the introduction to making models with Config::Model 💖

🌸 VERSION 🌸

version 2.166 — periodt.

---

🦋 Introduction 🦋

So this page is all about how you write a simple configuration model. The glow-up to bigger, more extra models lives in Creating a model with advanced features, iykyk.

Heads up bestie: this doc throws a LOT of Perl data structures at you so you can actually see what's inside a model. A Perl data structure is basically a JSON structure, no cap. The only two things you gotta know:

• Curly braces { ... } hold a dictionary of key/value pairs (that's a "hash" in Perl land 💅)
• Square brackets [ ... ] hold a list of items (that's an "array" or "list" in Perl land)

---

💜 Some definitions 💜

• configuration file — a text file where configuration data lives. The target application is the one using it.
• configuration tree — the semantic content of that configuration file, stored as a tree.
• configuration model — the structure and constraints of the configuration tree. Basically a schema for it, fr fr.
• target application — the app that uses the configuration file. It can be type system (config file lives in /etc), type user (config file lives in a user directory like ~/.config), or type application (config file is in or below the current directory).
• end user — the user of the target application.
• application developer — the developer of the target application.
• model developer — the people building the configuration model. Not necessarily the application developer, okay?

---

🎀 What is a configuration tree? 🎀

Most configuration files are actually organized mostly as a tree structure. Depending on the file's syntax this can be super obvious to see (like for XML, Apache) or not so obvious at all (Xorg syntax, INI syntax — looking at you 🙈).

For some files like approx.conf or adduser.conf, that tree structure is quite flat. It looks much more like a rake than a tree, but bestie, it's still 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 looks way more tree-shaped 🌳

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. And honestly? That's right — there are some more complex relations that get added on top of the tree structure. That whole situation gets covered in more detail when we deal 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 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). Iconic behavior, honestly. 👑

---

⭐ 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 you 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. Get comfy bestie, we're going deeper 💅

---

🧚 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 💖

ok so now we get to the actual model writing, bestie. buckle up. 🎀

✨ Configuration class declaration ✨

lowkey writing that data structure by hand is not fun — even in Perl, and you know Perl girlies love typing. so the recommendation is: use the model editor that cme gives you, via the cme meta edit command (which comes from Config::Model::Itself). it hands you a whole GUI to create or update your model. 💅

and when you save? cme writes the data structure into the correct directory for you. no cap. 🫶

🌸 Configuration class declaration (the hard way) 🌸

for the girlies doing it manually, here's the summary — configuration documentation gets translated into a format Config::Model can actually eat:

• the structure gets translated into configuration classes
• the configuration parameters get translated into elements
• the constraints get translated into element attributes

every model file has to live in a specific directory. for the model Xorg, you literally have to create ./lib/Config/Model/models/Xorg.pl. other classes like Xorg::Screen can go in their own file, ./lib/Config/Model/models/Xorg/Screen.pl, or you can just include them inside Xorg.pl. either way, iconic. ✨

a model file is a Perl file containing an array of hash refs. each hash ref holds one class declaration:

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

a class can have these 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 one is currently reserved for the Config::Model::Itself model editor.
• include — Include element description from another class.

for the full deets, see "Configuration_Model" in Config::Model.

for instance, bestie:

$ 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 batch of attributes is here to help the user by giving guidance (with level and status) and documentation (summary and description). it's giving considerate. 💖

every element — simple or complex, no exceptions — can have these attributes:

• description — full length description of the attribute
• summary — one line summary of the above description
• level — is important, normal or hidden. the level sets 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 you use a deprecated element, and an exception is raised when an obsolete element is used.

see "Configuration_class" in Config::Model for the details.

🍓 Leaf elements 🍓

the leaf element is the most common type for representing configuration data. like, the main character of element types, fr fr. 🌟 a leaf element represents one specific configuration parameter.

in more detail, a leaf element has these attributes (see the "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. yeah. homework. sorry bestie. 😭

for instance, the 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 the 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 actually a list or a hash of parameters. plot twist. 🙈 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 needs something that is not explicit in the approx.conf file: a parameter name. the 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 the 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 that case the tree is deeper than a rake, and a node element is 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. yes, a wizard. like, actual magic, but make it config. ✨

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.

bestie. don't skip the ponder step. the wizard will absolutely expose you if you do. 💀

💾 Reading configuration files

Okay bestie, so your model is declared, the wizard is cute, the UI pops off… but there's still a tiny problem: nothing can actually read or write the config file yet. 🙈 The model alone doesn't know how to touch disk.

So for Config::Model to read that file, the model designer has to declare in the model how the file gets read and written — that's what we call the read/write backend. 🎀

That read/write magic comes from a class that inherits from Config::Model::Backend::Any, like Config::Model::Backend::IniFile does. 💅

And here's the little naming salad rule that matters: the name you give the backend parameter must match the backend class name without Config::Model::Backend. And as a bit of syntactic sugar, lowercase backend names get transformed into upper case so they line up with the backend class name. ✨

E.g.:

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

Along with the backend name, these parameters must be defined:

• config_dir — the configuration directory 📁
• file — the config file name, and it's 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 all the deets. 📖

Also, lowkey convenient: these parameters can be set with the graphical configuration model editor too — that's cme meta edit. 👑

rw_config can also carry custom parameters, which get passed verbatim to the Config::Model::Backend::Foo methods. No cap, verbatim as in character-for-character:

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

That Config::Model::Backend::MyBackend class is expected to inherit from Config::Model::Backend::Any and provide these methods:

• new
• read
• write

Their signatures are explained in the Config::Model::BackendMgr doc, under 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

Fr fr, slide into the inbox — feel free to send comments and suggestions 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

---

And that's a wrap on the whole manual, bestie — this page ships with perl v5.42.3 and was last dated 2026-07-23. Go build something iconic with it. 💖✨🦋