Config::Model::Manual::ModelCreationIntroduction - Introduction to model creation with Config::Model
version 2.054
This page describes how to write a simple configuration model. Creation of more complex models are described in Creating a model with advanced features.
A tutorial is available in Creating a model from config file documentation.
Note that this document will show 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))
{ ... }
hash
Square brackets [ ... ] contain a list of items (array or list in Perl land)
[ ... ]
array
list
Text file where configuration data are stored. This configuration file will be used by an application -- the target application
The semantic content of the configuration file stored in a tree representation
Structure and constraints of the configuration tree. Like a schema for the configuration tree
The application that will use the configuration file
User of the target application
Target application developer
People developing the configuration model. Not necessarily the application developer
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).
Xorg
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.
approx.conf
adduser.conf
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.
apache2.conf
xorg.conf
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:
Identifiers
root |--Device(Device0) | `--Driver=nvidia `--Screen(Screen0) |--Device=Device0 |--Option | |--AllowGLXWithComposite=True | `--DynamicTwinView=True `--Display `--Depth=24
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.
Device
Monitor
Screen
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.
Xorg.conf
Device Driver
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).
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 will contain (see approx.conf man page):
Approx
A boolean leaf for pdiff (1 if not specified)
pdiff
An integer leaf for max_wait (10 seconds unless specified otherwise)
max_wait
A hash of string leaves for distrib (no default).
distrib
In terms of models, the model will be 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 will lead 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::Option
Xorg::Screen::Display for theDisplay subsection
Xorg::Screen::Display
Display
The root class will be 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' }, }, ] }
TheXorg::Screen class will be:
{ 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.
To define the configuration classes that will be required, you will have to 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 will also have to find several valid examples. These examples be used as non-regression tests and verify that the documentation was understood.
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
./lib/Config/Model/models/Xorg.pl
./lib/Config/Model/models/Xorg/Screen.pl
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.
Config::Model::Itself
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' } ] } ];
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
config-model-edit -model Xorg
This first set of attributes will help the user by providing guidance (with level and status and experience) and documentation (summary and description).
level
status
experience
summary
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.
important
normal
hidden
status: is obsolete, deprecated or standard (default). Using a deprecated element will issue a warning. Using an obsolete element will raise an exception.
obsolete
deprecated
standard
experience: By using the experience parameter, you can change the experience level of each element. Possible experience levels are master, advanced and beginner (default).
master
advanced
beginner
See "Configuration_class" in Config::Model for details.
Simple leaf elements will be used most often for configuration files. A leaf element will represent a specific configuration parameter.
In more details, a leaf element have the following attributes (See "Value_model_declaration" in Config::Model::Value doc):
Set to leaf (mandatory)
leaf
Either boolean, integer, number, enum, string, uniline (i.e. a string without "\n") (mandatory)
boolean
integer
number
enum
string
uniline
Minimum value (for integer or number)
Maximum value (for integer or number)
Possible values for an enum
Whether the value is mandatory or not
Default value that must be written in the configuration file
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".
AddressFamily
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.
any
sshd_config
Thus the model of this element will be :
AddressFamily => { type => 'leaf', value_type => 'enum', upstream_default => 'any', description => 'Specifies which address family should be used by sshd(8).', choice => [ 'any', 'inet', 'inet6' ] }
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 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.
distribution
The example will be stored this way in the configuration tree:
root |--distrib(debian)=http://ftp.fr.debian.org/debian `--distrib(multimedia)=http://www.debian-multimedia.org
The model will need to declare that distrib 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.
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)
node
the name of the configuration class name (>config_class_name>)
So the Option node element is declared with:
Option
Option => { type => 'node', config_class_name => 'Xorg::Screen::Option' },
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:
Identifier
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 will feature 2 elements (Screen and Device) that will 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 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). The exploration will also respect the experience parameter. I.e. a wizard run with master experience (see Option->Experience menu in the Perl/Tk interface) will show more parameters than running the interface with beginner experience.
When designing a model, you will have to think about each element:
The expertise required to tinker with this parameter and set experience to the right level, either master, advanced or beginner (default).
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.
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 the file (the read backend).
The read method can use one or more of the following mechanisms:
Built-in, e.g Perl file, INI file...
A plugin, i.e. a Perl Config::Model::Backend::* class like Config::Model::Backend::Augeas
Config::Model::Backend::*
Config::Model::Backend::Augeas
A custom class where a read call-back must be provided
For more details, see Config::Model::BackendMgr.
The name of the backend parameter must be specified in all cases.
Config::Model comes with 3 read/write built in mechanisms:
Config::Model
A perl data structure (like the ones produced by Data::Dumper). See Config::Model::DumpAsData for details.
Windows INI file (note that only simple tree structure can use this backend)
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:
The configuration directory
Config file name (optional). defaults to <config_class_name>.[pl|ini|cds]
<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.
A plugin backend class can also be specified with:
read_config => [ { backend => 'foo' , config_dir => '/etc/cfg_dir' } ]
In this case, Config::Model will try to load Config::Model::Backend::Foo. (The class name is constructed with ucfirst($backend_name))
Config::Model::Backend::Foo
ucfirst($backend_name)
read_config can also have custom parameters that will passed verbatim to Config::Model::Backend::Foo methods:
read_config
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:
Their signatures are explained in Config::Model::BackendMgr doc on plugin backends
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.
function
For more details on available parameters on custom backends, see Config::Model::BackendMgr doc on custom backends
Several read mechanism can be specified to enable:
Migration from one syntax to another
Usage of different libraries (e.g. Augeas 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 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:
OpenSsh
auto_create
read_config => [ { backend => 'custom' , class => 'ProcessRead' , config_dir => '/etc/foo', file => 'foo.conf', auto_create => 1, } ],
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.
read
write
Here's an example:
write_config => [ { backend => 'custom', class => 'NewFormat' function => 'my_write', } ],
Several write specification can be used. They are tried in order, until the first succeeds.
For more information, see write specification doc
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:
'one
{ name => 'Example', element => [ ... ] , read_config => [ { backend => 'perl_file', config_dir => '/etc/my_cfg/' } , { backend => 'custom', class => 'Bar' }, ], write_config => [ { backend => 'perl_file', config_dir => '/etc/my_cfg/' } ], }
How does this work ? Here's the sequence:
Configuration is stored in old file /etc/my_cfg/bar.conf
/etc/my_cfg/bar.conf
Config::Model tries to read the config with perl_file read backend and looks for /etc/my_cfg/example.pl. This file is not found so the read fails.
perl_file
/etc/my_cfg/example.pl
Config::Model tries the second backend which succeeds and load configuration data in the configuration tree
Config::Model writes data back from configuration tree using write_config backend which writes /etc/my_cfg/example.pl
write_config
At the next invocation, the first read backend will successfully read the perl configuration file. The old file is left alone and can be removed later by the system admin.
Thanks to this mechanism, this operation is idempotent so it can safely be scripted in package scriplets.
More complex models: Config::Model::Manual::ModelCreationAdvanced
Config::Model::Manual::ModelForUpgrade: Writing a model for configuration upgrades
Configuration upgrades within Debian packages
Feel free to send comments and suggestion about this page at
config-model-users at lists dot sourceforge dot net.
Dominique Dumont <ddumont at cpan.org>
Dominique Dumont
This software is Copyright (c) 2014 by Dominique Dumont.
This is free software, licensed under:
The GNU Lesser General Public License, Version 2.1, February 1999
To install Config::Model, copy and paste the appropriate command in to your terminal.
cpanm
cpanm Config::Model
CPAN shell
perl -MCPAN -e shell install Config::Model
For more information on module installation, please visit the detailed CPAN module installation guide.